task-pipeline-skill 1.94.1 → 1.96.0

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

@@ -36,7 +36,8 @@ A fix designed against today's state is the intermediate state that
 seam, and the fix is then paid for twice. The finding gets an id in its owning register
 and lands on a canvas node. Its wave decides when it is built.
 
-**The hotfix lane is the only exception, and it is closed.** It has five entries:
+**The hotfix lane is the only exception, and it is closed.** This list is its single home;
+[`finish-line.md`](finish-line.md)'s blocking test B2 cites it. It has five entries:
 - production is down;
 - data is being lost or corrupted;
 - a credential has leaked;
@@ -57,12 +58,12 @@ reason. "It is quick" is not one of the five entries.
 | 4 | Question round | answers from the sources, then one batch to the operator | every question is answered, assumed, or blocks a named node |
 | 5 | Plan | the work graph with waves and risk classes — `scripts/waves.py sync-graph` writes each node's `wave` and `risk` from the plan, so `graph.py close` enforces the rounds it owes — and one packet per node | every REQ lands on a node; [`planning.md`](planning.md)'s set comparison holds |
 | 6 | Build | parallel agents, each owning disjoint files | each node is committed on its branch, with its own checks green |
-| 7 | Verify | rounds per node, starting as each node lands | each node passes its risk class's rounds |
+| 7 | Verify | rounds per node, starting as each node lands; each finding triaged at discovery ([`finish-line.md`](finish-line.md)) | each node passes its risk class's rounds |
 | 8 | Seam check | cross-module checks per seam group | every seam the canvas names is exercised end to end |
 | 9 | Docs | stage 9 over everything the release iteration shipped | the doc gate passes and the docs match the code |
 | 10 | Release | versions, tags, pins, changelogs, in dependency order | the published artefacts resolve |
-| 11 | Post-release check | the stage-8 trio on what was released | every item the release claims closed is checked on the released artefact |
-| 12 | Next pool | the re-measured inventory and the proposal | the hand-back is sent |
+| 11 | Post-release check | the stage-8 trio on what was released, read as a finish-line round | every item the release claims closed is checked on the released artefact, and `finish:` is computed |
+| 12 | Next pool | the re-measured inventory and the proposal | the hand-back, with its `finish:` line, is sent |
 | 13 | Retrospective | the project retro, plus the shared lesson store where one exists | written last ([`retrospective.md`](retrospective.md)) |
 
 Steps 1–4 are stages 0–4 run once. Steps 6–8 are stages 5–8 per wave, and a wave's
@@ -218,7 +219,10 @@ actually published, installed or deployed — never on the branch. Each item the
 claims closed is re-checked against the released artefact. For installed packages and
 skills, follow [`deploy-targets.md`](deploy-targets.md) → *The verification trio*: update
 within the authorized rollout and read back each claimed installed channel. A failure goes to the hotfix
-lane if it is one of its five entries. Otherwise it goes to the next pool, with an id.
+lane if it is one of its five entries. Every post-release failure is triaged at the finish
+line ([`finish-line.md`](finish-line.md) → *Triage at discovery*): a blocking one is fixed in
+this release iteration, and the corrective release counts against `run.finish.maxReleases`; a
+deferred one goes to the next pool, with an id.
 
 ## The next pool
 

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

@@ -101,6 +101,11 @@ review cap reached — 3 rounds — artifact: test/validate.py
 - **New > self-inflicted** — the reader is still paying. Continuing is then the
   operator's call, made with the numbers in hand rather than out of fatigue.
 
+At the level of a whole iteration only new **blocking** findings argue for continuing; a
+deferred or noise finding is paid for on the board, not with another round
+([`finish-line.md`](finish-line.md) → *Rounds and the stop*). The class is read from the
+run ledger's `finding:` lines and the rounds from its `round:` lines, never from memory.
+
 **The pair is the whole point.** A round count alone says how tired everyone is; the
 pair says whether the loop still produces anything. Measured on one file once, the
 guard's shapes and the run's own prose disagreed — one still paying, one exhausted —

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

@@ -39,8 +39,19 @@ a row pointing outside the bundle is the defect this file exists to catch.
 
 | Workflow decision | Home |
 |---|---|
