triad-plus 1.0.0

package/docs/getting-started.md

@@ -0,0 +1,33 @@
+# Getting started
+
+Triad+ keeps project-control records outside product repositories. Choose an empty
+directory for that workspace and a runtime available on your machine.
+
+```bash
+npx triad-plus init --host codex --control "$PWD/triad-control" --global
+npx triad-plus doctor --host codex --control "$PWD/triad-control"
+```
+
+The interactive setup asks for language, owner address, neutral role names,
+personas, models, and whether optional Evaluator+ is enabled. It writes only
+after you type `install`.
+
+For non-interactive setup, pass a reviewed team file:
+
+```bash
+npx triad-plus init --host opencode --control "$PWD/triad-control" --team-config ./team.json
+```
+
+Open `triad-control` in the selected host and invoke its native Triad entry
+point with an absolute PRD path. The Orchestrator snapshots the PRD, asks only
+for missing measurable facts, and shows feature cards before implementation.
+
+For the first run, use a small PRD with one observable acceptance criterion and
+one deterministic command such as a focused unit test. The expected path is:
+
+```text
+Orchestrator → Developer → verifier evidence → Reviewer → approved | rework | blocked
+```
+
+The host agent governs the conversation. Triad+ does not start product services
+or demonstrations unless you explicitly request them.

package/docs/npx-installation.md

@@ -0,0 +1,44 @@
+# Install Triad+
+
+Triad+ installs a project-control workspace, not application code. Keep it
+outside product repositories whenever possible.
+
+```bash
+npx triad-plus
+```
+
+The interactive setup selects a host, optional user-level command, language,
+owner address, role display names/personas, models, and whether the optional
+Evaluator+ is enabled. It changes files only after `install` is typed.
+
+For repeatable setup:
+
+```bash
+npx triad-plus init --host codex --control /path/to/project-control --global
+npx triad-plus doctor --host codex --control /path/to/project-control
+```
+
+Supported hosts: `codex`, `opencode`, `claude-code`, `antigravity`, `hermes`.
+Use `--global` to install a host-level entry point where desired. The installer
+refuses overwrites. If the control path is recognizably a product Git repository,
+it stops unless `--allow-product-repo` is explicitly supplied after review.
+
+The saved `.triad-plus/team.json` separates stable role IDs from display names,
+personas, models, and supported effort/options. Existing schema-version-1 team
+files remain valid. Core roles are always enabled; Evaluator+ is enabled only
+when `roles.evaluator.enabled` is `true`.
+
+| Role | Responsibility |
+| --- | --- |
+| Orchestrator | Maintains goal/context and decides the next step. |
+| Developer | Changes the artifact to meet the declared card. |
+| Reviewer | Finds defects and returns approved, rework, or blocked. |
+| Evaluator+ | Optionally and freshly judges an approved result after the run. |
+
+Open the control workspace and invoke the host-native command with an absolute
+PRD path. The Orchestrator presents feature cards before implementation, then
+delegates normal development and review. Use the optional evaluator form exposed
+by the host only after Triad is approved: invoke the native Triad command with
+`--evaluator` (for example `/triad --evaluator`) and the Orchestrator will either
+run the configured Evaluator+ or state that it is disabled. Users never create
+evaluation packets, report paths, or evidence directories manually.

package/docs/opencode-replication.md

@@ -0,0 +1,8 @@
+# OpenCode adapter
+
+Install with `npx triad-plus init --host opencode --control <path>`. Open the
+control workspace and run `/triad <absolute-prd-path>`. Project-local agent and
+command assets carry the configured role models where OpenCode supports them.
+
+Verification uses explicit Orchestrator dispatch. Evaluator+ is optional and may
+be invoked only after a Reviewer-approved result; it cannot reopen that run.

package/docs/operating-guide.it.md

