codictator 0.0.0 → 0.1.3

package/dist/cli/plan-launcher.js

@@ -0,0 +1,272 @@
+// SPEC §4.19.3: the manifest-owned launcher text. Split from the plan
+// builders (plan.ts) by responsibility: generated bytes here, plan assembly
+// there.
+// SPEC §4.19.3: the manifest-owned launcher. Plain module syntax
+// (imports, no top-level await) so any Node can parse it: node floor
+// check, engine resolution at the root or tool dir, in-process main()
+// call with CODICTATOR_HOOK=1, and the harness's embedded static block
+// reply when no engine exists. The launcher is generated TEXT, not a
+// runtime import of this module, so its module specifiers interpolate
+// (SPEC §10.3 item 3 scans source for node:fs and friends); the emitted
+// bytes are the plain imports below.
+function launcherImport(decl, module) {
+    return `${decl} from "node:${module}";`;
+}
+export const LAUNCHER_TEXT = [
+    "// Generated by `codictator init` (SPEC §4.19.3); do not edit by hand.",
+    "// static replies below per configured harness (SPEC §4.5.1) and until then",
+    "// they are the two P0 harness deny forms by hand. Zero dependencies and",
+    "// ES2015-only syntax, so any Node parses it: the version check runs before",
+    "// any newer syntax could load, and only node: built-ins are imported. It",
+    "// sets CODICTATOR_HOOK=1 in the engine process, then resolves the engine at",
+    "// <root>/node_modules/codictator/dist/cli/main.js else",
+    "// <root>/.codictator/tool/node_modules/codictator/dist/cli/main.js. The",
+    "// launcher reads the resolved engine's manifest version and passes it",
+    "// as main's third argument, so hook validation sees the installed",
+    "// version (SPEC §4.2.1 EC-11); an unreadable manifest falls back to",
+    "// the two-argument call. A",
+    "// missing engine answers the harness's embedded static CDX-E003 block",
+    "// reply; outside hook it prints CDX-E003 and exits 6. Git hooks arrive",
+    "// as a `git` first word and route to the engine like hook words do, so",
+    "// a missing engine or an old node fails the commit or push closed.",
+    "// Version arbitration",
+    "// between the root and tool-dir engines (SPEC §4.19 EC-6) belongs to the",
+    "// phase 9 CLI: until then the first candidate that exists wins.",
+    launcherImport("import { existsSync, readFileSync }", "fs"),
+    launcherImport("import path", "path"),
+    launcherImport("import { fileURLToPath, pathToFileURL }", "url"),
+    "",
+    "const MIN_NODE_MAJOR = 24;",
+    "",
+    "function nodeMajor() {",
+    "\tconst match = /^v(\\d+)\\./.exec(process.version);",
+    "\tif (match === null) {",
+    "\t\treturn 0;",
+    "\t}",
+    "\tconst major = parseInt(match[1], 10);",
+    "\tif (Number.isNaN(major)) {",
+    "\t\treturn 0;",
+    "\t}",
+    "\treturn major;",
+    "}",
+    "",
+    "// The launcher ships at <root>/.codictator/bin/run.mjs, so the repo root",
+    "// is three levels up from this file.",
+    "function launcherRoot() {",
+    "\treturn path.dirname(",
+    "\t\tpath.dirname(path.dirname(fileURLToPath(import.meta.url))),",
+    "\t);",
+    "}",
+    "",
+    "function engineCandidates(root) {",
+    "\treturn [",
+    `\t\tpath.join(root, "node_modules", "codictator", "dist", "cli", "main.js"),`,
+    "\t\tpath.join(",
+    "\t\t\troot,",
+    `\t\t\t".codictator",`,
+    `\t\t\t"tool",`,
+    `\t\t\t"node_modules",`,
+    `\t\t\t"codictator",`,
+    `\t\t\t"dist",`,
+    `\t\t\t"cli",`,
+    `\t\t\t"main.js",`,
+    "\t\t),",
+    "\t];",
+    "}",
+    "",
+    "// The embedded pre-engine deny forms (SPEC §4.5.1): exit 0 with the",
+    "// harness's own deny JSON. Answers null for harnesses without a static",
+    "// form, so the caller falls back to the process exit code.",
+    "function staticReply(harness, code, message) {",
+    `\tif (harness === "muse-code") {`,
+    "\t\treturn {",
+    "\t\t\texitCode: 0,",
+    "\t\t\tstdout: JSON.stringify({",
+    "\t\t\t\thookSpecificOutput: {",
+    `\t\t\t\t\thookEventName: "PreToolUse",`,
+    `\t\t\t\t\tpermissionDecision: "deny",`,
+    `\t\t\t\t\tpermissionDecisionReason: \`\${code} \${message}\`,`,
+    "\t\t\t\t},",
+    "\t\t\t}),",
+    "\t\t};",
+    "\t}",
+    `\tif (harness === "opencode") {`,
+    "\t\treturn {",
+    "\t\t\texitCode: 0,",
+    "\t\t\tstdout: JSON.stringify({",
+    `\t\t\t\tdecision: "block",`,
+    `\t\t\t\tmessage: \`\${code} \${message}\`,`,
+    `\t\t\t\teventId: "static",`,
+    "\t\t\t}),",
+    "\t\t};",
+    "\t}",
+    "\treturn null;",
+    "}",
+    "",
+    "function writeStatic(reply) {",
+    "\tprocess.stdout.write(reply.stdout);",
+    "\tprocess.exitCode = reply.exitCode;",
+    "}",
+    "",
+    "function writeMissingEngine() {",
+    "\tprocess.stderr.write(",
+    `\t\t"CDX-E003 codictator engine is not installed; run npm ci, then retry.\\n",`,
+    "\t);",
+    "\tprocess.exitCode = 6;",
+    "}",
+    "",
+    "function writeOldNode() {",
+    "\tprocess.stderr.write(",
+    `\t\t\`CDX-E002 node \${process.version} is older than the required >=24.0.0; install a newer Node, then retry.\\n\`,`,
+    "\t);",
+    "\tprocess.exitCode = 6;",
+    "}",
+    "",
+    "function writeEngineFailed() {",
+    "\tprocess.stderr.write(",
+    `\t\t"CDX-E901 the codictator engine failed to load; the tool call is blocked.\\n",`,
+    "\t);",
+    "\tprocess.exitCode = 1;",
+    "}",
+    "",
+    "function oldNodeMessage() {",
+    "\treturn (",
+    `\t\t\`node \${process.version} is older than the required >=24.0.0; \` +`,
+    `\t\t"install a newer Node, then retry the tool call."`,
+    "\t);",
+    "}",
+    "",
+    "function firstExisting(candidates) {",
+    "\tfor (let index = 0; index < candidates.length; index += 1) {",
+    "\t\tif (existsSync(candidates[index])) {",
+    "\t\t\treturn candidates[index];",
+    "\t\t}",
+    "\t}",
+    "\treturn null;",
+    "}",
+    "",
+    "// SPEC §4.2.1 EC-11: the engine entry validates config.codictator",
+    "// against the installed engine version, so the launcher extracts it",
+    "// from the resolved engine's own manifest text and passes it as",
+    "// main's third argument. A version-field scan keeps JSON parsing in",
+    "// the kernel per §10.3 item 6 (and a regex literal would confuse the",
+    "// blankCode lexer the ts/lint gate runs on); any unreadable or",
+    "// version-less manifest answers null and the caller falls back to",
+    "// the two-argument call, which keeps the pinned placeholder —",
+    "// fail-closed downstream, never an allow.",
+    "function installedEngineVersion(enginePath) {",
+    "\ttry {",
+    "\t\tconst manifestPath = path.join(",
+    "\t\t\tpath.dirname(path.dirname(path.dirname(enginePath))),",
+    `\t\t\t"package.json",`,
+    "\t\t);",
+    `\t\tconst text = readFileSync(manifestPath, "utf8");`,
+    '\t\tconst marker = "\\"version\\":";',
+    "\t\tconst at = text.indexOf(marker);",
+    "\t\tif (at === -1) {",
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\tlet index = at + marker.length;",
+    '\t\twhile (text[index] === " " || text[index] === "\\t" || text[index] === "\\n" || text[index] === "\\r") {',
+    "\t\t\tindex += 1;",
+    "\t\t}",
+    '\t\tif (text[index] !== "\\"") {',
+    "\t\t\treturn null;",
+    "\t\t}",
+    '\t\tconst end = text.indexOf("\\"", index + 1);',
+    "\t\tif (end === -1) {",
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\tconst version = text.slice(index + 1, end);",
+    '\t\tif (version === "") {',
+    "\t\t\treturn null;",
+    "\t\t}",
+    "\t\treturn version;",
+    "\t} catch (ignored) {",
+    "\t\treturn null;",
+    "\t}",
+    "}",
+    "",
+    "function reportMissing(harness) {",
+    "\tconst missing = staticReply(",
+    "\t\tharness,",
+    `\t\t\t"CDX-E003",`,
+    `\t\t\t"codictator engine is not installed; run npm ci, then retry the tool call.",`,
+    "\t);",
+    "\tif (missing === null) {",
+    "\t\twriteMissingEngine();",
+    "\t\treturn;",
+    "\t}",
+    "\twriteStatic(missing);",
+    "}",
+    "",
+    "function checkNode(harness) {",
+    "\tif (nodeMajor() < MIN_NODE_MAJOR) {",
+    `\t\tconst oldNode = staticReply(harness, "CDX-E002", oldNodeMessage());`,
+    "\t\tif (oldNode === null) {",
+    "\t\t\twriteOldNode();",
+    "\t\t\treturn false;",
+    "\t\t}",
+    "\t\twriteStatic(oldNode);",
+    "\t\treturn false;",
+    "\t}",
+    "\treturn true;",
+    "}",
+    "",
+    "function runEngine(enginePath, args, harness) {",
+    `\tprocess.env.CODICTATOR_HOOK = "1";`,
+    "\timport(pathToFileURL(enginePath).href)",
+    "\t\t.then(",
+    "\t\t\t(engine) => {",
+    `\t\t\t\tif (engine === null || typeof engine.main !== "function") {`,
+    `\t\t\t\t\tthrow new Error("engine entry has no main");`,
+    "\t\t\t\t}",
+    "\t\t\t\tconst version = installedEngineVersion(enginePath);",
+    "\t\t\t\tif (version === null) {",
+    "\t\t\t\t\treturn engine.main(args, process.cwd());",
+    "\t\t\t\t}",
+    "\t\t\t\treturn engine.main(args, process.cwd(), version);",
+    "\t\t\t},",
+    "\t\t\t(error) => {",
+    "\t\t\t\tthrow error;",
+    "\t\t\t},",
+    "\t\t)",
+    "\t\t.then(",
+    "\t\t\t(code) => {",
+    `\t\t\t\tprocess.exitCode = typeof code === "number" ? code : 0;`,
+    "\t\t\t},",
+    "\t\t\t() => {",
+    "\t\t\t\tconst failed = staticReply(",
+    "\t\t\t\t\tharness,",
+    `\t\t\t\t\t"CDX-E901",`,
+    `\t\t\t\t\t"the codictator engine failed to load; the tool call is blocked.",`,
+    "\t\t\t\t);",
+    "\t\t\t\tif (failed === null) {",
+    "\t\t\t\t\twriteEngineFailed();",
+    "\t\t\t\t\treturn;",
+    "\t\t\t\t}",
+    "\t\t\t\twriteStatic(failed);",
+    "\t\t\t},",
+    "\t\t);",
+    "}",
+    "",
+    "function main() {",
+    "\tconst args = process.argv.slice(2);",
+    `\tif (args[0] !== "hook" && args[0] !== "git") {`,
+    "\t\twriteMissingEngine();",
+    "\t\treturn;",
+    "\t}",
+    `\tconst harness = args[1] || "";`,
+    "\tif (!checkNode(harness)) {",
+    "\t\treturn;",
+    "\t}",
+    "\tconst enginePath = firstExisting(engineCandidates(launcherRoot()));",
+    "\tif (enginePath === null) {",
+    "\t\treportMissing(harness);",
+    "\t\treturn;",
+    "\t}",
+    "\trunEngine(enginePath, args, harness);",
+    "}",
+    "main();",
+    "",
+].join("\n");