+| 0 · Stage procedure | `references/stage-00-intake.md` |
+| 1 · Stage procedure | `references/stage-01-docs-study.md` |
+| 2 · Stage procedure | `references/stage-02-brainstorm.md` |
+| 3 · Stage procedure | `references/stage-03-spec.md` |
+| 4 · Stage procedure | `references/stage-04-plan.md` |
+| 5 · Stage procedure | `references/stage-05-dev.md` |
+| 6 · Stage procedure | `references/stage-06-tests.md` |
+| 7 · Stage procedure | `references/stage-07-lint-deploy.md` |
+| 8 · Stage procedure | `references/stage-08-post-deploy.md` |
+| 9 · Stage procedure | `references/stage-09-docs-wiki.md` |
+| 10 · Stage procedure | `references/stage-10-acceptance.md` |
 | The stage list, ids, names, gate types | `pipeline.example.json` |
-| Per-stage criteria, freedom levels, the run checklist | `references/stages.md` |
+| Full gates, freedom levels, the run checklist and exact stage-detail routes | `references/stages.md` |
 | Which reference owns which stage (the doctrine map) | `references/doctrine-map.md` |
 | What the intake grill asks, and the autonomy sweep | `references/grill.md` |
 | **The escalation boundary** — what an agent may settle alone | `references/grill.md` |
@@ -53,6 +64,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | The entry audit and what it inspects | `references/setup.md` |
 | The ladder, seams, axis rotation, ratchets | `references/audit.md` |
 | Loop detection and its caps | `references/loop-guard.md` |
+| **The finish line** — when an iteration stops: the contract, triage at discovery, the round budget | `references/finish-line.md` |
 | **What the run prints about itself** — the header block, the rail, the iteration line | `references/progress.md` |
 | **What the run leaves running and leaves behind** — the eight classes, the `holds:` field, the teardown | `references/residue.md` |
 | **The run mode** — item-by-item pacing, default off, what it never collapses | `references/continuity.md` |

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

@@ -169,6 +169,9 @@ SCOPE       what this claim covers: the commit, the environment, the REQ
 NOT VERIFIED what was built and NOT checked, or could not be. The literal
             `none within the stated scope` is a valid answer; an empty
             field is not
+FINISH      finish: done | budget | blocked — the finish block, as
+            finish-line.md prints it; mid-iteration, the round and
+            the open blocking count
 
 DECISIONS WAITING  <n>   each as a question with options, asked HERE
 AMBIGUITIES        <n>   computed, below
@@ -189,6 +192,11 @@ And `none within the stated scope` is a claim with a subject — it says *nothin
 what SCOPE names is unverified*. Leaving the field empty says nothing at all, which reads
 as the same thing and is not: canon 9a, one artifact over.
 
+**`FINISH` says why the iteration stopped** ([`finish-line.md`](finish-line.md) → *The
+finish block*): `done` with its exit checks green on the artefact, `budget` with each open
+blocker a `needs-operator` board row, or `blocked`. A hand-back that cannot fill it has not
+reached a finish line, and says which round it is in.
+
 **Where there is no brief** — `checkup`, `setup`, a short path — TASK quotes the
 operator's own sentence instead, marked as such. An unquotable TASK is a run that cannot
 say what it was asked, which is worth its own line.

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

@@ -108,14 +108,19 @@ Review in this order; stop reading the diff only when you've covered all of it.
 **Severities:**
 
 - **Critical** — wrong behavior, data loss, security hole, a red or dishonest test
-  suite. Blocks.
+  suite. Blocks the node when the defect is in its diff or caused by it.
 - **Important** — a real defect or spec gap that will bite: missing requirement,
-  unhandled failure path, a magic value the constraints named. Blocks.
+  unhandled failure path, a magic value the constraints named. Blocks the node when the
+  defect is in its diff or caused by it.
 - **Minor** — style, naming, a nit with no behavioral consequence. Never blocks;
   goes to the ledger.
 - **⚠️ Cannot verify from diff** — the requirement lives in unchanged code or spans
   tasks. Not a blocker for the reviewer; the controller resolves it.
 
+**A pre-existing defect the reviewer notices** — one the diff neither contains nor
+causes — does not block the node, whatever its severity. It goes to finish-line triage
+([`finish-line.md`](finish-line.md) → *Triage at discovery*).
+
 Formatting nits that don't change meaning are not findings. Praise is not a
 finding either.
 

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

@@ -28,9 +28,12 @@ spec*.
 
 ## UX track (user-facing tasks only)
 
