soturail 0.7.0 → 0.8.0

package/dist/core/project-brain.js

@@ -0,0 +1,790 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { appendJsonl, ensureWorkspace, getWorkspacePaths, readJsonl, relativeToRoot, writeJson } from "./config.js";
+import { getAgentCapability, listAgentCapabilities } from "./agent-runtime.js";
+import { keywordScore, makeRailId, sha256Text, summarizeText } from "./rail-utils.js";
+import { SOTURAIL_VERSION } from "./version.js";
+const execFileAsync = promisify(execFile);
+export async function initBrain(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    await Promise.all([
+        fs.mkdir(paths.brainDir, { recursive: true }),
+        fs.mkdir(paths.brainExportsDir, { recursive: true }),
+        fs.mkdir(paths.brainSpecsDir, { recursive: true })
+    ]);
+    await Promise.all([
+        writeFileIfMissing(paths.brainClaimsFile, ""),
+        writeFileIfMissing(paths.brainDecisionsFile, ""),
+        writeFileIfMissing(paths.brainBugsFile, ""),
+        writeFileIfMissing(paths.brainGapsFile, ""),
+        writeFileIfMissing(paths.brainRulesFile, ""),
+        writeFileIfMissing(paths.brainStaleEventsFile, "")
+    ]);
+    const now = new Date().toISOString();
+    const counts = await brainCounts(root);
+    await writeJsonIfMissing(paths.brainProjectProfileFile, defaultProfile(root, counts, now));
+    await writeJsonIfMissing(paths.brainArchitectureFile, defaultArchitecture(root, now));
+    await writeJsonIfMissing(paths.brainIndexFile, { schemaVersion: "soturail.brain.index.v1", updatedAt: now, claims: [], decisions: [], gaps: [], rules: [] });
+    await writeJsonIfMissing(paths.brainFreshnessFile, { schemaVersion: "soturail.brain.freshness.v1", updatedAt: now, checkedRecords: 0, suspect: 0, stale: 0, warnings: [], events: [] });
+    const createdPaths = [
+        paths.brainDir,
+        paths.brainExportsDir,
+        paths.brainClaimsFile,
+        paths.brainDecisionsFile,
+        paths.brainBugsFile,
+        paths.brainGapsFile,
+        paths.brainRulesFile,
+        paths.brainStaleEventsFile,
+        paths.brainProjectProfileFile,
+        paths.brainArchitectureFile,
+        paths.brainIndexFile,
+        paths.brainFreshnessFile
+    ].map((filePath) => relativeToRoot(root, filePath));
+    return {
+        paths: createdPaths,
+        output: [
+            "SotuRail brain init",
+            `brain_dir: ${relativeToRoot(root, paths.brainDir)}`,
+            `exports_dir: ${relativeToRoot(root, paths.brainExportsDir)}`,
+            `claims: ${relativeToRoot(root, paths.brainClaimsFile)}`,
+            `profile: ${relativeToRoot(root, paths.brainProjectProfileFile)}`,
+            "next_commands:",
+            "- soturail brain scan",
+            "- soturail brain profile",
+            "- soturail brain doctor",
+            "- soturail brain export --agent codex"
+        ].join("\n") + "\n"
+    };
+}
+export async function scanBrain(root = process.cwd()) {
+    await initBrain(root);
+    const now = new Date().toISOString();
+    const paths = getWorkspacePaths(root);
+    const packageJson = await readPackageJson(root);
+    const tests = await listRelativeFiles(path.join(root, "tests"), root, (file) => file.endsWith(".test.ts"));
+    const docsFolders = await listDocsFolders(root);
+    const commands = await detectCliCommands(root);
+    const rails = await detectRails(root);
+    const claims = await scanClaims(root, now);
+    const added = await appendRecordsIfNew(paths.brainClaimsFile, claims);
+    const failures = await readJsonl(paths.harnessFailuresFile);
+    await appendRecordsIfNew(paths.brainBugsFile, failures.map((failure) => ({
+        schemaVersion: "soturail.brain.bug.v1",
+        id: makeRailId("bug", `${failure.id}:${failure.whatFailed}`),
+        bug: failure.whatFailed,
+        status: "recurring",
+        sourcePath: ".soturail/harness/failures.jsonl",
+        tags: ["harness", failure.preventionCandidate.replace(/\s+/g, "-")],
+        createdAt: now
+    })));
+    const counts = await brainCounts(root);
+    const releaseNotesPath = packageJson.version ? path.join("docs", "releases", `RELEASE_NOTES_v${packageJson.version}.md`) : "unknown";
+    const profile = {
+        schemaVersion: "soturail.brain.project-profile.v1",
+        projectName: packageJson.name ?? path.basename(root),
+        packageVersion: packageJson.version ?? "unknown",
+        cliVersion: SOTURAIL_VERSION,
+        identity: "Local-first Context OS for AI coding agents.",
+        mainLanguageRuntime: ["TypeScript", "Node >=20", "optional Rust/native"],
+        docsFolders,
+        releaseNotesPath,
+        rails,
+        commands,
+        tests,
+        workflowHarnessDiagramEval: {
+            workflow: await exists(paths.workflowsDir) ? "present" : "missing",
+            harness: await exists(paths.harnessDir) ? "present" : "missing",
+            diagram: await exists(paths.diagramsDir) ? "present" : "missing",
+            eval: await exists(path.join(paths.workspace, "eval", "latest.json")) ? "latest report present" : "no latest report"
+        },
+        agentHosts: listAgentCapabilities().map((capability) => capability.id),
+        knownReleaseProcess: ["npm run typecheck", "npm run build", "npm test", "npm run release:check", "tag/release after checks", "npm publish only after release gates"],
+        counts,
+        updatedAt: now
+    };
+    await writeJson(paths.brainProjectProfileFile, profile);
+    await writeJson(paths.brainArchitectureFile, defaultArchitecture(root, now));
+    await writeBrainIndex(root);
+    return {
+        profile,
+        claimsAdded: added,
+        output: [
+            "SotuRail brain scan",
+            `project: ${profile.projectName}`,
+            `package_version: ${profile.packageVersion}`,
+            `cli_version: ${profile.cliVersion}`,
+            `claims_added: ${added}`,
+            `claims_total: ${counts.claims}`,
+            `release_notes_path: ${profile.releaseNotesPath}`,
+            `rails: ${rails.join(", ")}`,
+            `commands_detected: ${commands.length}`,
+            `tests_detected: ${tests.length}`,
+            "next_commands:",
+            "- soturail brain recall \"release notes\"",
+            "- soturail rules from-brain",
+            "- soturail reverse gaps"
+        ].join("\n") + "\n"
+    };
+}
+export async function brainProfile(root = process.cwd()) {
+    await ensureProfile(root);
+    const paths = getWorkspacePaths(root);
+    const profile = JSON.parse(await fs.readFile(paths.brainProjectProfileFile, "utf8"));
+    const counts = await brainCounts(root);
+    return [
+        "SotuRail brain profile",
+        `project: ${profile.projectName}`,
+        `package_version: ${profile.packageVersion}`,
+        `cli_version: ${profile.cliVersion}`,
+        `identity: ${profile.identity}`,
+        `main_runtime: ${profile.mainLanguageRuntime.join(", ")}`,
+        `release_notes_path: ${profile.releaseNotesPath}`,
+        `rails: ${profile.rails.join(", ")}`,
+        `workflow_support: ${profile.workflowHarnessDiagramEval.workflow}`,
+        `diagram_support: ${profile.workflowHarnessDiagramEval.diagram}`,
+        `eval_support: ${profile.workflowHarnessDiagramEval.eval}`,
+        `claims: ${counts.claims}`,
+        `gaps: ${counts.gaps}`,
+        `suspect_or_stale: ${counts.suspectOrStale}`,
+        "next_commands:",
+        "- soturail brain stale",
+        "- soturail brain export --agent generic",
+        "- soturail reverse specs ./src"
+    ].join("\n") + "\n";
+}
+export async function recallBrain(query, root = process.cwd(), limit = 8) {
+    await ensureProfile(root);
+    const records = await allRecallRecords(root);
+    const scored = records
+        .map((record) => {
+        const text = recallText(record);
+        const score = keywordScore(query, `${text} ${record.tags.join(" ")}`);
+        const exact = text.toLowerCase().includes(query.toLowerCase());
+        const statusBoost = statusScore(record.status);
+        const confidenceBoost = confidenceScore(record.confidence);
+        return {
+            ...record,
+            score: score.score + statusBoost + confidenceBoost + (exact ? 8 : 0),
+            reason: [exact ? "exact phrase" : score.reason, `status ${record.status}`, record.confidence ? `confidence ${record.confidence}` : ""].filter(Boolean).join(", ")
+        };
+    })
+        .filter((record) => record.score > 0)
+        .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+        .slice(0, limit);
+    return [
+        "SotuRail brain recall",
+        `query: ${query}`,
+        `matches_count: ${scored.length}`,
+        "",
+        ...scored.flatMap((record) => [
+            `- ${record.id} [${record.type}] score ${record.score.toFixed(2)}`,
+            `  Status/confidence: ${record.status}${record.confidence ? ` / ${record.confidence}` : ""}`,
+            `  Source: ${record.sourcePath || "unknown"}`,
+            `  Reason: ${record.reason}`,
+            `  Text: ${summarizeText(recallText(record), 220)}`,
+            ""
+        ])
+    ].join("\n").trimEnd() + "\n";
+}
+export async function staleBrain(root = process.cwd()) {
+    await initBrain(root);
+    const paths = getWorkspacePaths(root);
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const existingEvents = await readJsonl(paths.brainStaleEventsFile);
+    const warnings = [];
+    const events = [];
+    for (const claim of claims) {
+        const absolute = path.resolve(root, claim.sourcePath);
+        if (!(await exists(absolute))) {
+            events.push(staleEvent(claim.id, "source file missing", claim.rangeHash, "missing", "stale"));
+            continue;
+        }
+        const evidence = await sourceEvidence(root, claim.sourcePath, undefined, claim.sourceRange);
+        if (claim.rangeHash !== evidence.rangeHash) {
+            events.push(staleEvent(claim.id, "rangeHash changed", claim.rangeHash, evidence.rangeHash, "suspect"));
+        }
+        else if (claim.fileHash !== evidence.fileHash) {
+            warnings.push(`${claim.id}: fileHash changed but rangeHash is unchanged`);
+        }
+        for (const validationPath of claim.validatedBy) {
+            if (!(await exists(path.resolve(root, validationPath)))) {
+                events.push(staleEvent(claim.id, `validatedBy missing: ${validationPath}`, claim.rangeHash, "missing-validation", "suspect"));
+            }
+        }
+    }
+    const newEvents = events.filter((event) => !existingEvents.some((existing) => existing.id === event.id));
+    for (const event of newEvents)
+        await appendJsonl(paths.brainStaleEventsFile, event);
+    const freshness = {
+        schemaVersion: "soturail.brain.freshness.v1",
+        updatedAt: new Date().toISOString(),
+        checkedRecords: claims.length,
+        suspect: events.filter((event) => event.status === "suspect").length,
+        stale: events.filter((event) => event.status === "stale").length,
+        warnings,
+        events
+    };
+    await writeJson(paths.brainFreshnessFile, freshness);
+    return {
+        freshness,
+        output: [
+            "SotuRail brain stale",
+            `checked_records: ${freshness.checkedRecords}`,
+            `new_events: ${newEvents.length}`,
+            `suspect: ${freshness.suspect}`,
+            `stale: ${freshness.stale}`,
+            `warnings: ${freshness.warnings.length}`,
+            `freshness: ${relativeToRoot(root, paths.brainFreshnessFile)}`,
+            "",
+            ...(newEvents.length > 0 ? newEvents.map((event) => `- ${event.recordId}: ${event.reason} [${event.status}]`) : ["No stale evidence drift detected."])
+        ].join("\n") + "\n"
+    };
+}
+export async function brainDoctor(root = process.cwd()) {
+    await initBrain(root);
+    const paths = getWorkspacePaths(root);
+    const counts = await brainCounts(root);
+    const jsonlFiles = [
+        paths.brainClaimsFile,
+        paths.brainDecisionsFile,
+        paths.brainBugsFile,
+        paths.brainGapsFile,
+        paths.brainRulesFile,
+        paths.brainStaleEventsFile
+    ];
+    const files = [];
+    for (const filePath of jsonlFiles) {
+        files.push({ path: relativeToRoot(root, filePath), present: await exists(filePath), validJsonl: await validJsonl(filePath) });
+    }
+    for (const filePath of [paths.brainProjectProfileFile, paths.brainIndexFile, paths.brainFreshnessFile]) {
+        files.push({ path: relativeToRoot(root, filePath), present: await exists(filePath) });
+    }
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const findings = [
+        ...(claims.some((claim) => !claim.sourcePath) ? ["Some claims are missing source paths."] : []),
+        ...(claims.some((claim) => claim.status === "verified" && claim.validatedBy.length === 0) ? ["Some verified claims have no validation references."] : []),
+        ...(counts.gaps > 0 ? [`Open gaps recorded: ${counts.gaps}`] : []),
+        ...(counts.suspectOrStale > 0 ? [`Suspect or stale records/events: ${counts.suspectOrStale}`] : []),
+        ...(await exists(path.join(paths.brainExportsDir, "agent-brief.md")) ? [] : ["Agent brief export is missing."])
+    ];
+    const report = {
+        schemaVersion: "soturail.brain.doctor.v1",
+        ok: files.every((file) => file.present && file.validJsonl !== false),
+        createdAt: new Date().toISOString(),
+        files,
+        counts,
+        findings,
+        nextCommands: ["soturail brain scan", "soturail brain stale", "soturail brain export --agent generic", "soturail rules from-brain"]
+    };
+    await writeJson(paths.brainDoctorFile, report);
+    return {
+        report,
+        output: [
+            "SotuRail brain doctor",
+            `ok: ${report.ok}`,
+            `claims: ${counts.claims}`,
+            `decisions: ${counts.decisions}`,
+            `bugs: ${counts.bugs}`,
+            `gaps: ${counts.gaps}`,
+            `rules: ${counts.rules}`,
+            `stale_events: ${counts.staleEvents}`,
+            `doctor_json: ${relativeToRoot(root, paths.brainDoctorFile)}`,
+            "",
+            "Files:",
+            ...files.map((file) => `- ${file.path}: ${file.present ? "present" : "missing"}${file.validJsonl === undefined ? "" : `, jsonl_valid=${file.validJsonl}`}`),
+            "",
+            "Findings:",
+            ...(findings.length > 0 ? findings.map((finding) => `- ${finding}`) : ["- none"]),
+            "",
+            "Next commands:",
+            ...report.nextCommands.map((command) => `- ${command}`)
+        ].join("\n") + "\n"
+    };
+}
+export async function exportBrain(agent, root = process.cwd()) {
+    await ensureProfile(root);
+    const paths = getWorkspacePaths(root);
+    const profile = JSON.parse(await fs.readFile(paths.brainProjectProfileFile, "utf8"));
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const decisions = await readJsonl(paths.brainDecisionsFile);
+    const gaps = await readJsonl(paths.brainGapsFile);
+    const bugs = await readJsonl(paths.brainBugsFile);
+    const rules = await readJsonl(paths.brainRulesFile);
+    const freshness = await readJson(paths.brainFreshnessFile).catch(() => null);
+    const approvedMemory = await readJsonl(paths.memoryApprovedFile).catch(() => []);
+    const base = renderBrainBrief(agent, profile, claims, decisions, gaps, bugs, rules, freshness, approvedMemory);
+    const content = agent === "claude" ? `<project_brain>\n${base}\n</project_brain>\n` : base;
+    const outputPath = path.join(paths.brainExportsDir, `${agent}.md`);
+    await fs.writeFile(outputPath, content, "utf8");
+    if (agent === "generic")
+        await fs.writeFile(path.join(paths.brainExportsDir, "agent-brief.md"), content, "utf8");
+    return {
+        path: outputPath,
+        content,
+        output: [
+            "SotuRail brain export",
+            `agent: ${agent}`,
+            `path: ${relativeToRoot(root, outputPath)}`,
+            ...(agent === "generic" ? [`generic_alias: ${relativeToRoot(root, path.join(paths.brainExportsDir, "agent-brief.md"))}`] : []),
+            "review_required: true"
+        ].join("\n") + "\n"
+    };
+}
+export async function rulesFromBrain(root = process.cwd()) {
+    await ensureProfile(root);
+    const paths = getWorkspacePaths(root);
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const decisions = await readJsonl(paths.brainDecisionsFile);
+    const now = new Date().toISOString();
+    const rules = [];
+    for (const claim of claims.filter((item) => item.status === "verified").slice(0, 25)) {
+        const ruleText = ruleFromClaim(claim.claim);
+        if (!ruleText)
+            continue;
+        rules.push({
+            schemaVersion: "soturail.brain.rule.v1",
+            id: makeRailId("rule", `${claim.id}:${ruleText}`),
+            rule: ruleText,
+            sourceClaimIds: [claim.id],
+            enforcement: claim.kind === "release" || claim.kind === "security" || claim.kind === "policy" ? "manual-review" : "advisory",
+            status: "active",
+            createdAt: now
+        });
+    }
+    for (const decision of decisions.filter((item) => item.status === "active").slice(0, 10)) {
+        rules.push({
+            schemaVersion: "soturail.brain.rule.v1",
+            id: makeRailId("rule", `${decision.id}:${decision.decision}`),
+            rule: ruleFromDecision(decision),
+            sourceClaimIds: [],
+            sourceDecisionIds: [decision.id],
+            enforcement: "advisory",
+            status: "active",
+            createdAt: now
+        });
+    }
+    await appendRecordsIfNew(paths.brainRulesFile, rules);
+    await fs.mkdir(paths.rulesDir, { recursive: true });
+    const markdownPath = path.join(paths.rulesDir, "from-brain.md");
+    await fs.writeFile(markdownPath, [
+        "# Brain-Derived Rules",
+        "",
+        "These rules are derived from verified Project Brain claims and active decisions. Review before using as policy gates.",
+        "",
+        ...rules.map((rule) => `- ${rule.rule} (sources: ${[...rule.sourceClaimIds, ...(rule.sourceDecisionIds ?? [])].join(", ") || "none"})`),
+        ""
+    ].join("\n"), "utf8");
+    return {
+        rules,
+        markdownPath,
+        output: [
+            "SotuRail rules from-brain",
+            `rules_written: ${rules.length}`,
+            `jsonl: ${relativeToRoot(root, paths.brainRulesFile)}`,
+            `markdown: ${relativeToRoot(root, markdownPath)}`,
+            "review_required: true"
+        ].join("\n") + "\n"
+    };
+}
+export async function readBrainCounts(root = process.cwd()) {
+    return brainCounts(root);
+}
+export async function brainExportExists(root = process.cwd()) {
+    return exists(path.join(getWorkspacePaths(root).brainExportsDir, "agent-brief.md"));
+}
+async function scanClaims(root, now) {
+    const commit = await currentCommit(root);
+    const packageJson = await readPackageJson(root);
+    const claims = [];
+    const add = async (claim, kind, sourcePath, tags, validatedBy = []) => {
+        const evidence = await sourceEvidence(root, sourcePath, claim.split(/\s+/).slice(0, 4).join(" "));
+        claims.push({
+            schemaVersion: "soturail.brain.claim.v1",
+            id: makeRailId("claim", `${kind}:${claim}:${sourcePath}`),
+            claim,
+            kind,
+            status: evidence.exists ? "verified" : "unverified",
+            confidence: evidence.exists ? "high" : "medium",
+            sourcePath,
+            sourceCommit: commit,
+            sourceRange: evidence.sourceRange,
+            fileHash: evidence.fileHash,
+            rangeHash: evidence.rangeHash,
+            validatedBy,
+            relatedWorkflowIds: [],
+            relatedEvidenceIds: [],
+            tags,
+            createdAt: now,
+            updatedAt: now
+        });
+    };
+    if (packageJson.name)
+        await add(`Package name is ${packageJson.name}.`, "architecture", "package.json", ["package", "identity"]);
+    if (packageJson.version)
+        await add(`Package version is ${packageJson.version}.`, "release", "package.json", ["package", "version"], ["tests/soturail.test.ts"]);
+    await add(`CLI version source is ${SOTURAIL_VERSION}.`, "release", "src/core/version.ts", ["cli", "version"], ["tests/soturail.test.ts"]);
+    await add("Release notes live under docs/releases/.", "release", "src/core/release-preflight.ts", ["release", "docs"], ["tests/v070.test.ts"]);
+    await add("SotuRail keeps native acceleration optional.", "architecture", "package.json", ["native", "optional"]);
+    await add("No arbitrary shell execution is exposed through SotuRail MCP by default.", "security", "src/core/agent-runtime.ts", ["mcp", "security"], ["tests/v060.test.ts"]);
+    await add("Workflow Rail stores local workflow evidence under .soturail/workflows/.", "workflow", "src/core/workflow-store.ts", ["workflow", "evidence"], ["tests/v070.test.ts"]);
+    await add("Diagram Rail uses lightweight Mermaid validation and is not a full Mermaid parser.", "docs", "src/core/diagram-validator.ts", ["diagram", "validation"], ["tests/v070.test.ts"]);
+    await add("Evaluation reports are written under .soturail/eval/.", "test", "src/core/evaluation-suite.ts", ["eval", "reports"], ["tests/v061.test.ts"]);
+    for (const command of await detectCliCommands(root)) {
+        await add(`CLI command '${command}' is registered.`, "command", "src/cli.ts", ["command", command]);
+    }
+    for (const capability of listAgentCapabilities()) {
+        await add(`Agent host '${capability.id}' supports ${capability.promptOnlyFallback} prompt-only fallback.`, "agent", "src/core/agent-runtime.ts", ["agent", capability.id]);
+    }
+    return claims;
+}
+async function writeBrainIndex(root) {
+    const paths = getWorkspacePaths(root);
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const decisions = await readJsonl(paths.brainDecisionsFile);
+    const gaps = await readJsonl(paths.brainGapsFile);
+    const rules = await readJsonl(paths.brainRulesFile);
+    const index = {
+        schemaVersion: "soturail.brain.index.v1",
+        updatedAt: new Date().toISOString(),
+        claims: claims.map((claim) => ({ id: claim.id, kind: claim.kind, status: claim.status, sourcePath: claim.sourcePath, tags: claim.tags })),
+        decisions: decisions.map((decision) => ({ id: decision.id, status: decision.status, sourcePath: decision.sourcePath, tags: decision.tags })),
+        gaps: gaps.map((gap) => ({ id: gap.id, severity: gap.severity, status: gap.status, sourcePath: gap.sourcePath })),
+        rules: rules.map((rule) => ({ id: rule.id, status: rule.status, sourceClaimIds: rule.sourceClaimIds }))
+    };
+    await writeJson(paths.brainIndexFile, index);
+}
+async function brainCounts(root) {
+    const paths = getWorkspacePaths(root);
+    const claims = await readJsonl(paths.brainClaimsFile);
+    const gaps = await readJsonl(paths.brainGapsFile);
+    const staleEvents = await readJsonl(paths.brainStaleEventsFile);
+    return {
+        claims: claims.length,
+        decisions: (await readJsonl(paths.brainDecisionsFile)).length,
+        bugs: (await readJsonl(paths.brainBugsFile)).length,
+        gaps: gaps.filter((gap) => gap.status === "open").length,
+        rules: (await readJsonl(paths.brainRulesFile)).length,
+        staleEvents: staleEvents.length,
+        suspectOrStale: claims.filter((claim) => claim.status === "suspect" || claim.status === "stale").length + staleEvents.filter((event) => event.status !== "resolved").length
+    };
+}
+function defaultProfile(root, counts, now) {
+    return {
+        schemaVersion: "soturail.brain.project-profile.v1",
+        projectName: path.basename(root),
+        packageVersion: "unknown",
+        cliVersion: SOTURAIL_VERSION,
+        identity: "Local-first Context OS for AI coding agents.",
+        mainLanguageRuntime: ["TypeScript", "Node >=20"],
+        docsFolders: [],
+        releaseNotesPath: "unknown",
+        rails: [],
+        commands: [],
+        tests: [],
+        workflowHarnessDiagramEval: {},
+        agentHosts: [],
+        knownReleaseProcess: [],
+        counts,
+        updatedAt: now
+    };
+}
+function defaultArchitecture(root, now) {
+    return {
+        schemaVersion: "soturail.brain.architecture.v1",
+        storage: {
+            jsonl: [
+                ".soturail/brain/claims.jsonl",
+                ".soturail/brain/decisions.jsonl",
+                ".soturail/brain/bugs.jsonl",
+                ".soturail/brain/gaps.jsonl",
+                ".soturail/brain/rules.jsonl",
+                ".soturail/brain/stale-events.jsonl"
+            ],
+            jsonViews: [
+                ".soturail/brain/project-profile.json",
+                ".soturail/brain/architecture.json",
+                ".soturail/brain/brain-index.json",
+                ".soturail/brain/freshness.json",
+                ".soturail/brain/doctor.json"
+            ],
+            exports: [relativeToRoot(root, path.join(getWorkspacePaths(root).brainExportsDir, "agent-brief.md"))]
+        },
+        rails: [
+            { name: "Memory", evidence: ".soturail/memory/" },
+            { name: "Workflow", evidence: ".soturail/workflows/" },
+            { name: "Harness", evidence: ".soturail/harness/" },
+            { name: "Diagram", evidence: ".soturail/diagrams/ and docs/diagrams/" },
+            { name: "Evaluation", evidence: ".soturail/eval/" }
+        ],
+        boundaries: ["no external LLM calls", "no embeddings required", "no cloud service", "agent-safe exports are reviewed Markdown/tagged context"],
+        updatedAt: now
+    };
+}
+async function sourceEvidence(root, relativePath, needle, forcedRange) {
+    const absolute = path.resolve(root, relativePath);
+    const raw = await fs.readFile(absolute, "utf8").catch(() => "");
+    if (!raw)
+        return { exists: false, sourceRange: { startLine: 1, endLine: 1 }, fileHash: "sha256-missing", rangeHash: "sha256-missing" };
+    const lines = raw.split(/\r?\n/);
+    let startLine = forcedRange?.startLine ?? 1;
+    let endLine = forcedRange?.endLine ?? Math.min(lines.length, 20);
+    if (!forcedRange && needle) {
+        const index = lines.findIndex((line) => line.toLowerCase().includes(needle.toLowerCase().split(/\s+/)[0] ?? needle.toLowerCase()));
+        if (index >= 0) {
+            startLine = index + 1;
+            endLine = Math.min(lines.length, index + 3);
+        }
+    }
+    const rangeText = lines.slice(Math.max(0, startLine - 1), endLine).join("\n");
+    return {
+        exists: true,
+        sourceRange: { startLine, endLine },
+        fileHash: `sha256-${sha256Text(raw)}`,
+        rangeHash: `sha256-${sha256Text(rangeText)}`
+    };
+}
+function staleEvent(recordId, reason, previousHash, currentHash, status) {
+    return {
+        schemaVersion: "soturail.brain.stale-event.v1",
+        id: makeRailId("stale", `${recordId}:${reason}:${previousHash}:${currentHash}`),
+        recordId,
+        reason,
+        previousHash,
+        currentHash,
+        status,
+        createdAt: new Date().toISOString()
+    };
+}
+async function allRecallRecords(root) {
+    const paths = getWorkspacePaths(root);
+    return [
+        ...(await readJsonl(paths.brainClaimsFile)).map((record) => ({ ...record, type: "claim" })),
+        ...(await readJsonl(paths.brainDecisionsFile)).map((record) => ({ ...record, type: "decision", confidence: "medium" })),
+        ...(await readJsonl(paths.brainBugsFile)).map((record) => ({ ...record, type: "bug", confidence: "medium" })),
+        ...(await readJsonl(paths.brainGapsFile)).map((record) => ({ ...record, type: "gap", confidence: "low", tags: ["gap"], sourcePath: record.sourcePath })),
+        ...(await readJsonl(paths.brainRulesFile)).map((record) => ({ ...record, type: "rule", confidence: "medium", sourcePath: ".soturail/brain/rules.jsonl", tags: ["rule"] }))
+    ];
+}
+function recallText(record) {
+    return record.claim ?? record.decision ?? record.bug ?? record.gap ?? record.rule ?? record.title ?? record.id;
+}
+function statusScore(status) {
+    if (status === "verified" || status === "active" || status === "recurring")
+        return 4;
+    if (status === "unverified" || status === "open")
+        return 2;
+    if (status === "suspect")
+        return 0;
+    if (status === "stale")
+        return -3;
+    return 1;
+}
+function confidenceScore(confidence) {
+    if (confidence === "high")
+        return 3;
+    if (confidence === "medium")
+        return 1;
+    return 0;
+}
+function renderBrainBrief(agent, profile, claims, decisions, gaps, bugs, rules, freshness, approvedMemory) {
+    const capability = getAgentCapability(agent);
+    const verifiedClaims = claims.filter((claim) => claim.status === "verified").slice(0, 12);
+    return [
+        `# SotuRail Project Brain Brief (${agent})`,
+        "",
+        "This brief is evidence-backed local context. Do not overclaim beyond the sources listed here.",
+        "",
+        "## Project Identity",
+        "",
+        `- project: ${profile.projectName}`,
+        `- package_version: ${profile.packageVersion}`,
+        `- cli_version: ${profile.cliVersion}`,
+        `- identity: ${profile.identity}`,
+        `- recommended_payloads: ${capability.recommendedPayloads.join(" + ")}`,
+        "",
+        "## Verified Claims",
+        "",
+        ...(verifiedClaims.length > 0 ? verifiedClaims.map((claim) => `- ${claim.claim} (${claim.id}, source: ${claim.sourcePath}:${claim.sourceRange.startLine})`) : ["- none yet"]),
+        "",
+        "## Active Rules",
+        "",
+        ...nonEmpty(rules.filter((rule) => rule.status === "active").slice(0, 12).map((rule) => `- ${rule.rule} (sources: ${rule.sourceClaimIds.join(", ") || (rule.sourceDecisionIds ?? []).join(", ") || "none"})`), "- none yet"),
+        "",
+        "## Active Decisions",
+        "",
+        ...nonEmpty(decisions.filter((decision) => decision.status === "active").slice(0, 8).map((decision) => `- ${decision.title}: ${decision.decision} (source: ${decision.sourcePath})`), "- none yet"),
+        "",
+        "## Known Gaps",
+        "",
+        ...nonEmpty(gaps.filter((gap) => gap.status === "open").slice(0, 8).map((gap) => `- [${gap.severity}] ${gap.gap} (source: ${gap.sourcePath})`), "- none recorded"),
+        "",
+        "## Recurring Bugs And Harness Notes",
+        "",
+        ...nonEmpty(bugs.slice(0, 8).map((bug) => `- ${bug.bug} (source: ${bug.sourcePath})`), "- none recorded"),
+        "",
+        "## Safe Commands",
+        "",
+        "- soturail brain doctor",
+        "- soturail context budget --explain",
+        "- soturail workflow verify",
+        "- soturail eval run --suite brain",
+        "- npm run release:check",
+        "",
+        "## Release And Workflow Notes",
+        "",
+        `- release_notes_path: ${profile.releaseNotesPath}`,
+        `- workflow: ${profile.workflowHarnessDiagramEval.workflow ?? "unknown"}`,
+        `- harness: ${profile.workflowHarnessDiagramEval.harness ?? "unknown"}`,
+        `- diagram: ${profile.workflowHarnessDiagramEval.diagram ?? "unknown"}`,
+        `- eval: ${profile.workflowHarnessDiagramEval.eval ?? "unknown"}`,
+        "",
+        "## Approved Memory Summary",
+        "",
+        ...(approvedMemory.length > 0 ? approvedMemory.slice(0, 5).map((memory) => `- ${memory.text} (${memory.source})`) : ["- no approved memory exported"]),
+        "",
+        "## Stale Or Suspect Warnings",
+        "",
+        ...(freshness && (freshness.suspect > 0 || freshness.stale > 0) ? freshness.events.slice(0, 8).map((event) => `- ${event.recordId}: ${event.reason} [${event.status}]`) : ["- none from latest freshness check"]),
+        "",
+        "## Safety Notes",
+        "",
+        "- Keep secrets local and redacted.",
+        "- Raw logs need explicit recovery and review.",
+        "- Brain claims are only as fresh as their source hashes.",
+        "- Generated exports should be reviewed before agent handoff.",
+        ""
+    ].join("\n");
+}
+function ruleFromClaim(claim) {
+    if (/release notes live under docs\/releases/i.test(claim))
+        return "Release notes must live under docs/releases/.";
+    if (/release|publish|npm|version|tag/i.test(claim))
+        return `Verify release evidence for: ${claim.replace(/\.$/, "")}.`;
+    if (/arbitrary shell|mcp/i.test(claim))
+        return "Do not expose arbitrary shell execution through MCP.";
+    if (/native/i.test(claim))
+        return "Keep native acceleration optional.";
+    if (/diagram|Mermaid/i.test(claim))
+        return "Do not treat diagram validation as a full Mermaid parser.";
+    return `Preserve evidence for: ${claim.replace(/\.$/, "")}.`;
+}
+function nonEmpty(values, fallback) {
+    return values.length > 0 ? values : [fallback];
+}
+function ruleFromDecision(decision) {
+    return `Follow active decision: ${decision.title}.`;
+}
+async function readPackageJson(root) {
+    const raw = await fs.readFile(path.join(root, "package.json"), "utf8").catch(() => "{}");
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+async function detectCliCommands(root) {
+    const raw = await fs.readFile(path.join(root, "src", "cli.ts"), "utf8").catch(() => "");
+    return [...raw.matchAll(/register([A-Z][A-Za-z]+)Command\(program\)/g)]
+        .map((match) => (match[1] ?? "").replace(/[A-Z]/g, (letter, index) => `${index === 0 ? "" : "-"}${letter.toLowerCase()}`))
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b));
+}
+async function detectRails(root) {
+    const candidates = [
+        ["memory", "src/commands/memory.ts"],
+        ["context", "src/commands/context.ts"],
+        ["workflow", "src/commands/workflow.ts"],
+        ["harness", "src/commands/harness.ts"],
+        ["diagram", "src/commands/diagram.ts"],
+        ["evaluation", "src/commands/eval.ts"],
+        ["agents", "src/commands/agents.ts"],
+        ["rules", "src/commands/rules.ts"],
+        ["brain", "src/commands/brain.ts"],
+        ["reverse", "src/commands/reverse.ts"]
+    ];
+    const present = [];
+    for (const [name, file] of candidates) {
+        if (await exists(path.join(root, file)))
+            present.push(name);
+    }
+    return present;
+}
+async function listDocsFolders(root) {
+    const docsRoot = path.join(root, "docs");
+    const entries = await fs.readdir(docsRoot, { withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join("docs", entry.name).replace(/\\/g, "/")).sort();
+}
+async function listRelativeFiles(dir, root, predicate) {
+    const output = [];
+    async function visit(current) {
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const absolute = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!["node_modules", ".git", "dist", ".soturail"].includes(entry.name))
+                    await visit(absolute);
+                continue;
+            }
+            if (entry.isFile() && predicate(absolute))
+                output.push(relativeToRoot(root, absolute).replace(/\\/g, "/"));
+        }
+    }
+    await visit(dir);
+    return output.sort((a, b) => a.localeCompare(b));
+}
+async function currentCommit(root) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--short", "HEAD"], { cwd: root, timeout: 3000, windowsHide: true });
+        return stdout.trim() || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function appendRecordsIfNew(filePath, records) {
+    const existing = new Set((await readJsonl(filePath)).map((record) => record.id));
+    let added = 0;
+    for (const record of records) {
+        if (existing.has(record.id))
+            continue;
+        await appendJsonl(filePath, record);
+        existing.add(record.id);
+        added += 1;
+    }
+    return added;
+}
+async function ensureProfile(root) {
+    const paths = getWorkspacePaths(root);
+    if (!(await exists(paths.brainProjectProfileFile)))
+        await scanBrain(root);
+}
+async function readJson(filePath) {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+async function validJsonl(filePath) {
+    try {
+        await readJsonl(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeFileIfMissing(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    if (!(await exists(filePath)))
+        await fs.writeFile(filePath, content, "utf8");
+}
+async function writeJsonIfMissing(filePath, value) {
+    if (!(await exists(filePath)))
+        await writeJson(filePath, value);
+}
+async function exists(filePath) {
+    return fs.access(filePath).then(() => true).catch(() => false);
+}
+//# sourceMappingURL=project-brain.js.map