task-pipeline-skill 0.17.1 → 1.1.0

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

@@ -35,10 +35,24 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   up front so stages 1→10 need no further human input beyond the manual gates.
   This is input expansion, not design: turn "make me feature X" into locked
   answers for scope, users, constraints, data, edge cases, done-criteria.
+- **Phase 1 — harvest the knowledge sources FIRST**
+  ([`knowledge-sources.md`](knowledge-sources.md)). Before the first question:
+  query what the project already knows about this task — code, `CLAUDE.md`,
+  `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs and carry-over
+  ledgers, 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 (a row per source, or an
+  explicit "none found"). It is retrieval scoped by the task's own nouns, not a
+  read of everything — and it is what makes phase 2's answers checkable instead of
+  merely confident.
 - **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
   skill (nothing to install). In short: one question per turn, a recommended
   answer with each, explore the codebase before asking, depth-first through the
-  decision tree, contradictions reconciled on the spot; plus **domain awareness**
+  decision tree, contradictions reconciled on the spot; **every answer that touches
+  a harvested source is checked against it** — the operator outranks any document,
+  but only out loud, and the losing side is logged for the stage-9 doc update; plus
+  **domain awareness**
   (challenge terms against `CONTEXT.md`, sharpen fuzzy language, stress-test with
   concrete scenarios, cross-reference the code, record ADRs for hard-to-reverse
   calls) and the **autonomy sweep** that pre-resolves every stage-1→10 blocker.
@@ -57,8 +71,11 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   its autonomy section instead of asking. Where the session produced them, also:
   an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
   `docs/adr/` — see `grill.md` → *Domain awareness*.
-- **GATE (manual):** shared understanding reached — every detected branch has a
-  recorded answer or an explicit deferral, no open contradictions, **every
+- **GATE (manual):** shared understanding reached — **the source ledger is written
+  (every source consulted, or an explicit "none found")**, every detected branch has
+  a recorded answer or an explicit deferral, **every answer that contradicted a
+  harvested source has a recorded resolution** (which governs, and whether the doc
+  is now stale), no open contradictions, **every
   autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
   **REQ table is written and every row names its check**, the carry-over ledger is
   seeded, the model decision is recorded, and the operator confirms the brief. Stop when a
@@ -123,8 +140,9 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
      map**: task analysis, user-flow diagrams (branches, error paths), every
      screen + state with wireframe and (Figma on) a Figma frame link.
   4. `ux-scenarios` → `docs/ux/scenarios.md` — the **WHAT** (source of truth for
-     behavior): scenarios validated per the format contract (`scenario-format.md`,
-     ux-contract v4) — IDs, statuses, `Traces:` to stories/journey stages/flows,
+     behavior): scenarios validated against the scenario-format contract super-ux
+     itself ships (`scenario-format.md` — read its current version there, never
+     pin one here) — IDs, statuses, `Traces:` to stories/journey stages/flows,
      edge/error states enumerated.
   5. **Run the super-ux linter** (`/ux-lint` or `python3 docs/ux/lint.py`) — it
      must pass: no drift, no orphans, no broken traces or stale Figma links.
@@ -217,12 +235,24 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   steps — never silent success.
 
 ## 9 — Docs + wiki
+- **The stage-0 source ledger is the work list** ([`knowledge-sources.md`](knowledge-sources.md)
+  → *Close the loop*): every source the harvest read gets updated if this run
+  changed or disproved it. What was worth reading at stage 0 and is wrong now is
+  the next run's false premise.
 - Update host module docs / runbooks per the project's self-update rules, in the
   **same change**. For UI tasks, confirm the super-ux layers were updated in this
-  change and the linter is green (super-ux *same-change* + *no-drift* rules). Then
-  sync knowledge to the wiki (`wiki-update` skill).
-- **GATE (auto):** docs in sync with code; UI: super-ux layers current + linter
-  green; wiki synced; dangling links fixed.
+  change and the linter is green (super-ux *same-change* + *no-drift* rules).
+- **Sync the knowledge wiki** — `wiki-update` when
+  [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) is installed (detect:
+  `~/.obsidian-wiki/config`, or the skill resolves). Not installed → recommend it
+  once with its install line and continue; a missing wiki never blocks the gate.
+  Distil the knowledge (decisions, seams, why), not a diff summary.
+- **Docs living in another repository** are outward: propose the edit, get an
+  explicit go, then open a PR there. No go → the exact edit goes in the carry-over
+  ledger.
+- **GATE (auto):** docs in sync with code; every stale row in the source ledger
+  either updated or carried over with its edit; UI: super-ux layers current +
+  linter green; wiki synced (or absent and recommended once); dangling links fixed.
 
 ## 10 — Acceptance
 - **What:** the closing stage — go back to the brief and account for **every**
@@ -232,6 +262,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   surfaces.
 - **Runs last**, after docs and wiki — those are deliverables too, and a REQ may
   name them.
+- **The ladder walk runs FIRST** ([`audit.md`](audit.md)). The REQ table can only
+  find what was named and lost; it cannot find what was never named, because a
+  comparison needs two sides and an absence has one. So before the table: walk each
+  REQ bottom-up through its rungs (decision → spec section → contract **and its
+  failure behavior** → task → change → executed test → surface/docs), check the
+  seam at each step, and order the findings **by seam, not by file**. An absence
+  becomes a **new REQ row with its check** and *then* the table is written;
+  appending after the table is how acceptance goes green over a gap. Findings that
+  belong to a lower layer go back to that layer (spec → stage 3, plan → stage 4).
+  Record the pass's two counts — new findings, and findings caused by this run's
+  own fixes — so the next pass can tell whether the axis is exhausted.
 - **How it runs:** built in. Read the brief's REQ table, the carry-over ledger in
   full, the plan's task statuses, git log, the final suite output, stage-8 notes and
   stage-9 doc changes (plus `docs/ux/scenarios.md` + `/ux-lint` for UI tasks). Write
@@ -244,10 +285,14 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   you asked for, here's what shipped, here's what's deferred and where it lives —
   what's missing?* Ask it even when the table is green; the operator holds context
   the brief never captured, and this is the cheapest moment in the run to hear it.
-- **GATE (manual):** every REQ has a status (none `unknown`); every `verified`
+- **GATE (manual):** the ladder walk ran and its absences became REQ rows before
+  the table was written; **every check this gate leans on has been seen failing
+  once against a planted defect** (an unproven check's green is not evidence);
+  every REQ has a status (none `unknown`); every `verified`
   carries evidence; every `partial` names what's missing and where it's tracked;
   every `deferred`/`dropped` has the operator's agreement and, for `deferred`, a
-  tracker entry; no carry-over row left `unresolved`; the operator answers the
+  tracker entry; no carry-over row left `unresolved`, and the ledger's counts are
+  printed with the verdict; the operator answers the
   closing question and signs off. Manual by design — an automated check can prove
   the table is well-formed, only the person who asked can confirm it is what they
   asked for.
@@ -299,3 +344,20 @@ cycle.
   re-plan the check as an ordered one-item-per-line checklist, then go through it in
   order, one commit per item. Never settle a higher-layer conflict inside a lower
   loop, and never adjudicate before the cap.
+
+## Cross-cutting — the audit
+
+The loop guard governs loops that **change** things. A loop that **looks** for
+things fails the other way: it converges, spending pass after pass on its own last
+pass's edits while the finding count stays healthy. [`audit.md`](audit.md) is that
+method and that exit — the L0→L7 ladder, the seam questions, the axis-rotation
+crossover, and the rule that a green from a check nobody has watched fail is worth
+nothing.
+
+- It runs **at stage 10 before the coverage table** (the only place that can find a
+  requirement nobody ever wrote), **per module** in the program loop, and as the
+  whole task when the request is itself an audit.
+- **A finding class seen twice becomes a script**, not a third ledger row.
+- **Whatever can't be fixed now becomes a ratchet** — a named, counted set that may
+  only shrink, printed beside every gate verdict, so "green" never reads as
+  "verified".

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

@@ -15,6 +15,11 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 **If you didn't watch the test fail, you don't know it tests the right thing.**
 
+The same law governs every other check in the run — a gate's `check`, a lint rule,
+a host script, a detector written during an audit. A check nobody has seen fail is
+a decoration that reports success. [`audit.md`](audit.md) → *Exit criterion* is
+this rule raised from one test to the whole pipeline.
+
 Wrote code before the test? Delete it and start from the test. Not "keep it as
 reference", not "adapt it while writing tests", not "look at it once more". Delete
 means delete — code you kept is code the test was written to fit.

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -9,6 +9,28 @@
 - **UI verdict:** yes / no — does this touch a user-facing surface (web/mobile/CLI/TUI)?
   If yes, the stage-3 super-ux UX track is armed.
 
+## Knowledge sources (the phase-1 harvest — written BEFORE the first question)
+
+What the project already knew about this task, and where it said so. One row per
+source actually consulted; `none found` is a valid, useful row. Stage 9 updates
+this same list — a source worth reading at the start is the next run's false
+premise if the run leaves it wrong.
+
+| Source | What it says about this task | Fresh? | Authority | Stale after this run? |
+|---|---|---|---|---|
+| `docs/adr/NNNN-….md` | … | YYYY-MM | decision | no |
+| wiki: `projects/…/concepts/…` | … | YYYY-MM | context | **yes — update at stage 9** |
+| `CLAUDE.md` | test/lint/deploy commands, house rules | current | convention | no |
+
+Precedence when two disagree: **code > host docs and ADRs > wiki > memory.** 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.
+
+- **Doc repos / hosted doc systems this project names:** … (or `none`)
+- **Knowledge wiki:** installed / not installed
+  ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki); recommended, never a gate)
+
 ## Scope
 
 - **In scope:** …
@@ -57,6 +79,7 @@ is not neutral — it is a scheduled interruption.
 |---|---|---|
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
 | run-wide | Decide autonomously vs escalate to me | … |
+| 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push) |
 | 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
 | 2 Decompose | 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); scenario-tracing waiver, if any | … |
@@ -67,7 +90,7 @@ is not neutral — it is a scheduled interruption.
 | 7 Deploy | Target + path; release automation on/off; deploy-from-main rule | … |
 | 7 Deploy | **Authorization** — standing go, or ask every time? | … |
 | 8 Post-deploy | Where logs / health live (app name, endpoint, workflow) | … |
-| 9 Docs+wiki | Which module docs / runbooks this change updates; wiki sync yes/no | … |
+| 9 Docs+wiki | Which module docs / runbooks this change updates; wiki sync yes/no; which stale ledger rows get fixed | … |
 | 10 Acceptance | Who signs off; where deferred REQs get tracked (issue tracker / backlog) | … |
 
 > **Deploy authorization has a hard floor.** A standing go counts only if it is

package/plugins/task-pipeline/skills/task-pipeline/templates/carryover.md

@@ -28,6 +28,29 @@
   with no home is exactly the thing that gets forgotten, so acceptance refuses to
   close on it.
 
+## This ledger is a ratchet, not a TODO list
+
+A TODO is invisible until somebody opens the file. **A ratchet is a named, counted
+set that may only shrink, and it is printed beside every gate verdict:**
+
+```
+GATE 6 tests: PASS — full suite green (247 tests)
+  carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
+```
+
+That one line is the whole mechanism. Without it, `PASS` reads as *verified*; with
+it, `PASS` reads as *"green, and here is exactly what was not looked at"* — which
+is the true statement.
+
+- **Print the counts at every gate**, not only at stage 10. A number nobody sees
+  until the end is a number nobody acts on.
+- **The set may only shrink.** If it grew, the run log gets one sentence saying why.
+  A ratchet that grows silently is a TODO with a better name.
+- **A finding class that appears twice stops belonging here** and becomes a check in
+  the host's lint or CI ([`audit.md`](../references/audit.md) → *A class that
+  repeats twice becomes a gate*). This ledger is for what cannot be automated, not
+  for what nobody automated.
+
 ## Notes
 
 - Adding a row costs one line and never blocks a stage — that is the point. The