@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/multi-agent-refs/features/research.md

@@ -0,0 +1,150 @@
+# Feature: Research Before Asking
+
+<!-- toc -->
+- [When it runs](#when-it-runs)
+- [The runner flow](#the-runner-flow)
+- [Round ceiling](#round-ceiling)
+- [Re-entry after proceed](#re-entry-after-proceed)
+- [Asking](#asking)
+- [Tracker context in the descriptor](#tracker-context-in-the-descriptor)
+- [State](#state)
+- [Limits](#limits)
+- [Reference](#reference)
+<!-- /toc -->
+
+**Pattern**: an unattended run that stops on a maturity blocker or on an open
+analysis question waits for a person, and the person often answers with
+something that was already in the ticket thread, a linked page or the code.
+Research reads those first. The research session gathers and proposes;
+`research-gate.mjs` checks every cited source and closes only what is backed; the
+run's own check - the maturity score, the open-questions gate - re-runs on the
+result and decides. The engine is `research/engine.md`.
+
+## When it runs
+
+| Run | What happens |
+|---|---|
+| Attended, not autopilot | Nothing automatic. `/multi-agent:research <id>` is a command a person runs; it asks one gap at a time. `research-gate.mjs` in gate mode is a no-op (`smoke-gates-interactive-noop.sh`) |
+| Gates active (`MULTI_AGENT_UNATTENDED=1` or `state.autopilot`) | `research-gate.mjs` records its verdict and parks or re-opens the run |
+| The autopilot runner | A parked run is routed to research before it is left awaiting an answer (below) |
+
+The split is `lib/unattended.mjs` `gatesActive`, as for every other quality
+gate (`features/unattended-gates.md`).
+
+## The runner flow
+
+The continuous-mode runner, step 5c, while the item is still claimed:
+
+1. The dev run (`/multi-agent <id> autopilot`) ends parked. `researchRoute`
+   routes two parks: `waitingFor: "maturity"` (or a Phase 0 halt that still
+   carries blockers), and `waitingFor: "question"` with
+   `pendingQuestion.stepId: "phase-1/open-questions"`. The channels menu, a
+   user test and a failed verification are a person's call and are never
+   researched.
+2. A research session: `/multi-agent:research <id> --autonomous --state <path>`,
+   launched with `--disallowedTools` naming `research_ask`, `research_search`
+   and `WebSearch` (`RESEARCH_DENIED_TOOLS`). It writes
+   `<state dir>/research/{context.json,research.json,research.md}`.
+3. The runner, not the session, runs `research-gate.mjs --state <path> --json`
+   with the unattended environment.
+4. `decision: "proceed"`: the runner launches `/multi-agent:resume <taskId>
+   autopilot` and supervises it. If that run parks again on the other kind of
+   gap, the loop goes round once more while the ceiling allows.
+5. Anything else - `ask`, no verdict, a launch that failed, a session that did
+   not end - leaves the run's state as it is. A parked state is recorded as
+   `awaiting-answer`, exactly as it would have been without research.
+
+The attempt row carries `researchRounds: <n>` for the rounds this tick used.
+
+Each research and resume launch is prepared like the first one: the runner
+checks that `agent-guard.sh` is registered on all three PreToolUse matchers (missing:
+no session is launched and the run stays parked), clears any file left under
+the new session's name in `pr-requests/`, and passes the unattended environment
+(`features/unattended-security.md`, "The runner's launch"). A resumed run that
+reaches the Phase 4 hand-off is published by the runner exactly like a first
+run: the request is looked up under the resumed session's id.
+
+## Round ceiling
+
+`maxAskRounds` in `~/.claude/autopilot/config.json` (default 2) caps research
+rounds per item. The count is summed from `researchRounds` on every
+`attempted.jsonl` row of that item - the whole log, not the recent tail the
+breaker reads - and not from the run state, because a later run of the same
+item is a fresh state file and would start at zero. At the ceiling
+the runner logs `maxAskRounds` and parks the run without researching it.
+
+## Re-entry after proceed
+
+| Kind | What the gate wrote | Where resume re-enters |
+|---|---|---|
+| `maturity` | `state.maturity` re-scored, `state.research.decision: proceed`, `waitingFor: "maturity"` | the maturity step. It re-fetches the item and runs `research-gate.mjs --state "$STATE_FILE" --recheck --descriptor <fresh.json> --json`: the recorded verified findings are applied to the fresh descriptor and re-scored. Exit 0: continue, with the printed `description` as the working description. Exit 1: the normal blocker path (`features/maturity-followup.md`) |
+| `open-questions` | closed rows removed from `analysis.openQuestions[]`, the `open-questions` gate re-recorded as pass, `waitingFor` and `pendingQuestion` cleared, `status: in_progress` | Phase 2, as `currentPhase + 1`: the gate is the last step of Phase 1, so the plan is already made and research's `pass` is the gate's latest entry. The answers are in `state.research.resolved[]` and research.md |
+
+Recheck re-verifies on fresh data: a comment deleted since the research no
+longer backs its gap.
+
+## Asking
+
+`decision: "ask"` parks the run with `waitingFor: "question"`:
+
+| Kind | `pendingQuestion` | Options |
+|---|---|---|
+| `maturity` | `id: maturity`, `stepId: phase-0/maturity`, the blockers still reported, then the unverified candidates | `fix`, `continue`, `abort` (`schemas/run-questions.json` `maturity`) |
+| `open-questions` | `id: open-questions`, `stepId: phase-1/open-questions`, only the rows still open, then the candidates | `ask-now`, `assume`, `abort`, as `open-questions-gate.mjs` |
+
+The candidates are shown so the person answering starts from what research
+found. They were not verified, or they are acceptance criteria or business rules,
+which research never decides.
+
+## Tracker context in the descriptor
+
+`lib/issue-fetcher.sh` carries `comments[]` (Jira comments or GitHub issue
+comments, the newest 20, at most 1500 characters each and 12000 bytes together),
+`commentsTotal`, `links[]` (Jira issue links) and `untrustedFields`, all on the
+request that fetches the item. None of it feeds the maturity score.
+`issue-fetcher.sh --rescore` re-scores a descriptor on stdin with the same
+formula; it is how the gate re-runs the check.
+
+## State
+
+```jsonc
+"research": {
+  "round": 1,
+  "kind": "maturity",               // or "open-questions"
+  "decision": "proceed",            // or "ask"
+  "reason": "...",
+  "dir": ".../research", "json": ".../research.json",
+  "context": ".../context.json", "md": ".../research.md",
+  "gaps": [{ "id": "description_empty", "category": "description",
+             "status": "closed", "sources": [{ "label": "evidence", "ref": "...", "quote": "..." }] }],
+  "closed": ["description_empty"], "candidates": [], "open": [], "ignored": [],
+  "resolved": [],                   // open-questions: answered rows with their sources
+  "maturityBefore": { }, "maturityAfter": { },
+  "at": "<ISO time>"
+}
+```
+
+Written by `research-gate.mjs` only, and declared in `agent-state.schema.json`.
+
+## Limits
+
+- A fetched document in `context.json` `documents[]` is written by the research
+  session. The gate proves the quote is in the text it was given, not that the
+  text came from the fetcher. The item, its comments and its links come from
+  the descriptor the fetcher printed.
+- The research session's own token cost is not priced into the attempt's `usd`:
+  the run's tracker records phases, and research is not one.
+- In an attended or terminal-autopilot run the gate is invoked by the agent,
+  and is advisory against an agent that skips it, as every in-run gate is. The
+  runner's own invocation is what holds.
+
+## Reference
+
+Scripts: `research-gate.mjs`, the continuous-mode runner (`researchRoute`,
+`researchRoundsUsed`, `researchArgv`, `resumeArgv`; its own reference is
+`features/autopilot-circuit-breaker.md`), `lib/issue-fetcher.sh`.
+Schemas: `research-output.schema.json`, `agent-state.schema.json` `research`,
+`prefs.schema.json` `projects.<slug>.research.providers`,
+`autopilot-config.schema.json` `maxAskRounds`. Tests:
+`test/research-gate.test.mjs`, `test/issue-fetcher-context.test.mjs`,
+the runner's tests; smoke `smoke-gates-interactive-noop.sh`.

package/pipeline/multi-agent-refs/features/review-decision.md

@@ -0,0 +1,185 @@
+# Feature: Review decision rule (autopilot)
+
+<!-- toc -->
+- [The rule](#the-rule)
+- [The same finding](#the-same-finding)
+- [Reviewers stay blind to each other](#reviewers-stay-blind-to-each-other)
+- [Wiring](#wiring)
+- [Verify-by-test in autopilot](#verify-by-test-in-autopilot)
+- [Mandatory at commit](#mandatory-at-commit)
+- [Limits](#limits)
+- [Reference](#reference)
+<!-- /toc -->
+
+**Pattern**: every reviewer on Claude Code is a Claude model. A panel that
+shares a model family shares its blind spots, so one reviewer's `blocking`
+finding is a judgement nobody independent has checked, and a panel that
+agrees can be agreeing for the same wrong reason. An attended run has a person
+at the Step 4 checkpoint to weigh that. An autopilot run has none, so while the
+quality gates are active (`lib/unattended.mjs`, `gatesActive`:
+`MULTI_AGENT_UNATTENDED=1` or `state.autopilot === true`) a blocker has to be
+backed by something other than one model's say-so before it stops the run.
+The lack of model diversity is compensated by asking for executable evidence,
+not by adding more reviewers of the same family.
+
+Attended review is unchanged: the gate prints its decisions marked advisory,
+exits 0 and writes neither the triage file nor the state.
+
+## The rule
+
+An `accepted[]` finding of severity `blocking` keeps its severity only when
+one of these holds:
+
+| Basis | What has to be true |
+|---|---|
+| `corroborated` | at least two independent reviewer outputs of the iteration carry a `blocking` finding that is the same finding |
+| `failing-test` | its `verification` (Step 3.7, `verify-by-test.md`) is `confirmed`, and `evidencePath` names a non-empty log inside the checkout that shows a failing test and no pass |
+| `test-integrity` | it is the finding `test-integrity-gate.mjs` produced for that file: a command's output, not a model's |
+
+Anything else is lowered to `important`. It stays in `accepted[]`: triage
+judged it real and in scope, so the rework still fixes it, it just no longer
+holds the run on one opinion. It is never dropped. Each one is listed in the
+gate's report and in its ledger entry with its fingerprint and the reason
+(`raised by 1 reviewer, two needed; no failing test recorded`). `approved` is
+recomputed from what is left.
+
+Findings of severity `important` and `suggestion` are not touched.
+
+## The same finding
+
+Two findings are the same finding when they name the same file, with diff
+prefixes (`a/`, `b/`, `./`) stripped, and either:
+
+- they have the same fingerprint (`_fingerprint.mjs`, the identity the review
+  delta already uses: the file plus the cited `ruleId`, else the file plus the
+  normalised issue text), or
+- both cite a line above 0 and the lines are at most `LINE_WINDOW` (3) apart.
+
+A whole-file finding (line 0) matches by fingerprint only. Two findings that
+cite different `ruleId`s, or different CWEs in their `security` envelope, are
+never the same finding, however close their lines. The reviewer schema has no
+category field; `ruleId` and the CWE are the categories it does carry.
+
+Independent means a separate reviewer dispatch: one entry of
+`state.reviewIterations[i].reviewers[]`, or one `--source` file (the Step 2.7
+security audit is a separate dispatch too). One reviewer reporting the same
+thing twice is one source. A second reviewer that saw the same line but called
+it a suggestion does not corroborate a blocker.
+
+## Reviewers stay blind to each other
+
+Step 2 dispatches the reviewers in parallel from the same shared prefix; no
+reviewer prompt carries another reviewer's output, and the outputs are
+consumed by Step 3 only. The one same-round exchange is Step 2.5, the rebuttal
+round, which shows each reviewer the others' blocker findings and replaces its
+output. Multi-round debate converges agents on each other, which is exactly
+what corroboration must not measure, so with the gates active the round does
+not run:
+
+```bash
+node "$HOME/.claude/scripts/review-decision-gate.mjs" --rebuttal-allowed --state "$STATE_FILE" \
+  || echo "Step 2.5 skipped: the quality gates are active"
+```
+
+Exit 1 means skip it, whatever `prefs.global.reviewDisagreementRound` says.
+The gate also holds it after the fact: a reviewer entry with `roundCount`
+above 1 fails the decision (exit 1, `rebuttal-round` in the ledger) and the
+triage file is left as it was. `test/review-decision-gate.test.mjs` asserts
+the dispatch side against `phase-3-review.md` and the persona.
+
+The previous-round block (Step 2.1, iteration 2 and later) is shared context,
+not a peer's output: every reviewer sees the same prior triage. A finding that
+two reviewers both carry over from it is still two dispatches agreeing, and it
+already passed this rule in the round before.
+
+## Wiring
+
+After Step 3.7 (verify-by-test) in every round, and after the Step 3.1 empty
+result, before Step 3.8:
+
+```bash
+node "$HOME/.claude/scripts/review-decision-gate.mjs" "$TRIAGE_FILE" --state "$STATE_FILE" \
+  --integrity "$WORKTREE/.pipeline/test-integrity.json" \
+  --source "$WORKTREE/.pipeline/security-audit-$ITERATION.json" \
+  --json > "$WORKTREE/.pipeline/review-decision-$ITERATION.json"
+RD_RC=$?
+cp "$TRIAGE_FILE" "$WORKTREE/triage-output.json"
+```
+
+`test-integrity.json` is the file Step 1.76 writes (`{}` when it found
+nothing); `security-audit-$ITERATION.json` is the file Step 2.7 writes when the
+audit runs (`security-audit.md`). Both are files and not process substitutions
+of a shell variable with a `{}` brace default: bash 3.2, the stock macOS
+`/bin/bash`, expands that to `{\}`, and unparseable input is exit 3.
+A missing or empty `--integrity` file means no test-integrity findings, and a
+missing or empty `--source` means the audit did not run.
+
+Merge the JSON into `state.reviewIterations[-1].reviewDecision` through
+`write-state.mjs`:
+
+```bash
+jq --slurpfile d "$WORKTREE/.pipeline/review-decision-$ITERATION.json" \
+  '{reviewIterations: (.reviewIterations | .[-1].reviewDecision = $d[0])}' "$STATE_FILE" \
+  | node "$HOME/.claude/scripts/write-state.mjs" "$STATE_FILE"
+```
+
+| Exit | Ledger | The run |
+|---|---|---|
+| 0 | `pass` | continues with the rewritten triage |
+| 1 | `fail`: a rebuttal round ran | `gate-ledger.mjs park --outcome verification-failed --gate review-decision` |
+| 2 | nothing | usage error; fix the call |
+| 3 | `fail`: triage unreadable, or an accepted blocker with no reviewer record to check it against | parks the same way |
+
+The gate records the verdict; it does not park. Parking is the explicit call:
+
+```bash
+[ "$RD_RC" = 1 ] || [ "$RD_RC" = 3 ] && node "$HOME/.claude/scripts/gate-ledger.mjs" park \
+  --outcome verification-failed --gate review-decision --reason "review-decision exit $RD_RC" --state "$STATE_FILE"
+```
+
+A missing reviewer record is a failure and not a pass: with nothing to count,
+every blocker would be lowered, and a run that forgot to persist its
+reviewers would get a clean review for it. An empty `reviewers: []` is a
+missing record, for the same reason.
+
+## Verify-by-test in autopilot
+
+A single-reviewer blocker survives only with a failing verify-by-test log, so
+an autopilot run with `prefs.global.verifyByTest.enabled` false keeps only
+corroborated and test-integrity blockers. That is the intended trade: without
+the empirical step there is nothing but a second opinion to lean on. Turn
+verify-by-test on for autopilot work where one reviewer catching a real bug
+matters more than the extra single-test runs.
+
+## Mandatory at commit
+
+`review-decision` is in `MANDATORY_AT_COMMIT` (`gate-ledger.mjs`). Every mode
+in `phases.json` carries Review (`smoke-review-in-every-mode.sh`), and the gate
+runs on the Step 3.1 empty result too, where it records `pass`: a run with no
+blocker, or with no finding at all, still gets an entry for HEAD, so the
+requirement blocks no clean commit. It is the only check that refuses a
+rebuttal round, and a check the commit hook does not ask for is one an agent
+can skip. Its sha is HEAD, as for `verify-citations`, which runs on the same
+triage output.
+
+## Limits
+
+- All reviewers on Claude Code are Claude-family. Requiring two of them is
+  weaker than two vendors agreeing; the failing-test basis is what carries the
+  weight, and the rule says so rather than counting same-family agreement as
+  independent proof.
+- The line window is a heuristic. Two reviewers describing different bugs
+  three lines apart in the same file count as one finding; two describing the
+  same bug from opposite ends of a long function do not.
+- The evidence check reads the log, it does not re-run the test. A log that
+  shows a failure for a different reason than the finding claims still counts;
+  verify-by-test writes one minimal repro per finding, which is what keeps that
+  case narrow.
+
+## Reference
+
+Script: `scripts/review-decision-gate.mjs`. Tests:
+`test/review-decision-gate.test.mjs`; smoke
+`smoke-gates-interactive-noop.sh`. Related: `verify-by-test.md`,
+`review-delta.md`, `unattended-gates.md`, `phases/phase-3-review.md` Steps
+2.5, 3.1, 3.6 and 3.7.

package/pipeline/multi-agent-refs/features/scaffold.md

@@ -0,0 +1,160 @@
+# Feature: Scaffold contract and the between-stories check
+
+<!-- toc -->
+- [The command](#the-command)
+- [What a scaffold skill must do](#what-a-scaffold-skill-must-do)
+- [The skeleton check](#the-skeleton-check)
+- [Between stories: build, smoke, demo](#between-stories-build-smoke-demo)
+- [Remote repository](#remote-repository)
+- [Ledger](#ledger)
+- [Limits](#limits)
+- [Reference](#reference)
+<!-- /toc -->
+
+**Pattern**: a new project is only a good starting point if it is already green
+by the same commands every later change is judged by. The pipeline does not
+write project code here. It calls the enabled toolkit's `<toolkit>:scaffold`
+skill, which owns the stack's layout and conventions, and then verifies the
+result with the stack adapter's build, test and lint commands and the evidence
+tooling the rest of the pipeline uses. After that, every story ends with the
+app still building, passing, linting and running its demo; a story that
+leaves it otherwise stops the next one from starting.
+
+## The command
+
+`/multi-agent:scaffold <ios|android|web|backend> <name> [--dir <path>]`
+(`commands/multi-agent/scaffold/SKILL.md`, frontmatter contract fields per
+`_command-contract.mjs`: one required enum, one required text, one path flag;
+`gui: form`, not destructive).
+
+| Step | What happens | Who |
+|---|---|---|
+| Resolve | `ai-<stack>-toolkit:scaffold` (`web` → `ai-frontend-toolkit`). Not available: stop, the plugin is not enabled (`/multi-agent:stack`). | pipeline |
+| Dispatch | the Skill tool with the name and the target directory | pipeline |
+| Create | the skeleton, `.scaffold.json`, a `.gitignore` covering `.pipeline/`, `git init` | toolkit skill |
+| Verify | `scaffold-gate.mjs --dir <dir> --phase skeleton` | pipeline |
+| Commit | `chore: scaffold <name>`, only after the gate exits 0 | pipeline |
+| Remote | a separate question after the commit, run only on an explicit yes | person |
+
+Dispatch follows the plugin-skill contract in `component-dispatch.md`: the
+skill is resolved by name through the Skill tool, a missing skill is a halt
+with the plugin to enable, never a fallback to hand-written files, and the
+skill neither reads nor writes `agent-state.json`. The pipeline's side is
+classification, dispatch and verification.
+
+## What a scaffold skill must do
+
+Each toolkit's `scaffold` skill (the `multi-agent-plugins` marketplace, authored
+in the plugin repo: `build-stack-plugins.mjs` regenerates only the `knowledge/`
+layer) states in its own SKILL.md what it creates, the build, test and lint
+commands that must pass, and that it never creates a remote. The pipeline holds
+it to this:
+
+- Writes into an empty or new directory only.
+- Includes at least one real test, so the test count is not zero.
+- Writes `.scaffold.json` (`schemas/scaffold-manifest.schema.json`):
+
+  ```json
+  { "version": "1.0.0", "toolkit": "ai-ios-toolkit", "name": "SampleApp",
+    "stack": "ios", "vars": { "scheme": "SampleApp-Package", "simulator": "iPhone 17 Pro" },
+    "demo": { "command": "swift run SampleAppDemo", "expect": "SampleApp ready, modules: [0-9]+" } }
+  ```
+
+  `stack` is an adapter id in `schemas/stack-adapters.json`; `vars` fills that
+  adapter's `{slot}`s. The gate sets `worktreePath` to the skeleton and a new
+  `resultBundle` per run itself, because xcodebuild will not overwrite one; a
+  `vars` entry of either name is ignored. `demo` is a command that terminates on its own and a
+  pattern its output must match. A `remote` key is refused.
+- Runs `git init`, makes no commit, adds no remote, pushes nothing.
+
+## The skeleton check
+
+`scaffold-gate.mjs --phase skeleton` passes when all of these hold:
+
+| Check | Pass |
+|---|---|
+| `manifest` | `.scaffold.json` is valid and names an applicable adapter |
+| `no-remote` | `git remote` lists nothing |
+| `first-commit` | the repository has no commit yet: the proof comes before it |
+| `build` | the adapter's build command exits 0 and `evidence-gate.mjs --claim build --stack` accepts the log |
+| `test` | the adapter's test command exits 0 and `evidence-gate.mjs --claim test --stack` accepts the log, counts included (`test-summary.mjs`): zero tests executed fails. Gradle prints no counts on success, so for an adapter that reads JUnit XML the `test-results` directories are summed as well |
+| `lint` | the adapter's lint command exits 0 |
+| `demo` | when the manifest declares one: exit 0 and the output matches `expect` |
+
+Commands come from the adapter (`_stack-adapter.mjs commandFor`), never from
+the skill: `ios` builds and tests through `xcodebuild` on the package scheme
+and lints with `swift format lint`, `android` through Gradle (`assembleDebug`,
+`testDebugUnitTest`, `lintDebug`), `web` and `backend-node` through the
+package's `build`, `test` and `lint` scripts with the repo's own package
+manager. Every log is kept under `<dir>/.pipeline/scaffold/`. Exit 0 pass, 1 a
+check failed, 2 usage, 3 manifest missing or invalid.
+
+A failed check goes back to the scaffold skill once with the failing checks and
+their logs; a second failure leaves the skeleton uncommitted and reports it.
+The pipeline does not edit the skeleton to make a check pass.
+
+## Between stories: build, smoke, demo
+
+A story is not done because its code exists; the app has to still work and be
+shown working. For a repository with `.scaffold.json` at its root, Phase 2 runs
+the story check at entry and at exit:
+
+```bash
+node "$HOME/.claude/scripts/scaffold-gate.mjs" --dir "$WORKTREE" --phase story --story "$ITEM_ID"
+```
+
+The same build, test and lint checks as the skeleton, plus `demo`, which is
+required here (a manifest without one is exit 3), and without the
+`first-commit` check.
+
+| Exit | At entry | At exit |
+|---|---|---|
+| 0 | the story starts | the story is done |
+| 1 | the previous story left the app broken or not demoable: this one does not start, the run halts with the failing checks | a Phase 2 gate failure, like a red build |
+| 2 | a call error: fix the arguments; never read as a pass | the same |
+| 3 | `.scaffold.json` missing, unreadable, invalid or without `demo`: the run halts, nothing is built on a manifest the gate cannot read | the same |
+
+The idea of checking that the app builds, passes a smoke and can be
+demonstrated after every story, before the next begins, comes from GPT-Pilot.
+Only the idea is taken; this is a separate implementation built on the
+pipeline's own adapter and evidence tooling.
+
+## Remote repository
+
+Creating the hosted repository is an outward write and is never part of the
+scaffold. `/multi-agent:scaffold` asks once, after the first commit, and runs
+`gh repo create` only on an explicit yes to the exact command shown. With
+`MULTI_AGENT_UNATTENDED=1` the question is never asked, and agent-guard's
+unattended policy refuses the write anyway: `gh repo create`, a mutating
+`gh api` call (for example `-X POST user/repos`) and `git push` are all
+blocked (`scripts/unattended_policy.py`, `GH_WRITES`; asserted in
+`test/scaffold-gate.test.mjs`).
+
+## Ledger
+
+With the quality gates active (`lib/unattended.mjs`, `gatesActive`) the verdict
+is recorded as `scaffold/skeleton` or `scaffold/story` through
+`gate-ledger.mjs`, next to the `evidence-gate/build` and `evidence-gate/test`
+entries evidence-gate.mjs writes for the same logs. Neither scaffold entry is
+mandatory at commit: a repository that was not scaffolded has nothing for them
+to check. A skeleton has no HEAD before its first commit, so its entries carry
+no sha, and an unattended first commit is refused by the commit hook's ledger
+check. Scaffolding is a flow with a person at it, or a terminal autopilot run.
+
+## Limits
+
+- The demo is a command and a pattern. It shows the app starts and reaches a
+  known state; it does not judge whether the story's behaviour is right, which
+  is what the tests and the review are for.
+- The iOS check needs Xcode and the simulator named in `vars`; a machine
+  without them fails the build or test check rather than skipping it.
+- A lint command the stack does not declare (`go`, `rust`, `python`, `jvm`
+  today) fails the `lint` check; those stacks have no scaffold skill.
+
+## Reference
+
+Scripts: `scaffold-gate.mjs`, `_stack-adapter.mjs` (`lint` command kind),
+`evidence-gate.mjs`, `test-summary.mjs`, `gate-ledger.mjs`. Schema:
+`schemas/scaffold-manifest.schema.json`, `schemas/stack-adapters.json`.
+Command: `commands/multi-agent/scaffold/SKILL.md`. Tests:
+`test/scaffold-gate.test.mjs`, `test/stack-adapter.test.mjs`.

package/pipeline/multi-agent-refs/features/security-audit.md

@@ -10,7 +10,7 @@ Run the audit when any of these holds:
 - The base branch is a release branch.
 - The run is the standalone `/multi-agent:security-review` command, which dispatches straight to this step.
 
-There is no `--audit` flag: the trigger is the diff, not a word the user has to remember. When none of these holds, the audit does not run, `$SECURITY_AUDIT_JSON` stays empty, and the Step 3.0 merge is a no-op.
+There is no `--audit` flag: the trigger is the diff, not a word the user has to remember. When none of these holds, the audit does not run, no `security-audit-$ITERATION.json` is written, and the Step 3.0 merge and the review-decision `--source` are no-ops.
 
 ## Threat model first
 
@@ -46,7 +46,11 @@ Validate with the same gate protocol as a reviewer  -  the exit code decides, no
 printf '%s' "$SECURITY_AUDIT_JSON" | node "$HOME/.claude/scripts/validate-reviewer.mjs" -
 ```
 
-On validator failure: one self-correction rework, then HALT the phase (identical to the reviewer output-contract gate). Persist the object to `state.reviewIterations[<iteration>].securityAudit` and hold it in `$SECURITY_AUDIT_JSON`.
+On validator failure: one self-correction rework, then HALT the phase (identical to the reviewer output-contract gate). Persist the object to `state.reviewIterations[<iteration>].securityAudit` and write it to a file, which Step 3.0 merges and `review-decision-gate.mjs` reads as one independent `--source`:
+
+```bash
+printf '%s' "$SECURITY_AUDIT_JSON" > "$WORKTREE/.pipeline/security-audit-$ITERATION.json"
+```
 
 Because the output is reviewer-shaped, the Step 3.0 merge appends its `findings[]` alongside the test-integrity findings. A `blocking` security finding then reaches triage, and a triage-accepted blocker blocks Phase 4  -  the "critical security items block the commit" contract is wired here, not merely stated.
 

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -36,9 +36,12 @@ The sharper case is a document whose evidence supported few sections: the sole i
 A skill becomes a standards registry by saying so in its own frontmatter:
 
 ```yaml
-standards-registry: references/rules.yml
+metadata:
+  standards-registry: references/rules.yml
 ```
 
+The key sits under `metadata:` because the host skill frontmatter schema has no `standards-registry` field, and the skill linters reject unknown top-level keys in skills that ship to a plugin. A top-level `standards-registry:` line is still read.
+
 `skill-conformance.mjs` reads frontmatter across the installed skills trees and loads what declared itself. Nothing in the pipeline names `ios-coding-standard`, `apple-archive-compliance` or any other skill, so a future UIKit, Objective-C, Kotlin or backend registry drops in with zero pipeline change  -  and a registry that is absent produces a declared coverage gap rather than a silent pass.
 
 **The skills root differs per host**, so discovery is a bounded walk over candidate roots (`<install>/skills`, `<install>/multi-agent-refs/skills` for Codex, `<repo>/pipeline/skills`), installed layouts first. `install/copilot.mjs` copies `scripts/` byte-for-byte with no path rewrite, so a hardcoded `~/.claude/skills` is inert on two of the three hosts. That bug has already shipped here once: dynamic skill loading exited 1 on every real install while passing a smoke that ran from the repo. `skillsRootsSearched` is recorded in the manifest so an empty result is attributable to a root rather than to an absence of registries.

package/pipeline/multi-agent-refs/features/stack-adapters.md

@@ -0,0 +1,116 @@
+# Feature: Stack Adapters and Test Evidence
+
+<!-- toc -->
+- [1. The adapter table](#1-the-adapter-table)
+- [2. `evidence-gate.mjs --stack <id>`](#2-evidence-gatemjs---stack-id)
+- [3. `test-summary.mjs`](#3-test-summarymjs)
+- [4. `test-strength.mjs`](#4-test-strengthmjs)
+- [Reference](#reference)
+<!-- /toc -->
+
+**Pattern**: one set of markers cannot read "the build passed" and "the tests
+passed" for every stack. It does not know Maven's `BUILD SUCCESS` or a silent
+`go build`, and `** TEST SUCCEEDED **`, Gradle's `BUILD SUCCESSFUL` and
+`go test`'s `ok` are all printed for a run that executed zero tests. A pass
+claim needs the stack's own markers and the test count, and a new test needs to
+fail without the change it claims to cover.
+
+## 1. The adapter table
+
+`$HOME/.claude/schemas/stack-adapters.json` (shape:
+`stack-adapters.schema.json`) holds one adapter per stack: `ios`, `android`,
+`web`, `backend-node`, `python`, `go`, `rust`, `jvm`, plus `unknown`. Each carries
+detection rules, build/test command templates, success and failure markers, the
+test-summary parser order, test-file patterns, truth-source globs (localization
+keys, strings.xml, i18n JSON, generated endpoints) and reference patterns with a
+`(?<ref>...)` group for the symbol they name. No company or product names: the
+table describes toolchains, not projects.
+
+`$HOME/.claude/scripts/_stack-adapter.mjs` loads and validates it (no schema
+library; every pattern is compiled at load) and resolves a repo:
+
+- `stack-detect.sh` answers the coarse class (ios / android / web / backend) and
+  keeps the rules that need file content - the Android plugin versus a JVM
+  Gradle build, and which side of a package.json a repo is on.
+- `backend` is refined by the manifest that names the language (`go.mod`,
+  `Cargo.toml`, `pyproject.toml`, `pom.xml`, ...), searched root first and then
+  three levels deep with the same prune set, so a vendored checkout or a build
+  directory never decides the stack.
+- Several adapters may match. `order` picks the primary: a language manifest
+  outranks a package.json, which is often only tooling.
+- Nothing matched is the `unknown` adapter, never an error.
+
+Commands render through `commandFor`: a template slot inside double quotes is
+inserted after refusing any quote-breaking character, a bare slot is
+single-quoted, and a package script resolves through `package-manager.mjs`.
+Tools that print nothing on success carry an `exitMarker` the shell echoes only
+on exit 0.
+
+## 2. `evidence-gate.mjs --stack <id>`
+
+Without `--stack` the gate is unchanged. With it:
+
+| Step | Rule |
+|---|---|
+| markers | the adapter's success/failure lists replace the defaults; a caller `--success-pattern` / `--failure-pattern` still wins |
+| failure | decisive, before anything else |
+| counts (test claim) | `test-summary.mjs` with the adapter's parsers, then `--junit` / `--xcresult` / `--xcresult-json` when the log has none: `executed == 0` fails ("no tests executed"), `failed > 0` fails. A `skipped` marker of the adapter (a test task that did not run) counts as zero when no count was read. Still unread: with the quality gates active the claim fails, since markers alone do not say how many tests ran; attended, the markers decide and the verdict says so |
+| `unknown` | present evidence with no default failure marker is `ok` with `notApplicable: true`; missing or failing evidence still fails |
+| a typo in the id | usage error (exit 2), so a misspelling cannot switch the success markers off |
+
+## 3. `test-summary.mjs`
+
+Reads counts from the runner's own output: xcodebuild (XCTest and Swift Testing
+lines), xcresult (`xcrun xcresulttool` when a bundle is given, or a captured JSON
+summary), JUnit XML (Gradle, Surefire, pytest), Maven, Gradle, pytest, jest,
+vitest, `node --test`, `go test -v` and `-json`, `cargo test`. Output:
+`{executed, passed, failed, skipped, parser, source, status, reason?}`.
+
+- `executed` excludes skipped tests, so a run that skipped everything is a zero run.
+- `status` is `passed | failed | no-tests | unparsed`; exit 0 / 1 / 3 / 4.
+- A runner recognised without counts (Gradle on success, `go test` without `-v`,
+  a build that failed first) is `unparsed` with the reason. Text no parser
+  recognises is `unparsed` too. Never a guess.
+
+## 4. `test-strength.mjs`
+
+For `--base`/`--head`, runs each changed test file in a temporary worktree at
+`head` (it must pass there), then restores every changed production file to
+`base` (files the change added are removed) and runs it again:
+
+| Verdict | Meaning |
+|---|---|
+| `red` | fails on a test without the production change: it covers the change |
+| `still-green` | passes without it: it does not exercise the change |
+| `unjudged` | fails without it by not compiling or loading (the adapter's `loadError` markers; every adapter's when none is named), so it never reached an assertion |
+| `not-run` | fails on head, timed out, executed zero tests, or no production change to revert |
+
+Exit 0 all red, 1 any still-green, 4 anything else, 2 usage. In the gate
+ledger red plus unjudged is a pass and unjudged alone not-applicable.
+
+The limit is the revert itself: production files go back whole and added
+files are removed, so a test that references new code fails to compile or
+load without it whatever it asserts. That red is no evidence, so it is not
+counted as red. On a compiled stack (Swift, Kotlin) this covers every test
+that calls a new symbol; only tests that compile against the base are judged. The worktree lives
+under the system temp directory (never inside the repo), each run is killed as a
+process group at `--timeout-ms`, and the worktree is removed and pruned on exit,
+including on SIGINT/SIGTERM. The caller's checkout is not touched.
+
+`--head worktree` judges the uncommitted working tree: it is snapshotted into a
+commit object through a private index, so the caller's index, HEAD and refs are
+not touched. Phase 2 ends before anything is committed, which is where it runs.
+
+It runs every changed test twice, so it belongs to unattended runs, where
+nobody is watching the clock and a weak test would otherwise pass review
+unnoticed. The unattended Phase 2 exit gate calls it, with `evidence-gate
+--stack` and `test-summary`, and each records its verdict in `state.gates[]`
+(`features/unattended-gates.md`, section 4). An attended run does not invoke it.
+
+## Reference
+
+Tests: `test/stack-adapter.test.mjs`, `test/evidence-gate-stack.test.mjs`,
+`test/test-summary.test.mjs`, `test/test-strength.test.mjs`. Fixtures:
+`test/fixtures/stack-logs/<stack>/` (success, failure, zero-test and mixed logs
+per stack; the xcodebuild, xcresult, pytest and `node --test` ones are captured
+output).