task-pipeline-skill 1.58.0 → 1.60.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## v1.60.0 — the gate this skill ships had never run on this skill
+
+Wiring it in was one line. Running it once found five things, and each was silent in a
+different way:
+
+- **It was skipping itself in every submodule checkout.** The section asked `[ -d .git ]`,
+  and a submodule's `.git` is a *file* holding a `gitdir:` pointer — the same shape that
+  disarmed two negative self-tests in v1.58.0, now found a third time in two days, in the
+  shipped gate. It asks `git rev-parse --is-inside-work-tree` now, which knows all three
+  shapes.
+- **Its corpus default still named the artifact root as it was before the 2026-08-13
+  rename**, so in every migrated project the SHA and propagation sections found nothing and
+  reported **dormant** — which reads exactly like having nothing to check. The root is
+  resolved now, new name first.
+- **Eleven commit references could not be followed.** Nine are pre-gate history rewritten
+  early in this project's life, one is a documentation placeholder that never named a
+  commit, and two were branch commits a **squash merge** had replaced — which is the same
+  class as the amend above, arriving from a different direction. The two were repointed to
+  the commits that carry their work on `main`; the other nine are **enumerated by name**
+  in the archive with their date and reason, so the gate passes over exactly those and
+  fails on the twelfth. An exception with names, never a floor.
+- **Two decisions named documents that never cited them.** `DEC-0001` and `DEC-0004` are
+  now cited in `progress.md` and `companion-skills.md` — which is the propagation contract
+  working the moment anything checked it.
+- **One id was reported undefined because the checker could not tell a plant from a
+  claim.** A retro entry recording *planted `DEC-0009` while the highest defined id was
+  `DEC-0001`* was read as a citation. A line describing a planted defect is sample content
+  by the same argument as a fenced block, and `strip_asides` now treats it as one.
+
+`npm run test:docs` is a script, and `test:all` calls it, and a guard requires both — a
+gate nobody's aggregate command runs is a gate that goes quiet the first busy week.
+
+Guards: 344 → **344**. The change is a gate script and its wiring; every finding above
+was watched being produced by the gate itself, which is the only plant a script that
+reads a project's own git history can have.
+
+## 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.60.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.60.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"
@@ -9,9 +9,10 @@
     "test": "python3 test/validate.py",
     "test:negatives": "python3 test/negatives.py",
     "test:probe": "python3 test/probe.py --self-test",
-    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks && npm run test:artifacts",
+    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks && npm run test:artifacts && npm run test:docs",
     "test:hooks": "python3 test/release_gate_test.py",
