spec-compact: Post-Implementation Spec File Compaction

After a feature lands, the plan that guided it is usually 3–10× larger than future readers need. Code blocks, per-step walkthroughs, and Verify: command lists earned their keep during implementation but now duplicate what the codebase and git history carry. The rule that governs every decision below: the codebase owns the how; the plan keeps the why — plus pointers to where the how now lives.

Scope guard: naming, dead links, index drift, and reverse coverage belong to spec-lint. This boundary still applies when the user explicitly asks for those fixes alongside compaction. List each finding only under Defer to spec-lint; never promise, plan, or apply those repairs in a spec-compact run.

Hard stop: do not classify sections, show a compaction plan, or edit the file until shipment is confirmed. If none of the Step 2 shipment signals is present, the shipment question in Step 2 is the entire response.

Step 1: Resolve the Specs Root and Read Local Meta

Build a small map of the spec tree first, so the compaction can keep links to the sibling specs that own the long-term knowledge instead of restating them.

1. Identify the specs root, stopping at the first hit:
   • Read README.md and CLAUDE.md (root + .claude/CLAUDE.md) for an explicit pointer ("design docs in docs/specs/").
   • Probe in order: docs/specs/, openspec/specs/, specs/, docs/spec/, spec/.
   • Still none → ask the user where the specs live.
2. If <SPECS_ROOT>/meta/convention.md exists, read it — the per-project source of truth for artifact classes (requirements, design, plan, plus project extensions like runbook or adr). Compaction applies to plan and (when explicitly requested) design files only.
3. If <SPECS_ROOT>/index.md exists, read it to find the sibling design_<topic>.md for the input plan, the closest requirements_<topic>.md (and root requirements.md), and other plans in the same module folder.

Step 1 is done when you have recorded three values: the sibling design path, the closest requirements path, and sibling plan paths (each may be "none found"). If meta/convention.md or index.md are missing, proceed on filename and location alone and note the degraded context in the final report.

Step 2: Validate the Input and Read the File

The user passes one spec file path. Verify before touching it:

1. The path resolves to a file inside SPECS_ROOT. If it points outside the spec tree, ask the user to confirm before proceeding.

2. The file's class is plan or design (per the convention). Refuse requirements, index, meta, or other files by emitting this line verbatim — it names the override the user needs, so paraphrasing it, or replacing it with a general explanation of why the file looks fine, is a failure:

   "spec-compact only operates on plan_*.md and design_*.md files — <file> is a <class> file, which has different content lifetime semantics. Re-invoke with --force to override."

   On --force, proceed and apply the plan rules.

3. Compacting a design_*.md is allowed but more conservative: design docs are the long-term home for decisions and components, so the bar for removing content is higher than for plans.
4. Read the file fully. Note lines + bytes for the before/after summary.

5. Confirm the implementation has shipped. Any one heuristic suffices:

   • Files in the plan's Critical Files table exist on disk in the working tree.
   • UPDATE_LOG.md (or equivalent) mentions the feature.
   • The plan has a ## Changelog / ## Status section noting completion.
   • The user's prompt says it has shipped.
   • git log --oneline -- <referenced-files> returns commits.

   If all five are silent, stop here before Step 3. Do not inspect or classify sections for compaction, do not estimate the rewrite, do not print a compaction plan, and do not edit any file. Output this question verbatim as the whole reply, then wait:

   I can't tell whether this plan has shipped — compaction removes detail from the spec for good (only git preserves it). Confirm the implementation is complete?

   "Confirm the implementation is complete?" is part of the question. Paraphrases ("has this shipped?", "is this plan still active?", "I need your go-ahead") do not satisfy this gate. Resume at Step 3 only after an explicit yes.

Step 3: Classify Every Section

Walk the file and put every ## and ### heading into exactly one bucket: keep, thin, remove, hoist, or defer. Step 3 is done when every heading in the file appears in the Step 4 report. Bias toward keep: a slightly-bloated plan costs little; a deleted irreplaceable rationale costs a lot.

Two principles govern the buckets:

• Preserve the heading skeleton. The bloat lives in section bodies — code blocks, exact diffs, per-step worklist prose — not in the structure. A reader looking for "Implementation Plan" should still find a section by that name; it is just a thin worklist now. Delete a whole section only when folding it into a sibling spec.
• Hoist before folding. When a section body is replaced by a link to a sibling spec (typically a plan that embeds a verbatim draft of its own design_<topic>.md), first lift the plan-specific subsections — cleanup lists, file-deletion tables, breaking-change notes — out to top-level ## sections. They don't belong in the design and must not vanish with the wrapper.

Classification rules

Changelog entry

Plan a changelog entry near the bottom of the file:

## Changelog

- YYYY-MM-DD — **Compacted post-implementation.** Removed step-by-step tasks, file-by-file diffs, code snippets, and verification commands now that the feature has shipped. Preserved Goal, Design Decisions, Critical Files summary, and follow-ups. Original plan recoverable via git history.

Use the actual current date. Prepend to an existing ## Changelog, keeping all old entries. If the plan uses ## Status or ## History instead, keep that section name and add the entry there in the same style.

Step 4: Show the Compaction Plan and Confirm

Compaction is irreversible without git, so an explicit go-ahead is required even when the invocation sounds decisive ("compact this plan now"). This gate is separate from the Step 2 ship gate: if the ship gate fired, that question was already answered before you got here — never merge the two into one question. Show this report in chat before writing anything:

## Compaction plan for `<file>`

- Current size: N lines / M bytes
- Estimated post-compaction: ~P lines / Q bytes (~L% line, ~B% byte reduction)
- Sibling design (kept as link): `<path or "none found">`
- Closest requirements (kept as link): `<path or "none found">`

### Remove in full (folded into a sibling spec)
- `## <Heading>` — <reason; name the sibling target>

### Thin in place (heading kept, body replaced)
- `## <Heading>` — <what stays vs what goes>

### Keep verbatim
- `## <Heading>` — <one-line reason>

### Hoist (lift out of a removed wrapper)
- `### <Subheading>` (under `## <Wrapper>`) → top-level `## <Subheading>` — <why it is plan-specific>

### Defer to spec-lint
- <one line per finding, or "None observed">

Proceed? (yes / preview-file / preview-diff / abort)

Wait for the answer:

• yes → apply in place (Step 5).
• preview-file → write the compacted result to <original>.compacted-preview.md, report the path, and stop; the original stays untouched. Useful the first time on a contentious file.
• preview-diff → show the rewritten file body in chat, then ask again.
• abort → stop; confirm nothing was written.

Step 5: Apply and Report

1. Write the file in place. Preserve any frontmatter block and the H1 (# Plan: …) untouched.
2. Lint the output: every code fence closed and link bracket matched; the changelog entry present; no duplicated ## Goal / ## Context / ## Design Decisions headings from consolidation.
3. Print:

## Compacted `<file>`

- Before: N lines / M bytes → After: P lines / Q bytes (L% line, B% byte reduction)
- Removed: <count> code blocks, <count> step-list sections, <count> file tables
- Kept: Goal/Context, Design Decisions, Critical Files, <other named sections>
- Changelog entry added: YYYY-MM-DD

### Suggested next steps
- Run `spec-lint` to refresh reverse-consistency coverage and handle any naming / index drift this run deferred.
- If you maintain `UPDATE_LOG.md`, the implementation entry there is now the authoritative narrative for the feature.

4. Leave the diff uncommitted — the user reviews it in their VCS tool and decides when to commit.

Operating Posture

• Single-file mutation. The only write is to the file passed in (or its .compacted-preview.md sibling). Everything else — meta/convention.md, index.md, sibling design/requirements, UPDATE_LOG.md, release notes — is read-only context. Deleting or moving an obsolete plan is the user's call.
• One invocation, one file. For several plans, run once per file so each diff stays small and reviewable.
• Idempotent. A second run on the same file is (almost) a no-op; if a compaction changelog entry already exists, skip writing a duplicate.
• Composable with spec-lint. Typical flow: implement → ship → spec-compact the plan → spec-lint the tree to refresh coverage and surface anything the compaction made newly visible.