@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/docs/architecture.md

@@ -34,12 +34,12 @@ graph LR
         N0[Init] --> N1[Plan] --> N2[Dev] --> N3[Review] --> N4[Commit] --> N5[Report]
     end
 
-    subgraph Dev ["Short depth (picker, Opus)"]
-        D0[Init] --> D2[Dev<br/>Opus] --> D3[Review] --> D4[Commit] --> D5[Report]
+    subgraph Autopilot ["Autopilot (skip confirmations, quality gates on)"]
+        A0[Init] --> A1[Plan] --> A2[Dev] --> A3[Review] --> A4[Commit] --> A5[Report]
     end
 
-    subgraph Autopilot ["Autopilot (skip confirmations)"]
-        A0[Init] --> A1[Plan] --> A2[Dev] --> A3[Review] --> A4[Commit] --> A5[Report]
+    subgraph Unattended ["Continuous mode (MULTI_AGENT_UNATTENDED=1)"]
+        U0[Init] --> U1[Plan] --> U2[Dev] --> U3[Review] --> U4[Commit<br/>PR request] --> UR[Runner verifies<br/>and opens a draft PR]
     end
 ```
 
@@ -113,16 +113,16 @@ graph TB
     end
 
     subgraph "Pipeline Specs"
-        CMD[commands/<br/>58 command files]
-        AGT[agents/<br/>8 agent personas]
-        RUL[rules/<br/>12 domain rules]
+        CMD[commands/<br/>61 command files]
+        AGT[agents/<br/>10 agent personas]
+        RUL[rules/<br/>13 domain rules]
         PHS[multi-agent-refs/phases/<br/>phase specs + contracts]
         CMP[skills/shared/core/<br/>orchestration skills<br/>incl. compliance]
         EXT["skills/shared/external/<br/>151 curated skills<br/>(authoring source for the<br/>multi-agent-plugins marketplace)"]
     end
 
     subgraph "Quality Gates"
-        SCH[schemas/<br/>19 JSON schemas]
+        SCH[schemas/<br/>JSON schemas + validated data]
         EVL[eval/triage/<br/>11 regression fixtures]
         SMK[scripts/smoke-*<br/>100+ smoke suites]
     end
@@ -159,20 +159,56 @@ User Input → Phase 0 (Init)
             agent-log.md + agent-state.json (final)
 ```
 
+## Unattended Autopilot (continuous mode)
+
+```mermaid
+graph TD
+    TICK["launchd tick<br/>autopilot-runner.mjs"]
+    ARM["Arm: cost ceiling · circuit breaker ·<br/>credential probe · parallel cap"]
+    TAKE["Take the head of the queue<br/>(one run per repo)"]
+    RUN["claude --bg child in a worktree<br/>MULTI_AGENT_UNATTENDED=1 · agent-guard fail-closed"]
+    GATES["Gate ledger: symbol existence · open questions ·<br/>plan critique · spec consistency · evidence ·<br/>test strength · citations · review decision · plan coverage"]
+    PARK{"Parked on maturity<br/>or open questions?"}
+    RESEARCH["/multi-agent:research --autonomous<br/>research-gate.mjs decides"]
+    REQ["Phase 4: commit + pr-request.json<br/>(no push from the session)"]
+    PUB["autopilot-publish.mjs: re-run build + tests,<br/>re-check ledger, secrets, outbound gate"]
+    PR["Push from a clean staging repo<br/>gh pr create --draft"]
+    HUMAN["A person reviews and merges"]
+    VF["verification-failed<br/>(verdict on disk)"]
+
+    TICK --> ARM --> TAKE --> RUN
+    RUN --> PARK
+    PARK -->|yes| RESEARCH
+    RESEARCH -->|proceed| RUN
+    RESEARCH -->|gaps left| WAIT["Parked for a person"]
+    PARK -->|no| GATES --> REQ --> PUB
+    PUB -->|pass| PR --> HUMAN
+    PUB -->|fail| VF
+```
+
+The session can build, test and commit inside its worktree; everything that
+leaves the machine goes through the runner, after the runner checked it again
+outside the session. With the variable unset none of this runs, and an attended
+run behaves as before. Detail:
+[`unattended-contract.md`](../pipeline/multi-agent-refs/unattended-contract.md),
+[`unattended-security.md`](../pipeline/multi-agent-refs/features/unattended-security.md),
+[`unattended-gates.md`](../pipeline/multi-agent-refs/features/unattended-gates.md),
+[`autopilot-operations.md`](../pipeline/multi-agent-refs/features/autopilot-operations.md).
+
 ## Ecosystem Sync Targets
 
