task-pipeline-skill 0.17.1 → 1.1.0

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

@@ -0,0 +1,224 @@
+# Audit — finding what is missing, cross-cutting
+
+Every gate in this pipeline asks *"is this artifact good?"*. Stage 10 asks *"is
+anything from the list lost?"* ([`acceptance.md`](acceptance.md)). **Neither asks
+what should have been on the list and never was.**
+
+That gap is not an oversight in the gates. It is structural: a gate compares two
+things, and **a contradiction has two sides while an absence has one.** Comparing
+the spec against the plan finds a requirement that was dropped. It cannot find the
+error path nobody specified, the entity nobody gave an owner, the failure mode
+nobody named — because on both sides of every comparison, it simply isn't there.
+
+This file is the method that finds those. It is **cross-cutting**: stage 10 runs it
+before writing the coverage table, the program loop runs it per module, and a task
+whose whole job is "audit X" runs nothing else.
+
+## Three things that are easy to confuse
+
+| File | Runs when | Answers |
+|---|---|---|
+| [`acceptance.md`](acceptance.md) | stage 10 | did everything **on the list** ship, with evidence? |
+| [`loop-guard.md`](loop-guard.md) | any **editing** loop churns | is this pass undoing the last one? |
+| **this file** | any **audit** pass | what is broken or missing that nobody has compared? |
+
+`loop-guard.md` governs loops that *change* things — the fix loop, a re-entered
+stage. Its trip means a decision is being re-litigated at the wrong altitude. This
+file governs loops that *look* for things. Its trip means the axis is exhausted,
+which is a different failure with a different exit. Both can bind one run; they do
+not overlap.
+
+## Why "look again, more carefully" stops working
+
+The method most audits use is **horizontal**: compare the documents against each
+other, then do it again. It works, and then it fails in a way that is invisible
+from inside it. Measured over seven passes on a production repository:
+
+| Pass | Findings | …of which the previous pass's own fixes caused |
+|---|---|---|
+| 4 | 12 | 5 |
+| 5 | 17 | 9 |
+| 6 | 13 | 10 |
+| 7 | 19 | 4 |
+
+By pass six the audit was **mostly repairing itself**. Not fatigue — arithmetic.
+Each pass edits the corpus the next pass reads, so the newest edits are always the
+least-reviewed text present, and they are what the next pass finds. The count stays
+healthy while the yield goes to zero.
+
+A single **vertical** pass over the same repository — one capability walked down
+through its layers — found nine defect classes those seven passes had been
+structurally **unable** to see. Not missed: unable. Two of them:
+
+- **A component that encrypts every object in the system had no key store
+  anywhere.** Its sibling's key table had been modelled for weeks. A comparison
+  needs two sides; this had one.
+- **An edit appended a new version while the derived index still pointed at the
+  old text.** The archive is correct. The index is correct. The answer is correct —
+  *against a version nobody is looking at.* Compare archive to archive and index to
+  index: both pass. **The defect lives in the seam.**
+
+## The ladder
+
+The rungs are **layers of one deliverable**; the work is the **seams between
+them**. Each rung's artefact either exists or it does not — that is what makes
+absence findable.
+
+| Rung | Layer | The artefact that must exist |
+|---|---|---|
+| **L0** | Requirement | a `REQ-###` row in the brief **with a named check** |
+| **L1** | Decision | the locked decision, ADR or `CONTEXT.md` term this REQ rests on |
+| **L2** | Design | a spec section carrying `covers: REQ-…` |
+| **L3** | Contract | an exact signature or schema · **and its failure behavior** |
+| **L4** | Task | a plan task with `Implements:` and a DoD satisfiable **as written** |
+| **L5** | Change | the commits — the thing actually in the tree |
+| **L6** | Test | an **executed** assertion, by name — never "the tests pass" |
+| **L7** | Surface | what a user reaches: scenario, screen state, CLI output, runbook |
+
+**Audit the seams, not the artifacts.** Each rung is internally consistent most of
+the time — that is exactly what the horizontal pass is good at, and it has already
+done it. What survives lives between rungs:
+
+| Seam | The question | What absence looks like here |
+|---|---|---|
+| L0→L1 | does the requirement rest on a **recorded** decision? | a REQ whose check implies a choice nobody ever made or wrote down |
+| L1→L2 | did the decision reach the spec? | an ADR or glossary term agreed at the grill that no spec section cites |
+| L2→L3 | does the section name its contract **and what happens when it fails**? | "handles errors" — no code, no shape, no caller-visible reason |
+| L3→L4 | does every contract have a task that builds it? | stage 4's set-equality covers REQ→task; **nothing** covers contract→task |
+| L4→L5 | did the DoD land in the tree? | a DoD line nothing in the diff satisfies, marked done anyway |
+| L5→L6 | is there an executed observable? | "tests pass"; a test that still passes with the production code deleted |
+| L6→L7 | can a user reach it, and does a doc say so? | shipped behavior with no scenario, no `--help` line, no runbook entry |
+| L7→L0 | does the shipped surface satisfy the requirement's **statement**? | it does what the task said and not what the requirement meant |
+
+The last seam is stage 10's question, expressed as a seam. When it fails, the run
+did every instruction correctly and delivered the wrong thing.
+
+## How one audit pass runs
+
+**Scope: one deliverable, all rungs.** One REQ, one module, one capability. Not
+"audit the docs" and not "audit the change" — an unscoped instruction is what
+produces seven converging passes.
+
+**Input** is the artifact that already names every rung: the brief's REQ row plus
+the module map row ([`decomposition.md`](decomposition.md)) when there is one. **If
+the input can't supply the rungs, that is the first finding** — do not go looking
+for the layers by hand; record that the spine is missing and fix that first.
+
+**Procedure: bottom-up, L0 → L7, running the seam check at each step.**
+
+The direction is not taste. A missing artefact at L1 makes everything above it
+meaningless, so top-down you spend the pass polishing a surface for a contract that
+does not exist. Bottom-up, the absence surfaces first and the six findings above it
+collapse into one.
+
+**Output: findings ordered by seam, never by file.** A file-ordered list reads as
+noise; a seam-ordered one tells you **which layer of your own process is leaking**,
+which is the thing worth knowing. Each finding carries `file:line`, the artefact
+that is missing, and the minimal fix.
+
+**Close through the pipeline, not around it.** A finding that is a genuine gap
+becomes a **new REQ row** (with its check) or a carry-over row — the list is frozen
+against *narrowing*, never against additions ([`grill.md`](grill.md) → *The REQ
+spine*). A finding that contradicts the spec goes back to stage 3; one that
+contradicts the plan goes back to stage 4. Auditing is not a licence to edit
+across layers in place.
+
+## Exit criterion — the part usually skipped
+
+A deliverable is **not** audited when somebody has read it. It is audited when:
+
+1. every rung has its artefact, **and**
+2. **every check you are relying on has fired at least once against a planted
+   defect.**
+
+**A green result from an unproven check is worth nothing.** This is the iron law of
+[`tdd.md`](tdd.md) — *if you didn't watch it fail, you don't know it tests the
+right thing* — raised from one test to every gate in the run. It applies to the
+stage-4 set-equality check, the host's lint and test commands, the super-ux linter,
+any script the host added, and every check you write during the audit itself.
+
+Checks written under time pressure lie in ways that read as success: a predicate
+that inspects the wrong shape and finds nothing; a probe that removes more than it
+adds and reads the shrinkage as a pass; a regex that misses the very word it
+searches for. All three pass loudly. **Plant the defect. Watch the check fail.
+Remove it. Then trust the green.** Record in the ledger that you did.
+
+## The three rules that stop this becoming another loop
+
+### 1. A class that repeats twice becomes a gate, not a note
+
+Once is an incident. **Twice is a category, and a category belongs in a script** —
+the host's lint, its CI, its check runner — where nobody has to remember it.
+
+Writing the third instance into the carry-over ledger is how a known, mechanical
+defect class becomes permanent. If the class genuinely cannot be checked
+mechanically, say so in one line and *say why*; that sentence is itself a finding
+worth having.
+
+### 2. Every pass changes the axis, not the effort
+
+"Look again, more carefully" is what converges. Passes must be **orthogonal by
+construction**:
+
+1. **Seams** — one deliverable walked L0→L7 (this file's ladder).
+2. **Invariants across deliverables** — one name, one enum, one owner, one spelling,
+   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.
+
+**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
+overtakes the first, the axis is exhausted — **rotate it, don't push harder.** Both
+counts go in the ledger; an audit that reports only "found N" cannot see its own
+exhaustion.
+
+### 3. What can't be fixed now becomes a ratchet, never a TODO
+
+A **ratchet** is a *named, counted set that may only shrink, printed on every
+run*.
+
+The carry-over ledger ([`templates/carryover.md`](../templates/carryover.md)) is
+the pipeline's ratchet, and it only works if its count is **printed at every gate
+beside the verdict**:
+
+```
+GATE 6 tests: PASS — full suite green (247 tests)
+  carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
+```
+
+The difference from a TODO is not bookkeeping. A TODO is invisible until somebody
+opens the file. A ratchet sits next to the word `PASS` on every single run, so
+**"green" never reads as "verified"** — it reads as *"green, and here is exactly
+what was not looked at."* A ratchet that grew needs a sentence in the run log
+explaining why; a ratchet nobody prints is a TODO with a better name.
+
+## When this runs
+
+- **Stage 10, before the coverage table.** Acceptance reads the REQ list; the
+  ladder walk is what can add to it. Absences found here become new REQ rows with
+  their checks, and *then* the table is written — otherwise acceptance closes green
+  over a gap that was never a row.
+- **Per module in the program loop** ([`decomposition.md`](decomposition.md)) — one
+  brick's ladder, at that brick's acceptance. Cross-module contracts are audited at
+  the seam that owns them, not twice.
+- **As the whole task**, when the operator's request *is* an audit. Then stages 3–5
+  produce findings and fixes rather than a feature, and the exit criterion above is
+  the stage-10 gate.
+- **Never as an eighth "look again" pass.** If the last two passes found mostly
+  self-inflicted findings, the answer is rule 2, not another pass.
+
+Once both axes are exhausted, the next finding of a known class should be caught by
+a script — and if it cannot be, **that is the finding: write the check.**
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The gates all passed, so it's complete" | Gates compare. Nothing that was never written appears on either side of a comparison. |
+| "One more careful pass will catch it" | Measured: by pass six the passes were mostly fixing their own last pass. Rotate the axis. |
+| "I'll audit top-down, the surface is where users are" | A surface built on an absent contract wastes the whole pass. Bottom-up, that absence is finding #1. |
+| "The check is green, that's evidence" | Only if you have seen it red. An unproven check is a decoration that reports success. |
+| "It's a small gap, I'll note it in the ledger" | Second occurrence of a class → it goes in a script. The ledger is for what cannot be automated, not what nobody automated. |
+| "Findings grouped by file are easier to fix" | And impossible to learn from. Group by seam; the seam names which layer of your process leaks. |
+| "The ledger has it, we won't forget" | Only if it is printed beside every verdict. Unprinted, it is a TODO, and TODOs are invisible by construction. |
+| "This is out of scope for the audit" | Then it is a carry-over row with a home, right now. An audit that silently declines findings is worse than none. |

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

@@ -37,10 +37,12 @@ not a question to re-open from scratch.
 1. **Explore the current state.** Files, module docs, recent commits, the
    conventions the repo already follows. Do this before asking anything.
 2. **Scope check, early.** If the task actually describes several independent
-   subsystems, say so immediately and help decompose it into sub-projects: what the
-   independent pieces are, how they relate, what order they get built in. Then
-   brainstorm the first one. Each sub-project gets its own spec → plan → build
-   cycle. Don't refine details of something that needs splitting first.
+   capabilities or separately shippable surfaces, say so immediately: that is a
+   **platform**, and it gets cut into modules at the end of this stage by
+   [`decomposition.md`](decomposition.md), before any spec is written. Brainstorm
+   the platform's shape — the pieces, how they relate, what order they land in —
+   not the details of one corner; those belong to each module's own stage-3
+   dossier. Don't refine something that needs splitting first.
 3. **Questions one at a time.** Never bundle. Multiple choice where it fits, open
    where it doesn't. Purpose, constraints, success criteria — anything the brief
    left at design level.

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

@@ -234,6 +234,12 @@ Two routes leave before the loop starts:
 - **Minor findings** never enter it. Record each in the ledger
   (`Task <N>: minor (deferred): <one-liner>`) and point the final review at that
   list. A roll-up nobody reads is a silent discard.
+- **A finding class that shows up a second time stops being a finding and becomes a
+  check.** Two tasks flagged for the same mechanical defect — the same missing
+  failure path, the same magic value, the same naming slip — means every later task
+  will produce it too. Add it to the host's lint or check script now, in its own
+  commit, instead of writing the third instance into the ledger
+  ([`audit.md`](audit.md) → *A class that repeats twice becomes a gate*).
 - **A finding that conflicts with what the plan mandates** is the operator's
   call: present the finding beside the plan text and ask which governs. Don't
   dismiss the finding because the plan mandated it; don't fix against the plan
@@ -304,7 +310,8 @@ findings are neither fixed nor parked-with-ruling at the cap.
 ## 5. Final whole-branch review
 
 After the last task: build a package over `MERGE_BASE`..`HEAD`
-(`git merge-base main HEAD`), dispatch the whole-branch review
+(`git merge-base "$BASE_BRANCH" HEAD`, where `$BASE_BRANCH` is the base recorded in
+the stage-0 brief — never a hardcoded `main`), dispatch the whole-branch review
 ([`review.md`](review.md) → *Final review*; on the run's model, escalation offered
 out loud per *Models* above), and point it at the
 ledger's deferred-minor and parked lines so it can triage what must be fixed before

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

@@ -12,6 +12,7 @@ better, plus one that is required only for user-facing work.
 
 | Stage | Doctrine |
 |---|---|
+| 0 Knowledge harvest (pre-grill) | `references/knowledge-sources.md` |
 | 0 Intake grill | `references/grill.md` |
 | 2 Brainstorm | `references/brainstorm.md` |
 | 2 Decompose (platforms only) | `references/decomposition.md` |
@@ -20,6 +21,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 + any audit (finding what's missing) | `references/audit.md` |
 | any repeating loop | `references/loop-guard.md` |
 
 ## The matrix
@@ -28,7 +30,7 @@ better, plus one that is required only for user-facing work.
 |---|---|---|---|
 | **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
 | **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
-| **wiki-update** | stage 9 wiki sync | Optional (skip wiki if absent) | user's wiki skill set |
+| **[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` |
 | ~~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`) | — |
 
@@ -60,7 +62,11 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
                            /plugin marketplace add ssheleg/super-ux
                            /plugin install super-ux@super-ux
   ✓ context7           — ready
-  ✓ wiki-update        — ready
+  ✗ obsidian-wiki      — recommended: stage 0 queries it before grilling you,
+                         stage 9 syncs back what this run learned:
+                           pip install obsidian-wiki
+                           obsidian-wiki setup --vault /path/to/your/vault
+                         (running without it — the harvest uses repo docs only)
 
 🧠 Model for this run: recommended <top tier available>. You're on <current>.
    /model <id> to switch, or "keep current", or name per-stage overrides.
@@ -72,6 +78,10 @@ Rules:
 
 - Only flag **super-ux** when the task implies a UI (the stage-0 grill decides;
   when unsure, flag it — a false positive costs one install).
+- **obsidian-wiki**: detect via `~/.obsidian-wiki/config` or a resolving
+  `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)).
 - **Never gate any stage on an install** except the stage-3 UX track on a UI task.
 - Optional tools missing → state the fallback, don't block.
 - Re-detect after the operator installs; don't assume.

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

@@ -1,7 +1,10 @@
-# Host conventions (stages 6–10)
+# Host conventions (stage 0 harvest, stages 6–10)
 
 The orchestrator is project-agnostic. For tests / lint / deploy / docs / wiki it reads the
 **host project's `CLAUDE.md` / `AGENTS.md` first**, then falls back to detection.
+The same files are the stage-0 harvest's first stop — they are where a project
+names its doc repos, its knowledge base and its house rules
+([`knowledge-sources.md`](knowledge-sources.md)).
 Prefer explicit host instructions over detection; if a step's convention can't be
 found, surface it and **ask** rather than guessing.
 
@@ -30,9 +33,20 @@ found, surface it and **ask** rather than guessing.
   CI: the workflow run. Hit the health endpoint if one is defined.
 
 ## Docs + wiki
+- **Start from the stage-0 source ledger** ([`knowledge-sources.md`](knowledge-sources.md)):
+  the sources the harvest read are the sources this stage updates. Anything the run
+  proved stale is already listed there with what's wrong.
 - Host self-update rules (module docs, runbooks, agent-self cards, etc.) — update
-  in the same change. Wiki: the `wiki-update` skill (resolves the vault via
-  `~/.obsidian-wiki/config`). Fix dangling links.
+  in the same change. Fix dangling links.
+- **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
+  (`pip install obsidian-wiki` → `obsidian-wiki setup --vault <path>`) and continue.
+  A project may of course use a different knowledge base — then its own
+  `CLAUDE.md` names the sync command, and that wins.
+- **Docs in another repository** (a docs repo, a submodule, a sibling checkout the
+  project names): updating it is **outward** — propose the change, get an explicit
+  operator go, open a PR there. Never push to a repo the task didn't name.
 
 ## Issue tracker (stage 10)
 

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

@@ -12,7 +12,27 @@ coming back to the operator.
 > half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
 > autonomy sweep and the brief are this pipeline's.
 
-## The loop
+## Phase 1 — harvest before you ask
+
+**Do not open the interview cold.** Stage 0 begins by finding what the project
+already knows about this task: the code, `CLAUDE.md`, `CONTEXT.md` and the ADRs,
+`docs/` and `docs/ux/`, past pipeline briefs, the **knowledge wiki** when one is
+installed, and any **other repository or hosted doc system the project names as
+its docs**. Full procedure, source order, the wiki's detection and install line,
+and the ledger to write: [`knowledge-sources.md`](knowledge-sources.md).
+
+Two things come out of it, both required before question one:
+
+- the **source ledger** in the brief — one row per source consulted, what it says
+  about this task, and how fresh it is (`no sources found` is a valid row);
+- the list of things you therefore **don't need to ask**, and the specific points
+  where a source looks stale or ambiguous — those become the sharpest questions.
+
+Everything below runs against that harvest. An answer you can't check against a
+source is a recollection, and the whole loop exists to stop the run from building
+on one.
+
+## Phase 2 — the loop
 
 Interview the operator relentlessly about every aspect of the task until you reach
 a **shared understanding**. Walk down each branch of the decision tree, resolving
@@ -73,6 +93,15 @@ Create these files **lazily** — only when you have something real to write.
   check whether the code agrees, and surface contradictions: *"Your code cancels
   entire Orders, but you just said partial cancellation is possible — which is
   right?"*
+- **Cross-reference with the harvest — every answer, not just the domain ones.**
+  Phase 1 put the ADRs, runbooks and wiki pages in your hands; use them the same
+  way: *"The March ADR says orders are written only through the command handler,
+  you just described a direct write — has that changed?"* 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. When two sources
+  disagree, precedence is code > host docs/ADRs > wiki > memory, and the loser is
+  logged for the stage-9 update ([`knowledge-sources.md`](knowledge-sources.md) →
+  *Phase 2*).
 - **Update `CONTEXT.md` inline.** Resolve a term → write it down right then, not in
   a batch at the end. Format: [`templates/context.md`](../templates/context.md).
   Keep it free of implementation detail — only terms a domain expert would
@@ -101,6 +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) |
 | 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 |
@@ -153,9 +183,12 @@ that shrank without anyone deciding it should.
 Everything resolved goes into the **task brief**, seeded from
 [`templates/brief.md`](../templates/brief.md) and committed to
 `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` — scope, **the REQ table**,
-users, UI verdict, constraints, locked decisions, the autonomy table,
-done-criteria, open assumptions. Seed the template only when the file is absent;
-never overwrite an existing brief.
+**the phase-1 source ledger**, users, UI verdict, constraints, locked decisions,
+the autonomy table, done-criteria, open assumptions. Seed the template only when
+the file is absent; never overwrite an existing brief.
+
+The ledger is not decoration: **stage 9 updates exactly what stage 0 read**, and
+every doc the grill proved stale is already listed there with what's wrong.
 
 Alongside it, seed the **carry-over ledger** from
 [`templates/carryover.md`](../templates/carryover.md) at

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

@@ -0,0 +1,159 @@
+# Knowledge sources — harvest before the grill, update after the build
+
+Stage 0 has two phases. This file is **phase 1**: before the first question is
+asked, find and read what the project already knows about this task. The interview
+([`grill.md`](grill.md)) is phase 2, and it runs *against* what was harvested here.
+
+The same source list closes the loop at **stage 9**: what was read at the start is
+what gets updated at the end. A source good enough to answer a question is a source
+that goes stale when the answer changes.
+
+## Why this is a phase and not "explore a bit first"
+
+An agent that starts asking without harvesting spends the operator's turns on
+questions the project already answered — in an ADR, in a runbook, in a wiki page
+written three months ago by the same person now being asked. That is the expensive
+failure, but not the worst one.
+
+The worst one is silent: **the operator misremembers, the agent believes them, and
+the run builds on it.** People answer from memory about systems they wrote a year
+ago. Without the documents in hand you cannot tell a decision from a recollection,
+so every later gate passes honestly on a false premise. Harvesting first is what
+makes the grill's answers *checkable* instead of merely confident.
+
+## The sources, in the order to try them
+
+| # | 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 |
+
+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
+  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 knowledge wiki — recommended
+
+The wiki this pipeline is built to work with is
+**[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (Karpathy's LLM-wiki
+pattern: raw sources → distilled wiki → schema). It is the one source that carries
+*why* across projects and across months, which is exactly what a fresh context lacks.
+
+**Detect it** — any of: `~/.obsidian-wiki/config` exists; the `wiki-query` /
+`wiki-update` skills resolve.
+
+- **Installed → use it.** Query it during the harvest (`wiki-query`, or the vault's
+  `index.md` + a targeted grep when the skill isn't loaded), and sync back at stage
+  9 (`wiki-update`).
+- **Not installed → recommend it once, in the preflight block, with the line:**
+
+  ```
+  pip install obsidian-wiki
+  obsidian-wiki setup --vault /path/to/your/vault
+  ```
+
+  Then continue without it. It is a **recommendation, never a gate** — no stage
+  blocks on a missing wiki, and the pipeline never nags twice in a run.
+
+## How to harvest — retrieval, not reading
+
+The harvest is bounded by the *task*, not by the size of the sources. You are not
+reading the wiki; you are asking it about this task.
+
+1. **Take the task's nouns** — the entities, the feature name, the subsystem, the
+   file paths the operator mentioned — plus their obvious synonyms.
+2. **Query each source with those terms**: `wiki-query` for the wiki; `grep`/`Read`
+   for repo docs; the tracker/hosted-doc tool if one is connected.
+3. **Follow one hop, not ten.** A hit that names an ADR, a scenario id or a module
+   is worth opening. A page three links away is context, not evidence.
+4. **Stop when the terms stop returning anything new.** Same rule as the interview:
+   no grinding past diminishing returns.
+
+## Record it — the source ledger
+
+Write what you found into the brief's **Knowledge sources** section
+([`templates/brief.md`](../templates/brief.md)) before the first question. One row
+per source actually consulted:
+
+| Source | What it says about this task | Fresh? | Authority |
+|---|---|---|---|
+| `docs/adr/0007-single-write-model.md` | orders are written only through the command handler | 2026-03 | decision |
+| wiki: `projects/x/concepts/billing-seams` | why invoicing was split out; the retry rule | 2026-06 | context |
+| `CLAUDE.md` | test = `npm test`, deploy from `main` only | current | convention |
+| (none for the export UI) | — | — | — |
+
+The ledger is what makes phase 2 work: during the interview you cite rows from it,
+and at stage 9 you update the same rows. A source consulted but not recorded is a
+source nobody will update.
+
+**"No sources found" is a valid, recorded outcome.** Write the row. An empty ledger
+tells the next run that the search happened and came back empty — silence doesn't.
+
+## Phase 2 — validate the answers against the harvest
+
+This is the payoff, and it belongs to the grill loop
+([`grill.md`](grill.md) → *Domain awareness*). Every operator answer that touches a
+harvested source gets checked against it, on the spot:
+
+> "The ADR from March says orders are written only through the command handler —
+> you just described a direct write. Has that changed, or should the export go
+> through the handler?"
+
+Three shapes and what to do with each:
+
+| The answer… | Do |
+|---|---|
+| **agrees** with the source | nothing — note it, move on |
+| **contradicts** a source | quote the source, name the conflict, ask which governs. The answer is either "the doc is stale" (→ it gets updated at stage 9, log it now) or "I misremembered" (→ the doc stands). Both are cheap here and expensive at stage 6 |
+| **goes beyond** every source | this is new knowledge — it belongs in the brief, and usually in `CONTEXT.md` or an ADR as it lands |
+
+**The operator outranks the docs — but only out loud.** A person may overrule any
+document; they may not do it by accident. The point of quoting the source is that
+the override becomes a recorded decision instead of an undetected divergence.
+
+**Precedence when two sources disagree with each other:** code > host docs and
+ADRs > the wiki > anyone's memory. The wiki is *distilled* knowledge and can lag
+the repo by months; the code is what runs. A disagreement between them is a grill
+question, never a silent pick — and it is usually a sign the doc is due an update.
+
+## Close the loop — stage 9 updates what stage 0 read
+
+The ledger is the stage-9 work list. For each row:
+
+- **Host repo docs, ADRs, runbooks, `docs/ux/`** — updated in the **same change**,
+  per the host's own rules ([`conventions.md`](conventions.md)).
+- **Anything the run proved stale** — including a doc that was "wrong but nobody
+  had time": that's why the conflict was logged in phase 2 instead of only being
+  resolved verbally.
+- **The wiki** — `wiki-update` syncs what this run learned. Distil the *knowledge*
+  (decisions, seams, gotchas, why), never a diff summary.
+- **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.
+
+A source that was worth reading at stage 0 and is wrong at stage 9 is the next
+run's false premise. Closing that loop is the whole point of harvesting from a
+written list instead of from whatever the search happened to surface.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "I'll just ask them, it's faster" | You'll ask about things a doc already answers, and you'll believe an answer you can't check. Retrieval is cheaper than a turn. |
+| "The wiki's probably stale" | Then say so with the page in hand and get it corrected. "Probably stale" unread is an assumption; read, it's a finding. |
+| "No docs in this repo" | Check `CLAUDE.md` for the repo that has them, and the wiki for the last time anyone touched this. Then record the empty ledger. |
+| "The operator knows their own system" | They do — a year ago, before three other people changed it. That's the exact case where quoting the doc pays. |
+| "Reading the whole wiki costs too much" | The harvest is a query per task noun, not a read. If it feels expensive, you're reading instead of retrieving. |
+| "I'll update the docs at the end from memory" | The ledger exists because the end is exactly when you no longer remember which sources you leaned on. |

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -10,6 +10,14 @@ the pipeline: the stage-5 fix loop, a stage re-entered after a failed gate, the
 per-module program loop ([`decomposition.md`](decomposition.md)), and any
 audit → fix → audit cycle.
 
+**This file governs loops that *change* things.** A loop that *looks* for things —
+pass after pass over one corpus — fails differently: it does not oscillate, it
+**converges**, quietly spending each pass on the previous pass's own edits while the
+finding count stays healthy. That has its own detector and its own exit (rotate the
+axis, don't push harder): [`audit.md`](audit.md) → *Every pass changes the axis*.
+Both can bind one run. Use this file's trips for edits, that file's crossover for
+searches.
+
 ## Bookkeeping — the thing that makes detection mechanical
 
 You cannot detect churn from memory, especially after compaction. Every repeating

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

@@ -21,9 +21,11 @@ brief and the spec.
 
 ## Before writing tasks
 
-**Scope check.** If the spec covers several independent subsystems, split it into
-one plan per subsystem; each plan must produce working, testable software on its
-own.
+**Scope check.** A plan covers exactly **one** spec — for a decomposed platform,
+one module's dossier ([`decomposition.md`](decomposition.md)). If the spec in front
+of you covers several independent subsystems, the decomposition was missed at stage
+2: say so and go back there for a module map, rather than inventing the split here.
+Whatever this plan covers must produce working, testable software on its own.
 
 **Map the file structure.** List every file that will be created or modified and
 what each one owns. This is where decomposition gets locked in:

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

@@ -29,7 +29,8 @@ this plan's git-ignored directory, `.task-pipeline/build/<plan-basename>/` — s
 `BASE` is the commit you recorded **before** dispatching the implementer — never
 `HEAD~1`, which silently drops every commit but the last of a multi-commit task.
 For a scoped re-review, `BASE` is the head the previous review saw. For the final
-review, `BASE` is `git merge-base main HEAD`.
+review, `BASE` is `git merge-base "$BASE_BRANCH" HEAD` — the base branch recorded
+in the stage-0 brief, which is not always `main`.
 
 Never dispatch a reviewer without a diff file.