-Runs on **super-ux** — the one companion this pipeline recommends by name
-([`companion-skills.md`](companion-skills.md)). If it isn't installed on a UI task,
-give the install line and stop; don't improvise a half-chain.
+Apply [the artifact-provider contract](companion-skills.md): super-ux is the
+preferred provider; equivalent artifacts or the inline fallback remain valid.
+Missing or invalid scenario artifacts stop the gate, regardless of provider.
+Record each unavailable check by name as NOT_RUN; do not claim a linter ran.
+The following chain describes the super-ux provider when available. Other
+providers owe the same scenario quality and traces, not these package commands.
 
 0. **The design destination is already decided — read it, don't re-open it.** When
    Figma is on, the stage-0 brief names the team/org and the files — one per surface
@@ -94,8 +97,7 @@ green over both.
   not checkable; a record is. The track writes a **director record** in the product's
   repository, beside `docs/ux/`: `docs/design/<surface>/director-record.md`, a header
   line `surface_class: <class>` and one `## <Field>` heading per field. Which fields are
-  owed is the brief's `surface_class` ([`stages.md`](stages.md) → stage 0, *The surface
-  class*):
+  owed is the brief's `surface_class` ([`stage-00-intake.md`](stage-00-intake.md) → *0 — Intake grill — MANDATORY*, the surface-class bullet):
 
   | Class | Fields the record owes |
   |---|---|

package/plugins/task-pipeline/skills/task-pipeline/references/stage-00-intake.md

