chore(ai): replace learned numbering pipeline with counter file

The old method scanned 719+ files via glob+grep+sort+head every time a
learned summary was created. Replace with plan/learned/.counter holding
the next available number. Commit scripts read it, use it, bump it.

Added make ze-learned-counter for recovery, collision guard in commit
scripts, and updated all skill/rule references.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: thomas-mangin

.claude/rules/planning.md

@@ -38,10 +38,19 @@ The lifecycle is: `in-progress` -> Review Gate clean -> write learned summary ->
 All three happen in `/ze-implement` step 15, in one commit script the user runs once.
 Leaving a completed spec in `plan/` causes every future session to count it as open work.
 
+**The commit script IS the final deliverable.** The user runs it and considers the work
+finished. They will not come back to ask for a "close the spec" step. Therefore:
+- Learned summary, LEARNED-INDEX update, and `git rm plan/<spec>` MUST be in the same
+  script that commits the implementation code.
+- Never present the implementation commit first and closure "as a next step."
+- Never split into two scripts or two commits.
+- If the script is missing any of these, the step is incomplete. Go back and include them.
+
 | Banned | Why |
 |--------|-----|
 | "I'll close it later" | Later never comes. Other sessions see it as in-progress. |
 | "The user will handle it" | The user asked us to implement. Closure is part of implementation. |
 | "It's just a status change" | A spec in `plan/` with status `done` is worse than `in-progress` -- it is invisible to `/ze-status` staleness checks but still occupies the spec list. |
+| "Run the commit, then I'll prepare closure" | The user will not ask. One script, one run, done. |
 
 `/ze-status` flags in-progress specs with clean Review Gates as "completed but not closed."

Makefile

@@ -675,6 +675,12 @@ ze-spec-status:
 ze-spec-status-json:
 	@go run scripts/status/spec_status.go --json
 
+# Rebuild plan/learned/.counter from directory contents (recovery)
+ze-learned-counter:
+	@n=$$(ls plan/learned/[0-9]*.md 2>/dev/null | sed 's/.*\///' | grep -oE '^[0-9]+' | sort -rn | head -1); \
+	echo $$(( $${n:-0} + 1 )) > plan/learned/.counter; \
+	echo "plan/learned/.counter set to $$(cat plan/learned/.counter)"
+
 # ─── Inventory ──────────────────────────────────────────────────────────
 
 # Generate project inventory (plugins, YANG, RPCs, tests, packages)

ai/rules/git-safety.md

@@ -16,6 +16,7 @@ cross-commit. Package add + commit into a single user-triggered script.
 4. `chmod +x` every script you hand the user (commit, delete, helper) at creation. User runs it directly (`./tmp/...`), not via `bash`.
 5. Never end an output line with `.`, `,`, `:`, or `)` directly after a path/URL/command -- users copy-paste; trailing punctuation breaks it. Put path on its own line or follow with a space.
 6. Report what was done and what is left. User decides when to commit.
+7. Before writing a commit script, read `.gitignore` and never `git add` ignored paths. Key ignored paths: `CLAUDE.md`, `AGENTS.md`, `.claude/skills/`, `.codex/skills/`, `.agents/skills/`, `tmp/`, `/bin/`. Only add canonical sources (e.g., `ai/skills/`, `ai/INSTRUCTIONS.md`).
 
 `git commit`/`git add` inside the script is fine -- the ban is on
 direct AI tool invocations, not on what the script does when the user
@@ -35,6 +36,7 @@ git commit -F tmp/commit-msg-<SESSION>-a.txt
 # Commit B (optional; e.g., spec-preservation)
 git rm plan/spec-<name>.md
 git add plan/learned/NNN-<name>.md
+git add plan/learned/.counter   # bumped to NNN+1
 git commit -F tmp/commit-msg-<SESSION>-b.txt
 ```
 
@@ -115,7 +117,8 @@ loops. Wait for completion.
 
 ```
 [ ] 3. Spec completion gate (if driven by a plan/ spec):
