@crown-dev-studios/review-council 0.1.0

package/dist/render-review-html.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import MarkdownIt from "markdown-it";
+function htmlEscape(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+const markdownRenderer = new MarkdownIt({
+    html: false,
+    linkify: true,
+    typographer: false,
+});
+function renderMarkdown(markdown) {
+    if (!markdown.trim()) {
+        return '<p class="empty">No content yet.</p>';
+    }
+    return markdownRenderer.render(markdown);
+}
+function loadJsonWithStatus(path) {
+    if (!existsSync(path)) {
+        return { data: {}, status: "missing" };
+    }
+    try {
+        return { data: JSON.parse(readFileSync(path, "utf8")), status: "ok" };
+    }
+    catch {
+        return { data: {}, status: "malformed" };
+    }
+}
+function loadText(path) {
+    if (!existsSync(path)) {
+        return "";
+    }
+    return readFileSync(path, "utf8");
+}
+function flattenFindings(document, reviewer) {
+    const findings = document.findings;
+    if (!Array.isArray(findings)) {
+        return [];
+    }
+    return findings
+        .filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
+        .map((item) => ({ ...item, reviewer }));
+}
+function stageStatusRow(name, status) {
+    const success = status.success === true;
+    const isEmpty = Object.keys(status).length === 0;
+    const state = isEmpty ? "pending" : success ? "success" : "failed";
+    const label = isEmpty ? "pending" : success ? "complete" : "failed";
+    const details = [];
+    if (!isEmpty) {
+        if (typeof status.exit_code === "number") {
+            details.push(`exit ${status.exit_code}`);
+        }
+        if (status.timed_out === true) {
+            details.push("timed out");
+        }
+        if (typeof status.attempts === "number" && status.attempts > 1) {
+            details.push(`${status.attempts} attempts`);
+        }
+        if (Array.isArray(status.validation_errors) && status.validation_errors.length > 0) {
+            details.push(`${status.validation_errors.length} validation error(s)`);
+        }
+        if (Array.isArray(status.missing_artifacts) && status.missing_artifacts.length > 0) {
+            details.push(`${status.missing_artifacts.length} missing artifact(s)`);
+        }
+    }
+    const detailSpan = details.length > 0
+        ? `<span class="status-details">${htmlEscape(details.join(" · "))}</span>`
+        : "";
+    return [
+        `<div class="status-row status-${htmlEscape(state)}">`,
+        `<strong>${htmlEscape(name)}</strong>`,
+        `<span>${htmlEscape(label)}${detailSpan}</span>`,
+        "</div>",
+    ].join("");
+}
+function stderrExcerpt(stageDir, maxLines = 20) {
+    const stderrPath = resolve(stageDir, "stderr.log");
+    const text = loadText(stderrPath);
+    if (!text.trim())
+        return "";
+    const lines = text.split("\n");
+    return lines.slice(-maxLines).join("\n");
+}
+function buildDiagnostics(runDir, statuses) {
+    const blocks = [];
+    for (const [stage, status] of Object.entries(statuses)) {
+        if (Object.keys(status).length === 0 || status.success === true)
+            continue;
+        const parts = [];
+        parts.push('<div class="diagnostic-block">');
+        parts.push(`<h3>${htmlEscape(stage)}</h3>`);
+        if (Array.isArray(status.validation_errors)) {
+            const errors = status.validation_errors;
+            parts.push("<p><strong>Validation errors:</strong></p><ul>");
+            for (const error of errors) {
+                const location = error.path ? `${error.path}: ` : "";
+                parts.push(`<li>${htmlEscape(`${location}${error.message ?? "unknown"}`)}</li>`);
+            }
+            parts.push("</ul>");
+        }
+        if (Array.isArray(status.missing_artifacts) && status.missing_artifacts.length > 0) {
+            const missingArtifacts = status.missing_artifacts;
+            parts.push("<p><strong>Missing artifacts:</strong></p><ul>");
+            for (const artifact of missingArtifacts) {
+                parts.push(`<li>${htmlEscape(artifact)}</li>`);
+            }
+            parts.push("</ul>");
+        }
+        const stageDir = resolve(runDir, stage);
+        const excerpt = stderrExcerpt(stageDir);
+        if (excerpt) {
+            parts.push("<p><strong>stderr (last 20 lines):</strong></p>");
+            parts.push(`<pre class="stderr-excerpt">${htmlEscape(excerpt)}</pre>`);
+        }
+        const stdoutLog = typeof status.stdout_log === "string" ? status.stdout_log : "";
+        const stderrLog = typeof status.stderr_log === "string" ? status.stderr_log : "";
+        if (stdoutLog || stderrLog) {
+            parts.push('<div class="log-paths">');
+            if (stdoutLog)
+                parts.push(`<code>${htmlEscape(stdoutLog)}</code>`);
+            if (stderrLog)
+                parts.push(`<code>${htmlEscape(stderrLog)}</code>`);
+            parts.push("</div>");
+        }
+        parts.push("</div>");
+        blocks.push(parts.join(""));
+    }
+    return blocks.join("");
+}
+function filesLabel(files) {
+    if (files.length === 0) {
+        return "-";
+    }
+    return files
+        .map((item) => {
+        if (!item.path)
+            return "?";
+        return item.line ? `${item.path}:${item.line}` : item.path;
+    })
+        .join(", ");
+}
+function candidateRow(row) {
+    const severity = String(row.severity ?? "-");
+    return [
+        "<tr>",
+        `<td>${htmlEscape(String(row.reviewer ?? "-"))}</td>`,
+        `<td><span class="severity ${htmlEscape(severity.toLowerCase())}">${htmlEscape(severity.toUpperCase())}</span></td>`,
+        `<td>${htmlEscape(String(row.title ?? "-"))}</td>`,
+        `<td>${htmlEscape(String(row.confidence ?? "-"))}</td>`,
+        `<td>${htmlEscape(filesLabel(row.files))}</td>`,
+        "</tr>",
+    ].join("");
+}
+function verdictRows(verdict) {
+    const rows = [];
+    const groups = [
+        ["confirmed", verdict.confirmed_findings],
+        ["contested", verdict.contested_findings],
+        ["rejected", verdict.rejected_findings],
+    ];
+    for (const [status, value] of groups) {
+        if (!Array.isArray(value))
+            continue;
+        for (const item of value) {
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                continue;
+            }
+            const verdictItem = item;
+            rows.push([
+                "<tr>",
+                `<td>${htmlEscape(status)}</td>`,
+                `<td>${htmlEscape(String(verdictItem.title ?? "-"))}</td>`,
+                `<td>${htmlEscape(String(verdictItem.reason ?? "-"))}</td>`,
+                `<td>${htmlEscape(String(verdictItem.final_priority ?? "-"))}</td>`,
+                "</tr>",
+            ].join(""));
+        }
+    }
+    return rows.length > 0
+        ? rows.join("")
+        : '<tr><td colspan="4" class="empty">No judge verdict rows yet.</td></tr>';
+}
+function chips(bundle) {
+    const verdict = bundle.judge_verdict;
+    const confirmed = Array.isArray(verdict.confirmed_findings) ? verdict.confirmed_findings.length : 0;
+    const contested = Array.isArray(verdict.contested_findings) ? verdict.contested_findings.length : 0;
+    const rejected = Array.isArray(verdict.rejected_findings) ? verdict.rejected_findings.length : 0;
+    return [
+        `Overall: ${String(verdict.overall_verdict ?? "incomplete")}`,
+        `Candidate findings: ${bundle.candidate_findings.length}`,
+        `Confirmed: ${confirmed}`,
+        `Contested: ${contested}`,
+        `Rejected: ${rejected}`,
+    ]
+        .map((item) => `<span class="chip">${htmlEscape(item)}</span>`)
+        .join("");
+}
+export function buildBundle(runDir) {
+    const resolvedRunDir = resolve(runDir);
+    const run = loadJsonWithStatus(resolve(resolvedRunDir, "run.json"));
+    const claudeDoc = loadJsonWithStatus(resolve(resolvedRunDir, "claude", "findings.json"));
+    const codexDoc = loadJsonWithStatus(resolve(resolvedRunDir, "codex", "findings.json"));
+    const judgeDoc = loadJsonWithStatus(resolve(resolvedRunDir, "judge", "verdict.json"));
+    const reviewId = typeof run.data.review_id === "string" ? run.data.review_id : "";
+    const runId = typeof run.data.run_id === "string" ? run.data.run_id : "";
+    const reviewTarget = typeof run.data.review_target === "string"
+        ? run.data.review_target
+        : (typeof run.data.target === "string" ? run.data.target : "-");
+    return {
+        review_id: reviewId,
+        run_id: runId,
+        review_target: reviewTarget,
+        run: run.data,
+        candidate_findings: [
+            ...flattenFindings(claudeDoc.data, "claude"),
+            ...flattenFindings(codexDoc.data, "codex"),
+        ],
+        judge_verdict: judgeDoc.data,
+        status: {
+            claude: loadJsonWithStatus(resolve(resolvedRunDir, "claude", "status.json")).data,
+            codex: loadJsonWithStatus(resolve(resolvedRunDir, "codex", "status.json")).data,
+            judge: loadJsonWithStatus(resolve(resolvedRunDir, "judge", "status.json")).data,
+        },
+        reports: {
+            claude: loadText(resolve(resolvedRunDir, "claude", "report.md")),
+            codex: loadText(resolve(resolvedRunDir, "codex", "report.md")),
+            judge: loadText(resolve(resolvedRunDir, "judge", "summary.md")),
+        },
+        artifact_status: {
+            claude: claudeDoc.status,
+            codex: codexDoc.status,
+            judge: judgeDoc.status,
+        },
+    };
+}
+export function renderRunDir(runDir, templatePath) {
+    const resolvedRunDir = resolve(runDir);
+    const moduleDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
+    const packageDir = resolve(moduleDir, "..");
+    const resolvedTemplatePath = templatePath
+        ? resolve(templatePath)
+        : resolve(packageDir, "templates", "report.html");
+    const bundle = buildBundle(resolvedRunDir);
+    const template = readFileSync(resolvedTemplatePath, "utf8");
+    const target = bundle.review_target;
+    const candidateRows = bundle.candidate_findings.length > 0
+        ? bundle.candidate_findings.map(candidateRow).join("")
+        : '<tr><td colspan="5" class="empty">No candidate findings yet.</td></tr>';
+    const statusRows = [
+        stageStatusRow("Claude", bundle.status.claude),
+        stageStatusRow("Codex", bundle.status.codex),
+        stageStatusRow("Judge", bundle.status.judge),
+    ].join("");
+    const diagnosticsContent = buildDiagnostics(resolvedRunDir, {
+        claude: bundle.status.claude,
+        codex: bundle.status.codex,
+        judge: bundle.status.judge,
+    });
+    const hasDiagnostics = diagnosticsContent.length > 0;
+    const replacements = {
+        "__TITLE__": "Review Council Report",
+        "__HEADING__": "Review Council",
+        "__META__": htmlEscape(`Target: ${target} · Review ID: ${bundle.review_id || "-"} · Run ID: ${bundle.run_id || "-"}`),
+        "__CHIPS__": chips(bundle),
+        "__JUDGE_SUMMARY__": renderMarkdown(bundle.reports.judge || "Judge output not available yet."),
+        "__STATUS_ROWS__": statusRows,
+        "__DIAGNOSTICS_DISPLAY__": hasDiagnostics ? "block" : "none",
+        "__DIAGNOSTICS_CONTENT__": diagnosticsContent,
+        "__CANDIDATE_ROWS__": candidateRows,
+        "__VERDICT_ROWS__": verdictRows(bundle.judge_verdict),
+        "__CLAUDE_REPORT__": renderMarkdown(bundle.reports.claude || "Claude report not available yet."),
+        "__CODEX_REPORT__": renderMarkdown(bundle.reports.codex || "Codex report not available yet."),
+    };
+    let htmlOutput = template;
+    for (const [needle, value] of Object.entries(replacements)) {
+        htmlOutput = htmlOutput.replaceAll(needle, value);
+    }
+    writeFileSync(resolve(resolvedRunDir, "bundle.json"), `${JSON.stringify(bundle, null, 2)}\n`);
+    writeFileSync(resolve(resolvedRunDir, "index.html"), htmlOutput);
+}
+export function main(args = process.argv.slice(2)) {
+    const [runDir, ...rest] = args;
+    if (!runDir || runDir === "--help" || runDir === "-h") {
+        console.log("usage: render-review-html [run_dir] [--template path]");
+        process.exit(runDir ? 0 : 1);
+    }
+    let templatePath;
+    for (let index = 0; index < rest.length; index += 1) {
+        if (rest[index] === "--template") {
+            templatePath = rest[index + 1];
+            index += 1;
+        }
+    }
+    renderRunDir(runDir, templatePath);
+}
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && resolve(process.argv[1]) === currentFile) {
+    main();
+}