@@ -0,0 +1,49 @@
+# Guida operativa Triad+
+
+Triad+ è un metodo operativo per un coding-agent host. Non avvia daemon,
+scheduler, database di workflow o una macchina a stati autonoma.
+
+## Il metodo
+
+```text
+ready → in_progress → verifying → in_review → approved
+                                      ├── rework → in_progress
+                                      └── blocked
+```
+
+L’Orchestrator decide il prossimo passo e le escalation. Il Developer esegue un
+tentativo delimitato. Il Reviewer decide `approved`, `rework` oppure `blocked`.
+
+Prima del lavoro l’Orchestrator congela il PRD, dichiara card misurabili,
+repository/worktree/branch e quality gate deterministici. Mostra il piano al
+proprietario, poi delega normalmente sviluppo e review.
+
+Dopo il completamento del Developer avviene la verifica: tramite hook validato
+quando disponibile, altrimenti con dispatch esplicito dell’Orchestrator. Il
+verifier esegue solo comandi `control-plane` dichiarati. L’evidence atomica lega
+assignment ID/hash, run, branch del worktree, fingerprint del candidato, hash di
+PRD/card e definizione dei gate. “I test passano” detto dall’agente è una claim;
+l’output del verifier è evidence derivata dall’ambiente. Evidence fallita o
+invalida non può essere trattata come pass.
+
+Il Reviewer riceve card, diff, report Developer, rilievi precedenti ed evidence.
+`rework` torna al Developer con una correzione delimitata; `blocked` richiede
+all’Orchestrator di escalare la decisione. Le push normali possono essere autonome
+dopo i goal dichiarati. Avvio e stop della demo restano del proprietario.
+
+## Evaluator+
+
+Evaluator+ è opzionale e fuori dal loop produttivo. Dopo `approved`, osserva solo
+goal, target di accettazione, candidato finale ed evidence del verifier. Produce
+`PASS`, `FAIL` oppure `INDETERMINATE`. Un `FAIL` non modifica la run chiusa e non
+avvia rework. Vedi [Evaluator+](evaluator-plus.md).
+
+## Decisioni umane e record
+
+Triad+ interpella il proprietario solo per criteri di successo mancanti, cambi di
+scope/policy materiali, ambiguità non risolvibili, fallimenti ripetuti o demo
+richieste. Conserva PRD immutabile, card, assignment, evidence, report di review,
+eventuali report Evaluator+ e handoff in un workspace di controllo separato. Non
+inserire token o segreti. Gli hook sono un’ottimizzazione, non autorità: il
+dispatch esplicito della verification resta sempre disponibile. Vedi la
+[matrice di compatibilità](compatibility.md).

package/docs/operating-guide.md

@@ -0,0 +1,49 @@
+# Triad+ operating guide
+
+Triad+ is an operating method for a coding-agent host. It does not run a daemon,
+scheduler, workflow database, or autonomous state controller.
+
+## The method
+
+```text
+ready → in_progress → verifying → in_review → approved
+                                      ├── rework → in_progress
+                                      └── blocked
+```
+
+The Orchestrator owns the next step and escalation. The Developer owns a bounded
+implementation attempt. The Reviewer owns its `approved`, `rework`, or `blocked`
+verdict.
+
+Before work, the Orchestrator snapshots the PRD, declares measurable feature
+cards, target repositories/worktrees/branches, and deterministic quality gates.
+It shows the plan to the owner, then delegates ordinary development and review.
+
+After Developer completion, verification happens through a validated host hook
+when available, or explicit Orchestrator dispatch. The verifier executes only
+declared `control-plane` commands. Atomic evidence binds assignment ID/hash, run,
+worktree branch, candidate fingerprint, PRD/card hashes, and gate definition
+hash. A developer saying tests pass is a claim; verifier output is
+environment-derived evidence. Failed or invalid evidence cannot be treated as a
+pass.
+
+The Reviewer sees the card, diff, Developer report, previous findings, and
+verifier evidence. `rework` returns a bounded finding to Developer; `blocked`
+asks the Orchestrator to escalate the stated decision. Normal pushes may happen
+autonomously once declared goals pass. Demo start and stop remain owner-controlled.
+
+## Evaluator+
+
+Evaluator+ is optional and outside the production loop. After `approved`, it
+inspects only the goal, acceptance target, final candidate, and verifier evidence.
+Its report is `PASS`, `FAIL`, or `INDETERMINATE`. A failure does not modify the
+closed run or start repair. See [Evaluator+](evaluator-plus.md).
+
+## Human decisions and records
+
+Triad+ asks the owner only for missing success criteria, material scope/policy
+changes, unresolved ambiguity, repeated failure, or a requested demo. Keep the
+immutable PRD, cards, assignments, evidence, review reports, optional Evaluator+
+reports, and handoff in a separate project-control workspace. Never place tokens
+or secrets there. Hooks are an optimization, not authority; explicit verification
+is always the fallback. See the [compatibility matrix](compatibility.md).

package/docs/runtimes.md