-      [ ] Learned summary written to plan/learned/NNN-<name>.md
+      [ ] Learned summary written to plan/learned/NNN-<name>.md (NNN from .counter)
+      [ ] plan/learned/.counter bumped to NNN+1
       [ ] Spec file staged for deletion (git rm)
       Not done -> STOP.
 [ ] 4. Executive Summary Report (rules/planning.md). What was done, what is left.

ai/rules/planning.md

@@ -167,17 +167,19 @@ If a spec describes work that is **already implemented**, run the full Completio
 [ ] 6. Critical Review (BLOCKING — rules/quality.md)
 [ ] 7. Review Mistake Log — check MEMORY.md, promote if seen before
 [ ] 7. Update spec — Implementation Summary, Documentation Updates, Deviations
-[ ] 7. Write learned summary: plan/learned/NNN-<name>.md (see plan/TEMPLATE.md for summary format)
+[ ] 7. Write learned summary: plan/learned/NNN-<name>.md (NNN from plan/learned/.counter; bump after)
 [ ] 7. Verify: `make ze-verify` + git status + git diff, no unintended changes
 [ ] 7. Executive Summary Report — present to user with what was done and what is left (including deferred).
         BLOCKING: learned summary (step 10) must exist. Name the file in the report.
         Do NOT ask to commit. The user will tell you when to commit.
