task-pipeline-skill 1.78.4 → 1.79.1

package/CHANGELOG.md

@@ -1,3 +1,108 @@
+# Changelog
+
+## v1.79.1 — the probe that a healthy release disarmed
+
+The first round of `v1.79.0` failed in the release job on the
+mentioned-vs-declared probe — not because that guard regressed, but because
+v1.79.0 was the first release in seven to carry a run stamp, which emptied the
+trailing set the probe's mutation lived in. A plant that inherits its
+precondition from repository history switches itself off the moment the history
+improves; the healthiest possible release is exactly what disarmed it.
+
+The plant now manufactures the guard's own refusal state rather than a proxy
+for it: it computes the trailing set exactly the way the guard does — tag
+ranges walked against the stamp-row commits, matching the stamp-row shape,
+because one draft matched "any line naming the sha" and deleted a standing
+instruction's `Fired at` cell instead — un-stamps the newest stamped release
+when nothing trails, mentions every trailing release unbolded, and then
+un-bolds the declarations. The proxy version died twice on the way here: first
+on the inherited precondition, then on a bold span that truthfully named a
+stamped release. Watched both ways on both trees: the correct guard refuses, a
+deliberately regressed guard that reads mentions as declarations accepts.
+
+**`v1.79.0` is a dead tag.** Its round shipped nothing — the suite failed before
+the release step, publish was skipped, npm never saw it — and the tag ruleset
+forbids deleting the tag, so it stays pointed at a tree whose own release suite
+refuses it. The version is burned, not reused: this release carries the whole
+v1.79.0 payload below, plus the probe repair.
+
+Guards: 417 → **417** — the repaired plant changed shape, not count.
+
+## v1.79.0 — the gate that could not see, and the example that disarmed it
+
+Four defects in the release machinery, each demonstrated live before it was
+fixed, plus the two commits that had been sitting on `main` unreleased — one
+version string was serving different trees through different channels.
+
+**A blind release gate now fails closed.** `printf '' | release-gate.sh` exited
+0 with no output, with a run in flight — an empty or unparseable hook payload
+was a silent skip, so the gate allowed every release for as long as its stdin
+plumbing was broken. That is the exact shape this repository's own retro names:
+a component that never receives its input fails open and is indistinguishable
+from approval. With a ledger present the gate now refuses (exit 2), names the
+payload failure and the next step, and appends an `event: gate-blind` line to
+the ledger so the blindness survives the refusal scrolling away. With no run in
+flight it stays silent, as before — installing the plugin still changes nothing
+in an ungoverned repository.
+
+**A green lint stage can no longer stand in for the tests stage.** The stage
+scan took the first stage that was declared `tests` *or* merely carried a gate
+command — so a lint stage declared before the tests stage captured the gate,
+and its green observation released a tag with the suite never run. The scan is
+two-pass now: a stage the project declared as `tests` outranks any stage that
+happens to carry a command. The observer had the same first-match break — only
+the first command-bearing stage was ever recorded — and now records every
+declared command under its own stage id, so the real suite's runs leave the
+trace the release gate corroborates against.
+
+**`npm run publish` is a project's script, not the registry act.** `"publish"
+anywhere in npm's argument list` classified it as `npm publish`; the subcommand
+must now be the first non-flag token. Fail-closed overmatch is still overmatch —
+a gate that fights an ordinary script daily is a gate that gets removed.
+
+**The build gate now fires on the flow this plugin ships.** It matched
+`state == "build"` while the shipped `pipeline.example.json` names its build
+stage `dev` — the canonical config, copied verbatim per its own note, disarmed
+the hook it ships beside. The declaration path now matches `build` or `dev`,
+mirroring the hook's own ledger fallback, and the fixture loads the example
+unmodified so the two cannot drift apart silently again.
+
+**The example no longer arms a loop its own note calls off, and no longer
+teaches the retro deadlock.** `run.loop.mode` was `dynamic` under a `_run_note`
+saying "shipped explicitly OFF" — every project copying the example verbatim
+armed the loop. It is `off` now, with queue, arm and command kept as
+documentation of the shape. And stage 10's check ordered "prune before you add …
+then stamp", which is the deadlock the retro doctrine records: the
+cold-retirement trigger reads the stamp, so a prune placed ahead of it can never
+run on real data. The check now orders stamp → prune → entry and carries the
+sixty-day cold clause the doctrine already had.
+
+**Three stage-0 surfaces stopped telling the run to read the uncapped log in
+full.** `templates/retro.md`, `references/knowledge-sources.md` and
+`templates/brief.md` each instructed reading the retro's Recent log end to end —
+contradicting the retro's own header, measured at 74% of the file with nothing
+capping it. All three now say what the command surface already said: standing
+instructions and run stamps are read in full because they are bounded by
+construction; the Recent log and the archive are queried by the task's nouns.
+
+**Also in this release, previously on `main` with no section here:**
+`references/prioritisation.md` — the impact ladder that dominates (a gate, not a
+factor: confidence × ease orders within a rung and never across one) with the
+operator above it, and `references/stages.md`'s note on what a stage that
+produces user-facing text owes. Both shipped commits now share a heading with
+the version that carries them.
+
+**And this file itself is repaired:** the `# Changelog` H1 sat below five
+version sections with an unheaded block attached — the split half of v1.78.0's
+own entry, orphaned when the section was inserted above the title instead of
+below it. The H1 leads the file again and the orphan is back in its section.
+
+Guards: 413 → **417**. Four new plants, one per gate fix — a blind gate reverted
+to skip, the two-pass scan collapsed to first-match, the npm overmatch restored,
+the build-state match narrowed back — each watched failing against the fixtures
+before it shipped. `test/negatives.py`'s floor moved with the count, in this
+change.
+
 ## v1.78.4 — the channel that sends the installs, on npm too
 
 - The `skills.sh` badge and the canonical `homepage` reached GitHub in the previous cycle and stopped
