task-pipeline-skill 1.4.3 → 1.6.0

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

@@ -1,7 +1,7 @@
 {
   "$schema": "./pipeline.schema.json",
   "version": 1,
-  "_note": "EXAMPLE ONLY — copy this file, rename to pipeline.json in your project, and rewrite it. This particular example encodes the plugin's own default flow (an up-front intake grill + this skill's own built-in stage doctrine + a super-ux UX track for user-facing tasks); it is NOT a fixed contract. Reading skills[] in THIS example: a 'task-pipeline:<name>' entry is not an installable skill — it names this skill's own built-in doctrine file (references/<name>.md, e.g. task-pipeline:grill -> references/grill.md); a 'host:<name>' entry is the host project's own command for that job, resolved from its CLAUDE.md (see references/conventions.md); every other entry is a real skill/agent your environment resolves (super-ux:*, context7, wiki-query, wiki-update). In YOUR pipeline.json, put whatever names your environment actually resolves. Your project defines its own stages (any count), each executed by your own skills/agents, with your own gate types. Stage models use provider-agnostic tokens ('default' = the model confirmed for the run, 'inherit' = whatever the operator is on) — never hardcode a vendor model id, it goes stale. The universal contract is pipeline.schema.json; test/validate.py checks this example against it. gate.type: auto = orchestrator verifies the check itself (pass/fail); manual = wait for an explicit operator go. Which stages are manual vs auto is the operator's decision, not the plugin's. Any repeating loop in a run (fix loop, a re-entered stage, the per-module program loop) is bound by the loop guard: log every repeat touch, stop on oscillation, escalate to the layer that owns the conflict, then re-check in a planned order.",
+  "_note": "EXAMPLE ONLY — copy this file, rename to pipeline.json in your project, and rewrite it. This particular example encodes the plugin's own default flow (an up-front intake grill + this skill's own built-in stage doctrine + a super-ux UX track for user-facing tasks); it is NOT a fixed contract. Reading skills[] in THIS example: a 'task-pipeline:<name>' entry is not an installable skill — it names this skill's own built-in doctrine file (references/<name>.md, e.g. task-pipeline:grill -> references/grill.md); a 'host:<name>' entry is the host project's own command for that job, resolved from its CLAUDE.md (see references/conventions.md); every other entry is a real skill/agent your environment resolves (super-ux:*, context7, wiki-query, wiki-update, graphify). In YOUR pipeline.json, put whatever names your environment actually resolves. Your project defines its own stages (any count), each executed by your own skills/agents, with your own gate types. Stage models use provider-agnostic tokens ('default' = the model confirmed for the run, 'inherit' = whatever the operator is on) — never hardcode a vendor model id, it goes stale. The universal contract is pipeline.schema.json; test/validate.py checks this example against it. gate.type: auto = orchestrator verifies the check itself (pass/fail); manual = wait for an explicit operator go. Which stages are manual vs auto is the operator's decision, not the plugin's. Any repeating loop in a run (fix loop, a re-entered stage, the per-module program loop) is bound by the loop guard: log every repeat touch, stop on oscillation, escalate to the layer that owns the conflict, then re-check in a planned order.",
   "stages": [
     {
       "id": 0,
@@ -9,13 +9,15 @@
       "name": "Intake grill",
       "model": "default",
       "skills": [
-        "task-pipeline:knowledge-harvest",
+        "task-pipeline:knowledge-sources",
+        "task-pipeline:knowledge-graph",
         "wiki-query",
+        "graphify",
         "task-pipeline:grill"
       ],
       "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, CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, 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'). 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."
+        "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 build date, because a graph goes stale like any other source). 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."
       }
     },
     {
@@ -39,7 +41,7 @@
       "model": "default",
       "skills": [
         "task-pipeline:brainstorm",
-        "task-pipeline:decompose"
+        "task-pipeline:decomposition"
       ],
       "gate": {
         "type": "manual",
@@ -71,7 +73,7 @@
       "name": "Plan",
       "model": "default",
       "skills": [
-        "task-pipeline:plan"
+        "task-pipeline:planning"
       ],
       "gate": {
         "type": "auto",
@@ -140,11 +142,13 @@
       "model": "default",
       "skills": [
         "host:module-docs",
-        "wiki-update"
+        "wiki-update",
+        "task-pipeline:knowledge-graph",
+        "graphify"
       ],
       "gate": {
         "type": "auto",
-        "check": "the stage-0 source ledger is the work list — every source the harvest read is updated if this run changed or disproved it; docs in sync with code in the same change; wiki synced via wiki-update when obsidian-wiki is installed (absent → recommended once, never a blocker); docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed"
+        "check": "the stage-0 source ledger is the work list — every source the harvest read is updated if this run changed or disproved it; docs in sync with code in the same change; wiki synced via wiki-update when obsidian-wiki is installed (absent → recommended once, never a blocker); THE CODE GRAPH REFRESHED — '/graphify . --update' where graphify-out/ exists (references/knowledge-graph.md), or the reason it was skipped written into the carry-over ledger; absent → recommended once, never a blocker. 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. Then the cheap half of the GRAPH-VS-DOCS DIVERGENCE CHECK: 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, and a doc naming a module the graph has no node for describes something that no longer exists — doc-side findings fixed here, absences handed to stage 10's ladder walk as REQ rows. Docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed"
       }
     },
     {
@@ -154,11 +158,12 @@
       "model": "default",
       "skills": [
         "task-pipeline:audit",
-        "task-pipeline:acceptance"
+        "task-pipeline:acceptance",
+        "task-pipeline:retrospective"
       ],
       "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"
+        "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."
       }
     }
   ],
@@ -167,7 +172,7 @@
     "trigger": "tag",
     "steps": [
       "create a GitHub release from the matching CHANGELOG section",
-      "npm publish (task-pipeline-skill) — human 2FA step, not automated"
+      "npm publish (task-pipeline-skill) — a second job in the same workflow, armed per repository by the PUBLISH_NPMJS variable (NPM_TOKEN granular automation token, or trusted publishing via OIDC); unarmed it falls back to a human 2FA step"
     ],
     "verify": [
       "CI green on the tagged commit",

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

@@ -153,6 +153,32 @@ never captured, and this is the cheapest moment in the whole run to hear it. An
 answer here becomes new REQ rows or new ledger entries — not a new argument about
 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`.
+Every run **prunes and stamps**; only a run that *diverged* writes an entry.
+
+The order is fixed, because a lesson that lands in a cluttered file is a lesson
+nobody reaches:
+
+1. **Prune first.** Every standing instruction is checked against its three
+   retirement triggers — it became a check, its surface is gone, or it has not
+   fired in the last five run stamps — and the list is held to its cap of **ten**.
+   Every deletion writes one line in the log; silent deletion is forbidden.
+2. **Stamp the run** — one line: date, topic, verdict, retro counts.
+3. **Write the entry, if the run diverged** — symptom, the stage it surfaced at,
+   the stage that *owned* it, the root cause, the fix (mechanical > standing
+   instruction > note with an expiry), and the check that catches it next time.
+
+The counts are printed **beside this gate's verdict**, exactly like the carry-over
+ledger's, so a list that quietly grew back is visible at the moment it happened:
+
+```
+GATE 10 acceptance: PASS — 14/14 REQ verified
+  carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
+```
+
 ## GATE (manual)
 
 All of:
@@ -174,6 +200,11 @@ All of:
    shows no `+`, and each repo is clean and pushed. A submodule is finished when
    its parent points at it.
 9. **The operator answers the closing question** and signs off.
+10. **The retrospective is written** ([`retrospective.md`](retrospective.md)) — the
+    prune ran **before** anything was added (standing instructions checked against
+    their retirement triggers, the list at or under its cap of ten, every deletion
+    logged), the run is stamped, and a run that diverged has its entry with a root
+    cause and a named check. The counts are printed beside this verdict, not filed.
 
 Manual by design. An automated check can prove the table is *well-formed*; only
 the person who asked can confirm it is *what they asked for*. Do not let a green

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

@@ -13,6 +13,7 @@ docs/
   adr/
     NNNN-<slug>.md                    # stage 0 — ADRs for hard-to-reverse decisions
   superpowers/
+    retro.md                          # stage 10's last act — ONE per project, not per run
     specs/
       YYYY-MM-DD-<topic>-brief.md     # stage 0 — locked intake brief (grill output)
       YYYY-MM-DD-<topic>-carryover.md # stage 0 seeds it; EVERY stage appends; stage 10 reads it
@@ -29,6 +30,10 @@ docs/
     audits/YYYY-MM-DD-<scope>.md       # ux-audit reports
     plans/YYYY-MM-DD-<scope>.md        # super-ux fix plans (may hand off to this pipeline)
     lint.py, README.md                 # seeded by super-ux
+graphify-out/                          # git-ignored: the code graph, if one is built
+  graph.json                           # stage 0 queries it; stage 9 refreshes it
+  GRAPH_REPORT.md  graph.html          # the plain-language report + interactive view
+  manifest.json  cache/                # extraction bookkeeping — never edited by hand
 ```
 
 Naming: date-prefixed `YYYY-MM-DD-<topic>` slugs, one topic per file, kebab-case.
@@ -57,13 +62,14 @@ record (see `build.md`).
 | 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 |
 | 0 Grill (domain) | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md` — created **lazily**, only when a term resolves or a decision qualifies | stages 2–4 + the repo |
 | 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 |
 | 3 UX track | `docs/ux/{foundation,flows,screens,scenarios}.md` | stages 4–9 + `/ux-lint` |
 | 8 Post-deploy | log/health notes (in the run, not a committed file) | stage 9 |
-| 9 Docs+wiki | host module docs + wiki pages | — |
+| 9 Docs+wiki | host module docs + wiki pages + the refreshed `graphify-out/graph.json` (`knowledge-graph.md`) | the **next** run's stage-0 harvest |
 
 ## This repo (task-pipeline itself), for reference
 
@@ -78,17 +84,18 @@ plugins/task-pipeline/
     pipeline.example.json                     # this plugin's own flow, as config
     references/                               # built-in stage doctrine:
       knowledge-sources.md grill.md           #   stage 0 (harvest, then interview)
+      knowledge-graph.md                      #   stages 0+9: the code graph, refresh, divergence
       brainstorm.md decomposition.md          #   stage 2
       spec.md planning.md                     #   stages 3-4
       build.md review.md tdd.md               #   stages 5-6
-      acceptance.md                           #   stage 10
+      acceptance.md retrospective.md          #   stage 10 (close-out, then the retro)
       audit.md                                #   cross-cutting: the ladder + seams
       loop-guard.md                           #   cross-cutting: churn detection
       stages.md model-tiering.md              #   gates, model policy
       conventions.md artifacts.md             #   host conventions, this layout
       companion-skills.md                     #   optional companions + preflight
     templates/                                # skeletons seeded into a host project
-      README.md brief.md carryover.md context.md adr.md
+      README.md brief.md carryover.md context.md adr.md retro.md
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
 install.sh                                    # POSIX installer

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

@@ -205,6 +205,14 @@ construction**:
    everywhere. This is the horizontal pass, and it is where it belongs.
 3. **One class swept end to end** — every error path, every count, every status
    vocabulary, every timeout, across the whole change at once.
+4. **The graph against the docs** — where a code graph exists
+   ([`knowledge-graph.md`](knowledge-graph.md)), it is a *second, machine-built
+   statement of the same system*, and disagreement is mechanical rather than
+   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. This axis is the only one that finds absences without reading for them,
+   which is why it is worth rotating onto when the reading axes go quiet.
 
 **The crossover is measurable, so measure it.** Every pass, count two numbers: new
 findings, and findings caused by the previous pass's own fixes. When the second

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

@@ -13,6 +13,7 @@ better, plus one that is required only for user-facing work.
 | Stage | Doctrine |
 |---|---|
 | 0 Knowledge harvest (pre-grill) | `references/knowledge-sources.md` |
+| 0 + 9 The code graph (the tool is optional; the doctrine ships) | `references/knowledge-graph.md` |
 | 0 Intake grill | `references/grill.md` |
 | 2 Brainstorm | `references/brainstorm.md` |
 | 2 Decompose (platforms only) | `references/decomposition.md` |
@@ -21,6 +22,7 @@ better, plus one that is required only for user-facing work.
 | 5 Build (isolation, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 10 Acceptance (REQ close-out) | `references/acceptance.md` |
+| 10 Retrospective (the run's last act: prune, stamp, entry) | `references/retrospective.md` |
 | 10 + any audit (finding what's missing) | `references/audit.md` |
 | any repeating loop | `references/loop-guard.md` |
 
@@ -32,6 +34,7 @@ better, plus one that is required only for user-facing work.
 | **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
+| **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
 
@@ -73,6 +76,13 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
                            pip install obsidian-wiki
                            obsidian-wiki setup --vault /path/to/your/vault
                          (running without it — the harvest uses repo docs only)
+  ✗ graphify           — recommended: stage 0 asks it what reaches what,
+                         stage 9 refreshes it beside the docs and the wiki:
+                           uv tool install graphifyy
+                           graphify install
+                           /graphify .        (once, in this project)
+                         (running without it — no reach queries, no graph↔docs
+                          divergence check)
 
 🧠 Model for this run: recommended <top tier available>. You're on <current>.
    /model <id> to switch, or "keep current", or name per-stage overrides.
@@ -88,6 +98,11 @@ Rules:
   `wiki-query`/`wiki-update`. Present → say `✓ ready` and use it in the harvest.
   Absent → print the two install lines **once** and continue; never ask twice in a
   run and never block a stage on it ([`knowledge-sources.md`](knowledge-sources.md)).
+- **graphify**: detect via `graphify-out/graph.json` (built → `✓ ready`, query it in
+  the harvest) or a resolving `graphify` binary with no `graphify-out/` (installed,
+  not built → offer the one-line `/graphify .`). Absent → print the install lines
+  **once** and continue. Same law as the wiki: recommended, never a gate, never
+  asked twice ([`knowledge-graph.md`](knowledge-graph.md)).
 - **Figma MCP**: flag it only when the task is user-facing **and** the project
   designs visually — read `docs/ux/foundation.md` → *Design tooling* first; no
   record yet means the choice itself is a stage-0 question (super-ux's default is

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

@@ -44,6 +44,12 @@ found, surface it and **ask** rather than guessing.
   into the host's own docs (`CLAUDE.md`, or the README) in this change, so the next
   run reads the destination instead of creating a second file
   ([`grill.md`](grill.md) → *The design destination*).
+- **The code graph:** [graphify](https://github.com/Graphify-Labs/graphify) —
+  `/graphify . --update` when `graphify-out/` exists, in the same change as the docs
+  and the wiki ([`knowledge-graph.md`](knowledge-graph.md)). It is derived, so
+  `graphify-out/` is git-ignored unless the project's own `CLAUDE.md` says the team
+  commits it. A project that uses a different graph/index tool names its refresh
+  command there, and that wins.
 - **Wiki:** [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — the
   `wiki-update` skill (resolves the vault via `~/.obsidian-wiki/config`). Detect it
   the same way the harvest does; if absent, recommend it once

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

@@ -130,7 +130,7 @@ explicit "stop and ask me here":
 | Stage | What to settle up front |
 |---|---|
 | run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
-| 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
+| 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki, **the code graph** ([`knowledge-graph.md`](knowledge-graph.md): built / installed-not-built / absent) — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
 | 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
 | 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |
@@ -141,8 +141,8 @@ explicit "stop and ask me here":
 | 6 Tests | the test command; what "green" means here; known-red baseline; coverage expectation |
 | 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 |
-| 10 Acceptance | who signs off; where deferred REQs are tracked (issue tracker, backlog) |
+| 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)) |
 
 **Deploy authorization has a hard floor.** Deploy and publish are outward and
 irreversible, so a vague "just do everything" authorizes nothing. A standing

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

@@ -0,0 +1,159 @@
+# The code graph — an index of reach, refreshed with the docs
+
+A grep finds a **name**. A graph finds **reach**: what actually calls this, what
+breaks if it moves, which module every change passes through. That is the question
+stage 0 needs answered before it asks the operator anything, and it is the question
+no document answers reliably — documents describe the reach the author remembered.
+
+The graph this pipeline is built to work with is
+**[graphify](https://github.com/Graphify-Labs/graphify)** — it turns a folder of
+code and docs into a persistent knowledge graph (`graphify-out/graph.json`, an HTML
+view and a plain-language `GRAPH_REPORT.md`), with community detection and
+query / path / explain / affected traversals.
+
+It is **recommended, never required**. No stage blocks on a missing graph; the
+harvest simply runs on the sources it has
+([`knowledge-sources.md`](knowledge-sources.md)).
+
+## Detect it, and install it once
+
+Detect, in this order:
+
+- `graphify-out/graph.json` exists → the graph is **built**; use it.
+- `command -v graphify` resolves but there is no `graphify-out/` → the tool is
+  installed, the graph is not built. Offer to build it (one command, below).
+- Neither → recommend it **once**, in the preflight block
+  ([`companion-skills.md`](companion-skills.md)), with the lines:
+
+  ```bash
+  uv tool install graphifyy      # the CLI
+  graphify install               # add the /graphify skill to this agent
+  ```
+
+  then, in the project root:
+
+  ```
+  /graphify .
+  ```
+
+  Then continue. Never ask twice in a run, and never hold a gate on it.
+
+`graphify-out/` is **derived**, so it is git-ignored by default — add it to the
+host's `.gitignore` in the same change that builds it. A team that wants the graph
+shared commits it instead and installs graphify's own git merge driver; that is the
+project's call, recorded in its `CLAUDE.md`, not this pipeline's default.
+
+## Stage 0 — query the graph before you ask the person
+
+The graph is a **source in the ledger**, read like any other, and it is the fastest
+one: it answers structural questions in a single call that would otherwise be a
+dozen greps.
+
+| Ask | Command |
+|---|---|
+| How does this work / where does this live? | `graphify query "how does session reach the API layer"` |
+| What is this thing? | `graphify explain "AuthModule"` |
+| What breaks if I change it? | `graphify affected "AuthModule"` |
+| How do these two connect? | `graphify path "AuthModule" "Database"` |
+| What is architecturally central? | `graphify god-nodes` |
+
+**What you get depends on what the repo is made of.** Code is extracted
+structurally, so `affected` and `path` are sharp on a code repo and return nothing
+useful on one that is mostly prose — there, the nodes are documents and headings,
+and the *divergence check* below is the half that pays. Say which one you are
+looking at rather than reporting an empty traversal as an absence of coupling.
+
+Two rules keep it honest:
+
+- **The graph points, the code decides.** It is an index built at a moment in time;
+  a graph from two weeks ago is exactly as stale as a doc from two weeks ago. It
+  belongs in the retrieval order right after the code, and never as the tiebreaker.
+  Precedence, reflowed so it reads in one direction: code first, then host docs and
+  ADRs, then the graph, then the wiki, then anyone's memory.
+- **Record it in the ledger with its build date** — source
+  `graphify-out/graph.json`, what it said about this task, how fresh, and therefore
+  whether stage 9 owes it a refresh. A source consulted but not recorded is a source
+  nobody will update.
+
+## Stage 9 — the close-out has three artifacts, not two
+
+The run is not written up until all three describe the same system:
+
+1. **The docs** — host module docs and runbooks, in the same change.
+2. **The wiki** — `wiki-update`, the distilled *why*.
+3. **The graph** — re-extracted from what this run just changed. **Two forms, and
+   the difference is the whole point of doing it at stage 9:**
+
+   ```
+   /graphify . --update      # in the agent: code AND docs, incremental — use this
+   ```
+
+   ```bash
+   graphify update .         # CLI shortcut: code ONLY, structural, no model, no key
+   ```
+
+   Stage 9 is the stage that *changed the docs*, so the CLI shortcut is the wrong
+   default here: it re-extracts code and leaves every edited document at its old
+   text, which produces the most expensive kind of stale graph — one that was
+   refreshed. The CLI's own last line says as much (*"for doc/paper/image changes
+   run `/graphify --update` in your AI assistant"*). Use the CLI form only when the
+   change was code-only.
+
+   Incremental either way: only new and changed files are re-extracted. On a run
+   that deleted code the rebuild legitimately has fewer nodes, and refuses to
+   overwrite until you say so — that is what `--force` is for.
+
+**Why it is a peer of the docs and not an afterthought:** the next run's stage-0
+harvest queries this graph *first*, and 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.
+
+Gate wording (stage 9, `auto`): where a graph exists, it is refreshed in this
+change, or the reason it wasn't is written in the carry-over ledger.
+
+## The divergence check — the graph against the docs
+
+Refreshing the graph is bookkeeping. The **check** is the payoff: two independent
+statements of the same system, so where they disagree, one of them is wrong and
+nobody had a way to notice. Run it as a pass, not as a linter — every close-out for
+the cheap half, the full sweep whenever the audit rotates onto this axis
+([`audit.md`](audit.md) → *Every pass changes the axis*).
+
+| Ask the graph | Command | A disagreement means |
+|---|---|---|
+| What are the hubs? | `graphify god-nodes` | a hub **no doc names** is an undocumented seam — the thing every change passes through and nothing explains |
+| What reaches what? | `graphify path "A" "B"` | an edge the docs **deny** ("these layers don't touch") is either a leak in the code or a lie in the docs — both are findings, and which one is a decision, not a guess |
+| What does this change touch? | `graphify affected "X"` | callers the docs never mention → the documented blast radius is smaller than the real one |
+| What is weakly connected? | `GRAPH_REPORT.md` communities + low-degree nodes | code that nothing — no doc, no test, no caller — reaches |
+
+And the reverse direction, which is the one that catches rot: **a doc that names a
+module, file or command the graph has no node for** describes something that no
+longer exists. That is a stale row in the stage-0 ledger, found mechanically instead
+of by remembering.
+
+Where the findings go:
+
+- **At stage 9** — a doc that is wrong about reach is fixed in this change, like
+  any other stale ledger row.
+- **At stage 10** — a seam nobody documented is an *absence*, and absences are what
+  the ladder walk exists to convert into REQ rows with their checks
+  ([`audit.md`](audit.md), [`acceptance.md`](acceptance.md)). It goes in **before**
+  the coverage table, never after.
+- **Never "fixed" in the graph.** The graph is derived. You fix the doc or you fix
+  the code, then re-run the extraction and the disagreement disappears on its own.
+  A hand-edited graph is a third statement, and now nothing is authoritative.
+
+**Cadence.** The refresh is every stage-9 close-out. The full sweep is periodic —
+stage 10, or whenever a pass on another axis stops finding anything new. Running the
+sweep on every commit turns an audit axis into noise and it stops being read.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "I'll just grep, it's faster" | Grep answers "where is this name". The questions that stop a run are "what reaches this" and "what breaks if it moves" — that is one query against a graph and an afternoon with grep. |
+| "The graph is probably stale" | Then it has a build date and you can say so. Stale-and-dated is a finding; stale-and-unknown is what you get by not building one. |
+| "Docs and wiki are updated, we're done" | The graph is the source the *next* harvest reads first. Leaving it behind is leaving a false premise where a machine will quote it back. |
+| "The divergence check found nothing, skip it next time" | It found nothing **on this axis, this pass**. Rotate the axis; that is the rule this check belongs to, not an exemption from it. |
+| "A hub with no doc is fine, everyone knows it" | Everyone currently on the team. The graph found it in one command; the person who joins next month will find it in a postmortem. |
+| "Building the graph costs an LLM run" | Code is extracted structurally, with no model and no API key. The cost you are avoiding is a rebuild you already paid for. |

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

@@ -26,23 +26,73 @@ makes the grill's answers *checkable* instead of merely confident.
 | # | Source | How to find it | What it's good for |
 |---|---|---|---|
 | 1 | **The code** | the repo you're in | what actually runs — the tiebreaker |
-| 2 | **Host agent docs** | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` | conventions, commands, deploy path, house rules |
-| 3 | **Domain docs** | `CONTEXT.md` / `CONTEXT-MAP.md`, `docs/adr/` | the glossary and the decisions with their reasons |
-| 4 | **Product/UX docs** | `docs/ux/` (super-ux chain), `README`, runbooks | user-facing behavior that is already specified |
-| 5 | **Pipeline history** | `docs/superpowers/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
-| 6 | **The knowledge wiki** | see below | distilled cross-project knowledge, prior sessions, why decisions were made |
-| 7 | **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 |
-| 8 | **Hosted doc systems the project names** | Notion / Confluence / Google Docs referenced in the project | the same, when the team keeps them there |
+| 2 | **The code graph** | `graphify-out/graph.json` — see below | *reach*: what calls this, what breaks if it moves, what every change passes through |
+| 3 | **Host agent docs** | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` | conventions, commands, deploy path, house rules |
+| 4 | **Domain docs** | `CONTEXT.md` / `CONTEXT-MAP.md`, `docs/adr/` | the glossary and the decisions with their reasons |
+| 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's standing instructions** | `docs/superpowers/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**, they are capped at ten |
+| 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 |
 
 Rules for the list:
 
 - **Never invent a source.** A doc repo is in scope because the project names it,
   not because it plausibly exists. Nothing is cloned or fetched on a guess.
-- **Sources 7–8 are read-only at this stage**, and reading a hosted system needs a
+- **Sources 9–10 are read-only at this stage**, and reading a hosted system needs a
   connected tool — if there's no tool, record the gap and ask the operator to paste
   what matters rather than pretending the source was covered.
-- **The wiki is optional; the harvest is not.** With no wiki and no doc repos, the
-  harvest is sources 1–5 and takes two minutes. Skipping it is never the answer.
+- **The wiki and the graph are optional; the harvest is not.** With no wiki, no
+  graph and no doc repos, the harvest is sources 1 and 3–7 and takes two minutes.
+  Skipping it is never the answer.
+- **Source 7 is read in full, not queried.** It is capped at ten instructions
+  precisely so that this is cheap, and it is the one source that *binds* the run
+  rather than informing it.
+
+## The retro's standing instructions — an instruction source, not background
+
+`docs/superpowers/retro.md` ([`retrospective.md`](retrospective.md)) is the one
+harvested source that is **read in full rather than queried**: the standing
+instructions are capped at ten precisely so that this is cheap. They are what
+previous runs of this pipeline got wrong *in this project* — the rules no check
+could decide — and they bind this run.
+
+Two obligations that come with reading them:
+
+- **Stamp an instruction the moment it fires.** That date is the only evidence
+  behind the cold-retirement rule at stage 10; without it "hasn't fired in five
+  runs" is a guess and the prune becomes a mood.
+- **Record the file as a ledger row**, like any other source. It is also the row
+  stage 10 writes back to, which is what closes this particular loop.
+
+## The code graph — recommended
+
+Full doctrine: [`knowledge-graph.md`](knowledge-graph.md). In one paragraph: a grep
+finds a **name**, a graph finds **reach** — what calls this, what breaks if it
+moves, which module every change passes through. That is the class of question the
+harvest most needs answered and the class documents answer least reliably, because a
+document records the reach its author remembered.
+
+**Detect it** — `graphify-out/graph.json` exists (built), or `graphify` resolves but
+the directory doesn't (installed, not built).
+
+- **Built → query it** during the harvest: `graphify query "<the task, as a
+  question>"`, `graphify affected "<the thing being changed>"`, `graphify god-nodes`.
+  Record the row **with the graph's build date**, because a graph is a source and
+  goes stale like one.
+- **Not installed → recommend it once**, in the preflight block, with the lines:
+
+  ```bash
+  uv tool install graphifyy      # the CLI
+  graphify install               # add the /graphify skill to this agent
+  ```
+
+  then `/graphify .` in the project root. Then continue — it is a
+  **recommendation, never a gate**, exactly like the wiki.
+
+The graph **points; the code decides.** Retrieval order puts it right after the
+code, never as the tiebreaker.
 
 ## The knowledge wiki — recommended
 
@@ -139,6 +189,13 @@ The ledger is the stage-9 work list. For each row:
   resolved verbally.
 - **The wiki** — `wiki-update` syncs what this run learned. Distil the *knowledge*
   (decisions, seams, gotchas, why), never a diff summary.
+- **The graph** — `/graphify . --update` re-extracts what this run changed
+  ([`knowledge-graph.md`](knowledge-graph.md)). It is a **peer of the docs, not an
+  afterthought**: the next run's harvest queries it first, and 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. Refreshing it also enables the cheap half of
+  the **divergence check** — a hub no doc names, an edge the docs deny, a doc naming
+  a module the graph no longer has.
 - **Another repository's docs** — writing to a repo the operator didn't ask you to
   touch is **outward**: propose the change, get an explicit go, then open a PR
   there. Absent a go, it goes in the carry-over ledger with the exact edit needed.

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

@@ -133,3 +133,11 @@ answer would have exposed it in a minute.
 | 6 Tests | 4, 5, 10, 11 — every new check probed both ways, measured, and asserted on its exit code |
 | 9 Docs | 8, 14 — every number computed, every target resolvable |
 | 10 Acceptance | 1, 3, 6, 7 — axis rotation recorded, closure verified against artefacts, classes swept, ratchets printed |
+
+**This file is the shipped list; a project keeps its own.** These fourteen were
+earned on someone else's build and travel with the skill. The lessons *your*
+project buys go in its retro ([`retrospective.md`](retrospective.md) →
+`docs/superpowers/retro.md`), where they are capped, pruned and retired — and a
+lesson there that would be true in any repository belongs here instead, as an issue
+upstream. A local file that accumulates universal rules is a fork of this one that
+nobody named.