-[ ] 7. Commit (when user says so) — TWO commits, in order:
-        **Commit A:** code + tests + docs + completed spec (with filled audit/verification tables).
-        This preserves the completed spec in git history for future review.
-        **Commit B:** delete spec (`git rm plan/spec-<name>.md`) + add learned summary (`plan/learned/NNN-<name>.md`).
-        The learned summary replaces the spec as the durable artifact.
-        Disjoint systems (e.g., CLI and BGP encoding) get separate commit pairs.
+[ ] 7. Commit (when user says so) — ONE script, ONE commit, everything included:
+        - `git add` all implementation files (code, tests, docs, schema)
+        - `git add plan/learned/NNN-<name>.md` (learned summary)
+        - `git rm plan/spec-<name>.md` (spec closure)
+        - Bump `plan/learned/.counter` and `git add plan/learned/.counter`
+        The user runs the script and the work is done. They will not come back for a
+        second step. If spec closure or learned summary is missing, it never happens.
+        Disjoint systems (e.g., CLI and BGP encoding) get separate commits.
 ```
 
 ## Deferred Work (BLOCKING)
@@ -232,14 +234,9 @@ Every row must be answered Yes/No. Every Yes must name the file and what to add.
 
 ## Writing Learned Summaries
 
-When a spec is complete, write a concise summary to `plan/learned/` using the next available number:
-
-```bash
-LAST=$(for f in plan/learned/[0-9]*-*.md; do basename "$f" | cut -d- -f1; done 2>/dev/null | sort -n | tail -1)
-test -z "$LAST" && LAST=0
-NEXT=$(printf "%03d" $((LAST + 1)))
-# Write summary to plan/learned/${NEXT}-<name>.md (see TEMPLATE.md for format)
-```
+When a spec is complete, write a concise summary to `plan/learned/` using the next available number.
+`plan/learned/.counter` contains the next number. Read it, use it, bump it in the commit script.
+Recovery: `make ze-learned-counter`.
 
 The summary (~25-35 lines) uses this fixed 5-section format:
 

ai/skills/ze-implement.md

@@ -79,25 +79,30 @@ See also: `/ze-audit` (check what exists first), `/ze-review-spec` (post-impl ve
     - If the spec has no Documentation Update Checklist, use `ai/rules/planning.md` "Documentation Update Checklist" as the reference and fill it for the spec.
     - Write the doc updates. Include them in the commit.
 15. **Close spec and present commit (BLOCKING -- do ALL of this BEFORE presenting the commit script):**
-    The user expects that running the commit script completes ALL work. Nothing may be left
-    over, deferred, or require a second script. Do everything below before showing the script.
+    The user runs the commit script and considers the work FINISHED. They will not come back
+    to ask "what's next" or "close the spec now." There is no step 16. The script is the
+    final deliverable. Everything below MUST be in that single script.
+
     a. Write the learned summary to `plan/learned/NNN-<spec-stem>.md` following `plan/learned/METHODOLOGY.md`.
-       Number NNN = next unused number. To find it: `for f in plan/learned/[0-9]*.md; do basename "$f"; done | grep -oE '^[0-9]+' | sort -rn | head -1`
-       then add 1. Use the extraction recipe: Context from Task + Current Behavior, Decisions from Key Design Decisions + annotations, Consequences from Design Insights + Limitations, Gotchas from Deviations + Mistake Log.
+       Number NNN: read `plan/learned/.counter` (contains the next available number).
+       Use the extraction recipe: Context from Task + Current Behavior, Decisions from Key Design Decisions + annotations, Consequences from Design Insights + Limitations, Gotchas from Deviations + Mistake Log.
     b. Update `ai/LEARNED-INDEX.md` if the summary contains a structural decision (not just task completion).
     c. Remove your line from `tmp/session/selected-spec`.
     d. List all changes made (files modified/created, tests added, docs updated, issues found and fixed).
     e. Prepare ONE commit script (`tmp/commit-SESSION.sh`) that does EVERYTHING in a single commit:
+       - Guard: `if ls plan/learned/NNN-*.md 1>/dev/null 2>&1; then echo "ERROR: NNN already taken, re-read .counter"; exit 1; fi`
        - `git add` all implementation files (code, tests, docs, schema)
        - `git add plan/learned/NNN-<spec-stem>.md`
        - `git add ai/LEARNED-INDEX.md` (if updated)
        - `git rm plan/<spec-name>`
-       - Commit message file with both the feature description and the spec closure
-    f. Present the commit script to the user.
+       - Bump `plan/learned/.counter` to NNN+1 and `git add plan/learned/.counter`
+       - Commit message file with both the feature description AND the spec closure
+    f. Present the commit script to the user. This is the end.
 
-    **Why one script, one commit:** the user runs the script and the work is done. No second
-    script, no "now run this other thing", no leftover steps. If there are ANY remaining
-    actions after the user runs the script, the step is not complete. Go back and include them.
+    **Why one script, one commit, no follow-up:** the user will not ask for a second step.
+    They will not remember that the spec needs closing. They will not prompt you for the
+    learned summary. If closure is not in the script, it will never happen and the spec
+    rots in `plan/` forever. Include everything. There is nothing after this step.
 
 ## Rules
 

ai/skills/ze-progress.md

@@ -43,7 +43,7 @@ A spec is **done** only when stage 5 is complete. Stages 1 through 4 are checkpo
    - Are there uncommitted files in the spec scope (code, tests, docs, or the spec file itself)?
    - If uncommitted spec-scoped files remain: STAGE = 4. Go to step 9.
 8. **Stage 5 -- Commit B (closure):** Check:
-   - Does `plan/learned/NNN-<spec-stem>.md` exist? Compute the next `NNN` from `ls plan/learned/ | sort | tail -1` if it does not.
+   - Does `plan/learned/NNN-<spec-stem>.md` exist? If not, read `plan/learned/.counter` for the next NNN.
    - Is `plan/spec-<name>.md` still tracked by git (`git ls-files plan/spec-<name>.md`)?
    - If the learned summary is missing OR the spec file is still tracked: STAGE = 5. Go to step 9.
    - Otherwise: STAGE = done.

plan/learned/.counter

@@ -0,0 +1 @@
+720

plan/learned/METHODOLOGY.md

@@ -102,4 +102,10 @@ At spec completion, the Executive Summary (already BLOCKING before commit) maps
 
 One additional step: scan Design Insights + Known Limitations for **Consequences** bullets not already covered by the Executive Summary mapping. This takes 30 seconds when context is fresh.
 
+## Numbering
+
+`plan/learned/.counter` contains the next available number. Read it, use it as NNN, then bump it (write NNN+1) and `git add plan/learned/.counter` in the commit script.
+
+If `.counter` is missing or wrong, run `make ze-learned-counter` to rebuild it from the directory.
+
 Write the summary to `plan/learned/NNN-<name>.md` instead of moving the full spec to `done/`.