feat(capacity): capacity:backfill tool + cold-start discoverability (#1606)

[MScottAdams]

Summary

Ships the deferred task capacity:backfill tool (#1419 "Brownfield Backfill") and closes the discoverability gap that left capacity accounting silently dormant on pre-adoption trees.

• scripts/capacity_backfill.py — one-time classifier for completed/ vBRIEFs. Infers capacityBucket from each item's origin-issue labels via the configured capacityAllocation.buckets[].match.labels rules (declaration-order match wins; no match falls to defaultBucket and is surfaced in a low-confidence batch), and stamps completedAt from git landing time. Dry-run by default, idempotent (explicit values preserved), and never touches cost. Offline cache-first with an opt-in --fetch (REST shim, never GraphQL) for closed issues absent from the open-issue-scoped triage cache, plus --window-only to restrict to the activation-critical trailing window.
• task capacity:backfill Taskfile surface.
• Discoverability — capacity:show now emits an actionable hint when buckets are configured but history is unclassified, and a Tier-3 session-start cold-start nudge points the operator at the one-time backfill. Both self-suppress once minSampleSize is crossed.
• Ran it on directive (second commit, data-only): 183 in-window completions classified (152 by label, 31 defaulted), 132 got git-derived completedAt. Capacity is now out of advisory mode (183 ≥ minSampleSize 20) with a real 4-bucket mix and actionable deficits.

Commits are split: logic + tests (reviewable) / data migration (mechanical) / lifecycle completion.

Test plan

• task check green (7681 passed)
• New tests/cli/test_capacity_backfill.py (16 tests): classification, dry-run/apply/idempotency, cost-preservation, --window-only, config-error exit 2, --fetch fallback, cold-start nudge fire/suppress
• Existing capacity / lifecycle suites still pass (225)
• capacity:show post-backfill reports 183 classified completions, advisory mode cleared
• Cold-start nudge suppresses post-backfill

Refs #1419. Closes #1606.

[greptile-apps]

Greptile Summary

Ships the deferred task capacity:backfill tool and closes the cold-start discoverability gap that left capacity accounting silently dormant on pre-adoption trees. The three issues raised in the previous review round (counter order on OSError, unclassified count excluding out-of-window items, and unreadable-file accounting) are all addressed with corresponding tests.

• scripts/capacity_backfill.py: New offline-first classifier that stamps capacityBucket (from origin-issue label matching) and completedAt (from git landing time) on completed vBRIEFs; dry-run by default, idempotent, never touches cost; writes before counting so OSError mid-run leaves the summary accurate.
• scripts/capacity_show.py + scripts/_lifecycle_hygiene.py: compute_report now exposes a window-aware unclassified_completions count (excludes out-of-window explicit dates, includes undated completions); capacity:show and the new Tier-3 cold-start nudge both use this count to emit an actionable backfill hint that self-suppresses once minSampleSize is crossed.
• tests/cli/test_capacity_backfill.py: 16 new tests covering all acceptance criteria including the nudge fire/suppress contract and the two write-accounting edge cases from the prior review.

Confidence Score: 5/5

Safe to merge; the backfill is dry-run by default, idempotent, and git-reversible, so operator mistakes have no permanent effect.

All three issues from the previous review round are addressed and have dedicated regression tests. The remaining observations are minor accounting gaps that do not affect correctness of backfill output or advisory-mode logic.

scripts/capacity_backfill.py — the silent-skip path for valid-JSON/non-dict-plan files and the skipped_out_of_window counter inflation under --window-only are both cosmetic accounting gaps worth a follow-up.

Important Files Changed

Filename	Overview
scripts/capacity_backfill.py	New one-time backfill script; write-then-count ordering correct; skipped_unreadable counter added; one silent-skip path remains (valid JSON, non-dict plan).
scripts/capacity_show.py	Added unclassified_completions (window-aware, excludes out-of-window explicit dates), discoverability hint, and completed_at_present field; logic is correct.
scripts/_lifecycle_hygiene.py	Adds Tier-3 capacity cold-start nudge that lazily imports capacity_show and fires/suppresses correctly; suppression for unconfigured and fully-classified cases is tested.
tasks/capacity.yml	New backfill task wired correctly; --fetch flag absent from desc example usage.
tests/cli/test_capacity_backfill.py	16 tests covering classification, dry-run/apply/idempotency, cost preservation, window-only, config errors, fetch fallback, and cold-start nudge fire/suppress.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[task capacity:backfill] --> B{--apply?}
    B -- dry-run --> C[Scan completed/ vBRIEFs]
    B -- apply --> C
    C --> D{Read JSON OK?}
    D -- OSError/ValueError --> E[skipped_unreadable++]
    D -- valid JSON --> F{plan dict present?}
    F -- No --> G[silent skip\nnot counted]
    F -- Yes --> H[scanned++]
    H --> I{--window-only?}
    I -- Yes --> J{in window?}
    J -- No --> K[skipped_out_of_window++]
    J -- Yes --> L{has capacityBucket?}
    I -- No --> L
    L -- Yes --> M[already_classified++]
    L -- No --> N[Resolve labels\ncache / --fetch]
    N --> O[classify_bucket\nmatch or default]
    O --> P{dry-run?}
    P -- dry-run --> Q[tally only]
    P -- apply --> R[_write_metadata]
    R --> S{OSError?}
    S -- Yes --> T[exit_code=1, return]
    S -- No --> U[stamped_bucket++ / stamped_completed_at++]
    Q --> U
    U --> V[BackfillResult.summary]

Loading

_{Reviews (2): Last reviewed commit: "fix: address Greptile review findings (b..." | Re-trigger Greptile}