-`/multi-agent:sync` actually walks **five** targets, not the three shown in earlier
-revisions of this diagram - Codex CLI and the two independently-shipped repos
-(`multi-agent-plugins`, `multi-agent-toolkit-mcp`) are real sync targets too:
+`/multi-agent:sync` walks **six** targets: Copilot CLI, Codex CLI, the pipeline
+repo and the website, plus the two independently shipped repos
+(`multi-agent-plugins`, `multi-agent-toolkit-mcp`):
 
 ```mermaid
 graph TD
     CC["Claude Code<br/>(source of truth)"]
-    COP["Copilot CLI<br/>(instructions + 56 skills)"]
-    COD["Codex CLI<br/>(1 router skill + 58 refs)"]
+    COP["Copilot CLI<br/>(instructions + 61 sub-command skills)"]
+    COD["Codex CLI<br/>(1 router skill + 61 refs)"]
     REPO["Pipeline Repo<br/>(npm package)"]
     WEB["Website"]
-    PLUGREPO["multi-agent-plugins<br/>(5 stack plugins, own repo)"]
+    PLUGREPO["multi-agent-plugins<br/>(6 plugins, own repo)"]
     DTK["multi-agent-toolkit-mcp<br/>(own repo, own release cadence)"]
 
     CC -->|copy + reformat| COP

package/docs/best-practices.md

@@ -17,7 +17,7 @@ npx @mmerterden/multi-agent-pipeline install --link
 
 **Rule**: When a bug or test failure is discovered during development, fix it immediately before continuing with the current task. Never defer fixes to "later".
 
-Applied in Phase 3 (Development):
+Applied in Phase 2 (Dev):
 
 - If a test fails → fix the failing test before writing new code
 - If lint errors appear → fix them before the next TDD cycle

package/docs/ecosystem.md

@@ -5,9 +5,9 @@ separately, wired together at install time and at run time:
 
 | Repo | What it owns | Ships as |
 |---|---|---|
-| **`multi-agent-pipeline`** (this repo) | Orchestration: the 6-phase flow, the 58 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
-| **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 5 independently-versioned plugins |
-| **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 115 MCP tools across 13 categories (simulator/emulator control, memory, crash diagnostics, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, code intelligence, wallet passes, an agent-DSL batch runner, a full-text context index, provider-backed research, video key frames) | npm package, registered as a standard stdio MCP server on every host |
+| **`multi-agent-pipeline`** (this repo) | Orchestration: the 6-phase flow, the 61 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
+| **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 6 independently-versioned plugins |
+| **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 118 MCP tools across 14 categories (simulator/emulator control, memory, crash diagnostics, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, code intelligence, wallet passes, an agent-DSL batch runner, a full-text context index, provider-backed research, video key frames, offline security scoring) | npm package, registered as a standard stdio MCP server on every host |
 
 None of the three depends on the others at the code level. They compose through two
 narrow contracts: the **Skill tool** (pipeline → plugin, at Phase 2) and the **MCP
@@ -18,7 +18,7 @@ Either can be swapped or removed without touching the other two's source.
 graph LR
     subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
         direction TB
-        PHASES["6 phases · 58 commands"]
+        PHASES["6 phases · 61 commands"]
         GATES["deterministic gates + review triage"]
     end
 
@@ -39,8 +39,8 @@ graph LR
         CRASH["Crash Diagnostics (2)"]
         A11Y["Accessibility Audit (3)"]
         STORE["Store Compliance (5)"]
-        WEB["Web Automation (8)"]
-        DESIGN["Design Audit (6)"]
+        WEB["Web Automation (18)"]
+        DESIGN["Design Audit (7)"]
         CODE["Code Intelligence (8)"]
         PASS["Wallet Passes (4)"]
         AGENTDSL["Agent DSL (2)"]
@@ -57,23 +57,23 @@ graph LR
 
 ---
 
-## 1. Authoring flow: one source of truth, five sync targets
+## 1. Authoring flow: one source of truth, six sync targets
 
 `~/.claude/` on the maintainer's machine is authoritative. Everything else is a
 derived, synced, or independently-shipped artifact. `/multi-agent:sync` is the one
-command that walks all five targets in order, detects which are stale, and updates
+command that walks all six targets in order, detects which are stale, and updates
 only those:
 
 ```mermaid
 graph TD
     CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
 
-    CC -->|"Step 2: copy + reformat<br/>58 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
-    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 58 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 2: copy + reformat<br/>61 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 61 refs<br/>+ 10 agent TOML"]
     CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
     CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
 
-    REPO -->|"Step 3c: build-stack-plugins.mjs<br/>rebuilds knowledge/ from<br/>shared/external"| PLUGREPO["multi-agent-plugins repo<br/>(5 stack plugins)"]
+    REPO -->|"Step 3c: build-stack-plugins.mjs<br/>rebuilds knowledge/ from<br/>shared/external"| PLUGREPO["multi-agent-plugins repo<br/>(6 plugins)"]
 
     DTK2["multi-agent-toolkit-mcp repo<br/>(own codebase, own gates,<br/>NOT generated from Claude)"]
     SYNC3D["Step 3d: detect movement →<br/>gate → commit → publish"]
@@ -89,7 +89,7 @@ graph TD
     style DTK2 fill:#dff,stroke:#333,stroke-dasharray: 5 5
 ```
 
-**Why `multi-agent-toolkit-mcp` is drawn differently.** The other four targets are *derived*
+**Why `multi-agent-toolkit-mcp` is drawn differently.** The other five targets are *derived*
 from the Claude Code source - sync writes their content. `multi-agent-toolkit-mcp` is not:
 it's a separate codebase developed on its own schedule. Sync's Step 3d only
 *detects* whether it moved (dirty tree, unpushed commits, untagged version), runs
@@ -106,18 +106,18 @@ hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
 
 ---
 
-## 2. Plugin marketplace build: one authoring source, five versioned artifacts
+## 2. Plugin marketplace build: one authoring source, six versioned artifacts
 
 ```mermaid
 graph TD
