@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/multi-agent-refs/unattended-contract.md

@@ -5,6 +5,7 @@
 - [The three effects](#the-three-effects)
 - [What it does NOT do](#what-it-does-not-do)
 - [Who honours it](#who-honours-it)
+- [Runner-side operations](#runner-side-operations)
 - [The model side already has a contract](#the-model-side-already-has-a-contract)
 - [Default behaviour is unchanged, and a gate says so](#default-behaviour-is-unchanged-and-a-gate-says-so)
 - [The permission posture](#the-permission-posture)
@@ -20,8 +21,7 @@ both directions on a server. A run under `screen`, `tmux`, `ssh -t` or a login
 shell HAS a terminal and still has nobody in front of it, so the test says
 "ask" and the process waits for an answer that will never come - printing
 nothing, exiting never, and looking exactly like slow work. That is the failure
-this contract exists to remove, and it is not hypothetical: two setup scripts
-shipped that way.
+this contract exists to remove.
 
 The variable is opt-in and defaults to absent. Nothing in this file describes
 behaviour that changes on a machine that does not set it.
@@ -65,14 +65,50 @@ in the user's worktree and the checkout is not there.
 | `scripts/github-ssh-setup.sh` | TTY: three questions. No TTY: refuses, naming `SSH_SETUP_EMAIL` | Refuses the same way even with a terminal |
 | `scripts/keychain-save.sh` | TTY: menu + secret prompt. No TTY: refuses, naming `--stdin` / `--json` | Refuses the same way even with a terminal |
 | `scripts/phase-banner.sh` | Colour when stdout is a TTY and `TERM != dumb` | Plain text |
+| `lib/unattended.mjs`, `lib/unattended.sh` | `isUnattended` false; `gatesActive` follows `state.autopilot` | Both true |
+| `scripts/phase0-exit-gate.mjs` | Autopilot-only sources accepted when `state.autopilot` is true, as before | Accepted |
+| `scripts/symbol-existence-gate.mjs`, `scripts/open-questions-gate.mjs` | Run only in autopilot mode; otherwise not-applicable, exit 0, nothing written | Run; a missing symbol fails, an open question parks the run |
+| `scripts/research-gate.mjs` | Runs only in autopilot mode; otherwise not-applicable, exit 0, nothing written (`--evaluate` and `--recheck` only report) | Runs; records `state.research`, re-opens the parked step or parks the run on the gaps left |
+| `scripts/spec-consistency-gate.mjs`, `scripts/analysis-story-tree.mjs` | Outside autopilot mode the consistency report is advisory: stdout only, exit unchanged, nothing written | Run; a gap fails and is recorded (the story tree refuses with exit 4) |
+| `scripts/plan-critique-gate.mjs` | Outside autopilot mode no critic is dispatched; the gate, if run, reports on stdout only, exit 0 (a usage error exits 3), nothing written | Runs after the one critique round; an unresolved binding-rule objection or a broken round fails, is recorded and parks the run |
+| `scripts/review-decision-gate.mjs` | Outside autopilot mode the decisions are advisory: stdout only, exit 0 (a usage error exits 2), triage and state untouched; `--rebuttal-allowed` exits 0 | Runs; a blocker without two reviewers or a failing test is lowered to important and recorded, a rebuttal round fails, `--rebuttal-allowed` exits 1 |
+| `scripts/verify-citations.mjs`, `scripts/plan-coverage-gate.mjs` | Pre-existing check and Section 14 fallback only in autopilot mode | Both run |
+| `scripts/gate-ledger.mjs` and the ledger writes of `evidence-gate.mjs`, `test-summary.mjs`, `test-strength.mjs` | Written only in autopilot mode | Each verdict appended to `state.gates[]` |
+| `scripts/pre-commit-check.sh` | Secret scan | Secret scan, then a `git commit` needs a passing gate ledger for HEAD |
+| `scripts/agent-guard.sh`, `scripts/agent-guard.py` | Attribution and force-push rules; fail-open on an input it cannot judge | Also `scripts/unattended_policy.py`, fail-closed: a command is judged only when it reduces to simple commands joined by `;`, `&&`, `||` and plain pipes between non-interpreter commands - a subshell, group, nested or command-position substitution, unquoted heredoc, background job, shell keyword, interpreter pipe, shell `-c`, inline interpreter program, program file the run wrote or modified, or runtime-built name is refused. On the parseable commands: no push, PR, issue or tracker write, no Keychain read, no fetch outside the allowlist (curl/wget/WebFetch/web_*), no package install or manifest edit, no write into a protected path |
+| `scripts/pr-request.mjs` | Not called | Phase 4 writes `pr-request.json` through it instead of pushing |
+| The continuous-mode runner | Not run | Sets the variable on every child it launches, and refuses to launch (`blocked-guard-missing`) unless `agent-guard.sh` is registered in the user or managed settings on the `Bash`, `Edit|Write|NotebookEdit` and `WebFetch|mcp__multi-agent-toolkit__.*` PreToolUse matchers with the installer's exact command, and unless the permission profile file exists; passes that file with `--settings` |
+| `scripts/autopilot-publish.mjs` | Not called | Runner-side: verifies the request, re-runs the stack's build and tests itself, pushes from a clean staging repository and opens the draft PR, with the variable removed from every process it starts |
+| `scripts/scaffold-gate.mjs` | The skeleton or story check runs and prints its verdict; the verdict reaches the gate ledger only in autopilot mode | The check runs, and the verdict is recorded as `scaffold/skeleton` or `scaffold/story` through `gate-ledger.mjs` |
+| `scripts/launch-request.mjs` | `register-repo` adds a checkout to the launch repositories | `register-repo` refuses with exit 3 |
+| `scripts/phone-devices.mjs` | `add`, `list`, `revoke`, `launch on\|off` change or print the phone device registry | `list` only; `add`, `revoke` and `launch` refuse with exit 3, and the guard blocks them by name (`features/phone-api.md`) |
 
 Anything not in this table does not read the variable. That is deliberate: a
-list of four that is true beats a claim of coverage that is not.
+list that is true beats a claim of coverage that is not. The verification gates,
+and the split between "gates active" and "unattended", are described in
+`features/unattended-gates.md`; the security side (the guard, the PR request, the
+profile, the machine setup) in `features/unattended-security.md`.
+
+## Runner-side operations
+
+These run in the runner process, never in a child, so none of them reads the
+variable or is visible to a session. They are listed here because they are part
+of what unattended mode does on a machine. Detail:
+`features/autopilot-operations.md`.
+
+| Operation | What the runner does | Default |
+|---|---|---|
+| Sleep lock | Holds `caffeinate -s -w <runner pid>` (AC only) from the launch to the end of the tick, and kills the pid it spawned on every exit path | On |
+| Awake agent | A separate launchd agent, `com.multi-agent.autopilot-awake`, runs `/usr/bin/caffeinate -s -i` (plus `-d` with `awake.display`) from `autopilot-on` to `autopilot-off`, so ticks keep firing between runs | On (`awake.enabled`); display may sleep |
+| Credential probe | `autopilot-arming.mjs probe` at `autopilot-on`, `check --probe` on every tick for the item's source: `gh auth status`, `credential-store.sh probe <key>`. A missing, unmapped or locked credential refuses; no value is read into the runner | On |
+| Parallel cap | `maxParallelAgents` caps the supervised run plus parked runs busy again | Unlimited: today's one-at-a-time claim, unchanged |
+| Cleanup report | `gc-abandoned.sh --only` over worktrees the runner created, minus any whose item is parked, once per local day, to `gc-report-<date>.json` / `.md` | Dry run; `gc.autoDelete` adds `--yes` |
+| Daily digest | Items, outcomes, PRs, parked items and cost for the day, sent through `reportChannels` after the outbound gate | Off (`digest.enabled`) |
 
 ## The model side already has a contract
 
 The prompt-level question - what an agent does when it would call
-`AskUserQuestion` and no one can answer - is `refs/picker-contract.md`, section
+`AskUserQuestion` and no one can answer - is `multi-agent-refs/picker-contract.md`, section
 "Autopilot / non-interactive contract", and it predates this file. It resolves
 from the remembered choice first, then the documented default, and records
 which rule fired so the run stays readable afterwards.
@@ -103,10 +139,20 @@ outside it is indistinguishable from a queue with nothing to do.
 `install --unattended` writes the profile that closes it:
 
 ```bash
-npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # show it
-npx @mmerterden/multi-agent-pipeline install --unattended             # write it
+npx @mmerterden/multi-agent-pipeline install --unattended --dry-run          # show it
+npx @mmerterden/multi-agent-pipeline install --unattended                    # write it
+npx @mmerterden/multi-agent-pipeline install --unattended-sandbox            # and the sandbox block
 ```
 
+The profile is `schemas/unattended-profile.json`, written to
+`~/.claude/multi-agent-unattended.settings.json` and passed to each run with
+`claude --settings`; `~/.claude/settings.json` is not changed. It holds `permissions.defaultMode:
+"dontAsk"` (a call that would prompt is denied, not left waiting), a narrow
+allow list, deny rules (merge, push, `~/.ssh`, `~/.aws`, `~/.gnupg`,
+`~/Library/Keychains`, the toolkit's `research_*` tools, the installed pipeline,
+CI workflows), and the toolkit's `MCP_TOOLKIT_URL_POLICY=strict` and
+`MCP_TOOLKIT_INDEX_DENY`. The sandbox block is opt-in on top.
+
 Three properties, each one a promise to somebody who did not ask for this:
 
 1. A DEFAULT install writes no permissions at all. Widening a permission set is
@@ -114,16 +160,22 @@ Three properties, each one a promise to somebody who did not ask for this:
 2. The profile is printed in full, with a reason per line, BEFORE anything is
    written. "The installer changed my permissions" must never be a thing
    discovered afterwards.
-3. It is additive and idempotent. An entry a person added by hand survives, a
-   narrower rule is kept alongside, unrelated settings are untouched, and a
-   second run changes nothing. A `settings.json` that does not parse is refused
-   rather than overwritten.
-
-The entries are broad, and that breadth is what unattended operation costs
-rather than an oversight: a run builds and tests whatever the target repo uses,
-so an allowlist narrow enough to be interesting is one the first unfamiliar repo
-stops at. `doctor --profile=server` reports `unattended-permissions` against the
-same rule the writer applies, so the two cannot disagree.
+3. It is additive and idempotent over its own file, and leaves the attended
+   posture alone. An entry is "already there" only when that exact rule is
+   present, so a narrower rule is kept alongside and never stands in for the
+   profile's entry. A `defaultMode` or env value already in the file is kept. A
+   whole-`Bash` allow in `settings.json` still reaches the run, because
+   permission lists merge; it is reported, never removed. A profile an earlier
+   install wrote into `settings.json` is moved out, printed first. A second run
+   changes nothing, and a profile file that does not parse is refused rather
+   than overwritten.
+
+The permission list is the second line, not the boundary. `Bash(node *)` lets a
+script do anything node can, and a Bash deny rule does not stop `sh -c`. The
+guard hook is the enforcement the run cannot switch off, and a separate macOS
+user is the boundary: `features/unattended-security.md`. `doctor
+--profile=server` reports `unattended-permissions` against the same file the
+writer applies, so the two cannot disagree.
 
 `smoke-unattended-install-profile.sh` asserts all of it, including that a plain
 install still writes nothing.

package/pipeline/rules/figma-pipeline.md

@@ -76,7 +76,7 @@ The 3-tier fallback chain above governs Figma access in `/multi-agent:analysis`
 |---|---|---|---|---|
 | Analysis Phase 1 | `/multi-agent:analysis` Phase 1 fetch | yes | yes (Tier 2 fallback) | Single source of design ground truth |
 | Plan (Phase 1) | `/multi-agent`, `/multi-agent:autopilot` | no | no | Plan reads analysis doc Section 14 + Section 6 |
-| Dev (Phase 2) | every mode that runs Phase 2 (8 modes total) | no | no | Reads analysis doc + Code Connect mapping |
+| Dev (Phase 2) | `/multi-agent`, `/multi-agent:autopilot` | no | no | Reads analysis doc + Code Connect mapping |
 | Review (Phase 3) | `/multi-agent:review`, every full-pipeline mode | no | no | Reviewer cites analysis doc Section 21 References |
 | Test (inside Phase 3) | `/multi-agent:test`, `/multi-agent:manual-test`, every full mode | no | no | Variant list comes from analysis Section 13.6 + 15.2 |
 | Commit (Phase 4) | every mode | no | no | PR body links to analysis doc URL, no design fetch |
@@ -96,7 +96,7 @@ Re-fetching Figma in dev phases:
 
 ### Verification
 
-The pipeline ships a smoke gate `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh` that reads `state.telemetry.mcpCalls[]`. If any entry has `phase >= 2`, the gate fails. It is a maintainer-side regression check: it runs locally as part of `npm test` and the pre-push hook, not in CI (the CI workflow is dormant) and not after every pipeline run.
+The repo carries `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh`, which reads a state file's `state.telemetry.mcpCalls[]`: a Figma tool entry with `phase >= 2` fails it, and a Figma entry with no phase is rejected as unjudgeable. It is a maintainer-side regression check: it runs locally as part of `npm test` and the pre-push hook, not in CI (the CI workflow is dormant) and not after every pipeline run.
 
 Memory: [[mcp-only-in-analysis]]
 
@@ -153,9 +153,9 @@ extension ButtonView {
 
 ### Mandatory Token Rules
 
-- No magic numbers: `padding: 16` -> `.Spacing.spacing16`
+- No magic numbers: `padding: 16` -> `.Spacing.n16`
 - No raw hex colors: `Color(hex: "#E31837")` -> `Color.Primary.primary`
-- No raw `.font()` -> `.typographyStyle(.body1)`
+- No raw `.font()` -> `.typographyStyle(.Body.Regular.lg)`
 - Token hierarchy: Spacing > Size > Radius > BorderWidth > Color > Typography
 
 ### Pre-Commit Checklist
@@ -168,16 +168,16 @@ extension ButtonView {
 - [ ] Preview shows all meaningful variants
 - [ ] FIGMA.md contains variant matrix
 
-### SubPhase Integration (multi-agent Phase 3)
+### SubPhase Integration (multi-agent Phase 2)
 
 When Figma pipeline is active (`figmaConfigPath` set in project preferences),
-multi-agent Phase 3 (DEV) dispatches Figma sub-phases instead of standard TDD:
+multi-agent Phase 2 (Dev) dispatches Figma sub-phases instead of standard TDD:
 
 ```
-Phase 3.0: figma-validate                          → registry, Code Connect, token compliance (halts Phase 3 on failure)
-Phase 3.1: create-component / create-screen        → full implementation by the enabled stack plugin (evolve-component for an existing one)
-Phase 3.2: figma-commit                            → 14-item review + commit + PR
-Phase 3.3: figma-iteration-commit                  → Batch iteration commit (if iterating)
+Phase 2.0: figma-validate                          → registry, Code Connect, token compliance (halts Phase 2 on failure)
+Phase 2.1: create-component / create-screen        → full implementation by the enabled stack plugin (evolve-component for an existing one)
+Phase 2.2: figma-commit                            → 14-item review + commit + PR
+Phase 2.3: figma-iteration-commit                  → Batch iteration commit (if iterating)
 ```
 
 Skill names are the enabled stack plugin's (`ai-ios-toolkit:*` / `ai-android-toolkit:*`); the dispatch contract is `multi-agent-refs/component-dispatch.md`.
@@ -201,7 +201,7 @@ Provider interfaces are defined inline in the plugin skill sets  -  see the `ai-
 | Registry CLI | `registry.enabled` | Manual component name/path input |
 | Projects V2 Board | `board.enabled` | No board column updates |
 | Wiki | `wiki.enabled` | Phase 5 wiki skipped |
-| Confluence | `confluence.enabled` | Phase 7a confluence skipped |
+| Confluence | `confluence.enabled` | Phase 5 Confluence skipped |
 | Figma MCP | `figma.mcpEnabled` | REST API fallback |
 
 ### 14-Item Review Checklist
@@ -227,7 +227,7 @@ The old 31-command personal catalog is retired; none of those `/figma-*` command
 
 | Surface | What it carries | When to use |
 |---------|-----------------|-------------|
-| `ai-ios-toolkit` / `ai-android-toolkit` (marketplace stack plugins, enabled per repo by `/multi-agent:stack`; skill names below are the iOS plugin's, the Android plugin carries the Compose equivalents) | Component skills: `create-component`, `create-screen`, `evolve-component`, `figma-validate`, `figma-review`, `figma-commit`, `figma-iteration-commit`, `figma-component-start`, `figma-utility`, `figma-setup`, `code-connect`, `component-docs`, `component-wiki`, plus the `navigation` / `overlays` / `bottom-sheets` / `ui-patterns` reference skills | Direct component work in a repo where the stack plugin is enabled; Phase 3 dispatches here for `taskType === component` |
+| `ai-ios-toolkit` / `ai-android-toolkit` (marketplace stack plugins, enabled per repo by `/multi-agent:stack`; skill names below are the iOS plugin's, the Android plugin carries the Compose equivalents) | Component skills: `create-component`, `create-screen`, `evolve-component`, `figma-validate`, `figma-review`, `figma-commit`, `figma-iteration-commit`, `figma-component-start`, `figma-utility`, `figma-setup`, `code-connect`, `component-docs`, `component-wiki`, plus the `navigation` / `overlays` / `bottom-sheets` / `ui-patterns` reference skills | Direct component work in a repo where the stack plugin is enabled; Phase 2 dispatches here for `taskType === component` |
 | Pipeline commands | `/multi-agent:analysis` (the only phase allowed to fetch Figma), `/multi-agent:design-check` (mock-mode vs Figma conformance, Phase 4 Step 2.8), `/multi-agent:review` (cites the analysis doc, never Figma) | Inside multi-agent pipeline runs |
 | Legacy `/figma-to-swiftui` (single standalone command) | The old full 8-phase flow | Kept for the old flow only; prefer the plugin's `create-component` for new work |