@@ -0,0 +1,158 @@
+# Stage 0 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## Contents
+
+- 0 — Intake grill — MANDATORY
+
+## 0 — Intake grill — MANDATORY
+- **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
+  entry-from-super-ux short-circuit below, and even that still requires a scope
+  confirmation and a record of what was adopted vs skipped. A run that reaches
+  stage 1 without a committed, operator-confirmed brief is a **failed run** —
+  stop and go back.
+- **Entry-from-super-ux short-circuit (check FIRST).** task-pipeline is often
+  launched *from* super-ux — its `/ux` action menu offers "execute autonomously
+  via the task-pipeline plugin" once the UX chain (and often a
+  `docs/ux/plans/…` fix plan) is already built. Before grilling, detect that:
+  if `docs/ux/` already holds a validated chain (foundation → flows → screens →
+  scenarios) and/or a fresh fix plan, **do not re-run the grill or the stage-3
+  UX track from scratch.** Instead: (1) run a quick check — `/ux-lint`
+  (`docs/ux/lint.py`) green, chain present, plan (if any) readable; (2) confirm
+  the scope with the operator in ONE line; (3) skip to the first stage that
+  still has real work (usually stage 4 Plan if a UX fix plan already exists, or
+  stage 3 Spec to formalize it). Record what was adopted vs skipped. If the
+  check finds drift/gaps, fall back to the normal flow for the missing parts
+  only.
+- **What (normal entry):** the operator's one-line task is almost never enough to
+  run autonomously. Before anything else, **grill the operator** to expand that
+  one line into a complete, unambiguous brief — resolve every decision branch
+  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, **the code graph**
+  when one is built ([`knowledge-graph.md`](knowledge-graph.md): `graphify query` /
+  `affected` / `god-nodes` answer *reach*, which is what grep cannot), `CLAUDE.md`,
+  `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs and carry-over
+  ledgers, **the retro's standing instructions and run stamps** (`<artifacts>/retro.md`,
+  read **in full** — ten standing rows and ten stamps, both bounded **by a cap**, and they bind this
+  run; stamp each instruction as it fires. Its *Recent log* is **queried** by the
+  task's nouns, not read: uncapped narrative inside a binding source is what makes the
+  capped part get skimmed, [`retrospective.md`](retrospective.md)), **lessons from other
+  projects** (source 7b, [`knowledge-sources.md`](knowledge-sources.md): `scripts/lessons.py
+  query` over the local index, then a shared store where the session lists one — each
+  layer's state printed in the source ledger), 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"; **the graph's row carries its measured lag — commits and
+  days behind `HEAD`, the signal that measured it, and `⚠ not trusted for reach
+  until refreshed` on anything but `current`**
+  ([`knowledge-graph.md`](knowledge-graph.md) → *Measure the lag*; a build date is
+  the graph's own reply about itself, not a measurement of it). 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.
+- **Phase 1b — the documentation inventory**
+  ([`documentation.md`](documentation.md)). Four questions, answered before the
+  interview and written to `docs/DOCMAP.md` (seeded from
+  [`../templates/docmap.md`](../templates/docmap.md), **only when absent**): where
+  do settled things live, what is each fact's single home, what does a change of
+  type X oblige, and what proves it. A project with no answers gets them seeded —
+  registers, the matrix and `scripts/check-docs.sh` — and the seeding is itself
+  recorded as the register's first entry. **One decision home per project:** an
+  existing `docs/adr/` *is* the register and is recorded as such, never duplicated.
+  The gate is seeded so that it exits `0` on its own seeds; a project that starts
+  red learns on day one that the gate is noise.
+- **Phase 1b+ — offer the entry audit, once** ([`setup.md`](setup.md)). When
+  `docs/DOCMAP.md` is absent or its regime line predates the project's last release,
+  ask whether to audit the documentation that already exists **before** building on
+  it. Record the answer — including a refusal — in the brief's autonomy sweep and
+  never ask again. `audit.md`'s ladder runs at the *end* over the change; this runs
+  at the *start* over what is already there.
+- **Phase 1c — reconcile intent against as-built.** Git says how it *should* be;
+  the run record says how it *turned out*. Read both for the area you are about to
+  touch and resolve every divergence — the document is stale, the record is wrong,
+  or they genuinely disagree and that is a decision. There is no fourth option, and
+  starting on an unresolved divergence means building against a system that does
+  not exist.
+- **Phase 1d — the short-path triage: printed, proposed, never taken silently.** This
+  pipeline's own boundary exempts a typo, a one-line fix and a mechanical rename — and
+  nothing measured that until 2026-08-10, so the exemption depended on an agent
+  remembering it while eleven stages and four manual gates stood in front of a
+  one-paragraph edit. Three questions, each with something behind it:
+
+  ```
+  1. files the request names, resolved        git ls-files -- <paths>       -> N
+  2. any of them a public contract            the surfaces the host's release
+                                              syncs, its schema or config
+                                              contracts, a shipped command,
+                                              its README                    -> yes/no
+  3. behaviour a user or a caller observes changes                          -> yes/no
+  ```
+
+  Few files, no contract, no observable change ⇒ **propose** the short path: stages 1,
+  2, 3 and 4 marked `⊘` with the triage answer as the reason, and 5→10 running
+  unchanged. **Propose, never take.** The answer goes in the brief's autonomy sweep and
+  silence takes the full flow — the same floor deploy authorization uses. The glyph is
+  what makes it safe: a skipped stage is printed on the rail **with its reason**
+  ([`progress.md`](progress.md)), and a skip nobody can see is indistinguishable from a
+  stage that was never entered.
+- **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
+  skill (nothing to install). In short: close what the sources can, then ONE batch
+  of the material unknowns, ordered by dependency, a recommended answer with each —
+  one at a time only where answers depend on each other or the operator asks;
+  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.
+  Deploy authorization has a hard floor there: a standing go counts only when it
+  names the target and the preconditions.
+- **The run mode is settled here too** ([`continuity.md`](continuity.md)): does
+  the run advance item-by-item with no check-in between items, and on what
+  interval? Exactly three sources arm it: `pipeline.json` → `run.loop` (read
+  first — a recorded mode is the answer and is not re-asked), the operator's answer
+  here, or a standing instruction the host already carries. The ledger names which, once:
+  `loop: armed by <source:line>`. **Absent all three, it is off.** It buys pacing, never
+  authorization: no loop mode collapses a `manual` gate or an outward act. The
+  same file carries the other half of pacing — the context budget, which fires
+  only on a harness signal or the operator's word, never on an estimate.
+- **UI early-detect:** one branch of the grill is always "does this touch a
+  user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
+  now (use it if installed; otherwise give the install line — see SKILL.md
+  *Prerequisites*); this arms the stage-3 UX track. **And the same branch records
+  the surface's class** — the next bullet.
+- **The surface class.** Every user-facing task's brief carries
+  `surface_class: flagship | product | internal | ad`, and the class selects the gate
+  profile the visual layer is held to for the rest of the run:
+
+  | Class | What it is | Director record (stage 3) | Visual half (stages 5–6) | Stage 10 |
+  |---|---|---|---|---|
+  | `flagship` | the surface a product is judged by — landing, onboarding, paywall, a hero screen | the full record | **gate**: full matrix, pairwise across every axis, the full rubric | approved contact sheet |
+  | `product` | an ordinary screen of the product | the short record — Brief, Mode, References, Markers, Open | **gate**: every state and the mandatory pairs; the gate items of the rubric | approved contact sheet |
+  | `internal` | an admin panel, an internal tool, a CLI | none owed | recommended; the project linter is the floor | the functional look |
+  | `ad` | a creative that runs as an advertisement or a store asset | Brief, Mode, References, Markers, ADA (its rubric profile and safe zones), Open | **gate**: the ad profile and the safe zones | approved contact sheet |
+
+  Ask it as one question with a recommended answer read off the request — a landing or a
+  paywall is `flagship` unless the operator says otherwise — and never leave it to stage
+  5: a class decided at build time is decided by whoever wants the build to pass. A
+  work-graph node that builds the surface copies the class as `surface_class`, and
+  `graph.py certify` then owes the fourth, `visual` reading on `flagship` and `product`
+  ([`certification.md`](certification.md) → *The fourth reading*).
+- **Artifact:** lock the resolved decisions into a **task brief** committed at
+  `<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict and,
+  for a user-facing task, `surface_class`, constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
+  autonomy sweep's per-stage answers and the model decision**. Seed it from
+  the skill's `templates/brief.md` skeleton — but only when absent, never
+  overwrite an existing brief. Stages 2–4 build on this brief; stages 5–10 read
+  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*.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-01-docs-study.md