-    EXT["pipeline/skills/shared/external/<br/>153 skills - single authoring source<br/>(the pipeline's own phases read these too)"]
+    EXT["pipeline/skills/shared/external/<br/>154 skills - single authoring source<br/>(the pipeline's own phases read these too)"]
 
-    EXT -->|"cross-stack skills"| COMMONP["ai-common-toolkit<br/>11 skills · v0.2.10"]
-    EXT -->|"outside facts for analysis"| ANAP["ai-analyst-toolkit<br/>5 skills · v0.1.3"]
-    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-toolkit<br/>133 skills · v0.12.1"]
-    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-toolkit<br/>30 skills · v0.1.5"]
-    EXT -->|"backend-only"| BEP["ai-backend-toolkit<br/>33 skills · v0.1.7"]
-    EXT -->|"web/frontend-only"| FEP["ai-frontend-toolkit<br/>25 skills · v0.1.5"]
+    EXT -->|"cross-stack skills"| COMMONP["ai-common-toolkit<br/>12 skills · v0.3.6"]
+    EXT -->|"outside facts for analysis"| ANAP["ai-analyst-toolkit<br/>5 skills · v0.1.8"]
+    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-toolkit<br/>136 skills · v0.16.0"]
+    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-toolkit<br/>36 skills · v0.3.0"]
+    EXT -->|"backend-only"| BEP["ai-backend-toolkit<br/>34 skills · v0.2.3"]
+    EXT -->|"web/frontend-only"| FEP["ai-frontend-toolkit<br/>26 skills · v0.2.2"]
 
     COMMONP --> BUMP{"skill set<br/>changed?"}
     ANAP --> BUMP
