@mmerterden/multi-agent-pipeline 10.8.0 → 10.12.0

package/CHANGELOG.md

@@ -14,6 +14,188 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [10.12.0] - 2026-07-06
+
+Two trust upgrades: every external channel post now shows a plan-mode-style
+preview + approval gate before anything is written (autopilot posts directly),
+and Phase 0 gains a proactive token expiry pre-flight with silent Figma MCP
+renewal via OAuth refresh grant.
+
+### Added
+
+- **Channels Step 6 body preview + approval gate** (dispatch → Step 7,
+  summary → Step 8) - interactive runs render
+  every selected channel's final body (PR description, Jira comment,
+  Confluence page, Wiki, Board move, GitHub issue comment) and ask
+  Approve & post / Edit (loop) / Skip channels / Cancel before dispatch.
+  Bypassed only by autopilot and `--dry-run`. What is posted is byte-identical
+  to the approved preview; regeneration after approval re-runs the gate.
+  Phase 7 Step 1.5 (issue comment + progress flags) routes through the same
+  gate. Contract: `smoke-channels-approval-gate.sh`.
+- **Phase 0 Step 0.7 token expiry pre-flight** - probes every token the run
+  will need (jira/github/bitbucket/confluence/figma/figma_mcp) with one cheap
+  call each (cached via `serviceStatus`, TTL 300s) and resolves expiry AT INIT
+  instead of on the first mid-run 401. Figma MCP is the critical path: silent
+  renewal first, then an init-time question (Regenerate now via script / Save
+  Flow / Continue degraded). Autopilot never prompts - silent renewal or
+  logged degrade. Contract: `smoke-token-preflight.sh`.
+- **`lib/figma-mcp-refresh.sh`** - silent Figma MCP (`figu_`) renewal via
+  OAuth refresh grant: reads `<key>_Refresh` from the Keychain + client
+  credentials from the `.figma-oauth.json` next to
+  `prefs.global.tokenScripts.figma_mcp`, saves the new access (and rotated
+  refresh) token back. Status lines only - token values never printed.
+  Live-verified end-to-end (renewed + mcp.figma.com probe 200).
+- **`prefs.global.tokenScripts`** (schema + template) - maps service ids to
+  user-owned token generation scripts; personal paths stay in the local
+  preferences file, never in synced command files.
+- **keychain.md Figma MCP lifecycle section** - refresh-entry convention,
+  silent-renewal-first rule, generation-script escalation, init cross-ref.
+
+### Fixed
+
+- Copilot parity catch-ups the 10.11.0 sweep missed: `multi-agent-sync/SKILL.md`
+  inventory 35 -> 37 + list, `multi-agent-help/SKILL.md` generator entries
+  (EN + TR), `multi-agent-channels/SKILL.md` flow now includes the approval
+  gate (steps 6-8). `smoke-generate-issue.sh` now asserts the SKILL-side
+  counts too.
+- `figma-mcp-refresh.sh` form fields sent via `--data-urlencode` (robust to
+  special characters in tokens); re-verified live.
+
+## [10.11.0] - 2026-07-06
+
+Jira issue generators: `/multi-agent:generate-task` and `/multi-agent:generate-bug` create standards-compliant Jira issues by learning the target project's own conventions before drafting, with a hard preview + approval gate before anything is created.
+
+### Added
+
+- **`/multi-agent:generate-task` + `/multi-agent:generate-bug`** - one-shot
+  Jira issue creators (no worktree, no commits, no pipeline chaining). Inputs:
+  optional free-text description + optional Figma URL; both asked
+  interactively when missing.
+- **Convention mining** - samples the project's 30 most recent same-type
+  issues (JQL) and adopts the team's summary prefix pattern, dominant
+  description heading set, top labels/components, and priority norm.
+  createmeta discovery surfaces required custom fields (allowedValues become
+  picker options) and detects Sprint/Epic/Team fields generically by
+  `schema.custom` id.
+- **Active-sprint placement** - Agile REST board + `sprint?state=active`
+  detection; the user chooses active sprint vs backlog. Sprint assignment
+  happens post-create via `POST /rest/agile/1.0/sprint/{id}/issue`
+  (field-id-agnostic). No board / no active sprint degrades to backlog with
+  an explicit note.
+- **Hard approval gate** - a full draft preview (every field + complete
+  description) renders before create; Approve / Edit (loop) / Cancel. The
+  gate has no bypass: no autopilot variant exists for these commands.
+  Genuinely unknown fields (component, epic, priority, labels, assignee,
+  sprint, required customs, missing Bug repro/environment) are asked, never
+  invented.
+- **Figma context (optional)** - the 3-tier chain (MCP -> REST PAT -> user
+  screenshot) resolves frame name + node id for a Design Reference section,
+  a remote link on the created issue, and an opt-in screenshot attachment.
+  Standalone command, so MCP use is allowed (analysis-class); Figma failures
+  never block issue creation.
+- **Language rule** - issue summary + description follow
+  `prefs.global.outputLanguage` (intentional exception to the
+  external-payloads-English default; the issue is authored for the user's
+  team). Documented in both command files and the shared ref.
+- **Shared flow ref** `refs/generate-issue.md` - single 11-step contract
+  consumed by both commands via profile blocks (`ISSUE_TYPE`, default
+  sections, JQL filter); UTF-8 verbatim POST path (`jq --rawfile` +
+  `--data-binary @file`) and humanizer pass reused from the Jira channel
+  adapter.
+- **Smoke gate** `smoke-generate-issue.sh` - 66 assertions: file/frontmatter
+  presence, profile declarations, approval-gate markers, endpoint markers,
+  UTF-8 path, section vocabulary, 37-command count consistency across
+  dispatcher/contract/sync/help, forbidden-string scan.
+
+### Changed
+
+- Command inventory 35 -> 37 across `cross-cli-contract.md`, `sync.md`,
+  dispatcher routing/loading tables, `help.md` (EN + TR), README.
+
+## [10.10.0] - 2026-07-03
+
+Live tracker UX: per-tile cost, a real "currently doing X" line, and tracker continuity across the local-test handover. Shaped by a market sweep of 2026 agent-UX practice (transparency-first live status; per-step cost visibility).
+
+### Added
+
+- **`phase-tracker.sh now <N> "<text>"`** - dedicated live current-action
+  line for the active phase (quiet: writes `meta.Now`, never renders, 60-char
+  cap). The bordered card shows it as `Now: <text>` under the active tile.
+- **`phase-tracker.sh cost <N>|total`** - single pricing implementation
+  (cost-table.json rates, cached tokens at the discounted cacheRead rate,
+  floored to cents; `-` when unpriceable). The completion narration line,
+  the card, and finish's summary all reuse it - no more inline USD math.
+- **Per-tile est. USD + cached footer on the bash card.** Tiles render
+  `<elapsed> · <tok> tok · ~$<usd>` when the phase has a priced model; the
+  footer adds total USD and cached tokens. Render survives a missing cost
+  table. Tiles now sort by numeric phase id so continuation sets stay ordered.
+- **Progress-line mirror rule** (tracker-contract "Active phase" +
+  progress-contract cross-link): every normal-tier `→ verb object` line is
+  mirrored to the active phase - `TaskUpdate activeForm` on Claude Code,
+  `now` elsewhere - so the tracker always answers "what is it doing right
+  now". Throttled: canonical lines only, dedupe, no renders.
+- **Completion tile suffix (Claude Code):** on phase completion the tile
+  subject gains the spend (`Phase 3: Dev · ~35k tok · ~$0.58`); subject edits
+  do not reorder tiles.
+- **Tracker continuity across the local-test handover.** Phase 5 and
+  `/multi-agent:manual-test` mark the waiting state
+  (`now 5 "awaiting local test (user)"`); `/multi-agent:finish` now runs
+  load-or-continue instead of an unconditional `init` - prior phase 0-3
+  history (elapsed, tokens, USD) survives, Phase 5 is closed with a Result
+  meta, the Claude Code TaskList is rebuilt from state, and one line
+  summarizes the inherited history (`Continuing <id>: phases 0-3 finished
+  earlier (12m, 38.4k tok, ~$0.74)`). `add` is idempotent to make this safe.
+- **`/multi-agent:resume` rebuilds the phase tiles** from `tracker-state.json`
+  (the contract documented it; the command now actually does it).
+- **Phase 0 + 7 token forwarding**: the clarifier call and the Phase 7 report
+  compose call forward tokens to the tracker, completing all 8 tiles.
+
+### Fixed
+
+- Tracker doc drift: the `tokens` action's 4th `[cached]` arg and the `model`
+  action are now documented in the contract and the script usage text.
+
+---
+
+## [10.9.0] - 2026-07-03
+
+### Added
+
+- **Update check at run start (Phase 0 Step 0.6, opt-out via
+  `prefs.global.updateCheck`).** Once per `ttlHours` window (default 24h,
+  cached, 3s-bounded curl straight to the npm registry - never `npm view`),
+  the pipeline compares the installed version against `dist-tags.latest`.
+  Newer version found: interactive modes ask ONE question ("Update now?" ->
+  yes runs the `/multi-agent:update` flow and the run continues; the update
+  takes full effect next session); autopilot logs one line and never asks
+  (zero-interaction contract). `autoUpdate: true` skips the question and
+  updates before the worktree is created. Offline, ahead-of-registry, and
+  failed checks are silent - the step never blocks. New
+  `pipeline/scripts/update-check.sh` + `smoke-update-check.sh` (13 assertions).
+- **Design fidelity contract (Phase 3, BLOCKING on Figma-referenced tasks).**
+  The analysis doc's captured frames are the 1:1 reference for every UI line:
+  a Code Connect-mapped component must be used verbatim (no sound-alikes,
+  missing modifiers go into `+Modifiers`, never forks), unmapped UI becomes a
+  NEW component under the standard architecture, and inter-component spacing
+  comes from the design's measured values mapped to tokens - never invented.
+  Missing design data halts with a re-run-analysis instruction; Figma MCP
+  stays forbidden outside analysis.
+- **`docs/engineering.md`** - version-free catalog of the discipline layer
+  (bounded loops, evidence gates, token-budgeted phase docs, immutable tests,
+  fresh-context handoffs, memory hedges, install hygiene), linked from README.
+
+### Changed
+
+- **Docs drop inline version markers.** `docs/features.md` headers and bullets
+  no longer carry `(vX.Y.Z)` tags - the docs describe the current state;
+  history lives in this CHANGELOG. Same principle applied to the website copy.
+- **Phase-doc token budgets recalibrated** (`token-budget.json`, total
+  46500 -> 50000) after the verify-by-test, update-check, immutable-test, and
+  design-fidelity contracts landed - Step 3.7 prose was compressed to a
+  pointer into `refs/features/verify-by-test.md` before recalibration.
+
+---
+
 ## [10.8.0] - 2026-07-02
 
 Three additive loop-quality features, all sourced from the 2026 agentic-loop research sweep (Anthropic long-running-agent harness guidance + adversarial-review findings): empirical verification of blocking findings, an immutable-test contract, and structured phase-boundary handoffs.