@@ -0,0 +1,10 @@
+# Stage 1 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 1 — Docs study
+- **What:** ground every external library / API / SDK the task touches on the
+  *current* docs, before locking any contract.
+- **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.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-02-brainstorm.md

@@ -0,0 +1,52 @@
+# Stage 2 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 2 — Brainstorm + decompose
+- **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, the open questions in one
+  batch, 2–3 approaches with a recommendation, design presented in sections and
+  approved section by section. **Hard gate:** no code, no scaffolding, no implementation
+  skill before the operator approves the design — including on "obviously simple"
+  tasks.
+- **UI detection (mandatory check):** decide whether the task touches any
+  user-facing surface (web, mobile, CLI, TUI — new feature, new screen/command,
+  or a change to user-visible behavior). Record the verdict; it arms the UX
+  track in stage 3.
+- **Decomposition (platforms only): [`decomposition.md`](decomposition.md).** If
+  the brief describes a platform rather than a change — several independent
+  capabilities, several surfaces that could ship separately, REQs no single
+  deliverable satisfies — cut it into **modules** before any spec is written, and
+  commit the module map (`specs/<topic>-modules.md`): what each module delivers,
+  the entities it owns, what it depends on, the contracts it exposes, its REQs and
+  its status, in build order with the walking skeleton first. Single-module work
+  records `single module: <name>` in the design and moves on — a skipped
+  decomposition is a decision, never an omission.
+- **Where the queue is a work graph, it is WRITTEN here**
+  ([`work-graph.md`](work-graph.md)): `.task-pipeline/graph.json`, carrying the frozen REQ
+  ids so `serves` resolves, one node per unit of work with its owner, what it touches and
+  **the check that will close it**, and an edge per dependency **naming what it hands
+  over**. The check is the planner's job and not the verifier's: a node whose completion
+  test is decided by whoever happens to close it is a node two closes will disagree about,
+  and `validate` refuses one that names none. Then
+  `python3 scripts/graph.py validate` — a graph that does not validate is not a queue, and
+  `next` refuses to walk one. The reason to prefer it over a prose plan is measured, not
+  aesthetic: a 400-node graph and a 4-node graph produce the same 27-byte frontier, so the
+  cost of knowing what is next does not grow with the programme.
+- **And the check is what THREE readings will run, not one**
+  ([`certification.md`](certification.md)). A node is closed by `unit`, `seam` and `product`
+  reports, dispatched blind and in parallel, and `certify` refuses the close until all three
+  pass. That is a planning fact, not only a verification one: a node whose blast radius nobody
+  can name is a node the seam and product tiers cannot scope, so `touches` and `serves` are
+  what make the two outer readings possible at all.
+- **The queue exists here, so the loop arms here** ([`continuity.md`](continuity.md) →
+  *Part 1a*). Where the loop is armed — `run.loop` with `arm: after-decomposition`, the
+  operator's preflight answer, or a standing instruction the host carries (which arms here
+  unless it says otherwise) — and the map holds more than one module, arm the mode at the
+  close of this stage, cite the source as `loop: armed by <source:line>`, and print one
+  line: the mode, and
+  either the job id and its cancel command (`interval`) or the delay chosen and why
+  (`dynamic`). Arming collapses no gate and authorizes no outward act; it decides only
+  that the run does not stop to ask *"shall I take the next one?"*. Single-module work
+  arms nothing and says so — a loop with one item is a timer.

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

