task-pipeline-skill 0.17.1 → 1.0.0

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.0.0",
   "author": {
     "name": "ssheleg"
   },

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

@@ -5,15 +5,25 @@ 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;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —

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) |
@@ -86,7 +91,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 +125,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
@@ -155,7 +177,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,7 +186,7 @@ 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 |
+| 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/acceptance.md`](references/acceptance.md) | every REQ accounted for with evidence; ledger has no unresolved row; operator signs off | manual |
 
 ## Model — ask once, at preflight
@@ -198,6 +220,7 @@ 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/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
@@ -211,3 +234,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"
       }
     },
     {

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

@@ -63,8 +63,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
 

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,34 @@ 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
+      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
 ```

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

@@ -304,7 +304,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` |
@@ -28,7 +29,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 +61,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 +77,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/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.