task-pipeline-skill 0.12.0 → 1.0.0

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

@@ -0,0 +1,365 @@
+# Build — stage 5, built in
+
+Executing the plan: an isolated workspace, one fresh implementer subagent per task,
+a review after each task, a whole-branch review at the end. Built into this skill;
+nothing to install.
+
+> Ported from the `using-git-worktrees` and `subagent-driven-development` skills in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
+> *Third-party*), rewritten for this pipeline: no external scripts, the ledger
+> lives under `.task-pipeline/`, and model choice defers to the run's single
+> confirmed model ([`model-tiering.md`](model-tiering.md)).
+
+**Why subagents:** each task goes to an agent with a constructed context — its
+brief, its interfaces, the global constraints, nothing else. It never inherits the
+session's history, so it stays focused; your context stays free for coordination.
+
+**Continuous execution:** don't check in between tasks. The operator asked for the
+plan to be executed — execute it. Stop only for BLOCKED you can't resolve, a
+genuine ambiguity, or completion. "Should I continue?" between tasks is noise.
+
+**Narration:** at most one short line between tool calls. The ledger and the tool
+results are the record.
+
+**No subagents available?** (a harness without them, or a plan so small that
+dispatching costs more than it saves) — run the same loop inline: same isolation,
+same ledger, same TDD per task, and after each task review your own diff against
+the rubric in [`review.md`](review.md) before moving on. What changes is who does
+the work; the gates, the artifacts and the review discipline do not. Say plainly
+that the run is inline, since a self-review is weaker evidence than a fresh
+reviewer's.
+
+## 1. Isolation
+
+Work never starts on `main`/`master` without the operator's explicit consent
+(the stage-0 brief usually records the branch policy — read it, don't re-ask).
+
+**Detect existing isolation first:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
+git rev-parse --show-superproject-working-tree   # non-empty ⇒ submodule, not a worktree
+```
+
+- `GIT_DIR != GIT_COMMON` and **not** a submodule → you are already in a linked
+  worktree. Do not create another. Report the path and branch, go to *Setup*.
+- Otherwise you are in a normal checkout. Honor the brief's worktree preference; if
+  none was recorded, ask once before creating one.
+
+**Creating one — native tool first.** If the harness offers a worktree tool
+(`EnterWorktree`, a `/worktree` command, a `--worktree` flag), use it: it owns
+placement, branch creation and cleanup. Reaching for raw `git worktree add` when a
+native tool exists creates state the harness can't see or clean up.
+
+**Git fallback**, only when there is no native tool:
+
+```bash
+# both scratch roots MUST be ignored before anything is created
+git check-ignore -q .worktrees || printf '.worktrees/\n' >> .gitignore
+git check-ignore -q .task-pipeline || printf '.task-pipeline/\n' >> .gitignore
+git diff --quiet .gitignore || git commit -m "chore: ignore build scratch dirs" .gitignore
+git worktree add ".worktrees/$BRANCH" -b "$BRANCH"
+```
+
+Directory priority: an explicit operator preference → an existing `.worktrees/` →
+an existing `worktrees/` → default `.worktrees/`. An unignored worktree directory
+commits the entire tree into the repo — verify before creating. If creation fails
+on a sandbox permission error, say so plainly and work in place.
+
+**Setup + baseline.** Install dependencies the way the project does (`npm install`,
+`cargo build`, `pip install -r requirements.txt`, `poetry install`, `go mod
+download`), then run the test command from the brief's autonomy sweep. A dirty
+baseline makes every later failure ambiguous: report failures and let the operator
+decide whether to proceed.
+
+## 2. Workspace and ledger
+
+Conversation memory does not survive compaction. A controller that lost its place
+re-dispatches completed tasks — the most expensive failure this stage has.
+**Track progress in a file, not only in todos.**
+
+- Each plan owns a git-ignored workspace: `.task-pipeline/build/<plan-basename>/`
+  at the repo root. Everything for THIS plan lives there — ledger, task briefs,
+  implementer reports, review packages. Another plan's directory is never yours to
+  read or write. `.task-pipeline/` must be git-ignored — the isolation step above
+  adds and commits it; if you skipped that step, do it now, in its own commit, so
+  scratch files never land in a task's diff.
+- Ledger: `<workspace>/progress.md`, first line = its identity:
+  `# build ledger — plan: <plan file path>`.
+- **Resuming:** a task with a `Task <N>: complete` line is DONE — never
+  re-dispatch it; resume at the first task without one. A task whose last line is a
+  fix round is mid-loop: continue at the next round. A ledger naming a different
+  plan belongs to that plan — leave it and start your own.
+- After compaction, trust the ledger and `git log` over your recollection: the
+  commits it names exist even when your context no longer remembers them.
+
+Read the plan **once**, note its context and Global Constraints, create a todo per
+task.
+
+**Pre-flight conflict scan.** Before Task 1, scan the plan for tasks that
+contradict each other or the Global Constraints, and for anything the plan mandates
+that the review rubric ([`review.md`](review.md)) treats as a defect. Present
+everything you find as **one batched question** — each finding beside the plan text
+that mandates it, asking which governs. Clean scan → proceed silently.
+
+## 3. Models
+
+**Default: the run's one confirmed model** ([`model-tiering.md`](model-tiering.md))
+for every subagent — implementers, reviewers, fixers. Pin it explicitly on each
+dispatch; an omitted model silently inherits the session's and defeats whatever the
+operator recorded.
+
+**Deviate only from the operator's recorded override map.** If the stage-0 brief
+carries per-stage or per-role overrides, apply them: mechanical transcription tasks
+(the plan carries the complete code, 1–2 files) can take a cheaper tier, while
+integration, design and review work stays on the confirmed model. No map recorded →
+no deviation, and never a silent downgrade. Turn count beats token price: the
+cheapest tier routinely takes 2–3× the turns on multi-step work and costs more
+overall.
+
+**Two moments deserve more capability than the run's default** — both are
+*recommendations you state out loud*, never silent switches:
+
+- **The final whole-branch review.** If the run is on a tier below the most capable
+  one available, say so and offer to run this one review there; if the operator
+  declines or the tier doesn't exist, run it on the confirmed model and note it.
+- **Fix-loop rounds 4–5.** One tier above the implementer that got stuck, when the
+  environment has one and the override map or the operator allows it; otherwise
+  say so and rely on fresh eyes alone.
+
+## 4. The task loop
+
+Everything you paste into a dispatch prompt — and everything a subagent prints back
+— stays in your context for the rest of the session. **Hand artifacts over as
+files.**
+
+### 4.1 Dispatch the implementer
+
+Record `BASE=$(git rev-parse HEAD)` before dispatching; the review package and the
+fix-round diffs need it.
+
+**Write the task brief to a file** — extract the task's full text from the plan to
+`<workspace>/task-<N>-brief.md`. The brief is the single source of requirements;
+exact values (numbers, strings, signatures, test cases) live **only** there.
+Include the task's `Implements:` ids **with each REQ's one-line statement quoted
+verbatim** — an implementer who sees only an instruction optimises the
+instruction; one who sees the requirement behind it catches the case the
+instruction didn't cover.
+
+The dispatch prompt contains exactly five things:
+
+1. One line on where this task fits in the project.
+2. The brief path — "read this first; it is your requirements, use its values
+   verbatim".
+3. Interfaces and decisions from earlier tasks the brief can't know.
+4. Your resolution of any ambiguity you spotted in the brief.
+5. The report path (`<workspace>/task-<N>-report.md`) and the report contract.
+
+Never paste accumulated history ("state after tasks 1–3") into later dispatches.
+Never make a subagent read the whole plan. If an earlier task parked a finding in
+the area this task touches, carry a pointer to that ledger line.
+
+Record the implementer's agent identity: fix rounds 1–3 resume it.
+
+**Implementer contract** (put this in the prompt):
+
+> Read `<brief path>` first — it is your requirements. Work TDD, and no production
+> code exists before a test you **watched fail**: write the failing test → run it
+> and confirm it fails for the right reason → write the minimal code that passes →
+> run it and confirm it passes, with the rest of the suite still green → commit.
+> Assert on real behavior, never on mock behavior. Commit as you go, conventional
+> commits. When done, self-review your diff, then write the full report to
+> `<report path>`:
+> what you built, the files touched, the commits, the test command and its
+> output, decisions you made, anything you're unsure about. Return **only**:
+> status (`DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`), the
+> commit range, a one-line test summary, and your concerns. Ask before starting
+> if anything in the brief is ambiguous — questions are cheaper than rework.
+
+### 4.2 Parallel groups — when fan-out is allowed
+
+The plan's parallel groups ([`planning.md`](planning.md)) describe what *may* run
+concurrently. Whether it actually does is this stage's call, and the constraint is
+physical: **two implementers writing one working tree corrupt each other's state.**
+
+- **Default: sequential.** One implementer at a time, review after each. Correct for
+  every group, and always correct when the tasks are small.
+- **Fan out only when all three hold:** the tasks are in the same group (no
+  `depends:` between them), their file ownership is exclusive per the plan, and
+  **each implementer gets its own isolated worktree**. Then dispatch them together,
+  review each one against its own diff, and integrate the worktrees back to the
+  build branch one at a time, running the suite after each merge.
+- **Any conflict on integration** means the plan's file ownership was wrong: stop
+  fanning out, finish the group sequentially, and record it in the ledger.
+- Never fan out the fix loop — a task under repair belongs to one implementer.
+
+### 4.3 Handle the report
+
+| Status | Action |
+|---|---|
+| `DONE` | Build the review package, dispatch the task review ([`review.md`](review.md)). |
+| `DONE_WITH_CONCERNS` | Read the concerns first. Correctness or scope → resolve before review. Observations ("this file is getting large") → **append to the carry-over ledger**, then proceed. A concern that stays only in the report dies with the workspace. |
+| `NEEDS_CONTEXT` | Supply exactly what's missing, re-dispatch. |
+| `BLOCKED` | Diagnose: missing context → re-dispatch with it; needs more reasoning → a more capable model; too large → split the task; the plan itself is wrong → escalate to the operator. |
+
+**Never** ignore an escalation, and never re-dispatch the same model with the same
+prompt after a BLOCKED. If the implementer says it's stuck, something must change.
+If the implementer asks a question — before or mid-task — answer it completely; do
+not rush it into implementation.
+
+### 4.4 Review the task
+
+Every task gets a review with **all three** verdicts — spec compliance, **REQ
+satisfied**, and code quality. The implementer's self-review never substitutes for
+it. Rubric, inputs, prompt templates and how to build the diff package:
+[`review.md`](review.md).
+
+The REQ verdict is the one the other two can't produce: a task can meet every line
+of its brief and still miss the requirement it was written to deliver. A ❌ there
+enters the fix loop like any Important finding.
+
+A review may report **"cannot verify from diff"** items — requirements that live in
+unchanged code or span tasks. They don't block the review, but you resolve each one
+yourself before completing the task; you hold the cross-task context the reviewer
+lacks. A confirmed gap becomes a failed spec review and enters the fix loop.
+
+### 4.5 The fix loop
+
+Triggered by: spec ❌, any Critical or Important finding, or a "cannot verify" item
+you confirmed as a real gap.
+
+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 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
+  without asking.
+
+Everything else loops. One round = one fix dispatch + one scoped re-review.
+**Five rounds maximum per task.**
+
+**The loop guard runs alongside the counter** ([`loop-guard.md`](loop-guard.md)):
+log every repeat touch (`touch: <file> — round N — reason: <finding id>`) and trip
+*before* the cap when a fix undoes an earlier fix, when the same file returns for
+the same reason, or when a finding already ADDRESSED reappears. A tripped guard is
+not another round: stop, name the two shapes, escalate to the layer that owns the
+conflict, then re-check in a planned order.
+
+- **Rounds 1–3:** resume the original implementer with the open findings verbatim —
+  its context is intact. If the harness can't message a live subagent, dispatch a
+  fresh one with the brief path, the report path and the findings; the report file
+  is the persistent memory either way.
+- **Rounds 4–5:** fresh implementer, one tier up if available, framed as: "a prior
+  implementer attempted this task N times; you own it now — read the report file
+  for what was tried." A loop that survives three resumes usually means the
+  implementer can't see its own problem.
+- **Every round:** the implementer fixes, re-runs the tests covering the amended
+  code, appends its fix report to the same report file, returns the short contract.
+  Before re-dispatching the reviewer, confirm the fix report names the covering
+  tests, the command run and the output.
+- **The re-review is scoped** to the fix diff (`FIX_BASE`..`HEAD`, where `FIX_BASE`
+  is the head the previous review saw). It verdicts each finding ADDRESSED / NOT
+  ADDRESSED and flags new breakage in the fix diff only. New Critical/Important
+  breakage joins the open list; out-of-scope observations go to the ledger as
+  deferred minors — they never extend the loop.
+- **Ledger, every round:**
+  `Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <one-liners>; commits <a7>..<b7>)`
+
+**In a subagent run, never fix findings yourself in the controller session** —
+controller fixes skip review and pollute the context you need for coordination. In a
+declared inline run you do fix them, and you still review the fix diff against the
+rubric before closing the round.
+
+**The breaker.** If round 5's re-review still leaves findings open, stop
+dispatching and adjudicate each one yourself:
+
+- **Reviewer wrong or the point contestable** → park it:
+  `Task <N>: parked — <finding> — ruling: <why the code stands>`.
+- **Real, but nothing downstream builds on it** → park it the same way, with a
+  ruling saying it's real and deferred.
+- **Real and load-bearing** (a later task builds on it, or it exposes a plan defect)
+  → **STOP**. Append `Task <N>: BLOCKED — <reason>` and report to the operator with
+  the finding, the plan text it collides with, and the fix history. Parking a
+  structural failure lets every dependent task build on it.
+
+Adjudicate **only at the cap**. Adjudicating earlier to end a loop is pre-judging
+with a nicer name. Every adjudication is a ledger line; silent discards are
+forbidden.
+
+### 4.6 Complete the task
+
+When the review is clean — or every open finding is parked with a ruling at the cap
+— append:
+
+- `Task <N>: complete (commits <base7>..<head7>, review clean)`, or
+- `Task <N>: complete (commits <base7>..<head7>, <K> parked)`
+
+Mark the todo complete, move on. Never start the next task while Critical/Important
+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 "$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
+merge.
+
+If it returns findings, dispatch **ONE** fix subagent with the complete list — not
+one fixer per finding; per-finding fixers each rebuild context and re-run suites.
+Then exactly **one** scoped re-review of the fix wave. Adjudicate residuals as in
+the breaker: park with rulings, or stop on load-bearing ones. There is no second
+fix wave.
+
+## 6. Integrate, then finish
+
+The work is in a worktree on its own branch; stages 7–9 lint, deploy and document
+the **integrated** result. Close that gap here, honoring the branch policy recorded
+in the stage-0 brief:
+
+1. **Sync with the base branch** (rebase or merge, whichever the project uses) and
+   re-run the full suite on the result. A branch that was green in isolation and red
+   after integration is red — fix it here, not at stage 7.
+2. **Land it the project's way:** merge into the base branch, or open a PR when the
+   project requires review. Opening a PR is outward-facing — do it only with the
+   operator's go or the brief's specific standing authorization.
+3. **Never force-push a shared branch**, and never land on `main` when the brief put
+   it off-limits.
+4. **Remove the worktree** once merged (`git worktree remove <path>`, or the native
+   tool that created it), and delete this plan's workspace
+   (`rm -rf .task-pipeline/build/<plan-basename>`) — git history is the record now.
+   Sibling directories belong to other plans; leave them.
+
+If the operator's policy is "leave the branch, I'll merge it myself", stop after
+step 1, say exactly where the branch is and what state it's in, and record that
+stages 7–9 run against an unintegrated branch.
+
+## GATE (auto)
+
+All plan tasks DONE with all three review verdicts (spec compliance, REQ satisfied,
+code quality); the full test suite green; every open finding either fixed or parked
+with a ruling; **every parked finding and implementer concern harvested into the
+carry-over ledger** — the workspace is deleted, so nothing may stay only there;
+no task left BLOCKED; the branch integrated per the brief's policy — or the
+operator explicitly told you to leave it, and that is recorded. Verify it yourself;
+a red suite or an unresolved BLOCKED does not advance to stage 6.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "Close enough on spec compliance" | The reviewer found spec gaps ⇒ not done. Fix, or hit the cap and adjudicate. Those are the only exits. |
+| "I'll fix it myself, dispatching is overhead" | In a subagent run, controller fixes skip review and pollute your context — resume the implementer. (Inline runs are the declared exception, and still review the fix diff.) |
+| "One more round will converge" | Past the cap, rounds don't converge — the failure is structural. Adjudicate and route. |
+| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
+| "This finding is obviously wrong, drop it" | You adjudicate at the cap, in writing. Silent discards are forbidden. |
+| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Without one, controllers re-run entire completed task sequences. |
+| "Two implementers in parallel will be faster" | One working tree, two writers = corrupted state. Parallel needs one worktree each. |
+| "I'll paste the earlier tasks so it has context" | A fresh subagent needs its task, its interfaces and the constraints. Pasted history is pure cost. |
+| "Stage 7 can merge the branch" | Stage 7 lints and deploys what is integrated. An unmerged branch means lint, deploy and docs all ran against something that is not what ships. |

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

@@ -1,39 +1,71 @@
-# Companion skills — what powers each stage, how to install, what to run
+# Companions — what's built in, what's optional, what to install
 
-task-pipeline is a thin orchestrator; the actual work is done by companion
-skills. Preflight-detect each one; if a needed skill doesn't resolve, **give the
-operator the install line immediately** and (for required ones) stop until it's
-installed. Never silently degrade a required capability.
+**The pipeline's doctrine is entirely built into this skill.** Stages 0, 2, 3, 4, 5,
+6 and 10 run from `references/*.md` — no companion plugin, no resolution step, no
+fallback path, no version skew, and no failure mode where a stage can't run because
+something isn't installed.
 
-**Stage 0 is the exception: the grill is part of this skill**
-(`references/grill.md`), so it has no companion, no install line and no failure
-mode where it can't run.
+What remains is a short list of **optional** companions that make individual stages
+better, plus one that is required only for user-facing work.
+
+## Built in — nothing to install
+
+| 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` |
+| 3 Spec | `references/spec.md` |
+| 4 Plan | `references/planning.md` |
+| 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` |
+| any repeating loop | `references/loop-guard.md` |
 
 ## The matrix
 
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
-| **superpowers** (`brainstorming`, `writing-plans`, `subagent-driven-development`, `using-git-worktrees`, `test-driven-development`) | stages 2, 4, 5, 6 | **Required** (always) | `/plugin marketplace add obra/superpowers` → `/plugin install superpowers@superpowers` |
 | **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`) |
-| ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is **built into this skill** (`references/grill.md`) — nothing to install, nothing to resolve, no fallback path | — |
 | **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`) | — |