@@ -133,12 +133,16 @@ graph TD
     style EXT fill:#ffd,stroke:#333
 ```
 
-A skill counted in more than one platform plugin (a cross-stack knowledge skill
-plus, say, an iOS-specific one) is why the plugins' skill counts sum to more than
-the 153-skill source: `ai-common` skills are vendored into every stack plugin's
-`knowledge/`, not deduplicated across them. Versioning is per-plugin and
-patch-only from this generator - a repo enabling only `ai-ios-toolkit`
-never pulls an Android-only change.
+The plugins' skill counts sum to more than the 154-skill source because each
+plugin also carries its own authored `reference/`, `workflow/` and `tools/`
+skills and an `index` router. A vendored knowledge skill ships in exactly one
+plugin: cross-stack skills go to `ai-common-toolkit` rather than into every
+stack plugin, and the marketplace's `tools/validate.py` fails a skill that
+appears in two. Each vendored skill's `NOTICE-*.md` ships beside it, listing the
+skills it covers, and the builder refuses to write when a NOTICE and the skills'
+`metadata.source` disagree. Versioning is per-plugin and patch-only from this
+generator - a repo enabling only `ai-ios-toolkit` never pulls an Android-only
+change.
 
 **Consumption is pull, not push.** A consumer repo enables a stack plugin once
 (`/multi-agent:stack ios`, writing the enabled-plugins list into
@@ -157,7 +161,7 @@ measurements behind this table):
 
 | | Claude Code | Copilot CLI | Codex CLI |
 |---|---|---|---|
-| **Pipeline commands** | 58 slash-command skills, native | 58 sub-command skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 58 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Pipeline commands** | 61 slash-command skills, native | 61 sub-command skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 61 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
 | **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-toolkit-architecture`) |
 | **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader - the enabled stack plugin's authored skills (incl. `create-component`) are copied flat into `~/.copilot/skills/` at install time (the old frozen `figma-*` copies are pruned, they were never a fallback) | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
 | **multi-agent-toolkit-mcp** | `claude mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `copilot mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `codex mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |
@@ -199,6 +203,11 @@ lifecycle (test → code → build → wiki) and reports back a coarse
 a plugin failure counts against the pipeline's own retry cap (`retryCount === 3` →
 hard stop, per `component-dispatch.md`).
 
+**`/multi-agent:scaffold` → plugin** uses the same seam for a new project: the
+enabled toolkit's `scaffold` skill writes the skeleton and a `.scaffold.json`
+manifest, and the pipeline judges the result with the stack adapter's build,
+test and lint commands before the first commit.
+
 **Phase 3 (and design-check / store-ready) → multi-agent-toolkit** is a long-lived MCP
 session, not a one-shot call: the same stdio server process answers many tool
 calls across a phase (boot simulator once, then screenshot/tap/screenshot/tap...).
@@ -209,16 +218,30 @@ e.g. `apple-archive-compliance` requires `ios_app_store_audit` from
 that drops or renames a tool a pipeline skill depends on is a **major** bump, by
 that step's own contract).
 
+### Unattended runs and the toolkit
+
+An autopilot run nobody watches uses the same MCP contract, narrowed by the
+runner before it launches the session. The child gets
+`MCP_TOOLKIT_URL_POLICY=strict` and `MCP_TOOLKIT_INDEX_DENY` (the runner refuses to launch without the guard
+registered, and `launch.json` carries both). Under `strict` the toolkit's web
+tools refuse loopback, private, link-local and metadata addresses on every
+request the browser makes, and `context_*` will not index or return the denied
+paths. On top of that the pipeline's guard holds `WebFetch` and the `web_*`
+tools to its own network allowlist and refuses `web_eval`; the unattended
+permission profile denies the `research_*` tools.
+
+Detail: [`unattended-security.md`](../pipeline/multi-agent-refs/features/unattended-security.md).
+
 ### multi-agent-toolkit-mcp's tools, by category
 
-115 tools in 13 categories, counted from the server's own `tools/list` response
-at toolkit 3.13.1 rather than from a README. Three families are defined in
+118 tools in 14 categories, counted from the server's own `tools/list` response
+at toolkit 3.14.0 rather than from a README. Three families are defined in
 modules the main file only spreads in, so a count taken from the source reads
 low; the response is the only place the whole surface appears at once.
 
 The families can be narrowed per host: `MCP_TOOLKIT_CAPS` serves only the named
-ones, and unset serves all 115. A frontend repo that sets `web,code,context`
-sees 29 tools instead of 115, which matters because every registered server's
+ones, and unset serves all 118. A frontend repo that sets `web,code,context`
+sees 29 tools instead of 118, which matters because every registered server's
 tool list is charged against the context window on every turn.
 
 | Category | Tools | Primary pipeline consumers |
@@ -229,13 +252,14 @@ tool list is charged against the context window on every turn.
 | Accessibility Audit | 3 (`ios_accessibility_audit`, `android_accessibility_audit`, `ios_accessibility_audit_deep`) | `/multi-agent:test` accessibility scenario, `test-accessibility` |
 | Store Compliance | 5 | `store-ready`, `testflight-validation`, `apple-archive-compliance` skill, Phase 3 Security Auditor |
 | Web Automation | 18 | frontend-stack UI testing (via `test`); snapshot `ref` targeting, console/network capture, readable extraction and a bounded same-origin crawl |
-| Design Audit | 6 | `design-check` (mock-mode vs Figma conformance) |
+| Design Audit | 7 | `design-check` (mock-mode vs Figma conformance, component variants) |
 | Autonomous Agent DSL | 2 (`agent_run_steps`, `agent_query_output`) | any skill that needs a scripted multi-step device flow in one round trip |
 | Code Intelligence | 8 (`code_definition`, `code_references`, `code_hover`, `code_diagnostics`, `code_document_symbols`, `code_workspace_symbols`, `code_index_status`, `code_server_reset`) | `/multi-agent:refactor`, Phase 3 reviewers needing a real symbol graph rather than grep |
 | Wallet Passes | 4 (`pass_build`, `pass_validate`, `pass_inspect`, `pass_certificates`) | pass-kit work outside the pipeline; no pipeline phase consumes them |
 | Context Index | 3 (`context_index`, `context_search`, `context_get`) | any skill holding an offloaded payload too large to read; ranks passages instead of grepping lines |
 | Research | 2 (`research_search`, `research_ask`) | closes the parity exemption that had web search outside the MCP channel |
 | Media | 1 (`media_frames`) | Phase 2 visual evidence: turns a screen recording into frames a reviewer and a model can both look at |
+| Security | 2 (`security_cvss_score`, `security_dep_inventory`) | the Phase 3 Step 2.7 security audit (`security-auditor`) and `/multi-agent:security-review`; offline, no egress |
 
 ---
 

package/docs/facts.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Generated by pipeline/scripts/gen-facts.mjs. Do not hand-edit: the site reads this, and a number edited here instead of at its source is the drift this file removes.",
-  "generatedAt": "2026-09-22",
-  "version": "20.2.1",
+  "generatedAt": "2026-09-25",
+  "version": "20.3.0",
   "phaseSchema": 2,
   "phases": [
     {
@@ -35,18 +35,18 @@
     "autopilot": [0, 1, 2, 3, 4, 5],
     "analysis": [0, 1, 3, 4, 5]
   },
-  "commandCount": 58,
-  "skillCount": 158,
-  "skillCountAll": 219,
-  "agentCount": 9,
+  "commandCount": 61,
+  "skillCount": 154,
+  "skillCountAll": 218,
+  "agentCount": 10,
   "hosts": ["Claude Code", "Codex CLI", "Copilot CLI"],
-  "toolCount": 117,
+  "toolCount": 118,
   "toolCategories": {
     "ios": 40,
     "android": 31,
     "web": 18,
     "code": 8,
-    "design": 6,
+    "design": 7,
     "pass": 4,
     "context": 3,
     "agent": 2,
@@ -54,6 +54,6 @@
     "security": 2,
     "media": 1
   },
-  "pluginSkillCount": 244,
-  "toolkitVersion": "3.14.0"
+  "pluginSkillCount": 245,
+  "toolkitVersion": "3.15.0"
 }

package/docs/features.md

@@ -2,6 +2,21 @@
 
 Comprehensive list of every feature the pipeline ships. The top-level `README.md` only highlights the 5-7 most important; this file is the complete catalog.
 
+## Contents
+
+- [Core Pipeline](#core-pipeline)
+- [PR & Review Flow](#pr--review-flow)
+- [Review Quality](#review-quality)
+- [Autopilot (unattended)](#autopilot-unattended)
+- [Safety & Hygiene](#safety--hygiene)
+- [Testing & Quality](#testing--quality)
+- [Telemetry & Observability](#telemetry--observability)
+- [Learning](#learning)
+- [User-Defined Routines](#user-defined-routines)
+- [Integrations](#integrations)
+- [Schemas & Validation](#schemas--validation)
+- [File Layout](#file-layout)
+
 ## Core Pipeline
 
 ### 6-Phase Orchestration (0-5)
@@ -14,7 +29,8 @@ Phase 2: Dev       TDD cycle: test → code → build (Sonnet), then the Verify
                    gate: build · lint · tests · secrets, run once
 Phase 3: Review    Parallel AI review + Fable triage against Dev's logs, then the
                    optional user test + on-demand device audits
-                   (Claude Code: Fable + Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+                   (Claude Code: Fable + Opus + Sonnet, or Opus + Sonnet with the
+                   fable rung off · Copilot CLI: GPT-5.4 + Opus + Sonnet)
 Phase 4: Commit    Git commit, push, PR with default reviewers + draft/ready prompt
 Phase 5: Report    External: Jira comment · Wiki + Figma screenshots · Confluence
                    Internal: agent-log.md + Quality & Metrics + knowledge + memory
@@ -26,7 +42,7 @@ Each phase reads its own spec file under `pipeline/multi-agent-refs/phases/phase
 
 | Flag        | Effect                                                                              |
 | ----------- | ----------------------------------------------------------------------------------- |
