@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/schemas/answer-request.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/answer-request.schema.json",
+  "title": "Answer request",
+  "description": "The body of POST /v1/runs/{id}/answer: the answer to the question a run stopped on, as `answer-question.mjs <state> --question <questionId> --answer <optionIds>` takes it. questionId is the pendingQuestion.id the client read from the runs index; a run that has moved on to another question refuses the answer. Every option id must be one the question offered. Nothing here is free text, so nothing here can become an instruction.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["questionId", "optionIds"],
+  "properties": {
+    "questionId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "maxLength": 100,
+      "x-sensitivity": "none"
+    },
+    "optionIds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "x-sensitivity": "none",
+      "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9+_-]*$", "maxLength": 100 }
+    }
+  }
+}

package/pipeline/schemas/answer-result.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/answer-result.schema.json",
+  "title": "Answer result",
+  "description": "What `answer-question.mjs` prints, and POST /v1/runs/{id}/answer returns, once an answer is recorded: the lastAnswer written to the run's state in the same write that cleared pendingQuestion.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "answered"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "answered": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["questionId", "stepId", "optionIds", "answeredAt"],
+      "x-sensitivity": "none",
+      "properties": {
+        "questionId": { "type": "string" },
+        "stepId": { "type": "string" },
+        "optionIds": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "answeredAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/pipeline/schemas/autopilot-config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/autopilot-config.schema.json",
   "title": "Autopilot configuration",
-  "description": "Continuous mode on ONE machine. Lives at ~/.claude/autopilot/config.json and deliberately NOT in multi-agent-preferences.json: that file has additionalProperties false and a migration chain, so a block there would push a key into every local user's preferences forever, including everyone who never turns this on. This file is the repo SELECTION, not the on/off state: autopilot-off keeps it so turning the mode back on does not re-ask which repos. On/off is whether launchd holds the job, because that is the thing that actually makes work happen. A clean install writes neither - there is no `enabled: false` default, because a file written at install time is a file that can be wrong.",
+  "description": "Continuous mode on ONE machine. Lives at ~/.claude/autopilot/config.json and deliberately NOT in multi-agent-preferences.json: that file has additionalProperties false and a migration chain, so a block there would push a key into every local user's preferences forever, including everyone who never turns this on. This file is the repo SELECTION, not the on/off state: autopilot-off keeps it so turning the mode back on does not re-ask which repos. On/off is whether launchd holds the job, because that is the thing that actually makes work happen. A clean install writes neither - there is no `enabled: false` default, because a file written at install time is a file that can be wrong. Every reader validates the file against this schema when it loads it; a value the schema refuses stops the queue with the field named (blocked-config) rather than being read as a missing ceiling.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "repos"],
@@ -52,13 +52,33 @@
           },
           "jiraJql": {
             "type": "string",
-            "description": "Full JQL, so an instance that cannot use labels is a config change rather than a redesign. The label form is sugar for: assignee = currentUser() AND labels = \"<label>\" AND resolution = EMPTY AND status not in (Done, Closed, Cancelled) ORDER BY priority DESC, created ASC. Jira labels are a single global namespace anyone can write to, so on a shared instance prefer a qualified name, and note that the Labels field must be on the edit screen for the issue types in play."
+            "description": "Full JQL, so an instance that cannot use labels is a config change rather than a redesign. The label form is sugar for: assignee = currentUser() AND labels = \"<label>\" AND resolution = EMPTY AND status not in (Done, Closed, Cancelled) ORDER BY priority DESC, created ASC. Jira labels are a single global namespace anyone can write to, so on a shared instance prefer a qualified name, and note that the Labels field must be on the edit screen for the issue types in play. An issue that more than one repo's search returns is queued once, for the first repo in config order, so repos sharing a Jira instance should each carry a jiraJql that matches only their own issues."
           },
           "jiraLabel": {
             "type": "string",
             "default": "agent-queue",
             "description": "Sugar for jiraJql. Ignored when jiraJql is set."
           },
