@lamentis/naome 1.2.0 → 1.3.0

package/installer/native.js

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { hasSymlinkInTargetPath } from "./filesystem.js";
+import { buildNativeDecisionBinary } from "./native-build.js";
+import { formatExpectedIntegrityBlock } from "./native-format.js";
+import { printError } from "./output.js";
+
+export function installNativeDecisionBinary(ctx) {
+  const targetPath = join(ctx.targetRoot, ctx.nativeBinaryRelativePath);
+
+  if (hasSymlinkInTargetPath(ctx, ctx.nativeBinaryRelativePath)) {
+    ctx.skipped.push(ctx.nativeBinaryRelativePath);
+    ctx.unsafeSkipped.push(ctx.nativeBinaryRelativePath);
+    return;
+  }
+
+  const sourcePath = findNativeDecisionBinary(ctx);
+  if (!sourcePath) {
+    printError(ctx, "NAOME native decision binary is unavailable.");
+    console.error("Install Cargo or provide NAOME_NATIVE_BIN with a built naome binary, then rerun naome sync.");
+    process.exit(1);
+  }
+
+  if (usesSourceNativeFallback(ctx)) {
+    patchNaomeCommandNativeIntegrity(ctx, "sha256:generated");
+    ctx.skipped.push(ctx.nativeBinaryRelativePath);
+    return;
+  }
+
+  mkdirSync(dirname(targetPath), { recursive: true });
+  const sourceHash = sha256(readFileSync(sourcePath));
+  const targetHash =
+    existsSync(targetPath) && lstatSync(targetPath).isFile()
+      ? sha256(readFileSync(targetPath))
+      : null;
+
+  if (sourceHash !== targetHash) {
+    copyFileSync(sourcePath, targetPath);
+    ctx.updated.push(ctx.nativeBinaryRelativePath);
+  } else {
+    ctx.skipped.push(ctx.nativeBinaryRelativePath);
+  }
+
+  chmodSync(targetPath, 0o755);
+  patchNaomeCommandNativeIntegrity(ctx, `sha256:${sourceHash}`);
+}
+
+export function findNativeDecisionBinary(ctx) {
+  const candidates = [];
+
+  if (process.env.NAOME_NATIVE_BIN) {
+    candidates.push(resolve(ctx.targetRoot, process.env.NAOME_NATIVE_BIN));
+  }
+
+  candidates.push(join(ctx.packageRoot, "native", `${process.platform}-${process.arch}`, ctx.nativeBinaryName));
+  candidates.push(join(ctx.packageRoot, "target", "release", ctx.nativeBinaryName));
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && lstatSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+
+  return buildNativeDecisionBinary(ctx);
+}
+
+export function patchInstalledMachineOwnedIntegrity(ctx) {
+  const integrityBlock = formatExpectedIntegrityBlock(templateIntegrity(ctx));
+
+  for (const relativePath of [ctx.healthCheckerRelativePath, ctx.taskStateCheckerRelativePath]) {
+    const targetPath = join(ctx.targetRoot, relativePath);
+    if (!existsSync(targetPath) || hasSymlinkInTargetPath(ctx, relativePath)) {
+      continue;
+    }
+
+    const content = readFileSync(targetPath, "utf8");
+    const nextContent = content.replace(ctx.integrityBlockPattern, integrityBlock);
+    if (nextContent !== content) {
+      writeFileSync(targetPath, nextContent);
+      ctx.updated.push(relativePath);
+    }
+  }
+}
+
+export function usesSourceNativeFallback(ctx) {
+  return existsSync(join(ctx.targetRoot, "packages", "naome", "Cargo.toml"))
+    && existsSync(join(ctx.targetRoot, "packages", "naome", "crates", "naome-cli", "src", "main.rs"));
+}
+
+export function installedNativeBinaryHash(ctx) {
+  const targetPath = join(ctx.targetRoot, ctx.nativeBinaryRelativePath);
+  if (
+    !existsSync(targetPath) ||
+    hasSymlinkInTargetPath(ctx, ctx.nativeBinaryRelativePath) ||
+    !lstatSync(targetPath).isFile()
+  ) {
+    return null;
+  }
+
+  return sha256(readFileSync(targetPath));
+}
+
+export function templateIntegrity(ctx) {
+  const integrity = {};
+
+  for (const relativePath of ctx.machineOwnedPaths) {
+    const sourcePath = join(ctx.templateRoot, relativePath);
+    integrity[relativePath] = `sha256:${machineFileHash(ctx, relativePath, readFileSync(sourcePath))}`;
+  }
+
+  return integrity;
+}
+
+export function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function machineFileHash(ctx, relativePath, content) {
+  let normalized = content;
+
+  if (hasGeneratedIntegrity(ctx, relativePath)) {
+    normalized = normalized.toString("utf8").replace(ctx.integrityBlockPattern, ctx.normalizedIntegrityBlock);
+  }
+
+  if (relativePath === ctx.naomeCommandRelativePath) {
+    normalized = normalized.toString("utf8").replace(ctx.nativeIntegrityPattern, ctx.normalizedNativeIntegrity);
+  }
+
+  return sha256(normalized);
+}
+
+export function hasGeneratedIntegrity(ctx, relativePath) {
+  return relativePath === ctx.healthCheckerRelativePath || relativePath === ctx.taskStateCheckerRelativePath;
+}
+
+function patchNaomeCommandNativeIntegrity(ctx, expectedIntegrity) {
+  const commandPath = join(ctx.targetRoot, ctx.naomeCommandRelativePath);
+  if (!existsSync(commandPath) || hasSymlinkInTargetPath(ctx, ctx.naomeCommandRelativePath)) {
+    return;
+  }
+
+  const content = readFileSync(commandPath, "utf8");
+  const nextContent = content.replace(
+    ctx.nativeIntegrityPattern,
+    `const expectedNativeBinaryIntegrity = "${expectedIntegrity}";\n`,
+  );
+
+  if (nextContent !== content) {
+    writeFileSync(commandPath, nextContent);
+    ctx.updated.push(ctx.naomeCommandRelativePath);
+  }
+}

