Update Specs

Update the Product Specs

Reconcile the spec set under docs/specs/ with everything merged to origin/main since the specs were last refreshed. The job has two halves: (1) review the new commits, decide what changed about the product, and edit the docs to match (Steps 2–6), and (2) confirm every claim already in the docs is still true of the current code (Step 7) — because a standing claim can rot from a change the commit review correctly skips as noise (a deletion, a rename, a moved default). Do not invent behavior, and do not document implementation detail the product docs deliberately omit.

The doc set

docs/specs/ holds four long-lived, related documents. Read docs/specs/README.md first — it is the authority on how they relate. In brief:

Discover the docs dynamically (ls docs/specs/*.md) rather than hard-coding the list, so the skill still works if a doc is added or renamed. Apply the per-doc guidance above by matching the doc's role, not its exact filename.

Step 1: Determine the baseline commit

The baseline is the commit the specs were last reconciled against. Everything after it is unreviewed.

1. If the user passed a commit as $ARGUMENTS, use that.
2. Else read docs/specs/.spec-baseline — a file holding the baseline SHA on its first line. Use that SHA.

head -1 docs/specs/.spec-baseline

If the file is missing, stop and tell the user — the baseline must be seeded first (write the last reconciliation commit's SHA to docs/specs/.spec-baseline). Don't guess a baseline.

Then fetch and confirm where the baseline sits relative to the current tip:

git fetch origin --quiet
git rev-parse origin/main
git merge-base --is-ancestor <baseline> origin/main && echo "baseline on main" || echo "WARN: baseline not on main"
git rev-list --count <baseline>..origin/main

If the baseline is not an ancestor of origin/main, stop and ask the user how to proceed (it may be on a feature branch or have been rebased away). Reconcile against origin/main, not the local HEAD, unless the user says otherwise.

Step 2: Enumerate the merged PRs since the baseline

This repo merges with no-fast-forward, so every PR is one merge commit on the first-parent spine. Use the merge commits as the source of truth for what landed, and the non-merge subjects for detail.

# Source of truth — one line per merged PR:
git log <baseline>..origin/main --merges --first-parent --format='%h %s'
# Detail — individual commit subjects, for understanding each PR:
git log <baseline>..origin/main --no-merges --format='%s'

If the lists are large, write them to the scratchpad and read them with the Read tool rather than scrolling shell output.

Step 3: Separate product changes from noise

Most commits do not change the product and must not trigger spec edits — but classify from the diff, not the subject. A subject and branch name describe intent ("cleanup", "flake fix", "build"); the spec cares about effect, and the two diverge exactly where it matters: a "cleanup" PR that removes a documented feature, a "flake fix" that changes behavior. So before you can call a PR noise, look at what files it touched — this is cheap:

# File list per PR — the real classification signal. Read this, not just the subject.
git show --stat <merge-sha>
# Or stat the whole range at once, one block per PR:
git log <baseline>..origin/main --first-parent --stat --format='### %h %s'

Three hard escalation triggers. A PR hitting any of these gets its diff read no matter how its subject reads — it cannot be dismissed as noise on the subject alone:

• Deletions & renames. Any PR that deletes or renames a file (git log <baseline>..origin/main --diff-filter=D,R --name-status). A removal is the change most likely to be both filed as noise and to invalidate a standing doc claim — grep the docs for the removed path/symbol before letting it pass. (This is the class that kept a deleted helper script in the docs for multiple runs.)
• Product-surface paths. The diff touches frontend/src/pages/** or frontend/src/components/**, a web route handler, config/user_config.py (settings/defaults), a */registry.py, a sculpt CLI command file, a keybindings map, or onboarding / add-repo / dependency-card code — regardless of subject.
• Non-test source under a test/flake subject. A "flake fix" or "test" PR whose diff includes non-test product files is a behavior change wearing a test-fix label. Read the non-test files.

Genuine noise — skip only when the diff confirms it, never on the subject:

• Comment scrubs and rewording.
• Dependency upgrades (Electron/Node/Python/React/Vite/etc.) and lockfile refreshes.
• CI / build / release plumbing (release gating, telemetry-key injection, apt-get hardening, CI concurrency, pyre-cache ignore).
• Test-only changes — the diff touches nothing but tests / test infra (*_test.py, test_*.py, *.test.ts(x), fixtures). (Exception: a test-only PR can still move a scenario_coverage.md status — see Step 6.)
• Style-guide / review-rule / internal-doc edits, version bumps, frozen-schema regeneration.

For everything not cleanly noise, apply the inclusion test from the spec's scope discipline:

Would a user see, name, or configure this? If yes, it likely belongs in the product docs.

New capabilities, new settings, new panels/screens, changed defaults, changed keybindings, new CLI flags, changed error/reliability behavior a user would notice, and removed features all qualify.

Keep implementation detail OUT of the product docs. Internal services, the task/Environment substrate, WebSocket/HTTP transport, Alembic/DB migrations, schema regen, and similar plumbing are impl-only — they belong (if anywhere) in requirements.md as a contract, never as product narrative.

The signal-to-noise ratio is typically ~10:1 (≈15 product features out of ≈80 PRs). Treat that as an observation to sanity-check against, not a quota to prune toward — classify each PR by its effect and let the count land where it lands. A list far larger than that means impl detail is probably leaking in; far smaller means you're likely trusting subjects over diffs. When a call is genuinely uncertain, bias toward reading the diff, not toward skipping.

Step 4: Understand each product change

Branch names embed ticket IDs (scu-NNNN) and squashed subjects are descriptive, but do not write spec text from the subject line alone — it describes the fix, not the resulting behavior. Step 3 already gave you each PR's file list; now read the real change for everything you kept (and for any escalation-trigger PR you're still unsure about):

