@nimiplatform/nimi-coding 0.1.0

package/cli/lib/contracts.mjs

@@ -0,0 +1,180 @@
+import path from "node:path";
+
+import {
+  loadBlueprintReference as loadBlueprintReferenceInternal,
+  loadCommandGatingMatrix as loadCommandGatingMatrixInternal,
+  loadAuditSweepContract as loadAuditSweepContractInternal,
+  loadDocSpecAuditContract as loadDocSpecAuditContractInternal,
+  loadExternalHostCompatibilityContract as loadExternalHostCompatibilityContractInternal,
+  loadHighRiskAdmissionContract as loadHighRiskAdmissionContractInternal,
+  loadHighRiskExecutionContract as loadHighRiskExecutionContractInternal,
+  loadHighRiskSchemaContracts as loadHighRiskSchemaContractsInternal,
+  loadSpecGenerationAuditContract as loadSpecGenerationAuditContractInternal,
+  loadSpecGenerationInputsConfig as loadSpecGenerationInputsConfigInternal,
+  loadSpecGenerationInputsContract as loadSpecGenerationInputsContractInternal,
+  loadSpecReconstructionContract as loadSpecReconstructionContractInternal,
+  loadSpecTreeModelContract as loadSpecTreeModelContractInternal,
+} from "./internal/contracts-loaders.mjs";
+import { readTextIfFile } from "./fs-helpers.mjs";
+import { parseYamlText } from "./yaml-helpers.mjs";
+import { matchCommandGatingRule } from "./internal/contracts-parse.mjs";
+import {
+  validateAuditSweepSummary as validateAuditSweepSummaryInternal,
+  validateDocSpecAuditSummary as validateDocSpecAuditSummaryInternal,
+  validateHighRiskAdmissionRecord as validateHighRiskAdmissionRecordInternal,
+  validateHighRiskAdmissionsSpec as validateHighRiskAdmissionsSpecInternal,
+  validateHighRiskExecutionSummary as validateHighRiskExecutionSummaryInternal,
+  validateSpecReconstructionSummary as validateSpecReconstructionSummaryInternal,
+} from "./internal/contracts-validators.mjs";
+
+export function findCommandGatingRule(commandGatingMatrix, command, skillId = null) {
+  return matchCommandGatingRule(commandGatingMatrix, command, skillId);
+}
+
+export function loadSpecReconstructionContract(projectRoot) {
+  return loadSpecReconstructionContractInternal(projectRoot);
+}
+
+export function loadSpecTreeModelContract(projectRoot) {
+  return loadSpecTreeModelContractInternal(projectRoot);
+}
+
+export function loadSpecGenerationInputsContract(projectRoot) {
+  return loadSpecGenerationInputsContractInternal(projectRoot);
+}
+
+export function loadSpecGenerationAuditContract(projectRoot) {
+  return loadSpecGenerationAuditContractInternal(projectRoot);
+}
+
+export function loadSpecGenerationInputsConfig(projectRoot) {
+  return loadSpecGenerationInputsConfigInternal(projectRoot);
+}
+
+export function loadCommandGatingMatrix(projectRoot) {
+  return loadCommandGatingMatrixInternal(projectRoot);
+}
+
+export function loadBlueprintReference(projectRoot) {
+  return loadBlueprintReferenceInternal(projectRoot);
+}
+
+export function loadDocSpecAuditContract(projectRoot) {
+  return loadDocSpecAuditContractInternal(projectRoot);
+}
+
+export function loadAuditSweepContract(projectRoot) {
+  return loadAuditSweepContractInternal(projectRoot);
+}
+
+export function loadHighRiskExecutionContract(projectRoot) {
+  return loadHighRiskExecutionContractInternal(projectRoot);
+}
+
+export function loadHighRiskAdmissionContract(projectRoot) {
+  return loadHighRiskAdmissionContractInternal(projectRoot);
+}
+
+export function loadExternalHostCompatibilityContract(projectRoot) {
+  return loadExternalHostCompatibilityContractInternal(projectRoot);
+}
+
+export function loadHighRiskSchemaContracts(projectRoot) {
+  return loadHighRiskSchemaContractsInternal(projectRoot);
+}
+
+export function validateSpecReconstructionSummary(summary, contract, verifiedAt) {
+  return validateSpecReconstructionSummaryInternal(summary, contract, verifiedAt);
+}
+
+export function validateDocSpecAuditSummary(summary, contract, verifiedAt) {
+  return validateDocSpecAuditSummaryInternal(summary, contract, verifiedAt);
+}
+
+export function validateAuditSweepSummary(summary, contract, verifiedAt) {
+  return validateAuditSweepSummaryInternal(summary, contract, verifiedAt);
+}
+
+export function validateHighRiskExecutionSummary(summary, contract, verifiedAt) {
+  return validateHighRiskExecutionSummaryInternal(summary, contract, verifiedAt);
+}
+
+export function validateHighRiskAdmissionRecord(record, contract) {
+  return validateHighRiskAdmissionRecordInternal(record, contract);
+}
+
+export function validateHighRiskAdmissionsSpec(spec, contract) {
+  return validateHighRiskAdmissionsSpecInternal(spec, contract);
+}
+
+async function loadYamlWithFallback(projectRoot, primaryRef, fallbackRef) {
+  const primaryText = await readTextIfFile(path.join(projectRoot, primaryRef));
+  if (primaryText !== null) {
+    return {
+      path: primaryRef,
+      text: primaryText,
+      data: parseYamlText(primaryText),
+    };
+  }
+
+  const fallbackText = await readTextIfFile(path.join(projectRoot, fallbackRef));
+  return {
+    path: fallbackRef,
+    text: fallbackText,
+    data: parseYamlText(fallbackText),
+  };
+}
+
+export async function loadTopicRuntimeContracts(projectRoot) {
+  const [
+    topicSchema,
+    waveSchema,
+    packetSchema,
+    resultSchema,
+    closeoutSchema,
+    remediationSchema,
+    decisionReviewSchema,
+    pendingNoteSchema,
+    topicStepDecisionSchema,
+    topicRunLedgerSchema,
+    forbiddenShortcutsCatalog,
+    lifecycleReport,
+    fourClosurePolicy,
+    validationPolicy,
+    authorityConvergencePolicy,
+  ] = await Promise.all([
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/topic.schema.yaml", "nimi-coding/contracts/topic.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/wave.schema.yaml", "nimi-coding/contracts/wave.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/packet.schema.yaml", "nimi-coding/contracts/packet.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/result.schema.yaml", "nimi-coding/contracts/result.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/closeout.schema.yaml", "nimi-coding/contracts/closeout.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/remediation.schema.yaml", "nimi-coding/contracts/remediation.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/decision-review.schema.yaml", "nimi-coding/contracts/decision-review.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/pending-note.schema.yaml", "nimi-coding/contracts/pending-note.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/topic-step-decision.schema.yaml", "nimi-coding/contracts/topic-step-decision.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/topic-run-ledger.schema.yaml", "nimi-coding/contracts/topic-run-ledger.schema.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/contracts/forbidden-shortcuts.catalog.yaml", "nimi-coding/contracts/forbidden-shortcuts.catalog.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/methodology/topic-lifecycle-report.yaml", "nimi-coding/methodology/topic-lifecycle-report.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/methodology/four-closure-policy.yaml", "nimi-coding/methodology/four-closure-policy.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/methodology/topic-validation-policy.yaml", "nimi-coding/methodology/topic-validation-policy.yaml"),
+    loadYamlWithFallback(projectRoot, ".nimi/methodology/authority-convergence-policy.yaml", "nimi-coding/methodology/authority-convergence-policy.yaml"),
+  ]);
+
+  return {
+    topicSchema,
+    waveSchema,
+    packetSchema,
+    resultSchema,
+    closeoutSchema,
+    remediationSchema,
+    decisionReviewSchema,
+    pendingNoteSchema,
+    topicStepDecisionSchema,
+    topicRunLedgerSchema,
+    forbiddenShortcutsCatalog,
+    lifecycleReport,
+    fourClosurePolicy,
+    validationPolicy,
+    authorityConvergencePolicy,
+  };
+}