+          "host": {
+            "enum": ["github", "bitbucket"],
+            "default": "github",
+            "description": "Where the runner publishes this repo's verified branch (autopilot-publish.mjs). github: push, then `gh pr create --draft`. bitbucket: there is no draft PR, so the branch is pushed, a summary is written beside the PR request and the outcome is pushed-awaiting-pr. Any other value is refused at publish time, before anything is pushed."
+          },
+          "pushUrl": {
+            "type": "string",
+            "description": "The URL the runner pushes to. Absent on github: `gh repo view <nameWithOwner> --json url`. Required on bitbucket. Never read from the worktree's .git/config, which the run could have changed. Carries no credentials; the operator's git credential helper supplies them, and a URL with credentials in it is refused."
+          },
+          "baseBranch": {
+            "type": "string",
+            "description": "The base every PR request for this repo must target. When set, a request naming another base is refused, and this branch is protected like main, master, develop and release/*. When absent, the base is the remote's default branch (the branch its HEAD names); a remote that names none is refused until this is set."
+          },
+          "allowedBases": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true,
+            "default": [],
+            "description": "Further bases a PR request for this repo may target, beside baseBranch or the remote's default branch. Each listed branch is protected like baseBranch. Empty means only the one base is accepted."
+          },
           "rank": {
             "type": "integer",
             "minimum": 1,
@@ -80,13 +100,84 @@
       "minimum": 60,
       "maximum": 3600,
       "default": 120,
-      "description": "How often a tick looks for new work. 120s means an issue is picked up within two minutes of being labelled. The scan itself is cheap - one `gh issue list` per repo plus one Jira search - so at five repos this is about 150 GitHub calls an hour against a 5000/hour limit. launchd does NOT wake a sleeping Mac, it only fires on the next wake, which is why the mode holds a sleep assertion while on AC and releases it on battery."
+      "description": "How often a tick looks for new work. 120s means an issue is picked up within two minutes of being labelled. The scan itself is cheap - one `gh issue list` per repo plus one Jira search - so at five repos this is about 150 GitHub calls an hour against a 5000/hour limit. launchd does NOT wake a sleeping Mac, it only fires on the next wake, which is why the awake agent (`awake`) holds sleep off for as long as the mode is on and a tick holds `caffeinate -s -w <pid>` while its session is in flight (multi-agent-refs/features/autopilot-operations.md)."
+    },
+    "maxParallelAgents": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "default": null,
+      "description": "Ceiling on runner-launched sessions working at once: the run the runner supervises plus every parked run whose session is busy again after a person answered it. A ceiling, never a raise: absent or null is unlimited and keeps the existing behaviour exactly, which is one supervised session at a time (runner.pid is exclusive) within `slots`, parked runs not counted. When set and the agent list cannot be read, no item is taken that tick."
+    },
+    "gc": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The daily cleanup report. On the first tick of each local day the runner runs gc-abandoned.sh over the worktrees it created (worktrees.jsonl: only runs whose state carries the session id the runner launched them with) and writes gc-report-<date>.json and .md to the autopilot root. A worktree the queue still holds is never on the list.",
+      "properties": {
+        "autoDelete": {
+          "type": "boolean",
+          "default": false,
+          "description": "Off: the report is a dry run and nothing is removed. On: gc-abandoned.sh runs with --yes, still restricted to runner-created worktrees and under its own rules - a run waiting on you is kept (including one parked with verificationFailed or waitingFor, and any whose item's newest attempt is parked), uncommitted work is stashed and its worktree kept, nothing outside <repo>/.worktrees/ is touched."
+        }
+      }
+    },
+    "verify": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The publish step's independent verification (multi-agent-refs/features/unattended-security.md). Before anything is pushed, the runner resolves the worktree's stack with _stack-adapter.mjs and runs the adapter's build and test commands itself, with tokens removed from the environment, then judges the output with evidence-gate.mjs --stack and test-summary.mjs. The run's own gate ledger is agent-writable and is only a consistency check.",
+      "properties": {
+        "allowUnverifiedStack": {
+          "type": "boolean",
+          "default": false,
+          "description": "False: a stack the adapters cannot build and test (the unknown adapter, a package without a build or test script) is refused as publish/verify-stack. True: such a branch is published on the ledger and test-log checks alone, and the verdict records verified: false."
+        },
+        "timeoutSec": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1800,
+          "description": "Ceiling for each of the build and the test command. At the ceiling the command's whole process group is killed and the publish is refused as publish/verify-build or publish/verify-test."
+        }
+      }
+    },
+    "digest": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The opt-in daily digest: items attempted, outcomes by class, PRs opened, parked items waiting for an answer, and cost, over the trailing 24 hours. Written to digest-<date>.json and .md on the first tick of each local day. Sent only when `reportChannels` is also true and `channels.mode` is `configured`, through the same outbound gate as the post-PR report.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Absent or false: no digest is computed, written or sent."
+        },
+        "jiraIssue": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*-[0-9]+$",
+          "description": "The standing Jira issue the digest is posted to as one comment when `channels.targets` has `jira`. A digest belongs to no single item, so it needs an issue of its own; without one the Jira target is reported as skipped."
+        }
+      }
+    },
+    "awake": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": { "enabled": true, "display": false },
+      "description": "Keeps the Mac awake for as long as autopilot is on, so launchd ticks keep firing between runs: a separate launchd agent (com.multi-agent.autopilot-awake) runs `/usr/bin/caffeinate -s -i`, installed by autopilot-on and removed by autopilot-off. `-s` holds system sleep off on AC power only; `-i` holds idle sleep off on battery as well. The in-flight lock around each run is separate and unchanged (multi-agent-refs/features/autopilot-operations.md).",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "False: no awake agent is installed and only the in-flight lock holds sleep off, so the Mac may sleep between ticks and the queue waits for the next wake."
+        },
+        "display": {
+          "type": "boolean",
+          "default": false,
+          "description": "True adds `-d`, keeping the display on too. Off by default: it costs energy and screen wear, and autopilot does not need it - builds, simctl screenshots and headless browsers work with the display asleep. Display sleep does not lock the keychain; system sleep can."
+        }
+      }
     },
     "maxAttempts": {
       "type": "integer",
       "minimum": 1,
       "default": 2,
-      "description": "How many times a died or build-failed item is re-queued before it is left alone. Retry is part of intake rather than a separate mechanism; without it one transient failure drops an item silently."
+      "description": "How many attempts that produced nothing - every RETRYABLE outcome in pipeline/scripts/_autopilot-outcomes.mjs, counted once per run - an item gets before it is left alone. Retry is part of intake rather than a separate mechanism; without it one transient failure drops an item silently."
     },
     "maxConsecutivePerRepo": {
       "type": "integer",
@@ -96,14 +187,13 @@
     },
     "askOnLowMaturity": {
       "type": "boolean",
-      "default": true,
-      "description": "An item that fails the readiness review gets ONE comment listing the open questions, and waits. This is an outward-facing write to a real ticket, so it is a flag rather than an assumption. When false the item is skipped with the reason recorded and nothing is posted."
+      "description": "Reserved, and read by nothing: setting it has no effect. It names a planned switch for posting one question comment on an item that fails the readiness review. Today a maturity blocker parks the run for the research-then-ask flow (maxAskRounds), whatever this says. Declared so a config that carries it still validates under additionalProperties false."
     },
     "maxAskRounds": {
       "type": "integer",
       "minimum": 1,
       "default": 2,
-      "description": "Ceiling on how many times one item can be asked about, so a permanently vague ticket cannot be commented on forever. The gap fingerprint prevents repeating the SAME question; this prevents an endless series of different ones."
+      "description": "Ceiling on research-then-ask rounds for one item, so a permanently vague ticket is not researched or asked about forever. A run that parks on a maturity blocker or on open questions gets one research pass per round (refs/features/research.md); the runner sums researchRounds from every attempted.jsonl row of the item, because each run of the item starts a fresh state file. At the ceiling the item is parked for a person without another pass. The gap fingerprint prevents repeating the SAME question; this prevents an endless series of different ones."
     },
     "costCeilingUsd": {
       "type": "number",
@@ -130,20 +220,28 @@
         }
       }
     },
