@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/schemas/launch.json

@@ -0,0 +1,61 @@
+{
+  "contractVersion": "1.1.0",
+  "verified": false,
+  "note": "How a client starts a run without a terminal conversation. The claude argv is launchArgv() and the environment is launchEnv() in scripts/autopilot-runner.mjs; test/launch-contract.test.mjs holds this file to both. The shape awaits a live launch trial, so a client treats it as provisional until verified is true.",
+  "requestFile": {
+    "env": "MA_LAUNCH_REQUEST",
+    "directory": "$MA_AUTOPILOT_ROOT/requests",
+    "directoryDefault": "$HOME/.claude/autopilot/requests",
+    "name": "{requestId}.json",
+    "fileMode": "0600",
+    "schema": "launch-request.schema.json",
+    "lifetime": "Written by the client before launch and removed by it once agent-state.json carries launchRequest; Phase 0 only reads it."
+  },
+  "placeholders": {
+    "input": "the request's input as launch-request.mjs promptArgument renders it: a structured reference (Jira key, GitHub issue URL, repo#N, #N, Jira URL on the configured host) as is, or desktop free text as one double-quoted argument",
+    "sessionId": "a UUID the client chooses; Phase 0 records it as sessionId, which is how the client finds this run's state",
+    "requestFile": "the absolute path of the request file",
+    "settingsFile": "the absolute path of the unattended permission profile install --unattended writes: $HOME/.claude/multi-agent-unattended.settings.json",
+    "repoPath": "the working directory: a configured autopilot repo (config.json repos[].localPath) or one registered with `launch-request.mjs register-repo`, compared by real path",
+    "runLogsRoot": "the log root an unattended run writes its state under: $HOME/.multi-agent-unattended/logs, the one directory outside the worktree the unattended profile's OS sandbox lets a run write (lib/pr-request-location.mjs unattendedLogsRoot)"
+  },
+  "hosts": {
+    "claude": {
+      "supported": true,
+      "bin": "claude",
+      "cwd": "{repoPath}",
+      "modes": {
+        "autopilot": {
+          "argv": [
+            "--bg",
+            "--session-id",
+            "{sessionId}",
+            "--permission-prompts",
+            "none",
+            "--settings",
+            "{settingsFile}",
+            "-p",
+            "/multi-agent {input} autopilot"
+          ],
+          "env": {
+            "MULTI_AGENT_UNATTENDED": "1",
+            "MULTI_AGENT_SESSION_ID": "{sessionId}",
+            "MCP_TOOLKIT_URL_POLICY": "strict",
+            "MCP_TOOLKIT_INDEX_DENY": "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains",
+            "LOGS_ROOT": "{runLogsRoot}",
+            "MA_LAUNCH_REQUEST": "{requestFile}"
+          }
+        }
+      },
+      "note": "Only the unattended shape is declared: a background session with no permission prompts has nobody to answer an interactive run. An interactive request is used by a person who sets MA_LAUNCH_REQUEST in their own terminal before typing /multi-agent."
+    },
+    "copilot": {
+      "supported": false,
+      "note": "The autopilot runner launches only the claude host. No argv is declared for Copilot CLI until one is verified."
+    },
+    "codex": {
+      "supported": false,
+      "note": "The autopilot runner launches only the claude host. No argv is declared for Codex CLI until one is verified."
+    }
+  }
+}