@@ -0,0 +1,66 @@
+# Stage 3 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 3 — Spec — with UX track for user-facing tasks
+- **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
+  review gate.
+- **UX track (runs FIRST when stage 2 flagged UI; skip entirely otherwise).**
+  Apply [the artifact-provider contract](companion-skills.md): super-ux is the
+  preferred provider; equivalent artifacts or the inline fallback remain valid.
+  Missing or invalid scenario artifacts stop the gate, regardless of provider.
+  Record each unavailable check by name as NOT_RUN; do not claim a linter ran.
+  The following chain describes the super-ux provider when available. Other
+  providers owe the same scenario quality and traces, not these package commands.
+  When using super-ux, walk its chain top-down (see its `system-map.md`):
+  0. **Destination first, when Figma is on.** The brief already names the team/org
+     and the files — **one per surface** (App, Web, ASO: store screenshots, icon and
+     logo), never one file for every frame; `docs/ux/foundation.md` → *Design tooling*
+     is the canonical record. Confirm each **resolves** before drawing. **Never create a file while a
+     recorded one resolves; if it doesn't resolve, stop and ask — never create a
+     replacement** (that is the duplicate, and it hides a permissions problem).
+     A creation happens at most once, in the named team, and its URL is written to
+     the canonical record before the first frame.
+  1. `/ux` (the only super-ux entry) — reports which `docs/ux/` layers exist,
+     repairs the skeleton, records the Figma on/off choice, recommends the next
+     action. Never make the operator pick skills.
+  2. `ux-foundation` → `docs/ux/foundation.md` — the **WHY**: personas, Jobs to
+     Be Done, **customer journey maps (CJM)**, user stories (Given/When/Then).
+  3. `ux-flows` → `docs/ux/flows.md` + `docs/ux/screens.md` — the **HOW + UI
+     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 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.
+  These skills are **idempotent** — reuse and extend existing `docs/ux/` layers,
+  never rebuild from scratch. If the chain already exists and is validated (e.g.
+  the task entered from super-ux), just verify (linter green) and embed it into
+  the spec; only build the parts that are missing.
+- **COPY track and VISUAL track — a parallel layer after UX, and their
+  convergence.** Three tracks, three questions, none substituting for another:
+  super-ux decides what the interface must **do**, `copywriting` how it
+  **sounds** (every string a product's user will read, against the brand pack),
+  `sheleg-design` how it **looks** (tokens, themes, typography, motion). COPY and
+  VISUAL are **parallel** — both consume the UX track's scenarios, neither
+  consumes the other — and where both ran, **their convergence check is run and
+  recorded before the spec is committed**: each can be right alone and the two
+  disagree together on one screen. The full doctrine — each track's scope and
+  out-of-scope, the refusal sentences, the four contradictions the check
+  catches — is [`spec.md`](spec.md) → *The COPY and VISUAL tracks, and their
+  convergence*, its one home. **The VISUAL track leaves a trace, not a fact**: a
+  director record at `docs/design/<surface>/director-record.md`, whose fields the gate
+  reads by the brief's `surface_class` (`python3 scripts/visual_gate.py record <file>
+  --class <c>`), and a refusal is that same file saying `Mode: declined` and why.
+- **Spec:** write the approved design to
+  `<artifacts>/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
+  shared contracts (types, schemas, signatures, file layout). For UI tasks the
+  spec **embeds the UX layer**: links the validated scenario IDs, the flows and
+  `SCR-` screens, the CJM stages the feature serves, and the UX
+  patterns/principles from super-ux that apply (`best-practices.md`,
+  `ux-design-principles.md`, `component-guidelines.md`).

package/plugins/task-pipeline/skills/task-pipeline/references/stage-04-plan.md

@@ -0,0 +1,11 @@
+# Stage 4 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 4 — Plan
+- **How it runs: [`planning.md`](planning.md)** — built into this skill →
+  `<artifacts>/plans/YYYY-MM-DD-<topic>.md` (same slug as the brief and the
+  spec). Zero-context tasks, exact
+  paths, complete code in every step, TDD steps with expected output, DoD each,
+  dependency graph + parallel groups, non-overlapping file ownership, and the
+  Global Constraints block copied verbatim from the spec.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-05-dev.md

@@ -0,0 +1,55 @@
+# Stage 5 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 5 — Dev
+- **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,
+  then one fresh implementer subagent per task with a file-based brief and report,
+  a review after every task ([`review.md`](review.md)), and a five-round fix loop
+  with an explicit breaker. TDD per task ([`tdd.md`](tdd.md)): failing test →
+  watch it fail → minimal impl → watch it pass → commit. Pin subagents to the
+  run's confirmed model (`model-tiering.md`). The plan's parallel groups fan out
+  **only when all three hold** — the tasks share no `depends:`, their file ownership
+  is exclusive per the plan, and each implementer gets its own worktree; otherwise
+  sequential. A group that did fan out gets **one convergence check over all its
+  reports and diffs together, before the first worktree is integrated**
+  ([`build.md`](build.md) §4.2a) — a per-task review reads one diff and cannot see a
+  contradiction that exists only between two of them.
+- **Web front end? The task's own surface is checked in a browser, not in the diff.**
+  Where a browser channel is connected — `playwright` **or** `chrome-devtools`, either
+  one, whichever answers first (**how**: [`browser.md`](browser.md); which:
+  [`companion-skills.md`](companion-skills.md)): after a
+  task that changes a rendered surface, load it, take a snapshot and read the
+  console and the network log **before the task is marked DONE** — a component can be
+  correct and land under a fixed header, and a review of the diff cannot see that.
+  **What the look finds is fixed in this task, or parked with the ruling the GATE below
+  requires — never parked silently** — a browser finding filed without a ruling is the
+  diff-review verdict wearing a screenshot; the look was worth taking only if it can
+  still change the code or is on record as deliberately not doing so. Absent, say the surface was verified by reading
+  the diff and treat it as the weaker claim it is. **On a surface whose brief names a
+  `surface_class`, the project linter runs here too**, after each task that changes a
+  rendered surface — `python3 scripts/visual_gate.py lint <dir>`; an S1 finding is
+  fixed in the task, and NOT_RUN (exit 3) is recorded as such
+  ([`browser.md`](browser.md) → *The visual half*). **With Figma on, the token drift
+  probe runs beside it** after a task that touches the token file or a tokenised
+  component: `python3 scripts/visual_gate.py tokens --figma <variables.json> --css
+  <tokens.css>`. A FAIL is fixed in the task, renaming one side to match the other.
+  No export is NOT_RUN, recorded as such. A component whose API the task changed
+  updates its Code Connect mapping in the same change
+  ([`build.md`](build.md) → *Code Connect, kept*). A slop marker caught while the
+  implementer is dispatched costs a line; caught on the contact sheet it costs a round. Stage 6 repeats this over the whole tree; this one catches it while the
+  implementer that wrote it is still dispatched. The matrix pointed this companion at
+  stages 5–6 from the day it was added and **this stage had never named it** — found by
+  the guard comparing the two, not by a reader.
+- **Domain companions, where the task is on their ground** — recommended, never a
+  gate ([`companion-skills.md`](companion-skills.md)): `sheleg-dev` when the build
+  wires money, tracking, sign-in or page speed; `agent-stack` when the thing being
+  built is an agent system; `telegram-dev` when Telegram is the platform rather
+  than the transport. Absent, the build ships on the host's own doctrine and the
+  close-out names the seam nobody checked.
+- **Integration closes the stage:** sync with the base branch, re-run the full suite
+  on the result, land it the project's way (merge, or a PR — outward, so it needs a
+  go), remove the worktree. Stages 7–9 act on the integrated result, so a branch the
+  operator chose to leave unmerged is recorded as such.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-06-tests.md