+    "reportChannels": {
+      "type": "boolean",
+      "default": false,
+      "description": "Opt-in for any report beyond the draft PR. An unattended run posts nothing itself (agent-guard blocks every publisher under MULTI_AGENT_UNATTENDED=1). The runner, after it verified pr-request.json, pushed and opened the PR, and only then, reads the `channels` selection above: mode `configured` with target `jira` posts one comment (the PR link and text) through jira-publish.sh; `pr` is the draft PR itself; `confluence` and `wiki` need a page composed with publish rights and are reported as skipped. Absent or false: the draft PR is the only thing published. multi-agent-refs/features/unattended-security.md."
+    },
+    "reportIssueUpdates": {
+      "type": "boolean",
+      "default": false,
+      "description": "Opt-in for the issue updates an attended Phase 4 makes itself. After the runner opened the PR, and only then: update-issue-progress.sh for the GitHub issue the run recorded, and a PR-link comment on the linked Jira issue when reportChannels did not already post one. Each runs once, with MULTI_AGENT_UNATTENDED unset, and its text passes the outbound gate. Absent or false: nothing is posted."
+    },
     "reportStatus": {
       "type": "boolean",
-      "default": true,
-      "description": "Send a small heartbeat to the admin panel: counts and states only. Never item keys, repo names, branch names or PR titles - the existing telemetry hashes even the repo name, and carrying corporate ticket keys into that database would break the protection it was built for. A failed heartbeat is silent and never blocks a tick."
+      "description": "Reserved, and read by nothing: no heartbeat is sent, whatever this says. It names a planned counts-only heartbeat to the admin panel. Declared so a config that carries it still validates under additionalProperties false."
     },
     "sendItemKeys": {
       "type": "boolean",
-      "default": false,
-      "description": "Opt-in to also send item identifiers to the panel. Off by default and shown once with an example of what would be sent, because the same pipeline carries corporate identifiers."
+      "description": "Reserved, and read by nothing, like reportStatus: no item identifier leaves the machine through the runner. Declared so a config that carries it still validates under additionalProperties false."
     },
     "depthRouter": {
       "enum": ["off", "auto"],
-      "default": "off",
-      "description": "off: every item runs Full. auto: a deterministic router may pick Short for a bugfix or chore under the blast-radius threshold, and writes its reasoning into the PR body so the shortcut is visible to the reviewer. Off until a dozen items have been watched on Full."
+      "deprecated": true,
+      "description": "Accepted and ignored. Every item runs the one autopilot pipeline, and nothing reads this key; it stays declared so a config written by an older version still validates under additionalProperties false. autopilot-on drops it when it rewrites the file."
     }
   }
 }