package/dist/cli/plan.d.ts

@@ -0,0 +1,25 @@
+import type { Result } from "../kernel/index.ts";
+export declare const KNOWN_HELPER_ROLES: ReadonlySet<string>;
+export interface HelperProposal {
+    readonly role: string;
+    readonly command: string;
+    readonly pin: string;
+}
+export declare function buildHelperTool(proposal: HelperProposal): Record<string, unknown>;
+export interface GuardrailPlan {
+    readonly files: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface PlanExtras {
+    readonly packs?: unknown;
+    readonly tunables?: unknown;
+    readonly architecture?: unknown;
+    readonly tools?: unknown;
+}
+export declare function guardrailPlan(harnesses: ReadonlyArray<string>, profile: string, repoName: string, existingAgents: string | undefined, extras?: PlanExtras, engineVersion?: string): GuardrailPlan;
+export declare function writePlan(root: string, plan: GuardrailPlan, engineVersion?: string): Promise<Result<Array<{
+    path: string;
+    hash: string;
+}>>>;

package/dist/cli/plan.js

@@ -0,0 +1,121 @@
+// SPEC §4.14.1 + §4.14.5: guardrail plan builders. The file list (config,
+// steering block, CI workflow, hooks, launcher) and the manifest write are
+// shared by init and regen, so regeneration stays byte-identical.
+import { renderWorkflow } from "../features/ci/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { buildManifest, EXPECTED_HOOKS_PATH, HOOK_NAMES, hookInstallPlan, renderHookScript, } from "../features/integrity/index.js";
+import { buildManagedBlock, MANAGED_BEGIN, MANAGED_END, } from "../features/steering/index.js";
+import { err, normalizeText, ok, sha256Text, stableStringify, } from "../kernel/index.js";
+import { LAUNCHER_TEXT } from "./plan-launcher.js";
+import { portsFor } from "./shared.js";
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+// SPEC §4.4.5 + §4.6.6: init proposals for helper tools. The entry carries
+// the role, the binary, the exact pin from the human's registry lookup, and
+// a probe matching any semver in the tool's --version output whose capture
+// must equal the pin (external-probe.ts). Helpers never back enforcers, so
+// the probe runs only when a pack binds the tool.
+export const KNOWN_HELPER_ROLES = new Set([
+    "knowledge-graph",
+    "token-saver",
+    "dependency-bot",
+    "other",
+]);
+const SEMVER_CAPTURE = "(\\d+\\.\\d+\\.\\d+)";
+export function buildHelperTool(proposal) {
+    return {
+        id: proposal.command,
+        command: [proposal.command],
+        version: {
+            pin: proposal.pin,
+            probe: [proposal.command, "--version"],
+            pattern: SEMVER_CAPTURE,
+        },
+        role: proposal.role,
+    };
+}
+function configText(harnesses, profile, extras = {}, engineVersion = ENGINE_VERSION) {
+    const sorted = [...harnesses].sort();
+    const architecture = extras.architecture ?? (profile === "" ? undefined : { profile });
+    const config = {
+        version: 1,
+        codictator: engineVersion,
+        packs: extras.packs ?? [],
+        harnesses: sorted,
+        tunables: extras.tunables ?? {},
+        ...(architecture === undefined ? {} : { architecture }),
+        ...(extras.tools === undefined ? {} : { tools: extras.tools }),
+    };
+    return `${stableStringify(config)}\n`;
+}
+// SPEC §4.14.1: user text outside the managed block survives regen; a
+// malformed block is replaced rather than duplicated (CDX-E501 avoided).
+function withManagedBlock(existing) {
+    const block = buildManagedBlock();
+    if (existing === undefined) {
+        return `${block}\n`;
+    }
+    const start = existing.indexOf(MANAGED_BEGIN);
+    const end = existing.indexOf(MANAGED_END);
+    if (start < 0 || end < 0 || end < start) {
+        const trimmed = existing.endsWith("\n") ? existing : `${existing}\n`;
+        return `${trimmed}\n${block}\n`;
+    }
+    const after = end + MANAGED_END.length;
+    return `${existing.slice(0, start)}${block}${existing.slice(after)}`;
+}
+export function guardrailPlan(harnesses, profile, repoName, existingAgents, extras = {}, engineVersion = ENGINE_VERSION) {
+    const files = [];
+    files.push({
+        path: ".codictator/config.json",
+        content: configText(harnesses, profile, extras, engineVersion),
+    });
+    files.push({ path: "AGENTS.md", content: withManagedBlock(existingAgents) });
+    const workflow = renderWorkflow(repoName);
+    files.push({
+        path: ".github/workflows/codictator.yml",
+        content: workflow.text ?? "",
+    });
+    for (const hook of HOOK_NAMES) {
+        files.push({
+            path: `${EXPECTED_HOOKS_PATH}/${hook}`,
+            content: renderHookScript(hook),
+        });
+    }
+    const plan = hookInstallPlan({});
+    files.push({
+        path: `${EXPECTED_HOOKS_PATH}/.gitattributes`,
+        content: plan.gitattributes,
+    });
+    files.push({ path: ".codictator/bin/run.mjs", content: LAUNCHER_TEXT });
+    return { files };
+}
+export async function writePlan(root, plan, engineVersion = ENGINE_VERSION) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return err(ports.error);
+    }
+    const written = [];
+    for (const file of plan.files) {
+        const done = await ports.value.fs.write(file.path, encode(file.content));
+        if (!done.ok) {
+            return err(done.error);
+        }
+        written.push({
+            path: file.path,
+            hash: sha256Text(normalizeText(file.content)),
+        });
+    }
+    const manifest = buildManifest(engineVersion, written.map((entry) => ({
+        path: entry.path,
+        owner: "codictator",
+        mode: "file",
+        hash: entry.hash,
+    })));
+    const saved = await ports.value.fs.write(".codictator/manifest.json", encode(`${stableStringify(manifest)}\n`));
+    if (!saved.ok) {
+        return err(saved.error);
+    }
+    return ok(written);
+}