package/pipeline/schemas/launch.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/launch.schema.json",
+  "title": "Launch shape",
+  "description": "Shape of launch.json: per host CLI, the argv template and environment that start a run, and where the launch request file goes. Templates use {placeholder} tokens named in `placeholders`. Every field is x-sensitivity none: the file ships with the package and holds templates, never a machine's values.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "verified", "note", "requestFile", "placeholders", "hosts"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "verified": {
+      "type": "boolean",
+      "x-sensitivity": "none",
+      "description": "false until a live launch trial confirmed the shape on a real host."
+    },
+    "note": { "type": "string", "x-sensitivity": "none" },
+    "requestFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "env",
+        "directory",
+        "directoryDefault",
+        "name",
+        "fileMode",
+        "schema",
+        "lifetime"
+      ],
+      "x-sensitivity": "none",
+      "properties": {
+        "env": { "const": "MA_LAUNCH_REQUEST" },
+        "directory": { "type": "string" },
+        "directoryDefault": { "type": "string" },
+        "name": { "type": "string" },
+        "fileMode": { "type": "string", "pattern": "^0[0-7]{3}$" },
+        "schema": { "type": "string" },
+        "lifetime": { "type": "string" }
+      }
+    },
+    "placeholders": {
+      "type": "object",
+      "x-sensitivity": "none",
+      "additionalProperties": { "type": "string" }
+    },
+    "hosts": {
+      "type": "object",
+      "x-sensitivity": "none",
+      "required": ["claude"],
+      "additionalProperties": { "$ref": "#/$defs/host" }
+    }
+  },
+  "$defs": {
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["supported", "note"],
+      "properties": {
+        "supported": { "type": "boolean" },
+        "bin": { "type": "string" },
+        "cwd": { "type": "string" },
+        "note": { "type": "string" },
+        "modes": {
+          "type": "object",
+          "propertyNames": { "enum": ["interactive", "autopilot"] },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["argv", "env"],
+            "properties": {
+              "argv": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+              "env": { "type": "object", "additionalProperties": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "if": { "properties": { "supported": { "const": true } } },
+      "then": { "required": ["bin", "cwd", "modes"] }
+    }
+  }
+}

package/pipeline/schemas/phases.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.json",
-  "description": "The phase contract, in one place. Before this file the phase list existed as eight independent copies - gen-mode-dispatch.mjs, phases.md twice, phase-tracker.sh, render-work-summary.sh, agent-state.schema.json, token-budget.json, docs/architecture.md - and none derived from another, so a renumbering meant eight hand edits and the count in prose was guarded by nothing. smoke-phase-contract.sh reads this file and holds every other copy to it. Adding or merging a phase means editing here; everywhere else either reads this or is checked against it. Ceilings are re-measured after the docs merge (Faz F), not summed from the old ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement, so summing would ship a stale ceiling by construction.",
+  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
   "contractVersion": "2.0.0",
   "phaseSchema": 2,
   "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
@@ -78,6 +78,6 @@
   "thresholds": {
     "waitingFromPhase": 4,
     "mcpAllowedThroughPhase": 1,
-    "note": "Phase numbers other code compares against, named here so a renumbering moves them with the contract. waitingFromPhase: runs-index.mjs groups a run as 'waiting on you' from Commit on. mcpAllowedThroughPhase: Figma MCP is reachable only through Plan; smoke-no-mcp-in-dev-phases.sh fails any recorded call at a higher phase. Its literal threshold is unchanged from the eight-phase contract on purpose - Analysis was 1 and is now inside Plan, also 1, so the permitted set {0,1} is identical."
+    "note": "Phase numbers other code compares against, named here so a renumbering moves them with the contract. waitingFromPhase: runs-index.mjs groups a run as 'waiting on you' from Commit on. mcpAllowedThroughPhase: Figma MCP is reachable only through Plan; smoke-no-mcp-in-dev-phases.sh flags any recorded Figma call at a higher phase. Analysis runs inside Plan, so the permitted set is {0,1}."
   }
 }

package/pipeline/schemas/phases.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.schema.json",
+  "title": "Phase contract",
+  "description": "phases.json: the phase set, the modes that run a subset of it and the phase numbers other code compares against.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "phaseSchema", "phases", "totalMaxTokens", "modes", "thresholds"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "$id": { "type": "string" },
+    "description": { "type": "string" },
+    "contractVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "phaseSchema": { "type": "integer", "minimum": 1 },
+    "phaseSchemaNote": { "type": "string" },
+    "legacyPhaseNames": {
+      "type": "object",
+      "properties": { "note": { "type": "string" } },
+      "patternProperties": { "^[0-9]+$": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "doc", "maxTokens"],
+        "properties": {
+          "id": { "type": "integer", "minimum": 0 },
+          "name": { "type": "string", "minLength": 1 },
+          "doc": { "type": "string", "pattern": "^phase-[0-9]+-[a-z-]+\\.md$" },
+          "maxTokens": { "type": "integer", "minimum": 1 },
+          "was": { "type": "array", "items": { "type": "integer", "minimum": 0 } }
+        }
+      }
+    },
+    "totalMaxTokens": { "type": "integer", "minimum": 1 },
+    "modes": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["phases", "autopilot"],
+        "properties": {
+          "phases": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "integer", "minimum": 0 },
+            "uniqueItems": true
+          },
+          "autopilot": { "type": "boolean" }
+        }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["waitingFromPhase", "mcpAllowedThroughPhase"],
+      "properties": {
+        "waitingFromPhase": { "type": "integer", "minimum": 0 },
+        "mcpAllowedThroughPhase": { "type": "integer", "minimum": 0 },
+        "note": { "type": "string" }
+      }
+    }
+  }
+}