package/pipeline/schemas/command-parameters.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/command-parameters.schema.json",
+  "title": "Command catalog",
+  "description": "What `commands.mjs --json` prints: every /multi-agent:<id> command with the parameters, surface and confirmation it declares in its SKILL.md frontmatter, defaults filled in. A client renders a button or a form from this without hard-coding a command. The frontmatter is the source; `_command-contract.mjs` holds it to `argument-hint`. Every field is `x-sensitivity: none`: nothing here is specific to a machine or a person.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "commands"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none",
+      "description": "Major 1. A minor bump adds fields; a consumer ignores keys it does not know."
+    },
+    "commands": {
+      "type": "array",
+      "x-sensitivity": "none",
+      "items": { "$ref": "#/$defs/command" }
+    }
+  },
+  "$defs": {
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "argumentHint", "parameters", "gui", "destructive", "confirm"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "x-sensitivity": "none",
+          "description": "The command directory name; invoked as /multi-agent:<id>."
+        },
+        "argumentHint": {
+          "type": "string",
+          "x-sensitivity": "none",
+          "description": "The human hint, verbatim. Empty when the command declares none."
+        },
+        "parameters": {
+          "type": "array",
+          "x-sensitivity": "none",
+          "items": { "$ref": "#/$defs/parameter" }
+        },
+        "gui": {
+          "enum": ["button", "form", "hidden"],
+          "x-sensitivity": "none",
+          "description": "button: runs with no input. form: collect parameters first. hidden: not offered as an action (maintainer tooling, help text). Independent of disable-model-invocation, which only stops the model invoking the command itself."
+        },
+        "destructive": {
+          "type": "boolean",
+          "x-sensitivity": "none",
+          "description": "Removes something that is not trivially recreated: a worktree, a branch, logs, an install, user instruction lines."
+        },
+        "confirm": {
+          "enum": ["required", "none"],
+          "x-sensitivity": "none",
+          "description": "required: a client asks before launching. Always required when destructive. The command keeps its own in-session confirmation either way."
+        }
+      }
+    },
+    "parameter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "kind"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^(--)?[a-z0-9][a-z0-9-]*$",
+          "x-sensitivity": "none",
+          "description": "`--name` for a flag, typed as written. Otherwise a positional, in order; a positional of kind flag is a literal keyword typed as its name."
+        },
+        "kind": {
+          "enum": ["run-id", "branch", "pull-request", "issue-key", "path", "text", "enum", "flag"],
+          "x-sensitivity": "none",
+          "description": "run-id: #N or a task id. pull-request: a PR number or URL. issue-key: a Jira key or a GitHub issue reference. flag: present or absent, no value."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "x-sensitivity": "none",
+          "description": "Omitted in frontmatter means false; the catalog always carries it."
+        },
+        "repeat": {
+          "type": "boolean",
+          "default": false,
+          "x-sensitivity": "none",
+          "description": "More than one value: space-separated for a positional, comma-separated for a flag."
+        },
+        "enum": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "x-sensitivity": "none",
+          "description": "The allowed values. Present exactly when kind is enum."
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/constitution.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/constitution.schema.json",
+  "title": "Multi-Agent Pipeline  -  project constitution",
+  "description": "The machine-readable twin of a project's constitution.md: the invariant rules every requirement and task of that project is held to (security, accessibility, architecture, licensing). Written by /multi-agent:analysis to ~/.claude/knowledge/<project>/constitution.json (multi-agent-refs/features/constitution.md), checked by constitution.mjs check, read by spec-consistency-gate.mjs. Each rule carries exactly one source with the research engine's labels: repo (a file in the repository, ref `path` or `path:line`), evidence (a fetched standards document, tracker item or page, ref a URL or id) or inference (reasoning, ref the one-line rationale). An inference-sourced rule is always proposed: only a rule a person or a source stated can bind.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "rules"],
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "project": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The knowledge-store key: the main checkout's directory name, or the analysis name slug for a run with no repository."
+    },
+    "greenfield": {
+      "type": "boolean",
+      "description": "True when no repository was selected (analysis platform `none`): no rule can carry the repo label."
+    },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "category", "text", "source", "status"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^CON-(SEC|A11Y|ARCH|LIC)-[0-9]{2,3}$",
+            "description": "Stable id a requirement or task cites. The middle segment names the category: SEC security, A11Y accessibility, ARCH architecture, LIC licensing."
+          },
+          "category": { "enum": ["security", "accessibility", "architecture", "licensing"] },
+          "text": { "type": "string", "minLength": 1 },
+          "source": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "ref"],
+            "properties": {
+              "label": { "enum": ["evidence", "repo", "inference"] },
+              "ref": { "type": "string", "minLength": 1 }
+            }
+          },
+          "status": {
+            "enum": ["binding", "proposed"],
+            "description": "binding: spec-consistency-gate.mjs fails a requirement or task that waives it. proposed: reported only, until a person adopts it."
+          }
+        },
+        "if": {
+          "properties": { "source": { "properties": { "label": { "const": "inference" } } } }
+        },
+        "then": { "properties": { "status": { "const": "proposed" } } }
+      }
+    }
+  }
+}