-    "test:artifacts": "python3 test/artifact_root_test.py && python3 test/migrate_artifacts_test.py"
+    "test:artifacts": "python3 test/artifact_root_test.py && python3 test/migrate_artifacts_test.py",
+    "test:docs": "bash plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh"
   },
   "files": [
     "bin",

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.60.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -8,6 +8,12 @@ something isn't installed.
 What remains is a short list of **optional** companions that make individual stages
 better, plus one that is required only for user-facing work.
 
+
+> **Decision `DEC-0004`** — two browser channels ranked by nothing, one detection rule,
+> stop at the first that answers. The step stays **recommended and never a gate**: a gate
+> an environment cannot satisfy is one an agent learns to report around, and *verified by
+> reading the diff* already prices the absence honestly (`docs/DECISIONS.md`).
+
 ## Contents
 
 - Built in — nothing to install

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

@@ -18,6 +18,12 @@ maintains them and the next run reads them as current.
 
 ---
 
+
+> **Decision `DEC-0001`** — the hand-back names what this run filed, and the join from a
+> run to its rows already exists: the board's `Source` column. It deliberately buys no
+> coverage number, because a required minimum is a run filing a throwaway row to make
+> the count agree (`docs/DECISIONS.md`).
+
 ## Contents
 
 - The two boundaries, and only those two

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

@@ -34,7 +34,18 @@ DEC_FILE=${DEC_FILE:-$DOCS_DIR/DECISIONS.md}
 ADR_DIR=${ADR_DIR:-$DOCS_DIR/adr}
 OQ_FILE=${OQ_FILE:-$DOCS_DIR/OPEN_QUESTIONS.md}
 MAP_FILE=${MAP_FILE:-$DOCS_DIR/DOCMAP.md}
-RETRO_GLOB=${RETRO_GLOB:-$DOCS_DIR/superpowers}
+# The artifact root is RESOLVED, not assumed. It was renamed `superpowers` → `evidence`
+# on 2026-08-13 (v1.53.0 made it resolvable, v0.46.0 moved the family), and this default
+# still named the old one — so in every migrated project the SHA and propagation sections
+# below found no corpus and went **dormant**, which reads exactly like having nothing to
+# check. Measured 2026-08-16 on this skill's own repository. Prefer the new name, fall
+# back to the old, and a project that has neither gets the dormant message it deserves.
+if [ -z "${RETRO_GLOB:-}" ]; then
+  if [ -d "$DOCS_DIR/evidence" ]; then RETRO_GLOB="$DOCS_DIR/evidence"
+  elif [ -d "$DOCS_DIR/superpowers" ]; then RETRO_GLOB="$DOCS_DIR/superpowers"
+  else RETRO_GLOB="$DOCS_DIR/evidence"
+  fi
+fi
 
 # ---------- ratchets: a floor may only fall. Raising one is a decision. ----------
 # THE TWO FLOORS ARE DIFFERENT KINDS. Mixing them up is why this is spelled out.
@@ -68,6 +79,13 @@ strip_asides() {
   awk '
     /^[ \t]*(```|~~~)/ { infence = !infence; print ""; next }
     infence { print ""; next }
+    # A line describing a PLANTED defect quotes ids that were never meant to exist —
+    # that is the payload of a negative self-test, written down so the incident can be
+    # read later. It is sample content by the same argument as a fenced block, and the
+    # checker cannot otherwise tell an id being USED from an id being DISCUSSED. Found
+    # 2026-08-16: a retro entry recording `planted DEC-0009 while the highest defined id
+    # was DEC-0001` was reported as citing an undefined decision.
+    /planted/ { print ""; next }
     {
       line = $0
       # A comment carried over from an earlier line.
@@ -430,25 +448,45 @@ fi
 # ---------- 9. every commit SHA named in the retro resolves ----------
 # A file:line rots at the next edit; a SHA carries the diff, the message and the
 # parent forever. A document may not send a reader to something absent.
-if [ ! -d .git ]; then
+# `[ -d .git ]` is the wrong question and it silently disabled this whole section for
+# every submodule and every linked worktree — where `.git` is a FILE holding a `gitdir:`
+# pointer. Measured 2026-08-16 on this skill's own repository, checked out as a submodule:
+# the section printed `skip` while five SHAs in the archive did not resolve at all. Ask git
+# whether it is inside a work tree; it knows about all three shapes and this does not.
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   skipmsg "commit-SHA resolution — not a git working tree"
 elif [ ! -d "$RETRO_GLOB" ]; then
   dormant "commit-SHA resolution — no $RETRO_GLOB yet"
 else
   : > "$TMP/sha"
+  # An enumerated exception, never a floor. A commit whose history was rewritten before any
+  # of this was gated cannot be repaired without inventing a mapping, and a frozen record of
+  # a past run is not rewritten. Such SHAs are listed by name in a `docgate:known-dead`
+  # marker inside the retro corpus itself — one home, with the reason in prose beside it —
+  # so this passes over exactly those and still fails on the next one.
+  DEAD=$(grep -rho 'docgate:known-dead[^>]*' "$RETRO_GLOB" 2>/dev/null | sed 's/docgate:known-dead//' | tr -s ' \n' ' ')
   find "$RETRO_GLOB" -type f -name '*.md' 2>/dev/null | sort | while IFS= read -r f; do
     grep -n -o '`[0-9a-f][0-9a-f]*`' "$(flat_of "$f")" 2>/dev/null |
     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 ||
+      case " $DEAD " in *" $s "*) continue ;; esac
+      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