package/installer/output.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function printHeader(ctx) {
+  console.log("");
+  console.log(`${ctx.color.bold("NAOME")} ${ctx.color.dim(`v${ctx.packageVersion}`)}`);
+  console.log(ctx.color.dim("AI coding-agent harness installer"));
+  console.log("");
+  console.log(`${ctx.color.dim("target  ")} ${ctx.targetRoot}`);
+}
+
+export function printSection(ctx, title) {
+  console.log("");
+  console.log(ctx.color.bold(title));
+}
+
+export function printList(ctx, items, marker) {
+  for (const item of uniqueStrings(items)) {
+    console.log(`${ctx.color.dim(marker)} ${item}`);
+  }
+}
+
+export function uniqueStrings(items) {
+  return Array.from(new Set(items));
+}
+
+export function printError(ctx, message) {
+  console.error("");
+  console.error(`${ctx.color.red("x")} ${message}`);
+}
+
+export function printCancelled(ctx, message) {
+  console.log("");
+  console.log(`${ctx.color.yellow("-")} ${message}`);
+}
+
+export function printCommandFailure(ctx, message, result) {
+  printError(ctx, message);
+  if (result.stdout.trim()) {
+    console.error(result.stdout.trim());
+  }
+  if (result.stderr.trim()) {
+    console.error(result.stderr.trim());
+  }
+  process.exit(1);
+}
+
+export function printSummary(ctx, existingInstall) {
+  console.log("");
+  console.log(`${ctx.color.green("+")} ${ctx.summaryTitle}`);
+
+  const detailedOutput = shouldPrintDetailedSummary(ctx, existingInstall);
+  if (!detailedOutput) {
+    printCompactSummary(ctx);
+  }
+
+  printDetailedSummary(ctx, detailedOutput);
+  if (ctx.unsafeSkipped.length > 0) {
+    printSection(ctx, "Skipped unsafe symlinked paths");
+    printList(ctx, ctx.unsafeSkipped, "!");
+  }
+
+  if (isRepositoryInitialized(ctx)) {
+    console.log("");
+    return;
+  }
+
+  printSection(ctx, "Next step");
+  console.log("Copy this into your coding agent:");
+  console.log("");
+  console.log(ctx.color.dim("```"));
+  console.log(ctx.nextStepPrompt);
+  console.log(ctx.color.dim("```"));
+  console.log("");
+}
+
+function printDetailedSummary(ctx, detailedOutput) {
+  if (detailedOutput && ctx.installed.length > 0) {
+    const items = uniqueStrings(ctx.installed);
+    printSection(ctx, `Installed ${items.length} ${items.length === 1 ? "item" : "items"}`);
+    printList(ctx, ctx.installed, "+");
+  }
+
+  if (detailedOutput && ctx.updated.length > 0) {
+    const items = uniqueStrings(ctx.updated);
+    printSection(ctx, `Updated ${items.length} ${items.length === 1 ? "item" : "items"}`);
+    printList(ctx, ctx.updated, "~");
+  }
+
+  if (detailedOutput && ctx.archived.length > 0) {
+    printSection(ctx, "Archived");
+    for (const entry of ctx.archived) {
+      console.log(`${ctx.color.dim(">")} ${entry.from} -> ${entry.to}`);
+    }
+  }
+
+  if (detailedOutput && ctx.skipped.length > 0) {
+    const items = uniqueStrings(ctx.skipped);
+    printSection(ctx, `Skipped ${items.length} existing ${items.length === 1 ? "path" : "paths"}`);
+    printList(ctx, ctx.skipped, "-");
+  }
+}
+
+function shouldPrintDetailedSummary(ctx, existingInstall) {
+  return ctx.verboseOutput || !existingInstall;
+}
+
+function printCompactSummary(ctx) {
+  const installedCount = uniqueStrings(ctx.installed).length;
+  const updatedCount = uniqueStrings(ctx.updated).length;
+  const archivedCount = ctx.archived.length;
+
+  if (installedCount > 0) {
+    console.log(`${ctx.color.dim("installed")} ${installedCount}`);
+  }
+  if (updatedCount > 0) {
+    console.log(`${ctx.color.dim("updated")} ${updatedCount}`);
+  }
+  if (archivedCount > 0) {
+    console.log(`${ctx.color.dim("archived")} ${archivedCount}`);
+  }
+}
+
+function isRepositoryInitialized(ctx) {
+  try {
+    const initState = JSON.parse(readFileSync(join(ctx.targetRoot, ".naome", "init-state.json"), "utf8"));
+    return initState.initialized === true;
+  } catch {
+    return false;
+  }
+}

