task-pipeline-skill 1.51.0 → 1.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.51.0",
+  "version": "1.53.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,8 +9,9 @@
     "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",
-    "test:hooks": "python3 test/release_gate_test.py"
+    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks && npm run test:artifacts",
+    "test:hooks": "python3 test/release_gate_test.py",
+    "test:artifacts": "python3 test/artifact_root_test.py && python3 test/migrate_artifacts_test.py"
   },
   "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.51.0",
+  "version": "1.53.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -37,15 +37,15 @@ Pull what the project already knows about *this task*:
   `graphify-out/graph.json`. It answers **reach** — what calls this, what breaks if it
   moves — which grep cannot.
 - `CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past briefs and carry-over ledgers.
-- **the retro's standing instructions and run stamps** — `docs/superpowers/retro.md`,
+- **the retro's standing instructions and run stamps** — `docs/evidence/retro.md`,
   read in full; both are bounded and they bind this run. Its **Recent log** is
   *queried* by the task's nouns, not read: nothing caps it, and an uncapped section
   inside a binding source is what makes the capped part get skimmed
   (`references/retrospective.md`).
 - the **knowledge wiki** if installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki);
   detect `~/.obsidian-wiki/config`), and any other doc system the project names as its docs.
-- **the board** (`docs/superpowers/backlog.md`) — open count quoted in the brief, or
-  seeded when absent. **the verification ledger** (`docs/superpowers/verification.md`) —
+- **the board** (`docs/evidence/backlog.md`) — open count quoted in the brief, or
+  seeded when absent. **the verification ledger** (`docs/evidence/verification.md`) —
   how many rows sit at `never`.
 
 Write the **source ledger** into the brief: a row per source, or an explicit *none found*.

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# PreToolUse — editing the product before the plan is agreed.
+#
+# `stages.md` says no stage advances until its gate passes, and stage 5 is where
+# code gets written. Editing the product during intake, docs, brainstorm, spec or
+# plan is the pipeline's own discipline being skipped — and it is the skip nobody
+# notices, because the work looks like progress.
+#
+# **`ask`, never `deny`, and the reason is this file's own doctrine.** The routing
+# boundary says a typo, a one-line edit or a mechanical rename does not go through
+# the pipeline, and no hook can tell a typo from a feature. A refusal here would
+# fight the honest cases daily and be removed inside a week; a question answered
+# once costs a keystroke.
+#
+# **The build stage is resolved by ROLE, never by number.** v1.50.0 matched
+# `stage: 6` literally and blocked every release in a six-stage project; the same
+# mistake here would put a prompt in front of every edit in any project whose flow
+# is numbered differently. `pipeline.json` → a stage whose `state` is `build`, else
+# one whose name says build. Unresolvable → silence, because a question nobody can
+# act on is worse than none.
+#
+# **The pipeline's own artefacts are never gated.** Stages 0-4 exist to WRITE
+# things — the brief, the spec, the plan, the ledger. A gate that asked about those
+# would fire on the very work it is protecting.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+[ -f "$ledger" ] || exit 0
+
+HOOK_INPUT="$input" python3 - "$ledger" "$project" <<'PY' 2>/dev/null || exit 0
+import json, os, re, sys
+
+ledger, project = sys.argv[1], sys.argv[2]
+try:
+    data = json.loads(os.environ.get("HOOK_INPUT", ""))
+except Exception:
+    raise SystemExit(0)
+
+ti = data.get("tool_input") or {}
+path = ti.get("file_path") or ti.get("notebook_path") or ""
+if not path:
+    raise SystemExit(0)
+
+rel = os.path.relpath(path, project) if os.path.isabs(path) else path
+rel = rel.replace(os.sep, "/")
+# The run writes these; gating them would fire on the work stages 0-4 are for.
+if rel.startswith("..") or re.match(r"^(docs/|\.task-pipeline/|\.claude/|CHANGELOG\.md|README\.md)", rel):
+    raise SystemExit(0)
+
+try:
+    text = open(ledger, encoding="utf-8").read()
+except Exception:
+    raise SystemExit(0)
+
+stage_lines = [l.strip() for l in text.splitlines() if l.strip().startswith("stage:")]
+if not stage_lines:
+    raise SystemExit(0)
+
+
+def build_stage_id():
+    """By role, never by number — the mistake v1.50.0 shipped in the release gate."""
+    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":
+                return str(s.get("id"))
+    except Exception:
+        pass
+    for l in stage_lines:
+        m = re.match(r"stage:\s*(\S+)\s+([^—]*)", l)
+        if m and re.search(r"build|dev\b", m.group(2), re.I):
+            return m.group(1)
+    return None
+
+
+build_id = build_stage_id()
+if build_id is None:
+    raise SystemExit(0)          # unresolvable: a question nobody can act on
+
+# Has the run entered the build stage at all? Entering is enough — the gate is
+# about editing BEFORE the plan is agreed, not about the build's own verdict.
+entered = any(re.match(r"stage:\s*%s\b" % re.escape(build_id), l) for l in stage_lines)
+if entered:
+    raise SystemExit(0)
+
+last = stage_lines[-1]
+m = re.match(r"stage:\s*(\S+)\s+([^—]*)", last)
+now = "%s %s" % (m.group(1), m.group(2).strip()) if m else "an early stage"
+
+print(json.dumps({"hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "ask",
+    "permissionDecisionReason":
+        "This run is at stage %s and has not entered the build stage (%s). Editing "
+        "the product before the plan is agreed is the pipeline's own discipline "
+        "being skipped — and it is the skip nobody notices, because the work looks "
+        "like progress.\n\n"
+        "Allow if this is a typo, a one-line fix or a mechanical rename, which the "
+        "routing boundary says never went through the pipeline anyway. Otherwise "
+        "finish the plan and record stage %s in %s.\n\n"
+        "The pipeline's own artefacts — docs/, .task-pipeline/, README, CHANGELOG — "
+        "are never gated." % (now, build_id, build_id, ledger),
+}}))
+PY
+exit 0

package/plugins/task-pipeline/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "task-pipeline — the stage-7 gate and the observation it rests on. Every hook exits 0 immediately when the project has no .task-pipeline/run.md, so installing the plugin globally changes nothing in a repository that is not running a pipeline.",
+  "description": "task-pipeline — the gates and the observations they rest on. Every hook exits 0 immediately when the project has no .task-pipeline/run.md, so installing the plugin globally changes nothing in a repository that is not running a pipeline.",
   "hooks": {
     "PreToolUse": [
       {
@@ -13,6 +13,17 @@
             "timeout": 20
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/build-gate.sh\"",
+            "timeout": 20
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -40,6 +51,42 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/task-pipeline/hooks/run-lifecycle.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# PreCompact · SessionEnd · SubagentStop — the three moments the run's own record
+# cannot see, written down as they happen.
+#
+# One line shape for all three:
+#
+#     event: <kind> — <detail> — <ISO-8601>
+#
+# **Why one shape and not three.** A ledger grammar is read by four documents and
+# two hooks; every shape added is a shape each of them must learn. These three are
+# the same kind of fact — something happened to the RUN rather than to a stage —
+# and a `kind` field costs one word against three grammars.
+#
+# WHAT EACH ONE IS FOR
+#
+#   compact      — the ledger exists because compaction happens; `templates/run.md`
+#                  says so in its own header. Until now the boundary itself was the
+#                  one event the file could not show, so a resumed run could not
+#                  tell "the context was compacted here" from "nothing happened".
+#   session-end  — a run whose session ended without reaching acceptance is
+#                  ABANDONED, and abandoned runs are exactly what
+#                  `/task-pipeline checkup` exists to surface. Before this they
+#                  were invisible: the ledger simply stopped, which looks identical
+#                  to a run still in progress.
+#   subagent     — stage 5 dispatches implementers as subagents, and the `hand:`
+#                  line counts them. Both sides of that count are written by the
+#                  same agent from the same memory, so the audit comparing them
+#                  compares a number with itself.
+#
+# **It does NOT write `hand:` lines, and that is not a shortcut.** That shape
+# carries `done`, `surfaced`, `decisions` and `amb` — judgements only the agent
+# holds. A hook filling them in would be fabricating the very evidence the line
+# exists to provide. So it records what it can actually see (a subagent of this
+# type stopped) and leaves the accounting to whoever can account.
+#
+# Silent with no ledger, and never blocking: none of these events should ever cost
+# a session. `SessionEnd` hooks share a 1.5-second budget, so this appends one line
+# and exits.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+[ -f "$ledger" ] || exit 0
+
+HOOK_INPUT="$input" python3 - "$ledger" <<'PY' 2>/dev/null || true
+import json, os, sys, datetime, re
+
+ledger = sys.argv[1]
+try:
+    data = json.loads(os.environ.get("HOOK_INPUT", ""))
+except Exception:
+    raise SystemExit(0)
+
+event = data.get("hook_event_name")
+
+
+def clean(text, limit=90):
+    """One line, no separators that would break the ledger's own grammar."""
+    s = re.sub(r"\s+", " ", str(text or "")).replace("—", "-").strip()
+    return s[:limit]
+
+
+if event == "PreCompact":
+    kind, detail = "compact", clean(data.get("trigger") or "unknown")
+elif event == "SessionEnd":
+    # A run that reached acceptance is finished, not abandoned. Recording an end
+    # for it would fill `checkup` with runs that closed exactly as intended.
+    try:
+        text = open(ledger, encoding="utf-8").read()
+    except Exception:
+        raise SystemExit(0)
+    stages = [l.strip() for l in text.splitlines() if l.strip().startswith("stage:")]
+    closed = any(re.search(r"verdict\s+pass", l) and re.search(r"accept", l, re.I) for l in stages)
+    if closed:
+        raise SystemExit(0)
+    kind = "session-end"
+    detail = "%s - run not closed, no acceptance recorded" % clean(data.get("reason") or "other", 40)
+elif event == "SubagentStop":
+    kind = "subagent"
+    detail = clean(data.get("agent_type") or "unknown", 40)
+else:
+    raise SystemExit(0)
+
+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: %s — %s — %s\n' % (kind, detail, stamp))
+PY
+exit 0

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

@@ -18,7 +18,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/superpowers/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; THE GRAPH'S ROW CARRIES ITS MEASURED LAG — commits and days behind HEAD, the signal it was measured with (built_at_commit exact / mtime approximate / unresolvable), and the marker '⚠ not trusted for reach until refreshed' — that exact string, so one marker is greppable across every ledger — on anything but current. A bare build date does NOT satisfy this: it is the graph's own reply about itself, true and self-reported and silent about whether the graph describes the tree this run is about to change — references/knowledge-graph.md -> Measure the lag, and references/gates.md -> False success for the class). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/evidence/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; THE GRAPH'S ROW CARRIES ITS MEASURED LAG — commits and days behind HEAD, the signal it was measured with (built_at_commit exact / mtime approximate / unresolvable), and the marker '⚠ not trusted for reach until refreshed' — that exact string, so one marker is greppable across every ledger — on anything but current. A bare build date does NOT satisfy this: it is the graph's own reply about itself, true and self-reported and silent about whether the graph describes the tree this run is about to change — references/knowledge-graph.md -> Measure the lag, and references/gates.md -> False success for the class). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
       }
     },
     {
@@ -167,7 +167,7 @@
       ],
       "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/superpowers/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/superpowers/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): 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."
       }
     }
   ],

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

@@ -21,6 +21,9 @@
         "$ref": "#/definitions/stage"
       }
     },
+    "paths": {
+      "$ref": "#/definitions/paths"
+    },
     "release": {
       "$ref": "#/definitions/release"
     },
@@ -32,6 +35,19 @@
     }
   },
   "definitions": {
+    "paths": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Where this project keeps the pipeline's own paperwork. Optional: omit it and the root is DISCOVERED — docs/evidence/ when it exists and carries a register (retro.md, backlog.md, verification.md, or a specs/plans/briefs/retro directory), else the legacy docs/superpowers/ on the same test, else docs/evidence/ for a project that has neither. The legacy name is the one this pipeline used until 2026-08-13; a project on it keeps it, with no warning on any run. Setting this key outranks both discovered names, which is what finally makes references/artifacts.md's long-standing promise — a host project may relocate the root — something a machine keeps rather than a sentence.",
+      "properties": {
+        "artifacts": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/].*[^/]$|^[^/]$",
+          "description": "Relative path from the project root to the artifact home: briefs, specs, plans, the backlog, the verification ledger and the retrospective. Relative, no leading or trailing slash — an absolute path would make the config unusable in any other checkout of the same project."
+        }
+      }
+    },
     "run": {
       "type": "object",
       "additionalProperties": true,
@@ -195,7 +211,7 @@
     "retro": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Optional. Governs what the retrospective does BEYOND writing to the project's own docs/superpowers/retro.md, which always happens. Omit it and nothing leaves the repository: silence arms nothing, exactly as it authorises no deploy.",
+      "description": "Optional. Governs what the retrospective does BEYOND writing to the project's own docs/evidence/retro.md, which always happens. Omit it and nothing leaves the repository: silence arms nothing, exactly as it authorises no deploy.",
       "properties": {
         "publish": {
           "type": "object",

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

@@ -61,7 +61,7 @@ that was never a row.
 Read all of them before writing anything:
 
 - the ladder walk's findings (above) — they may have added REQ rows
-- the brief's **REQ table** (`docs/superpowers/specs/<topic>-brief.md`)
+- the brief's **REQ table** (`<artifacts>/specs/<topic>-brief.md`)
 - the **carry-over ledger** (`…-carryover.md`) — in full, every row
 - the plan and its task statuses
 - git log for the run's branch; the test suite's final output
@@ -70,7 +70,7 @@ Read all of them before writing anything:
 
 ## Output — the coverage table
 
-Write `docs/superpowers/specs/YYYY-MM-DD-<topic>-acceptance.md`:
+Write `<artifacts>/specs/YYYY-MM-DD-<topic>-acceptance.md`:
 
 ```markdown
 # Acceptance — <topic>