-| `autopilot` | Skip all confirmation prompts; still fails safe on review blockers + build retries. Also resolves the workspace to a worktree without asking. |
+| `autopilot` | Skip all confirmation prompts; still fails safe on review blockers + build retries. Also resolves the workspace to a worktree without asking, and turns on the verification gates described under [Autopilot (unattended)](#autopilot-unattended). |
 
 The workspace is not a flag. **Where the branch lives** is asked at Phase 0 Step 5b - worktree (`.worktrees/{id}/`, your checkout untouched) or local (the project root, which drops the user-test offer because that gate checks the change out of a worktree and there is none). There is no `:local` command and no `--local` switch: an answer given in the run is visible in the run, where a flag is visible only in how the run was typed. Every autopilot entry resolves it to a worktree and never asks, because an unattended run commits and pushes from wherever it stands and doing that in the user's own checkout is what worktrees exist to prevent. `state.workspaceSource` records who decided - `localMode: false` alone is both "the user chose a worktree" and "nothing asked".
 
@@ -38,7 +54,7 @@ The install is not only useful while `/multi-agent` is running. `rules/outside-t
 
 - **Onboarded service credentials.** Resolve the logical name through `credential-store.sh` and read the issue, page or log. Writes route through the pipeline commands, which carry the rules that make them safe - issues are never auto-closed, PR bodies use `Ref:`, outward prose goes through the humanizer.
 - **The stack skills enabled for this repo.** Each toolkit's own `index` skill routes. The pipeline reads the effective `enabledPlugins` rather than keeping a stack table, so a seventh toolkit needs no code change.
-- **The `multi-agent-toolkit` MCP.** 115 tools for a running app.
+- **The `multi-agent-toolkit` MCP.** 118 tools for a running app.
 
 Uninstall preserves the whole layer - tokens, the reader that opens them, the mapping that names them, the MCP registration. It is 1.5 kB of always-loaded text; the detail lives in a ref that loads on demand, and a gate keeps both under a ceiling because every byte there is paid by every session.
 
@@ -78,6 +94,10 @@ Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketpl
 /multi-agent:stack all         # every stack plugin
 ```
 
+### Project Scaffold (`/multi-agent:scaffold <stack> <name>`)
+
+A new project starts green by the same commands every later change is judged by. The command resolves the enabled toolkit's `ai-<stack>-toolkit:scaffold` skill (ios, android, web, backend), dispatches it through the Skill tool, and then only verifies: `scaffold-gate.mjs --phase skeleton` requires a valid `.scaffold.json`, no commit and no remote yet, and the stack adapter's build, test and lint commands to pass, with build and test judged by `evidence-gate.mjs --stack` and a test count. The first commit follows a pass; creating the hosted repository is a separate question asked afterwards, and refused unattended. For a scaffolded repo, Phase 2 runs `--phase story` at entry and exit: build, test, lint and the manifest's demo command must pass, or the next story does not start. Detail: [`scaffold.md`](../pipeline/multi-agent-refs/features/scaffold.md).
+
 ### Package Manager Resolution (Phase 2, node-shaped stacks)
 
 Phase 2's web test arm and its build step used to type `npm`. A repo on pnpm, yarn or bun then failed in Phase 2 - with a worktree and a branch already created - or, worse, npm resolved against a lock file it does not own and the run continued on a tree the repo's own tooling would never have produced.
@@ -141,7 +161,7 @@ When a specialized skill takes over a main pipeline phase, progress is reported
 
 ### Draft vs Ready Prompt
 
-Phase 4 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`.
+Phase 4 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`. An unattended run does not ask: the autopilot runner always opens a draft.
 
 - Bitbucket: `draft: true` flag (DC 8.x+) with `[DRAFT]` title fallback for older servers.
 - GitHub: `gh pr create --draft` + `gh pr ready` for promotion.
@@ -258,12 +278,84 @@ Pure code analysis - no simulator needed. Device-level audits run in Phase 5 whe
 
 Phase 2 treats the issue-tracker status update as a required step 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).
 
