task-pipeline-skill 1.7.1 → 1.8.0

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

@@ -4,6 +4,22 @@
 have.** A hook is rung 5 of [`gates.md`](gates.md)'s ladder — the only mechanism
 that acts *while the agent is working* rather than after the commit.
 
+## Contents
+
+- The limit, before the capability
+- The events
+- The `PreToolUse` contract
+- What the hook receives
+- Where it lives
+- Matchers
+- Performance
+- What belongs in a hook, and what does not
+- A worked example
+- Debugging
+- Removing them
+- Leases are not reimplemented here
+- Rationalizations
+
 ## The limit, before the capability
 
 **Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill
@@ -16,13 +32,29 @@ The gap between "the rule exists" and "the rule is enforced" is invisible from
 inside a transcript, and a false guarantee is worse than a stated absence: everyone
 downstream stops checking.
 
+> **Provenance.** Every contract below is quoted from the Claude Code hooks
+> reference (`code.claude.com/docs/en/hooks`), fetched **2026-08-03**. Re-fetch
+> before relying on it: this is an external API, and stage 1 of this very pipeline
+> exists because a contract recalled from memory is a contract that has already
+> moved. Where the reference and this file disagree, the reference wins and this
+> file is the bug.
+
 ## The events
 
+There are **35** hook events. These are the ones this pipeline reaches for; the
+reference has the rest, grouped as session lifecycle, per-turn, tool execution,
+subagents and tasks, file and config changes, compaction, worktrees, display, and
+MCP elicitation.
+
 | Event | Fires | Used for |
 |---|---|---|
 | `SessionStart` | session opens (matcher `startup\|resume`) | register the run, print the board, name the one next action |
-| `PreToolUse` | before a tool call | **block** — the only event that can refuse |
-| `PostToolUse` | after every tool call | bookkeeping: renew a lease, stamp a marker |
+| `PreToolUse` | before a tool call | **block** — the event that can refuse |
+| `PostToolUse` | after a tool call | bookkeeping: renew a lease, stamp a marker |
+| `Stop` | the turn ends | a last-word check — the run's own gate, not the repo's |
+| `SubagentStart` · `SubagentStop` | a subagent starts or finishes | stage 5 runs implementers as subagents; this is where a per-agent identity or ledger line belongs |
+| `WorktreeCreate` · `WorktreeRemove` | a worktree appears or goes | stage 5 isolates in worktrees; a guard that must not fire inside one can key off these |
+| `PreCompact` · `PostCompact` | context is compacted | flush anything that only lives in context — the ledger exists because this happens |
 | `SessionEnd` | session closes | release leases, flush the journal |
 
 ## The `PreToolUse` contract
