task-pipeline-skill 0.17.1 → 1.1.0

package/cursor/rules/task-pipeline.mdc

@@ -28,16 +28,42 @@ recommended tier isn't available, say which one you're using and continue.
 
 Never skipped, and nothing to install — the grill is part of this rule. No "the
 task was already clear" exemption, no starting stage 1 while the user thinks. A
-one-line task ("build feature X") is not enough to finish autonomously. Grill the
-user up front, then run the rest without mid-flight questions:
+one-line task ("build feature X") is not enough to finish autonomously.
+
+**Phase 1 — harvest the sources BEFORE the first question.** Find what the project
+already knows about this task and read it: the code; `CLAUDE.md` / `AGENTS.md`;
+`CONTEXT.md` (or `CONTEXT-MAP.md`) and `docs/adr/`; `docs/` and `docs/ux/`; past
+briefs/plans and their carry-over ledgers; **the knowledge wiki if one is
+installed** — [obsidian-wiki](https://github.com/ar9av/obsidian-wiki), detect
+`~/.obsidian-wiki/config` or a resolving `wiki-query`; and **any other repository
+or hosted doc system the project names as its docs** (read-only, and never a source
+you invented — it counts because the project names it). Query each by *this task's*
+nouns; it is retrieval, not a full read; stop when the terms return nothing new.
+Write a short **source ledger** into the brief — source, what it says about this
+task, how fresh, and whether this run makes it stale. `none found` is a valid row.
+If no wiki is installed, recommend it once and continue:
+`pip install obsidian-wiki` → `obsidian-wiki setup --vault <path>`. It is never a
+gate.
+
+**Phase 2 — grill the user against that harvest**, then run the rest without
+mid-flight questions:
 1. One question per turn — never bundle.
 2. Give a recommended answer with every question (+ one-line rationale).
 3. Explore the codebase before asking — if a search/read answers it, do that.
-4. Walk the decision tree depth-first; ask prerequisite decisions first.
-5. Reconcile contradictions; chase dodges ("decide later" → "latest you can decide
+4. **Validate every answer against the harvest.** When what the user says
+   contradicts a doc you read, quote the doc and ask which governs: *"the March ADR
+   says X, you just described Y — has it changed?"* The user **outranks every
+   document, but only out loud** — an override quoted against its source is a
+   recorded decision; an unquoted one is an undetected divergence that every later
+   gate will pass over. When two sources disagree: code > host docs/ADRs > wiki >
+   memory. Whichever side loses, if it's written down somewhere, log it for the
+   stage-9 doc update.
+5. Walk the decision tree depth-first; ask prerequisite decisions first.
+6. Reconcile contradictions; chase dodges ("decide later" → "latest you can decide
    and still ship?").
-6. Run the **autonomy sweep** — resolve now whatever would stop stages 1→10 later:
-   external libs and where their docs live; UI verdict; base branch, branch policy,
+7. Run the **autonomy sweep** — resolve now whatever would stop stages 1→10 later:
+   external libs and where their docs live; **which doc sources beyond this repo are
+   in play and whether stage 9 may write to them**; UI verdict; base branch, branch policy,
    commit convention, task tracker; the test command and what "green" means; the
    lint command; the deploy target, release toggle and **deploy authorization**;
    where logs/health live; which docs and runbooks this change updates. Each item
@@ -127,16 +153,39 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    the stage-0 brief.
 8. **Post-deploy** (auto) — tail logs / health-check; clean boot or an honest
    degradation report (never silent success).
-9. **Docs + wiki** (auto) — update module docs/runbooks in the SAME change, and
-    sync the project's knowledge base/wiki if it has one.
-10. **Acceptance** (manual) — the closing stage: go back to the brief and account
-    for **every** REQ. One row each, status `verified` / `partial` / `deferred` /
-    `dropped`, and every `verified` carries **evidence** — a passing test name, a
-    `file:line`, a command and its output. "Done" without evidence is downgraded to
-    `partial`, never upgraded. Then ask out loud, list in hand: *here's what you
-    asked for, here's what shipped, here's what's deferred and where it lives —
-    what's missing?* Ask it even when the table is green. Gate: no REQ `unknown`,
-    no ledger row without a home, user signs off.
+9. **Docs + wiki** (auto) — **the phase-1 source ledger is the work list**: every
+    source the harvest read gets updated if this run changed or disproved it. Module
+    docs and runbooks in the SAME change; the knowledge wiki via `wiki-update` when
+    [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) is installed (absent →
+    recommend once, never block). Docs in **another repository** are outward:
+    propose the edit and get an explicit go, or carry it over with the exact change
+    written down. A doc that was worth reading at stage 0 and is wrong now is the
+    next run's false premise.
+10. **Acceptance** (manual) — the closing stage, in two halves.
+    **First the ladder walk**, because the REQ table only finds what was named and
+    lost: a comparison needs two sides and **an absence has one**. Walk each REQ
+    bottom-up through its rungs — recorded decision → spec section → contract *and
+    its failure behavior* → plan task with a satisfiable DoD → the change in the
+    tree → an **executed** named assertion → the surface a user reaches, and its
+    docs — checking the seam between each pair: does the decision reach the spec;
+    does the section say what happens when the contract fails; does every contract
+    have a task; did the DoD land in the diff; would that test still pass with the
+    production code deleted; can a user reach this and does a doc say so; and
+    finally, does what shipped satisfy the requirement's own *statement* rather
+    than the task's instructions. Order findings **by seam, not by file** — the
+    seam tells you which layer of your process leaks. Every absence becomes a new
+    REQ row with its check **before** the table is written; appending afterwards is
+    how acceptance goes green over a gap. Findings owned by a lower layer go back
+    there (spec → stage 3, plan → stage 4).
+    **Then the table:** one row per REQ, status `verified` / `partial` /
+    `deferred` / `dropped`, and every `verified` carries **evidence** — a passing
+    test name, a `file:line`, a command and its output. "Done" without evidence is
+    downgraded to `partial`, never upgraded, and **a green from a check nobody has
+    watched fail against a planted defect is not evidence at all**. Then ask out
+    loud, list in hand: *here's what you asked for, here's what shipped, here's
+    what's deferred and where it lives — what's missing?* Ask it even when the
+    table is green. Gate: ladder walk ran, no REQ `unknown`, no ledger row without
+    a home, user signs off.
 
 Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step
@@ -161,6 +210,32 @@ no opportunistic edits. Re-check the list once in the same order at the end. If
 trips again after a re-planned pass, stop and hand back with both shapes, the
 evidence and your recommendation.
 
+**Audit rules — for loops that *look* rather than edit.** A searching pass doesn't
+oscillate, it **converges**: each pass edits the corpus the next pass reads, so the
+newest edits are the least-reviewed text and are what the next pass finds. Measured
+over seven passes on a real repository, by pass six the audit was mostly repairing
+its own previous pass while the finding count still looked healthy. So:
+- **Count two numbers every pass** — new findings, and findings caused by the last
+  pass's own fixes. When the second overtakes the first, the axis is exhausted:
+  **rotate the axis, don't look harder.** The axes are orthogonal by construction —
+  seams down one deliverable (the ladder above), then invariants *across*
+  deliverables (one name, one enum, one owner everywhere), then one class swept end
+  to end (every error path, every count, every status vocabulary).
+- **Audit bottom-up.** A missing artefact at a low rung makes everything above it
+  meaningless; top-down you polish a surface for a contract that doesn't exist.
+- **A class that repeats twice becomes a check, not a note.** Once is an incident;
+  twice is a category, and a category belongs in lint or CI where nobody has to
+  remember it. The third instance in a ledger is how a mechanical defect becomes
+  permanent.
+- **What can't be fixed now becomes a ratchet, never a TODO** — a named, counted
+  set that may only shrink, **printed beside every gate verdict**
+  (`carry-over: 4 open (was 6) · unresolved: 0`). A TODO is invisible until someone
+  opens the file; a ratchet makes "green" read as *"green, and here is exactly what
+  was not looked at"*. If it grew, one sentence says why.
+- **Never trust an unproven check.** Plant the defect, watch the check fail, remove
+  it, then trust the green — same law as the failing test, applied to every gate,
+  linter and script the run leans on.
+
 ## super-ux for user-facing tasks (recommended)
 
 If the task touches any UI (web/mobile/CLI/TUI), the WHY→UI→scenario chain comes

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "task-pipeline-skill",
-  "version": "0.17.1",
-  "description": "Full-cycle task delivery pipeline orchestrator skill for Claude Code — a mandatory built-in intake grill + 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance) whose doctrine ships inside the skill with no required companion plugin, plus a super-ux UX track for user-facing tasks and toggleable release automation. This package is the installer CLI.",
+  "version": "1.1.0",
+  "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
+  "scripts": {
+    "test": "python3 test/validate.py"
+  },
   "files": [
     "bin",
     "plugins",
@@ -14,7 +17,8 @@
     "CHANGELOG.md"
   ],
   "repository": "github:ssheleg/task-pipeline",
-  "homepage": "https://github.com/ssheleg/task-pipeline",
+  "homepage": "https://github.com/ssheleg/task-pipeline#readme",
+  "bugs": "https://github.com/ssheleg/task-pipeline/issues",
   "license": "MIT",
   "author": "ssheleg",
   "engines": {

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

@@ -1,7 +1,7 @@
 {
   "name": "task-pipeline",
-  "description": "Self-contained orchestrator that runs a task through a mandatory built-in intake grill + 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a loop guard that breaks churn, one provider-agnostic model confirmed up front, a super-ux UX track for user-facing tasks, and toggleable project-configurable release automation.",
-  "version": "0.17.1",
+  "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
+  "version": "1.1.0",
   "author": {
     "name": "ssheleg"
   },

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

@@ -5,17 +5,27 @@ argument-hint: <one-line task description>
 Use the `task-pipeline` skill to run the task below through all gated stages —
 **stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent
 build → tests → lint/deploy → post-deploy → docs/wiki → **acceptance**. **Every stage's doctrine is
-built into the skill** (`references/{grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,loop-guard}.md`)
-— no companion plugin is required for any of them. The **intake grill is
+built into the skill** (`references/{knowledge-sources,grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,loop-guard}.md`)
+— no companion plugin is required for any of them. **Stage 0 opens with the
+knowledge harvest, before the first question** (`references/knowledge-sources.md`):
+pull what the project already knows about this task from the code, `CLAUDE.md`,
+`CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the **knowledge wiki**
+if one is installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) —
+recommended, never required; detect `~/.obsidian-wiki/config`) and any **other repo
+or hosted doc system the project names as its docs**, then write the **source
+ledger** into the brief. The **intake grill is
 mandatory** (`references/grill.md`): interview the
 operator one question at a time (with a recommended answer each, exploring the
-codebase before asking) until every decision branch is resolved, applying the
+codebase before asking) until every decision branch is resolved, **validating every
+answer against the harvested sources** — the operator outranks any document, but
+only out loud, and a doc the run proves stale is logged for the stage-9 update —
+applying the
 grill's **domain awareness** (challenge terms against `CONTEXT.md`, sharpen fuzzy
 language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (what
-would otherwise stop stages 1→10: docs sources, branch/tracker policy, test and lint
-commands, deploy target and authorization, log locations, docs/wiki targets) —
+would otherwise stop stages 1→10: docs sources incl. doc repos and the wiki, branch/tracker
+policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets) —
 until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
-**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. Honor every stage gate by its type (`auto` = verify yourself;
+**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —
 recommend the most capable one the environment offers, never a hardcoded id — then
 run the whole pipeline on it without re-asking.

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

@@ -27,7 +27,11 @@ tabled below) and an optional, toggleable `release` block. Any project replaces
 wholesale — any number of stages, run by its own skills/agents, with its own gate
 types (see *Bring your own skills*). Each gate has a **type**: `auto` (the
 orchestrator verifies the `check` itself, pass/fail) or `manual` (wait for an
-explicit operator go); which stages are manual is the operator's call.
+explicit operator go); which stages are manual is the operator's call. In the
+example's `skills[]`, `task-pipeline:<name>` denotes this skill's own built-in
+doctrine (`references/<name>.md`) and `host:<name>` denotes the host project's own
+command for that job (`references/conventions.md`); everything else is a real skill
+the environment resolves.
 
 ## Prerequisites — none required
 
@@ -37,6 +41,7 @@ and no stage that can fail because a dependency is missing:
 
 | Stage | Built-in doctrine |
 |---|---|
+| 0 Knowledge harvest (pre-grill) | [`references/knowledge-sources.md`](references/knowledge-sources.md) |
 | 0 Intake grill | [`references/grill.md`](references/grill.md) |
 | 2 Brainstorm | [`references/brainstorm.md`](references/brainstorm.md) |
 | 2 Decompose (platforms only) | [`references/decomposition.md`](references/decomposition.md) |
@@ -45,6 +50,7 @@ and no stage that can fail because a dependency is missing:
 | 5 Build (worktree, subagents, fix loop) | [`references/build.md`](references/build.md) + [`references/review.md`](references/review.md) |
 | 5–6 TDD + suite gate | [`references/tdd.md`](references/tdd.md) |
 | 10 Acceptance (REQ close-out) | [`references/acceptance.md`](references/acceptance.md) |
+| 10 + any audit (what's *missing*) | [`references/audit.md`](references/audit.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
 
 **Optional bridge.** If the operator already runs an equivalent skill set (e.g.
@@ -86,7 +92,19 @@ requirements, each naming how it will be verified. Stages 3–5 trace to those i
 stage 4's gate is a mechanical set-comparison against them, and **stage 10 accounts
 for every one** — which is what turns the pipeline from a funnel into a circle.
 
-Two things the grill does beyond clarifying the request:
+**Harvest before you ask.** Stage 0 opens with a **knowledge harvest**
+([`references/knowledge-sources.md`](references/knowledge-sources.md)), not a
+question: pull what the project already knows about this task from the code,
+`CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, the
+**knowledge wiki** if one is installed
+([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never
+required) and any **other repo or hosted doc system the project names as its
+docs**. Write the source ledger into the brief, then interview *against* it: every
+answer that touches a source is checked against that source, and the operator
+outranks any document — but only out loud, so an override is a recorded decision
+instead of an undetected divergence. The same ledger is stage 9's work list.
+
+Three things the grill does beyond clarifying the request:
 - **Domain awareness.** It reads the project's own `CONTEXT.md` / `docs/adr/` and
   holds the operator to them — challenging terms that conflict with the glossary,
   sharpening overloaded words, stress-testing with concrete scenarios, and
@@ -108,8 +126,13 @@ Two things the grill does beyond clarifying the request:
    **and the model decision** (`references/model-tiering.md`): recommend
    the most capable model available, let the operator confirm or override, record
    it. Ask once, here.
-2. **Run stage 0 (Intake grill) — always, no exceptions.** Grill until shared
-   understanding is reached, the autonomy sweep is covered, **the REQ table is
+2. **Run stage 0 — always, no exceptions.** It opens with the **knowledge harvest**
+   (`references/knowledge-sources.md`): query the project's own sources — repo docs,
+   ADRs, `docs/ux/`, past briefs, the wiki if installed, any doc repo the project
+   names — for this task's terms, and write the **source ledger** into the brief
+   before question one. Then grill until shared
+   understanding is reached, **each answer checked against the harvest**, the
+   autonomy sweep is covered, **the REQ table is
    written (one row per independently verifiable deliverable, each naming its
    check)** and the brief is locked
    (`references/stages.md` → 0). Do not touch stage 1 before the brief is
@@ -140,7 +163,10 @@ Two things the grill does beyond clarifying the request:
    third entry into one stage — stop and run the loop guard**
    (`references/loop-guard.md`): name the two shapes, escalate to the layer that
    owns the conflict, re-plan the check as an ordered list, then go through it one
-   item at a time; task
+   item at a time; **when a pass is *searching* rather than editing and starts
+   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
+   rotate it, don't look harder** (`references/audit.md`), and remember that a
+   green from a check nobody has watched fail is not evidence; task
    tracker + conventional commits per host conventions; worktree isolation for the
    build, integrated back per the brief's branch policy before stage 7; honest
    degradation (never claim a failed/skipped step succeeded);
@@ -155,7 +181,7 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Invoke | Gate | Type |
 |---|---|---|---|---|
-| 0 | Intake grill — **mandatory** | built in: [`references/grill.md`](references/grill.md) | shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
+| 0 | Intake grill — **mandatory** | built in: [`references/knowledge-sources.md`](references/knowledge-sources.md) (harvest) → [`references/grill.md`](references/grill.md) (interview) | source ledger written; shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
 | 1 | Docs study | `context7` (resolve-library-id → get-library-docs) / `context7-docs` | contracts grounded on fetched docs | auto |
 | 2 | Brainstorm + decompose | built in: [`references/brainstorm.md`](references/brainstorm.md) + **UI detection** + [`references/decomposition.md`](references/decomposition.md) for platforms | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | built in: [`references/spec.md`](references/spec.md) — **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
@@ -164,8 +190,8 @@ capable available — see `references/model-tiering.md`).
 | 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) | full suite green; new/changed code covered | auto |
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
-| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` | docs synced, wiki synced | auto |
-| 10 | **Acceptance** | built in: [`references/acceptance.md`](references/acceptance.md) | every REQ accounted for with evidence; ledger has no unresolved row; operator signs off | manual |
+| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced | auto |
+| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; operator signs off | manual |
 
 ## Model — ask once, at preflight
 
@@ -198,8 +224,10 @@ automation is on — `pipeline.schema.json` is the only contract.
 
 - `pipeline.schema.json` — the universal pipeline config contract (stages + release)
 - `pipeline.example.json` — this plugin's default flow (stage 0 + 1→10) + release, as config
+- `references/knowledge-sources.md` — stage-0 phase 1: the source list, the wiki, the ledger, the stage-9 loop-back
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
+- `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
 - `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
 - `references/spec.md` — stage 3: UX track order, the spec contract, self-review, review gate
 - `references/planning.md` — stage 4: zero-context plan format, parallel groups, no placeholders
@@ -211,3 +239,6 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/conventions.md` — how stages 6–10 read the host project's CLAUDE.md
 - `references/companion-skills.md` — companion skills, install lines, preflight recommendation
 - `references/artifacts.md` — the canonical document/artifact layout per stage
+- `templates/` — skeletons seeded into the host project: `brief.md` (stage 0),
+  `carryover.md` (seeded at 0, appended by every stage, read in full at 10),
+  `context.md` and `adr.md` (format references the grill writes lazily)

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. 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). 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,11 +9,13 @@
       "name": "Intake grill",
       "model": "default",
       "skills": [
+        "task-pipeline:knowledge-harvest",
+        "wiki-query",
         "task-pipeline:grill"
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). The grill is 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; 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) 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, 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) 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."
       }
     },
     {
@@ -50,9 +52,11 @@
       "name": "Spec",
       "model": "default",
       "skills": [
+        "super-ux:ux",
         "super-ux:ux-foundation",
         "super-ux:ux-flows",
         "super-ux:ux-scenarios",
+        "super-ux:ux-lint",
         "task-pipeline:spec"
       ],
       "gate": {
@@ -139,7 +143,7 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "docs in sync with code in the same change; wiki synced; 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); docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed"
       }
     },
     {
@@ -148,11 +152,12 @@
       "name": "Acceptance",
       "model": "default",
       "skills": [
+        "task-pipeline:audit",
         "task-pipeline:acceptance"
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle: every REQ in the brief 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; 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 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'; 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"
       }
     }
   ],

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