+## Autopilot (unattended)
+
+Continuous mode (`/multi-agent:autopilot-on`) runs the pipeline with nobody watching. The runner is a launchd tick: it takes the head of the queue, runs the whole pipeline on it in a worktree with `MULTI_AGENT_UNATTENDED=1` set on the child, and ends at a draft pull request that a person reviews and merges. Every behaviour in this section keys on that variable or on autopilot mode; an attended run is unchanged. Contract, entry point by entry point: [`unattended-contract.md`](../pipeline/multi-agent-refs/unattended-contract.md).
+
+### Research Before Asking
+
+A run that parks on a maturity blocker or on open analysis questions gets a research pass before it waits for a person. `/multi-agent:research <id> --autonomous` reads the tracker thread, issue links, similar closed items, linked documents and the repository; `research-gate.mjs` decides what closed. `inference` alone never closes a gap, `evidence` must be quoted from a fetched source, `repo` must resolve at `file:line` or in a commit, and acceptance criteria and business rules only ever yield candidates. The maturity check or the open-questions gate then re-runs on the result: `proceed` resumes the run, anything else parks it with the gaps left. `maxAskRounds` bounds the rounds per item. Detail: [`research.md`](../pipeline/multi-agent-refs/features/research.md).
+
+### The Runner Publishes
+
+The session commits and stops. Phase 4 writes a PR request through `pr-request.mjs`, and `autopilot-publish.mjs`, in the runner process, decides whether it leaves the machine: the repository comes from the runner's config, the branch must be the one the run recorded and must be unprotected, the stack adapter's build and test commands are re-run in the worktree with token-shaped variables removed, the gate ledger, the secret detectors over the commit range and the outbound gate are re-checked, and the push goes from a fresh bare staging repository that carries none of the worktree's git config. GitHub gets `gh pr create --draft` with the body from a file; Bitbucket gets the branch and a summary (`pushed-awaiting-pr`). Any failed check is `verification-failed`, with the verdict in `pr-requests/<session>.verdict.json`. Post-PR reports (`reportChannels`, `reportIssueUpdates`) run once, after the PR opened, and are off by default.
+
+### Operations Around a Run
+
+| Operation | Default | What it does |
+|---|---|---|
+| Awake agent | on | `com.multi-agent.autopilot-awake` runs `caffeinate -s -i` from `autopilot-on` to `autopilot-off`; `awake.display` adds `-d` |
+| Sleep lock | on | `caffeinate -s -w <runner pid>` from the launch to the end of the tick |
+| Credential probe | on | `autopilot-arming.mjs probe` before the schedule is offered, `check --probe` on every tick; `credential-store.sh probe` answers `readable`, `missing` or `locked` without reading a value |
+| Circuit breaker | on | stops launching after consecutive attempts that produced nothing, and lets one attempt through per cooldown |
+| Cost ceiling | on | `costCeilingUsd` over a rolling 24 hours, each run counted once at its largest recorded spend |
+| Parallel cap | unlimited | `maxParallelAgents` caps runner-launched sessions working at once |
+| Cleanup report | dry run | `gc-report-<date>.json` / `.md` over the worktrees the runner created; `gc.autoDelete` removes |
+| Daily digest | off | items, outcomes, PRs, parked items and cost, through `reportChannels` after the outbound gate |
+
+Detail: [`autopilot-operations.md`](../pipeline/multi-agent-refs/features/autopilot-operations.md), [`autopilot-circuit-breaker.md`](../pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md).
+
+### Security Base
+
+- **Fail-closed guard.** `agent-guard.sh` is the PreToolUse hook on `Bash`, `Edit|Write|NotebookEdit` and `WebFetch|mcp__multi-agent-toolkit__.*`. Under the variable a Bash command is judged only when it reduces to simple commands joined by `;`, `&&`, `||` and plain pipes between non-interpreter commands; a subshell, group, nested substitution, unquoted heredoc, background job, shell keyword, interpreter reading stdin, shell `-c`, inline interpreter program (`node -e`, `perl -e`, `php -r`, ...), program file the run wrote or modified, or runtime-built command name is refused unparsed. On what it parses: no push, PR, issue or tracker write, no Keychain read, no package install or manifest edit, no write into a protected path. The guard arms its own 5-second deadline and answers "block" on expiry when unattended.
+- **Network allowlist.** `curl`, `wget`, `WebFetch` and the toolkit's `web_*` tools reach only hosts in the allowlist (`network.staticHosts` plus the configured service hosts); a URL built at run time, a proxy flag or a request body is refused, and `web_eval` is refused outright. The runner starts the toolkit with `MCP_TOOLKIT_URL_POLICY=strict` and `MCP_TOOLKIT_INDEX_DENY`.
+- **No package installs.** A restore from the committed lockfile is allowed; adding a package is not.
+- **Untrusted data.** Fetched bodies, ticket text, comments and PR text enter prompts inside `<untrusted-data>` delimiters that defuse a forged closing tag.
+- **Permission profile.** `install --unattended` writes a `dontAsk` profile with a narrow allow list and deny rules into `~/.claude/multi-agent-unattended.settings.json`, printed in full before anything is written; the runner passes it with `claude --settings`, so `~/.claude/settings.json` and attended sessions are unchanged. A default install writes no permissions.
+- **Machine setup, applied by the operator.** A separate non-admin macOS user for the runner, per-repo GitHub credentials limited to contents and pull requests, a Jira token that can only read and comment, and GitHub rulesets on every default and release branch (no force-push, no deletion, PR and code-owner review required, the bot in no bypass list).
+
+Detail: [`unattended-security.md`](../pipeline/multi-agent-refs/features/unattended-security.md).
+
+### Verification Gates
+
+While the quality gates are active (`MULTI_AGENT_UNATTENDED=1`, or `state.autopilot` for a terminal autopilot run), each gate appends its verdict to `state.gates[]` through `gate-ledger.mjs`, and under the variable the commit hook refuses a commit unless every mandatory gate passed or was not applicable for HEAD.
+
+| Gate | What it checks |
+|---|---|
+| `symbol-existence` | every localization key and endpoint the added lines reference exists in the repository's truth sources |
+| `open-questions` | open analysis questions are answered, assumed or park the run |
+| `verify-citations` | a triage citation quotes the line it cites (at least 8 non-space characters, or the whole line) |
+| pre-existing claims | a "pre-existing" finding cites a line the diff from the base does not add or change |
+| `plan-coverage` | every plan step is accounted for; a planned run with no todos is a gap |
+| `evidence-gate`, `test-summary` | build and test claims read with the stack's own markers and a positive executed test count |
+| `test-strength` | a new test goes red without the change it claims to cover |
+| `review-decision` | a `blocking` finding carries two independent reviewers or a failing test |
+| `spec-consistency`, `plan-critique` | recorded, not mandatory at commit (see below) |
+
+Stack adapters cover 8 stacks: `ios`, `android`, `web`, `backend-node`, `python`, `go`, `rust`, `jvm`, plus `unknown`. Detail: [`unattended-gates.md`](../pipeline/multi-agent-refs/features/unattended-gates.md), [`stack-adapters.md`](../pipeline/multi-agent-refs/features/stack-adapters.md).
+
+### Constitution and Spec Consistency
+
+`/multi-agent:analysis` writes the project's invariant rules (security, accessibility, architecture, licensing) to `constitution.md` and `constitution.json` under the project's knowledge directory. Each rule cites one labelled source: `repo` (a file and line), `evidence` (a standards document or tracker item) or `inference`, which is always `proposed` and never binding. `spec-consistency-gate.mjs` checks by id, with no model call, that every requirement has a task and a Test Plan row, every task cites a defined requirement, and no row or task waives a binding rule. Attended it prints an advisory report and writes nothing. Detail: [`constitution.md`](../pipeline/multi-agent-refs/features/constitution.md).
+
+### Plan Critic
+
+With the gates active, Phase 1 ends with one adversarial critic (`agents/plan-critic.md`) under four lenses: scope, feasibility, security and a cheaper alternative. Each objection carries evidence anchors; the planner answers each once, accepting and revising or rebutting with evidence, and `plan-critique-gate.mjs` judges with no model call. An objection citing a binding constitution rule blocks unless its reply resolves it with an anchor that holds; the rest is advisory and appears in the plan render and the PR summary. One round, because further rounds move agents toward each other rather than toward the right answer. The critic follows the fable switch. Detail: [`plan-critic.md`](../pipeline/multi-agent-refs/features/plan-critic.md).
+
+### Review Decision Rule
+
+Every reviewer on Claude Code is a Claude model, so with the gates active a `blocking` finding keeps its severity only when two independent reviewer outputs carry the same finding, a confirmed verify-by-test log shows a failing test, or the test-integrity gate produced it. Anything else is lowered to `important` in place, never dropped, with the reason in the report and the ledger. The rebuttal round does not run under the gates. Attended review is unchanged. Detail: [`review-decision.md`](../pipeline/multi-agent-refs/features/review-decision.md).
+
+### Client Contract and Phone API
+
+Commands (`commands.mjs --json`) and run questions (`launch-request.mjs questions`) are declared as data, and every surface is reachable two ways that print the same bytes: the CLI scripts, and `contract-server.mjs`, started with `/multi-agent:serve` on 127.0.0.1 behind a bearer token. `pipeline/contract/` ships the manifest, generated TypeScript types and fixtures ([kit README](../pipeline/contract/README.md)). A launch request's input is a reference, not a prompt: a Jira key, an issue URL, `repo#N` or `#N`, or desktop free text passed as one quoted argument; op and mode words are refused. Four phone routes under `/v1/phone/` (runs, one run, answer, launch) accept only Ed25519-signed requests from devices enrolled with `phone-devices.mjs`, always return the redacted view, and keep launch off until `phone-devices.mjs launch on`. The phone app is a separate project. Detail: [`phone-api.md`](../pipeline/multi-agent-refs/features/phone-api.md).
+
 ## Safety & Hygiene
 
 - **Pre-Commit Secret Detection** (12 patterns): `PreToolUse` hook scans staged files for API keys/tokens, AWS access keys, private keys, `.env` files, service account JSON. Commit **blocked** if found.
 - **Read-Size Gate** (opt-in, `prefs.global.bulkRead.mode`): a `PreToolUse` hook inspects `Read` and the shell commands that read a file whole. In `observe` it only logs what it would have caught - the baseline you measure before routing anything. In `enforce` a file over `minLines` (default 350) is blocked and delegated to a haiku-rung worker (`bulk-read.sh`), which returns a line-numbered summary so the follow-up is a bounded `Read(offset:limit:)` instead of the whole file; the full text is parked under `.multi-agent/refs/`. The development phase and any file the run has already touched are exempt, because Claude Code's `Edit` requires its own `Read` first.
 - **Capture Hooks** (`SessionEnd`, `PreCompact`, `SessionStart`): every durable write used to live in Phase 5, the phase a run is least likely to reach. `SessionEnd` flushes a run that never got there; `PreCompact` flushes before an auto-compaction summarizes a long phase mid-flight, which is the same loss one level down; `SessionStart` prints at most two lines about an unfinished run. None calls a model, none reads a payload, and all exit 0 on every path - a hook that fails a session over bookkeeping is worse than the bookkeeping.