@@ -46,8 +151,6 @@ with rows still open prints the attribution and drops the request. Asking to be
 endorsed while something is still open is asking to be judged on manner rather
 than on evidence.
 
-# Changelog
-
 **The flow diagram now reads top to bottom, and cannot trip GitHub's renderer.** It
 was reported failing with *"Could not find a suitable point for the given
 distance"* — the error mermaid's edge routing raises on long curved edges, which is

package/README.md

@@ -193,6 +193,7 @@ until it is installed.
 | run-wide reporting | [`progress.md`](plugins/task-pipeline/skills/task-pipeline/references/progress.md) — the header block at task start and the one-line iteration close: the stage rail computed from the project's own `pipeline.json`, every number borrowed from the gate that measured it |
 | run-wide pacing | [`continuity.md`](plugins/task-pipeline/skills/task-pipeline/references/continuity.md) — the loop mode (`run.loop`, default off, never collapses a manual gate) and the context budget (fires on a harness signal, never on an estimate) |
 | the board between runs | [`backlog.md`](plugins/task-pipeline/skills/task-pipeline/references/backlog.md) — the work-list that outlives a run: seeded at stage 0 or picked up, priority **computed** from three stated inputs rather than assigned, and the seam where the carry-over ledger's `backlog` pointer finally resolves |