@@ -38,22 +70,44 @@ A hook blocks a call in **either** of two ways:
  "permissionDecisionReason":"docs gate failed: 2 undefined ids in docs/ARCHITECTURE.md"}}
 ```
 
+`permissionDecision` takes **four** values, not one: `allow` (permit it), `deny`
+(block it), `ask` (escalate to the user), `defer` (fall through to the normal
+permission flow). Exit 0 with empty stdout means `defer` by omission. A hook may
+also rewrite the call instead of judging it, by returning `updatedInput` in the
+same block — which is a different power from blocking and worth knowing before you
+reach for it.
+
 **Any other exit code is a non-blocking error**: execution continues and stderr is
-shown in the transcript. So **a crashing guard fails open** — it stops guarding and
-nothing announces that it has. Write the guard to `exit 2` on its own internal
-errors, or accept that a typo in it silently removes the protection everyone
-believes is there.
+shown in the transcript. The reference is explicit that **exit 1 is treated as
+non-blocking, "even though 1 is the conventional Unix failure code"** — so the
+single most likely way to write a guard, `command || exit 1`, is the one that does
+not guard. And on exit 2 Claude Code **ignores stdout and any JSON in it**; only
+stderr is read back.
+
+So **a crashing guard fails open** — it stops guarding and nothing announces that
+it has. Write the guard to `exit 2` on its own internal errors, or accept that a
+typo in it silently removes the protection everyone believes is there.
 
 That asymmetry is the whole reason this file leads with the limit: a hook is the
 strongest rung and the one whose failure is quietest.
 
 ## What the hook receives
 
-JSON on stdin: `session_id`, `prompt_id`, `transcript_path`, `cwd`,
-`permission_mode`, `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`.
+JSON on stdin. Common to every event: `session_id`, `transcript_path`, `cwd`,
+`permission_mode` (`default` · `plan` · `acceptEdits` · `auto` · `dontAsk` ·
+`bypassPermissions`), `effort` (an object with `level`), `hook_event_name`, and —
+inside a subagent — `agent_id` and `agent_type`. `prompt_id` is present from a
+recent version onward, so treat it as optional unless you pin one.
+
+Tool events add `tool_name`, `tool_input` and `tool_use_id`. **`tool_input` is
+where the target lives** — `file_path` for an edit, `command` for a Bash call.
+Parse it; do not infer the target from anything else in the environment
+([`learned.md`](learned.md) rule 15: a heuristic over strings the environment also
+produces matched the throwaway shell of every tool call).
 
-`tool_input` is where the target lives — `file_path` for an edit, `command` for a
-Bash call. Parse it; do not infer the target from anything else in the environment.
+`agent_id` matters more here than it looks: stage 5 runs implementers as subagents
+in worktrees, and a guard that must behave differently for the orchestrator and for
+an implementer has exactly one honest way to tell them apart.
 
 ## Where it lives
 
@@ -77,6 +131,17 @@ machine, and the first surprising denial is debugged in the wrong project.
 - for a specific shell command, add `"if": "Bash(git commit *)"` beside
   `"matcher": "Bash"`.
 
+`if` uses **permission-rule syntax** (`Bash(git *)`, `Edit(*.ts)`) and is evaluated
+**only on tool events** — `PreToolUse`, `PostToolUse`, `PostToolUseFailure`,
+`PermissionRequest`, `PermissionDenied`. Anywhere else it is inert, which is a
+silent way to write a guard that never fires.
+
+**For Bash the match is best-effort — the reference's own word.** It inspects
+subcommands, `$()` expansions and backticks, and strips leading `FOO=bar`
+assignments before matching. So `if` is a good **filter** and a bad **boundary**:
+narrow with it to keep the hook cheap, then re-check the real target inside the
+script before refusing anything.
+
 Match as **narrowly** as the rule allows. A `"*"` matcher on a blocking event puts
 your script in the path of every tool call the agent makes.
 

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

@@ -15,6 +15,14 @@ It is **recommended, never required**. No stage blocks on a missing graph; the
 harvest simply runs on the sources it has
 ([`knowledge-sources.md`](knowledge-sources.md)).
 
+## Contents
+
+- Detect it, and install it once
+- Stage 0 — query the graph before you ask the person
+- Stage 9 — the close-out has three artifacts, not two
+- The divergence check — the graph against the docs
+- Rationalizations
+
 ## Detect it, and install it once
 
 Detect, in this order:

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

@@ -8,6 +8,19 @@ The same source list closes the loop at **stage 9**: what was read at the start
 what gets updated at the end. A source good enough to answer a question is a source
 that goes stale when the answer changes.
 
+## Contents
+
+- Why this is a phase and not "explore a bit first"
+- The sources, in the order to try them
+- The retro's standing instructions — an instruction source, not background
+- The code graph — recommended
+- The knowledge wiki — recommended
+- How to harvest — retrieval, not reading
+- Record it — the source ledger
+- Phase 2 — validate the answers against the harvest
+- Close the loop — stage 9 updates what stage 0 read
+- Rationalizations
+
 ## Why this is a phase and not "explore a bit first"
 
 An agent that starts asking without harvesting spends the operator's turns on

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

@@ -13,6 +13,14 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 
 ---
 
+## Contents
+
+- The table — trigger · check · exit criterion
+- The incidents, so the rules are not abstract
+- The two that are not in the table, and why
+- The one instruction that would have prevented the most
+- Where these bind in the pipeline
+
 ## The table — trigger · check · exit criterion
 
 | # | Rule | Trigger | The check | Exit criterion |

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

@@ -18,6 +18,14 @@ axis, don't push harder): [`audit.md`](audit.md) → *Every pass changes the axi
 Both can bind one run. Use this file's trips for edits, that file's crossover for
 searches.
 
+## Contents
+
+- Bookkeeping — the thing that makes detection mechanical
+- Detection — any one of these trips the guard
+- The break protocol
+- When to stop and hand back
+- Rationalizations
+
 ## Bookkeeping — the thing that makes detection mechanical
 
 You cannot detect churn from memory, especially after compaction. Every repeating

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

@@ -9,6 +9,18 @@ Built into this skill; nothing to install.
 > *Third-party*), extended with the dependency graph, parallel groups and
 > file-ownership rules this pipeline's stage-5 subagent build depends on.
 
+## Contents
+
+- Audience
+- Before writing tasks
+- Task right-sizing
+- Plan header — required
+- Task structure — required
+- No placeholders
+- Self-review — before handing off
+- This stage settles nothing — and that is a rule, not an omission
+- GATE (auto)
+
 ## Audience
 
 Assume a skilled developer who knows nothing about this codebase, this domain or
@@ -182,6 +194,19 @@ A checklist you run yourself, inline. No subagent:
    `depends:` points at a task that really produces what's consumed.
 6. **DoD present and verifiable** on every task.
 
+## This stage settles nothing — and that is a rule, not an omission
+
+Planning **translates** decisions; it does not make them. So unlike stages 2, 3, 5
+and 10 there is no Doc Loop trigger here ([`documentation.md`](documentation.md)),
+and the reason is worth stating, because an unstated exclusion is indistinguishable
+from a gap.
+
+The consequence is the working rule: **if writing the plan forces a choice, the
+choice belongs to a lower layer.** A contract that turns out underspecified goes
+back to stage 3 and is recorded there; a scope question goes back to the operator.
+A decision first made while sequencing tasks is a decision nothing downstream will
+ever find, because nobody reads a plan after the build.
+
 ## GATE (auto)
 
 **Set equality first:** the REQ ids in the brief equal the union of `Implements:`

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

@@ -20,6 +20,17 @@ Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
 writes an entry. A retro that is empty after a messy run is the exact failure this
 file exists to stop.
 
+## Contents
+
+- Write the entry only for a divergence — and name the layer that owned it
+- Every lesson carries its commit
+- Rotation — the archive is how pruning stops losing things
+- Three grades of fix — take the highest one that can work
+- The prune — mandatory, and it runs BEFORE the new entry is written
+- The loop closes at stage 0
+- Where a lesson goes when it is not about this project
+- Rationalizations
+
 ## Write the entry only for a divergence — and name the layer that owned it
 
 An entry is owed when the run did not go as planned: a gate reopened, a stage was

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

@@ -10,6 +10,16 @@ install.
 > external helper scripts replaced by plain git commands so the doctrine works on
 > any agent.
 
+## Contents
+
+- The diff package
+- Reviewer inputs
+- Controller rules
+- The rubric
+- Prompt — task review
+- Prompt — scoped re-review
+- Prompt — final whole-branch review
+
 ## The diff package
 
 A reviewer never re-derives the diff with a dozen git calls, and the diff never
@@ -167,6 +177,13 @@ finding either.
 > which can stand and why. Findings only, with severity and a concrete failure
 > scenario each. Return the findings as your final message.
 
+**A ruling that parks a finding is a decision.** *"This stands, and here is why"* is
+exactly the sentence a future reader will hit in the code and re-litigate, so a
+ruling that outlives the run goes through the **Doc Loop**
+([`documentation.md`](documentation.md)) — via the report and the ledger, written by
+the orchestrator after integration, never by a subagent
+([`build.md`](build.md) → *§4.1a*).
+
 Run the final review on the **run's confirmed model** like everything else
 ([`model-tiering.md`](model-tiering.md)). It is the one review that sees the whole
 change, so if the run is on a tier below the most capable one available, say so and

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

@@ -9,6 +9,16 @@ Writing the approved design down so a zero-context implementer — human or suba
 > *Third-party*), extended here with the UX track and the Global Constraints block
 > that stages 4–5 depend on.
 
+## Contents
+
+- Order of operations
+- UX track (user-facing tasks only)
+- Write the spec
+- Module dossier — when the run is one brick of a platform
+- Self-review — before showing it
+- Locked contracts are decisions — the register, not only the spec
+- GATE (manual)
+
 ## Order of operations
 
 For a **user-facing task** (stage-2 UI verdict = yes) the UX chain runs **first** —
@@ -134,6 +144,18 @@ Read what you wrote with fresh eyes and fix inline. No subagent, no second pass:
 5. **Ambiguity:** can any requirement be read two ways? Pick one and say it.
 6. **Traceability (UI):** does every user-facing requirement name its scenario ID?
 
+## Locked contracts are decisions — the register, not only the spec
+
+This stage settles more than any other: a schema, a signature, a status vocabulary,
+an error shape. Each has a life longer than the document it is written into, so run
+the **Doc Loop** ([`documentation.md`](documentation.md)) for the ones that bind
+future work — record the entry, propagate by the matrix, and cite the id from the
+spec section instead of restating the reasoning there.
+
+**A spec states a contract; the register makes it addressable.** A spec is per-run
+and the next one supersedes it; an id survives. If this stage settled something and
+no entry names it, the run has agreed to decide it again later.
+
 ## GATE (manual)
 
 > "Spec written and committed to `<path>`. Review it and tell me if anything should

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

@@ -8,7 +8,52 @@ operator's explicit go). These stages (0 intake + 1→10) are the plugin's
 `pipeline.schema.json`; a host project replaces it with its own
 stages/agents/types (see SKILL.md → *Bring your own skills*).
 
+## The run checklist — copy it, tick it
+
+Complex workflows lose steps silently. Copy this into your response at the start of
+a run and check items off as they close; it is the cheapest guard against the one
+failure this pipeline keeps paying for — a stage that *looks* done because nothing
+printed.
+
+```
+Pipeline progress
+- [ ]  0  Intake — harvest + doc inventory + reconcile, grill, REQ table, brief locked
+- [ ]  1  Docs study — every contract grounded on fetched docs, not recall
+- [ ]  2  Brainstorm — design approved, UI verdict recorded, every REQ answered
+- [ ]  3  Spec — committed, reviewed, every section covers: REQ-…
+- [ ]  4  Plan — REQ set equality holds, no placeholders, groups share no files
+- [ ]  5  Dev — tasks DONE, three verdicts each, suite green, branch integrated
+- [ ]  6  Tests — full suite green, new checks probed both ways
+- [ ]  7  Lint + deploy — clean, and the deploy authorization is specific
+- [ ]  8  Post-deploy — clean boot, or an honest degradation report
+- [ ]  9  Docs — matrix walked, registers written, docs gate green with ratchets printed
+- [ ] 10  Acceptance — ladder walk first, every REQ with evidence, retro written last
+```
+
+Each line is a **gate**, not a task: an unchecked box means the gate did not pass,
+never that the work was skipped quietly.
+
+## Contents
+
+- The run checklist — copy it, tick it
+- 0 — Intake grill — MANDATORY
+- 1 — Docs study
+- 2 — Brainstorm + decompose
+- 3 — Spec — with UX track for user-facing tasks
+- 4 — Plan
+- 5 — Dev
+- 6 — Tests
+- 7 — Lint + deploy
+- 8 — Post-deploy
+- 9 — Docs + wiki
+- 10 — Acceptance
+- The program loop — a platform, one brick at a time
+- Cross-cutting — the Doc Loop
+- Cross-cutting — the loop guard
+- Cross-cutting — the audit
+
 ## 0 — Intake grill — MANDATORY
+- **Freedom: medium** — the interview adapts to the answers; its two phases and their order do not ([`gates.md`](gates.md) → *Axis B*).
 - **Stage 0 is not optional and not skippable.** There is no "small enough task"
   exemption, no "the request was already clear" exemption, no starting stage 1
   "while the operator thinks". The only sanctioned bypass is the
@@ -109,15 +154,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   reversible calls can be deferred with a note). Only then start stage 1.
 
 ## 1 — Docs study
+- **Freedom: medium** — which sources to fetch is judgement; grounding contracts on fetched docs is not ([`gates.md`](gates.md) → *Axis B*).
 - **What:** ground every external library / API / SDK the task touches on the
   *current* docs, before locking any contract.
-- **Invoke:** `context7` MCP (`resolve-library-id` → `get-library-docs`, scope by
-  `topic`) or the `context7-docs` skill. Web-search fallback for libs context7
+- **Invoke:** the `context7` MCP — `context7:resolve-library-id` → `context7:query-docs`,
+  scoped by topic or the `context7-docs` skill. Web-search fallback for libs context7
   can't resolve.
 - **GATE (auto):** every contract the design will lock is grounded in fetched docs,
   not recall. Unresolvable libraries are flagged in the spec.
 
 ## 2 — Brainstorm + decompose
+- **Freedom: high** — many designs are valid — this is the open field, and the only fixed thing is the gate ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`brainstorm.md`](brainstorm.md)** — built into this skill. Read
   the brief first (stage 0 already answered scope/constraints/done-criteria), then
   explore the codebase, scope-check for decomposition, one question at a time, 2–3
@@ -147,6 +194,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   contracts named with their owner.
 
 ## 3 — Spec — with UX track for user-facing tasks
+- **Freedom: medium** — what the contract says is judgement; which contracts must be locked is a list ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`spec.md`](spec.md)** — built into this skill: the UX-track order,
   what the spec must lock (types, schemas, signatures, file layout, the **Global
   Constraints** block stages 4–5 depend on), the self-review pass and the operator
@@ -202,6 +250,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
+- **Freedom: low** — the task format is prescribed and the REQ set-comparison is mechanical ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`planning.md`](planning.md)** — built into this skill →
   `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` (same slug as the brief and the
   spec). Zero-context tasks, exact
@@ -220,6 +269,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   same change (super-ux *same-change* rule).
 
 ## 5 — Dev
+- **Freedom: low** — TDD order, worktree isolation and 'a subagent never writes the register' are the narrow bridge ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`build.md`](build.md)** — built into this skill: isolate the
   workspace (native worktree tool first, git fallback, baseline tests), keep a
   ledger under `.task-pipeline/build/<plan>/` so a compacted context can resume,
@@ -241,6 +291,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   "leave it" recorded).
 
 ## 6 — Tests
+- **Freedom: low** — green means the full suite, and no skip smuggles a red one past ([`gates.md`](gates.md) → *Axis B*).
 - **What:** consolidate test coverage for the change: confirm new functionality
   has tests (written test-first in stage 5), update/repair existing tests the
   change touched, and add edge-case + failure-path tests per DoD.
@@ -254,6 +305,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   ([`audit.md`](audit.md)).
 
 ## 7 — Lint + deploy
+- **Freedom: low** — outward and irreversible — the authorization floor is exact or the stage stops ([`gates.md`](gates.md) → *Axis B*).
 - Read host conventions (`conventions.md`): run the linter; fix failures. The suite
   is already green from stage 6 — re-run it if code changed since. For UI projects,
   the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
@@ -268,12 +320,14 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   operator go. Respect deploy-from-main rules if the project mandates them.
 
 ## 8 — Post-deploy
+- **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis B*).
 - Tail deploy logs / health-check per conventions. Confirm clean boot, no error
   spike, live subsystems healthy.
 - **GATE (auto):** clean boot confirmed, or an **honest degradation report** with next
   steps — never silent success.
 
 ## 9 — Docs + wiki
+- **Freedom: low** — the matrix walk and the gate are mechanical; what a doc says is not this stage's call ([`gates.md`](gates.md) → *Axis B*).
 - **The propagation sweep runs first** ([`documentation.md`](documentation.md)).
   The ledger below names the documents you **read**; the matrix in `docs/DOCMAP.md`
   names the documents you **owe**. They are not the same list, and the gap between
@@ -327,6 +381,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   carry-over count printed beside this verdict**.
 
 ## 10 — Acceptance
+- **Freedom: medium** — the walk and the evidence rule are fixed; whether it is what was asked for is the operator's ([`gates.md`](gates.md) → *Axis B*).
 - **What:** the closing stage — go back to the brief and account for **every**
   requirement. Doctrine: [`acceptance.md`](acceptance.md). Every earlier gate asks
   "is this artifact good?"; none asks "does this still contain everything that was
@@ -382,7 +437,8 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   notices it is the same one. So, in this order: **prune first** (every standing
   instruction against its three retirement triggers — it became a check, its
   surface is gone, it hasn't fired in five run stamps — and the list held to its cap
-  of ten, every deletion logged), **stamp the run**, then **write an entry only if
+  of ten, every deletion logged **in the archive, with the commit that retired it**),
+  **stamp the run**, then **write an entry only if
   the run diverged** (symptom · the stage it surfaced at · the stage that *owned* it
   · root cause · fix, mechanical before instruction before expiring note · the check
   that catches it next time). Every run prunes and stamps; a retro left empty after
@@ -390,9 +446,9 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   instructions in full next time, which is why the cap is not negotiable.
 - **GATE (manual):** the ladder walk ran and its absences became REQ rows before
   the table was written; **the retrospective is written — prune before entry, the
-  list at or under its cap, every deletion logged **in the archive with its commit**,
+  list at or under its cap, every deletion logged in the archive with its commit,
   entries older than five run stamps rotated into `docs/superpowers/retro/`, the run
-  stamped **with its commit**, every SHA in either file resolvable, and the
+  stamped with its commit, every SHA in either file resolvable, and the
   counts printed beside this verdict**; **the documentation gate has been seen
   failing once against a planted defect and its ratchet counts are printed**
   ([`gates.md`](gates.md)); **every repository is closed — the parent included:

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

@@ -7,6 +7,16 @@ into this skill; nothing to install.
 > [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
 > *Third-party*), with the stage-6 suite gate added.
 
+## Contents
+
+- The iron law
+- Red → green → refactor
+- Tests that stay honest
+- Stage 6 — consolidation and the suite gate
+- When stuck
+- Rationalizations
+- Red flags — stop and start over
+
 ## The iron law
 
 ```