git log <merge-sha>^1..<merge-sha>^2 --format='%s'   # the PR's own commits
git diff <merge-sha>^1..<merge-sha> -- <relevant paths>   # the real change → the resulting behavior

Group related PRs into one feature before editing (e.g. a dozen plugin-system PRs are one new product surface, not a dozen edits). Decide, per feature, the current user-visible behavior — what the product does now, on main — because that is what the spec must describe.

Step 5: Plan the edits

For each feature, decide which docs are affected and what each edit is. This is mostly a straight translation from "what the commits changed" to "what the product now does" — don't check in with the user for routine edits. Make the changes and let the user review the diff at the end (Step 9).

Only pause to ask the user when there is genuine ambiguity you cannot resolve from the code and docs — e.g. a default changed but you can't tell which value is now authoritative, or it's unclear whether a feature is shipped vs. gated behind an experimental flag and the code doesn't say. Resolve everything you can on your own first (read the code, read the surrounding doc); ask only about what's truly left over, and batch those questions rather than interrupting per-feature.

Step 6: Apply the edits

Edit each doc in place, matching its established format, tone, and structure. Read enough surrounding context in each doc to slot the change in where it belongs, not at the end.

Describe what the code does today — never what it used to do. These are living descriptions of the current product, not a changelog. Don't leave a trace of the change: no "now …", "no longer …", "previously …", "used to …", "formerly …", "renamed from …", "instead of …", or any before/after phrasing. The commit history already records what changed; the doc records what is. When you revise a section, rewrite it so a reader with no knowledge of the old behavior gets an accurate, self-contained description — then delete any wording that only makes sense relative to the past.

• SPEC.md — prose behavior. Add to or revise the relevant feature section; remove text for removed features. Keep the descriptive, present-tense product voice. Experimental/off-by-default features go in the experimental section, marked as such.
• requirements.md — only when the change sets or moves a measurable target, version/platform bar, persistence/migration guarantee, integration contract, or resolves an open question. Don't restate prose here; record the fact.
• scenarios.md — Given/When/Then with a stable AREA-NNN ID. Preserve the ID scheme: reuse the right area prefix (see its "Areas / ID prefixes" table), and assign the next free number in that area — never renumber existing scenarios. Every Then must be visible on screen. Delete scenarios for removed behavior; revise in place for changed behavior.
• scenario_coverage.md — for every scenario you added/changed/removed, add/update/remove its coverage row, set status (Complete / Partial / Missing) by checking whether an integration test actually drives the action and asserts the visible outcome, and update the per-area counts in the executive summary table so the totals stay consistent. A test-only PR that newly covers an existing scenario can move a status here even though no other doc changes.

Public-visibility rule: these docs are world-readable. Scrub PII, internal hostnames/service names, customer data, and security-sensitive detail, per CLAUDE.md's "Public Visibility" section.