@@ -177,7 +177,7 @@ whether the run was finished.
 ## The retrospective — the run's last act
 
 After the closing question, before the run is called done:
-[`retrospective.md`](retrospective.md), written to `docs/superpowers/retro.md`.
+[`retrospective.md`](retrospective.md), written to `<artifacts>/retro.md`.
 Every run **stamps and prunes**; only a run that *diverged* writes an entry.
 
 The order is fixed, and it is a **dependency, not a preference** — step 2 reads the

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

@@ -163,7 +163,7 @@ it lands — `templates/hooks.example.json`, and read
 Only when more than one agent works the repository. Then the registers become shared
 state ([`documentation.md`](documentation.md) → *Registers are shared state*) and a
 coordination tool arbitrates: `guardedFiles` must list every register **plus
-`docs/DOCMAP.md` and `docs/superpowers/retro.md`**, which are equally shared and
+`docs/DOCMAP.md` and `<artifacts>/retro.md`**, which are equally shared and
 equally lossy under a concurrent write.
 
 Without such a tool the run is **`ungated`** and must say so. The discipline still

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

@@ -23,7 +23,7 @@ docs/
   OPEN_QUESTIONS.md                   #   … and its questions (OQ-####) — never delete a resolved row
   adr/
     NNNN-<slug>.md                    # the OTHER permitted decision home — one project uses ONE