package/dist/cli/proofs-test.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleTestCmd(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/proofs-test.js

@@ -0,0 +1,77 @@
+// SPEC §4.10.2: red and green proofs attach the HEAD commit and tree to the
+// task; the declared tests must have executed (titles listed on the command).
+import { parseArgs } from "node:util";
+import { ok } from "../kernel/index.js";
+import { fail, needTaskRoot, portsFor, printHuman, usageError, } from "./shared.js";
+import { readTask, writeTask } from "./tasks.js";
+async function recordProof(req, root, kind, titles, task) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const head = await ports.value.proc.run(["git", "rev-parse", "HEAD"], {
+        cwd: root,
+        env: {},
+        timeoutMs: 15000,
+        maxOutputBytes: 4096,
+    });
+    const tree = await ports.value.proc.run(["git", "rev-parse", "HEAD^{tree}"], {
+        cwd: root,
+        env: {},
+        timeoutMs: 15000,
+        maxOutputBytes: 4096,
+    });
+    if (head.code !== 0 || tree.code !== 0) {
+        return fail("CDX-E703", "cannot read the HEAD commit or tree", "Commit first, then retry.", req.json);
+    }
+    const now = ports.value.clock.now();
+    const proved = kind === "red"
+        ? {
+            ...task,
+            redProof: {
+                commit: head.stdout.trim(),
+                tree: tree.stdout.trim(),
+                failing: [...titles],
+                at: now,
+            },
+        }
+        : { ...task, greenProof: { at: now, tree: tree.stdout.trim() } };
+    const saved = await writeTask(root, proved);
+    if (!saved.ok) {
+        return saved;
+    }
+    printHuman(`recorded ${kind} proof for ${task.id}`, req.quiet);
+    return ok(0);
+}
+export async function handleTestCmd(req) {
+    const kind = req.args[0] ?? "";
+    if (kind !== "red" && kind !== "green") {
+        return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+    }
+    let taskId = "";
+    let titles = [];
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { task: { type: "string" } },
+            allowPositionals: true,
+        });
+        taskId = parsed.values.task ?? "";
+        titles = [...parsed.positionals];
+        if (taskId === "" || titles.length === 0) {
+            return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+        }
+    }
+    catch {
+        return usageError("usage: codictator test <red|green> --task <T-####> [<test title> ...]");
+    }
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const task = await readTask(root, taskId);
+    if (task === undefined) {
+        return fail("CDX-E903", `no task record for "${taskId}"`, "Create it with codictator task new, then retry.", req.json);
+    }
+    return recordProof(req, root, kind, titles, task);
+}

