task-pipeline-skill 1.96.0 → 1.98.0

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

@@ -2,225 +2,20 @@
 description: "Run a task through task-pipeline's gated stages (intake grill → docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki → acceptance). Also: `waves` — close the whole board in waves; `iteration` — the release loop around the waves; `setup` — audit the docs you already have; `checkup` — what has shipped unverified, with no task running."
 argument-hint: "<one-line task> | waves | iteration | setup | checkup"
 ---
-Run the task below through `task-pipeline`'s gated stages. **Every stage's doctrine
-ships inside the skill** — no companion plugin is required for any of it. The
-reference files are indexed in `SKILL.md`; this page is the run order, not the index.
+Run the task below through the `task-pipeline` skill. **Read its `SKILL.md` and follow
+it**; this page is a pointer, not a second copy of the run order (until 1.98.0 it was a
+13 KB restatement read on top of `SKILL.md` before any work).
 
 Task: $ARGUMENTS
 
-> **Four other modes.** `waves` takes the whole board instead of one task;
-> `iteration` runs the release loop around the waves — survey, design, build, release,
-> the next pool; `setup` audits the documentation this project already has; `checkup`
-> reports what has shipped without a person confirming it, with no task in flight. All
-> four are at the bottom of this page.
-
-**Idempotent entry — inspect state first, never restart blindly.** If a pipeline
-TaskList from a previous run exists for this task, **resume** from the first incomplete
-stage. Otherwise begin at stage 0. With no task given, the grill's first question asks
-for it in one line.
-
----
-
-## Preflight — settle these once
-
-**Print this line once, before the first question:**
-
-> Running **Proof of Done** — every claim this run makes will carry the command,
-> the file or the test that proves it.
-
-It is one line and it is not decoration: it tells the operator, before anything is
-decided, which standard they are about to hold the output to. A run that opens by
-naming the standard is one an operator can call out for missing it.
-
-- **Model.** Recommend the most capable one the environment offers, never a hardcoded
-  id. Confirmed once, then the whole run uses it without re-asking.
-- **Companions.** Print the detection block once (`references/companion-skills.md`).
-  Absent ones state their fallback and name any unavailable check as NOT_RUN.
-  On user-facing tasks stage 3 gates the valid scenario artifact, not package
-  presence; use the provider rule in that reference.
-
-## Stage 0 — the harvest, then the grill
-
-**The harvest runs before the first question** (`references/knowledge-sources.md`).
-Pull what the project already knows about *this task*:
-
-- the code, and **the code graph** where one is built — [graphify](https://github.com/Graphify-Labs/graphify),
-  `references/knowledge-graph.md`; recommended, never required; detect
-  `graphify-out/graph.json`. It answers **reach** — what calls this, what breaks if it
-  moves — which grep cannot.
-- `CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past briefs and carry-over ledgers.
-- **the retro's standing instructions and run stamps** — `docs/evidence/retro.md`,
-  read in full; both are bounded and they bind this run. Its **Recent log** is
-  *queried* by the task's nouns, not read: nothing caps it, and an uncapped section
-  inside a binding source is what makes the capped part get skimmed
-  (`references/retrospective.md`).
-- the **knowledge wiki** if installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki);
-  detect `~/.obsidian-wiki/config`), and any other doc system the project names as its docs.
-- **the board** (`docs/evidence/backlog.md`) — open count quoted in the brief, or
-  seeded when absent. **the verification ledger** (`docs/evidence/verification.md`) —
-  how many rows sit at `never`.
-
-Write the **source ledger** into the brief: a row per source, or an explicit *none found*.
-
-**Then the grill, and it is mandatory** (`references/grill.md`). Close what the sources
-can, then ask the material unknowns in ONE batch, ordered by dependency, each with a
-recommended answer — one at a time only where answers depend on each other or the
-operator asks — until every decision branch is resolved.
-
-- **Validate 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 stage 9.
-- **Domain awareness:** challenge terms against `CONTEXT.md`, sharpen fuzzy language,
-  write an ADR for a hard-to-reverse call.
-- **The autonomy sweep** pre-resolves what would otherwise stop stages 1→10: doc
-  sources, wiki and graph, branch and tracker policy, test and lint commands, deploy
-  target and authorization, log locations.
-- **UI tasks add the design surface.** Is the design done visually in Figma or
-  text-only? Is the Figma MCP connected? If not — ship text-only, or stop and connect
-  it? The UX chain degrades on its own and never blocks, so this choice must be
-  recorded rather than discovered.
-- **With Figma on, the destination is named before the first frame:** which team/org,
-  which file — the recorded one, a URL the operator gives, or creation in that named
-  team explicitly authorized. A destination decided at drawing time is how a project
-  ends up with three design files and no way to tell which is real. **Never create
-  while a recorded file resolves; if it does not resolve, stop and ask — never create a
-  replacement.**
-
-**The brief closes on the REQ table** — the request as an addressable list where every
-row names how it is verified. Frozen: adding is free, removing needs the operator.
-Anything deferred enters the carry-over ledger the moment it is said.
-
-## Stages 1→10 — the flow
-
-| | Stage | The thing that must be true to leave it |
-|---|---|---|
-| 1 | Docs study | every contract the design will lock is grounded on fetched docs, not recall |
-| 2 | Brainstorm + decompose | the design is approved and every REQ is answered by it. **A platform is cut into modules** (`references/decomposition.md`) — map committed, walking skeleton first, every REQ in exactly one module; stages 3→10 then run per module |
-| 3 | Spec | contracts locked; user-facing work runs three tracks — what it **does** (super-ux), how it **sounds** (`copywriting`), how it **looks** (`sheleg-design`); a declined track is recorded, never silent |
-| 4 | Plan | the REQ set-comparison holds: brief REQs == union of `Implements:` |
-| 5 | Build | TDD per task, a review after each, findings fixed or parked with a ruling |
-| 6 | Tests | the **full** suite green; a web surface checked in a browser, not in the diff |
-| 7 | Lint + deploy | outward: the authorization is specific, and the CI verdict is **read** before any tag |
-| 8 | Post-deploy | the verification trio, not one of three; a verification row per shipped REQ |
-| 9 | Docs + wiki | **three artifacts, not two** — module docs, the wiki, **and the code graph** |
-| 10 | Acceptance | the ladder walk first, then the table, then the retrospective |
-
-**Honor every gate by its type**: `auto` — verify the check yourself; `judgment` —
-record the named judge's ruling as judgement, never as a measurement; `manual` — cite
-an explicit go or specific standing authorization naming the act, otherwise wait.
-
-## Cross-cutting — the three that fire at any stage
-
-**The loop guard** (`references/loop-guard.md`). If a pass starts undoing an earlier one
-— the same file edited twice for the same reason, a closed finding returning, a third
-entry into one stage — stop editing. Name both shapes, escalate to the layer that owns
-the conflict, re-plan the check as an ordered list, then go item by item. The review
-loop has its own ceiling, and at it the run **measures** rather than stops.
-
-**The audit's exit** (`references/audit.md`). If a searching pass starts finding mostly
-what the previous pass's own fixes broke, the axis is exhausted — rotate it, do not look
-harder.
-
-**Evidence.** A green from a check nobody has watched fail against a planted defect is
-not evidence. A finding class seen twice becomes a script, not a third ledger row.
-
-## Stage 9 — the graph is the third artifact
-
-Refresh it (`/graphify . --update` where `graphify-out/` exists), then **check it against
-the docs**: a hub `graphify god-nodes` reports that no document names is an undocumented
-seam; an edge the docs deny is a leak in the code or a lie in the docs; a doc naming a
-module the graph no longer has is stale. Doc-side findings are fixed here; absences
-become REQ rows at stage 10.
-
-A stale graph is a false premise **carrying the authority of a machine** — a wrong doc
-gets argued with, a wrong graph gets believed.
-
-## Stage 10 — the close-out, in order
-
-1. **The ladder walk, first.** The REQ table finds what was named and lost; it cannot
-   find what was never named, because a comparison needs two sides and an absence has
-   one. Walk each REQ bottom-up — decision → spec section → contract *and its failure
-   behavior* → task → change → executed test → surface/docs — check the seam at each
-   step, and order findings **by seam, not by file**. Every absence becomes a new REQ
-   row **before** the coverage table is written.
-2. **The table**, one row per REQ, each with evidence.
-3. **The ledgers close.** Every carry-over row still `open`, `unresolved` or homed
-   `backlog` leaves with a board id, and the board's priorities are re-derived. The
-   counts print beside every gate verdict, so *green* never reads as *verified*.
-4. **Several repositories? The parent closes too.** A parent records each submodule as a
-   pointer to one commit, and moving the submodule does not move the pointer — so work
-   can be committed, pushed and green while a clone of the parent still gets the commit
-   before it. Neither repo looks wrong alone. Require `git submodule status` with no
-   line starting `+`, and every repo clean and pushed. The fix is two commands and the
-   second gets forgotten: push the submodule, **then** `git add <submodule> && git commit`.
-5. **The retrospective is the run's last act** (`references/retrospective.md`), in this
-   order: **stamp the run first** (its commit makes the cold trigger computable) → **prune**
-   every standing instruction against its three retirement triggers, list held to ten,
-   every deletion logged → **write an entry only if the run diverged**: symptom with
-   evidence, the stage it surfaced at, the stage that *owned* it, the root cause, the
-   fix by grade, and the check that catches it next time.
-
-Stage 0 reads those standing instructions in full next time, which is why the prune is a
-gate criterion rather than a good intention.
-
-**Then, and only after every gate above has closed, sign off:**
-
-> — **Proof of Done**
-> <https://github.com/ssheleg/sshlg-skills> · <https://skills.sshlg.me>
-> If this run was useful, a ⭐ helps other people find it.
-
-**Last, after the work — never before it, and never instead of a finding.** A run that
-asks for a star while a gate is open is asking to be judged on its manner rather than
-its evidence, which is the exact substitution this whole pipeline exists to refuse. If
-the run ended red, ended early or ended with rows still open, print the attribution and
-**drop the request**: the invitation is to endorse a finished result, and there is not
-one to endorse.
-
----
-
-## `/task-pipeline checkup`
-
-**Runs with no task in flight, and that is the point.** Accumulated unconfirmed work is
-invisible precisely because nobody is running a pipeline, so a check living only inside a
-run can never say *"stop, fourteen things are unconfirmed."*
-
-It takes no brief, opens no grill, and writes nothing on its own. Four sections, each
-read from a file this pipeline already keeps: the **exposure** line with its check-list
-oldest-first, the **board**'s open rows by computed priority, the carry-over ledgers'
-unresolved count, and the code graph's staleness where one exists.
-
-Where you ask it to file what it found, it appends board rows whose `Source` names the
-checkup and its date — printing what it would add first, never silently.
-Doctrine: `references/exposure.md`.
-
-## `/task-pipeline waves`
-
-**The whole board, closed in its final form.** Every open item — board, ledgers, plan
-rows, unverified rows, uncovered scenarios, other products' asks — plus the new requests,
-in one machine-readable inventory verified against the code. Questions are closed from
-the sources; what remains goes to the operator once, as one batch, at the end of
-planning. A committed canvas lays the target state over the current logic, and the work
-is cut into waves that each close in one pass. Stages 0–4 run once, 5–8 per wave with a
-close pass after each (verify, one fix round, docs, re-measure, re-cut), 9–10 to close.
-It takes the next wave without asking, says once when the board is empty, and leaves
-every sign-in, consent, payment and outward act to a person.
-Doctrine: `references/waves.md`.
-
-## `/task-pipeline iteration`
-
-**The loop around the waves: a project moves in whole releases.** Survey every source into
-one inventory (`scripts/waves.py merge`), write module dossiers in parallel, integrate them
-into one canvas until a pass changes nothing, ask the operator in batches (rounds), never
-one question at a time, then build in parallel. Each node is verified as it lands, in one
-to three rounds by its risk class (R1–R3); a wave's stage 7 integrates without tagging, and
-the release's stage-7 gate and stage 8's trio run once on what was released. The next pool
-is re-measured and handed back once. Every run reads earlier runs' lessons
-(`scripts/lessons.py query`) and writes its own at the retro. A finding made mid-iteration
-joins the inventory; only the closed hotfix lane ships alone.
-Doctrine: `references/iteration.md`.
-
-## `/task-pipeline setup`
-
-**The entry audit instead of a feature.** Seven passes over the documentation this
-project already has, findings reported as `file:line` + the minimal fix ordered by seam,
-and a fix plan the pipeline can run. Offered once at stage 0 when the doc map is absent
-or stale; run it directly any time. Doctrine: `references/setup.md`.
+- **Resume, never restart blindly.** If `.task-pipeline/run.md` or a pipeline task
+  list exists for this task, continue from the first incomplete stage.
+- **No task given?** Ask for it in one line.
+- **Proportional.** Stage 0's gap check decides: a small change takes the short path
+  and says so in one line; anything larger runs the full flow
+  (`references/stage-00-intake.md` → Phase 1d).
+- **Modes.** `waves`: the whole board (`references/waves.md`). `iteration`: the
+  release loop around the waves (`references/iteration.md`). `setup`: audit the
+  documentation the project already has (`references/setup.md`). `checkup`: what has
+  shipped with no person confirming it, with no task in flight
+  (`references/verification.md`).

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

@@ -1,6 +1,6 @@
 ---
 name: evidence-docs
-description: "Use when writing or reviewing anything that will be read as true — a decision record, a README, an acceptance report, a runbook, a changelog entry, an audit finding, or any claim that something was verified. Applies the ten canons of evidence-backed documentation — what makes a claim documentation rather than an assertion — and routes to the doctrine that enforces each one. Also use when a project needs a documentation gate, a decision register, a propagation matrix, or a retrospective that outlives its author. Triggers - 'documentation gate', 'decision record', 'ADR', 'acceptance report', 'runbook', 'is this verified', 'доказательная документация', 'записать решение', 'запиши решение', 'отчёт о приёмке', 'раннбук', 'чем это подтверждено', 'доки в синхроне'. Not for: drafts, chat answers, commit messages or code comments — say 'без доков' to opt out."
+description: "Use when writing or reviewing anything read as true: a decision record, ADR, README, acceptance report, runbook, changelog, audit finding, or a claim that something was verified. Applies the ten canons of evidence-backed documentation and routes to the doctrine enforcing each; also a documentation gate or decision register. Not for: drafts, chat answers, commit messages; 'без доков' opts out."
 license: MIT
 compatibility: "Doctrine runs on any agent. No bundled scripts — nothing to install and nothing to degrade."
 ---
@@ -108,3 +108,10 @@ then nothing carries an address.
 GENERATED copies, so a single-skill install of this skill resolves every link without a
 neighbouring checkout. Edit the source home, never the copy — which file is generated,
 from where, and how to re-sync: [`GENERATED.md`](references/GENERATED.md).
+
+## Triggers
+
+The description is the short form. The full trigger list it carried until 1.98.0,
+moved here verbatim, still routes to this skill:
+
+"Use when writing or reviewing anything that will be read as true — a decision record, a README, an acceptance report, a runbook, a changelog entry, an audit finding, or any claim that something was verified. Applies the ten canons of evidence-backed documentation — what makes a claim documentation rather than an assertion — and routes to the doctrine that enforces each one. Also use when a project needs a documentation gate, a decision register, a propagation matrix, or a retrospective that outlives its author. Triggers - 'documentation gate', 'decision record', 'ADR', 'acceptance report', 'runbook', 'is this verified', 'доказательная документация', 'записать решение', 'запиши решение', 'отчёт о приёмке', 'раннбук', 'чем это подтверждено', 'доки в синхроне'. Not for: drafts, chat answers, commit messages or code comments — say 'без доков' to opt out."

package/plugins/task-pipeline/skills/evidence-docs/references/GENERATED.md

@@ -1,6 +1,6 @@
 # Generated copies — do not edit here
 
-The files in this directory (and `../templates/`) are GENERATED (a deterministic transform: in-set links stay relative, out-of-set links point at the source home’s canonical URL) from the
+The files in this directory (and `../templates/`), except `retrospective.md` (a hand-written pointer to its single home since 1.98.0), are GENERATED (a deterministic transform: in-set links stay relative, out-of-set links point at the source home’s canonical URL) from the
 source home `skills/task-pipeline/references/` and `skills/task-pipeline/templates/`
 so an isolated single-skill install of evidence-docs resolves every required
 link without a neighbouring checkout (FIX-ED-01.01). Edit the source home and

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

@@ -58,6 +58,13 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 | 30 | **A gate scoped by exclusion judges every newcomer silently** | any lint, format or check configured with an ignore list rather than an include list | scope by what it COVERS; where the tool has no such switch, assert the covered set and fail on additions, deriving the allowlist by measuring the tool's own reach | the failure message names the intruder and the remedy, because the operator meets it mid-release |
 | 31 | **A gate needs a third verdict — could not measure** | any check that can time out, lose a dependency, or run on a contended machine | distinguish *failed* from *could not measure* with different exit codes, and say which; neither is a verdict about the code | the refusal names its remedy, and a test that waits for a DURATION rather than an event is treated as a defect in the test |
 | 32 | **A test whose assertion is implied by compilation is not a test** | any test whose name promises a behaviour | delete the subject: if that is a type or import error rather than a red test, the test is decoration | removing one asks what the name PROMISED and whether anything checks it — four of five such cases here were covered elsewhere and the fifth was a real gap only visible because the name was read as a claim |
+| 33 | **Snapshot before you undo** | any `git checkout`, `git restore`, `git stash` or `reset` in a tree that may hold uncommitted work you did not write | copy the affected files first (to a dated folder, or `git diff > <file>.patch`) and restore from that copy, never from git | the run names the copy it took before the first destructive command |
+| 34 | **One answer for inputs that should differ is a broken instrument** | any shell measurement, zsh above all | quote every expansion (`"$var"`, `'*.py'`), read data from files rather than inline literals, and feed it two inputs that should answer differently | the two answers differ, or the instrument is rewritten before its answer is used |
+| 35 | **Release the tree you tested** | any tag or release | run the release workflow's own suite on the exact commit the tag will name, and select the CI run by that tag, never by branch | the run the tag triggered is green and its head SHA is the tagged commit |
+| 36 | **A fix after a passing review is unreviewed** | any change made after a review or verifier passed | re-read the delta (`git diff <reviewed>..HEAD`) before merge | the merge names the reviewed SHA and who read the delta |
+| 37 | **Call the real service once before writing its fake** | any mock, stub or fixture of an external API, CLI or service | make one real call, or read a recorded real response, and shape the fake from it | the fake cites the response it was shaped from |
+| 38 | **Close blockers yourself; park only human gates** | any blocker about to be handed back | try every route the run holds (an API, a CLI, a credential door) first; park only a sign-in, consent, payment, typed secret or recorded operator decision | every handed-back item is a human gate, listed in one block with the route that failed |
+| 39 | **Never retry an unchanged failing action** | any failed command, check or approach | change the input or the approach before trying again; after two failed approaches, change approach or record a blocker | no identical retry in the run ledger, and a third attempt names what changed |
 
 ---
 
@@ -163,6 +170,17 @@ that document is checked. This one governs a fact that crossed a **session bound
 reported as current — the case where there is no document to check, only a memory that reads like
 one.
 
+**33 to 39 · The 2026-10-20 retro audit.** Read across ~54 retrospectives from ~50
+projects, the same lessons recurred under different words, each in at least the number
+of runs given: uncommitted work overwritten by a checkout, restore or stash with no copy
+taken (17); a zsh glob or `=` left unquoted, so a command failed or a loop printed one
+count for every file (8; this release's own run hit both); a tag cut from a tree the
+release suite never ran on, or a CI run picked by branch rather than by tag (24, with
+immutable tags burned); a fix landed after the review passed and merged unread; a fake
+shaped from documentation that the real service contradicted (11); a hand-back listing
+steps the agent could have done itself (12); and the same failing action retried
+unchanged, round after round. None of them was new to the project that hit it again.
+
 ---
 
 ## The two that are not in the table, and why
@@ -214,6 +232,11 @@ answer would have exposed it in a minute.
 | any command run to establish a fact — 6 Tests · 9 Docs · 10 Acceptance · 5 review | 19 — the output asserted non-empty and shaped as expected, and **quoted** rather than concluded from, [`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) → *Silence is not a reading*; the reviewer's half is in [`review.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/review.md) |
 | 0 Harvest · 10 Acceptance | 20 — the **consumer** read to learn which copy ships, never the copies compared against each other, [`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) → *Two copies, and which one wins*; asked as row `0 Duplicates` of [`grill.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/grill.md) → *The autonomy sweep* |
 | 10 Retro · **any gate or check you order** | 21 — each input traced to the step that writes it, and that step proven upstream, [`retrospective.md`](retrospective.md) → *Stamp first, then prune, then write* |
+| any stage · a destructive git command · a shell measurement | 33, 34 |
+| 7 Release · 5 Dev after review | 35, 36 |
+| 5 Dev · 6 Tests · a fake of an external service | 37 |
+| 10 Acceptance · the hand-back | 38 |
+| every stage · any retry | 39, [`loop-guard.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) |
 
 **This file is the shipped list; a project keeps its own.** Every rule in the table
 above was earned on someone else's build and travels with the skill. The lessons *your*
@@ -276,7 +299,7 @@ evidence that something left, and the log below says what.
 
 ### Retired
 
-**Numbers issued so far: 32.** This is the high-water mark, and it is the only number
+**Numbers issued so far: 39.** This is the high-water mark, and it is the only number
 this file states about itself — deliberately, because the gap that proves a rule left
 cannot be computed from the table alone: **deleting the highest-numbered rule shrinks
 the maximum with it, and no gap ever opens.** That false negative shipped in the first