task-pipeline-skill 1.58.0 → 1.59.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## v1.59.0 — never amend a commit a record already names
+
+### Fixed
+
+- **The stamping procedure invited the defect it then had to repair, twice in one
+  close-out.** `retrospective.md` says stamp the run with its own commit; the only way to
+  know that commit is to make it; so the stamp gets folded in with `--amend` — and the
+  amend mints a new SHA, leaving the stamp naming a commit that resolves on the machine
+  that wrote it and reaches no clone. It happened here on 2026-08-16 and then again in the
+  umbrella twenty minutes later, which is a procedure fault rather than two lapses.
+
+  The doctrine now says it in one line — **once a file names a SHA, that commit is
+  frozen** — states the order that removes the temptation (commit the work, *then* stamp in
+  a commit of its own), and names the only repair that does not re-enter the loop: a
+  follow-up commit, never a second amend.
+
+- **The documentation gate asked the weaker of the two questions.** It required every
+  backticked SHA in the retro to *resolve*, and an amended-away commit resolves for as long
+  as the object survives locally. It now also requires **reachability from `HEAD`**
+  (`git merge-base --is-ancestor`), which is the question a reader two months later is
+  actually asking. Watched failing on a purpose-built repository whose stamped commit had
+  been amended away: `commit ... resolves but is NOT reachable from HEAD`.
+
+- **Three id registers that could never allocate are removed** (`B-45`). They were declared
+  over the `fs` backend, whose `reserve` refuses by design, and `agent_sync.py check` had
+  been calling it a problem for as long as they stood. A declaration that cannot be served
+  is worse than none: it reads as a capability, so nobody writes the procedure it hides —
+  and on 2026-08-15 two sessions filed a different `B-073`. Allocation is manual, documented
+  in `CLAUDE.md`, and the guard that requires that documentation now fires on the **backend**
+  rather than on the declaration, so removing the registers could not retire it.
+
+Guards: 344 → **344**. Property checks: 9 → 9. No new plant, and that is the honest
+number: what changed is a gate script (`templates/docgate.sh`) rather than a validator
+guard, and it was watched failing against a purpose-built repository whose stamped commit
+had been amended away — the plant lives in that measurement rather than in the workflow,
+because a gate that runs over a project's own git history cannot be planted from inside a
+copy of this one.
+
+- **The coordination snapshot exists and is linked.** `docs/AGENT_SYNC.md` was missing
+  entirely, which `check` had also been reporting. Generated from the live configuration and
+  linked from `CLAUDE.md`; `agent_sync.py check` → **exit 0, `setup healthy`**, for the first
+  time in this repository.
+
 ## v1.58.0 — a fan-out is not finished when its branches are
 
 The graph model this pipeline was audited against in v1.57.0 named one defect and fixed

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.58.0 |
+| **Version** | 1.59.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/skills/task-pipeline/references/retrospective.md

@@ -32,6 +32,7 @@ file exists to stop.
 
 - Write the entry only for a divergence — and name the layer that owned it
 - Every lesson carries its commit
+- Never amend a commit a record already names
 - The stamp table is capped at ten, and *one line per run* was never a cap
 - `publish:` is a line in the verdict, not a silence
 - Rotation — the archive is how pruning stops losing things
@@ -76,11 +77,39 @@ message and the parent, so `git show <sha>` reconstructs the entire incident two
 months later — which is exactly when the same class comes back and somebody needs
 to know whether this was already understood.
 
-**Every SHA must resolve.** This is [`learned.md`](learned.md) rule 14 — *a
-document may not send a reader to something absent* — applied to history, and it is
-mechanical: the project's documentation gate runs `git rev-parse --verify --quiet
-<sha>^{commit}` over every backticked SHA in the retro and its archive
-([`gates.md`](gates.md)).
+**Every SHA must resolve — and resolving is not enough.** This is
+[`learned.md`](learned.md) rule 14 — *a document may not send a reader to something
+absent* — applied to history, and it is mechanical: the documentation gate runs
+`git rev-parse --verify --quiet <sha>^{commit}` over every backticked SHA in the retro
+and its archive ([`gates.md`](gates.md)).
+
+**But a commit that was amended away still resolves on the machine that amended it**,
+and exists in no clone. The gate therefore also requires each SHA to be **reachable
+from `HEAD`** — `git merge-base --is-ancestor <sha> HEAD` — because that is the
+question a reader two months from now is actually asking, and the weaker one passes
+for as long as the object survives locally.
+
+## Never amend a commit a record already names
+
+Measured 2026-08-16, twice in one close-out and twenty minutes apart. The sequence is
+seductive because each step is right on its own: stamp the run with its commit → the
+stamp is part of the run, so fold it in with `--amend` → the amend mints a new SHA →
+the stamp now names a commit that will never reach the remote.
+
+The rule is one line and it is absolute: **once a file names a SHA, that commit is
+frozen.** A correction goes in a *follow-up commit*, never a second amend — amending to
+repair a stamp is the loop that produced the problem, and the second attempt lands in the
+same place as the first.
+
+Practically, that makes the order:
+
+1. commit the work;
+2. **then** stamp, in a commit of its own, naming the commit from step 1;
+3. prune and write the entry in that same second commit, or a third.
+
+The stamp costs one line and one commit. A run that folds it back into the work to keep
+the history tidy is trading a reader's ability to find the incident for the appearance of
+tidiness — and the reader is the entire reason the stamp exists.
 
 ## The stamp table is capped at ten, and *one line per run* was never a cap
 

package/plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh

@@ -441,14 +441,22 @@ else
     while IFS=: read -r ln tok; do
       s=$(echo "$tok" | tr -d '`')
       case ${#s} in 7|8|9|10|11|12|40) ;; *) continue ;; esac
-      git rev-parse --verify --quiet "$s^{commit}" >/dev/null 2>&1 ||
+      if ! git rev-parse --verify --quiet "$s^{commit}" >/dev/null 2>&1; then
         echo "$f:$ln: commit \`$s\` does not resolve" >> "$TMP/sha"
+      # Resolving is the weaker half. A commit that was AMENDED AWAY still resolves on
+      # the machine that amended it and reaches no clone — measured 2026-08-16, twice in
+      # one close-out: the stamp named the run's commit, the commit was amended to carry
+      # the stamp, and the SHA the stamp recorded stopped being reachable. Ask the
+      # question a reader actually has: is it in this history at all.
+      elif ! git merge-base --is-ancestor "$s^{commit}" HEAD >/dev/null 2>&1; then
+        echo "$f:$ln: commit \`$s\` resolves but is NOT reachable from HEAD — amended away, or on a branch this checkout does not have" >> "$TMP/sha"
+      fi
     done
   done
   if [ -s "$TMP/sha" ] 2>/dev/null; then
-    err "unresolvable commit reference(s):"; sed 's/^/         /' "$TMP/sha"
+    err "commit reference(s) a clone could not follow:"; sed 's/^/         /' "$TMP/sha"
   else
-    ok "every commit reference in $RETRO_GLOB resolves"
+    ok "every commit reference in $RETRO_GLOB resolves AND is reachable from HEAD"
   fi
 fi