package/pipeline/schemas/phone-devices.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/phone-devices.schema.json",
+  "title": "Phone device registry",
+  "description": "<autopilot root>/phone/devices.json, mode 0600 in a 0700 directory, written only by phone-devices.mjs on this machine. Public keys only: a private key never reaches this file. contract-server.mjs reads it on every phone request, so a revocation or a launch toggle applies to the next request, and a file other users can write is treated as empty. A revoked device stays listed so its id is never reissued and the audit log still resolves.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "launchEnabled", "devices"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0", "x-sensitivity": "none" },
+    "launchEnabled": {
+      "type": "boolean",
+      "description": "POST /v1/phone/launch is refused (launch-disabled) unless this is true, whatever scopes a device holds. Off by default; `phone-devices.mjs launch on|off` sets it.",
+      "x-sensitivity": "none"
+    },
+    "devices": {
+      "type": "array",
+      "maxItems": 256,
+      "x-sensitivity": "none",
+      "items": { "$ref": "#/$defs/device" }
+    }
+  },
+  "$defs": {
+    "device": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "publicKey", "scopes", "addedAt", "revokedAt"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^d-[0-9a-f]{16}$", "x-sensitivity": "none" },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "A label for a person reading `list`; never used for a decision.",
+          "x-sensitivity": "local"
+        },
+        "publicKey": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$",
+          "description": "The raw 32-byte Ed25519 public key, unpadded base64url.",
+          "x-sensitivity": "local"
+        },
+        "scopes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "enum": ["read", "answer", "launch"] },
+          "description": "read: GET /v1/phone/runs and /v1/phone/runs/{id}. answer: POST /v1/phone/runs/{id}/answer. launch: POST /v1/phone/launch, and only while launchEnabled is true.",
+          "x-sensitivity": "none"
+        },
+        "addedAt": { "type": "string", "format": "date-time", "x-sensitivity": "none" },
+        "revokedAt": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "Set by `phone-devices.mjs revoke`; a revoked device is refused on its next request.",
+          "x-sensitivity": "none"
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/phone-signed-request.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phone-signed-request.schema.json",
+  "title": "Phone signed request",
+  "description": "What a phone signs for every request under /v1/phone/ (features/phone-api.md). The device sends deviceId, timestamp, nonce and signature as the headers X-MA-Device, X-MA-Timestamp, X-MA-Nonce and X-MA-Signature; the server rebuilds the other fields from the request itself. The signed text is the seven fields `version`, `method`, `target`, `bodySha256`, `deviceId`, `timestamp`, `nonce`, in that order, joined by a single \\n with no trailing newline, UTF-8, signed with the device's Ed25519 private key. No field may contain a newline, which is what makes the join unambiguous. The server refuses a timestamp more than 60 seconds behind its clock, more than 5 seconds ahead of it or earlier than its own start, and a nonce it has seen inside the window (manifest.json phone.signature windowSeconds and futureSkewSeconds).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "method",
+    "target",
+    "bodySha256",
+    "deviceId",
+    "timestamp",
+    "nonce",
+    "signature"
+  ],
+  "properties": {
+    "version": {
+      "const": "MA-PHONE-SIG-1",
+      "description": "The scheme; a different version is a different signed text.",
+      "x-sensitivity": "none"
+    },
+    "method": {
+      "type": "string",
+      "pattern": "^[A-Z]{1,10}$",
+      "description": "The HTTP method as sent.",
+      "x-sensitivity": "none"
+    },
+    "target": {
+      "type": "string",
+      "pattern": "^/[\\x21-\\x7e]{0,4095}$",
+      "description": "The request target exactly as sent: path plus query string, percent-encoding untouched. A forwarder must pass it unchanged.",
+      "x-sensitivity": "none"
+    },
+    "bodySha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Lowercase hex SHA-256 of the raw body bytes; an empty body hashes to e3b0c442...b855.",
+      "x-sensitivity": "none"
+    },
+    "deviceId": {
+      "type": "string",
+      "pattern": "^d-[0-9a-f]{16}$",
+      "description": "The id phone-devices.mjs add printed at enrolment. Header X-MA-Device.",
+      "x-sensitivity": "none"
+    },
+    "timestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{1,12}$",
+      "description": "Unix seconds, as decimal digits. Header X-MA-Timestamp.",
+      "x-sensitivity": "none"
+    },
+    "nonce": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,64}$",
+      "description": "Fresh random base64url per request. Header X-MA-Nonce.",
+      "x-sensitivity": "none"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{86}$",
+      "description": "Unpadded base64url of the 64-byte Ed25519 signature over the signed text. Header X-MA-Signature. Never logged.",
+      "x-sensitivity": "local"
+    }
+  }
+}