@@ -18,10 +18,34 @@ run itself decided, deferred, or quietly dropped along the way.
 It runs **last** — after docs and wiki (stage 9), because those are deliverables
 too and a requirement may name them.
 
+## First, the ladder walk — what the list itself is missing
+
+The REQ table answers *"did everything on the list ship?"*. It cannot answer
+*"should something else have been on the list?"* — a comparison needs two sides,
+and an absence has one.
+
+So **before writing the coverage table**, walk the ladder in
+[`audit.md`](audit.md): each REQ bottom-up through its rungs (decision → spec
+section → contract **and its failure behavior** → task → change → executed test →
+surface and docs), checking the seam at each step. It is one pass, scoped to this
+run's deliverables, and it is the only part of the pipeline that can find a gap
+that was never a row.
+
+- **An absence found here becomes a new REQ row with its check**, then the table is
+  written. The list is frozen against *narrowing*, never against additions
+  ([`grill.md`](grill.md) → *The REQ spine*). Writing the table first and appending
+  afterwards is how acceptance goes green over a gap.
+- **A finding that belongs to a lower layer goes back to that layer** — spec gaps to
+  stage 3, plan gaps to stage 4 — rather than being patched in place at stage 10.
+- **Report the audit's two counts** (new findings; findings caused by this run's own
+  fixes) in the ledger. They are what tells the next pass whether the axis is
+  exhausted (`audit.md` → *Every pass changes the axis*).
+
 ## Inputs
 
 Read all of them before writing anything:
 