@@ -0,0 +1,11 @@
+# Stage 6 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 6 — Tests
+- **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.
+- **Invoke:** the host test runner (see `conventions.md` → *Lint + test*); the
+  built-in [`tdd.md`](tdd.md) cycle for any uncovered gap — failing test first,
+  same as stage 5.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-07-lint-deploy.md

@@ -0,0 +1,15 @@
+# Stage 7 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 7 — Lint + deploy
+- 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 —
+  it must pass too (no UX drift merges). Then deploy per the project's convention;
+  if the project defines release automation (`pipeline.json` → `release`, toggle
+  on), that is what "deploy" runs here. **No runbook, or one too thin to act on?
+  Write it first** ([`deploy-targets.md`](deploy-targets.md)) — a deploy performed
+  from inference about the project is one nobody can repeat or roll back, and the
+  operator is standing at this gate anyway. That reference also carries the CLI
+  verbs per target for when the runbook names a platform you have to recall.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-08-post-deploy.md

@@ -0,0 +1,29 @@
+# Stage 8 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 8 — Post-deploy
+- Tail deploy logs / health-check per conventions. Confirm clean boot, no error
+  spike, live subsystems healthy. **All three of the verification trio, not one of
+  them** ([`deploy-targets.md`](deploy-targets.md) → *The verification trio*):
+  deployment/process state, runtime logs, and a health-check request from outside.
+  Where deploy happens in CI, verify the **deploy** job and not only the build —
+  a green build beside a skipped deploy is the commonest way a run reports success
+  while nothing shipped.
+- **A deployed web target is opened, not curled.** A `200` proves the server
+  answered; it says nothing about whether the page rendered, whether a bundle 404'd,
+  or whether the console filled with errors on load — all three ship green past a
+  health check. Where a browser channel is connected — `playwright` **or**
+  `chrome-devtools`, either one ([`browser.md`](browser.md)) — load the deployed URL and read
+  the console and the network log; quote what you read, not that you looked
+  ([`companion-skills.md`](companion-skills.md)). Absent → say the check was an HTTP
+  response only, which is the honest name for it.
+- **Read the CI verdict for the deploy's own commit** ([`conventions.md`](conventions.md)
+  → *The CI verdict*): the run's conclusion quoted, the **failing step's log quoted**
+  on anything but `success`, and one of the three states stated — including **`no run
+  found`**, out loud, because a project without CI is a legitimate state and not a
+  green one.
+- **A public surface a logged-out reader will see** can additionally be audited for
+  search and answer-engine visibility with `seo-aeo-audit`
+  ([`companion-skills.md`](companion-skills.md)) — recommended, never a gate;
+  absent, visibility ships unaudited and the close-out says so.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-09-docs-wiki.md