+
+## Optional bridge — substituting an external skill set
+
+An operator who already runs an equivalent skill set may map it onto stages 2/4/5/6
+in their `pipeline.json` → `skills[]`, e.g. `superpowers:brainstorming`,
+`superpowers:writing-plans`, `superpowers:using-git-worktrees`,
+`superpowers:subagent-driven-development`, `superpowers:test-driven-development`.
+
+Rules for that bridge:
+
+- **It is a substitution, never a requirement.** Nothing detects it, nothing
+  recommends it, nothing waits for it, and its absence is never an error.
+- **The gates still govern.** Whatever runs a stage, `stages.md` decides when the
+  stage is done.
+- **Never mix providers inside one stage** — either the built-in doctrine runs it or
+  the substitute does; interleaving two review loops produces neither.
 
 ## Preflight (emit before stage 0)
 
-At the very start, detect which of the above resolve and print ONE block —
-companions **plus the model decision** (`model-tiering.md`), so the operator arms
-the whole run in a single exchange. Example:
+Detect the optional companions and print ONE block — companions **plus the model
+decision** (`model-tiering.md`), so the operator arms the whole run in a single
+exchange:
 
 ```
-Pipeline companions:
-  ✓ superpowers        — ready
-  ✗ super-ux           — this task looks user-facing; recommended. Install:
+Pipeline companions (stage doctrine is built in — nothing to install for it):
+  ✗ super-ux           — this task looks user-facing; required for the UX track:
                            /plugin marketplace add ssheleg/super-ux
                            /plugin install super-ux@super-ux
   ✓ context7           — ready
-  ✓ wiki-update        — ready
-  • intake grill       — built in, no install needed
+  ✗ 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.
@@ -42,11 +74,14 @@ Install the ✗ items you want, answer the model line, then say "continue".
 ```
 
 Rules:
-- Only flag **super-ux** as recommended when the task implies a UI (the stage-0
-  grill decides this; when unsure, flag it — a false positive costs one install).
-- **superpowers** missing → stop; it's required for the core stages.
-- **Never gate stage 0 on an install.** The grill ships with this skill; there is
-  no external grill dependency to detect, recommend, or fall back from.
+
+- 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.
 - The model answer goes into the brief. Don't ask again per stage
@@ -54,13 +89,19 @@ Rules:
 
 ## Credit
 
-The built-in grill is adapted from Matt Pocock's `grilling` / `grill-with-docs`
-skills (MIT, https://github.com/mattpocock/skills) — see the repo `LICENSE` →
-*Third-party*. It is **ported, not depended on**: no install, no resolution, no
-version skew.
+The built-in doctrine is **ported, not depended on**:
+
+- The stage-0 grill is adapted from Matt Pocock's `grilling` / `grill-with-docs`
+  skills (MIT, https://github.com/mattpocock/skills).
+- Stages 2–6 are adapted from the `brainstorming`, `writing-plans`,
+  `using-git-worktrees`, `subagent-driven-development`, `test-driven-development`
+  and `requesting-code-review` skills in obra/superpowers (MIT,
+  https://github.com/obra/superpowers).
+
+Both notices live in the repo `LICENSE` → *Third-party*.
 
 ## Hand-off the other direction
 
-super-ux's `/ux` menu can hand off *to* this pipeline (its "execute
-autonomously" action). When entered that way the UX chain already exists — see
-`stages.md` → 0 *Entry-from-super-ux short-circuit*: verify, don't rebuild.
+super-ux's `/ux` menu can hand off *to* this pipeline (its "execute autonomously"
+action). When entered that way the UX chain already exists — see `stages.md` → 0
+*Entry-from-super-ux short-circuit*: verify, don't rebuild.

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

@@ -1,7 +1,10 @@
-# Host conventions (stages 6–9)
+# 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,6 +33,27 @@ 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)
+
+Acceptance parks what wasn't delivered: every `deferred` REQ and every unresolved
+carry-over row needs a **home** — an issue, a backlog entry, a ticket id. Read the
+host's convention (`CLAUDE.md` usually names the tracker and the id format; else
+detect: a `.github/ISSUE_TEMPLATE/`, a Linear/Jira reference in recent commits, a
+`TODO.md`). Never invent a tracker, and never close a run on "we'll remember it" —
+if no tracker exists, write the row into the repo's backlog file and say where it
+went.