task-pipeline-skill 1.68.0 → 1.69.0

package/plugins/task-pipeline/skills/task-pipeline/templates/README.md

@@ -21,6 +21,7 @@ from `super-ux`.
 | `open-questions.md` | `docs/OPEN_QUESTIONS.md` | 0 seeds it, the Doc Loop resolves rows |
 | `docgate.sh` | `scripts/check-docs.sh` | 0 seeds it · 9 runs it · 10 proves it |
 | `exposure.sh` | `scripts/exposure.sh` | 0 reads it · 10 recomputes it · `checkup` prints it |
+| `convergence.sh` | `scripts/check-convergence.sh` | 0 seeds it · **10 runs it before the release closes** — only where the project pins components |
 | `hygiene.sh` | `scripts/check-hygiene.sh` | 0 seeds it · **5 runs it after every task** · 6 and 9 run it · 10 proves it |
 | `stage-coverage.sh` | `scripts/stage-coverage.sh` | 0 seeds it · **10 runs it before the coverage table** — every stage the flow declares must carry a verdict, or the flow stops declaring one it merges |
 | `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |

package/plugins/task-pipeline/skills/task-pipeline/templates/carryover.md

@@ -41,7 +41,7 @@ set that may only shrink, and it is printed beside every gate verdict:**
 ```
 GATE 6 tests: PASS — full suite green (247 tests)
   carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
