Wf Spec Housekeeping

Specs housekeeping

Bring one specs directory back to a single invariant: every spec in it is NNN-name.md in that directory's own number space; active specs stay in place, terminal specs retire under .archive/ but keep their number so depends_on: frontmatter still resolves. Then rebuild the index for that directory in number order.

The scope is a directory, not a repo. Numbering is a per-directory reading order that composes with track grouping: specs/local/003-live-serve.md is both grouped and numbered, and specs/local/003-… and specs/cloud/003-… are separate number spaces that do not collide. Whatever moves here, the dependency graph is unaffected — depends_on paths are repo-root-relative and form one DAG across the whole tree, so keeping numbers stable across an archive move is what keeps that graph resolving.

$ARGUMENTS may contain a mode flag and/or a target directory:

• default (no flag): do both the numbering pass and the README rebuild.
• --number-only: number + archive + fix references; skip the README rebuild.
• --index-only: rebuild the README index only; assume numbering is already clean.
• a path: operate on that directory — either another repo's specs/, or a single track inside one (specs/local/).

This skill mutates files, renames with history, and commits. Work on main only if that is the repo's convention (check git log); otherwise branch first.

Step 0: Fix the scope

Decide which single directory to work on. A path in $ARGUMENTS names it directly; otherwise use specs/ itself. Glob that directory's own *.md (not recursively — sub-directories are separate scopes, and child specs under a <parent>/ folder belong to their parent, not to this number space).

Then read the intent already in that directory:

• Some or all specs already carry an NNN- prefix → it has adopted numbering; proceed to make it consistent.
• No spec carries one → adopting numbering is a new convention, not a repair. Say so and confirm with the user before renaming anything.

A directory full of track sub-directories and no specs of its own has nothing to number. Say which sub-directories are candidates and let the user pick one, rather than recursing on your own.

If the repository, or a sibling repository you can read, already has a specs/README.md, use it as the reference shape for the index. Otherwise use this shape: a status-legend line plus one | # | Spec | Status | table ordered by number, active rows linking to the root and archived rows into .archive/.

Step 1: Inventory

Extract (number, location, filename, status, title) for every spec. Numbers come from the NNN filename prefix; name-only files have none yet.

cd <repo>/specs
meta() { local loc="$1"; shift; for f in "$@"; do
  n=$(basename "$f" | grep -oE '^[0-9]+')
  t=$(grep -m1 '^title:' "$f" | sed 's/^title: *//; s/^"//; s/"$//')
  s=$(grep -m1 '^status:' "$f" | sed 's/^status: *//; s/ *$//')
  printf '%s\t%s\t%s\t%s\t%s\n' "${n:-NONE}" "$loc" "$(basename "$f")" "${s:-none}" "$t"
done; }
meta root    $(ls [0-9]*.md 2>/dev/null)      # numbered active
meta root    $(ls *.md 2>/dev/null | grep -vE '^[0-9]|^README')  # NAME-ONLY: the drift
meta archive $(ls .archive/[0-9]*.md 2>/dev/null)

The name-only list is the work. For each, read its frontmatter status.

Step 2: Classify — terminal vs live

Status vocab varies by repo; map onto two buckets:

• Terminal (archive it): complete, shipped, implemented, superseded, abandoned, archived, stale, deferred. Also treat a draft/drafted spec that carries an Outcome section (shipped-but-status-stale) as terminal, and flip its status to complete, the lifecycle status for shipped work, when you move it.
• Live (keep at the root, just give it a number if it lacks one): vague, drafted/draft with no Outcome, validated, testing, in-progress.

When a name-only spec's status is ambiguous, read the body tail for an ## Outcome / "Done"/"shipped" signal before deciding. If still unclear, ask.

Step 3: Assign numbers

Numbers are stable IDs; never renumber an existing spec. Find the highest number in use across both the root and .archive/, and append from max+1 in created-date order (read each created: field). Created-order is a good default because it keeps a superseding spec after the specs it supersedes; contiguous same-family numbering is an equally fine alternative.

Step 4: Cross-reference grep BEFORE renaming (the step that blocks)

A name-only spec is often a cross-repo companion — the same bare filename exists in sibling repos, and its own frontmatter depends_on/affects may point across ../. Renaming can strand references. Grep the whole workspace for every basename first:

cd <workspace-root>   # the dir that holds all sibling repos, e.g. ../
for b in <basename1> <basename2> ...; do
  echo "=== $b.md ==="
  grep -rIn --exclude-dir=node_modules --exclude-dir=.git "$b\.md" .
done

Triage the hits:

• Same-repo hard links — this repo's own frontmatter (supersedes:, superseded_by:, depends_on:), README rows, and internal doc links. You must fix every one of these in the rename commit.
• Sibling-repo index/prose listings (another repo's README pointing at thisrepo/specs/name.md). These are usually already stale ecosystem-wide and are that repo's housekeeping, not yours. Do not edit sibling repos; note them for the user instead. (If the ecosystem convention is that every repo numbers its own copy, your rename matches it — say so.)