task-pipeline-skill 1.4.4 → 1.6.0

package/CHANGELOG.md

@@ -1,11 +1,114 @@
 # Changelog
 
-## v1.4.4 — 2026-07-30
-
-### Added
-- **`displayName`** ("Task Pipeline") in both manifests — `name` stays kebab-case
-  because it namespaces components; the picker shows this instead.
-
+## v1.6.0 — 2026-08-01
+
+### `references/retrospective.md` — the run teaches the next run, and the list stays short
+
+Every gate in this flow is good at *this* run and blind across runs. So a class of
+failure gets caught, fixed and forgotten five times, and nothing in the pipeline
+notices it is the same one. The ladder walk finds what was never written **inside** a
+run; nothing was looking across them.
+
+Stage 10 now ends with a **retrospective** written to `docs/superpowers/retro.md` —
+**one file per project, not per run**, seeded from the new `templates/retro.md`.
+Every run prunes and stamps; only a run that *diverged* writes an entry, and the
+entry names the stage that **owned** the failure rather than the stage that tripped
+over it — recording it against the latter is how the same defect comes back.
+
+**Fixes have three grades, and the highest one that works is the one you take:** a
+mechanical check (a test, a lint rule, a gate criterion — the check *is* the memory,
+so nothing has to be remembered or pruned later), a **standing instruction** for
+what no check can decide, or a note that expires in two runs.
+
+**The part that makes it survive: the prune is mandatory and runs before anything is
+added.** Every standing instruction is checked against three retirement triggers —
+it became a check · every path or command it names is gone · it has not fired in the
+last five run stamps — and the list is held to a **hard cap of ten**. At eleven, the
+oldest never-fired rule goes. "But they all matter" is precisely the state in which
+the list stopped being read, and the ninth stale rule is what discredits the two that
+are load-bearing.
+
+Nothing leaves silently: **every retirement writes one line in the log**, so the
+incident survives and only the instruction goes. The counts print beside the gate
+verdict like the carry-over ledger's, so a list that quietly grew back is visible
+where it happened.
+
+Stage 0 reads the standing instructions **in full** (they are capped, so it is
+cheap) and stamps each one as it fires — which is the only evidence behind the
+cold-retirement rule. Without that stamp the prune is a mood.
+
+Three new guards, each with its negative self-test: the retro must reach the
+surfaces that *enforce* stage 10 — not just `SKILL.md`; the template must ship; and
+its standing-instruction table must carry a **Retire when** column and the run
+stamps. A retirement trigger written at birth is what makes the prune mechanical
+instead of an argument every time.
+
+### Also in this release — what an audit of the two features found
+
+Both features were then walked against the tools they name, which is the only way
+this class of defect surfaces:
+
+- **The refresh command was wrong, in thirteen files.** `graphify . --update` was
+  documented as a shell command. Run, it does not do what the text claims: the CLI's
+  incremental form is `graphify update <path>` and it re-extracts **code only**,
+  while `/graphify . --update` is the *agent* form that also re-reads the documents.
+  Stage 9 is the stage that just changed the documents, so the shortcut would have
+  produced the most expensive kind of stale graph — one that was refreshed. Both
+  forms are now documented with the distinction spelled out, and the doctrine says
+  which is the default and why.
+- **Three stages pointed at doctrine that does not exist.** In the example config a
+  `task-pipeline:<name>` entry *is* the built-in doctrine file `references/<name>.md`
+  — and `knowledge-harvest`, `decompose` and `plan` resolved to nothing. It read as
+  covered on every review. Fixed, and now a **guard** resolves every such entry
+  (33 guards total, all provable locally).
+- **The retro is a seeded file, and the templates README said only the brief was.**
+  The seeding rule matters most there: overwriting `retro.md` with the skeleton
+  destroys every lesson the project has bought. Stated explicitly.
+- **The harvest source list is renumbered** (the retro's standing instructions are
+  source 7, read *in full* rather than queried) and the graph doctrine now says
+  plainly that `affected`/`path` are sharp on a code repo and near-useless on a prose
+  one — an empty traversal there is not evidence of no coupling.
+
+## v1.5.0 — 2026-08-01
+
+### `references/knowledge-graph.md` — the code graph as a source, and as a second opinion
+
+A grep finds a **name**. The questions that actually stop a run are *what calls this*
+and *what breaks if it moves* — **reach** — and reach is exactly what a document
+records least reliably, because it records the reach its author remembered. The
+harvest had no way to ask that question, so it asked the operator, whose answer
+nobody could check.
+
+So the pipeline now uses a code graph where one exists
+([graphify](https://github.com/Graphify-Labs/graphify) — detected via
+`graphify-out/graph.json`; recommended, never a gate, exactly like the wiki, with its
+install line printed once in the preflight block).
+
+**Stage 0** queries it before the interview (`graphify query` / `affected` /
+`god-nodes`) and records it in the source ledger **with its build date** — a graph
+goes stale like any other source, and it points while the code decides.
+
+**Stage 9 now closes three artifacts, not two:** docs, wiki, **and the graph**
+(`/graphify . --update`). The reason it is a peer rather than an afterthought is
+asymmetric: the next run's harvest queries the graph *first*, so a stale graph is a
+false premise delivered with the authority of a machine. A wrong doc gets argued
+with; a wrong graph gets believed.
+
+**And then the part that finds things: the graph↔docs divergence check.** Two
+independent statements of the same system, so a disagreement is mechanical instead of
+remembered — a hub `god-nodes` reports that no document names is an undocumented
+seam; an edge the docs deny is either a leak in the code or a lie in the docs; a doc
+naming a module the graph has no node for describes something that no longer exists.
+Doc-side findings are fixed at stage 9; **absences become REQ rows at stage 10**,
+because this is a fourth audit axis (`references/audit.md`) and the only one that
+finds an absence without reading for it. The graph is derived, so it is never
+hand-edited: fix the code or the doc and re-extract.
+
+Two new guards, both with negative self-tests: a
+shipped graph doctrine must reach the **stage-9 gate** in `pipeline.example.json`
+*and* the stage-9 section of `references/stages.md`. That is the third time this repo
+has shipped a rule to `SKILL.md` and not to the surface that enforces it — a gate
+declared where it is not enforced is inert.
 ## v1.4.3 — 2026-07-30
 
 ### Fixed

package/README.md

@@ -67,8 +67,8 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
 | 6 | Tests | full suite green, new code covered | auto |
 | 7 | Lint + deploy | lint clean + suite green before deploy | manual |
 | 8 | Post-deploy | clean boot / honest degradation | auto |
-| 9 | Docs + wiki | every stale source-ledger row updated; docs + wiki synced | auto |
-| 10 | **Acceptance** | every REQ accounted for with evidence; operator signs off | manual |
+| 9 | Docs + wiki | every stale source-ledger row updated; docs + wiki synced; the code graph refreshed and checked against the docs | auto |
+| 10 | **Acceptance** | every REQ accounted for with evidence; operator signs off; the retro written — pruned before anything was added | manual |
 
 ## What you get
 
@@ -84,6 +84,10 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
   wiki entry — produced as part of the work, not promised for later.
 - **It adapts to your repo, not the reverse.** Deploy, docs and wiki conventions
   are read from the host project, so nothing is imposed.
+- **It gets better at your project, without getting longer.** Each run ends with a
+  retrospective, and the next run reads it — but the standing-instruction list is
+  capped at ten and pruned *before* anything is added, so what you inherit is the
+  rules that still fire, not an archive.
 
 ## Quickstart
 
@@ -163,7 +167,8 @@ Stage 0 doesn't open with a question. It opens by finding what the project alrea
 knows about this task
 ([`knowledge-sources.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md)):
 the code, `CLAUDE.md`, `CONTEXT.md` and the ADRs, `docs/` and `docs/ux/`, previous
-pipeline briefs and their carry-over ledgers, **the knowledge wiki if you have one**,
+pipeline briefs and their carry-over ledgers, **the retro's standing instructions**
+(read in full — they bind the run; see below), **the knowledge wiki if you have one**,
 and **any other repository or hosted doc system your project names as its docs**. It's
 retrieval scoped by the task's own nouns, not a read of everything, and it ends with a
 **source ledger** written into the brief — one row per source, what it says, how
@@ -199,6 +204,70 @@ obsidian-wiki setup --vault /path/to/your/vault
 It is a **recommendation, never a gate** — no stage blocks on a missing wiki, and
 nothing asks twice in one run.
 
+### The code graph — reach, and a second opinion on your docs
+
+A grep finds a **name**. A graph finds **reach**: what actually calls this, what
+breaks if it moves, what every change passes through. That is the question stage 0
+needs answered before it asks you anything, and the one documents answer least
+reliably — a document records the reach its author remembered.
+
+So where a code graph exists, the pipeline uses it
+([`knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md)).
+The tool is **[graphify](https://github.com/Graphify-Labs/graphify)**; detected via
+`graphify-out/graph.json`. Not installed → recommended once, in the preflight block,
+with the lines — then the run continues:
+
+```bash
+uv tool install graphifyy      # the CLI
+graphify install               # add the /graphify skill to this agent
+```
+
+then, in the project root:
+
+```
+/graphify .
+```
+
+**Stage 0 asks it what grep can't** — `graphify query "how does session reach the
+API layer"`, `graphify affected "AuthModule"`, `graphify god-nodes` — and records it
+in the source ledger **with its build date**, because a graph goes stale exactly like
+a doc. It points; the code decides.
+
+**Stage 9 closes three artifacts, not two.** Docs, wiki, **and the graph** — in the
+agent, so the documents this stage just edited are re-extracted too:
+
+```
+/graphify . --update
+```
+
+There is a CLI shortcut, `graphify update .`, which is structural, model-free and
+**code-only** — the wrong default at the one stage whose job was changing the docs,
+because it produces the most expensive kind of stale graph: one that was refreshed.
+And the reason the graph is a peer of the docs rather than an afterthought: the
+*next* run's harvest queries it first, so a stale graph is a false premise delivered
+with the authority of a machine. A wrong doc gets argued with. A wrong graph gets
+believed.
+
+**Then the divergence check — two independent statements of the same system.** This
+is the part a doc linter cannot do, because it compares your docs against the code's
+actual shape rather than against itself:
+
+| Ask the graph | A disagreement means |
+|---|---|
+| `graphify god-nodes` | a hub **no document names** — an undocumented seam: the thing every change passes through and nothing explains |
+| `graphify path "A" "B"` | an edge the docs **deny** — either a leak in the code or a lie in the docs, and which one is a decision, not a guess |
+| `graphify affected "X"` | callers the docs never mention — the documented blast radius is smaller than the real one |
+| a doc naming a module the graph has **no node for** | the doc describes something that no longer exists |
+
+Doc-side findings are fixed at stage 9. Absences go to stage 10's ladder walk and
+become **REQ rows with their checks** — the graph is the fourth audit axis, and the
+only one that finds an absence without reading for it. The graph is *derived*, so it
+is never hand-edited and `graphify-out/` is git-ignored by default: you fix the code
+or the doc and re-extract.
+
+Cadence: refresh every close-out, sweep periodically (stage 10, or when another axis
+goes quiet). Like the wiki, it is a **recommendation, never a gate**.
+
 ### The REQ spine — why nothing falls out the back
 
 Every gate before the last one asks *"is this artifact good?"* — none asks *"does
@@ -338,6 +407,50 @@ fail, you don't know it tests the right thing* — raised from one test to every
 gate, linter and script in the run. **A green result from an unproven check is
 worth nothing.**
 
+### The retrospective — the run teaches the next run, and the list stays short
+
+Every gate in this flow is good at *this* run and blind across runs. So the same
+class of failure gets caught, fixed and forgotten five times, and nothing in the
+pipeline notices it is the same one.
+
+The last act of stage 10 is therefore a **retrospective**, written to
+`docs/superpowers/retro.md` — **one file per project, not per run**
+([`retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md)).
+Every run **prunes and stamps**; only a run that *diverged* writes an entry:
+symptom with evidence, the stage it surfaced at, the stage that **owned** it, the
+root cause, the fix, and the check that catches it the first time from now on.
+
+**Fixes come in three grades, and you take the highest one that works:**
+
+| Grade | What it is | What it costs later |
+|---|---|---|
+| 1 — mechanical | a test, a lint rule, a gate criterion, a hook | nothing: the check *is* the memory |
+| 2 — standing instruction | a rule agents read, for what no check can decide | one of ten slots, and its retirement trigger must be written at birth |
+| 3 — a note | something still being understood | expires in two runs, then it is promoted or deleted |
+
+**The prune is mandatory and runs before anything is added.** Every standing
+instruction is checked against three retirement triggers — *it became a check* ·
+*every path or command it names is gone* · *it has not fired in the last five run
+stamps* — and the list is held to a **hard cap of ten**. At eleven, the oldest
+never-fired rule goes; "but they all matter" is exactly the state in which the list
+stopped being read, and the ninth stale rule is what discredits the two that are
+load-bearing.
+
+Nothing is deleted silently: **every retirement writes one line in the log**, so
+the incident survives and only the instruction leaves. And the counts print beside
+the gate verdict, like the carry-over ledger's, so a list that quietly grew back is
+visible where it happened:
+
+```
+GATE 10 acceptance: PASS — 14/14 REQ verified
+  carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
+```
+
+Stage 0 reads those standing instructions **in full** on the next run — which is
+the whole reason the cap exists and the prune is a gate criterion instead of a good
+intention. A rule nobody reads to the end is worse than no rule: everyone believes
+it is covered.
+
 ### UX track (user-facing tasks) — super-ux recommended
 
 The moment a task touches any user-facing surface (web / mobile / CLI / TUI — a
@@ -517,13 +630,14 @@ the same Claude Code install yields a duplicate, shadowing skill.
 ### Prerequisites
 
 **None for the pipeline itself** — the doctrine for every stage ships inside the
-skill. Three optional companions make individual stages better:
+skill. Four optional companions make individual stages better:
 
 | Companion | For | Required? |
 |---|---|---|
 | [super-ux](https://github.com/ssheleg/super-ux) | the stage-3 UX track | only for user-facing tasks |
 | context7 (MCP) | stage-1 docs study | recommended — web-search fallback |
 | [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) | stage-0 harvest + stage-9 sync | recommended — never a gate |
+| [graphify](https://github.com/Graphify-Labs/graphify) | stage-0 reach queries + stage-9 refresh + the graph↔docs divergence check | recommended — never a gate |
 
 A single preflight block prints which are ready, which to install, and the model
 recommendation, so you arm the whole run in one exchange. Detail:
@@ -539,6 +653,8 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/stages.md`](plugins/task-pipeline/skills/task-pipeline/references/stages.md) | per-stage detail and the exact gate criteria |
 | [`references/artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md) | the canonical document layout each stage writes to |
 | [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md` |
+| [`references/knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md) | the code graph: install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check |
+| [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
 | [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons |
 | [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |

package/cursor/rules/task-pipeline.mdc

@@ -31,7 +31,11 @@ task was already clear" exemption, no starting stage 1 while the user thinks. A
 one-line task ("build feature X") is not enough to finish autonomously.
 
 **Phase 1 — harvest the sources BEFORE the first question.** Find what the project
-already knows about this task and read it: the code; `CLAUDE.md` / `AGENTS.md`;
+already knows about this task and read it: the code; **the code graph if one is
+built** — [graphify](https://github.com/Graphify-Labs/graphify), detect
+`graphify-out/graph.json`, and ask it what grep cannot (`graphify query "<the task,
+as a question>"`, `graphify affected "<what is changing>"`, `graphify god-nodes`);
+`CLAUDE.md` / `AGENTS.md`;
 `CONTEXT.md` (or `CONTEXT-MAP.md`) and `docs/adr/`; `docs/` and `docs/ux/`; past
 briefs/plans and their carry-over ledgers; **the knowledge wiki if one is
 installed** — [obsidian-wiki](https://github.com/ar9av/obsidian-wiki), detect
@@ -40,10 +44,18 @@ or hosted doc system the project names as its docs** (read-only, and never a sou
 you invented — it counts because the project names it). Query each by *this task's*
 nouns; it is retrieval, not a full read; stop when the terms return nothing new.
 Write a short **source ledger** into the brief — source, what it says about this
-task, how fresh, and whether this run makes it stale. `none found` is a valid row.
+task, how fresh, and whether this run makes it stale. `none found` is a valid row;
+the graph's row carries its build date, because a graph goes stale like any other
+source, and it **points while the code decides** — never the tiebreaker.
+**Read `docs/superpowers/retro.md` in full if it exists** — its *standing
+instructions* are what previous runs of this pipeline got wrong in this project, and
+they bind this run (they are capped at ten, so reading them all is cheap). Stamp
+each one the moment it fires: that date is the only evidence behind the
+cold-retirement rule at stage 10.
 If no wiki is installed, recommend it once and continue:
-`pip install obsidian-wiki` → `obsidian-wiki setup --vault <path>`. It is never a
-gate.
+`pip install obsidian-wiki` → `obsidian-wiki setup --vault <path>`. If no graph is
+built, recommend it once and continue: `uv tool install graphifyy` →
+`graphify install` → `/graphify .`. Neither is ever a gate.
 
 **Phase 2 — grill the user against that harvest**, then run the rest without
 mid-flight questions:
@@ -172,7 +184,18 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     source the harvest read gets updated if this run changed or disproved it. Module
     docs and runbooks in the SAME change; the knowledge wiki via `wiki-update` when
     [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) is installed (absent →
-    recommend once, never block). Docs in **another repository** are outward:
+    recommend once, never block); **and the code graph via `/graphify . --update`**
+    when `graphify-out/` exists (absent → recommend once, never block). The close-out
+    has **three** artifacts, not two — the graph is what the *next* run's harvest
+    queries first, so a stale one is a false premise carrying the authority of a
+    machine: a wrong doc gets argued with, a wrong graph gets believed.
+    **Then check the graph against the docs:** a hub `graphify god-nodes` reports
+    that no document names is an undocumented seam; an edge the docs deny is either a
+    leak in the code or a lie in the docs; a doc naming a module the graph has no
+    node for describes something that no longer exists. Fix the doc-side findings
+    here; hand absences to stage 10's ladder walk as REQ rows. Never "fix" the graph
+    by hand — it is derived: fix the code or the doc and re-extract.
+    Docs in **another repository** are outward:
     propose the edit and get an explicit go, or carry it over with the exact change
     written down. A doc that was worth reading at stage 0 and is wrong now is the
     next run's false premise.
@@ -223,8 +246,37 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     `git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD --oneline`.
     The fix is two commands and the second is the one that gets forgotten:
     `git -C <submodule> push`, then `git add <submodule> && git commit`.
+    **The last act is the retrospective** — `docs/superpowers/retro.md`, **one file
+    per project, not per run**. Every gate above is good at *this* run and blind
+    across runs: the same class of failure gets caught, fixed and forgotten five
+    times and nothing notices it is the same one. So, in this order —
+    **1. Prune before you add.** Check every standing instruction against three
+    retirement triggers: it became a check (a test, a lint rule, a gate, a hook →
+    delete it; the check is the memory, and keeping both means it is read twice and
+    obeyed once); every path, command or stage it names is gone (→ delete, it
+    describes a system nobody runs); it has not fired in the last **five run
+    stamps** (→ delete, that is the evidence it was situational). Then the cap:
+    **ten standing instructions, hard** — at eleven the oldest never-fired row goes,
+    because "they all matter" is exactly the state in which the list stopped being
+    read. **Every deletion writes one line in the log; silent deletion is
+    forbidden** — the record stays, the instruction leaves.
+    **2. Stamp the run** — date, topic, verdict, counts. That stamp is what makes
+    "five runs" countable.
+    **3. Write an entry, only if the run diverged** — symptom with evidence, the
+    stage it *surfaced at*, the stage that **owned** it (usually earlier — a finding
+    recorded against the stage that tripped over it comes back), the root cause
+    ("the agent was careless" is not a cause, it is the absence of 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 lesson true in any repository belongs upstream in
+    the skill's own doctrine, not in one project's file.
+    A retro left empty after a messy run is the failure it exists to stop. Phase 1
+    of the next run reads those standing instructions **in full**, which is why the
+    cap is not negotiable and the prune is a gate item, not a good intention.
     Gate: ladder walk ran, no REQ `unknown`, no ledger row without
-    a home, every repository clean/pushed/pointed-at, user signs off.
+    a home, every repository clean/pushed/pointed-at, user signs off, **and the
+    retro is written — pruned before anything was added, at or under its cap, every
+    deletion logged, the run stamped, and the counts printed beside this verdict**.
 
 Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step
@@ -262,7 +314,10 @@ its own previous pass while the finding count still looked healthy. So:
   **rotate the axis, don't look harder.** The axes are orthogonal by construction —
   seams down one deliverable (the ladder above), then invariants *across*
   deliverables (one name, one enum, one owner everywhere), then one class swept end
-  to end (every error path, every count, every status vocabulary).
+  to end (every error path, every count, every status vocabulary), then — where a
+  code graph exists — **the graph against the docs**, the only axis that finds an
+  absence without reading for it (a hub no document names, an edge the docs deny, a
+  doc naming a module the graph no longer has).
 - **Audit bottom-up.** A missing artefact at a low rung makes everything above it
   meaningless; top-down you polish a surface for a contract that doesn't exist.
 - **A class that repeats twice becomes a check, not a note.** Once is an incident;

package/package.json

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

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

@@ -1,8 +1,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 must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.4.4",
+  "version": "1.6.0",
   "author": {
     "name": "ssheleg"
   },

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

@@ -5,11 +5,17 @@ argument-hint: "<one-line task description>"
 Use the `task-pipeline` skill to run the task below through all gated stages —
 **stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent
 build → tests → lint/deploy → post-deploy → docs/wiki → **acceptance**. **Every stage's doctrine is
-built into the skill** (`references/{knowledge-sources,grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,loop-guard}.md`)
+built into the skill** (`references/{knowledge-sources,knowledge-graph,grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,retrospective,loop-guard}.md`)
 — no companion plugin is required for any of them. **Stage 0 opens with the
 knowledge harvest, before the first question** (`references/knowledge-sources.md`):
-pull what the project already knows about this task from the code, `CLAUDE.md`,
-`CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the **knowledge wiki**
+pull what the project already knows about this task from the code, **the code graph**
+if one is built ([graphify](https://github.com/Graphify-Labs/graphify) —
+`references/knowledge-graph.md`; recommended, never required; detect
+`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 pipeline briefs, **the retro's standing
+instructions** (`docs/superpowers/retro.md` — read in full, they bind this run;
+`references/retrospective.md`), the **knowledge wiki**
 if one is installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) —
 recommended, never required; detect `~/.obsidian-wiki/config`) and any **other repo
 or hosted doc system the project names as its docs**, then write the **source
@@ -22,10 +28,10 @@ only out loud, and a doc the run proves stale is logged for the stage-9 update
 applying the
 grill's **domain awareness** (challenge terms against `CONTEXT.md`, sharpen fuzzy
 language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (what
-would otherwise stop stages 1→10: docs sources incl. doc repos and the wiki, branch/tracker
-policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets, and for UI tasks whether the design is done visually in Figma or text-only, whether the Figma MCP is connected, and — if it isn't — whether to ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; **and 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 explicitly authorized, written into the project's canonical record before the first frame, because a destination decided at drawing time is how a project ends up with three design files and no way to tell which is real. **Never create while a recorded file resolves; if it doesn't resolve, stop and ask — never create a replacement**) —
+would otherwise stop stages 1→10: docs sources incl. doc repos, the wiki and the code graph, branch/tracker
+policy, test and lint commands, deploy target and authorization, log locations, docs/wiki/graph targets, and for UI tasks whether the design is done visually in Figma or text-only, whether the Figma MCP is connected, and — if it isn't — whether to ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; **and 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 explicitly authorized, written into the project's canonical record before the first frame, because a destination decided at drawing time is how a project ends up with three design files and no way to tell which is real. **Never create while a recorded file resolves; if it doesn't resolve, stop and ask — never create a replacement**) —
 until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
-**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. **In a project of several repositories, stage 10 closes on the parent too:** a parent records each submodule as a pointer to one commit, and moving the submodule does not move the pointer — so the work can be committed, pushed and green while a clone of the parent still gets the commit before it. Neither repo looks wrong alone, which is why it survives every check that runs inside one. Require `git submodule status` with no line starting `+`, and every repo clean and pushed (`git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD`). The fix is two commands and the second gets forgotten: push the submodule, then `git add <submodule> && git commit`. Honor every stage gate by its type (`auto` = verify yourself;
+**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. **The docs stage closes three artifacts, not two:** module docs, the wiki, **and the code graph** (`/graphify . --update` where `graphify-out/` exists — `references/knowledge-graph.md`), because the graph is what the next run's harvest queries first and a stale one is a false premise carrying the authority of a machine. Then check the graph against the docs: a hub `graphify god-nodes` reports that no document names is an undocumented seam; an edge the docs deny is a leak in the code or a lie in the docs; a doc naming a module the graph no longer has is stale. Doc-side findings are fixed there, absences become REQ rows in the closing stage. **In a project of several repositories, stage 10 closes on the parent too:** a parent records each submodule as a pointer to one commit, and moving the submodule does not move the pointer — so the work can be committed, pushed and green while a clone of the parent still gets the commit before it. Neither repo looks wrong alone, which is why it survives every check that runs inside one. Require `git submodule status` with no line starting `+`, and every repo clean and pushed (`git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD`). The fix is two commands and the second gets forgotten: push the submodule, then `git add <submodule> && git commit`. **The run's last act is the retrospective** (`references/retrospective.md` → `docs/superpowers/retro.md`, one file per project): **prune before you add** — every standing instruction against its three retirement triggers (it became a check; the paths/commands it names are gone; it hasn't fired in five run stamps), the list held to a hard cap of ten, every deletion logged as one line and never silent — then stamp the run, 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 fix by grade (mechanical check > standing instruction > note that expires in two runs), and the check that catches it next time. Stage 0 reads those standing instructions in full, so the prune is a gate criterion, not a good intention: a rule nobody reads to the end is worse than no rule, because everyone believes it is covered. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —
 recommend the most capable one the environment offers, never a hardcoded id — then
 run the whole pipeline on it without re-asking.

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

@@ -43,6 +43,7 @@ and no stage that can fail because a dependency is missing:
 | Stage | Built-in doctrine |
 |---|---|
 | 0 Knowledge harvest (pre-grill) | [`references/knowledge-sources.md`](references/knowledge-sources.md) |
+| 0 + 9 The code graph (graphify — recommended, never required) | [`references/knowledge-graph.md`](references/knowledge-graph.md) |
 | 0 Intake grill | [`references/grill.md`](references/grill.md) |
 | 2 Brainstorm | [`references/brainstorm.md`](references/brainstorm.md) |
 | 2 Decompose (platforms only) | [`references/decomposition.md`](references/decomposition.md) |
@@ -51,6 +52,7 @@ and no stage that can fail because a dependency is missing:
 | 5 Build (worktree, subagents, fix loop) | [`references/build.md`](references/build.md) + [`references/review.md`](references/review.md) |
 | 5–6 TDD + suite gate | [`references/tdd.md`](references/tdd.md) |
 | 10 Acceptance (REQ close-out) | [`references/acceptance.md`](references/acceptance.md) |
+| 10 Retrospective (the run's last act) | [`references/retrospective.md`](references/retrospective.md) |
 | 10 + any audit (what's *missing*) | [`references/audit.md`](references/audit.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
 
@@ -95,9 +97,14 @@ for every one** — which is what turns the pipeline from a funnel into a circle
 
 **Harvest before you ask.** Stage 0 opens with a **knowledge harvest**
 ([`references/knowledge-sources.md`](references/knowledge-sources.md)), not a
-question: pull what the project already knows about this task from the code,
-`CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the
-**knowledge wiki** if one is installed
+question: pull what the project already knows about this task from the code, the
+**code graph** if one is built
+([`references/knowledge-graph.md`](references/knowledge-graph.md) — graphify;
+recommended, never required),
+`CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, **the
+retro's standing instructions** — `docs/superpowers/retro.md`, read in full because
+they *bind* this run ([`references/retrospective.md`](references/retrospective.md)) —
+the **knowledge wiki** if one is installed
 ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never
 required) and any **other repo or hosted doc system the project names as its
 docs**. Write the source ledger into the brief, then interview *against* it: every
@@ -105,6 +112,29 @@ answer that touches a source is checked against that source, and the operator
 outranks any document — but only out loud, so an override is a recorded decision
 instead of an undetected divergence. The same ledger is stage 9's work list.
 
+**Three artifacts close a run, not two.** Stage 9 syncs the docs, the wiki **and the
+code graph** (`/graphify . --update`) — the graph is what the *next* run's harvest
+queries first, so a stale one is a false premise carrying the authority of a
+machine. Refreshing it also buys the **graph↔docs divergence check**: a hub no
+document names, an edge the docs deny, a doc naming a module the graph no longer
+has. Doc-side findings are fixed at stage 9; absences become REQ rows at stage 10
+([`references/knowledge-graph.md`](references/knowledge-graph.md),
+[`references/audit.md`](references/audit.md)).
+
+**The run teaches the next run — and the list stays short.** Every gate is good at
+*this* run and blind across runs, so the same class of failure can be caught, fixed
+and forgotten five times with nothing noticing it is the same one. The last act of
+stage 10 is therefore the **retrospective**
+([`references/retrospective.md`](references/retrospective.md), written to
+`docs/superpowers/retro.md`): **prune first** — every standing instruction checked
+against its retirement triggers (it became a check · its surface is gone · it hasn't
+fired in five runs), the list held to a hard cap of **ten**, every deletion logged —
+then stamp the run, then write an entry **only if the run diverged** (symptom, the
+stage that *owned* it, root cause, fix, and the check that catches it next time).
+Stage 0 reads those standing instructions in full, which is exactly why the prune is
+a gate criterion and not a good intention: a rule nobody reads to the end is worse
+than no rule, because everyone believes it is covered.
+
 Three things the grill does beyond clarifying the request:
 - **Domain awareness.** It reads the project's own `CONTEXT.md` / `docs/adr/` and
   holds the operator to them — challenging terms that conflict with the glossary,
@@ -123,7 +153,7 @@ Three things the grill does beyond clarifying the request:
    with stage 0** (survives context loss; lets you resume). Then run the
    **companion preflight** (`references/companion-skills.md`): the stage doctrine
    is built in, so this only checks the *optional* companions (super-ux for UI
-   tasks, context7, wiki-update) and emits ONE block covering them
+   tasks, context7, wiki-update, graphify) and emits ONE block covering them
    **and the model decision** (`references/model-tiering.md`): recommend
    the most capable model available, let the operator confirm or override, record
    it. Ask once, here.
@@ -194,8 +224,8 @@ capable available — see `references/model-tiering.md`).
 | 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) + [`references/learned.md`](references/learned.md) | full suite green; new/changed code covered; **every new check probed both ways and asserted on its exit code**, and the suite run once against a cold environment | auto |
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
-| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced; **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)) | auto |
-| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); operator signs off | manual |
+| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) → `/graphify . --update` ([`references/knowledge-graph.md`](references/knowledge-graph.md), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced; **the code graph refreshed where one exists** and checked against the docs (a hub no doc names, a doc naming a node the graph lost); **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)) | auto |
+| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) → [`references/retrospective.md`](references/retrospective.md) (retro: prune, stamp, entry) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); operator signs off; **the retrospective written last — prune before entry, list at or under its cap, deletions logged, run stamped, counts printed** | manual |
 
 
 ### Stage 10 in a project of several repositories
@@ -256,8 +286,10 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `pipeline.schema.json` — the universal pipeline config contract (stages + release)
 - `pipeline.example.json` — this plugin's default flow (stage 0 + 1→10) + release, as config
 - `references/knowledge-sources.md` — stage-0 phase 1: the source list, the wiki, the ledger, the stage-9 loop-back
+- `references/knowledge-graph.md` — the code graph (graphify): install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
+- `references/retrospective.md` — stage 10's last act: the project retro (`docs/superpowers/retro.md`), the three grades of fix, the mandatory prune and its cap of ten
 - `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
 - `references/learned.md` — cross-cutting: fourteen rules earned by failure on a real multi-repository build, each with the incident behind it, its check and its exit criterion; plus the two that no check can decide
 - `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate