task-pipeline-skill 1.4.4 → 1.6.1

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

@@ -0,0 +1,117 @@
+# Retrospective — the run teaches the next run, and the list stays short
+
+The last act of stage 10, after the coverage table and before the run is called
+done. It exists because the pipeline's gates are good at *this* run and blind
+across runs: the same class of failure can be caught, fixed and forgotten five
+times, and nothing in the flow notices it is the same one.
+
+**Artifact:** `docs/superpowers/retro.md` — **one per project, not per run**,
+committed. It has three parts and a hard size limit:
+
+| Part | What's in it | Read by |
+|---|---|---|
+| **Standing instructions** | the rules currently in force — max **10** | stage 0, in full, every run |
+| **Log** | problem → cause → fix → check, newest first, plus every retirement | a human, and stage 0 when the terms match |
+| **Run stamps** | one line per run: date, topic, verdict | the prune (this is what makes "five runs" countable) |
+
+Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
+writes an entry. A retro that is empty after a messy run is the exact failure this
+file exists to stop.
+
+## Write the entry only for a divergence — and name the layer that owned it
+
+An entry is owed when the run did not go as planned: a gate reopened, a stage was
+re-entered, a fix broke something it wasn't touching, an estimate was wrong by a
+factor, the operator had to intervene where the brief said they wouldn't.
+
+Required fields, and none of them is optional:
+
+| Field | The rule |
+|---|---|
+| **Symptom** | what actually happened, in one line, with the evidence (a command, a `file:line`, the gate that reopened) |
+| **Surfaced at** | the stage where it became visible |
+| **Owned by** | the stage that *let it through* — usually an earlier one. A finding belongs to the layer that owns it; recording it against the stage that tripped over it is how the same defect returns |
+| **Root cause** | why the pipeline permitted it. "The agent was careless" is not a cause — it is the absence of one, and it produces no fix |
+| **Fix** | one of the three grades below |
+| **The check** | what would have caught this the first time. If the honest answer is "nothing yet", that is the fix, and it is grade 1 |
+
+## Three grades of fix — take the highest one that can work
+
+**Grade 1 — mechanical.** A test, a lint rule, a gate criterion, a CI step, a hook.
+The check *is* the memory: nothing has to be read, remembered or pruned later. Log
+it as `landed` and move on — it never becomes a standing instruction and never
+costs a slot.
+
+**Grade 2 — a standing instruction.** A rule an agent must read, for the cases no
+check can decide (a judgement, a precedence, a "ask before X"). It costs one of the
+ten slots and it is **only accepted with its retirement trigger written at birth**
+(below).
+
+**Grade 3 — a note with an expiry.** For something still being understood. Maximum
+**two runs**. At the second stamp it is promoted to grade 1 or 2, or deleted. A note
+with no expiry is how a file becomes unreadable one honest line at a time.
+
+Prefer grade 1 whenever a check can decide it. This is the same law as
+[`audit.md`](audit.md) → *A class that repeats twice becomes a gate, not a note*: a
+rule that could have been a check gets read twice and obeyed once.
+
+## The prune — mandatory, and it runs BEFORE the new entry is written
+
+Prune first, then write. A lesson that lands in a cluttered file is a lesson nobody
+will reach.
+
+Check **every** standing instruction against three retirement triggers:
+
+| Trigger | Test | Then |
+|---|---|---|
+| **It became a check** | the rule is now enforced by a test, lint, gate or hook | delete it — the check is the memory, and keeping both means it is read twice and obeyed once |
+| **Its surface is gone** | resolve every path, command, stage and tool it names; any that no longer exists | delete it — it now describes a system nobody is running |
+| **It went cold** | it has not fired in the last **five run stamps** | delete it — five runs without firing is the evidence that it was situational |
+
+Then the cap: **ten standing instructions, hard.** At eleven you do not get to keep
+them all — the oldest never-fired one goes. "But all of them 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.
+
+**Every deletion writes one line in the Log** — id, date, which trigger fired.
+Silent deletion is forbidden: the record is what survives, the instruction is what
+leaves. A retired rule that comes back as a real failure is a grade-1 fix, and now
+you have its history.
+
+**Print the counts beside the gate verdict**, the same way the carry-over ledger
+does ([`audit.md`](audit.md) → *ratchet, never TODO*):
+
+```
+GATE 10 acceptance: PASS — 14/14 REQ verified
+  carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
+```
+
+A pruned list that nobody prints is a list that quietly grows back.
+
+## The loop closes at stage 0
+
+The standing instructions are an **instruction source**, not background reading:
+[`knowledge-sources.md`](knowledge-sources.md) reads them in full at the harvest —
+they are short by construction — and records the file as a ledger row. Every
+instruction that actually *fires* during the run gets its **last-fired date
+stamped** as it fires. That stamp is the only thing that makes the cold-rule honest;
+without it "five runs without firing" is a guess, and the prune becomes a mood.
+
+## Where a lesson goes when it is not about this project
+
+A lesson that would be true in any repository does not belong in one project's
+retro — it belongs in the pipeline's own doctrine
+([`learned.md`](learned.md), which is exactly that list, earned the same way). Open
+an issue upstream and say so in the entry. A local file that accumulates universal
+rules is a fork of the skill that nobody named.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "Nothing really went wrong this run" | Then the stamp says so in one line and you are done in ten seconds. The runs that "went fine" are where a repeated class hides — it never cost enough to remember. |
+| "I'll write the retro later, with a clear head" | Later is when you remember the outcome and not the seam. The cause is legible for about an hour after the run. |
+| "Don't delete it, it might still be useful" | That sentence is the entire failure mode. Every rule kept "just in case" spends attention that the load-bearing ones needed, and the file stops being read at all. |
+| "Pruning loses knowledge" | The Log keeps the incident forever; only the *instruction* leaves. If it recurs you get a grade-1 fix with its own history attached. |
+| "The list is at eleven but they're all important" | Then one of them is doctrine and belongs in `CLAUDE.md`, one has become a check, and one has not fired in a year. Ten is the budget precisely because ranking is uncomfortable. |
+| "I'll note it as a reminder for next time" | A note is grade 3 and expires in two runs. If it is worth remembering it is worth a check or a slot; if it is worth neither, it was never going to be read. |

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