-- **Operational Reporting** (`prefs.global.usageLog`): coarse run metadata - task id, phase, status, durations, token counts - and never prompts, code, diffs or absolute paths. The per-machine token is REQUESTED from the endpoint by `usage-register.mjs` (setup, update, and the Phase 0 exit gate as a backstop), is write-only, and lives in the OS credential store; prefs hold only the entry name and the switch. `usageLog.optOut: true` blocks registration permanently and is checked before the network call. An unreachable endpoint leaves reporting off with one line and exit 0 - a run is never failed over bookkeeping.
+- **Operational Reporting** (`prefs.global.usageLog`): coarse run metadata - task id and type, current phase, run status (in progress, completed, halted, parked), phase durations, whether a PR opened, token counts - sent at every phase transition and at completion, halt and park, and never prompts, code, diffs or absolute paths (task title and PR URL only when `includeTitle` / `includePrUrl` are set). Runs are reported under the logged-in GitHub account that can read the pipeline repository (`usage-identity.mjs`, cached in `usageLog.login`, `--refresh` to re-check); with no such account nothing is sent. The per-machine token is REQUESTED from the endpoint by `usage-register.mjs` (setup, update, and the Phase 0 exit gate as a backstop), is write-only, and lives in the OS credential store; prefs hold only the entry name and the switch. `usageLog.optOut: true` blocks registration permanently and is checked before the network call. The server issues a token only to the repository owner or a collaborator, pins the login to it, and shows only those accounts' records on the panel. An unreachable endpoint leaves reporting off with one line and exit 0 - a run is never failed over bookkeeping.
 - **Build Queue**: All `xcodebuild` calls acquire a lock. Each worktree uses own `-derivedDataPath`. Stale locks auto-clean after 15 min. Non-Xcode builds don't need the lock.
 - **Context Management**: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` - compaction at 65% usage (prevents degradation in 6-phase sessions).
 - **3-Iteration Hard Kill**: Any retry loop stops after 3 attempts, then pauses for user. No infinite loops.

package/docs/recovery-guide.md

@@ -344,20 +344,13 @@ though earlier phases worked.
 Fix:
 
 ```bash
-# 1. Update the keychain entry for the rotated provider. The mapping
-#    keys live in prefs.global.keychainMapping (account+label tuple per provider).
-ACCOUNT=$(jq -r '.global.keychainMapping.<provider>.account' \
-            $HOME/.claude/multi-agent-preferences.json)
-LABEL=$(jq -r '.global.keychainMapping.<provider>.label' \
-            $HOME/.claude/multi-agent-preferences.json)
-
-# macOS:
-security delete-generic-password -s "$LABEL" -a "$ACCOUNT" 2>/dev/null
-security add-generic-password   -s "$LABEL" -a "$ACCOUNT" -w "$NEW_TOKEN"
-
-# Linux:
-secret-tool clear     account "$ACCOUNT" service "$LABEL"
-echo "$NEW_TOKEN" | secret-tool store --label="$LABEL" account "$ACCOUNT" service "$LABEL"
+# 1. Update the credential-store entry for the rotated provider. The item
+#    name lives in prefs.global.keychainMapping.<provider>. Copy the new token,
+#    then stream it over stdin so it never reaches argv.
+KEY=$(jq -r '.global.keychainMapping.<provider>' \
+        $HOME/.claude/multi-agent-preferences.json)
+pbpaste | ~/.claude/lib/credential-store.sh set "$KEY" -
+pbcopy < /dev/null
 
 # 2. Sanity-check the doctor reports the new token's prefix
 bash pipeline/lib/credential-store.sh doctor