soturail 1.2.0 → 1.5.0

package/dist/core/artifact-registry.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { getWorkspacePaths } from "./config.js";
+export class ArtifactRegistry {
+    paths;
+    constructor(root = process.cwd()) {
+        const workspace = getWorkspacePaths(root);
+        this.paths = {
+            artifacts: workspace.artifactsDir,
+            brain: workspace.brainDir,
+            capabilities: workspace.capabilitiesDir,
+            contracts: workspace.contractsDir,
+            evals: workspace.evalsDir,
+            evidence: workspace.evidenceDir,
+            index: workspace.localIndexDir,
+            knowledge: workspace.knowledgeDir,
+            migrations: workspace.migrationsDir,
+            outcomes: workspace.outcomesDir,
+            raw: workspace.rawDir,
+            receipts: workspace.receiptsDir,
+            runs: workspace.runsDir
+        };
+    }
+    resolve(id, ...segments) {
+        const base = this.paths[id];
+        const target = path.resolve(base, ...segments);
+        const relative = path.relative(base, target);
+        if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            throw new Error(`Artifact path escapes registry root: ${id}`);
+        return target;
+    }
+    entries() {
+        return Object.entries(this.paths).map(([id, value]) => ({ id: id, path: value }));
+    }
+}
+//# sourceMappingURL=artifact-registry.js.map

package/dist/core/artifact-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-registry.js","sourceRoot":"","sources":["../../src/core/artifact-registry.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBhD,MAAM,OAAO,gBAAgB;IACV,KAAK,CAAiC;IAEvD,YAAY,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;QAC9B,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG;YACX,SAAS,EAAE,SAAS,CAAC,YAAY;YACjC,KAAK,EAAE,SAAS,CAAC,QAAQ;YACzB,YAAY,EAAE,SAAS,CAAC,eAAe;YACvC,SAAS,EAAE,SAAS,CAAC,YAAY;YACjC,KAAK,EAAE,SAAS,CAAC,QAAQ;YACzB,QAAQ,EAAE,SAAS,CAAC,WAAW;YAC/B,KAAK,EAAE,SAAS,CAAC,aAAa;YAC9B,SAAS,EAAE,SAAS,CAAC,YAAY;YACjC,UAAU,EAAE,SAAS,CAAC,aAAa;YACnC,QAAQ,EAAE,SAAS,CAAC,WAAW;YAC/B,GAAG,EAAE,SAAS,CAAC,MAAM;YACrB,QAAQ,EAAE,SAAS,CAAC,WAAW;YAC/B,IAAI,EAAE,SAAS,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,EAAkB,EAAE,GAAG,QAAkB;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,EAAE,EAAE,CAAC,CAAC;QAC1J,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACtG,CAAC;CACF"}

package/dist/core/artifact-store.d.ts

@@ -0,0 +1,14 @@
+import type { ZodType } from "zod";
+export interface JsonlReadResult<T> {
+    records: T[];
+    recoveredPartialTail: boolean;
+    corruptLine?: number;
+}
+export declare class ArtifactStore {
+    writeText(filePath: string, content: string): Promise<void>;
+    writeJson<T>(filePath: string, value: T, schema?: ZodType<T>): Promise<void>;
+    appendJsonl(filePath: string, value: unknown): Promise<void>;
+    readJsonl<T>(filePath: string): Promise<JsonlReadResult<T>>;
+    repairJsonl(filePath: string): Promise<JsonlReadResult<unknown>>;
+}
+export declare const artifactStore: ArtifactStore;

package/dist/core/artifact-store.js