+| what to do next | [`prioritisation.md`](plugins/task-pipeline/skills/task-pipeline/references/prioritisation.md) — an impact ladder that dominates, confidence × ease inside the rung, researchers dispatched **before** scoring, and the operator's word overriding all of it |
 | what a human confirmed | [`verification.md`](plugins/task-pipeline/skills/task-pipeline/references/verification.md) — one row per shipped REQ and the one column a machine may not fill: the date somebody **looked**, or `never`. No floor, no target — `never` is a fact, and a count driven down is a column that has started lying |
 | how much is unconfirmed | [`exposure.md`](plugins/task-pipeline/skills/task-pipeline/references/exposure.md) — the unconfirmed count as a **vector with its components named**, never a percentage: `P(defect)` is not computable from these inputs and a single score invites a threshold, which is a target on `never`. Plus the check-list, oldest first, and the `/task-pipeline checkup` mode that prints it with no task in flight |
 | 0 + 9 + any settled decision | [`documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) — the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
@@ -586,7 +587,7 @@ must say so.
 ### Held to Anthropic's own Skill authoring guidance
 
 Audited against the four Agent Skills pages. Most of it already held — `name`
-13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 36 references
+13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 37 references
 linked **directly** from `SKILL.md`, 436 KB against a 30 MB ceiling. What did not,
 now does:
 

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.78.4 |
+| **Version** | 1.79.1 |
 | **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.78.4",
+  "version": "1.79.1",
   "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.78.4",
+  "version": "1.79.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/hooks/build-gate.sh

@@ -64,7 +64,12 @@ def build_stage_id():
     try:
         cfg = json.load(open(os.path.join(project, "pipeline.json"), encoding="utf-8"))
         for s in cfg.get("stages") or []:
-            if isinstance(s, dict) and s.get("state") == "build":
+            # `build` OR `dev` — mirroring this hook's own ledger fallback
+            # (`build|dev`) below. Matching only `build` meant the shipped
+            # pipeline.example.json, whose build stage is `state: "dev"`, never
+            # armed this gate: the canonical config disarmed the hook it ships
+            # beside.
+            if isinstance(s, dict) and s.get("state") in ("build", "dev"):
                 return str(s.get("id"))
     except Exception:
         pass

package/plugins/task-pipeline/hooks/gate-observer.sh

@@ -49,23 +49,25 @@ try:
 except Exception:
     raise SystemExit(0)
 
-target = None
-for s in cfg.get("stages") or []:
-    if isinstance(s, dict) and (s.get("gate") or {}).get("command"):
-        target = (str(s.get("id")), (s.get("gate") or {})["command"].strip())
-        break
-if not target:
+# EVERY stage that declares a command, not the first. A first-match scan meant
+# a lint stage declared before the tests stage was the only one ever observed,
+# so the real suite's runs left no trace for the release gate to corroborate —
+# the same first-match break the release gate's own stage scan shipped with,
+# fixed together (sweep the class, not the instance).
+declared = [(str(s.get("id")), (s.get("gate") or {})["command"].strip())
+            for s in cfg.get("stages") or []
+            if isinstance(s, dict) and (s.get("gate") or {}).get("command")]
+if not declared:
     raise SystemExit(0)
 
-stage_id, declared = target
-
 # Compared on the normalised command line, not on a substring: `echo "npm test"`
 # and `npm test --watch` are not the project's gate, and treating them as one puts
 # a fabricated observation in the ledger the release gate trusts.
 def norm(s):
     return " ".join(s.split())
 
-if norm(cmd) != norm(declared):
+matches = [(sid, d) for sid, d in declared if norm(cmd) == norm(d)]
+if not matches:
     raise SystemExit(0)
 
 # PostToolUse fires on success; PostToolUseFailure carries the error. Both are
@@ -78,11 +80,13 @@ else:
     code = 1 if failed else 0
 
 stamp = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
-line = 'gate:  %s — command "%s" — exit %d — %s\n' % (stage_id, norm(declared), code, stamp)
 
 # Append-only, like every other line in this file. A ledger that is rewritten is a
-# ledger whose history can be edited to say the suite passed.
+# ledger whose history can be edited to say the suite passed. One line per stage
+# that declared this exact command: two stages declaring the same command is two
+# observations, because each stage's gate is corroborated separately.
 with open(ledger, "a", encoding="utf-8") as fh:
-    fh.write(line)
+    for stage_id, decl in matches:
+        fh.write('gate:  %s — command "%s" — exit %d — %s\n' % (stage_id, norm(decl), code, stamp))
 PY
 exit 0

package/plugins/task-pipeline/hooks/release-gate.sh

@@ -54,13 +54,36 @@ decide() {
   # JSON from there. Watched failing — the gate allowed every release, silently,
   # because `sys.stdin.read()` came back empty and an empty payload is a skip.
   HOOK_INPUT="$input" python3 - "$ledger" "$project" <<'PY'
-import json, shlex, sys, os, re
+import datetime, json, shlex, sys, os, re
 
 ledger, project = sys.argv[1], sys.argv[2]
 raw = os.environ.get("HOOK_INPUT", "")
 try:
     data = json.loads(raw)
-except Exception:
+    if not isinstance(data, dict):
+        raise ValueError("payload is not a JSON object")
+except Exception as exc:
+    # An empty or unreadable payload is the gate NOT SEEING — it says nothing
+    # about whether a release is happening. With no run in flight that is
+    # nobody's business, so stay silent. With a run in flight, a silent skip
+    # here is the fail-open this hook exists to close: watched happening —
+    # `printf '' | release-gate.sh` exited 0 with no output, and the gate
+    # allowed every release for as long as its stdin plumbing was broken. A
+    # component that never receives its input is indistinguishable from
+    # approval, so it fails CLOSED, and the blindness is written into the
+    # ledger (append-only, the lifecycle grammar) so the run can see the gate
+    # went blind even after the refusal scrolls away.
+    if os.path.exists(ledger):
+        why = ("empty payload" if not raw.strip()
+               else "unparseable payload (%s)" % type(exc).__name__)
+        try:
+            stamp = (datetime.datetime.now(datetime.timezone.utc)
+                     .replace(microsecond=0).isoformat().replace("+00:00", "Z"))
+            with open(ledger, "a", encoding="utf-8") as fh:
+                fh.write("event: gate-blind — %s — %s\n" % (why, stamp))
+        except Exception:
+            pass  # recording failed; the block below still stands
+        print("blind\t%s" % why); raise SystemExit(0)
     print("skip"); raise SystemExit(0)
 
 cmd = ((data.get("tool_input") or {}).get("command") or "")
@@ -99,8 +122,22 @@ def outward(tokens):
                         return "git push <tag>"
         if t.endswith("gh") and rest[:2] == ["release", "create"]:
             return "gh release create"
-        if t.endswith("npm") and "publish" in rest:
-            return "npm publish"
+        if t.endswith("npm"):
+            # `publish` must be npm's SUBCOMMAND — the first non-flag token after
+            # npm. `"publish" in rest` matched anywhere in the argument list, so a
+            # project's own `npm run publish` script was gated as the registry
+            # act; fail-closed overmatch is still overmatch, and a gate that
+            # fights an ordinary script daily is a gate that gets removed. Known
+            # narrowness, stated rather than discovered: a flag whose value is a
+            # separate token (`npm --loglevel silent publish`) hides the
+            # subcommand from this scan; the `--flag=value` spelling is read
+            # correctly.
+            for a in rest:
+                if a.startswith("-"):
+                    continue
+                if a == "publish":
+                    return "npm publish"
+                break
     return None
 
 
@@ -122,16 +159,25 @@ stage_lines = [l.strip() for l in text.splitlines() if l.strip().startswith("sta
 
 
 def declared_test_stage():
-    """The tests stage, from the project's own flow. `(id, command)` or None."""
+    """The tests stage, from the project's own flow. `(id, command)` or None.
+
+    TWO PASSES, and the order is the fix. One pass took the first stage that was
+    declared `tests` OR merely carried a gate command — so a lint stage declared
+    before the tests stage became "the tests stage", and its green observation
+    released a tag with the suite never run. A stage the project DECLARED as
+    tests outranks any stage that happens to carry a command; the command-bearing
+    fallback remains for flows that declare no `tests` state at all."""
     try:
         cfg = json.load(open(os.path.join(project, "pipeline.json"), encoding="utf-8"))
     except Exception:
         return None
-    for s in cfg.get("stages") or []:
-        if not isinstance(s, dict):
-            continue
+    stages = [s for s in cfg.get("stages") or [] if isinstance(s, dict)]
+    for s in stages:
+        if s.get("state") == "tests":
+            return (str(s.get("id")), (s.get("gate") or {}).get("command"))
+    for s in stages:
         gate = s.get("gate") or {}
-        if s.get("state") == "tests" or gate.get("command"):
+        if gate.get("command"):
             return (str(s.get("id")), gate.get("command"))
     return None
 
@@ -207,6 +253,21 @@ why=$(printf '%s' "$verdict" | cut -f3)
 
 case "$state" in
   skip|ok) exit 0 ;;
+  blind)
+    # act holds the reason here — the payload never carried a command to name.
+    cat >&2 <<EOF
+task-pipeline: this project has a run in flight ($ledger) and the release gate
+received an unreadable hook payload ($act), so it cannot tell whether this
+command is an outward act. A gate that cannot see fails CLOSED — a blind gate
+that waves things through is indistinguishable from approval, and that is the
+exact shape it once shipped with.
+
+An \`event: gate-blind\` line was appended to the ledger. Check the hook wiring
+(stdin must carry the PreToolUse JSON), then re-run the command. To work without
+the pipeline, remove the ledger ($ledger) or say «без пайплайна» and take the
+route by hand.
+EOF
+    exit 2 ;;
   block)
     cat >&2 <<EOF
 task-pipeline: \`$act\` is an outward, irreversible act and the tests gate has not

package/plugins/task-pipeline/skills/evidence-docs/SKILL.md

@@ -62,8 +62,38 @@ way to teach an agent to route around the rule where it actually protects someth
 pass through here: do it directly and **say out loud** that the claim is unbacked, rather
 than presenting an estimate as a measurement (canon 8).
 
+## Whom the canons serve
+
+**The operator's intent is the point. Evidence is how it survives contact with reality —
+not a licence to refuse it.**
+
+Everything above exists so the operator gets the result they actually wanted and nothing
+breaks quietly on the way. It does not exist to decide *what they are allowed to say*. A
+skill that reads canon 8 as "I may not write an unverified claim" and refuses the work has
+inverted its own purpose: it protected a rule and lost the person the rule was for.
+
+The line, and it is not the same line:
+
+| The operator may | The operator may not, and this is refusal ground |
+|---|---|
+| assert something not yet true — a landing page describing the product they are building, a roadmap, a pitch | make a **measurement** say something it did not: a test that passed, a benchmark, a count, a citation |
+| ship an unbacked claim knowingly, after being told once | have an estimate **presented as** a measurement (canon 8), which is the one thing no intent authorises |
+
+**So the sequence on an unproven claim is: say it once, label it, do the work.** Not a
+negotiation, not a second warning, and never a silent refusal dressed as a question. If
+the operator confirms they know, the claim ships with a marker naming it as forward-looking
+— that marker is the whole of what this skill owes here, and the task gets done.
+
+**Then do the harder half.** Following intent is the floor, not the service. The service is
+making that intent *better* — more structural, more predictable, easier to maintain and
+extend than the operator asked for — while still being the thing they asked for. An agent
+that only obeys is a slower keyboard.
+
 ## The one test
 
 Before a document ships, read it for the sentence that would embarrass you if someone
-asked *"how do you know?"* — and either give that sentence its address, or delete it.
-Everything above is that question, made mechanical.
+asked *"how do you know?"* — then do one of **three** things: give that sentence its
+address, delete it, or **mark it as an unbacked claim the operator chose to make and ship
+it**. The third option is not a loophole; it is the reason the other two are worth
+anything. A rule with no way to proceed under it becomes a rule people route around, and
+then nothing carries an address.

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -73,7 +73,7 @@ gate stops until it is installed.
 | run-wide · what the run **leaves running and leaves behind** — every gate, and stage 10 | `references/residue.md` |
 | run-wide · what the run **prints about itself** — the rail, the iteration line | `references/progress.md` |
 | run-wide · how a run keeps going (the loop mode + the context budget) | `references/continuity.md` |
-| run-wide · the work-list **between** runs, and how its priority is computed | `references/backlog.md` |
+| run-wide · the work-list **between** runs, and the order it comes off | `references/backlog.md` + `references/prioritisation.md` |
 | run-wide · whether a **human** ever confirmed what shipped, and when | `references/verification.md` |
 | run-wide · how much unconfirmed work has piled up, and what to look at first | `references/exposure.md` |
 | any stage · Where each artifact belongs | `references/artifacts.md` |

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

@@ -167,14 +167,14 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/evidence/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): PRUNE BEFORE YOU ADD — every standing instruction checked against its three retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN stamp the run (date, topic, verdict, counts); THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/evidence/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md). THE HAND-BACK IS WRITTEN — the request quoted as GIVEN, progress against it, what was solved with evidence, what surfaced unasked, every waiting decision ASKED here with options, and the ambiguity count computed from the four registers; zero prints as zero."
+        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/evidence/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): STAMP THE RUN FIRST (date, topic, verdict, counts) — the order is load-bearing, not style: the cold-retirement trigger reads the stamp this stage writes, so a prune placed ahead of the stamp can never run on real data; THEN PRUNE — every standing instruction checked against its retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps, or in the last sixty days), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/evidence/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md). THE HAND-BACK IS WRITTEN — the request quoted as GIVEN, progress against it, what was solved with evidence, what surfaced unasked, every waiting decision ASKED here with options, and the ambiguity count computed from the four registers; zero prints as zero."
       }
     }
   ],
-  "_run_note": "Run-wide pacing. Shipped explicitly OFF so this example DEMONSTRATES the default rather than relying on its absence — see references/continuity.md. Set mode to 'interval' and a project stops being asked whether to run item-by-item; it still stops at every manual gate. There is no context-budget field here on purpose: the threshold is not measurable, so it is unconditional doctrine, not config.",
+  "_run_note": "Run-wide pacing. Shipped explicitly OFF so this example DEMONSTRATES the default rather than relying on its absence — see references/continuity.md. (It shipped saying this while mode was 'dynamic' — an example whose note and config disagree arms a loop in every project that copies it verbatim, which is the opposite of demonstrating the default.) The queue, arm and command keys stay filled in as documentation of the shape a project switches on; only mode arms anything. Set mode to 'interval' or 'dynamic' and a project stops being asked whether to run item-by-item; it still stops at every manual gate. There is no context-budget field here on purpose: the threshold is not measurable, so it is unconditional doctrine, not config.",
   "run": {
     "loop": {
-      "mode": "dynamic",
+      "mode": "off",
       "queue": "module-map",
       "arm": "after-decomposition",
       "command": "/loop"

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

@@ -122,6 +122,12 @@ Two consequences worth stating, because both are the point:
 `sev` and `blast` are judgement, and they are written down *as* judgement: two small
 integers a reader can disagree with, rather than a ranking they can only accept.
 
+**This column ranks findings against each other.** When findings and product work compete
+in one list — which is what happens the moment somebody asks *what next* — the order comes
+from [`prioritisation.md`](prioritisation.md): an impact ladder that dominates, then
+confidence × ease inside the rung. `sev × blast` is evidence for the rung there, not a
+substitute for it.
+
 ## The shape is not fixed, so nothing may assume it
 
 This template ships one shape. Projects change it, and they are right to — the family

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -50,7 +50,7 @@ makes the grill's answers *checkable* instead of merely confident.
 | 4b | **The task register, for its *state*** | `docs/ROADMAP.md`, a board, a backlog, the tracker `CLAUDE.md` names | **what is open right now** — read with a command, never from memory; see *Carried-in claims* |
 | 5 | **Product/UX docs** | `docs/ux/` (super-ux chain), `README`, runbooks | user-facing behavior that is already specified |
 | 6 | **Pipeline history** | `<artifacts>/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
-| 7 | **The retro, in force** | `<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**: standing instructions (capped at ten), run stamps and the recent-log window, all bounded by construction |
+| 7 | **The retro, in force** | `<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**: standing instructions (capped at ten) and run stamps (one line each), both bounded by construction; the *Recent log* is **queried** by the task's nouns, like the archive — nothing caps it |
 | 7a | **The retro archive** | `<artifacts>/retro/YYYY-QN.md` | *have we been bitten by this class before?* — **queried** by the task's nouns, never read end to end |
 | 8 | **The knowledge wiki** | see below | distilled cross-project knowledge, prior sessions, why decisions were made |
 | 9 | **Other doc repos the project names** | a docs repo URL or submodule in `CLAUDE.md`/`README`, a sibling checkout, a `docs/` monorepo package | specs, contracts and runbooks that live outside this repo |

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

@@ -57,6 +57,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | **The run mode** — item-by-item pacing, default off, what it never collapses | `references/continuity.md` |
 | **The context budget** — the evidence rule and what a flush actually updates | `references/continuity.md` |
 | **The board** — the work-list between runs, its computed priority, and the ledger seam it resolves | `references/backlog.md` |
+| **The order** — the impact ladder, confidence and ease, research before scoring, and where the human goes | `references/prioritisation.md` |
 | **The verification ledger** — what shipped, and whether a human ever confirmed it | `references/verification.md` |
 | **Exposure** — the unconfirmed count as a named vector, never a probability, and the `checkup` mode | `references/exposure.md` |
 | The retro: prune, cap, commits, archive | `references/retrospective.md` |

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

@@ -0,0 +1,165 @@
+# Prioritisation — what to do next, and why that and not the other thing
+
+**Load this when** the task was not named, when the next row comes off the backlog, when
+the operator asks what to work on, or when a run is about to spend a day on something and
+nobody has checked that it is the most valuable day available.
+
+`backlog.md` owns the **board** — what a row is, where it lives, how it closes. This owns
+the **order** the rows come off it.
+
+## Contents
+
+- The default, and its one exception
+- 1. The impact ladder
+- 2. Confidence and Ease
+- 3. The order, and why it is not a product
+- 4. Research before scoring, not after
+- 5. Where the human goes
+- 6. Two models in one family, and why both are right
+
+## The default, and its one exception
+
+**Every run assumes a backlog exists and that this task competes with it.** A task arriving
+with no stated priority is not priority-free; it is unranked, which is a different and
+worse thing.
+
+**The exception is the operator, and it is absolute.** When they name the task, that is the
+task. The most this file authorises is **one line** — *"`BL-14` scores higher: a checkout
+error affecting paying users. Say the word and I switch; otherwise starting yours now"* —
+and then starting theirs. Not a second ask, not a hedge, not a silent substitution. An
+operator who knows what they are doing is the most reliable prioritiser in the system, and
+an agent that argues with them twice has made itself expensive to use.
+
+## 1. The impact ladder
+
+Impact is the rung, not a feeling. The ladder exists so a bug and a feature can be compared
+at all — without it, "impact" is scored per-item by whoever is looking, and every item is
+somebody's priority.
+
+| Rung | What it means | Test |
+|---|---|---|
+| **I5** | the product does not work for someone **right now** | data loss, an outage, a broken purchase, a blocked signup |
+| **I4** | a product or business metric moves | revenue, activation, retention, traffic, conversion |
+| **I3** | it works, and the experience degrades | crash-free rate, error rate, latency, a rough edge people hit |
+| **I2** | our own speed | debt, tooling, tests, anything that changes how fast the next thing ships |
+| **I1** | polish | nobody's metric moves; it is better and that is all |
+
+Two rules that carry most of the value:
+
+- **An unmeasured claim of I4 is I3 until it is measured.** "This will lift conversion" is
+  a hypothesis; the rung is what the evidence supports, and the gap goes in Confidence.
+- **Blocking is not a rung, it is a multiplier on someone else.** A task nobody can proceed
+  past inherits the highest rung it blocks. State whose work it blocks, or it is not
+  blocking — it is just old.
+
+## 2. Confidence and Ease
+
+Both are 1–3, both are judgement, and both are written down **as** judgement — small
+integers a reader can disagree with, in the row, next to the rung.
+
+**Confidence** — how sure are we that doing this produces the effect claimed?
+
+| | |
+|---|---|
+| **C3** | measured, or the mechanism is obvious and the change is local |
+| **C2** | reasoned from something real — a trace, a ticket, one user |
+| **C1** | a guess we believe. Fine to hold, not fine to hide |
+
+**Ease** — how cheap is it, including the parts nobody counts?
+
+| | |
+|---|---|
+| **E3** | within a run, one surface, reversible |
+| **E2** | a few surfaces, or one that needs coordination |
+| **E1** | crosses repositories, needs a migration or a credential, or cannot be undone cheaply |
+
+Ease counts the **whole** cost: the migration, the review, the rollback, the second
+repository. An E3 that turns out to need a credential from a person who is asleep was an E1
+and the estimate was the defect.
+
+## 3. The order, and why it is not a product
+
+```
+sort by   I    descending          the ladder dominates
+then by   C × E descending          1..9 within the rung
+then by   age  descending           the tie-break, oldest first
+```
+
+**Classic ICE multiplies I × C × E, and this deliberately does not.** Multiplying lets a
+trivial certain easy win outrank a hard uncertain critical one — `I1×C3×E3 = 9` beats
+`I5×C1×E1 = 5` — and shipping the 9 while the 5 waits is precisely the failure this file
+exists to prevent. It is also the failure that feels most productive from inside: a
+stream of small completed things while the thing that matters sits.
+
+So the ladder is a **gate**, not a factor. `C × E` orders within a rung and never across
+one.
+
+**What age may and may not do.** It breaks ties, and past **30 days** the row is reported
+as one the queue has been lying about — surfaced in the run's output, not silently
+promoted. Age never lifts a row across a rung: a polish item that has waited a year is
+still polish, and letting it climb is how a queue ends up sorted by patience.
+
+**`prio` in `backlog.md` is not replaced.** That formula (`sev × blast + age_bonus`) ranks
+*findings against each other* and stays the board's own column. This file's ordering is
+what runs when findings and product work compete in **one** list — the finding's rung comes
+from the ladder above, and `sev × blast` is evidence for it, not a substitute.
+
+## 4. Research before scoring, not after
+
+**A row is scored from what it touches, never from its title.** "Fix the login redirect"
+is E3 by its name and E1 once you find it crosses an auth library, a cookie domain and a
+cached edge rule. Scoring first and discovering second produces an order that was wrong
+before the first task started.
+
+So, before an order is emitted:
+
+1. **Fan out one researcher per candidate row** — same rules as `build.md` §4.2: fresh
+   context each, given the row and nothing else, no shared working tree because they write
+   nothing.
+2. **Each returns four things and no opinion**: what it touches (`file:line`, services,
+   external systems), what it depends on and what depends on it, what is already
+   *measured* about the claimed effect, and what would have to be true for it to be wrong.
+3. **Score after they return.** The rung comes from the evidence, `C` from what the
+   researcher could and could not confirm, `E` from the surfaces they found.
+4. **Emit the ordered list once**, with the three numbers and one line of why per row.
+
+A researcher that comes back with "seems fine, medium effort" has returned nothing. The
+four fields are the contract; anything else is a subagent that spent context to guess.
+
+**Do not fan out to score two rows.** The dispatch costs more than reading them.
+
+## 5. Where the human goes
+
+The operator is a **scarce, high-value input**, and the failure mode is spending them one
+question at a time.
+
+- **Ask at the start, or in a batch at a boundary. Never after each task.** If the whole
+  queue needs one decision, ask it before the queue starts.
+- **A blocked row does not stop the run.** When something needs a person: first satisfy
+  yourself that you are actually right and it is actually blocked — most "I need input"
+  is an unread file — then write the question **into the row**, mark it `needs-operator`,
+  and take the next row that is not blocked by the same answer.
+- **The question in the row is answerable without context.** What was tried, what is
+  needed, and what happens under each answer. A question that requires re-reading the run
+  to understand is a question that waits another day.
+- **Batch the answers back.** The operator returns to a list of questions with their
+  consequences, not to a transcript.
+
+The measure of this section: **how much of the queue moved while nobody was watching**, and
+whether the things that stopped genuinely could not proceed.
+
+## 6. Two models in one family, and why both are right
+
+`seo-aeo-audit` triages on impact, irreversibility, uncertainty and coordination, and states
+that **effort is recorded and never ranks**.
+This file makes Ease rank. That is not a contradiction and the difference is the queue:
+
+| | an **audit** | a **backlog** |
+|---|---|---|
+| the list is | everything that is wrong | everything that could be done |
+| letting effort rank means | a blocker gets skipped for being hard, and the audit lies by omission | the queue self-selects toward value per day |
+| so effort | is recorded and never ranks | ranks, inside the rung |
+
+An audit must be complete before it is ordered; a backlog is ordered because it will never
+be complete. Reach for the wrong one and the symptom is recognisable: an audit that
+quietly dropped its hardest finding, or a backlog where nothing small ever ships.

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

@@ -66,6 +66,7 @@ never that the work was skipped quietly.
 - Cross-cutting — the Doc Loop
 - Cross-cutting — the loop guard
 - Cross-cutting — the audit
+- A stage that produces text a user will read
 
 ## 0 — Intake grill — MANDATORY
 - **Freedom: medium** — the interview adapts to the answers; its two phases and their order do not ([`gates.md`](gates.md) → *Axis C*).
@@ -860,3 +861,22 @@ nothing.
 - **Whatever can't be fixed now becomes a ratchet** — a named, counted set that may
   only shrink, printed beside every gate verdict, so "green" never reads as
   "verified".
+
+## A stage that produces text a user will read
+
+The framework has no opinion on which skills run where — `pipeline.json` is the contract —
+but two facts about copy are worth stating once, because a stage author rediscovers them
+expensively.
+
+**Route it through the copy skill, not through the stage's own prose.** A stage that writes
+interface strings, a landing page or a changelog entry for users is producing brand surface;
+the registers, terminology and canonical facts that constrain it live in `docs/brand/`, and
+a stage writing directly does not read them.
+
+**The humanization pass is decided once, in the brand pack, not per run.**
+`docs/brand/voice.md` carries an optional `Humanization pass:` field; absent means nobody
+has been asked, and the copy skill asks once and records the answer. A pipeline that asks
+every run has turned a settled decision into a prompt, and a pipeline that gates on a
+marker count has turned a writing-quality signal into a verdict — the false positives fall
+hardest on people writing in a second language, and nothing here fails a stage for them.
+`npx sshlg-skills humanizers` lists what is installed.

package/plugins/task-pipeline/skills/task-pipeline/scripts/graph.py

@@ -1042,7 +1042,7 @@ def cmd_producer(graph, args):
 def cmd_doctrine(graph, args):
     """Which doctrine this run actually read — B-061.
 
-    The bundle is 36 reference files. A run reads some subset and nothing recorded which,
+    The bundle is 37 reference files. A run reads some subset and nothing recorded which,
     so **a skipped file and a read one were indistinguishable** — the class every guard in
     this repository exists to catch, left standing over the doctrine itself.
 

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

@@ -59,9 +59,10 @@ source is a recorded decision, an unquoted one is an undetected divergence.
 - **Knowledge wiki:** installed / not installed
   ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki); recommended, never a gate)
 - **Retro, in force:** `docs/evidence/retro.md` — none / N standing instructions
-  (read **in full**, together with the run stamps and the recent-log window; list
-  which ones bind this run, and stamp each as it fires **with the commit** — that
-  stamp is the only evidence behind stage 10's cold-retirement rule)
+  (read **in full**, together with the run stamps — both bounded by construction;
+  the recent log is **queried** by this task's nouns, never read end to end; list
+  which instructions bind this run, and stamp each as it fires **with the commit**
+  — that stamp is the only evidence behind stage 10's cold-retirement rule)
 - **Retro archive:** `docs/evidence/retro/` — **queried** by this task's nouns;
   what it returned: … (or `nothing`)
 - **Code graph:** built / installed-not-built / not installed

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

@@ -6,10 +6,12 @@ The order is load-bearing: the cold-retirement trigger reads the stamp this stag
 writes, so a prune ahead of it can never run on real data (`learned.md` rule 21).
 Doctrine: `references/retrospective.md`.
 
-**What stage 0 reads in full:** *Standing instructions*, *Run stamps* and *Recent
-log* — all three are bounded by construction, which is why the cap is not
-negotiable. The **archive** (`docs/evidence/retro/YYYY-QN.md`) is *queried* by
-the task's nouns and never read end to end.
+**What stage 0 reads in full:** *Standing instructions* and *Run stamps* — both
+are bounded by construction (ten rows, one line per run), which is why the cap is
+not negotiable. The **Recent log** and the **archive**
+(`docs/evidence/retro/YYYY-QN.md`) are *queried* by the task's nouns and never
+read end to end: nothing caps the log's length, and an uncapped section read in
+full is the volume that stops the ten binding rows being read.
 
 ## Standing instructions (max 10 — in force right now)
 

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

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 36 reference files and nothing recorded which of them a run read, so **a
+The bundle is 37 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.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `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 36 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 37 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **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