@@ -0,0 +1,24 @@
+# Runtime adapters
+
+Every adapter installs the same role skills and verifier runtime, while retaining
+host-specific entry points and configuration behavior.
+
+| Runtime | Prerequisite | Entry point | Verification | Hook limitation |
+| --- | --- | --- | --- | --- |
+| Codex | Codex CLI | `/prompts:triad` | Explicit dispatch; async hook when validated | Hook is optional and requires trusted configuration. |
+| Claude Code | Claude Code CLI | `/triad` | Explicit dispatch; hook when validated | Hook is optional and requires trusted configuration. |
+| OpenCode | OpenCode | `/triad` | Explicit dispatch | No Triad lifecycle hook. |
+| Antigravity | Antigravity | `/triad` | Explicit dispatch | No Triad lifecycle hook. |
+| Hermes Agent | Hermes Agent | `/triad` | Explicit dispatch | No Triad lifecycle hook. |
+
+Install with `npx triad-plus init --host <runtime> --control <path>`; use
+`--global` when you want host-level command assets. `doctor` reports the runtime
+binary, adapter assets, verifier, team file, and optional Evaluator+ state.
+
+Hermes installs user skills into the active Hermes profile. Its role invocations
+must bind terminal operations to the declared worktree; this is handled by its
+adapter instructions. It is supported, not experimental.
+
+See the concise host guides for [Codex](codex-replication.md),
+[Claude Code](claude-code-replication.md), [OpenCode](opencode-replication.md),
+and [Antigravity](antigravity-replication.md).

package/docs/troubleshooting.md

@@ -0,0 +1,22 @@
+# Troubleshooting
+
+Run doctor first:
+
+```bash
+npx triad-plus doctor --host <runtime> --control /path/to/triad-control
+```
+
+`not installed` means the selected adapter assets are absent from that control
+workspace. `not installed or version unavailable` for a host means its binary is
+not on PATH or otherwise cannot answer `--version`. Re-run the appropriate host
+installer or fix the host environment; Triad+ does not require every runtime to
+be present.
+
+If a hook is unavailable, use explicit verification dispatch. Hooks are never a
+requirement for a normal Triad run.
+
+If a verifier result is `invalid_context`, compare the assignment, PRD/card/gate
+baselines, worktree, branch, and candidate. Do not treat it as a passing test.
+
+If Evaluator+ is unavailable, check `roles.evaluator.enabled` in the team file.
+An Evaluator+ failure is post-run information, not an automatic repair request.

package/docs/verification.md

@@ -0,0 +1,17 @@
+# Verification and evidence
+
+An agent-reported claim is not the same as verification evidence. A Developer can
+report the commands it ran; `triad-verify` independently observes declared
+required `control-plane` gates and writes atomic evidence.
+
+Before gates run, the verifier validates the active assignment, PRD/card/gate
+hashes, worktree, expected branch, and candidate fingerprint. It records the
+assignment ID/hash and run ID, executes deterministic commands with a bounded
+timeout, and invalidates evidence if the candidate changes while gates run.
+
+Only `control-plane` gate executors are supported in v1. A required unsupported
+executor fails closed. Verifier evidence informs the Reviewer and Orchestrator;
+it does not itself approve, rework, or transition a run.
+
+Evidence files and logs are diagnostics. Users normally need only the
+Orchestrator's summary and the Reviewer verdict.

package/integrations/claude-code/README.md

@@ -0,0 +1,25 @@
+# Triad Claude Code hook adapter
+
+Claude Code exposes `SubagentStop` with the developer's `agent_id` and
+`agent_type`. The optional command hook in `hooks.json` filters exactly
+`triad-developer` and invokes the Node verifier. It is a synchronous hook
+dispatch: it writes evidence but never owns a Triad state transition.
+
+The file is a configuration fragment, not a settings file to copy blindly.
+Replace `<TRIAD_RUNTIME>` and `<TRIAD_CONTROL_ROOT>` with canonical absolute
+paths in the actual Claude settings syntax. Confirm its presence with `/hooks`
+and validate agent configuration with `claude plugin validate .claude/agents`
+where the installed CLI supports it.
+
+With `dispatch_mode: auto`, run:
+
+```bash
+node .triad-runtime/triad-runtime-capabilities.mjs \
+  --host claude-code \
+  --hook-config /absolute/path/to/installed-claude-settings.json
+```
+
+An installed `SubagentStop` hook selects `hook_dispatch`. If Claude Code or its
+hook is absent, Triad selects `explicit_dispatch`: the orchestrator runs the
+same verifier after developer completion. Neither mode permits developer claims
+to substitute for verification evidence.