package/pipeline/schemas/contract-error.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/contract-error.schema.json",
+  "title": "Contract error",
+  "description": "Every non-2xx body contract-server.mjs sends, on the desktop and the phone routes alike. `error` is a fixed code a client switches on; `message` is for a person and names no path, host or token. `errors` lists schema or rule violations for invalid-body and invalid-request; `supported` lists the majors ?v= accepts for unsupported-version.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "error", "message"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "error": {
+      "enum": [
+        "unauthorized",
+        "forbidden-host",
+        "forbidden-origin",
+        "not-found",
+        "method-not-allowed",
+        "invalid-query",
+        "unsupported-version",
+        "unsupported-media-type",
+        "invalid-body",
+        "invalid-request",
+        "no-launch-shape",
+        "not-waiting",
+        "wrong-question",
+        "wrong-arity",
+        "not-an-option",
+        "state-moved",
+        "unsigned",
+        "unknown-device",
+        "revoked-device",
+        "bad-signature",
+        "stale-request",
+        "replayed",
+        "replay-store-full",
+        "unknown-verb",
+        "forbidden-scope",
+        "launch-disabled",
+        "repo-not-allowed",
+        "internal"
+      ],
+      "x-sensitivity": "none"
+    },
+    "message": { "type": "string", "x-sensitivity": "none" },
+    "errors": { "type": "array", "items": { "type": "string" }, "x-sensitivity": "none" },
+    "supported": { "type": "array", "items": { "type": "integer" }, "x-sensitivity": "none" }
+  }
+}