package/cli/lib/doctor.mjs

@@ -0,0 +1,18 @@
+import { inspectDoctorBootstrapSurface } from "./internal/doctor-bootstrap-surface.mjs";
+import { inspectDoctorDelegatedSurface } from "./internal/doctor-delegated-surface.mjs";
+import { finalizeDoctorState } from "./internal/doctor-finalize.mjs";
+import { formatDoctorResult as formatDoctorResultInternal } from "./internal/doctor-format.mjs";
+
+export async function inspectDoctorState(projectRoot) {
+  const bootstrapSurface = await inspectDoctorBootstrapSurface(projectRoot);
+  if (bootstrapSurface.done) {
+    return bootstrapSurface.result;
+  }
+
+  const delegatedSurface = await inspectDoctorDelegatedSurface(projectRoot, bootstrapSurface);
+  return finalizeDoctorState(projectRoot, bootstrapSurface, delegatedSurface);
+}
+
+export function formatDoctorResult(result, options = {}) {
+  return formatDoctorResultInternal(result, options);
+}

package/cli/lib/entrypoints.mjs

@@ -0,0 +1,274 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  AGENTS_BEGIN,
+  AGENTS_END,
+  CLAUDE_BEGIN,
+  CLAUDE_END,
+} from "../constants.mjs";
+import { pathExists } from "./fs-helpers.mjs";
+
+function managedAgentsBlock() {
+  return `${AGENTS_BEGIN}
+# Nimi Coding Managed Block
+
+- Read .nimi/methodology, .nimi/spec, and .nimi/contracts before high-risk changes.
+- Treat .nimi as the primary AI truth surface for this project.
+- Treat \`/.nimi/spec/**\` as the current repo-wide product authority for this project, and use Git history for retired pre-cutover authority evidence.
+- If .nimi/spec remains bootstrap-only, use .nimi/methodology/spec-reconstruction.yaml and .nimi/config/skills.yaml to drive AI-side truth reconstruction.
+- Treat .nimi/methodology/spec-target-truth-profile.yaml as repo-local support guidance for future governance slices, not as the canonical reconstruction completion target or a guaranteed fresh-bootstrap seed.
+- Treat .nimi/contracts/spec-reconstruction-result.yaml, .nimi/contracts/doc-spec-audit-result.yaml, .nimi/contracts/high-risk-execution-result.yaml, and .nimi/contracts/high-risk-admission.schema.yaml as machine contracts for reconstruction, audit, local-only high-risk closeout summaries, and canonical high-risk admission truth.
+- Treat .nimi/config/skill-manifest.yaml, .nimi/config/host-profile.yaml, .nimi/config/host-adapter.yaml, .nimi/config/external-execution-artifacts.yaml, .nimi/config/skill-installer.yaml, .nimi/methodology/skill-runtime.yaml, .nimi/methodology/skill-installer-result.yaml, .nimi/methodology/skill-handoff.yaml, and admitted package-owned adapter profiles under adapters/**/profile.yaml as the canonical bridge to any external AI/skill execution.
+- Treat standalone nimicoding as boundary-complete for bootstrap, handoff, validation, projection, and explicit admission only; do not assume packaged run-kernel, provider, scheduler, notification, or automation ownership.
+- Treat .nimi/config/installer-evidence.yaml and .nimi/methodology/skill-installer-summary-projection.yaml as the operational-to-semantic installer projection boundary; do not promote concrete evidence artifacts into semantic truth.
+- Treat high-risk external execution closeout, decision, ingest, and review payloads under .nimi/local/** as local-only operational projections; they do not promote semantic truth automatically, even when manager-owned.
+- Use high-risk packetized execution only when authority, ownership, or cross-layer risk justifies it.
+- Keep inline manager-worker as the default methodology posture; do not assume a separate worker runtime is mandatory.
+- Keep code changes AI-context-efficient: favor bounded, cohesive files and split by responsibility during implementation instead of first concentrating unrelated logic into one file.
+- Keep the methodology continuity-agnostic; do not assume daemon, heartbeat, or persistent manager ownership.
+- Treat cutover readiness as preflight evidence only; the authority flip must come from an admitted cutover batch, not from readiness green by itself.
+- Do not treat this managed block as a replacement for project-specific rules outside .nimi.
+${AGENTS_END}`;
+}
+
+function managedClaudeBlock() {
+  return `${CLAUDE_BEGIN}
+# Nimi Coding Managed Block
+
+Use the project's .nimi layer as the primary AI truth surface.
+
+Priority:
+1. .nimi/methodology
+2. .nimi/spec
+3. .nimi/contracts
+4. .nimi/config
+5. repository-local AI entrypoint files
+
+If the project still exposes only bootstrap seed files, use the reconstruction guidance, result contracts, manifest, host-profile, host-adapter, admitted package-owned adapter profiles, installer, runtime contract, installer result contract, collapsed installer summary projection lifecycle contract, operational evidence guidance, and handoff truth under .nimi rather than assuming skills are already installed.
+
+Default posture:
+- use risk-shaped methodology only for authority-bearing or high-risk work
+- prefer inline manager-worker unless a later admitted packet expands runtime ownership
+- keep code changes AI-context-efficient: prefer bounded cohesive files and split by responsibility during implementation instead of first concentrating unrelated logic into one file
+- keep continuity-agnostic semantics; do not assume persistent automation or self-hosting
+- treat handoff --json as the authoritative machine contract and handoff --prompt as a human-readable projection only
+- treat \`/.nimi/spec/**\` as today's repo-wide authority, treat pre-cutover authority history as Git-only, and treat cutover readiness as historical preflight evidence rather than the authority source
+${CLAUDE_END}`;
+}
+
+function upsertManagedBlock(existing, begin, end, block) {
+  const pattern = new RegExp(
+    `${begin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, block);
+  }
+
+  const prefix = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${prefix}${block}\n`;
+}
+
+function removeManagedBlock(existing, begin, end) {
+  const pattern = new RegExp(
+    `(?:\\n\\n)?${begin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\n)?`,
+  );
+
+  if (!pattern.test(existing)) {
+    return {
+      changed: false,
+      next: existing,
+      deleteFile: false,
+    };
+  }
+
+  const next = existing
+    .replace(pattern, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/^\n+/, "")
+    .trimEnd();
+
+  return {
+    changed: true,
+    next: next.length === 0 ? "" : `${next}\n`,
+    deleteFile: next.length === 0,
+  };
+}
+
+function computeTextFileUpdate(existing, block, begin, end, header) {
+  const base = existing ?? header;
+  const next = upsertManagedBlock(base, begin, end, block);
+  return {
+    changed: next !== base,
+    next,
+  };
+}
+
+async function upsertTextFile(filePath, block, begin, end, header) {
+  const existing = (await pathExists(filePath)) ? await readFile(filePath, "utf8") : header;
+  const computed = computeTextFileUpdate(existing, block, begin, end, header);
+
+  if (!computed.changed) {
+    return false;
+  }
+
+  await writeFile(filePath, computed.next, "utf8");
+  return true;
+}
+
+async function removeManagedTextFile(filePath, begin, end, emptyFallbackHeader = null) {
+  const existing = (await pathExists(filePath)) ? await readFile(filePath, "utf8") : null;
+  if (existing === null) {
+    return {
+      changed: false,
+      removedFile: false,
+    };
+  }
+
+  const computed = removeManagedBlock(existing, begin, end);
+  if (!computed.changed) {
+    return {
+      changed: false,
+      removedFile: false,
+    };
+  }
+
+  if (computed.deleteFile || (emptyFallbackHeader && computed.next.trim() === emptyFallbackHeader.trim())) {
+    await rm(filePath, { force: true });
+    return {
+      changed: true,
+      removedFile: true,
+    };
+  }
+
+  await writeFile(filePath, computed.next, "utf8");
+  return {
+    changed: true,
+    removedFile: false,
+  };
+}
+
+export async function previewEntrypointIntegration(projectRoot) {
+  const updates = [];
+  const files = [
+    {
+      path: path.join(projectRoot, "AGENTS.md"),
+      block: managedAgentsBlock(),
+      begin: AGENTS_BEGIN,
+      end: AGENTS_END,
+      header: "# AGENTS.md\n",
+      relativePath: "AGENTS.md",
+    },
+    {
+      path: path.join(projectRoot, "CLAUDE.md"),
+      block: managedClaudeBlock(),
+      begin: CLAUDE_BEGIN,
+      end: CLAUDE_END,
+      header: "# CLAUDE.md\n",
+      relativePath: "CLAUDE.md",
+    },
+  ];
+
+  for (const file of files) {
+    const existing = (await pathExists(file.path)) ? await readFile(file.path, "utf8") : null;
+    const computed = computeTextFileUpdate(existing, file.block, file.begin, file.end, file.header);
+    if (computed.changed) {
+      updates.push(file.relativePath);
+    }
+  }
+
+  return updates;
+}
+
+export async function integrateEntrypoints(projectRoot) {
+  const updated = [];
+
+  if (
+    await upsertTextFile(
+      path.join(projectRoot, "AGENTS.md"),
+      managedAgentsBlock(),
+      AGENTS_BEGIN,
+      AGENTS_END,
+      "# AGENTS.md\n",
+    )
+  ) {
+    updated.push("AGENTS.md");
+  }
+
+  if (
+    await upsertTextFile(
+      path.join(projectRoot, "CLAUDE.md"),
+      managedClaudeBlock(),
+      CLAUDE_BEGIN,
+      CLAUDE_END,
+      "# CLAUDE.md\n",
+    )
+  ) {
+    updated.push("CLAUDE.md");
+  }
+
+  return updated;
+}
+
+export async function previewEntrypointRemoval(projectRoot) {
+  const updates = [];
+  const files = [
+    {
+      path: path.join(projectRoot, "AGENTS.md"),
+      begin: AGENTS_BEGIN,
+      end: AGENTS_END,
+      relativePath: "AGENTS.md",
+    },
+    {
+      path: path.join(projectRoot, "CLAUDE.md"),
+      begin: CLAUDE_BEGIN,
+      end: CLAUDE_END,
+      relativePath: "CLAUDE.md",
+    },
+  ];
+
+  for (const file of files) {
+    const existing = (await pathExists(file.path)) ? await readFile(file.path, "utf8") : null;
+    if (existing === null) {
+      continue;
+    }
+
+    const computed = removeManagedBlock(existing, file.begin, file.end);
+    if (computed.changed) {
+      updates.push(file.relativePath);
+    }
+  }
+
+  return updates;
+}
+
+export async function removeManagedEntrypoints(projectRoot) {
+  const updatedFiles = [];
+  const removedFiles = [];
+
+  const agentsResult = await removeManagedTextFile(
+    path.join(projectRoot, "AGENTS.md"),
+    AGENTS_BEGIN,
+    AGENTS_END,
+    "# AGENTS.md",
+  );
+  if (agentsResult.changed) {
+    (agentsResult.removedFile ? removedFiles : updatedFiles).push("AGENTS.md");
+  }
+
+  const claudeResult = await removeManagedTextFile(
+    path.join(projectRoot, "CLAUDE.md"),
+    CLAUDE_BEGIN,
+    CLAUDE_END,
+    "# CLAUDE.md",
+  );
+  if (claudeResult.changed) {
+    (claudeResult.removedFile ? removedFiles : updatedFiles).push("CLAUDE.md");
+  }
+
+  return {
+    updatedFiles,
+    removedFiles,
+  };
+}

package/cli/lib/external-execution.mjs

@@ -0,0 +1,101 @@
+import path from "node:path";
+
+import {
+  EXTERNAL_EXECUTION_ARTIFACTS_CONFIG_REF,
+  HIGH_RISK_EXECUTION_ARTIFACT_HARD_CONSTRAINTS,
+  HIGH_RISK_EXECUTION_ARTIFACT_ROOTS,
+  HIGH_RISK_EXECUTION_RESULT_CONTRACT_REF,
+  HOST_ADAPTER_CONFIG_REF,
+} from "../constants.mjs";
+import { readTextIfFile } from "./fs-helpers.mjs";
+import { arraysEqual, isPlainObject, toStringArray } from "./value-helpers.mjs";
+import { parseYamlText } from "./yaml-helpers.mjs";
+
+function parseExternalExecutionArtifactsConfig(text) {
+  const parsed = parseYamlText(text);
+  const root = parsed?.external_execution_artifacts;
+  const artifactRoots = isPlainObject(root?.artifact_roots) ? root.artifact_roots : null;
+  const hardConstraints = toStringArray(root?.hard_constraints);
+
+  const artifactRootsOk = Boolean(artifactRoots)
+    && Object.entries(HIGH_RISK_EXECUTION_ARTIFACT_ROOTS).every(
+      ([field, expectedPath]) => String(artifactRoots[field] ?? "") === expectedPath,
+    )
+    && Object.keys(artifactRoots).length === Object.keys(HIGH_RISK_EXECUTION_ARTIFACT_ROOTS).length;
+
+  return {
+    ok: String(root?.skill_id ?? "") === "high_risk_execution"
+      && String(root?.host_adapter_ref ?? "") === HOST_ADAPTER_CONFIG_REF
+      && String(root?.result_contract_ref ?? "") === HIGH_RISK_EXECUTION_RESULT_CONTRACT_REF
+      && String(root?.locality ?? "") === "local_only"
+      && artifactRootsOk
+      && arraysEqual(hardConstraints, HIGH_RISK_EXECUTION_ARTIFACT_HARD_CONSTRAINTS),
+    artifactRoots: artifactRootsOk
+      ? Object.fromEntries(
+        Object.entries(HIGH_RISK_EXECUTION_ARTIFACT_ROOTS).map(([field]) => [field, artifactRoots[field]]),
+      )
+      : null,
+    hardConstraints,
+  };
+}
+
+function normalizeRef(ref) {
+  return path.posix.normalize(String(ref ?? "")).replace(/^\.\/+/, "");
+}
+
+function isRefUnderRoot(ref, root) {
+  const normalizedRef = normalizeRef(ref);
+  const normalizedRoot = normalizeRef(root);
+
+  return normalizedRef === normalizedRoot || normalizedRef.startsWith(`${normalizedRoot}/`);
+}
+
+export async function loadExternalExecutionArtifactsConfig(projectRoot) {
+  const text = await readTextIfFile(
+    path.join(projectRoot, EXTERNAL_EXECUTION_ARTIFACTS_CONFIG_REF),
+  );
+
+  return {
+    path: EXTERNAL_EXECUTION_ARTIFACTS_CONFIG_REF,
+    text,
+    ...parseExternalExecutionArtifactsConfig(text),
+  };
+}
+
+export function validateHighRiskExecutionArtifactRefs(summary, config) {
+  if (!config.ok || !config.artifactRoots) {
+    return {
+      ok: false,
+      reason: "external execution artifacts config is missing or malformed",
+    };
+  }
+
+  for (const field of [
+    "packet_ref",
+    "orchestration_state_ref",
+    "prompt_ref",
+    "worker_output_ref",
+  ]) {
+    const expectedRoot = config.artifactRoots[field];
+    if (!isRefUnderRoot(summary[field], expectedRoot)) {
+      return {
+        ok: false,
+        reason: `high_risk_execution summary.${field} must stay under ${expectedRoot}`,
+      };
+    }
+  }
+
+  const evidenceRoot = config.artifactRoots.evidence_refs;
+  for (const ref of summary.evidence_refs) {
+    if (!isRefUnderRoot(ref, evidenceRoot)) {
+      return {
+        ok: false,
+        reason: `high_risk_execution summary.evidence_refs entries must stay under ${evidenceRoot}`,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+  };
+}

package/cli/lib/fs-helpers.mjs

@@ -0,0 +1,33 @@
+import { readFile, stat, writeFile } from "node:fs/promises";
+
+export async function pathExists(targetPath) {
+  try {
+    return await stat(targetPath);
+  } catch {
+    return null;
+  }
+}
+
+export async function readTextIfFile(filePath) {
+  const info = await pathExists(filePath);
+  if (!info || !info.isFile()) {
+    return null;
+  }
+
+  return readFile(filePath, "utf8");
+}
+
+export async function appendGitignoreEntries(gitignorePath, entries) {
+  const existing = (await pathExists(gitignorePath))
+    ? await readFile(gitignorePath, "utf8")
+    : "";
+  const missing = entries.filter((entry) => !existing.includes(entry));
+
+  if (missing.length === 0) {
+    return false;
+  }
+
+  const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  await writeFile(gitignorePath, `${existing}${prefix}${missing.join("\n")}\n`, "utf8");
+  return true;
+}