feat(spec-sort): add the docs-pile retrofit helper

spec-sort is Phase 2 of the docs-lifecycle build. It proposes the sort (spine-predicate classification, an evidence panel per candidate, a conservative keyword proposal) and a human confirms every move with --confirm/--skip. Terminal states need an explicit --reason, recorded in the status history.

--apply is fail-safe. It refuses a dirty worktree, validates then writes from a recorded plan file, names applied and not-applied work with a git restore recovery recipe on mid-apply failure, and exits non-zero on post-apply residue. Moves land in docs/specs/ with the -spec.org suffix, a status heading carrying :ID: and a dated history line, and the two-sequence keyword header. file: links across the project-owned roots are recomputed, including a moved doc's own outbound links. Session archives and synced template paths are reported, never rewritten, with the canonical claude-templates file named. A successful run stamps :LAST_SPEC_SORT: in .ai/notes.org.

The 33-test bats suite is glob-discovered by make test. A dry run against rulesets' own pile matches the expected five candidates.

1 files changed, 2 insertions, 2 deletions

diff --git a/todo.org b/todo.org
index 61be603..3aa31b3 100644
--- a/todo.org
+++ b/todo.org
@@ -405,8 +405,8 @@ spec-response Phase 6 run: this parent now carries the =:SPEC_ID:= binding (the
 *** 2026-07-01 Wed @ 23:39:10 -0400 Phase 1 landed — docs-lifecycle rule + four spec-workflow updates
 claude-rules/docs-lifecycle.md written and linked machine-wide (make install). Canonical-side updates: spec-create Phase 5 + template (docs/specs/ location, two-sequence keyword header, DRAFT status heading with :ID:, transition mechanics), spec-review (location expectation with the legacy compatibility rule keyed on :LAST_SPEC_SORT:, plus the DRAFT→READY flip — and the demote-back-to-DRAFT path a failed re-review takes), spec-response Phase 6 (owns READY→DOING, stamps :SPEC_ID: on the build parent, always emits the flip-to-IMPLEMENTED task), task-audit Phase B (the :SPEC_ID: reconcile query, checking the parent's keyword rather than counting children). Mirror synced; make test green end to end.
 
-*** TODO Phase 2 — spec-sort helper + bats suite :solo:
-Build claude-templates/.ai/scripts/spec-sort per the spec's retrofit contract: classify (Decisions AND Implementation phases), evidence-based confirm gate, plan + validate before first write, move + rename to -spec.org + status heading + :ID:, relink file: links per the rewritten-roots/report-only contract, clean-worktree preflight (--allow-dirty override), named recovery on mid-apply failure (incl. deleting created untracked copies), residue-grep exit gate, :LAST_SPEC_SORT: stamp. Bats in claude-templates/.ai/scripts/tests/ covering classification, confirm gate, plan validation, move+rename, relink, preflight, forced-failure recovery output, idempotence, marker stamp. Verify: make test green, sync-check clean.
+*** 2026-07-01 Wed @ 23:57:44 -0400 Phase 2 landed — spec-sort helper + 30-test bats suite
+Built claude-templates/.ai/scripts/spec-sort (Python, TDD — the 30-test bats suite written red-first in claude-templates/.ai/scripts/tests/spec-sort.bats) covering the full retrofit contract: spine classification with the -spec.org-name-without-spine anomaly case, evidence panel (Status field, cookies, linking todo.org task, dated history, artifact existence) with conservative non-terminal proposals, per-candidate --confirm/--skip gate with --reason required on terminal keywords, clean-worktree preflight (--allow-dirty prints what recovery loses), validate-then-write from a recorded plan file, relink across the rewritten roots (inbound AND the moved doc's own outbound relative links) with report-only for sessions + synced templates (naming the canonical claude-templates file), bare-path mentions blocking until --acknowledge-bare, named recovery on injected mid-apply failure, post-apply residue gate, idempotent :LAST_SPEC_SORT: stamp. Real-data dry run against rulesets' pile matched predictions: 5 candidates, 4 anomalies, 30 notes, 0 bare, 10 report-only (incl. the startup.org synced-template case Codex flagged). make test green; sync-check clean.
 
 *** TODO Phase 3 — rulesets pilot (interactive)
 Run spec-sort against rulesets' own docs/ with Craig confirming each candidate (~5 spec candidates among 41 design files + 2 stray root specs). Fix what the pilot surfaces. Verify: acceptance criteria 1-6 and 10 — status board matches reality, every remaining docs/design file is a note, re-homed specs carry -spec.org, links resolve, residue grep zero, no id: links in rewritten output.