@@ -0,0 +1,45 @@
+# Stage 9 detail
+
+The full gate and freedom level remain in [stages.md](stages.md).
+
+## 9 — Docs + wiki
+- **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
+  them is where documentation rots — the document nobody read is exactly the
+  document nobody updated. Walk the matrix row for **every** change type this run
+  produced. Every settled thing gets an id in the register, every answered question
+  is flipped to `Resolved→<id>`, and every document named in a
+  `Consequences / affects:` line cites its decision.
+- **Then run the documentation gate** (`bash scripts/check-docs.sh`, or whatever
+  `docs/DOCMAP.md` → *Gates* names) and print its **ratchet counts** beside the
+  verdict, so "green" reads as *"green, and here is exactly what was not looked
+  at"* ([`gates.md`](gates.md)). A check that skipped says so.
+- **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).
+- **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.
+- **Refresh the code graph** — `/graphify . --update` when one exists
+  ([`knowledge-graph.md`](knowledge-graph.md)). The close-out has **three**
+  artifacts, not two: docs, wiki, graph. The graph is the source the *next* run's
+  harvest queries first, so a stale one is a false premise carrying the authority of
+  a machine — a wrong doc gets argued with, a wrong graph gets believed. Incremental
+  and model-free for code; a run that deleted code legitimately rebuilds smaller
+  (`--force`).
+- **Then check the graph against the docs** — the cheap half of the divergence sweep
+  (`graphify god-nodes`; any doc naming a module the graph no longer has). A hub no
+  doc names, or an edge the docs deny, is either a leak in the code or a lie in the
+  docs; a doc naming a node that no longer exists is a stale ledger row found
+  mechanically. Doc-side findings are fixed here; **absences go to stage 10's ladder
+  walk as REQ rows** ([`audit.md`](audit.md)).
+- **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.