@@ -0,0 +1,161 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export class ArtifactStore {
+    async writeText(filePath, content) {
+        await atomicWrite(filePath, Buffer.from(content, "utf8"));
+    }
+    async writeJson(filePath, value, schema) {
+        const validated = schema ? schema.parse(value) : value;
+        await this.writeText(filePath, `${JSON.stringify(validated, null, 2)}\n`);
+    }
+    async appendJsonl(filePath, value) {
+        await withFileLock(filePath, async () => {
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
+            await recoverPartialJsonlTail(filePath);
+            const handle = await fs.open(filePath, "a");
+            try {
+                await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    async readJsonl(filePath) {
+        try {
+            const raw = await fs.readFile(filePath, "utf8");
+            return parseJsonl(raw);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { records: [], recoveredPartialTail: false };
+            throw error;
+        }
+    }
+    async repairJsonl(filePath) {
+        return withFileLock(filePath, async () => {
+            const recoveredPartialTail = await recoverPartialJsonlTail(filePath);
+            const result = await this.readJsonl(filePath);
+            return { ...result, recoveredPartialTail: recoveredPartialTail || result.recoveredPartialTail };
+        });
+    }
+}
+export const artifactStore = new ArtifactStore();
+async function atomicWrite(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await fs.open(temp, "wx", 0o600);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await fs.rename(temp, filePath);
+    }
+    catch (error) {
+        await fs.unlink(temp).catch(() => undefined);
+        throw error;
+    }
+    const directoryHandle = await fs.open(dir, "r").catch(() => null);
+    if (directoryHandle) {
+        try {
+            await directoryHandle.sync().catch(() => undefined);
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+}
+function parseJsonl(raw) {
+    const lines = raw.split(/\r?\n/);
+    const records = [];
+    const hasTerminatingNewline = raw.length === 0 || /\r?\n$/.test(raw);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (!line.trim())
+            continue;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            const isPartialTail = index === lines.length - 1 && !hasTerminatingNewline;
+            if (isPartialTail)
+                return { records, recoveredPartialTail: true };
+            return { records, recoveredPartialTail: false, corruptLine: index + 1 };
+        }
+    }
+    return { records, recoveredPartialTail: false };
+}
+async function recoverPartialJsonlTail(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    if (raw.length === 0 || raw.at(-1) === 0x0a)
+        return false;
+    const lastNewline = raw.lastIndexOf(0x0a);
+    const tail = raw.subarray(lastNewline + 1).toString("utf8");
+    try {
+        JSON.parse(tail);
+        const handle = await fs.open(filePath, "a");
+        try {
+            await handle.writeFile("\n", "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return false;
+    }
+    catch {
+        const handle = await fs.open(filePath, "r+");
+        try {
+            await handle.truncate(lastNewline + 1);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return true;
+    }
+}
+async function withFileLock(filePath, operation) {
+    const lockPath = `${filePath}.lock`;
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    let lock;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            lock = await fs.open(lockPath, "wx", 0o600);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const stat = await fs.stat(lockPath).catch(() => null);
+            if (stat && Date.now() - stat.mtimeMs > 30_000)
+                await fs.unlink(lockPath).catch(() => undefined);
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    if (!lock)
+        throw new Error(`Timed out waiting for artifact writer lock: ${filePath}`);
+    try {
+        return await operation();
+    }
+    finally {
+        await lock.close();
+        await fs.unlink(lockPath).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=artifact-store.js.map

package/dist/core/artifact-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-store.js","sourceRoot":"","sources":["../../src/core/artifact-store.ts"],"names":[],"mappings":"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"}

package/dist/core/capability-registry.d.ts

@@ -0,0 +1,50 @@
+export type CapabilityMaturity = "experimental" | "stable" | "deprecated";
+export type SideEffectScope = "none" | "local-state" | "workspace" | "external";
+export interface CapabilityDefinition {
+    id: string;
+    description: string;
+    maturity: CapabilityMaturity;
+    since: string;
+    cli: {
+        command: string;
+    } | null;
+    mcp: {
+        exposed: boolean;
+        tool?: string;
+    };
+    permissions: {
+        filesystemRead: "none" | "project" | "workspace";
+        filesystemWrite: "none" | "soturail-state" | "project";
+        shell: "none" | "restricted";
+        network: "none" | "optional";
+    };
+    sideEffects: {
+        scope: SideEffectScope;
+        reversible: boolean;
+        consequence: "low" | "medium" | "high";
+    };
+    approvalRequired: boolean;
+    outputs: string[];
+    docs: string[];
+}
+export declare const CAPABILITY_REGISTRY: readonly CapabilityDefinition[];
+export declare function getCapabilityDefinition(id: string): CapabilityDefinition | undefined;
+export declare function capabilityRegistryDigest(): string;
+export interface CapabilityEpoch {
+    schemaVersion: "soturail.capability-epoch.v1";
+    id: string;
+    phase: "plan" | "implement" | "review" | "release";
+    registryDigest: string;
+    capabilityIds: string[];
+    createdAt: string;
+}
+export declare function createCapabilityEpoch(phase: CapabilityEpoch["phase"]): CapabilityEpoch;
+export declare function inspectToolCapabilities(): Promise<Array<{
+    tool: string;
+    version: string;
+    ready: boolean;
+    path: string;
+    provider: string;
+    verification: string;
+    risk: string;
+}>>;

package/dist/core/capability-registry.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const CAPABILITY_REGISTRY = [
+    capability("repo.index", "Build a deterministic local repository map.", "index", "soturail.index", "soturail.repo-map.v1", "local-state"),
+    capability("project.read", "Read non-sensitive project files through WorkspaceGuard.", "read <file>", "soturail.read", "text/plain", "none"),
+    capability("context.pack", "Build a fingerprinted context artifact within a hard budget.", "context build", "soturail.context.pack", "soturail.context-artifact.v1", "local-state"),
+    capability("evidence.collect", "Collect workspace-bound local evidence without executing checks.", "evidence collect", null, "soturail.evidence.provenance.v1", "local-state"),
+    capability("raw.inspect.redacted", "Inspect raw logs with mandatory redaction.", "raw inspect <id> --redacted", "soturail.expand", "text/plain", "none"),
+    capability("command.run", "Execute a user-supplied command through the restricted runner.", "run <command...>", null, "soturail.run.v1", "workspace", true, "high"),
+    capability("governance.evaluate", "Evaluate authority and readiness gates deterministically.", "governance evaluate", null, "soturail.governance.verdict.v1", "none"),
+    capability("contract.verify", "Verify change-contract fidelity, freshness and evidence requirements.", "contract verify <file>", null, "soturail.change-contract.verification.v1", "none")
+];
+export function getCapabilityDefinition(id) {
+    return CAPABILITY_REGISTRY.find((item) => item.id === id);
+}
+export function capabilityRegistryDigest() {
+    return createHash("sha256").update(JSON.stringify(CAPABILITY_REGISTRY)).digest("hex");
+}
+export function createCapabilityEpoch(phase) {
+    const registryDigest = capabilityRegistryDigest();
+    return {
+        schemaVersion: "soturail.capability-epoch.v1",
+        id: `epoch-${phase}-${registryDigest.slice(0, 12)}`,
+        phase,
+        registryDigest,
+        capabilityIds: CAPABILITY_REGISTRY.map((item) => item.id),
+        createdAt: new Date().toISOString()
+    };
+}
+export async function inspectToolCapabilities() {
+    return Promise.all([
+        inspectTool("node", ["--version"], "native-runtime", "low"),
+        inspectTool("npm", ["--version"], "native-package-manager", "medium"),
+        inspectTool("git", ["--version"], "native-vcs", "medium"),
+        inspectTool("cargo", ["--version"], "optional-native", "medium")
+    ]);
+}
+async function inspectTool(tool, args, provider, risk) {
+    try {
+        const [{ stdout }, { stdout: resolved }] = await Promise.all([
+            execFileAsync(tool, args, { timeout: 5000, windowsHide: true, encoding: "utf8" }),
+            execFileAsync(process.platform === "win32" ? "where" : "which", [tool], { timeout: 5000, windowsHide: true, encoding: "utf8" })
+        ]);
+        return { tool, version: stdout.trim(), ready: true, path: resolved.split(/\r?\n/)[0] ?? "UNKNOWN", provider, verification: "executed-version-probe", risk };
+    }
+    catch {
+        return { tool, version: "UNAVAILABLE", ready: false, path: "UNAVAILABLE", provider, verification: "probe-failed", risk };
+    }
+}
+function capability(id, description, command, mcpTool, output, sideEffect, approvalRequired = false, consequence = "low") {
+    return {
+        id,
+        description,
+        maturity: "stable",
+        since: "1.5.0",
+        cli: { command },
+        mcp: mcpTool ? { exposed: true, tool: mcpTool } : { exposed: false },
+        permissions: {
+            filesystemRead: sideEffect === "none" ? "project" : "workspace",
+            filesystemWrite: sideEffect === "none" ? "none" : sideEffect === "workspace" ? "project" : "soturail-state",
+            shell: id === "command.run" ? "restricted" : "none",
+            network: "none"
+        },
+        sideEffects: { scope: sideEffect, reversible: sideEffect !== "external", consequence },
+        approvalRequired,
+        outputs: [output],
+        docs: ["docs/architecture/verified-control-plane.md"]
+    };
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/core/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../../src/core/capability-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/change-contract.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { GovernanceVerdict } from "./governance.js";
+export declare const ChangeContractSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"soturail.change-contract.v1">;
+    id: z.ZodString;
+    title: z.ZodString;
+    intent: z.ZodString;
+    risk: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    workspaceFingerprint: z.ZodString;
+    decisions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        decision: z.ZodString;
+        rationale: z.ZodString;
+    }, z.core.$strip>>;
+    acceptanceCriteria: z.ZodArray<z.ZodString>;
+    requiredChecks: z.ZodArray<z.ZodString>;
+    evidencePolicy: z.ZodObject<{
+        runtimeEvidenceRequired: z.ZodBoolean;
+        independentReviewRequired: z.ZodBoolean;
+        humanApprovalRequired: z.ZodBoolean;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type ChangeContract = z.infer<typeof ChangeContractSchema>;
+export interface ReadinessSnapshot {
+    workspaceFingerprint: string;
+    acceptanceCriteriaPassed: string[];
+    checksPassed: string[];
+    evidenceFreshness: "current" | "stale" | "unknown";
+    runtimeEvidence: boolean;
+    independentReview: boolean;
+    humanApproval: boolean;
+    blockers: string[];
+}
+export interface ReadinessVerdict {
+    schemaVersion: "soturail.readiness.verdict.v1";
+    verdict: "ready" | "not-ready";
+    reasons: string[];
+    evaluatedAt: string;
+}
+export interface DualGateVerdict {
+    schemaVersion: "soturail.dual-gate.v1";
+    authority: GovernanceVerdict["verdict"];
+    readiness: ReadinessVerdict["verdict"];
+    verdict: "allow" | "deny";
+    reasons: string[];
+}
+export declare function createChangeContract(input: Omit<ChangeContract, "schemaVersion" | "workspaceFingerprint" | "createdAt">, root?: string): Promise<ChangeContract>;
+export declare function evaluateReadiness(contract: ChangeContract, snapshot: ReadinessSnapshot): ReadinessVerdict;
+export declare function evaluateDualGate(authority: GovernanceVerdict, readiness: ReadinessVerdict): DualGateVerdict;
+export declare function changeContractDigest(contract: ChangeContract): string;

package/dist/core/change-contract.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { createWorkspaceFingerprint } from "./workspace-fingerprint.js";
+export const ChangeContractSchema = z.object({
+    schemaVersion: z.literal("soturail.change-contract.v1"),
+    id: z.string().min(1),
+    title: z.string().min(1),
+    intent: z.string().min(1),
+    risk: z.enum(["low", "medium", "high", "critical"]),
+    workspaceFingerprint: z.string().min(1),
+    decisions: z.array(z.object({ id: z.string().min(1), decision: z.string().min(1), rationale: z.string().min(1) })),
+    acceptanceCriteria: z.array(z.string().min(1)).min(1),
+    requiredChecks: z.array(z.string().min(1)),
+    evidencePolicy: z.object({ runtimeEvidenceRequired: z.boolean(), independentReviewRequired: z.boolean(), humanApprovalRequired: z.boolean() }),
+    createdAt: z.string().datetime()
+});
+export async function createChangeContract(input, root = process.cwd()) {
+    const workspace = await createWorkspaceFingerprint(root);
+    return ChangeContractSchema.parse({ ...input, schemaVersion: "soturail.change-contract.v1", workspaceFingerprint: workspace.fingerprint, createdAt: new Date().toISOString() });
+}
+export function evaluateReadiness(contract, snapshot) {
+    const reasons = [...snapshot.blockers];
+    if (contract.workspaceFingerprint !== snapshot.workspaceFingerprint)
+        reasons.push("Contract workspace fingerprint is stale.");
+    if (snapshot.evidenceFreshness !== "current")
+        reasons.push(`Evidence freshness is ${snapshot.evidenceFreshness}.`);
+    for (const criterion of contract.acceptanceCriteria)
+        if (!snapshot.acceptanceCriteriaPassed.includes(criterion))
+            reasons.push(`Acceptance criterion not satisfied: ${criterion}`);
+    for (const check of contract.requiredChecks)
+        if (!snapshot.checksPassed.includes(check))
+            reasons.push(`Required check missing: ${check}`);
+    if (contract.evidencePolicy.runtimeEvidenceRequired && !snapshot.runtimeEvidence)
+        reasons.push("Runtime evidence is required.");
+    if (contract.evidencePolicy.independentReviewRequired && !snapshot.independentReview)
+        reasons.push("Independent review is required.");
+    if (contract.evidencePolicy.humanApprovalRequired && !snapshot.humanApproval)
+        reasons.push("Human approval is required.");
+    return { schemaVersion: "soturail.readiness.verdict.v1", verdict: reasons.length === 0 ? "ready" : "not-ready", reasons: reasons.length ? reasons : ["All deterministic readiness requirements passed."], evaluatedAt: new Date().toISOString() };
+}
+export function evaluateDualGate(authority, readiness) {
+    const allow = authority.verdict === "allow" && readiness.verdict === "ready";
+    return {
+        schemaVersion: "soturail.dual-gate.v1",
+        authority: authority.verdict,
+        readiness: readiness.verdict,
+        verdict: allow ? "allow" : "deny",
+        reasons: allow ? ["Authority and readiness gates passed."] : [...authority.reasons, ...readiness.reasons]
+    };
+}
+export function changeContractDigest(contract) {
+    return createHash("sha256").update(canonicalJson(contract)).digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=change-contract.js.map

package/dist/core/change-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-contract.js","sourceRoot":"","sources":["../../src/core/change-contract.ts"],"names":[],"mappings":"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"}

package/dist/core/code-health.js

@@ -19,18 +19,18 @@ const requiredV1Docs = [
     "README.md",
     "ROADMAP.md",
     "CHANGELOG.md",
-    "docs/quickstart.md",
-    "docs/v1-contract.md",
-    "docs/schema-contracts.md",
-    "docs/stable-command-surface.md",
-    "docs/deprecation-policy.md",
-    "docs/migration-v1.md",
-    "docs/agent-hosts.md",
-    "docs/host-matrix-schema.md",
-    "docs/agent-export-contract.md",
-    "docs/mcp-host-manifest.md",
-    "docs/clean-code-guidelines.md",
-    "docs/architecture-boundaries.md"
+    "docs/getting-started/quickstart.md",
+    "docs/reference/contracts/v1-contract.md",
+    "docs/reference/schemas/schema-contracts.md",
+    "docs/reference/commands/stable-command-surface.md",
+    "docs/reference/contracts/deprecation-policy.md",
+    "docs/getting-started/migration-v1.md",
+    "docs/rails/hosts/agent-hosts.md",
+    "docs/reference/schemas/host-matrix-schema.md",
+    "docs/reference/contracts/agent-export-contract.md",
+    "docs/rails/hosts/mcp-host-manifest.md",
+    "docs/architecture/clean-code-guidelines.md",
+    "docs/architecture/architecture-boundaries.md"
 ];
 export async function runCodeHealth(root = process.cwd(), options = {}) {
     const resolvedRoot = path.resolve(root);
@@ -63,6 +63,58 @@ export async function runCodeHealth(root = process.cwd(), options = {}) {
         output: renderQualityOutput("SotuRail code health", report, resolvedRoot, jsonPath, markdownPath)
     };
 }
+async function checkVerifiedControlPlaneInvariants(root) {
+    const findings = [];
+    // Older/minimal fixtures do not model the verified-control-plane surface. Keep
+    // the generic architecture checks compatible while enforcing these invariants
+    // whenever the canonical capability registry is present.
+    if (!existsSync(path.join(root, "src", "core", "capability-registry.ts")))
+        return findings;
+    const packageText = await fs.readFile(path.join(root, "package.json"), "utf8").catch(() => "{}");
+    const packageJson = JSON.parse(packageText);
+    const cargo = await fs.readFile(path.join(root, "native", "soturail-native", "Cargo.toml"), "utf8").catch(() => "");
+    const ci = await fs.readFile(path.join(root, ".github", "workflows", "ci.yml"), "utf8").catch(() => "");
+    const mcpServer = await fs.readFile(path.join(root, "src", "core", "mcp-server.ts"), "utf8").catch(() => "");
+    const mcpTools = await fs.readFile(path.join(root, "src", "core", "mcp-tools.ts"), "utf8").catch(() => "");
+    const config = await fs.readFile(path.join(root, "src", "core", "config.ts"), "utf8").catch(() => "");
+    const guardedModules = ["src/commands/read.ts", "src/core/mcp-tools.ts", "src/core/knowledge-rail.ts", "src/core/raw-store.ts"];
+    const criticalStores = ["src/core/context-pack.ts", "src/core/evidence-provenance.ts", "src/core/knowledge-rail.ts", "src/core/run-workspace.ts"];
+    if (!packageJson.dependencies?.["@modelcontextprotocol/server"]?.startsWith("^2") && packageJson.dependencies?.["@modelcontextprotocol/server"] !== "2.0.0") {
+        findings.push(finding("mcp_official_sdk", "control_plane_invariant", "blocking", "package.json", undefined, "Official MCP server SDK v2 is required."));
+    }
+    if (!mcpServer.includes("@modelcontextprotocol/server") || !mcpServer.includes("2026-07-28")) {
+        findings.push(finding("mcp_modern_protocol", "control_plane_invariant", "blocking", "src/core/mcp-server.ts", undefined, "MCP must use the official SDK and declare the stable modern protocol revision."));
+    }
+    if (/allow_raw|allowRaw/.test(mcpTools)) {
+        findings.push(finding("mcp_raw_self_authorization", "control_plane_invariant", "blocking", "src/core/mcp-tools.ts", undefined, "MCP must not accept caller-controlled raw disclosure authorization."));
+    }
+    if (!mcpTools.includes("capabilityId") || !mcpTools.includes("getCapabilityDefinition")) {
+        findings.push(finding("mcp_capability_registry", "control_plane_invariant", "blocking", "src/core/mcp-tools.ts", undefined, "MCP tools must map to the canonical capability registry."));
+    }
+    if (!config.includes('evalsDir: path.resolve(workspace, "evals")')) {
+        findings.push(finding("evals_canonical_path", "control_plane_invariant", "blocking", "src/core/config.ts", undefined, "The canonical evaluation artifact directory must remain evals/."));
+    }
+    const nodeRange = packageJson.engines?.node ?? "";
+    if (!/>=22/.test(nodeRange))
+        findings.push(finding("node_eol_baseline", "control_plane_invariant", "blocking", "package.json", undefined, "Node baseline must exclude EOL Node 20 and require Node 22 or newer."));
+    if (!/node:\s*\[22, 24\]/.test(ci) || /node:\s*\[[^\]]*20/.test(ci))
+        findings.push(finding("ci_node_lts", "control_plane_invariant", "blocking", ".github/workflows/ci.yml", undefined, "CI must test maintained Node 22 and 24 LTS baselines without Node 20."));
+    const cargoVersion = /^version\s*=\s*"([^"]+)"/m.exec(cargo)?.[1];
+    const cargoLicense = /^license\s*=\s*"([^"]+)"/m.exec(cargo)?.[1];
+    if (cargoVersion !== packageJson.version || cargoLicense !== "Apache-2.0")
+        findings.push(finding("native_metadata_sync", "control_plane_invariant", "blocking", "native/soturail-native/Cargo.toml", undefined, "Native version/license must match the package release and Apache-2.0 repository license."));
+    for (const relative of guardedModules) {
+        const text = await fs.readFile(path.join(root, relative), "utf8").catch(() => "");
+        if (!text.includes("WorkspaceGuard"))
+            findings.push(finding("workspace_guard_missing", "control_plane_invariant", "blocking", relative, undefined, "Caller-controlled filesystem paths must pass through WorkspaceGuard."));
+    }
+    for (const relative of criticalStores) {
+        const text = await fs.readFile(path.join(root, relative), "utf8").catch(() => "");
+        if (!text.includes("artifactStore") && !text.includes("writeJson"))
+            findings.push(finding("artifact_store_missing", "control_plane_invariant", "blocking", relative, undefined, "Critical artifacts must use the atomic ArtifactStore path."));
+    }
+    return findings;
+}
 export async function runArchitectureCheck(root = process.cwd(), options = {}) {
     const resolvedRoot = path.resolve(root);
     const files = await listFiles(resolvedRoot, ["src"], [".ts"]);
@@ -78,6 +130,7 @@ export async function runArchitectureCheck(root = process.cwd(), options = {}) {
             findings.push(finding("command_business_logic", "architecture_boundary", "warning", relative, 1, "Command file is large; keep CLI parsing in commands/ and move domain logic to core/."));
         }
     }
+    findings.push(...await checkVerifiedControlPlaneInvariants(resolvedRoot));
     const report = makeArchitectureReport(files.length, findings, options.strict === true);
     const dir = path.join(getWorkspacePaths(resolvedRoot).workspace, "architecture");
     const jsonPath = path.join(dir, "check.json");
@@ -177,12 +230,12 @@ async function checkScopeContamination(root) {
     const files = [
         "README.md",
         "ROADMAP.md",
-        "docs/quickstart.md",
-        "docs/v1-contract.md",
-        "docs/schema-contracts.md",
-        "docs/stable-command-surface.md",
-        "docs/migration-v1.md",
-        "docs/future-rails-index.md"
+        "docs/getting-started/quickstart.md",
+        "docs/reference/contracts/v1-contract.md",
+        "docs/reference/schemas/schema-contracts.md",
+        "docs/reference/commands/stable-command-surface.md",
+        "docs/getting-started/migration-v1.md",
+        "docs/roadmap/future-rails-index.md"
     ];
     const terms = /\b(SoturAI|trading|finance|backtest)\b/i;
     const findings = [];
@@ -232,7 +285,7 @@ function makeArchitectureReport(filesScanned, findings, strict) {
         nextCommands: [
             "soturail self architecture --check --json",
             "soturail self code-health",
-            "docs/architecture-boundaries.md"
+            "docs/architecture/architecture-boundaries.md"
         ]
     };
 }