-  superpowers/
+  evidence/                             # the artifact root — RESOLVED, see the note below
     retro.md                          # stage 10's last act — ONE per project, not per run
     backlog.md                        # the work-list BETWEEN runs — read at 0, resolved at 10
     verification.md                   # one row per shipped REQ; `Human` is a date or `never`
@@ -54,10 +54,39 @@ Naming: date-prefixed `YYYY-MM-DD-<topic>` slugs, one topic per file, kebab-case
 Brief, carry-over, design, plan and acceptance share the **same `<topic>` slug**, so the chain is traceable
 at a glance.
 
-> The `docs/superpowers/` directory name is this pipeline's historical convention
-> (kept so existing projects don't have to migrate) — **not a dependency on any
-> external skill**. A host project may relocate the root via its `CLAUDE.md`; keep
-> the shape, keep the slugs.
+### `<artifacts>/` — the root is resolved, not spelled
+
+Every path above is written `<artifacts>/…`. That is not a placeholder you fill in by
+hand: it is **resolved**, in this order, and the answer is the same for the validator,
+the migration command and you.
+
+1. **`paths.artifacts` in `pipeline.json`** wins outright. Any relative path —
+   `docs/runs/`, `notes/pipeline/`, whatever this project already uses. Until v1.53.0
+   this file promised that a host project *may relocate the root* and nothing kept the
+   promise; the config key is what turned the sentence into a mechanism.
+2. **otherwise the first of `docs/evidence/`, then `docs/superpowers/`** that exists
+   **and carries a register** — a `retro.md`, `backlog.md`, `verification.md`, or a
+   `specs/`, `plans/`, `briefs/`, `retro/` directory. The new name is checked first, so
+   a project that moves one file at a time is never left split.
+3. **otherwise `docs/evidence/`** — the default for a project that has neither.
+
+**Carrying a register is the whole difference between a root and a directory.** A
+project may keep an unrelated `docs/evidence/` full of compliance material; adopting it
+because the name matched would write a run's paperwork into somebody else's folder. When
+the default lands on a directory like that, the resolver says so and the caller asks
+rather than writing.
+
+**`docs/superpowers/` is the name this pipeline used until 2026-08-13, and it is
+supported, not deprecated.** A project already on it keeps it — forever, with no
+warning on any run. The name was inherited from an unrelated pack whose own tests walk
+the same path; it was never a dependency on that pack, and renaming the default is what
+finally says so. Nothing migrates on its own: `npx task-pipeline migrate-artifacts`
+moves a project that wants to move, `--dry-run` first, and a project that never runs it
+is not behind.
+
+Implementations: `bin/lib/artifact-root.js` (shipped) and `test/artifact_root.py` (the
+validator). `test/artifact_root_test.py` runs both against one case table and fails when
+they disagree — which is why one rule is allowed two implementations here.
 
 **Every** run keeps a **git-ignored** run ledger at `.task-pipeline/run.md`, seeded at
 stage 0 from [`../templates/run.md`](../templates/run.md). Three line shapes: a
@@ -84,7 +113,7 @@ whatever the context happens to hold.
 
 | Stage | Reads | From where |
 |---|---|---|
-| **0 Harvest** | the project's own knowledge about this task | code · the code graph (`graphify-out/`) · `CLAUDE.md`/`AGENTS.md` · `CONTEXT.md`/`docs/adr/` · `docs/` + `docs/ux/` · past briefs and carry-over ledgers · **the board** (`docs/superpowers/backlog.md`, open count quoted in the brief) · **the verification ledger** (`docs/superpowers/verification.md`, how many rows sit at `never`) · the retro's standing instructions **in full** · the wiki · any doc repo or hosted system the project names |
+| **0 Harvest** | the project's own knowledge about this task | code · the code graph (`graphify-out/`) · `CLAUDE.md`/`AGENTS.md` · `CONTEXT.md`/`docs/adr/` · `docs/` + `docs/ux/` · past briefs and carry-over ledgers · **the board** (`<artifacts>/backlog.md`, open count quoted in the brief) · **the verification ledger** (`<artifacts>/verification.md`, how many rows sit at `never`) · the retro's standing instructions **in full** · the wiki · any doc repo or hosted system the project names |
 | **0 Inventory (1b)** | the documentation regime | `docs/DOCMAP.md` — registers, single homes, propagation matrix, gate commands, ratchet floors. Absent ⇒ seeded ([`adoption.md`](adoption.md)) |
 | **0 Reconcile (1c)** | intent vs as-built | git (how it *should* be) against the run record (how it *turned out*) |
 | **0 Grill** | the operator | the interview — every answer checked against the harvest, which is what makes it checkable rather than confident |
@@ -108,9 +137,9 @@ that has not read them is running the pipeline's defaults, not this project's.
 |---|---|---|---|
 | `CLAUDE.md` / `AGENTS.md` | commands, deploy path, house rules, which docs exist and where | 0 | 6–10 |
 | `docs/DOCMAP.md` | the decision home, each fact's single home, the propagation matrix, the gate and its ratchet floors | 0 (1b) | 9 |
-| `docs/superpowers/verification.md` | one row per shipped REQ, and the one column a machine may not fill: the date a **human** confirmed it, or `never` ([`verification.md`](verification.md)) | 0 | written at 8, required at 10 |
-| `docs/superpowers/backlog.md` | the project's work-list **between** runs — ids, the three priority inputs, state. Mutable; rows leave only into its *Closed* list ([`backlog.md`](backlog.md)) | 0 | re-derived at every iteration's end; resolved at 10 |
-| `docs/superpowers/retro.md` | standing instructions — the rules no check can decide. Capped at ten, **read in full**, stamped the moment one fires | 0 | pruned at 10 |
+| `<artifacts>/verification.md` | one row per shipped REQ, and the one column a machine may not fill: the date a **human** confirmed it, or `never` ([`verification.md`](verification.md)) | 0 | written at 8, required at 10 |
+| `<artifacts>/backlog.md` | the project's work-list **between** runs — ids, the three priority inputs, state. Mutable; rows leave only into its *Closed* list ([`backlog.md`](backlog.md)) | 0 | re-derived at every iteration's end; resolved at 10 |
+| `<artifacts>/retro.md` | standing instructions — the rules no check can decide. Capped at ten, **read in full**, stamped the moment one fires | 0 | pruned at 10 |
 | `specs/<topic>-brief.md` → *Autonomy* | every pre-resolved decision; stages 1→10 **answer from it instead of asking** | 0 | 1–10 |
 | `specs/<topic>-carryover.md` | everything deferred, parked or half-done; appended the moment it is said | all | read in full at 10 |
 | `docs/ux/scenarios.md` | the source of truth for user-facing behaviour (super-ux) | 3 | 3, 7, 9, 10 |
@@ -130,13 +159,13 @@ them is a finding, not a tie-break ([`knowledge-sources.md`](knowledge-sources.m
 | 0 Intake | `specs/<topic>-brief.md` — incl. the **REQ table** (seed from `templates/brief.md`) | stages 2–5, 7, 10 |
 | 0→10 all | `specs/<topic>-carryover.md` — append-only ledger (seed from `templates/carryover.md`) | stage 10, in full |
 | 10 Acceptance | `specs/<topic>-acceptance.md` — every REQ with a status and evidence | the operator |
-| 10 Retro | `superpowers/retro.md` — standing instructions (max 10), the problem→cause→fix log, run stamps. Pruned **before** anything is added (`retrospective.md`) | **stage 0 of the next run**, in full |
+| 10 Retro | `<artifacts>/retro.md` — standing instructions (max 10), the problem→cause→fix log, run stamps. Pruned **before** anything is added (`retrospective.md`) | **stage 0 of the next run**, in full |
 | 0 Inventory | `docs/DOCMAP.md` + the registers + `scripts/check-docs.sh` — seeded **only when absent**, and the seeding is the register's first entry ([`documentation.md`](documentation.md)) | every later stage; **stage 9** walks the matrix, **stage 10** proves the gate |
 | 0 Grill (domain) | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md` — created **lazily**, only when a term resolves or a decision qualifies. Where `docs/adr/` **is** the register, entries carry the register's field set | stages 2–4 + the repo |
 | any stage | a register entry per settled thing, via the **Doc Loop** — recorded, resolved, propagated, committed with its id | the next run's harvest |
-| 8 Verification row | `docs/superpowers/verification.md` — one row per REQ the run shipped, written right after the deploy verification; `Human` starts at `never` ([`verification.md`](verification.md)) | stage 10 requires it; stage 0 of every later run reads it |
-| 10 Board resolution | `docs/superpowers/backlog.md` — every unresolved ledger row — homed `backlog` or still `open` — arrives with a real id, and the ledger row is updated to name it; priority re-derived ([`backlog.md`](backlog.md)) | the next run's harvest, and every loop iteration |
-| 10 Retro rotation | `docs/superpowers/retro/YYYY-QN.md` — entries older than five stamps, plus every retirement, each with its commit | queried by a later run's harvest |
+| 8 Verification row | `<artifacts>/verification.md` — one row per REQ the run shipped, written right after the deploy verification; `Human` starts at `never` ([`verification.md`](verification.md)) | stage 10 requires it; stage 0 of every later run reads it |
+| 10 Board resolution | `<artifacts>/backlog.md` — every unresolved ledger row — homed `backlog` or still `open` — arrives with a real id, and the ledger row is updated to name it; priority re-derived ([`backlog.md`](backlog.md)) | the next run's harvest, and every loop iteration |
+| 10 Retro rotation | `<artifacts>/retro/YYYY-QN.md` — entries older than five stamps, plus every retirement, each with its commit | queried by a later run's harvest |
 | 2 Decompose | `specs/<topic>-modules.md` — module map, build order, contracts, per-module status (platforms only) | stages 3–10, every module's run |
 | 3 Spec | `specs/<topic>-design.md` — module dossier for a decomposed platform (+ links `docs/ux/*` for UI) | stage 4 |
 | 4 Plan | `plans/<topic>.md` | stage 5 |
@@ -180,5 +209,5 @@ test/validate.py                              # structural validator (npm test)
 package.json  .gitignore
 README.md  CHANGELOG.md  LICENSE  CLAUDE.md
 CONTRIBUTING.md  SECURITY.md  CODE_OF_CONDUCT.md
-docs/superpowers/{specs,plans}/               # this repo's own design history
+<artifacts>/{specs,plans}/               # this repo's own design history
 ```

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

@@ -47,7 +47,7 @@ pass in each direction finds both.
 
 ## Seeded or picked up
 
-Stage 0's harvest reads `docs/superpowers/backlog.md` when it exists — it is a source
+Stage 0's harvest reads `<artifacts>/backlog.md` when it exists — it is a source
 in the ledger like any other, and its **open count is quoted in the brief**, because a
 run that begins without knowing what is already queued will cheerfully re-discover it.
 

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

@@ -198,7 +198,7 @@ works a stale board for as long as the loop runs. One command, at the top of the
 iteration, recorded ([`knowledge-sources.md`](knowledge-sources.md) → *Carried-in
 claims*; [`learned.md`](learned.md) rule 16).
 
-**The work-list is `docs/superpowers/backlog.md`** ([`backlog.md`](backlog.md)), and the
+**The work-list is `<artifacts>/backlog.md`** ([`backlog.md`](backlog.md)), and the
 other half of the same measurement is the exposure line ([`exposure.md`](exposure.md)).
 Counted at the top of the iteration, re-derived at the bottom — `age` moves on its own,
 so the re-derivation is the only moment the board stops being stale.

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

@@ -65,7 +65,7 @@ into its neighbor or move the disputed data to the module that truly owns it.
 
 ## The module map — the artifact
 
-Write `docs/superpowers/specs/YYYY-MM-DD-<topic>-modules.md` and commit it. It is
+Write `<artifacts>/specs/YYYY-MM-DD-<topic>-modules.md` and commit it. It is
 the program's spine: every later run reads it, and its status column is how a
 resumed session knows where the program stopped.
 

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

@@ -160,7 +160,7 @@ explicit "stop and ask me here":
 | 7 Lint+deploy | lint command; deploy target and path; release automation on/off; deploy-from-main rule; **deploy authorization** |
 | 8 Post-deploy | where logs / health live (app name, endpoint, workflow) |
 | 9 Docs+wiki | which module docs / runbooks this change updates; wiki sync yes/no; **code-graph refresh yes/no** (`/graphify . --update` — the third close-out artifact) |
-| 10 Acceptance | who signs off; where deferred REQs are tracked (issue tracker, backlog); the **retro file** — does `docs/superpowers/retro.md` exist, and are its standing instructions in force for this run ([`retrospective.md`](retrospective.md)) |
+| 10 Acceptance | who signs off; where deferred REQs are tracked (issue tracker, backlog); the **retro file** — does `<artifacts>/retro.md` exist, and are its standing instructions in force for this run ([`retrospective.md`](retrospective.md)) |
 
 **Deploy authorization has a hard floor.** Deploy and publish are outward and
 irreversible, so a vague "just do everything" authorizes nothing. A standing
@@ -254,7 +254,7 @@ that shrank without anyone deciding it should.
 
 Everything resolved goes into the **task brief**, seeded from
 [`templates/brief.md`](../templates/brief.md) and committed to
-`docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` — scope, **the REQ table**,
+`<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` — scope, **the REQ table**,
 **the phase-1 source ledger**, users, UI verdict, constraints, locked decisions,
 the autonomy table, done-criteria, open assumptions. Seed the template only when
 the file is absent; never overwrite an existing brief.

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

@@ -47,9 +47,9 @@ makes the grill's answers *checkable* instead of merely confident.
 | 4a | **The decision register and the doc map** | `docs/DECISIONS.md` **or** `docs/adr/` — `docs/DOCMAP.md` says which ([`documentation.md`](documentation.md)) | what is already settled, what it superseded, and which documents this run will owe |
 | 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** | `docs/superpowers/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
-| 7 | **The retro, in force** | `docs/superpowers/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 |
-| 7a | **The retro archive** | `docs/superpowers/retro/YYYY-QN.md` | *have we been bitten by this class before?* — **queried** by the task's nouns, never read end to end |
+| 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 |
+| 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 |
 | 10 | **Hosted doc systems the project names** | Notion / Confluence / Google Docs referenced in the project | the same, when the team keeps them there |
@@ -73,7 +73,7 @@ Rules for the list:
 
 ## The retro's standing instructions — an instruction source, not background
 
-`docs/superpowers/retro.md` ([`retrospective.md`](retrospective.md)) is the one
+`<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) is the one
 harvested source whose binding part is **read in full rather than queried**: the
 standing instructions are capped at ten precisely so that this is cheap, and the run
 stamps are one line each. Its narrative log is queried, not read — an uncapped section