package/pipeline/schemas/design-check-config.schema.json

@@ -42,6 +42,10 @@
       "additionalProperties": false,
       "description": "Augments design_scenario_inventory, which decides the audit's target set. Only for states no source signal can reveal - everything detectable is detected.",
       "properties": {
+        "targetsFile": {
+          "type": "string",
+          "description": "Path to a JSON target catalog (a bare array, or { version: 1, platform?, description?, targets }) passed to design_scenario_inventory as targets_file. When set, source scanning is skipped and the catalog is the target set; plan, groups, relaunch count and the coverage gate work unchanged. For repos whose state drivers no source signal reveals, such as a debug menu over a stub library."
+        },
         "extraLaunchArgs": {
           "type": "array",
           "items": { "type": "string" },
@@ -57,7 +61,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "Stable target id, e.g. 'config:seatmap-3d'."
+                "description": "Stable target id, e.g. 'config:gallery-3d'."
               },
               "kind": { "type": "string", "description": "Target kind label (default 'config')." },
               "label": { "type": "string" },

package/pipeline/schemas/issues.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/issues.schema.json",
+  "title": "Assigned issues",
+  "description": "What `issues.mjs --json` prints: open items assigned to the current user, Jira and GitHub in one list. No field carries a URL, a host, a person or a path - summaries are scrubbed before they are printed - so every field is x-sensitivity none and --redact changes nothing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "items", "sources"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "items": {
+      "type": "array",
+      "x-sensitivity": "none",
+      "description": "Priority first, then status, then newest.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "summary", "status", "type", "priority", "source"],
+        "properties": {
+          "key": {
+            "type": "string",
+            "pattern": "^([A-Z][A-Z0-9_]*-[0-9]+|[A-Za-z0-9._-]+/[A-Za-z0-9._-]+#[0-9]+)$",
+            "x-sensitivity": "none",
+            "description": "A Jira key, or owner/repo#N for GitHub."
+          },
+          "summary": { "type": "string", "x-sensitivity": "none" },
+          "status": { "type": ["string", "null"], "x-sensitivity": "none" },
+          "type": { "type": ["string", "null"], "x-sensitivity": "none" },
+          "priority": {
+            "type": ["string", "null"],
+            "x-sensitivity": "none",
+            "description": "Jira's priority name. Always null for GitHub, which has none."
+          },
+          "source": { "enum": ["jira", "github"], "x-sensitivity": "none" }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "x-sensitivity": "none",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source", "ok", "count"],
+        "properties": {
+          "source": { "enum": ["jira", "github"] },
+          "ok": { "type": "boolean" },
+          "count": { "type": "integer", "minimum": 0 },
+          "reason": {
+            "enum": ["not-onboarded", "unavailable", "failed"],
+            "description": "Why a source contributed nothing. A fixed code, never the tool's own message."
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/launch-plan.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/launch-plan.schema.json",
+  "title": "Launch plan",
+  "description": "What `launch-request.mjs plan` prints, and POST /v1/launch returns: the command a client runs to start a validated launch request unattended, with launch.json's placeholders filled. Neither carrier runs it. argv is an argument vector for a process spawned without a shell (shell is always false): the input is one element, never a string to be split or interpreted. `verified` repeats launch.json's flag; until it is true the shape is provisional. Under redact every x-sensitivity local field is dropped, leaving the session id a client tracks the run by.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "valid", "verified", "host", "mode", "sessionId", "bin", "shell"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "valid": { "const": true, "x-sensitivity": "none" },
+    "verified": { "type": "boolean", "x-sensitivity": "none" },
+    "host": { "enum": ["claude"], "x-sensitivity": "none" },
+    "mode": { "enum": ["autopilot"], "x-sensitivity": "none" },
+    "sessionId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "x-sensitivity": "none",
+      "description": "Phase 0 records it as sessionId; the runs index carries it, which is how the client finds this run."
+    },
+    "requestFile": {
+      "type": "string",
+      "x-sensitivity": "local",
+      "description": "The request file, mode 0600, named for the session."
+    },
+    "bin": { "type": "string", "x-sensitivity": "none" },
+    "cwd": { "type": "string", "x-sensitivity": "local" },
+    "argv": {
+      "type": "array",
+      "x-sensitivity": "local",
+      "items": { "type": "string" },
+      "description": "Carries the request's input, which is local."
+    },
+    "env": {
+      "type": "object",
+      "x-sensitivity": "local",
+      "additionalProperties": { "type": "string" },
+      "description": "Variables to add to the client's own environment for the launched process."
+    },
+    "shell": { "const": false, "x-sensitivity": "none" }
+  }
+}

package/pipeline/schemas/launch-request.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/launch-request.schema.json",
+  "title": "Launch request",
+  "description": "The file MA_LAUNCH_REQUEST names: what a client asked for before the run started. Phase 0 reads it through `launch-request.mjs resolve` and pre-fills the matching pickers; with the variable unset nothing changes. Answers are data, never instructions: each one is an option id from run-questions.json or a value its `answer.pattern` admits, and anything else rejects the whole request. The file lives on the machine that runs the pipeline, so every field is x-sensitivity local - a client that relays a request elsewhere strips it first.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "input", "mode", "answers"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none",
+      "description": "Major 1. A request for another major is rejected rather than half-understood."
+    },
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "x-sensitivity": "local",
+      "description": "What the run works on. A structured reference - a Jira key (^[A-Z][A-Z0-9]+-[0-9]+$), https://github.com/<owner>/<repo>/issues/<n>, repo#N, #N, or a Jira URL on the configured Jira host - reaches the prompt as it is. Free text is accepted on the desktop channel only (never on /v1/phone/launch): one line of at most 500 printable characters with no quote, backslash, backtick or URL, reaching the prompt as one double-quoted argument. On every channel a newline, a control or format character, a leading '-', a flag-like token, or a first token naming a pipeline op or mode keyword rejects the request; a later word is not held to that rule, because a quoted argument cannot route on it. launch-request.mjs inputErrors is the rule."
+    },
+    "mode": {
+      "enum": ["interactive", "autopilot"],
+      "x-sensitivity": "none",
+      "description": "Whether the run confirms anything. The workspace is a separate answer, and autopilot never runs local."
+    },
+    "answers": {
+      "type": "object",
+      "x-sensitivity": "local",
+      "description": "questionId -> optionId (single-select) or optionId[] (multi-select). Keys come from run-questions.json; an unknown or unanswerable key rejects the request.",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": {
+        "anyOf": [
+          { "type": "string", "minLength": 1, "maxLength": 200 },
+          {
+            "type": "array",
+            "maxItems": 50,
+            "items": { "type": "string", "minLength": 1, "maxLength": 200 }
+          }
+        ]
+      }
+    }
+  }
+}