@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/scripts/write-state.mjs

@@ -32,6 +32,9 @@
  *   4  -  the lock was taken from us mid-write; nothing was written, retry
  *   3  -  I/O error (disk full, permission denied, parent dir missing)
  *   5  -  --if-rev did not match; the record moved, nothing was written
+ *   6  -  the write moves the run into `status: complete` without the evidence
+ *         lib/run-completion.mjs requires (last phase of the mode, Phase 4
+ *         evidence, a plan-coverage verdict); nothing was written
  *
  * Tunables (env):
  *   WRITE_STATE_LOCK_TIMEOUT_MS  acquire window before exit 2 (default 15000)
@@ -67,6 +70,7 @@ import { dirname, basename } from "path";
 import { Buffer } from "node:buffer";
 import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { completionGaps } from "../lib/run-completion.mjs";
 
 /**
  * @typedef {{ replace: boolean, path: string, ifRev: number|null }} ParsedArgs
@@ -320,6 +324,104 @@ function undeclaredKeys(payload, current) {
   );
 }
 
+const COMPLETE = new Set(["complete", "completed"]);
+const STOP_GUARD_HALT = /^\d+:stop-guard:/;
+
+/**
+ * Lift the halt run-stop-guard.mjs records after its repeat ceiling once the
+ * run advances a phase. That halt says only "the session kept stopping"; a
+ * later phase transition is the run going on, and leaving the halt in place
+ * would show a moving run as paused and make every later Stop let it through.
+ * A halt any other step recorded, or a write that sets status or haltReason
+ * itself, is left alone.
+ *
+ * @param {object} next
+ * @param {object} current
+ * @param {unknown} payload
+ */
+export function clearStopGuardHalt(next, current, payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  if (Object.hasOwn(payload, "status") || Object.hasOwn(payload, "haltReason")) return;
+  if (typeof current?.haltReason !== "string" || !STOP_GUARD_HALT.test(current.haltReason)) return;
+  const was = Number(current.currentPhase);
+  const now = Number(payload.currentPhase);
+  if (!Number.isInteger(now) || !(now > (Number.isInteger(was) ? was : -1))) return;
+  next.haltReason = null;
+  next.status = "in_progress";
+}
+
+/**
+ * Clear a wait the run has moved past. A write that advances `currentPhase`
+ * without setting `waitingFor` itself ends any wait recorded in the earlier
+ * phase, so a clear the step forgot cannot keep the run marked as waiting
+ * (and the stop guard off) for the rest of the run. `question` is left to
+ * answer-question.mjs, which clears it together with its pendingQuestion.
+ *
+ * @param {object} next
+ * @param {object} current
+ * @param {unknown} payload
+ */
+export function clearPassedWait(next, current, payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  if (Object.hasOwn(payload, "waitingFor")) return;
+  if (typeof current?.waitingFor !== "string" || current.waitingFor === "question") return;
+  const was = Number(current.currentPhase);
+  const now = Number(payload.currentPhase);
+  if (!Number.isInteger(now) || !(now > (Number.isInteger(was) ? was : -1))) return;
+  next.waitingFor = null;
+}
+
+/**
+ * The refusal message for a write that moves the run into `complete` without
+ * the evidence lib/run-completion.mjs asks for, or null.
+ *
+ * Only the transition is judged: a merge that sets `status: complete`, or a
+ * replace whose document is complete over one that was not. A later write to
+ * an already complete run that does not touch `status` goes through, so the
+ * report steps after the transition keep working.
+ *
+ * @param {object} next
+ * @param {unknown} payload
+ * @param {boolean} replace
+ * @param {string|null} diskStatus
+ * @returns {string|null}
+ */
+export function completionRefusal(next, payload, replace, diskStatus) {
+  if (!COMPLETE.has(next?.status)) return null;
+  const entering = replace
+    ? !COMPLETE.has(diskStatus)
+    : Boolean(payload && typeof payload === "object" && COMPLETE.has(payload.status));
+  if (!entering) return null;
+  const gaps = completionGaps(next);
+  if (!gaps.length) return null;
+  return `write-state: refusing status "${next.status}": ${gaps.join("; ")}. Nothing was written. Finish the missing step, or record a halt (status "paused" with a haltReason).`;
+}
+
+/**
+ * Bind the run to the host session that drives it.
+ *
+ * `hostSessionId` is the Claude Code session (CLAUDE_CODE_SESSION_ID in the
+ * Bash environment) that made the run's last phase transition. The Stop hook
+ * (run-stop-guard.mjs) and the run-scoped PreToolUse guards read it to find
+ * the run a hook call belongs to. Stamped only when the write creates the
+ * document or sets `currentPhase`: those are the driver's writes, while a
+ * second session editing a running task (`/multi-agent:steer`) sets neither
+ * and so does not take the run over.
+ *
+ * @param {object} next
+ * @param {unknown} payload
+ * @param {boolean} existed
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function stampHostSession(next, payload, existed, env = process.env) {
+  const sid = env.CLAUDE_CODE_SESSION_ID;
+  if (typeof sid !== "string" || !sid.trim()) return;
+  const transition =
+    payload && typeof payload === "object" && Object.hasOwn(payload, "currentPhase");
+  if (existed && !transition) return;
+  next.hostSessionId = sid.trim();
+}
+
 /**
  * @param {object} base
  * @param {object} patch
@@ -397,6 +499,8 @@ async function main() {
         }
       }
       next = deepMerge(current, payload);
+      clearStopGuardHalt(next, current, payload);
+      clearPassedWait(next, current, payload);
     }
 
     // A state document is an object. Anything else cannot carry `rev`, and
@@ -415,9 +519,11 @@ async function main() {
     // would tell the next reader that nothing changed.
     let priorRev = Number.isInteger(next.rev) ? next.rev : 0;
     let diskRev = null;
+    let diskStatus = null;
     if (existsSync(path)) {
       try {
         const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        diskStatus = parsed?.status ?? null;
         if (Number.isInteger(parsed?.rev)) {
           diskRev = parsed.rev;
           priorRev = Math.max(priorRev, parsed.rev);
@@ -448,7 +554,15 @@ async function main() {
       }
     }
 
+    const refusal = completionRefusal(next, payload, replace, diskStatus);
+    if (refusal) {
+      console.error(refusal);
+      releaseLock(path);
+      process.exit(6);
+    }
+
     next.rev = priorRev + 1;
+    stampHostSession(next, payload, fileExistedBefore);
 
     const unknown = undeclaredKeys(payload, replace ? {} : current);
     if (unknown.length) {

package/pipeline/skills/.skill-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-20T13:08:30Z",
-  "skillCount": 229,
+  "generatedAt": "2026-10-24T14:34:39Z",
+  "skillCount": 234,
   "entries": [
     {
       "path": "shared/core/apple-archive-compliance/SKILL.md",
@@ -237,7 +237,7 @@
     },
     {
       "path": "shared/core/multi-agent-sync/SKILL.md",
-      "sha256": "1e418fe472a93cc7b4b5bc19ff9e9b8b9d89b545e45d343a643f17a492cb0624"
+      "sha256": "e96afa9b89a2ab6e2fe13a01158f98272c6828e5cef03c8909240766aaefd44b"
     },
     {
       "path": "shared/core/multi-agent-test-accessibility/SKILL.md",
@@ -251,6 +251,10 @@
       "path": "shared/core/multi-agent-test-dynamic-type/SKILL.md",
       "sha256": "e1cadd5eb8d680b0edfc40a4912733dc6a432493c868f4997b2dec0db6638dd4"
     },
+    {
+      "path": "shared/core/multi-agent-test-gen/SKILL.md",
+      "sha256": "0da450ed0c74ab610d3c8f0cf1b0facd2a4ae179afc832440939c3367de7e762"
+    },
     {
       "path": "shared/core/multi-agent-test-screenshots/SKILL.md",
       "sha256": "a41507304e4650079e6359b3ad5854f90f45a90172911f487c4c923ef8839f91"
@@ -487,6 +491,10 @@
       "path": "shared/external/firebase/SKILL.md",
       "sha256": "d377217a03e7fc63bd7eba285c6e2b450f293b13c6e65680e71b022cd14872a3"
     },
+    {
+      "path": "shared/external/fix-review-verdicts/SKILL.md",
+      "sha256": "a728b7c87fbf175e959e23b655c626294b7a7a2949c62a37e7b3d4a172ce57d5"
+    },
     {
       "path": "shared/external/github-actions-templates/SKILL.md",
       "sha256": "13b6fec454c2ebf69b06fcdc00033a6dab98d6111e0346447c8d474db547f801"
@@ -495,6 +503,10 @@
       "path": "shared/external/gradle-kotlin-dsl/SKILL.md",
       "sha256": "af7b1e30e2448f43b5100b2a935bbaadde86ccd490844c901736c9270f8cc3ce"
     },
+    {
+      "path": "shared/external/handle-request/SKILL.md",
+      "sha256": "05ecf72d8e40eeca8dfc0913764b1188b9b1189ea098ad23b4f0c8256f2c671c"
+    },
     {
       "path": "shared/external/healthkit/SKILL.md",
       "sha256": "fece1986bc35925e34fed8d8cb13aa59a3577b8cedefdc02c736c0d4a5d38aff"
@@ -703,6 +715,10 @@
       "path": "shared/external/room-database/SKILL.md",
       "sha256": "45fe377469f1fb4036431194d3b525d3caaa79231808625f643468863c6e814a"
     },
+    {
+      "path": "shared/external/scenario-gap-analysis/SKILL.md",
+      "sha256": "fcd9f614dc18ea0d4610469f7edcf9214d3b14d65976fa3fb7c4a524330a392a"
+    },
     {
       "path": "shared/external/search-first/SKILL.md",
       "sha256": "c9d5ffb698bbfb76a89da6a35dfc0f1d72a31d2b4a0e9e9f3e027be7a8fddfde"
@@ -855,6 +871,10 @@
       "path": "shared/external/tailwind-css/SKILL.md",
       "sha256": "9eda0a871962f52e381781b95c948128626984a82ddbd47be53ea869cd250b7e"
     },
+    {
+      "path": "shared/external/test-result-triage/SKILL.md",
+      "sha256": "72b0e0049fcf549b61a189900ca8e503b779e93cd26575d7b7328ae785465e38"
+    },
     {
       "path": "shared/external/testing-backend/SKILL.md",
       "sha256": "d3eea1c6d1e2a40a0b66bc6460194ee313e17fc2af8f75047030b7840c2db857"

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 229,
+  "skillCount": 234,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -191,7 +191,7 @@
     },
     {
       "name": "app-store-review",
-      "description": "App Store submission readiness and rejection prevention: Review Guidelines 2.1, 2.3, 2.5.1, 3.1.1, 4.2 and 5.1.2, PrivacyInfo.xcprivacy manifests and required-reason codes, IAP and StoreKit rules, ATT consent, EU DMA distribution, entitlements and usage strings, metadata limits, screenshots, TestFli",
+      "description": "App Store submission readiness and rejection prevention: Review Guidelines 1.2, 2.1, 2.3, 2.3.14, 2.5.1, 2.5.19, 3.1.1, 4.2 and 5.1.2, upload floors, age rating and medical device declarations, PrivacyInfo.xcprivacy manifests and required-reason codes, IAP and StoreKit rules, ATT consent, EU DMA dis",
       "platform": null,
       "group": "external",
       "plugin": "ai-ios-toolkit",
@@ -596,6 +596,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/firebase/SKILL.md"
     },
+    {
+      "name": "fix-review-verdicts",
+      "description": "Independent fix review with three verdicts, test-gaming, scope and root-cause, each backed by file:line findings; the result is computed from findings, never from a claim. Use when reviewing a fix made to turn tests green. Not a full review checklist.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-common-toolkit",
+      "invokeAs": "ai-common-toolkit:fix-review-verdicts",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/fix-review-verdicts/SKILL.md"
+    },
     {
       "name": "github-actions-templates",
       "description": "Authoring GitHub Actions workflows: triggers, matrices, caching, concurrency, least-privilege permissions, SHA pinning, OIDC, reusable workflows, composite actions, Xcode runners. Use when writing or hardening a workflow file.",
@@ -629,6 +640,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/gradle-kotlin-dsl/SKILL.md"
     },
+    {
+      "name": "handle-request",
+      "description": "Add the test handles a scenario needs and answer each request with ADDED, ALREADY or COULD NOT ADD plus file:line or reason. Identity values only, attribute-only diffs; iOS accessibilityIdentifier, Compose testTag, web data-testid. Use when a test needs an element handle the UI lacks.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-common-toolkit",
+      "invokeAs": "ai-common-toolkit:handle-request",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/handle-request/SKILL.md"
+    },
     {
       "name": "healthkit",
       "description": "HealthKit on iOS, iPadOS, watchOS and visionOS: HKHealthStore authorization, sample, statistics and chart-ready collection queries, saving HKQuantitySample values, background delivery, live workouts (HKWorkoutSession, HKLiveWorkoutBuilder), HKUnit, HKQuantityTypeIdentifier. Use when reading, writing",
@@ -1685,6 +1707,17 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-test-dynamic-type/SKILL.md"
     },
+    {
+      "name": "multi-agent-test-gen",
+      "description": "Write the tests an app lacks, stage by stage, each gated on its artefact: inventory, read-only gap analysis, handles, tests, runs, per-test classification. Use when screens, flows or a change need tests.",
+      "platform": null,
+      "group": "core",
+      "plugin": null,
+      "invokeAs": "multi-agent-test-gen",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-test-gen/SKILL.md"
+    },
     {
       "name": "multi-agent-test-screenshots",
       "description": "App Store screenshot set from a booted simulator / emulator in a given locale, taken as an argument and defaulting to tr. Alias pinning the screenshot scenario. Use when generating store screenshots or checking a localised build renders.",
@@ -1927,6 +1960,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/room-database/SKILL.md"
     },
+    {
+      "name": "scenario-gap-analysis",
+      "description": "Set an inventory against existing tests, sort each behaviour into COVERED, WRONGLY COVERED or MISSING, and write gaps as measurable, prioritised scenarios with cross-screen flows. Use when planning tests or auditing coverage. Not for writing tests or judging a run.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-common-toolkit",
+      "invokeAs": "ai-common-toolkit:scenario-gap-analysis",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/scenario-gap-analysis/SKILL.md"
+    },
     {
       "name": "search-first",
       "description": "Research-before-coding workflow. Before writing a custom implementation, check what already exists (repo utilities, installed libraries, packages, internal components) and decide adopt / extend / compose / build on evidence. Use at the start of any non-trivial feature or utility, especially when you",
@@ -2345,6 +2389,17 @@
       "triggerPaths": [],
       "relativePath": "shared/external/tailwind-css/SKILL.md"
     },
+    {
+      "name": "test-result-triage",
+      "description": "Judge each test result on changed code as product-bug, stale-test, valid or ambiguous (the default), and list behaviour no test covers. stale-test needs a diff file:line, product-bug needs evidence. Use when tests ran on a new commit, PR or fix. Not for writing or editing tests.",
+      "platform": null,
+      "group": "external",
+      "plugin": "ai-common-toolkit",
+      "invokeAs": "ai-common-toolkit:test-result-triage",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/test-result-triage/SKILL.md"
+    },
     {
       "name": "testing-backend",
       "description": "Backend testing: pytest patterns (Python), Jest patterns (Node.js), integration testing, database fixtures/factories, API contract testing. Use when writing or reviewing backend tests: unit, integration, database and API level.",

package/pipeline/skills/shared/README.md

@@ -2,24 +2,24 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 229 skills (68 core + 161 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 234 skills (69 core + 165 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  68 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
-- **`external/`**  -  161 iOS / Android / generic skills that ship into the stack plugins. Each names its origin in `metadata.source`: `multi-agent-pipeline` when written here, or the upstream and license a `NOTICE-*.md` in this directory covers.
+- **`core/`**  -  69 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`external/`**  -  165 iOS / Android / generic skills that ship into the stack plugins. Each names its origin in `metadata.source`: `multi-agent-pipeline` when written here, or the upstream and license a `NOTICE-*.md` in this directory covers.
 - Install destinations (ADR-0009): Claude Code gets NO local copy of `external/` - it loads those skills from the `multi-agent-plugins` marketplace, namespaced (`ai-<stack>-toolkit:<name>`); only the two compliance catalogs from `core/` land in `~/.claude/skills/`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. `external/` remains the single authoring source that `build-stack-plugins.mjs` publishes from.
 
 Source layout is logical grouping only  -  skill discovery at runtime is unchanged.
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  68
+- [Pipeline Orchestration](#pipeline-orchestration)  -  69
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  94
 - [Android / Kotlin](#android-kotlin)  -  16
 - [Web](#web)  -  10
 - [Backend / API](#backend-api)  -  11
-- [Cross-cutting](#cross-cutting)  -  30
+- [Cross-cutting](#cross-cutting)  -  34
 
 ## Pipeline Orchestration
 
@@ -89,6 +89,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-test-accessibility`](./core/multi-agent-test-accessibility/) | `core` | Accessibility audit on a booted simulator / emulator: VoiceOver labels, sub-44pt tap targets, contrast, traits. Alias pinning the accessibil |
 | [`multi-agent-test-dark-mode`](./core/multi-agent-test-dark-mode/) | `core` | Dark mode UI test on a booted simulator / emulator: walk every screen light then dark, report contrast + colour bugs. Alias pinning the dark |
 | [`multi-agent-test-dynamic-type`](./core/multi-agent-test-dynamic-type/) | `core` | Dynamic Type layout test on a booted simulator / emulator: re-walk every screen at XL through accessibility-extra-large, report truncation a |
+| [`multi-agent-test-gen`](./core/multi-agent-test-gen/) | `core` | Write the tests an app lacks, stage by stage, each gated on its artefact: inventory, read-only gap analysis, handles, tests, runs, per-test  |
 | [`multi-agent-test-screenshots`](./core/multi-agent-test-screenshots/) | `core` | App Store screenshot set from a booted simulator / emulator in a given locale, taken as an argument and defaulting to tr. Alias pinning the  |
 | [`multi-agent-testflight-validation`](./core/multi-agent-testflight-validation/) | `core` | iOS-pinned alias of store-ready: same three gates on an iOS build, one implementation. Validates a TestFlight / App Store package, never upl |
 | [`multi-agent-uninstall`](./core/multi-agent-uninstall/) | `core` | Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline set |
@@ -264,15 +265,19 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`e2e-testing`](./external/e2e-testing/) | `external` | \| |
 | [`evidence-github`](./external/evidence-github/) | `external` | Search GitHub for facts an analysis can cite - a known issue in a dependency, the PR that fixed it, what a release actually changed, prior a |
 | [`evidence-registry`](./external/evidence-registry/) | `external` | Check a package's real version, deprecation status and release notes on npm, PyPI, Maven Central or Swift Package Index. Use when a spec or  |
+| [`fix-review-verdicts`](./external/fix-review-verdicts/) | `external` | Independent fix review with three verdicts, test-gaming, scope and root-cause, each backed by file:line findings; the result is computed fro |
 | [`github-actions-templates`](./external/github-actions-templates/) | `external` | Authoring GitHub Actions workflows: triggers, matrices, caching, concurrency, least-privilege permissions, SHA pinning, OIDC, reusable workf |
+| [`handle-request`](./external/handle-request/) | `external` | Add the test handles a scenario needs and answer each request with ADDED, ALREADY or COULD NOT ADD plus file:line or reason. Identity values |
 | [`humanizer`](./external/humanizer/) | `external` | \| |
 | [`localization-reuse-map`](./external/localization-reuse-map/) | `external` | Localization reuse map for one redesigned screen on iOS, Android and web: new keys set against each platform's legacy key, legacy values and |
 | [`pdfkit`](./external/pdfkit/) | `external` | PDFKit on iOS: PDFView display and SwiftUI wrapping, creating and editing PDFDocument and PDFPage, highlight, note, signature and form annot |
+| [`scenario-gap-analysis`](./external/scenario-gap-analysis/) | `external` | Set an inventory against existing tests, sort each behaviour into COVERED, WRONGLY COVERED or MISSING, and write gaps as measurable, priorit |
 | [`search-first`](./external/search-first/) | `external` | \| |
 | [`security-review`](./external/security-review/) | `external` | Run a defensive, static security review of a diff or a repo: build a run-scoped threat model, find vulnerabilities joined to OWASP + CWE wit |
 | [`signal-community`](./external/signal-community/) | `external` | Check whether other people hit the same problem, via Stack Overflow and Hacker News (keyless) plus opt-in Reddit and X. Use when a bug repor |
 | [`skill-creator`](./external/skill-creator/) | `external` | House guide for authoring plugin skills: creating a new skill, trimming or splitting a bloated one, writing or sharpening a description, and |
 | [`spm-build-analysis`](./external/spm-build-analysis/) | `external` | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use whe |
+| [`test-result-triage`](./external/test-result-triage/) | `external` | Judge each test result on changed code as product-bug, stale-test, valid or ambiguous (the default), and list behaviour no test covers. stal |
 | [`valven-rules`](./external/valven-rules/) | `external` | Delivery-flow rules from metrics Valven reports: PR size, one concern per PR, tests with source, issue keys, no WIP commits, churn, PR body, |
 | [`xcode-build-benchmark`](./external/xcode-build-benchmark/) | `external` | Benchmark Xcode clean and incremental builds with repeatable inputs, timing summaries, and timestamped `.build-benchmark/` artifacts. Use wh |
 | [`xcode-build-fixer`](./external/xcode-build-fixer/) | `external` | Apply approved Xcode build optimization changes following best practices, then re-benchmark to verify improvement. Use when a developer has  |

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -33,7 +33,7 @@ Run all steps automatically:
 ```
 Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 65 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 66 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
@@ -229,7 +229,7 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**65 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**66 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
@@ -241,7 +241,7 @@ prune-prompts, purge, refactor, research, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scaffold, scan, scenario-audit, search,
 security-review, serve, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
-test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
+test-dark-mode, test-dynamic-type, test-gen, test-screenshots, testflight-validation,
 uninstall, update
 ```
 

package/pipeline/skills/shared/core/multi-agent-test-gen/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: multi-agent-test-gen
+description: "Write the tests an app lacks, stage by stage, each gated on its artefact: inventory, read-only gap analysis, handles, tests, runs, per-test classification. Use when screens, flows or a change need tests."
+user-invocable: true
+argument-hint: "[scope] [--platform ios|android|web] [--repo <path>]  -  scope: a screen, route or flow, or empty for what changed since the last test-gen run"
+metadata:
+  language: en
+  not-for: test, bug-bash, scenario-audit, manual-test
+---
+
+# multi-agent-test-gen
+
+**Input**: $ARGUMENTS
+
+Writes the tests an app is missing, in the repo's own frameworks, and reports
+what they found. Seven stages run as subagents, each leaving one artefact that a
+script gates before the next stage starts: inventory, discovery, gaps, handles,
+write, run, classify. The two analysis stages run as a read-only agent type, so
+nothing they do can change the repository.
+
+Stage contract, read before Step 1:
+
+```
+$HOME/.claude/multi-agent-refs/test-gen/stages.md
+$HOME/.claude/multi-agent-refs/features/test-classification.md
+```
+
+Scripts: `test-gen-gate.mjs` (artefact, handle and write gates),
+`handle-diff-audit.mjs` (handles only), `test-classify.mjs`,
+`test-gen-state.mjs` (change base, revision cap), `evidence-gate.mjs`, all under
+`$HOME/.claude/scripts/`. Schemas: `test-gen-inventory`, `test-gen-gaps`,
+`test-gen-results` under `$HOME/.claude/schemas/`.
+
+## Gotchas
+
+- An analysis stage that wants to "just fix" something is out of its lane. Discovery and gaps go to `test-gen-analyst`, whose grant is an allowlist of read-only tools.
+- The handle stage adds handles and nothing else. A wrapped view, a renamed element or a changed condition fails `handle-diff-audit.mjs`; revert the hunk, do not argue with the audit.
+- `HANDLES: none-needed` is a claim that the handles exist. It needs the `file:line` of each.
+- A test that passed once is not green. Unstable is a fail, and a red test with no base to compare is `not_measured`, not a regression.
+- Test data is named in `dataNeeds[]`, never filled in by the run. A credential is a `secretRef`.
+- A product bug is reported, never fixed here. In autopilot it parks the run.
+
+## Step 1 - Prepare
+
+1. Repo: `--repo`, else the current directory; confirm it in one line.
+   Platform: `--platform`, else detect as `multi-agent-test` does. Run id
+   `tg-<timestamp>`; `RUN="$HOME/.claude/logs/test-gen/<repo>/<timestamp>"`,
+   created with `mkdir -p "$RUN"`.
+2. Toolkit: `test_results_classify`, `coverage_gap` and `ui_locator_codegen`
+   need `@mmerterden/multi-agent-toolkit-mcp` >= v3.25.0. Check the tool list
+   once. Each missing tool has a fallback in `stages.md` (classify from the
+   repeats, the analyst matches coverage itself with every match `inferred`,
+   locators written by hand from the handles); say which fallbacks are in use,
+   once.
+3. Change base. `TG_STATE="$HOME/.claude/knowledge/<project>/test-gen-state.json"`:
+
+   ```bash
+   node "$HOME/.claude/scripts/test-gen-state.mjs" base-scan --state "$TG_STATE" --repo "$REPO" \
+     --graph "$HOME/.claude/knowledge/<project>/code-graph.json" > "$RUN/base-scan.json"
+   ```
+
+   Exit 0: the changed files and their dependents narrow an empty scope. Exit 1
+   (`measured: false`, first run or base gone): nothing is narrowed, and the
+   reason goes in the report.
+
+## Step 2 - Inventory and priority
+
+Stage 1 of `stages.md`, then the priority pick: ask which items to cover
+(one question to the user; autopilot: the top three, recorded as `autopilot-top3`). Gate:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" check --stage inventory --file "$RUN/inventory.json"
+node "$HOME/.claude/scripts/evidence-gate.mjs" --claim artefact --status passed \
+  --evidence "$RUN/inventory.json" --stage-start "$STAGE_START"
+```
+
+## Step 3 - Discovery and gaps (read-only)
+
+Stages 2 and 3, both with `subagent_type: "test-gen-analyst"`. Write each answer
+with the Write tool, then gate each file with `evidence-gate.mjs --claim
+artefact` against its own stage start, and each with `test-gen-gate.mjs check`
+(`--stage discovery`, `--stage gaps`). Show the gaps (bucket, priority,
+expectation) and the `dataNeeds[]`; ask for the data or the credential names
+(autopilot: write only the scenarios whose needs are met).
+
+## Step 4 - Handles
+
+Stage 4. Snapshot first (`test-gen-gate.mjs baseline`), then the subagent, then
+both gates against that snapshot: `test-gen-gate.mjs handles` and
+`handle-diff-audit.mjs --baseline` exit 0. The gates read only the stage's own
+change; the person's uncommitted work is never the stage's to revert. Skip the
+stage when no gap has `handlesNeeded`, and say so.
+
+## Step 5 - Write, run, classify
+
+Stages 5 to 7: a new snapshot, the tests and `written.json`, the
+`test-gen-gate.mjs written --baseline` gate (test files only, inside the repo
+and changed by the stage, no test gaming, a discovered runner, more than zero
+tests run), the repeated runs, then
+`results.json` through `test-classify.mjs` and `test-gen-gate.mjs results`.
+
+## Step 6 - Triage
+
+Stage 8, one verdict per non-pass result, each through `test-gen-state.mjs
+revise`. Exit 3 parks the run: stop, keep every artefact, report why, and record
+no change base, because the run did not finish.
+
+## Step 7 - Report and base
+
+Print, in this order: the tests written (file, scenario, expectation), the
+results table from `results.json` with every `fail` and `not_measured` reason,
+the triage verdicts, the handles added (`handles.md`), the scenarios blocked by
+data, and `gaps.json`'s `unmeasured[]`. State which parts are mechanical (the
+gates, the classification, the handle audit) and which are judgement (the
+inventory, the gaps, the triage). Then record the change base
+(`test-gen-state.mjs base-record`).
+
+Offer, one question: open the product bugs through `multi-agent` with each
+failing test as the acceptance check, or stop. **No commit, no push, no issue
+from this command.**