package/README.md

@@ -51,6 +51,8 @@ One command runs 8 phases, with a gate between the risky ones:
 
 Under the hood: each task runs in its own **git worktree** (or the current branch with `:local`), commits use the **git identity routed from the repo's origin URL**, and **multi-repo** tasks get per-repo worktrees plus an integration build. Tokens stay in the OS keychain; nothing is committed or logged. `/multi-agent:review` can also review an existing GitHub/Bitbucket PR — per-finding inline comments anchored to `file:line` + an explicit Approve / Needs-Work state.
 
+The discipline behind all of this — bounded loops, evidence gates, token-budgeted phase docs, immutable tests, fresh-context handoffs — is catalogued in [docs/engineering.md](./docs/engineering.md). The full feature list lives in [docs/features.md](./docs/features.md).
+
 ## Modes
 
 | Mode | Command | Flow |
@@ -61,7 +63,7 @@ Under the hood: each task runs in its own **git worktree** (or the current branc
 | Local | `/multi-agent:local "task"` | Full pipeline, current branch (no worktree) |
 | Finish | `/multi-agent:finish` | Run the review→test→commit→report tail over local work |
 
-Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `jira`, `issue`, `analysis`. Full list: `/multi-agent:help`.
+Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `jira`, `issue`, `analysis`, `generate-task`, `generate-bug`. Full list: `/multi-agent:help`.
 
 ## Stacks
 

package/docs/engineering.md

@@ -0,0 +1,76 @@
+# Engineering Discipline
+
+The pipeline's output quality comes less from any single model call and more from the constraints wrapped around every call. This page lists those constraints - the internals that keep long agentic runs correct, cheap, and auditable. No version markers here; this document always describes the current state (history lives in the [CHANGELOG](../CHANGELOG.md)).
+
+## Loop discipline
+
+Every loop in the pipeline has a deterministic exit condition and a hard iteration cap. Nothing "keeps trying".
+
+- **TDD micro-loop** (Phase 3): red -> green -> refactor per task; build-fix retries capped at 3 attempts.
+- **Dev-critic loop** (Phase 3.5, opt-in): generator vs critic on deterministic criteria; max 2 iterations, round 3 escalates to the user.
+- **Review-fix macro-loop** (Phase 3 <-> 4): only triage-accepted blocking findings re-enter development; max 3 iterations, then hard-kill and escalate.
+- **Disagreement round** (Phase 4, opt-in): when reviewers split, exactly one rebuttal round - never more.
+- **Global rule**: any retry loop stops after 3 attempts and asks the user. No exceptions, no infinite loops.
+
+## Evidence over claims
+
+- **Default-FAIL evidence gate**: a "build passed" or "tests passed" claim is rejected unless the captured log actually shows success. Missing, empty, or failure-marked logs fail CLOSED.
+- **Verify-by-test** (opt-in): an accepted blocking review finding can be empirically confirmed - a verifier agent writes a minimal repro test and runs it. Test fails as predicted: the finding stands and the failing test is handed to the rework loop as its RED test. Test passes: the finding is downgraded, and even the downgrade must pass the evidence gate.
+- **Deterministic validator gates**: triage output, reviewer output, diff-risk output, and agent state are schema-validated by zero-dependency scripts whose exit codes decide the flow - one self-correction rework, then halt with a recovery hint. The LLM never grades its own homework.
+
+## Test integrity
+
+- **Immutable tests**: deleting, renaming, or weakening an existing test to get a green run is a rule violation. A test changes only when the task changes the spec it encodes, named in the commit body.
+- **Deterministic backstop**: the diff-risk scorer flags any test file whose diff removes more lines than it adds (`test_lines_removed`), so a shrinking test suite surfaces to reviewers even if the rule is ignored.
+- **Test-gap detection**: newly added public symbols with no paired test are reported before the test phase.
+
+## Context management
+
+- **Token-budgeted phase docs**: every phase document has a per-file and total token budget enforced by a smoke gate (`token-budget.json`). Growth is compressed first; budgets are recalibrated only when real contract text lands. This keeps the orchestrator's working context lean across an 8-phase run.
+- **Lazy loading**: only the active phase's document is in context; references load on demand.
+- **Structured handoff blocks**: at every phase boundary the orchestrator appends a Done / Remaining / Decisions / Open findings / Next block to the run log - written from state it already holds, no extra model call. Resume and post-compaction re-entry read the latest handoff plus the state file, never the conversation history.
+- **Proactive compaction**: past ~50% context usage the run compacts itself and re-grounds from durable artifacts instead of waiting for lossy auto-compaction.
+
+## Review architecture
+
+- **Deterministic gates before AI review**: build, lint, tests, and secret scan must be green before a single reviewer token is spent.
+- **Cross-model parallel review**: independent reviewers with different vantage points, then a triage pass that filters false positives and out-of-scope noise. Reviewer findings are raw signals, not commands - nothing auto-loops on a "blocking" tag.
+- **Consensus surfacing**: unanimous agreement between same-base-model reviewers on judgment-heavy surfaces is flagged as unverified instead of being trusted as independent confirmation.
+- **Diff risk scoring**: a sub-second, zero-LLM heuristic ranks changed files (security paths, migrations, missing tests, shrinking tests) and feeds reviewers a priority hint - advisory, never a gate.
+- **Prompt-cache-aware dispatch**: reviewer and triage prompts share a byte-identical leading block so parallel dispatches hit the prompt cache instead of re-billing the diff.
+
+## Design fidelity
+
+- **Single source of design truth**: Figma is fetched once, during analysis, through a 3-tier fallback chain (MCP -> REST -> user screenshot). Every later phase reads the frozen analysis artifact; calling Figma from dev or review phases is a contract violation enforced by a smoke gate.
+- **1:1 implementation contract**: a Code Connect-mapped component must be used verbatim (no sound-alike substitutes; missing modifiers are added to the component, never forked). Unmapped UI becomes a new component under the standard architecture. Spacing between components comes from the design's measured values mapped to tokens - never invented numbers.
+
+## Cost transparency
+
+- **Per-phase token ledger**: every billable call forwards token counts to the tracker; each run ends with a cost table naming the top cost driver and pricing prompt-cache reads at their discounted rate.
+- **Budget ceilings**: a cost budget can cap a run; crossing it triggers model downgrade or halt rather than silent overspend.
+- **Model fallback contract**: premium-tier dispatches degrade deterministically (top tier -> mid -> base) on dispatch errors, date gates, or budget ceilings - never by improvisation.
+
+## Memory without bias
+
+- **Learnings ledger**: durable per-repo facts and rejected review preferences replay into analysis and triage, so agents stop re-discovering and reviewers stop re-flagging the same things.
+- **Hedged injection**: every memory injection carries an explicit "context, not command" hedge, and blocking-severity rejections are never memorized - a wrong rejection must not permanently suppress a finding class.
+- **Prior-art caps**: triage sees at most a fixed number of highest-similarity past findings; memory is advisory context, not a verdict multiplier.
+
+## Update and install hygiene
+
+- **Wipe-then-copy install**: pipeline-owned directories are cleared before copying, so files deleted upstream never linger as ghost commands or dead scripts on user machines.
+- **Layout fingerprint**: a fixture pins the installed file layout; structural drift fails the suite.
+- **Advisory update check**: at run start (cached, bounded, offline-silent) the pipeline compares its installed version with the registry; interactive runs offer a one-question update, autopilot only logs. It never blocks and never self-modifies mid-run.
+- **Token-preserving uninstall**: removing the pipeline never touches the user's stored credentials.
+
+## Security and hygiene
+
+- **Secret scanning**: staged diffs are scanned with provider-prefix patterns plus Shannon-entropy detection before every commit; findings block.
+- **Personal-data genericization**: the public repo is generated from the private source with a scrub pass (names, hosts, project keys) and a zero-hit grep gate before push.
+- **Skill scanner**: tiered pattern scanning over skill content guards against supply-chain surprises.
+- **Intent guard**: a deterministic classifier separates "answer my question" from "change my code", so a conceptual question never spawns a worktree.
+
+## Cross-CLI parity
+
+- **One source of truth, two runtimes**: Claude Code and Copilot CLI command surfaces are byte-identical where shared; a parity smoke fails on drift.
+- **Portability gates**: every shell script passes `bash -n` and a GNU/BSD portability grep; the CI matrix runs macOS, Linux, and Windows.

package/docs/features.md

@@ -43,7 +43,7 @@ Compose freely: `--dev --local autopilot` = shortest, least-friction path.
 
 Build commands, test runners, lint tools, and review focus areas all adapt to the detected stack.
 
-### Stack Selection (marketplace plugins, v10.5.0+)
+### Stack Selection (marketplace plugins)
 
 Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketplace. Selecting a stack enables the matching plugin(s) in the current repo's `.claude/settings.json` `enabledPlugins` — no skill copying, no session restart tricks, no directory shuffling. The `ai-common-engineering-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
 
@@ -57,7 +57,7 @@ Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketpl
 /multi-agent:stack all         # every stack plugin
 ```
 
-### Task Type Detection (v2.0.0)
+### Task Type Detection
 
 Phase 0 Step 9 classifies every task before Phase 1 starts. Deterministic priority order: Figma URL → instruction file path → git diff heuristic → Jira issue type → branch name → description keywords → user prompt (autopilot defaults to `feature`).
 
@@ -71,26 +71,26 @@ Result persisted to `agent-state.taskType`:
 | `refactor`  | Phase 4 emphasizes behavior preservation; Phase 6 uses `refactor(...)` prefix |
 | `chore`     | Lightweight flow; Phase 6 uses `chore(...)` prefix                            |
 
-### SubPhase Convention (v2.0.0)
+### SubPhase Convention
 
-When a specialized skill takes over a main pipeline phase, progress is reported as SubPhases (e.g. `SubPhase 3.0: Init`, `SubPhase 3.1: Gather`). The top-level pipeline stays fixed at 8 phases (0-7 — Phase 6.5 was merged into Phase 7 REPORT in v5.1.0) — specialized work slots into its parent phase without inflating the count.
+When a specialized skill takes over a main pipeline phase, progress is reported as SubPhases (e.g. `SubPhase 3.0: Init`, `SubPhase 3.1: Gather`). The top-level pipeline stays fixed at 8 phases (0-7) — specialized work slots into its parent phase without inflating the count.
 
 ## PR & Review Flow
 
-### Default Reviewers (v1.6.1, hardened in v2.0.0)
+### Default Reviewers
 
 - **Bitbucket**: Fetches via `/rest/default-reviewers/1.0/`. Every PUT must re-send `reviewers`, `fromRef`, `toRef`, `draft` (regression guarded by smoke test).
 - **GitHub**: Honors `CODEOWNERS` + falls back to `prefs.projects[].githubDefaultReviewers`.
 - PR author always filtered out (Bitbucket: 409, GitHub: GraphQL error).
 
-### Draft vs Ready Prompt (v1.7.0)
+### Draft vs Ready Prompt
 
 Phase 6 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`.
 
 - Bitbucket: `draft: true` flag (DC 8.x+) with `[DRAFT]` title fallback for older servers.
 - GitHub: `gh pr create --draft` + `gh pr ready` for promotion.
 
-### `channels` Command (v5.7.0 — replaces `enrich`)
+### `channels` Command
 
 Multi-channel reporter — Phase 7 delegates to it, and it's also invocable post-hoc for fixes closed outside the pipeline:
 
@@ -102,9 +102,9 @@ Multi-channel reporter — Phase 7 delegates to it, and it's also invocable post
 /multi-agent:channels ABC-1234 --channels jira,confluence --content test
 ```
 
-Multi-select **channels** (Jira / Confluence / Wiki / PR description) × multi-select **content** (normal analysis / test scenarios / auto-diff summary / manual note). Each body runs through the humanizer skill per-channel. Bitbucket PR updates use the reviewer-preserving PUT pattern (title + description + reviewers + fromRef + toRef + version mandatory). Replaces the pre-v5.7 `enrich` command — all its capabilities (diff auto-summarize, manual mode, reviewer-preserving) are preserved; Confluence + Wiki are new.
+Multi-select **channels** (Jira / Confluence / Wiki / PR description) × multi-select **content** (normal analysis / test scenarios / auto-diff summary / manual note). Each body runs through the humanizer skill per-channel. Bitbucket PR updates use the reviewer-preserving PUT pattern (title + description + reviewers + fromRef + toRef + version mandatory). Replaces the earlier `enrich` command — all its capabilities (diff auto-summarize, manual mode, reviewer-preserving) are preserved; Confluence + Wiki are new.
 
-### Body Preservation Contract (v1.6.1, verified by smoke test in v2.0.0)
+### Body Preservation Contract (smoke-verified)
 
 Every external-system body (PR description, Jira comment, GitHub issue) uses `jq -n --rawfile body body.md '{description: $body}'` → `curl --data-binary @payload.json`. No literal `\n` strings, no HTML entities (`&`, `<`, `"`). UTF-8 preserved end-to-end. `scripts/smoke-add-detail.sh` runs 14 contract assertions.
 
@@ -137,7 +137,7 @@ The reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers in paralle
 
 **Fable Triage** (Phase 4 Step 3, Opus on Copilot CLI): Evaluates merged raw findings against task scope. Classifies each as `accepted` (fix now), `deferred` (out of scope, log for later), or `rejected` (false positive / noise). Only triage-accepted blocking items loop back to Phase 3.
 
-### Runtime Triage Validator (v2.3.0)
+### Runtime Triage Validator
 
 After triage returns, output is validated by `validate-triage.mjs`:
 
@@ -148,19 +148,23 @@ After triage returns, output is validated by `validate-triage.mjs`:
 | **2** | Over-rejection guard tripped — pause for human               |
 | **3** | Contradiction auto-corrected — proceed with corrected output |
 
-### Bidirectional Approved↔Blocking Auto-Correction (v2.6.1)
+### Bidirectional Approved↔Blocking Auto-Correction
 
-If triage returns `approved: false` but has no blocking items, the validator forces `approved: true`. Conversely, if `approved: true` but blocking items exist, it forces `approved: false`. Hardened with `if`/`then` constraint in schema v3.0.0.
+If triage returns `approved: false` but has no blocking items, the validator forces `approved: true`. Conversely, if `approved: true` but blocking items exist, it forces `approved: false`. Hardened with an `if`/`then` constraint in the schema itself.
 
-### Verify-by-Test Triage (Phase 4 Step 3.7, v10.8.0, opt-in)
+### Verify-by-Test Triage (Phase 4 Step 3.7, opt-in)
 
 A triage verdict is a judgment call; a failing repro test is proof. When `prefs.global.verifyByTest.enabled` is on, one verifier agent (default Sonnet) writes a minimal repro test per accepted blocking finding (cap: `maxFindings`=3) and runs only that test. Fails as predicted -> finding confirmed, the repro test becomes the Phase 3 rework RED test. Passes under `evidence-gate.mjs` -> finding downgraded to `deferred`. Compile error / timeout -> `inconclusive`, judgment stands. Timeout-bounded, never blocks. Full spec: `refs/features/verify-by-test.md`.
 
-### Immutable-Test Rule + `test_lines_removed` Signal (v10.8.0)
+### Immutable-Test Rule + `test_lines_removed` Signal
 
 Existing tests are immutable during a task: deleting, renaming, or weakening an assertion to reach green is a violation (`refs/rules.md`, Phase 3 GREEN step). A test changes only when the task changes the spec it encodes, named in the commit body. Deterministic backstop: `diff-risk-score.mjs` emits `test_lines_removed` (w=3.0) for any test-classified file whose diff removes more lines than it adds.
 
-### Structured Handoff Blocks (v10.8.0)
+### Update Check at Run Start
+
+Phase 0 Step 0.6, opt-out via `prefs.global.updateCheck`. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against `dist-tags.latest`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+
+### Structured Handoff Blocks
 
 Every phase transition appends a `## Handoff` block (Done / Remaining / Decisions / Open findings / Next) to `agent-log.md` - orchestrator-written from existing state, no LLM call. `/multi-agent:resume` and post-`/compact` re-grounding read the latest handoff first, so long runs re-enter from durable artifacts instead of conversation memory (fresh-context discipline from Anthropic's long-running-agent harness guidance).
 
@@ -174,7 +178,7 @@ If changes include UI files, reviewers check for:
 
 Pure code analysis — no simulator needed. Device-level audits run in Phase 5 when requested.
 
-### Status Enforcement (v1.5.0)
+### Status Enforcement
 
 Phase 3 marks issue-tracker status update as MANDATORY with a post-mutation verify step that re-reads the field and retries once on silent `VALIDATION` failures (e.g. stale Projects V2 option IDs after a board rebuild).
 
@@ -187,49 +191,49 @@ Phase 3 marks issue-tracker status update as MANDATORY with a post-mutation veri
 
 ## Testing & Quality
 
-### Schema-Validated State (v2.0.0)
+### Schema-Validated State
 
 All critical state files are schema-validated at read and write time:
 
 - `agent-state.schema.json` — validates `$HOME/.claude/logs/multi-agent/.../agent-state.json`
-- `prefs.schema.json` — validates `$HOME/.claude/multi-agent-preferences.json` (extended v2.5.0)
-- `triage-output.schema.json` — validates triage output (v2.3.0, hardened v2.6.1, `if`/`then` constraint v3.0.0)
+- `prefs.schema.json` — validates `$HOME/.claude/multi-agent-preferences.json`
+- `triage-output.schema.json` — validates triage output (contradiction `if`/`then` constraint built in)
 
-### Smoke Test Suites (v2.0.0–v2.5.0)
+### Smoke Test Suites
 
 10 suites: add-detail (14 body-preservation assertions), review-triage (validator exit codes), prefs (schema round-trip), state (agent-state lifecycle), metrics (telemetry emission), sync (instruction parity), secret-scan (hook patterns), phase-banner (terminal UI), token-budget (per-phase limits), phase-tracker (progress tracking).
 
-### Adversarial Eval Fixtures (v2.5.0–v2.6.0)
+### Adversarial Eval Fixtures
 
 10 fixtures that test triage resilience against adversarial reviewer output: over-rejection, hallucinated findings, contradictions, invalid JSON, schema violations, duplicate findings, scope creep, empty results, timeout simulation, and combined edge cases.
 
-### Sync Parity Check (v2.3.0)
+### Sync Parity Check
 
 Detects drift between Claude Code instructions (`~/.claude/commands/multi-agent.md`), Copilot CLI instructions (`~/.copilot/copilot-instructions.md`), and the repo's pipeline spec files. Reports discrepancies during Phase 0 Init.
 
-### Token Budget Enforcement (v3.0.0)
+### Token Budget Enforcement
 
 Per-phase token budgets prevent runaway sessions. If a phase exceeds its budget, the pipeline pauses and offers: continue (extend budget), skip phase, or abort. Budgets are configurable in `prefs.global.tokenBudgets`.
 
 ## Telemetry & Observability
 
-- **Pipeline Metrics** (v2.3.0): Structured metrics to `metrics.jsonl` via `log-metric.sh`. Aggregated by `aggregate-metrics.mjs`.
-- **Cost Telemetry** (v2.5.0): Per-phase token cost tracking (`tokens_in`, `tokens_out`, `model`, `duration_ms`). Omitted fields handled gracefully.
-- **Phase Tracker** (v2.4.0): Cross-CLI visual progress (current phase, elapsed time, iteration count).
-- **Phase Banner** (v2.4.0): Terminal UI for phase transitions with Unicode box-drawing characters.
-- **Per-task Cost Breakdown in agent-log.md** (v8.3.0): Phase 7 appends a 4-column block (Phase · Model · Tokens in/out · Est. USD) to every run's `agent-log.md`. Sourced from `phase-tracker.sh tokens` accumulators × `cost-table.json` prices. Independent of the channels-side `reportContent.costSummary` toggle. The `LOG_METRIC_FORWARD_TO_TRACKER=1` env flag mirrors `tokens_in`/`tokens_out`/`model` from `log-metric.sh` into the tracker so JSONL metrics and the cost block stay in sync from one call site.
+- **Pipeline Metrics**: Structured metrics to `metrics.jsonl` via `log-metric.sh`. Aggregated by `aggregate-metrics.mjs`.
+- **Cost Telemetry**: Per-phase token cost tracking (`tokens_in`, `tokens_out`, `model`, `duration_ms`). Omitted fields handled gracefully.
+- **Phase Tracker**: Cross-CLI visual progress (current phase, elapsed time, iteration count).
+- **Phase Banner**: Terminal UI for phase transitions with Unicode box-drawing characters.
+- **Per-task Cost Breakdown in agent-log.md**: Phase 7 appends a 4-column block (Phase · Model · Tokens in/out · Est. USD) to every run's `agent-log.md`. Sourced from `phase-tracker.sh tokens` accumulators × `cost-table.json` prices. Independent of the channels-side `reportContent.costSummary` toggle. The `LOG_METRIC_FORWARD_TO_TRACKER=1` env flag mirrors `tokens_in`/`tokens_out`/`model` from `log-metric.sh` into the tracker so JSONL metrics and the cost block stay in sync from one call site.
 
-### Diff Risk Scoring (v8.3.0)
+### Diff Risk Scoring
 
 `pipeline/scripts/diff-risk-score.mjs` runs at Phase 4 Step 1.75 — before reviewer dispatch. Heuristic, deterministic, sub-second, no LLM. Top-N risk-ranked files inject into each reviewer's prompt as a `${PRIORITY_FILES}` block; reviewers read those files first but still review the entire diff.
 
-Signals + weights: `security_path` ×3, `migration` ×4, `public_api` ×2, `no_test_change` ×2.5, `test_lines_removed` ×3 (v10.8.0: test file shrinks - immutable-test backstop), `complexity_delta` ×1.5, `ui_critical` ×1.5, `loc_changed` ×1. Toggle via `prefs.global.diffRiskAdvisory` (default ON).
+Signals + weights: `security_path` ×3, `migration` ×4, `public_api` ×2, `no_test_change` ×2.5, `test_lines_removed` ×3 (test file shrinks - immutable-test backstop), `complexity_delta` ×1.5, `ui_critical` ×1.5, `loc_changed` ×1. Toggle via `prefs.global.diffRiskAdvisory` (default ON).
 
-### Test Gap Detection (v8.3.0)
+### Test Gap Detection
 
 `pipeline/scripts/test-gap-scan.mjs` runs at Phase 5 Step 0. Walks the diff for newly added public symbols and reports those with no paired test. Stack-specific rules ship for iOS, Android, Python, Node.js. iOS Views and Android `@Composable` symbols default to `important`; other public API additions to `suggestion`. Optional gating via `prefs.testGap.blockingThreshold` — when set, the report becomes a Phase 4 rework finding once `important + blocking` count exceeds the threshold.
 
-### Triage Memory (v8.3.0)
+### Triage Memory
 
 Per-repo append-only JSONL corpus at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl`. Phase 7 ingests every triage output (idempotent), Phase 1 enriches the analysis with similar past tasks, Phase 4 triage attaches prior-art hits to each raw finding with an explicit bias hedge. Token-overlap recall, zero deps, Node-18-compatible. `/multi-agent:search "<text>" --semantic` routes the query to the corpus instead of agent-log grep. Toggle via `prefs.global.priorArtEnrichment.enabled` (default ON).
 
@@ -280,10 +284,10 @@ Token registry maps logical names (`jira`, `bitbucket`, `github`, `confluence`)
 
 ## Schemas & Validation
 
-- `pipeline/schemas/agent-state.schema.json` — validates agent state lifecycle (v2.0.0)
-- `pipeline/schemas/prefs.schema.json` — validates preferences (v2.0.0, extended v2.5.0)
-- `pipeline/schemas/triage-output.schema.json` — validates triage output (v2.3.0, hardened v2.6.1, `if`/`then` constraint v3.0.0)
+- `pipeline/schemas/agent-state.schema.json` — validates agent state lifecycle
+- `pipeline/schemas/prefs.schema.json` — validates preferences
+- `pipeline/schemas/triage-output.schema.json` — validates triage output (contradiction `if`/`then` constraint built in)
 
-## File Layout (v1.9.0)
+## File Layout
 
 `commands/multi-agent/{add-detail,setup,help}.md` → slash commands. `commands/multi-agent/refs/**` → guides, phase specs, rules (`refs:` prefix signals "not an action"). Modifier flags and ops stay inline in `multi-agent.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "10.8.0",
+  "version": "10.12.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/channels.md

@@ -34,7 +34,7 @@ Target resolution is identical to the pre-existing enrich flow  -  any of the 6
 
 ## Flow
 
-`resolve target → fetch context → menu (or flags) → generator → humanizer → dispatch → summary`. Channels: Jira comment, Confluence page, Wiki pages, PR description, Board status (GitHub Projects v2).
+`resolve target → fetch context → menu (or flags) → generator → humanizer → approval → dispatch → summary`. Channels: Jira comment, Confluence page, Wiki pages, PR description, Board status (GitHub Projects v2).
 
 ### Step 1  -  Target resolution
 
@@ -49,7 +49,7 @@ Target resolution is identical to the pre-existing enrich flow  -  any of the 6
 
 **Multi-repo:** when `agent-state.json` `projects[].length > 1`, Step 1 builds **one target per project**. Each project's PR is resolved via `pr` field in its projects[] entry; if missing, the Jira/Issue link query returns multiple PRs (one per repo)  -  all are added to `targets[]`. The project at `projects[0]` (or whose name matches `state.project`) is marked `isPrimary: true`; others are `isPrimary: false`.
 
-For single-repo tasks, `targets` has exactly one entry. The rest of the flow is target-aware: Step 5 generates one body, Step 6 dispatches to each target, with cross-links (see below).
+For single-repo tasks, `targets` has exactly one entry. The rest of the flow is target-aware: Step 5 generates one body, Step 7 dispatches to each target, with cross-links (see below).
 
 ### Step 2  -  Context source detection
 
@@ -298,9 +298,44 @@ Generated by `pipeline/scripts/render-cost-summary.sh <task-id>` using prices fr
 
 **Target length rule:** full body fits one screen on a typical laptop (< 80 lines). Auto-diff summary capped at 5 lines per section. No framework-theory paragraphs, no numbered "why this approach" lists.
 
-### Step 6  -  Channel dispatch
+### Step 6  -  Body preview + approval gate (interactive modes)
 
-For each selected **channel**, call the corresponding adapter. Adapters run **in parallel**  -  one failure does not block others.
+Plan-mode-style gate: the user sees exactly what will be posted BEFORE any external write. Runs after the generator + humanizer, before Step 7 dispatch, in every interactive invocation  -  menu mode AND `--channels`/`--content` flag mode alike (flags pick the targets, they do not waive the content approval).
+
+Skipped in exactly two cases:
+
+| Case | Why |
+|---|---|
+| Autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`) | Explicit consent for side-effect creation  -  posts directly with prefs/flag selections, zero interaction |
+| `--dry-run` | Already prints without posting; a question would be redundant |
+
+**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval):
+
+```
+── PR description  ({repoName} #{prNumber}, replace) ─────────
+{body}
+── Jira comment  ({jiraId}) ──────────────────────────────────
+{body}
+── Confluence page  ("{title}" under {parentUrl}) ────────────
+{body}
+```
+
+Secondary artifacts ride along as one-line intents at the bottom of the preview: Wiki page list, wiki → Jira triad comment (when Wiki is selected and the triad is active per `refs/issue-jira-triad.md`), Board status move (`{from} → {to}`), GitHub issue comment + Progress-flag sync (Phase 7 Step 1.5  -  same gate, see `refs/phases/phase-7-report.md`).
+
+**Then a single AskUserQuestion** (`question`/`description` in `outputLanguage`; `label`/`header` English):
+
+| Option | Behavior |
+|---|---|
+| `Approve & post` | Step 7 dispatches every previewed body verbatim |
+| `Edit` | Free-text "which channel, what should change" → apply → re-render the FULL preview → re-ask (loop, no cap) |
+| `Skip channels` | multiSelect which channels to drop this run → re-render remaining → re-ask |
+| `Cancel` | Abort dispatch entirely  -  nothing posted anywhere. Internal capture (agent-log, knowledge) is unaffected |
+
+**Hard rule:** what is posted is byte-identical to the approved preview (markup conversion excepted). Any body regeneration after approval invalidates the approval and re-runs the gate. Persisting channel prefs (Step 8) still happens on `Cancel`  -  selection memory and content approval are independent.
+
+### Step 7  -  Channel dispatch
+
+For each selected **channel**, call the corresponding adapter. Adapters run **in parallel**  -  one failure does not block others. Dispatch NEVER starts before the Step 6 gate resolves (`Approve & post`), except in the two documented skip cases (autopilot, `--dry-run`).
 
 **Multi-repo dispatch:** When `state.projects[].length > 1`, the dispatcher delegates per-channel rendering to `~/.claude/lib/channels-multi-repo.sh`:
 
@@ -358,7 +393,7 @@ Full contract: [`refs/channels/confluence.md`](refs/channels/confluence.md)  -
 
 Full contract: [`refs/channels/wiki.md`](refs/channels/wiki.md)  -  all four `figma-config.wiki.mode` adapters (submodule / in-repo / github-wiki / separate-repo), full Case A scope menu, screenshot quadrant gate.
 
-### Step 7  -  Summary
+### Step 8  -  Summary
 
 After all adapters complete (or fail non-blocking):
 
@@ -397,6 +432,7 @@ Persist selections to `prefs.global.reportChannels` + `prefs.global.reportConten
 - **No markers**  -  channels does a full replace each run; no `<!-- channels:start -->` bookmarks.
 - **Every body item references a symbol/file/line** from diff or pipeline log. No generic "tested the feature" sentences.
 - **Adapter failures are non-blocking**  -  one channel failing does not abort others. Final summary shows per-adapter status.
+- **Approval before post**  -  interactive runs never write to an external channel without the Step 6 preview + approval. Autopilot and `--dry-run` are the only bypasses.
 
 ## Error handling
 
@@ -423,7 +459,7 @@ Phase 7 invokes this command internally instead of running its own inline Jira/C
 
 Phase 7 passes a runtime state bundle: `{jiraId, prUrl, remoteType, taskType, figmaConfig, agentState, pipelineLogPath}`. `channels` reads these directly, skips target-resolution Step 1.
 
-**Autopilot contract:** Phase 7 ALWAYS pauses at the channels menu (breaks generic autopilot zero-interaction). 30-min timeout → session ends cleanly, task resumable via `/multi-agent:resume`. See `refs/phases/modes.md` for full contract.
+**Autopilot contract:** Phase 7 ALWAYS pauses at the channels menu (breaks generic autopilot zero-interaction). 30-min timeout → session ends cleanly, task resumable via `/multi-agent:resume`. See `refs/phases/modes.md` for full contract. The Step 6 body preview + approval gate follows the same split: interactive runs approve the composed bodies before dispatch; autopilot posts directly after the menu resolves.
 
 ## Cross-CLI parity
 

package/pipeline/commands/multi-agent/finish.md

@@ -65,25 +65,34 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `finish` treats
 
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory.** Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md). `finish` registers only its active phase set  -  `0:Init 4:Review 5:Build+Test 6:Commit 7:Report` (phases 1-3 are not part of the finish set; do not register tiles for them).
+**The phase tracker is required.** Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md). `finish` registers its active phase set  -  `0:Init 4:Review 5:Build+Test 6:Commit 7:Report`  -  but NEVER resets a tracker that an earlier run already built (load-or-continue; contract section "Continuation runs"):
 
 ```bash
-# Phase 0, first shell call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+# Phase 0, first shell call (every CLI). init ONLY when no prior state exists -
+# a task handed off from Phase 5 ("awaiting local test") keeps its full
+# phase 0-3 history (elapsed, tokens, USD).
+STATE="$HOME/.claude/logs/multi-agent/${TASK_ID}/tracker-state.json"
+if [ ! -f "$STATE" ]; then
+  bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+fi
 for p in "0:Init" "4:Review" "5:Build+Test" "6:Commit" "7:Report"; do
-  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"   # idempotent: existing phases keep their history
 done
 bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 
 # Every phase boundary (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
+**Continuation path (prior state existed):** (1) if Phase 5 was left `in_progress` with `Now: awaiting local test (user)`, mark it `update 5 completed` + `meta 5 Result "local test done (user)"` before finish's own work (finish re-opens it with `update 5 in_progress` when its Build+Test gate runs; elapsed keeps the original `started_at`, which is expected); (2) print ONE line in `outputLanguage` summarizing the inherited history, e.g. `Continuing PROJ-12345: phases 0-3 finished earlier (12m, 38.4k tok, ~$0.74)` (USD via `phase-tracker.sh cost total`); (3) `render`.
+
 ### Visual channel  -  Claude Code (native TaskList widget, required)
 
-Register one tile per phase in **strict creation order** (`0 → 4 → 5 → 6 → 7`) BEFORE any TaskUpdate, capture each `taskId`, persist via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, then flip status with `TaskUpdate` at each boundary. Out-of-order TaskCreate scrambles the tile stack. Full contract: `refs/tracker-contract.md` "TaskCreate ordering (strict)".
+Fresh state: register one tile per phase in strict phase-number order (`0 → 4 → 5 → 6 → 7`) BEFORE any TaskUpdate, capture each `taskId`, persist via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, then flip status with `TaskUpdate` at each boundary. Out-of-order TaskCreate scrambles the tile stack. Full contract: `refs/tracker-contract.md` "TaskCreate ordering (strict)".
+
+Continuation: rebuild the FULL TaskList from the state file (completed 0-3 tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta  -  same as the contract's "Resume behaviour".
 
 ### Visual channel  -  Copilot CLI / plain shell