package/dist/cli/proofs.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleReview(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/proofs.js

@@ -0,0 +1,168 @@
+// SPEC §4.12.4: review rounds. Submit validates the findings file and
+// verdicts it; resolve reports the still-open blockers and majors. Rounds
+// bind the staged tree and the reviewer session on the task record.
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { checkReview } from "../features/workflow/index.js";
+import { NodeFs, ok, parseJson } from "../kernel/index.js";
+import { fail, loadRepoConfig, needTaskRoot, portsFor, printHuman, printJson, readStateText, usageError, } from "./shared.js";
+import { readTask, writeTask } from "./tasks.js";
+function parseReviewArgs(req) {
+    try {
+        const parsed = parseArgs({
+            args: [...req.args.slice(1)],
+            options: { file: { type: "string" }, task: { type: "string" } },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        if ((parsed.values.file ?? "") === "") {
+            return undefined;
+        }
+        return { file: parsed.values.file ?? "", taskId: parsed.values.task };
+    }
+    catch {
+        return undefined;
+    }
+}
+// SPEC §4.12.4: absolute --file inputs are canonicalized before the
+// root-prefix comparison, so symlinked checkouts (macOS /var to
+// /private/var, Windows SUBST drives) compare canonical against canonical.
+// The root is already canonical via resolveRepoRoot; only the kernel
+// touches node:fs (§10.3 item 3), so the input goes through NodeFs the same
+// way the hook runtime's canonicalRoot does. Inputs that do not resolve
+// keep their spelling and fail closed downstream as CDX-E607.
+async function canonicalDir(dir) {
+    const made = await NodeFs.create({ root: dir });
+    if (!made.ok) {
+        return dir;
+    }
+    const real = await made.value.realpath(".");
+    if (!real.ok) {
+        return dir;
+    }
+    return real.value;
+}
+async function readFindingsFile(root, file) {
+    if (!path.isAbsolute(file)) {
+        return readStateText(root, file);
+    }
+    const realRoot = await canonicalDir(root);
+    const realFile = path.join(await canonicalDir(path.dirname(file)), path.basename(file));
+    const rel = path.relative(realRoot, realFile);
+    if (rel === "" ||
+        rel === ".." ||
+        rel.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(rel)) {
+        return undefined;
+    }
+    return readStateText(root, rel);
+}
+function validateFindingsFile(text, file, req) {
+    const parsedJson = parseJson(text);
+    if (!parsedJson.ok ||
+        typeof parsedJson.value !== "object" ||
+        parsedJson.value === null) {
+        return fail("CDX-E607", `review findings file "${file}" is not JSON`, "Fix the file so it matches schema/review-findings.schema.json, then retry.", req.json);
+    }
+    const shaped = parsedJson.value;
+    if (shaped.version !== 1 || !Array.isArray(shaped.findings)) {
+        return fail("CDX-E607", `review findings file "${file}" is invalid`, "Fix the file so it matches schema/review-findings.schema.json, then retry.", req.json);
+    }
+    return {
+        version: 1,
+        findings: shaped.findings,
+        tree: shaped.tree,
+        reviewerSession: shaped.reviewerSession,
+    };
+}
+async function loadFindingsShape(req, root, file) {
+    const loaded = await readFindingsFile(root, file);
+    if (loaded === undefined) {
+        return fail("CDX-E607", `review findings file "${file}" unreadable`, "Point --file at the findings JSON, then retry.", req.json);
+    }
+    return validateFindingsFile(loaded, file, req);
+}
+function printReviewVerdict(req, sub, file, verdict, blockers) {
+    if (req.json) {
+        printJson({ file, findings: verdict.length, blockers });
+        return;
+    }
+    for (const finding of verdict) {
+        printHuman(`${finding.ruleId}  ${finding.message}`, req.quiet);
+    }
+    if (verdict.length === 0) {
+        printHuman(sub === "submit" ? "review submitted: pass" : "review resolved: clean", req.quiet);
+    }
+}
+async function submitReviewRound(root, taskId, shaped, openBlockers, openMajors, now) {
+    const task = await readTask(root, taskId);
+    if (task === undefined) {
+        return;
+    }
+    const rounds = task.reviews ?? [];
+    await writeTask(root, {
+        ...task,
+        reviews: [
+            ...rounds,
+            {
+                round: rounds.length + 1,
+                tree: typeof shaped.tree === "string" ? shaped.tree : "unknown",
+                reviewerSession: typeof shaped.reviewerSession === "string"
+                    ? shaped.reviewerSession
+                    : "cli",
+                identity: "observed",
+                openBlockers,
+                openMajors,
+                acknowledgedExceptions: [],
+                at: now,
+            },
+        ],
+    });
+}
+// SPEC §4.12.4: review rounds bind the staged tree and the reviewer
+// session; submit validates the findings file and verdicts it, resolve
+// reports the still-open blockers and majors.
+export async function handleReview(req) {
+    const sub = req.args[0] ?? "";
+    if (sub !== "submit" && sub !== "resolve") {
+        return usageError("usage: codictator review <submit|resolve> --file <path> [--task <T-####>]");
+    }
+    const parsed = parseReviewArgs(req);
+    if (parsed === undefined) {
+        return usageError("usage: codictator review <submit|resolve> --file <path> [--task <T-####>]");
+    }
+    const root = await needTaskRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const shaped = await loadFindingsShape(req, root, parsed.file);
+    if (!("version" in shaped)) {
+        return shaped;
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    let configHash = "unknown";
+    const configured = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (configured.ok) {
+        configHash = configured.value.effective.configHash;
+    }
+    const verdict = await checkReview({
+        trigger: "pre-tool",
+        scope: { files: [] },
+        now: ports.value.clock.now(),
+        configHash,
+    }, shaped, {});
+    const blockers = verdict.filter((finding) => finding.ruleId === "core/review-blockers" || finding.code === "CDX-E605");
+    printReviewVerdict(req, sub, parsed.file, verdict, blockers.length);
+    if (parsed.taskId !== undefined &&
+        sub === "submit" &&
+        blockers.length === 0) {
+        await submitReviewRound(root, parsed.taskId, shaped, 0, 0, ports.value.clock.now());
+    }
+    return verdict.length === 0 ? ok(0) : ok(1);
+}

package/dist/cli/remediation.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleRemediate(req: CommandRequest): Promise<Result<number>>;