package/installer/version.js

@@ -0,0 +1,32 @@
+import { printError } from "./output.js";
+
+export function compareVersions(ctx, left, right) {
+  const leftParts = parseVersion(ctx, left);
+  const rightParts = parseVersion(ctx, right);
+
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] > rightParts[index]) {
+      return 1;
+    }
+
+    if (leftParts[index] < rightParts[index]) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+export function isVersion(version) {
+  return typeof version === "string" && /^\d+\.\d+\.\d+$/.test(version);
+}
+
+function parseVersion(ctx, version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match) {
+    printError(ctx, `Invalid NAOME version: ${version}`);
+    process.exit(1);
+  }
+
+  return match.slice(1).map((part) => Number.parseInt(part, 10));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamentis/naome",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Native-first CLI for the NAOME agent harness.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,6 +31,7 @@
     "Cargo.lock",
     "Cargo.toml",
     "crates",
+    "installer",
     "native",
     "templates",
     "README.md"

package/templates/naome-root/.naome/bin/check-harness-health.js

@@ -11,14 +11,14 @@ const nativeBinaryName = process.platform === "win32" ? "naome.exe" : "naome";
 const expectedMachineOwnedIntegrity = Object.freeze({
   ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
   ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-  ".naome/bin/naome.js": "sha256:5675f729be6da3cbda1d8b9e0b36821cc98409aae95dff0603ed9161a5eb3b38",
+  ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
   ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
   ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
   "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-  "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+  "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
   "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
   "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
-  "docs/naome/index.md": "sha256:7d917f1fa368874653bb458384bd9d0b221529e19644028a3143db3d3c144213",
+  "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",
   "docs/naome/upgrade.md": "sha256:2c60f0441bbd98bd528d109b30a7ded4b0ad55d61ffb9f52edac9e93b7999cb1"
 });
 