-  abstained: 1 (1 cannot-verify) · unlooked: 2 dormant
+  abstained: 1 (1 cannot-verify) · unlooked: 2 dormant · holds: 1 (container: pg-test, this run)
 ```
 
 That one line is the whole mechanism. Without it, `PASS` reads as *verified*; with

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# check-convergence.sh — release acceptance across components, for <project>.
+#
+# Seeded by task-pipeline (references/acceptance.md → *Release acceptance happens at
+# convergence*). IT IS YOURS NOW: extend it here, section by section.
+#
+# WHY IT EXISTS. Stage 10 already required `git submodule status` with no `+` and every
+#   repository clean and pushed. That is a statement about COMMITS: the parent points at
+#   the child's newest one. It does not prove anything works at those two versions
+#   together. A parent can point at a green submodule whose contract the parent calls
+#   with the previous signature, and every check passes — the submodule's suite ran
+#   against the submodule, the parent's against the parent, and no check ran across the
+#   pointer. Neither repository looks wrong alone.
+#
+# SCOPE: it checks the POINTERS mechanically and the SEAM by record. It does NOT run your
+#   cross-component test — it cannot know what that is — it requires that one was run and
+#   that its record names the exact versions it observed. Read this before quoting a green
+#   from here as evidence of a working composition.
+#
+# EXIT CODE IS THE OUTPUT: non-zero on any failure. Nothing runs after the VERDICT block.
+#
+# PORTABLE to macOS bash 3.2: no grep -P, no readarray, no mapfile, no sed -i.
+#
+# PROGRESSIVE ARMING: a section whose input does not exist prints `dormant:` and does NOT
+#   fail. A project with no components, or a range in which no component pointer moved,
+#   has no seam to prove — and a gate that starts red teaches its project on day one that
+#   the gate is noise.
+#
+# USAGE: check-convergence.sh [<base-ref>]      # default: origin/HEAD, else the root commit
+set -u
+
+BASE="${1:-}"
+FAILED=0
+LIVE=0
+say()  { printf '%s\n' "$*"; }
+ok()   { LIVE=$((LIVE+1)); say "ok: $*"; }
+bad()  { FAILED=$((FAILED+1)); say "FAIL: $*"; }
+dorm() { say "dormant: $*"; }
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  dorm "not a git checkout — nothing to converge"
+  say ""; say "VERDICT: PASS (dormant) — components 0 · live checks 0"
+  exit 0
+fi
+
+if [ -z "$BASE" ]; then
+  if git rev-parse --verify -q origin/HEAD >/dev/null 2>&1; then
+    BASE="origin/HEAD"
+  elif git rev-parse --verify -q origin/main >/dev/null 2>&1; then
+    BASE="origin/main"
+  else
+    BASE="$(git rev-list --max-parents=0 HEAD 2>/dev/null | tail -1)"
+  fi
+fi
+say "range: ${BASE}..HEAD"
+
+# --- 1. the components this repository pins -----------------------------------------
+if [ ! -f .gitmodules ]; then
+  dorm "no .gitmodules — this repository pins no components"
+  say ""; say "VERDICT: PASS (dormant) — components 0 · live checks 0"
+  exit 0
+fi
+
+COMPONENTS="$(git config -f .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null \
+              | awk '{print $2}')"
+N=0
+for c in $COMPONENTS; do N=$((N+1)); done
+say "components: $N"
+
+# --- 2. the pointer, mechanically ----------------------------------------------------
+# A '+' means the parent points at something other than the child's checked-out commit,
+# so a clone of the parent gets a different tree than the one that was tested.
+DIRTY="$(git submodule status 2>/dev/null | grep '^+' | awk '{print $2}')"
+if [ -n "$DIRTY" ]; then
+  for d in $DIRTY; do bad "$d: the parent's pointer and the child's HEAD disagree — a clone gets a different tree than the one tested"; done
+else
+  ok "every pointer matches the child's HEAD"
+fi
+
+# --- 3. the pin must exist on the child's REMOTE -------------------------------------
+# Measured here, 2026-08-16: a release tag failed CI at checkout because the parent
+# pinned a commit that existed only on one machine. `git submodule status` showed no '+',
+# because the pointer matched the LOCAL head. This is the check that was missing.
+# The PARENT'S POINTER, not the child's HEAD. Those are the same fact only while they
+# agree, and they disagree in exactly the case this section exists for. The first draft
+# read `git -C <c> rev-parse HEAD` and, on its first live run against a real parent,
+# reported about a commit the parent does not pin.
+for c in $COMPONENTS; do
+  PIN="$(git rev-parse "HEAD:$c" 2>/dev/null)"
+  [ -n "$PIN" ] || { dorm "$c: the parent's tree records no pointer for it"; continue; }
+  SHORT="$(printf '%.7s' "$PIN")"
+  if [ ! -d "$c/.git" ] && [ ! -f "$c/.git" ]; then
+    dorm "$c: pinned at $SHORT but not checked out — cannot ask its remote whether that commit is published"
+    continue
+  fi
+  if git -C "$c" branch -r --contains "$PIN" 2>/dev/null | grep -q .; then
+    ok "$c: pinned at $SHORT and that commit is published"
+  else
+    bad "$c: pinned at $SHORT, which no remote branch of the component contains — every clone of the parent fails at checkout while this machine stays green"
+  fi
+done
+
+# --- 4. the seam, by record -----------------------------------------------------------
+# Required only for a component whose pointer MOVED in this range: a range that crossed
+# no component boundary has no seam to prove, and demanding a record for it is how a
+# gate becomes noise.
+MOVED=""
+for c in $COMPONENTS; do
+  if git diff --quiet "$BASE" HEAD -- "$c" 2>/dev/null; then :; else MOVED="$MOVED $c"; fi
+done
+
+if [ -z "$MOVED" ]; then
+  dorm "no component pointer moved in this range — no seam was crossed"
+else
+  RECORD=""
+  for f in docs/evidence/convergence.md docs/superpowers/convergence.md CONVERGENCE.md; do
+    [ -f "$f" ] && RECORD="$f" && break
+  done
+  if [ -z "$RECORD" ]; then
+    for c in $MOVED; do
+      bad "$c: its pointer moved and no convergence record exists (docs/evidence/convergence.md) — the composition at these versions was never observed"
+    done
+  else
+    ok "convergence record: $RECORD"
+    for c in $MOVED; do
+      # Again the parent's pointer: the record must name the version the parent will
+      # SHIP, which is what a clone gets, not whatever is checked out here.
+      PIN="$(git rev-parse "HEAD:$c" 2>/dev/null)"
+      SHORT="$(printf '%.7s' "${PIN:-}")"
+      if [ -n "$SHORT" ] && grep -q "$SHORT" "$RECORD"; then
+        ok "$c: the record names the exact version it observed ($SHORT)"
+      else
+        bad "$c: pinned at ${SHORT:-?} and $RECORD does not name that version — a record citing no version cannot say which composition it observed"
+      fi
+    done
+  fi
+fi
+
+# --- VERDICT — nothing runs after this ------------------------------------------------
+say ""
+if [ "$FAILED" -gt 0 ]; then
+  say "VERDICT: FAIL — components $N · live checks $LIVE · failures $FAILED"
+  exit 1
+fi
+say "VERDICT: PASS — components $N · live checks $LIVE"
+exit 0

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

@@ -3,7 +3,10 @@
 #
 # Seeded by task-pipeline (references/exposure.md). IT IS YOURS NOW.
 #
-# SCOPE: reads the verification ledger and the git tag list. It does NOT know whether a
+# SCOPE: reads the verification ledger and the git tag list. The staleness section reports
+#   how far behind HEAD each row's observation is; it does NOT know whether the commits in
+#   between touched anything the row covers, so `behind` means *unproven for this tree*,
+#   never *wrong*. It does NOT know whether a
 #   confirmation was any good, whether a `pass` in the Auto column was watched failing,
 #   or anything about code. Read this header before quoting a number from here.
 #
@@ -226,6 +229,106 @@ esac
 
 echo "$LINE"
 
+# ---------- staleness: a row is true about the tree it OBSERVED, not about this one ------
+# B-081. The ledger tracked rows nobody had ever confirmed and had no notion of a row whose
+# confirmation the tree has since overtaken. Those are the same failure from two ends and
+# only one end was instrumented: a row verified at commit A stayed `verified` after commit B
+# forever.
+#
+# This is a PORT, not a design: `references/knowledge-graph.md` already gives the code graph
+# a freshness contract — a stamp, a distance, three states, and every non-current state
+# ending in a marker. The same shape, applied to the ledger.
+#
+# NO THRESHOLD AND NO TARGET, for the same reason the `never` column has none: the honest
+# number is whatever it is, and a floor here would teach a run to re-observe rows for the
+# counter rather than for the question.
+STALE_CURRENT=0; STALE_BEHIND=0; STALE_UNRESOLVABLE=0; STALE_UNANCHORED=0
+STALE_LIST=""
+if [ -f "$LEDGER" ] && git rev-parse --git-dir >/dev/null 2>&1; then
+  OBSERVED=$(awk -F'|' '
+    function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s }
+    function lower(s) { return tolower(s) }
+    {
+      if (NF < 3) next
+      c1 = lower(trim($2))
+      if (c1 == "req" || c1 == "id" || c1 == "#") {
+        ocol = 0
+        for (i = 2; i < NF; i++) {
+          n = lower(trim($i))
+          if (n == "observed at" || n == "observed") { ocol = i }
+        }
+        next
+      }
+      if (!ocol) next
+      if (trim($2) ~ /^-+$/) next
+      id = trim($2); v = trim($(ocol))
+      gsub(/[`*]/, "", v)
+      if (id == "" || id ~ /^-+$/) next
+      print id "\t" v
+    }
+  ' "$LEDGER" 2>/dev/null)
+
+  if [ -z "$OBSERVED" ]; then
+    STALE_STATE="dormant: the ledger has no \`Observed at\` column — no row can say which tree it saw"
+  else
+    STALE_STATE=""
+    OLDIFS=$IFS; IFS='
+'
+    for line in $OBSERVED; do
+      IFS=$OLDIFS
+      rid=$(printf '%s' "$line" | cut -f1)
+      sha=$(printf '%s' "$line" | cut -f2)
+      case "$sha" in
+        ""|"-"|"—"|"never"|"n/a")
+          STALE_UNANCHORED=$((STALE_UNANCHORED+1))
+          STALE_LIST="$STALE_LIST$rid unanchored — no commit recorded, so nothing can say what it saw
+" ;;
+        *)
+          if git rev-parse --verify -q "${sha}^{commit}" >/dev/null 2>&1; then
+            behind=$(git rev-list --count "${sha}..HEAD" 2>/dev/null || echo 0)
+            if [ "${behind:-0}" -eq 0 ]; then
+              STALE_CURRENT=$((STALE_CURRENT+1))
+            else
+              ts=$(git log -1 --format=%ct "$sha" 2>/dev/null || echo "")
+              now=$(git log -1 --format=%ct HEAD 2>/dev/null || echo "")
+              days=""
+              if [ -n "$ts" ] && [ -n "$now" ]; then days=" / $(( (now - ts) / 86400 ))d"; fi
+              STALE_BEHIND=$((STALE_BEHIND+1))
+              plural="commits"; [ "$behind" -eq 1 ] && plural="commit"
+              STALE_LIST="$STALE_LIST$rid observed \`$sha\` — $behind $plural$days behind HEAD — not trusted for the current tree until re-observed
+"
+            fi
+          else
+            STALE_UNRESOLVABLE=$((STALE_UNRESOLVABLE+1))
+            STALE_LIST="$STALE_LIST$rid observed \`$sha\`, which does not resolve in this checkout (rebase, squash or shallow clone) — not trusted until re-observed
+"
+          fi ;;
+      esac
+      IFS='
+'
+    done
+    IFS=$OLDIFS
+  fi
+else
+  STALE_STATE="dormant: no ledger or not a git checkout"
+fi
+
+echo ""
+if [ -n "${STALE_STATE:-}" ]; then
+  echo "staleness — $STALE_STATE"
+else
+  # State zero out loud: printing nothing when every row is current is what makes
+  # freshness indistinguishable from a check that never looked.
+  echo "staleness — current $STALE_CURRENT · behind $STALE_BEHIND · unresolvable $STALE_UNRESOLVABLE · unanchored $STALE_UNANCHORED"
+  echo "             (a disclosure: no floor, no direction, never a target. Invalidation is"
+  echo "              not deletion — an overtaken row stays true about the tree it observed.)"
+  if [ -n "$STALE_LIST" ]; then
+    printf '%s' "$STALE_LIST" | head -8 | while IFS= read -r l; do
+      [ -n "$l" ] && echo "           $l"
+    done
+  fi
+fi
+
 # ---------- the check-list: a number without it says there is a problem, not where ----------
 # A SHRUG IS NOT A CLEAN BILL. A status that is neither a date nor a known word means
 # somebody wrote something and nobody can act on it; printing "every shipped row is