package/integrations/claude-code/hooks.json

@@ -0,0 +1,17 @@
+{
+  "purpose": "Triad verification dispatch only; this hook writes evidence and never changes card state.",
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "^triad-developer$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node <TRIAD_RUNTIME>/triad-verify.mjs --project <TRIAD_CONTROL_ROOT>",
+            "timeout": 900
+          }
+        ]
+      }
+    ]
+  }
+}

package/integrations/codex/README.md

@@ -0,0 +1,61 @@
+# Triad Codex hook adapter
+
+This adapter is for Codex CLI 0.148.0 or newer. It dispatches the Node
+verification runner when a subagent whose type is exactly `triad_developer`
+stops. It is deliberately an asynchronous command hook: it writes immutable
+evidence and has no authority to approve, reject, or transition a feature card.
+
+## Install only after verifying the local Codex schema
+
+The included `hooks.json` is a versioned configuration fragment, not a global
+configuration file to copy blindly. Replace these placeholders with canonical
+absolute paths in the configuration syntax accepted by the installed CLI:
+
+- `<TRIAD_RUNTIME>`: the cloned repository's `runtime` directory;
+- `<TRIAD_CONTROL_ROOT>`: the project-control repository containing `.loop/`.
+
+Before enabling it, verify all of the following:
+
+1. `codex --version` is at least `0.148.0`.
+2. The local CLI accepts the `SubagentStop` async command-hook schema.
+3. The project-local hook source is trusted by the Codex installation.
+4. Developer assignments use `agent_type: triad_developer` and are written
+   before the subagent starts.
+5. Gate commands are in the hashed, trusted `.loop/quality-gates.yaml`.
+
+Do not use this fragment for `mcp_tool` execution. MCP hooks are synchronous and
+optional; long verification remains in the async command runner. A missing,
+aborted, or unsupported hook must be detected by the orchestrator watchdog and
+recorded as `verification_hook_missing`, `developer_aborted`, or
+`verification_timeout`; it must never silently create a passing result.
+
+## Direct, auditable fallback
+
+Until the lifecycle hook is supported and verified, dispatch the same runner
+explicitly after developer completion:
+
+```bash
+node /absolute/path/to/triad-plus-engineering-loop/runtime/triad-verify.mjs \
+  --project /absolute/path/to/project-control < hook-payload.json
+```
+
+The JSON payload needs an `agent_id` matching an active assignment under
+`.loop/runtime/assignments/`. The runner resolves all semantic data from that
+assignment and emits only structured evidence. The orchestrator still validates
+the evidence against the active candidate before changing state.
+
+## Let Triad choose the route
+
+Do not select this route by memory. Keep
+`project.control_plane.dispatch_mode: auto` and run:
+
+```bash
+node /absolute/path/to/triad-plus-engineering-loop/runtime/triad-runtime-capabilities.mjs \
+  --hook-config /absolute/path/to/installed-triad-hooks.json
+```
+
+Store the JSON output at `.loop/runtime/capabilities.json`. A CLI below 0.148,
+an uninstalled hook, or a configuration with placeholders selects
+`explicit_dispatch`; a supported, configured hook selects `async_hook`. The
+orchestrator follows that snapshot and re-detects only before a new assignment or
+on resume after runtime configuration changes.

package/integrations/codex/hooks.json

@@ -0,0 +1,20 @@
+{
+  "minimum_codex_cli_version": "0.148.0",
+  "purpose": "Triad external verification dispatch only; this hook never changes card state.",
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "^triad_developer$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node <TRIAD_RUNTIME>/triad-verify.mjs --project <TRIAD_CONTROL_ROOT>",
+            "async": true,
+            "timeout": 900,
+            "statusMessage": "Running Triad verification"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "triad-plus",
+  "version": "1.0.0",
+  "description": "A lightweight, evidence-backed engineering loop for coding agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "triad-plus": "bin/triad-plus.js"
+  },
+  "files": [
+    "bin/",
+    "adapters/",
+    "integrations/",
+    "runtime/",
+    "schemas/",
+    "skills/",
+    "docs/",
+    "assets/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node tests/runtime-forward-test.mjs && node tests/cli-install-test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/delbono-smeup/triad-plus-engineering-loop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/delbono-smeup/triad-plus-engineering-loop/issues"
+  },
+  "homepage": "https://github.com/delbono-smeup/triad-plus-engineering-loop#readme",
+  "keywords": [
+    "agent-skills",
+    "codex",
+    "claude-code",
+    "opencode",
+    "antigravity",
+    "engineering-loop",
+    "code-review",
+    "verification"
+  ]
+}