package/dist/review-session.js

@@ -0,0 +1,77 @@
+import { createHash, randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+export const REVIEW_ID_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+function realpathOrResolve(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function normalizeWhitespace(value) {
+    return value.trim().replaceAll(/\s+/g, " ");
+}
+function slugify(value, maxLength = 48) {
+    const slug = value
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, "-")
+        .replaceAll(/^-+|-+$/g, "")
+        .replaceAll(/-{2,}/g, "-");
+    if (!slug) {
+        return "review";
+    }
+    return slug.slice(0, maxLength).replaceAll(/-+$/g, "") || "review";
+}
+function formatTimestamp(date) {
+    const iso = date.toISOString();
+    const [day, time] = iso.split("T");
+    const datePart = day.replaceAll("-", "");
+    const timePart = time.replace("Z", "").replaceAll(":", "").replace(".", "");
+    return `${datePart}-${timePart}`;
+}
+export function normalizeReviewTarget(target) {
+    return normalizeWhitespace(target);
+}
+export function deriveReviewId(cwd, target) {
+    const normalizedRoot = realpathOrResolve(cwd);
+    const normalizedTarget = normalizeReviewTarget(target).toLowerCase();
+    const hash = createHash("sha1")
+        .update(normalizedRoot)
+        .update("\n")
+        .update(normalizedTarget)
+        .digest("hex")
+        .slice(0, 12);
+    const targetSlug = slugify(normalizedTarget);
+    return `${targetSlug}-${hash}`;
+}
+export function validateReviewId(reviewId) {
+    if (!REVIEW_ID_PATTERN.test(reviewId)) {
+        return "Review IDs must match /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/";
+    }
+    return null;
+}
+export function createRunId(date = new Date(), uuid = randomUUID()) {
+    const suffix = uuid.replaceAll("-", "").slice(0, 8).toLowerCase();
+    return `${formatTimestamp(date)}-${suffix}`;
+}
+export function buildReviewPaths(cwd, reviewId, runId, explicitRunDir) {
+    const rootDir = resolve(cwd, "docs", "reviews");
+    const reviewDir = resolve(rootDir, reviewId);
+    const runsDir = resolve(reviewDir, "runs");
+    const runDir = explicitRunDir ? resolve(explicitRunDir) : resolve(runsDir, runId);
+    return {
+        rootDir,
+        reviewDir,
+        runsDir,
+        runDir,
+        claudeDir: resolve(runDir, "claude"),
+        codexDir: resolve(runDir, "codex"),
+        judgeDir: resolve(runDir, "judge"),
+    };
+}
+export function isReviewScopedRunDir(paths) {
+    const relativePath = relative(paths.runsDir, paths.runDir);
+    return relativePath !== "" && relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !relativePath.includes(`${sep}..${sep}`);
+}

package/dist/schemas.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+const fileRef = z.object({
+    path: z.string(),
+    line: z.number().int().min(1).optional(),
+}).strict();
+const finding = z.object({
+    id: z.string(),
+    title: z.string(),
+    severity: z.enum(["p1", "p2", "p3"]),
+    confidence: z.enum(["high", "medium", "low"]),
+    category: z.string(),
+    description: z.string(),
+    evidence: z.string(),
+    recommended_fix: z.string(),
+    files: z.array(fileRef),
+}).strict();
+export const reviewFindingsSchema = z.object({
+    review_id: z.string(),
+    run_id: z.string(),
+    reviewer: z.enum(["claude", "codex", "other"]),
+    target: z.string(),
+    generated_at: z.iso.datetime(),
+    summary: z.string(),
+    findings: z.array(finding),
+}).strict();
+const verdictFinding = z.object({
+    title: z.string(),
+    status: z.enum(["confirmed", "contested", "rejected"]),
+    reason: z.string(),
+    reviewer_ids: z.array(z.string()).optional(),
+    final_priority: z.enum(["p1", "p2", "p3"]).optional(),
+}).strict();
+const todoRecommendation = z.object({
+    title: z.string(),
+    priority: z.enum(["p1", "p2", "p3"]),
+    reason: z.string(),
+}).strict();
+export const judgeVerdictSchema = z.object({
+    review_id: z.string(),
+    run_id: z.string(),
+    target: z.string(),
+    generated_at: z.iso.datetime(),
+    overall_verdict: z.enum(["approve", "needs-fixes", "blocked", "incomplete"]),
+    summary_markdown: z.string(),
+    confirmed_findings: z.array(verdictFinding),
+    contested_findings: z.array(verdictFinding),
+    rejected_findings: z.array(verdictFinding),
+    todo_recommendations: z.array(todoRecommendation),
+}).strict();
+export const reviewDoneSchema = z.object({
+    review_id: z.string(),
+    run_id: z.string(),
+    reviewer: z.enum(["claude", "codex", "other"]),
+    status: z.literal("complete"),
+    completed_at: z.iso.datetime(),
+    finding_count: z.number().int().min(0),
+}).strict();
+export const judgeDoneSchema = z.object({
+    review_id: z.string(),
+    run_id: z.string(),
+    reviewer: z.literal("judge"),
+    status: z.literal("complete"),
+    completed_at: z.iso.datetime(),
+    confirmed_count: z.number().int().min(0),
+    contested_count: z.number().int().min(0),
+    rejected_count: z.number().int().min(0),
+}).strict();

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@crown-dev-studios/review-council",
+  "version": "0.1.0",
+  "description": "Parallel multi-agent code review orchestration with bundled prompts, schemas, and HTML reporting.",
+  "packageManager": "pnpm@10.30.3",
+  "type": "module",
+  "bin": {
+    "review-council": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "schemas/",
+    "references/",
+    "README.md",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "pack:dry-run": "npm_config_cache=.npm-cache npm pack --dry-run --json",
+    "review-council:orchestrate": "tsx src/cli.ts",
+    "review-council:render": "tsx src/render-review-html.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "node --import tsx/esm --test test/*.test.ts",
+    "test:package": "node --test test/package-smoke.test.mjs",
+    "test": "pnpm run typecheck && pnpm run test:unit && pnpm run test:package",
+    "verify:package": "pnpm run pack:dry-run && pnpm run test:package",
+    "release:manual": "bash scripts/prepare-release.sh"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^24",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "markdown-it": "^14.1.1",
+    "zod": "^4.3.5"
+  }
+}

package/references/cli-integration.md

@@ -0,0 +1,177 @@
+# CLI Integration
+
+The orchestrator accepts literal shell commands via `--claude-command`, `--codex-command`, and `--judge-command`. Context values are passed as environment variables to each child process.
+
+Point reviewer CLIs at the rendered prompt files created inside the run directory. This keeps the command templates self-contained and avoids depending on any external `/review-export` command.
+
+Pass `--review-id` explicitly when you want run output that is easy to correlate across reruns.
+
+Available environment variables:
+
+- `$CWD`
+- `$SKILL_DIR`
+- `$REVIEW_ID`
+- `$RUN_ID`
+- `$REVIEW_DIR`
+- `$RUN_DIR`
+- `$CLAUDE_DIR`
+- `$CODEX_DIR`
+- `$JUDGE_DIR`
+- `$REVIEW_SCHEMA`
+- `$JUDGE_SCHEMA`
+
+These variables are set in the child process environment. Use standard shell quoting (`"$VAR"`) in command templates.
+
+Review targets are available in the rendered prompt templates, but not as environment variables. Keep target text in prompt files rather than interpolating it into reviewer or judge command strings.
+
+The orchestrator renders these prompt files before launching any stage:
+
+- `$CLAUDE_DIR/claude-review-export.md`
+- `$CODEX_DIR/codex-review-export.md`
+- `$JUDGE_DIR/judge.md`
+
+When invoking the orchestrator from the project being reviewed, prefer the published package command:
+
+```bash
+npx @crown-dev-studios/review-council --help
+```
+
+If the package is already installed, `review-council --help` is equivalent. Invoking the command from the project under review keeps `process.cwd()` anchored there, so the default output path lands in `docs/reviews/` for that project.
+
+## Recommended Mode
+
+Use raw-review prompts that export findings into the run directory.
+
+### Claude
+
+Claude supports non-interactive `-p` and built-in `--worktree`.
+
+Reviewer commands should already be authenticated and must not require interactive approvals or follow-up answers.
+
+Example:
+
+```bash
+claude -p --disable-slash-commands --permission-mode acceptEdits \
+  "$(cat "$CLAUDE_DIR/claude-review-export.md")" < /dev/null
+```
+
+Use `--disable-slash-commands --permission-mode acceptEdits` for artifact-writing review flows, and redirect stdin from `/dev/null` when the stage is fully headless. This keeps Claude in print mode, disables skills, allows artifact writes without interactive approval prompts, and avoids stdin wait warnings.
+
+If you want Claude to create an isolated Git worktree, add `--worktree <name>` to the Claude command itself. `review-council` does not own reviewer cwd or worktree paths; that stays inside the raw command you pass.
+
+### Codex
+
+Codex supports:
+
+- `codex review --uncommitted`
+- `codex review --base <branch>`
+- `codex exec`
+
+For exact staged-only review, prefer `codex exec` with an explicit prompt.
+
+Example:
+
+```bash
+codex exec --sandbox workspace-write -o "$CODEX_DIR/last-message.txt" \
+  "$(cat "$CODEX_DIR/codex-review-export.md")"
+```
+
+Codex reviewer and judge commands must run with a writable sandbox because they need to write artifacts into the stage directory.
+
+## Minimal-Change Mode
+
+If you want to keep using `workflows-review` unchanged:
+
+1. Create a separate worktree per reviewer
+2. Run `workflows-review` inside each worktree
+3. Let each reviewer write to that worktree's local `todos/`
+4. Harvest those todo files into `docs/reviews/<run>/`
+5. Judge the normalized findings afterward
+
+This works, but the cleaner long-term shape is export-only reviewer artifacts plus final todo creation after the judge.
+
+## Orchestrator Example
+
+```bash
+npx @crown-dev-studios/review-council \
+  --target "branch main..feature/review-council" \
+  --review-id branch-main-feature-review-council \
+  --claude-command 'claude -p --disable-slash-commands --permission-mode acceptEdits --worktree review-council-claude "$(cat "$CLAUDE_DIR/claude-review-export.md")" < /dev/null' \
+  --codex-command 'codex exec --sandbox workspace-write -o "$CODEX_DIR/last-message.txt" "$(cat "$CODEX_DIR/codex-review-export.md")"' \
+  --judge-command 'codex exec --sandbox workspace-write -o "$JUDGE_DIR/last-message.txt" "$(cat "$JUDGE_DIR/judge.md")"'
+```
+
+## Resilience Options
+
+### Timeout
+
+`--timeout <ms>` (default: 300000 — 5 minutes) sets a per-stage deadline. On timeout:
+
+1. The child process receives `SIGTERM`
+2. After a 5-second grace period, `SIGKILL` is sent if the process hasn't exited
+3. The stage result records `exit_code: 124` and `timed_out: true`
+
+Timed-out stages are not retried.
+
+### Retries
+
+`--retries <n>` (default: 2) retries a stage up to N times on non-zero exit. Delay between retries uses exponential backoff: `2000 * 2^(attempt-1)` ms (2s, 4s, 8s...). The final `status.json` records `attempts` and `retried` fields.
+
+Retries are skipped for timeouts (not transient).
+
+### Interactive Prompt Detection
+
+The orchestrator monitors each reviewer's stdout for prompt-like output (lines ending with `? `, `: `, `> `, or containing `y/n`, `yes/no`) followed by 3 seconds of silence. When detected, the prompt is relayed to the user's terminal and the response is piped back to the child's stdin.
+
+If both reviewers prompt simultaneously, questions are queued and presented one at a time.
+
+This is a best-effort safety net. Prefer explicit non-interactive mode (`claude -p --disable-slash-commands --permission-mode acceptEdits < /dev/null`, `codex exec`) when possible.
+
+### Schema Validation
+
+After each successful process exit, the orchestrator requires the full artifact set (`report.md` + `findings.json` for reviewers, `summary.md` + `verdict.json` for the judge, plus `done.json` unless `--allow-missing-sentinel` is set). It then validates the JSON artifact against its schema. Missing artifacts and validation failures both mark the stage as failed in `status.json`.
+
+### Partial Judge Execution
+
+The judge runs if at least one reviewer succeeded. The final JSON summary includes a `reviewers_partial` flag and per-reviewer result details.
+
+### Skip Judge
+
+`--skip-judge` disables judge prompt rendering, judge command validation, and judge execution. This makes reviewer-only runs independent of any configured judge binary.
+
+### Judge Inputs
+
+The judge template always names the reviewer artifact paths it can inspect. If a listed reviewer directory does not exist in a run, that reviewer did not run and its files should be ignored.
+
+## Sentinel Contract
+
+The orchestrator waits for:
+
+- reviewer exit code `0`
+- reviewer `done.json`
+- judge exit code `0`
+- judge `done.json`
+
+If a process exits `0` but omits `done.json`, the stage is treated as incomplete.
+
+## Development Runtime
+
+The supported consumer runtime is the published package. For local development from a source checkout:
+
+```bash
+cd ~/src/review-council
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm verify:package
+```
+
+Package scripts are defined in `package.json`:
+
+- `pnpm review-council:orchestrate`
+- `pnpm review-council:render`
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm verify:package`
+
+Those scripts are for contributors working inside the package repo itself. For reviewing another project, prefer the published package command above so the docs, package metadata, and runtime contract all stay aligned.