package/plugins/task-pipeline/skills/task-pipeline/templates/hooks.example.json

@@ -16,6 +16,18 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(python3 -c 'import json,sys;print(json.load(sys.stdin).get(\"tool_input\",{}).get(\"file_path\",\"\"))'); case \"$f\" in *task-pipeline/references/*.md) r=\"references/${f##*/}\"; l=.task-pipeline/run.md; mkdir -p .task-pipeline; touch \"$l\"; grep -q \"^read: $r$\" \"$l\" || echo \"read: $r\" >> \"$l\";; esac; exit 0"
+          }
+        ]
+      }
     ]
-  }
+  },
+  "_read_note": "The PostToolUse/Read hook writes `read: references/<file>.md` into the run ledger, deduplicated, and ALWAYS exits 0 — a hook that can fail a Read would break every turn in every session. It is what makes `scripts/graph.py doctrine` able to say which doctrine a run opened. Without it that verb reports `unmeasured` rather than 0: a skipped file and a read one are otherwise indistinguishable, and 0 would be the reassuring answer to a question nobody asked. Hooks exist only in Claude Code; on any other agent the count stays `unmeasured` and says so."
 }

package/plugins/task-pipeline/skills/task-pipeline/templates/run.md

@@ -18,6 +18,33 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 - Why it is not the build ledger
 - What closes it, and what survives it
 