+- the ladder walk's findings (above) — they may have added REQ rows
 - the brief's **REQ table** (`docs/superpowers/specs/<topic>-brief.md`)
 - the **carry-over ledger** (`…-carryover.md`) — in full, every row
 - the plan and its task statuses
@@ -63,8 +87,9 @@ Run: <branch/commit range> · Date: YYYY-MM-DD
 | `deferred` | agreed not to do it now | the operator's agreement **and** a tracker entry |
 | `dropped` | agreed it isn't wanted | the operator's agreement + the reason |
 
-There is no fifth status. A requirement nobody can classify is `unknown`, and
-`unknown` fails the gate — that is the whole mechanism.
+Those four are the only ways a requirement may close. Anything that fits none of
+them is `unknown`, and **`unknown` fails the gate** — that is the whole mechanism:
+the run cannot end while a requirement is still unclassified.
 
 ## Evidence, not assertion
 
@@ -96,13 +121,20 @@ whether the run was finished.
 
 All of:
 
-1. **Every REQ has a status** — none `unknown`, none blank.
-2. **Every `verified` carries evidence** of the kind above.
-3. **Every `partial` names what's missing** and where it's tracked.
-4. **Every `deferred` / `dropped` has the operator's agreement** recorded (in the
+1. **The ladder walk ran** ([`audit.md`](audit.md)) — every REQ's rungs checked
+   bottom-up, findings ordered by seam, absences turned into REQ rows **before**
+   the table was written, and the two pass counts recorded.
+2. **Every check this gate leans on has been seen failing** at least once against a
+   planted defect (`audit.md` → *Exit criterion*). An unproven check's green is not
+   evidence.
+3. **Every REQ has a status** — none `unknown`, none blank.
+4. **Every `verified` carries evidence** of the kind above.
+5. **Every `partial` names what's missing** and where it's tracked.
+6. **Every `deferred` / `dropped` has the operator's agreement** recorded (in the
    ledger or here) and, for `deferred`, a tracker entry.