package/runtime/legacy-adapters.json

@@ -0,0 +1,17 @@
+{
+  "codex": {
+    "schema_version": 1,
+    "id": "codex",
+    "binary": "codex",
+    "lifecycle": { "kind": "SubagentStop", "agent_type": "triad_developer", "requires_async": true, "minimum_version": "0.148.0" }
+  },
+  "opencode": { "schema_version": 1, "id": "opencode", "binary": "opencode", "lifecycle": null },
+  "claude-code": {
+    "schema_version": 1,
+    "id": "claude-code",
+    "binary": "claude",
+    "lifecycle": { "kind": "SubagentStop", "agent_type": "triad-developer", "requires_async": false }
+  },
+  "antigravity": { "schema_version": 1, "id": "antigravity", "binary": "agy", "lifecycle": null },
+  "hermes": { "schema_version": 1, "id": "hermes", "binary": "hermes", "lifecycle": null }
+}

package/runtime/lib/evidence.mjs

@@ -0,0 +1,31 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const TOKEN_PATTERN = /(?:api[_-]?key|token|secret|password|authorization)\s*(?:=|:|\s)\s*(?:Bearer\s+)?[^\s'"`]{8,}/gi;
+const MAX_LOG_BYTES = 64 * 1024;
+
+export function redactAndCap(value) {
+  const text = String(value ?? "").replace(TOKEN_PATTERN, "[REDACTED]");
+  const bytes = Buffer.from(text);
+  if (bytes.length <= MAX_LOG_BYTES) return { text, truncated: false };
+  return {
+    text: bytes.subarray(0, MAX_LOG_BYTES).toString("utf8") + "\n[TRUNCATED]",
+    truncated: true,
+  };
+}
+
+export async function writeLog(logDirectory, gateId, stream, value) {
+  await mkdir(logDirectory, { recursive: true });
+  const safeId = gateId.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const relative = path.join("logs", `${safeId}.${stream}.log`);
+  const result = redactAndCap(value);
+  await writeFile(path.join(path.dirname(logDirectory), relative), result.text, "utf8");
+  return { ref: relative, truncated: result.truncated };
+}
+
+export async function writeAtomicJson(targetPath, value) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  const temporaryPath = `${targetPath}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await rename(temporaryPath, targetPath);
+}

package/runtime/lib/fingerprint.mjs

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { runProcess } from "./process.mjs";
+
+const SENSITIVE_PATH = /(^|\/)(?:\.env(?:\..*)?|.*\.pem|.*\.key|credentials(?:\..*)?)$/i;
+const IGNORED_PATH = /(^|\/)(?:node_modules|\.git|dist|build|coverage)(\/|$)/;
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function parseLines(value) {
+  return value.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+async function gitLines(worktree, args) {
+  const result = await runProcess("git", args, { cwd: worktree, timeoutMs: 15_000 });
+  if (result.exitCode !== 0) throw new Error(`git ${args.join(" ")} failed`);
+  return parseLines(result.stdout);
+}
+
+export async function worktreeBranch(worktree) {
+  const root = await realpath(worktree);
+  return (await gitLines(root, ["branch", "--show-current"]))[0] ?? "DETACHED";
+}
+
+export async function calculateCandidateFingerprint(worktree) {
+  const root = await realpath(worktree);
+  const head = (await gitLines(root, ["rev-parse", "HEAD"]))[0] ?? "NO_HEAD";
+  const changed = new Set([
+    ...(await gitLines(root, ["diff", "--name-only"])),
+    ...(await gitLines(root, ["diff", "--cached", "--name-only"])),
+    ...(await gitLines(root, ["ls-files", "--others", "--exclude-standard"])),
+  ]);
+  const files = [];
+  for (const relativePath of [...changed].sort()) {
+    if (SENSITIVE_PATH.test(relativePath) || IGNORED_PATH.test(relativePath)) continue;
+    const absolutePath = path.resolve(root, relativePath);
+    if (!absolutePath.startsWith(`${root}${path.sep}`)) throw new Error(`unsafe changed path: ${relativePath}`);
+    let contentHash = "DELETED";
+    try {
+      const metadata = await stat(absolutePath);
+      if (metadata.isFile()) contentHash = digest(await readFile(absolutePath));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    files.push({ path: relativePath, sha256: contentHash });
+  }
+  const canonical = JSON.stringify({ git_head: head, files });
+  return { algorithm: "sha256", value: digest(canonical), git_head: head, files };
+}

package/runtime/lib/gates.mjs

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { redactAndCap, writeLog } from "./evidence.mjs";
+import { runProcess } from "./process.mjs";
+
+function scalar(value) {
+  const trimmed = value.trim();
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  if (trimmed === "[]") return [];
+  return trimmed.replace(/^['"]|['"]$/g, "");
+}
+
+function unquoteWhole(value) {
+  const trimmed = value.trim();
+  if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+// Supports the deliberately small, list-of-maps YAML contract used by quality-gates.yaml.
+export function parseQualityGates(source) {
+  try {
+    const parsed = JSON.parse(source);
+    return parsed.gates ?? [];
+  } catch {}
+  const gates = [];
+  let current = null;
+  for (const rawLine of source.split("\n")) {
+    const line = rawLine.replace(/\s+#.*$/, "");
+    const match = line.match(/^\s*(?:-\s+)?([a-z_]+):\s*(.*?)\s*$/i);
+    if (!match) continue;
+    const [, key, value] = match;
+    const parsedValue = key === "command" || key === "description" ? unquoteWhole(value) : scalar(value);
+    if (line.trimStart().startsWith("- ")) {
+      if (current) gates.push(current);
+      current = { [key]: parsedValue };
+    } else if (current) {
+      current[key] = parsedValue;
+    }
+  }
+  if (current) gates.push(current);
+  return gates;
+}
+
+export async function loadTrustedGates(gatesPath, expectedHash) {
+  const source = await readFile(gatesPath, "utf8");
+  const actualHash = createHash("sha256").update(source).digest("hex");
+  if (!expectedHash || actualHash !== expectedHash) {
+    return { valid: false, actualHash, gates: [] };
+  }
+  return { valid: true, actualHash, gates: parseQualityGates(source) };
+}
+
+export async function executeGates(gates, worktree, logDirectory) {
+  const results = [];
+  for (const gate of gates) {
+    const required = gate.required !== false;
+    const executor = gate.executor ?? "control-plane";
+    if (executor !== "control-plane") {
+      results.push({ id: gate.id ?? "unknown", required, executor, status: "unsupported_executor", reason: `executor_${executor}_is_not_supported_in_v1` });
+      continue;
+    }
+    if (!gate.id || !gate.command || /^REPLACE_ME/.test(gate.command)) {
+      results.push({ id: gate.id ?? "unknown", required, executor, status: "invalid_gate", reason: "missing_trusted_command" });
+      continue;
+    }
+    const startedAt = Date.now();
+    const result = await runProcess(gate.command, [], { cwd: worktree, shell: true, timeoutMs: (gate.timeout_seconds ?? 600) * 1000 });
+    const stdout = redactAndCap(result.stdout);
+    const stderr = redactAndCap(result.stderr);
+    const stdoutLog = await writeLog(logDirectory, gate.id, "stdout", result.stdout);
+    const stderrLog = await writeLog(logDirectory, gate.id, "stderr", result.stderr);
+    results.push({
+      id: gate.id,
+      required,
+      executor,
+      status: result.timedOut ? "timeout" : result.exitCode === 0 ? "pass" : "fail",
+      exit_code: result.exitCode,
+      duration_ms: Date.now() - startedAt,
+      stdout_ref: stdoutLog.ref,
+      stderr_ref: stderrLog.ref,
+      output_truncated: stdout.truncated || stderr.truncated,
+    });
+  }
+  return results;
+}

package/runtime/lib/process.mjs

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+export function runProcess(command, args = [], options = {}) {
+  const { cwd, timeoutMs = 600_000, shell = false, killGraceMs = 2_000 } = options;
+  return new Promise((resolve) => {
+    const detached = process.platform !== "win32";
+    const child = spawn(command, args, { cwd, shell, detached, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let forceTimer;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      signalProcess(child, "SIGTERM", detached);
+      forceTimer = setTimeout(() => signalProcess(child, "SIGKILL", detached), killGraceMs);
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => { stderr += `${error.message}\n`; });
+    child.on("close", (exitCode, signal) => {
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      resolve({ exitCode: exitCode ?? 1, signal, timedOut, stdout, stderr });
+    });
+  });
+}
+
+function signalProcess(child, signal, detached) {
+  try {
+    if (detached && child.pid) process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch {
+    // The process may have exited between the timeout and the escalation.
+  }
+}