+## `read:` — which doctrine this run actually opened
+
+The bundle is 34 reference files and nothing recorded which of them a run read, so **a
+skipped file and a read one were indistinguishable** — the class every guard in this
+pipeline exists to catch, left standing over the doctrine itself.
+
+`read:` is **hook-written, never agent-written**, for the same reason `gate:` is: a claim
+about what somebody read, written by the party the claim is about, is not evidence. The
+hook is in `hooks.example.json`, matches `Read`, records the path only
+when it is inside the bundle's `references/`, deduplicates, and **always exits 0** — a hook
+that can fail a `Read` would break every turn in every session.
+
+`scripts/graph.py doctrine` reads these lines and prints one of three things:
+
+| It prints | When | Why not just a number |
+|---|---|---|
+| `unmeasured — no run ledger` | there is no ledger | nothing to read from |
+| `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
+| `N of 34 reference files read`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where |
+
+**It is a disclosure: no floor, no direction, never a target.** A run that needs four files
+and reads four is not worse than one that reads thirty — and the moment the number becomes
+something to raise, agents will open files to raise it. There is **no per-file reading
+floor** in this pipeline; stage 0's mandatory items are the floor that exists, and they are
+not per-file. Inventing one inside a measurement would be a doctrine decision smuggled in
+as a count.
+
 ## Lines
 
 Append-only. These shapes, and nothing else belongs here (the list is the count — a written one drifts, and this one already had):
@@ -27,9 +54,11 @@ stage: <id> <name> — gate <auto|manual> — verdict <pass|fail|skip> — <ISO-
 iter:  <N> — item <B-NNN or task id> — closed at gate <stage id>
 touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
 hand:  <N|10> — task "<quoted>" — done <n> — surfaced <n> — decisions <n> — amb <n> (<ids or "— no register">)
+       scope <commit>/<env>/<REQ ids> — unverified <n|none-in-scope> (<what, or the literal>)
 holds: <stage id> — <n> (<class: what, owner>; … or "none") — enumerated <n>/8 classes, <unlooked: classes not enumerable>
 gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
 event: <compact|session-end|subagent> — <detail> — <ISO-8601>
+read:  references/<file>.md            # hook-written, deduplicated, one per file opened
 ```
 
 - **`stage:`** — written when a gate **returns**, not when the stage is entered. The