package/templates/naome-root/.naome/bin/check-task-state.js

@@ -11,14 +11,14 @@ const nativeBinaryName = process.platform === "win32" ? "naome.exe" : "naome";
 const expectedMachineOwnedIntegrity = Object.freeze({
   ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
   ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-  ".naome/bin/naome.js": "sha256:5675f729be6da3cbda1d8b9e0b36821cc98409aae95dff0603ed9161a5eb3b38",
+  ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
   ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
   ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
   "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-  "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+  "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
   "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
   "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
-  "docs/naome/index.md": "sha256:7d917f1fa368874653bb458384bd9d0b221529e19644028a3143db3d3c144213",
+  "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",
   "docs/naome/upgrade.md": "sha256:2c60f0441bbd98bd528d109b30a7ded4b0ad55d61ffb9f52edac9e93b7999cb1"
 });
 

package/templates/naome-root/.naome/bin/naome.js

@@ -27,7 +27,7 @@ function main(argv) {
     return;
   }
 
-  if (["status", "next", "intent", "route", "explain", "quality", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
+  if (["status", "next", "intent", "route", "explain", "doctor", "quality", "semantic", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
     runNativeDecisionCommand(command, args);
     return;
   }
@@ -349,26 +349,37 @@ function findAncestorWithMarker(startPath, markerParts) {
 }
 
 function printHelp() {
-  console.log("Usage:");
-  console.log("  naome status [--json]");
-  console.log("  naome next [--json]");
-  console.log("  naome intent --prompt-file <path> [--json]");
-  console.log("  naome intent --prompt <text> [--json]");
-  console.log("  naome route --prompt-file <path> [--execute] [--json]");
-  console.log("  naome route --prompt <text> [--execute] [--json]");
-  console.log("  naome explain --prompt-file <path> [--json]");
-  console.log("  naome explain --prompt <text> [--json]");
-  console.log("  naome quality init [--json]");
-  console.log("  naome quality check --changed [--json]");
-  console.log("  naome quality report [--json]");
-  console.log("  naome cleanup plan [--json]");
-  console.log("  naome cleanup route --path <path> [--json]");
-  console.log("  naome refresh-integrity [--json]");
-  console.log("  naome workflow search-profile|check-search|phases|processes|mutations [--json]");
-  console.log("  naome install");
-  console.log("  naome sync");
-  console.log("  naome commit -m \"type(scope): message\"");
-  console.log("  node .naome/bin/naome.js commit -m \"type(scope): message\"");
+  const commands = [
+    "naome status [--json]",
+    "naome next [--json]",
+    "naome intent --prompt-file <path> [--json]",
+    "naome intent --prompt <text> [--json]",
+    "naome route --prompt-file <path> [--execute] [--json]",
+    "naome route --prompt <text> [--execute] [--json]",
+    "naome explain --prompt-file <path> [--json]",
+    "naome explain --prompt <text> [--json]",
+    "naome doctor [--json]",
+    "naome quality init [--baseline|--deep-baseline] [--json]",
+    "naome quality check --changed [--include-scanned-paths] [--json]",
+    "naome quality report [--deep] [--include-scanned-paths] [--json]",
+    "naome quality cache status [--json]",
+    "naome quality cache clear",
+    "naome semantic report [--deep] [--json]",
+    "naome semantic check --changed [--json]",
+    "naome semantic route --finding <id> [--json]",
+    "naome semantic loop [--json]",
+    "naome structure report [--json]",
+    "naome structure explain --path <path> [--json]",
+    "naome cleanup plan [--json]",
+    "naome cleanup route --path <path> [--json]",
+    "naome refresh-integrity [--json]",
+    "naome workflow search-profile|check-search|phases|processes|mutations [--json]",
+    "naome install",
+    "naome sync",
+    "naome commit -m \"type(scope): message\"",
+    "node .naome/bin/naome.js commit -m \"type(scope): message\""
+  ];
+  console.log(["Usage:", ...commands.map((command) => `  ${command}`)].join("\n"));
 }
 
 function fail(message) {

package/templates/naome-root/.naome/manifest.json

@@ -4,14 +4,14 @@
   "integrity": {
     ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
     ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-    ".naome/bin/naome.js": "sha256:5675f729be6da3cbda1d8b9e0b36821cc98409aae95dff0603ed9161a5eb3b38",
+    ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
     ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
     ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
     "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-    "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+    "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
     "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
     "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
-    "docs/naome/index.md": "sha256:7d917f1fa368874653bb458384bd9d0b221529e19644028a3143db3d3c144213",
+    "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",
     "docs/naome/upgrade.md": "sha256:2c60f0441bbd98bd528d109b30a7ded4b0ad55d61ffb9f52edac9e93b7999cb1"
   },
   "machineOwned": [
@@ -37,11 +37,13 @@
     ".naome/upgrade-state.json",
     ".naome/verification.json",
     ".naome/repository-quality.json",
+    ".naome/repository-structure.json",
     ".naome/repository-quality-baseline.json",
     "docs/naome/architecture.md",
     "docs/naome/decisions.md",
     "docs/naome/repo-profile.md",
     "docs/naome/repository-quality.md",
+    "docs/naome/repository-structure.md",
     "docs/naome/security.md",
     "docs/naome/testing.md"
   ]

package/templates/naome-root/.naome/repository-structure.json

@@ -0,0 +1,90 @@
+{
+  "schema": "naome.repository-structure.v1",
+  "version": 1,
+  "status": "ready",
+  "enabledAdapters": [],
+  "sourceRoots": [
+    "src/**",
+    "app/**",
+    "apps/*/src/**",
+    "packages/*/src/**",
+    "crates/*/src/**",
+    "**/src/**",
+    "lib/**"
+  ],
+  "testRoots": [
+    "test/**",
+    "tests/**",
+    "__tests__/**",
+    "packages/*/test/**",
+    "packages/*/tests/**",
+    "crates/*/tests/**",
+    "**/tests/**",
+    "scripts/*.test.js"
+  ],
+  "docsRoots": [
+    "docs/**",
+    "doc/**"
+  ],
+  "generatedRoots": [
+    "**/generated/**",
+    "**/__generated__/**",
+    "**/codegen/**",
+    "**/*.generated.*"
+  ],
+  "artifactRoots": [
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".next/**",
+    "target/**",
+    "**/dist/**",
+    "**/build/**"
+  ],
+  "moduleRoots": [
+    "src/**",
+    "app/**",
+    "packages/*/src/**",
+    "crates/*/src/**",
+    "**/src/**"
+  ],
+  "allowedRootFiles": [
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "AGENTS.md",
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "go.mod",
+    "go.sum",
+    "Makefile",
+    ".gitignore",
+    ".naomeignore"
+  ],
+  "directoryRoleRules": [],
+  "layerRules": [],
+  "ignoredPaths": [
+    ".git/**",
+    "node_modules/**",
+    "vendor/**",
+    "target/**",
+    "**/target/**",
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".next/**"
+  ],
+  "disabledChecks": [],
+  "changedCodePolicy": "block",
+  "debtPolicy": "report",
+  "limits": {
+    "maxDirectoryFiles": 40,
+    "maxPathDepth": 10,
+    "maxDirectoryRoles": 2,
+    "maxDumpingGroundFiles": 12
+  }
+}

package/templates/naome-root/.naome/verification.json

@@ -48,6 +48,7 @@
       "source": "NAOME built-in",
       "evidence": [
         ".naome/repository-quality.json",
+        ".naome/repository-structure.json",
         ".naome/repository-quality-baseline.json"
       ],
       "lastVerified": null

package/templates/naome-root/.naomeignore

@@ -2,3 +2,4 @@
 # Agents must not read, summarize, scan, import, or use these paths as context.
 
 .naome/archive/
+.naome/cache/

package/templates/naome-root/docs/naome/agent-workflow.md

@@ -20,37 +20,39 @@ Use this workflow after first-run intake is complete.
    debugging why a policy won.
 4. Run `node .naome/bin/naome.js status --json` when reporting state without
    routing a new request.
-5. Run `node .naome/bin/check-harness-health.js`.
-6. If harness health fails, do not start new feature work. Ask the user to
+5. Run `node .naome/bin/naome.js doctor --json` when state is unclear or a
+   gate blocks unexpectedly; use its `nextAction` as the first diagnostic.
+6. Run `node .naome/bin/check-harness-health.js`.
+7. If harness health fails, do not start new feature work. Ask the user to
    choose `repair_harness`, `review_harness_diff`, or
    `cancel_repair_baseline`.
-7. Run `node .naome/bin/check-task-state.js --admission`.
-8. If task admission fails for a natural-language work request, use
+8. Run `node .naome/bin/check-task-state.js --admission`.
+9. If task admission fails for a natural-language work request, use
    `naome route --execute --json`. Route may baseline valid completed setup or
    task diffs, create an isolated task worktree around unrelated user edits,
    baseline pure harness refreshes in the current worktree, and rerun
    admission. Ask the user only when `humanOptions` is non-empty,
    route blocks as unsafe/ambiguous, or automatic baselining fails.
-9. If route blocks or returns no mutation, do not use raw `git commit`, IDE
+10. If route blocks or returns no mutation, do not use raw `git commit`, IDE
    commit, `git add`, or hook bypass commands as a fallback. Unowned changes
    are user-owned unless NAOME route explicitly isolates around them or
    baselines a deterministic harness/task diff. If the user explicitly asks to
    commit their own unowned changes, route must run the configured quality gate
    first, require committed verification coverage for every path, and commit
    only the final stabilized paths it evaluated.
-10. Record the passed admission check in `.naome/task-state.json` when starting
+11. Record the passed admission check in `.naome/task-state.json` when starting
    the task.
-11. Restate the task in concrete terms.
-12. Read `.naomeignore`.
-13. Exclude every path matched by `.naomeignore` from context gathering.
-14. For broad searches, use `node .naome/bin/naome.js workflow search-profile`
+12. Restate the task in concrete terms.
+13. Read `.naomeignore`.
+14. Exclude every path matched by `.naomeignore` from context gathering.
+15. For broad searches, use `node .naome/bin/naome.js workflow search-profile`
     or equivalent excludes for `.git`, `.naome/archive`, dependencies, build
     outputs, caches, and `.naomeignore` paths.
-15. Read only the `requiredContext` returned by route/status plus the smallest
+16. Read only the `requiredContext` returned by route/status plus the smallest
     task-relevant NAOME docs.
-16. Inspect the existing code or docs before proposing changes.
-17. Read `testing.md` and `.naome/verification.json`.
-18. Identify the required proof before claiming success.
+17. Inspect the existing code or docs before proposing changes.
+18. Read `testing.md` and `.naome/verification.json`.
+19. Identify the required proof before claiming success.
 
 ## Instruction Boundaries
 

package/templates/naome-root/docs/naome/index.md

@@ -18,9 +18,10 @@ for the current step.
 11. `testing.md`
 12. `.naome/verification.json`
 13. `repository-quality.md`, when repository-quality checks or cleanup are relevant
-14. `security.md`
-15. `agent-workflow.md`
-16. `decisions.md`, when changing durable project policy
+14. `repository-structure.md`, when path roles or structure cleanup are relevant
+15. `security.md`
+16. `agent-workflow.md`
+17. `decisions.md`, when changing durable project policy
 
 ## Source Types