package/pipeline/schemas/plan-critique.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/plan-critique.schema.json",
+  "title": "Multi-Agent Pipeline  -  plan critique (one round)",
+  "description": "The plan critic's objections to a Phase 1 plan and the planner's one reply to each, in one file: <worktree>/.pipeline/plan-critique.json (multi-agent-refs/features/plan-critic.md). The plan-critic persona writes version, round and objections[]; the planner adds replies[]. plan-critique-gate.mjs checks this shape without a dependency, resolves every anchor, and judges by constitution rule id. There is exactly one round: round is always 1, each objection gets exactly one reply, and a critique the gate has already judged for the run cannot be replaced. An anchor is file (ref `path:line`, optional quote, resolved like verify-citations.mjs in the working tree), plan (ref a task id of the plan), analysis (ref a requirement id the analysis defines, or text of one of its headings) or inference (ref the one-line reasoning, never checkable). An objection none of whose anchors resolves is labelled inference.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "round", "objections", "replies"],
+  "$defs": {
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "ref"],
+      "properties": {
+        "kind": { "enum": ["file", "plan", "analysis", "inference"] },
+        "ref": { "type": "string", "minLength": 1 },
+        "quote": {
+          "type": "string",
+          "minLength": 1,
+          "description": "file anchors only: text that must appear on the cited line, whitespace collapsed."
+        }
+      }
+    }
+  },
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "round": {
+      "type": "integer",
+      "const": 1,
+      "description": "Always 1. A second critique round is refused, not scored."
+    },
+    "critic": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "persona": { "type": "string", "minLength": 1 },
+        "rung": { "type": "string", "minLength": 1 }
+      },
+      "description": "Who wrote the objections: the persona and the model rung model-dispatch.sh returned."
+    },
+    "objections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "lens", "claim", "evidence"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^OBJ-[0-9]{2,3}$" },
+          "lens": {
+            "enum": ["scope", "feasibility", "security", "alternative"],
+            "description": "scope: the plan does more or less than the analysis asks. feasibility: a step cannot work as planned. security: a step opens a hole. alternative: a cheaper plan reaches the same result."
+          },
+          "claim": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the plan will fail, in one or two sentences."
+          },
+          "rule": {
+            "type": "string",
+            "pattern": "^CON-(SEC|A11Y|ARCH|LIC)-[0-9]{2,3}$",
+            "description": "The constitution rule the plan breaks, when there is one. Only an objection citing a binding rule can block."
+          },
+          "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/anchor" } }
+        }
+      }
+    },
+    "replies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["objection", "action"],
+        "properties": {
+          "objection": { "type": "string", "pattern": "^OBJ-[0-9]{2,3}$" },
+          "action": {
+            "enum": ["accept", "rebut"],
+            "description": "accept: the plan was revised; revision says how and a plan anchor names the task. rebut: the objection does not hold, shown by evidence."
+          },
+          "revision": { "type": "string", "minLength": 1 },
+          "note": { "type": "string" },
+          "evidence": { "type": "array", "items": { "$ref": "#/$defs/anchor" } }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "action": { "const": "accept" } } },
+            "then": { "required": ["revision"] }
+          },
+          {
+            "if": { "properties": { "action": { "const": "rebut" } } },
+            "then": {
+              "required": ["evidence"],
+              "properties": { "evidence": { "minItems": 1 } }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

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

@@ -2,24 +2,24 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://example.com/pipeline/plan-todos.schema.json",
   "title": "Plan Todo List",
-  "description": "Structured representation of Phase 2's plan. Persists into agent-state under `.plan.todos[]` and survives across phases. Phase 3 (Dev) iterates step-by-step; Phase 4 (Review) verifies completed steps against criteria; Phase 5 (Report) renders a per-step rollup. The plan is broken into a live, structured Todo list for step-by-step tracking across phases.",
+  "description": "Structured representation of the Phase 1 plan. Persists into agent-state under `.plan.todos[]` and survives across phases. Phase 2 (Dev) iterates step-by-step; Phase 3 (Review) verifies completed steps against criteria; Phase 5 (Report) renders a per-step rollup. The plan is broken into a live, structured Todo list for step-by-step tracking across phases.",
   "type": "object",
   "additionalProperties": false,
   "required": ["title", "todos"],
   "properties": {
     "title": {
       "type": "string",
-      "description": "One-line plan summary, mirrors the task title. Surfaced in Phase 3 progress lines and Phase 5 report."
+      "description": "One-line plan summary, mirrors the task title. Surfaced in Phase 2 progress lines and the Phase 5 report."
     },
     "createdAt": {
       "type": "string",
       "format": "date-time",
-      "description": "ISO-8601 timestamp Phase 2 emitted this plan. Used by Phase 5 for elapsed-time math."
+      "description": "ISO-8601 timestamp Phase 1 emitted this plan. Used by Phase 5 for elapsed-time math."
     },
     "todos": {
       "type": "array",
       "minItems": 1,
-      "description": "Ordered list of steps. Phase 3 picks them in `deps`-respecting order  -  see plan-todos.sh next.",
+      "description": "Ordered list of steps. Phase 2 picks them in `deps`-respecting order  -  see plan-todos.sh next.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -32,7 +32,7 @@
           },
           "task": {
             "type": "string",
-            "description": "Imperative one-liner  -  what gets done. Avoid 'investigate X' or 'consider Y'  -  Phase 3 needs concrete actions."
+            "description": "Imperative one-liner  -  what gets done. Avoid 'investigate X' or 'consider Y'  -  Phase 2 needs concrete actions."
           },
           "status": {
             "type": "string",
@@ -56,12 +56,12 @@
           "sourceTag": {
             "type": "string",
             "enum": ["Reuse", "Add new", "Modify"],
-            "description": "Carried from the analysis Section 14 row this step came from (Locked 16). Phase 3 reads it as an instruction: a Reuse step binds the existing file and must not write a new one. Phase 4 checks the diff against it. Absent when the step did not originate from a Files-to-Add row."
+            "description": "Carried from the analysis Section 14 row this step came from (Locked 16). Phase 2 reads it as an instruction: a Reuse step binds the existing file and must not write a new one. Phase 3 checks the diff against it. Absent when the step did not originate from a Files-to-Add row."
           },
           "estimatedMinutes": {
             "type": "integer",
             "minimum": 1,
-            "description": "Optional Phase 2 estimate for the step. Phase 5 compares against actual duration."
+            "description": "Optional Phase 1 estimate for the step. Phase 5 compares against actual duration."
           }
         }
       }

package/pipeline/schemas/planning-output.schema.json

@@ -45,6 +45,11 @@
             "type": "array",
             "items": { "type": "string" },
             "description": "Bullet list of testable conditions that prove the task is done."
+          },
+          "requirements": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Analysis requirement ids this task implements or tests (BR-<slug>-NN, FG-NN). spec-consistency-gate.mjs reads them, with any id in the title or acceptance criteria, to check that every requirement has a task and a test and that every task traces to a requirement."
           }
         }
       }