@@ -37,15 +37,20 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   answers for scope, users, constraints, data, edge cases, done-criteria.
 - **Phase 1 — harvest the knowledge sources FIRST**
   ([`knowledge-sources.md`](knowledge-sources.md)). Before the first question:
-  query what the project already knows about this task — code, `CLAUDE.md`,
+  query what the project already knows about this task — code, **the code graph**
+  when one is built ([`knowledge-graph.md`](knowledge-graph.md): `graphify query` /
+  `affected` / `god-nodes` answer *reach*, which is what grep cannot), `CLAUDE.md`,
   `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs and carry-over
-  ledgers, the **knowledge wiki** if one is installed
+  ledgers, **the retro's standing instructions** (`docs/superpowers/retro.md`, read
+  **in full** — they are capped at ten and they bind this run; stamp each one as it
+  fires, [`retrospective.md`](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 (a row per source, or an
-  explicit "none found"). It is retrieval scoped by the task's own nouns, not a
-  read of everything — and it is what makes phase 2's answers checkable instead of
-  merely confident.
+  explicit "none found"; the graph's row carries its build date). It is retrieval
+  scoped by the task's own nouns, not a read of everything — and it is what makes
+  phase 2's answers checkable instead of merely confident.
 - **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
   skill (nothing to install). In short: one question per turn, a recommended
   answer with each, explore the codebase before asking, depth-first through the
@@ -257,12 +262,27 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   `~/.obsidian-wiki/config`, or the skill resolves). Not installed → recommend it
   once with its install line and continue; a missing wiki never blocks the gate.
   Distil the knowledge (decisions, seams, why), not a diff summary.
+- **Refresh the code graph** — `/graphify . --update` when one exists
+  ([`knowledge-graph.md`](knowledge-graph.md)). The close-out has **three**
+  artifacts, not two: docs, wiki, graph. The graph is the source 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. Incremental
+  and model-free for code; a run that deleted code legitimately rebuilds smaller
+  (`--force`).
+- **Then check the graph against the docs** — the cheap half of the divergence sweep
+  (`graphify god-nodes`; any doc naming a module the graph no longer has). A hub no
+  doc names, or an edge the docs deny, is either a leak in the code or a lie in the
+  docs; a doc naming a node that no longer exists is a stale ledger row found
+  mechanically. Doc-side findings are fixed here; **absences go to stage 10's ladder
+  walk as REQ rows** ([`audit.md`](audit.md)).
 - **Docs living in another repository** are outward: propose the edit, get an
   explicit go, then open a PR there. No go → the exact edit goes in the carry-over
   ledger.
 - **GATE (auto):** docs in sync with code; every stale row in the source ledger
   either updated or carried over with its edit; UI: super-ux layers current +
-  linter green; wiki synced (or absent and recommended once); dangling links fixed.
+  linter green; wiki synced (or absent and recommended once); **the code graph
+  refreshed where one exists, or the reason it wasn't written into the carry-over
+  ledger** (absent and recommended once is fine); dangling links fixed.
 
 ## 10 — Acceptance
 - **What:** the closing stage — go back to the brief and account for **every**
@@ -313,8 +333,23 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   `/agent-sync finish` runs exactly that. The fix is two commands and the second is
   the forgotten one: `git -C <submodule> push`, then
   `git add <submodule> && git commit`.
+- **The retrospective is the run's last act** ([`retrospective.md`](retrospective.md)),
+  written to `docs/superpowers/retro.md` — one file per project, not per run. The
+  pipeline's gates are good at *this* run and blind across runs: the same class of
+  failure can be caught, fixed and forgotten five times and nothing in the flow
+  notices it is the same one. So, in this order: **prune first** (every standing
+  instruction against its three retirement triggers — it became a check, its
+  surface is gone, it hasn't fired in five run stamps — and the list held to its cap
+  of ten, every deletion logged), **stamp the run**, then **write an entry only if
+  the run diverged** (symptom · the stage it surfaced at · the stage that *owned* it
+  · root cause · fix, mechanical before instruction before expiring note · the check
+  that catches it next time). Every run prunes and stamps; a retro left empty after
+  a messy run is the failure the file exists to stop. Stage 0 reads the standing
+  instructions in full next time, which is why the cap is not negotiable.
 - **GATE (manual):** the ladder walk ran and its absences became REQ rows before
-  the table was written; **every repository is closed — the parent included:
+  the table was written; **the retrospective is written — prune before entry, the
+  list at or under its cap with every deletion logged, the run stamped, and the
+  counts printed beside this verdict**; **every repository is closed — the parent included:
   `git submodule status` shows no `+`, each repo clean and pushed**; **every check this gate leans on has been seen failing
   once against a planted defect** (an unproven check's green is not evidence);
   every REQ has a status (none `unknown`); every `verified`

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

@@ -1,9 +1,11 @@
 # templates
 
-Skeletons task-pipeline seeds into a host project. Only the **brief** is a seeded
-file (it is the stage-0 intake artifact). The spec and plan have no skeleton here —
-their required structure is prescribed inline by `references/spec.md` and
-`references/planning.md`; the `docs/ux/*` skeletons come from `super-ux`.
+Skeletons task-pipeline seeds into a host project. Two are **seeded files** — the
+**brief** (the stage-0 intake artifact) and the **retro** (created at the first
+stage-10 close-out, then appended to for the life of the project). The spec and plan
+have no skeleton here — their required structure is prescribed inline by
+`references/spec.md` and `references/planning.md`; the `docs/ux/*` skeletons come
+from `super-ux`.
 
 | Template | Seeded to | Stage |
 |---|---|---|
@@ -11,10 +13,14 @@ their required structure is prescribed inline by `references/spec.md` and
 | `carryover.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-carryover.md` | 0 seeds, all stages append, 10 reads |
 | `context.md` | `CONTEXT.md` at the repo root (or per context) | 0 — grill, domain awareness |
 | `adr.md` | `docs/adr/NNNN-<slug>.md` | 0 — grill, hard-to-reverse decisions |
+| `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads the standing instructions in full |
 
 `context.md` and `adr.md` are **format references**, not files to copy wholesale:
 the grill writes `CONTEXT.md` entries and ADRs in their shape, lazily — only once
 there is a resolved term or a decision worth recording.
 
 Seeding rule (per the ssheleg canon): create a template copy **only when the
-target is absent**; never overwrite an existing brief.
+target is absent**; never overwrite an existing brief. The rule is hardest and most
+important for `retro.md`: it is the only artifact that accumulates across runs, so
+overwriting it with the skeleton destroys every lesson the project has bought —
+seed it once, then read, prune and append.

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

@@ -19,17 +19,25 @@ premise if the run leaves it wrong.
 | Source | What it says about this task | Fresh? | Authority | Stale after this run? |
 |---|---|---|---|---|
 | `docs/adr/NNNN-….md` | … | YYYY-MM | decision | no |
+| `graphify-out/graph.json` | reach: what calls it, what breaks if it moves | built YYYY-MM-DD | index | **yes — refresh at stage 9** |
 | wiki: `projects/…/concepts/…` | … | YYYY-MM | context | **yes — update at stage 9** |
 | `CLAUDE.md` | test/lint/deploy commands, house rules | current | convention | no |
 
-Precedence when two disagree: **code > host docs and ADRs > wiki > memory.** The
-operator outranks every document — but only **out loud**: an override quoted
-against its source is a recorded decision, an unquoted one is an undetected
+Precedence when two disagree, in one direction: **code first, then host docs and
+ADRs, then the code graph, then the wiki, then memory.** The graph points; the code
+decides. The operator outranks every document — but only **out loud**: an override
+quoted against its source is a recorded decision, an unquoted one is an undetected
 divergence.
 
 - **Doc repos / hosted doc systems this project names:** … (or `none`)
 - **Knowledge wiki:** installed / not installed
   ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki); recommended, never a gate)
+- **Retro standing instructions:** `docs/superpowers/retro.md` — none / N in force
+  (read **in full**; list which ones bind this run, and stamp each as it fires —
+  that date is the only evidence behind stage 10's cold-retirement rule)
+- **Code graph:** built / installed-not-built / not installed
+  ([graphify](https://github.com/Graphify-Labs/graphify); recommended, never a gate —
+  built → its row above carries the build date and stage 9 refreshes it)
 
 ## Scope
 
@@ -79,7 +87,7 @@ is not neutral — it is a scheduled interruption.
 |---|---|---|
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
 | run-wide | Decide autonomously vs escalate to me | … |
-| 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push) |
+| 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki, the code graph; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push; graph built / not built) |
 | 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
 | 2 Decompose | 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); scenario-tracing waiver, if any | … |
@@ -92,8 +100,8 @@ is not neutral — it is a scheduled interruption.
 | 7 Deploy | Target + path; release automation on/off; deploy-from-main rule | … |
 | 7 Deploy | **Authorization** — standing go, or ask every time? | … |
 | 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; which stale ledger rows get fixed | … |
-| 10 Acceptance | Who signs off; where deferred REQs get 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`); which stale ledger rows get fixed | … |
+| 10 Acceptance | Who signs off; where deferred REQs get tracked (issue tracker / backlog); **retro file** — `docs/superpowers/retro.md` present? which standing instructions bind this run? | … |
 
 > **Deploy authorization has a hard floor.** A standing go counts only if it is
 > **specific** — named target and named preconditions ("staging, once lint and the

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

@@ -0,0 +1,51 @@
+# Pipeline retrospective — <project>
+
+One file per project, not per run. Written as the **last act of stage 10**:
+prune first, then stamp, then write an entry **only if the run diverged**.
+Doctrine: `references/retrospective.md`.
+
+Stage 0 reads *Standing instructions* in full, every run — which is why the list
+has a hard cap of **ten**.
+
+## Standing instructions (max 10 — in force right now)
+
+Every row is a rule an agent must follow, that **no check can decide**. A rule a
+check *can* decide is not written here: it is written as the check (grade 1).
+No row is accepted without its **retire-when** trigger, written at birth.
+
+| id | Born | Instruction | Because (incident) | Retire when | Last fired |
+|---|---|---|---|---|---|
+| R-001 | 2026-05-04 · `<topic>` | … | … (one line, links the log entry) | … (e.g. "the export path is covered by a test") | 2026-06-18 |
+
+Retire on **any** of: it became a check · every path/command it names is gone · it
+has not fired in the last five run stamps. At eleven rows, the oldest never-fired
+row goes — the cap is not negotiable, ranking is.
+
+## Log — problem → cause → fix (newest first)
+
+Retirements are logged here too, one line each: *silent deletion is forbidden; the
+record stays, the instruction leaves.*
+
+### 2026-05-04 · `<topic>` · gate 6 reopened twice
+
+- **Symptom:** … (one line + evidence — a command, a `file:line`, the gate)
+- **Surfaced at:** stage 6 · **Owned by:** stage 4 (the plan never named the check)
+- **Root cause:** … (why the pipeline permitted it — "the agent was careless" is
+  not a cause; it is the absence of one, and it produces no fix)
+- **Fix:** grade 1 (mechanical) — … / grade 2 → `R-00N` / grade 3, expires in
+  2 runs
+- **The check:** … (what catches this the first time, from now on)
+- **Upstream?** … (a lesson true in any repo belongs in the skill's own
+  `references/learned.md` — open an issue and say so here)
+
+### 2026-05-04 · retired R-000 — became a check (`npm run lint:paths`)
+
+## Run stamps
+
+One line per run, appended at stage 10. This is what makes "five runs" countable
+— without it the cold-rule is a guess and the prune becomes a mood.
+
+| Date | Topic | Verdict | Retro |
+|---|---|---|---|
+| 2026-05-04 | `<topic>` | 14/14 verified | 1 entry · 7 standing (was 9) · retired 3 · added 1 |
+| 2026-05-02 | `<topic>` | 9/9 verified | no divergence · 9 standing · retired 0 |