-5. **No carry-over row is left `unresolved`** — every one has a home.
-6. **The operator answers the closing question** and signs off.
+7. **No carry-over row is left `unresolved`** — every one has a home, and the
+   ledger's counts are printed with this verdict, not just filed.
+8. **The operator answers the closing question** and signs off.
 
 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

@@ -53,6 +53,7 @@ record (see `build.md`).
 
 | Stage | Writes | Consumed by |
 |---|---|---|
+| 0 Harvest | the brief's **Knowledge sources** ledger — every source consulted, its freshness, whether this run makes it stale | the grill (validation), **stage 9** (the update work list) |
 | 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 |
@@ -67,24 +68,35 @@ record (see `build.md`).
 ## This repo (task-pipeline itself), for reference
 
 ```
-.claude-plugin/marketplace.json              # marketplace manifest
+.claude-plugin/marketplace.json               # marketplace manifest
 plugins/task-pipeline/
-  .claude-plugin/plugin.json
+  .claude-plugin/plugin.json                  # plugin manifest
   commands/task-pipeline.md                   # /task-pipeline
   skills/task-pipeline/
-    SKILL.md
+    SKILL.md                                  # the orchestrator itself
     pipeline.schema.json                      # generic pipeline contract
     pipeline.example.json                     # this plugin's own flow, as config
-    references/{grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance}.md  # built-in stage doctrine
-    references/loop-guard.md                  # cross-cutting: churn detection + break protocol
-    references/{stages,model-tiering,conventions,artifacts,companion-skills}.md
+    references/                               # built-in stage doctrine:
+      knowledge-sources.md grill.md           #   stage 0 (harvest, then interview)
+      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
+      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
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
-plugins/task-pipeline/skills/task-pipeline/templates/{brief,carryover,context,adr}.md   # stage-0 skeletons (ship on every channel)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
-package.json
 install.sh                                    # POSIX installer
-test/validate.py                              # structural validator
-.github/workflows/{validate,release}.yml      # CI + toggleable release
-README.md  CHANGELOG.md  LICENSE
+test/validate.py                              # structural validator (npm test)
+.github/workflows/{validate,release}.yml      # CI + toggleable release automation
+.github/ISSUE_TEMPLATE/  .github/PULL_REQUEST_TEMPLATE.md
+package.json  .gitignore
+README.md  CHANGELOG.md  LICENSE  CLAUDE.md
+CONTRIBUTING.md  SECURITY.md  CODE_OF_CONDUCT.md
 docs/superpowers/{specs,plans}/               # this repo's own design history
 ```