package/pipeline/schemas/pr-request.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/pr-request.schema.json",
+  "title": "PR request",
+  "description": "What an unattended Phase 4 leaves instead of pushing and opening a PR. Written only through `scripts/pr-request.mjs write`, at <autopilot root>/pr-requests/<session id>.json (lib/pr-request-location.mjs). The autopilot runner reads it, verifies it against the branch it can see, and is the only process that pushes and creates the PR. Every field is data: the runner passes title and body to the forge as text and never executes or interprets them. The body has passed the outbound gate before the file was written and is scanned again by `validate`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["branch", "base", "title", "body", "draft", "repo"],
+  "properties": {
+    "branch": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^[A-Za-z0-9._/-]+$",
+      "description": "The local branch holding the run's commits. Never a protected branch (main, master, develop) and never the base; `validate` enforces both."
+    },
+    "base": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^[A-Za-z0-9._/-]+$",
+      "description": "The branch the PR targets."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "PR title in the repo's commit convention."
+    },
+    "body": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 65536,
+      "description": "PR description in Markdown, the section set of channels/pr.md. No auto-close keywords (Closes/Fixes/Resolves #N)."
+    },
+    "draft": {
+      "const": true,
+      "description": "Always true. An unattended PR is opened as a draft so a person decides when it is ready."
+    },
+    "repo": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
+      "description": "owner/name of the repository the PR is opened on."
+    }
+  }
+}