@@ -77,6 +106,8 @@ never entered look identical from outside, and they mean opposite things.
 ## Log
 
 ```
+read:  references/grill.md
+read:  references/knowledge-sources.md
 stage: 0 Intake — gate manual — verdict pass — 2026-08-10T11:14Z
 iter:  1 — item B-025 — closed at gate 0
 stage: 1 Docs study — gate auto — verdict pass — 2026-08-10T11:31Z
@@ -88,6 +119,7 @@ event: subagent — general-purpose — 2026-08-10T12:00Z
 gate:  6 — command "npm test" — exit 0 — 2026-08-10T12:02Z
 stage: 6 Tests — gate manual — verdict pass — 2026-08-10T12:03Z
 hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1 — decisions 1 — amb 2 (OQ-0007, ledger row 4)
+       scope 5f21ac3/node-24-linux/REQ-001,REQ-004 — unverified 1 (XLSX path: no fixture)
 holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
 holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)
 ```

package/plugins/task-pipeline/skills/task-pipeline/templates/verification.md

@@ -9,11 +9,73 @@
 > after it shipped, nor whether it still works N releases later, and it dies with its
 > run. This file is the column that outlives it.
 
-| REQ | What | Run | Shipped in | Auto | Human | Note |
-|---|---|---|---|---|---|---|
-| REQ-001 | CSV export from a report | `2026-07-28-export` | v1.4.0 | pass | 2026-07-30 | opened the deployed page, exported, opened the file |
-| REQ-004 | XLSX export | `2026-07-28-export` | v1.4.0 | pass | **never** | — |
-| REQ-007 | Export respects active filters | `2026-07-28-export` | v1.4.0 | partial | **never** | CSV path only |
+## Producer — what wrote the rows below
+
+Computed, never typed, and every field prints even when it cannot be resolved:
+
+```bash
+python3 scripts/graph.py producer      # from the project root
+```
+
+```text
+actor: unavailable: TASK_PIPELINE_ACTOR is not set by this harness
+model: unavailable: TASK_PIPELINE_MODEL is not set by this harness
+runtime: unavailable: TASK_PIPELINE_RUNTIME is not set by this harness
+skill: task-pipeline@1.69.0
+config: sha256:3bb638e189c9ef46
+commit: fbd8a67e6988a0893f273eb37bd9a075a036c223
+trace: unavailable: TASK_PIPELINE_TRACE is not set by this harness
+```
+
+**Paste one such block per run, above the rows that run wrote.** Without it, two runs six
+months apart under different generations of this doctrine leave rows nobody can tell
+apart — so a defect traced to a doctrine change cannot be scoped to the runs that carried
+it. `skill`, `config` and `commit` resolve from the tree; `actor`, `model`, `runtime` and
+`trace` are the harness's to export, and each says so by name when unset, because a field
+that vanishes when unavailable is indistinguishable from one nobody checked.
+
+**A field is never deleted and never guessed.** `model` in particular is not inferred:
+naming a vendor id in a shipped skill is forbidden here, and inferring the wrong one is
+worse than saying nothing.
+
+## Contents
+
+- [Staleness — a row is true about the tree it OBSERVED](#staleness--a-row-is-true-about-the-tree-it-observed)
+- the ledger itself — one row per REQ, appended by stage 8
+- [What `Human` means, and what it does not](#what-human-means-and-what-it-does-not)
+
+## Staleness — a row is true about the tree it OBSERVED
+
+`Observed at` is the commit the check ran against. Without it a row verified at commit A
+reads `verified` after commit B forever, and the ledger tracks rows nobody ever confirmed
+while having no notion of a row the tree has since **overtaken**. Those are the same
+failure from two ends, and only one end was instrumented.
+
+`scripts/exposure.sh` reports four states, and it is a **disclosure**: no floor, no
+direction, never a target — for the same reason the `Human` column has none.
+
+| State | Condition | What it means |
+|---|---|---|
+| **current** | 0 commits behind `HEAD` | the row still speaks about this tree |
+| **behind** | N commits / M days behind | *not trusted for the current tree until re-observed* |
+| **unresolvable** | the commit does not resolve here | rebase, squash or shallow clone — same marker |
+| **unanchored** | no commit recorded | nothing can say what it saw |
+
+**State zero prints out loud.** `current 12 · behind 0 · unresolvable 0 · unanchored 0` is
+a measurement; printing nothing when everything is fresh is what makes freshness
+indistinguishable from a check that never looked.
+
+**Invalidation is not deletion.** An overtaken row is not wrong — it is true about the tree
+it observed, and it stays. Re-observing appends a **new** row; it does not edit the old
+one. Four things overtake a row, and naming which one applies is the note's job: a **code**
+change in what it covers, a **dependency** change, an **environment** change, and a
+**policy** change — the last being the rule under which the evidence was accepted.
+
+| REQ | What | Run | Shipped in | Observed at | Auto | Human | Note |
+|---|---|---|---|---|---|---|---|
+| REQ-001 | CSV export from a report | `2026-07-28-export` | v1.4.0 | `5f21ac3` | pass | 2026-07-30 | opened the deployed page, exported, opened the file |
+| REQ-004 | XLSX export | `2026-07-28-export` | v1.4.0 | `5f21ac3` | pass | **never** | — |
+| REQ-007 | Export respects active filters | `2026-07-28-export` | v1.4.0 | `5f21ac3` | partial | **never** | CSV path only |
 
 ## Columns