@lamentis/naome 1.2.0 → 1.2.1

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.2.1",
   "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:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
   ".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/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:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
   ".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/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", "quality", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
     runNativeDecisionCommand(command, args);
     return;
   }
@@ -349,26 +349,30 @@ 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 quality init [--json]",
+    "naome quality check --changed [--json]",
+    "naome quality report [--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:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
     ".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/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/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
 

package/templates/naome-root/docs/naome/repository-quality.md

@@ -33,6 +33,9 @@ to avoid overlapping window spam and include repeated regions inside the same
 file. Near-duplicate function checks compare functions/components, not
 container symbols against their own children.
 
+Structure checks run through the same gate. See `repository-structure.md` for
+path roles, module/layer policy, adapters, and cleanup routing.
+
 Agents may propose stricter repo-specific rules after inspecting the language
 and stack.
 

package/templates/naome-root/docs/naome/repository-structure.md

@@ -0,0 +1,51 @@
+# Repository Structure
+
+NAOME checks whether new and changed files land in a maintainable directory
+structure. Existing structure debt stays visible in reports and cleanup routes,
+but normal feature work is blocked only by relevant changed paths.
+
+## Model
+
+The structure model classifies each path as:
+
+`path -> role -> module -> layer -> language -> generated/debt/changed`
+
+Generic roles are `source`, `test`, `docs`, `config`, `script`, `generated`,
+`artifact`, `dependency/vendor`, and `unknown`.
+
+## Gates
+
+- `naome quality check --changed` includes structure checks.
+- `naome quality report` shows structure debt with other quality findings.
+- `naome structure report --json` returns only structure findings.
+- `naome structure explain --path <path> --json` explains one path's role,
+  module, layer, language, generated flag, debt flag, and changed flag.
+- `naome cleanup plan` and `naome cleanup route --path <path>` include
+  structure findings when a cleanup task should move or split files.
+
+## Checks
+
+Structure checks include directory role mixing, misplaced file roles,
+root-level file sprawl, dumping-ground directories, directory size, path depth,
+case-insensitive path collisions, and source/test pairing hints.
+
+Dumping-ground names such as `utils`, `helpers`, `common`, `shared`, `misc`,
+and `lib` are not banned. New feature logic there is reported when a named
+module location is more appropriate.
+
+## Adapters
+
+The core is language-independent. Adapters add deterministic signals for stack
+conventions. Built-in adapters currently include `rust` and
+`javascript-typescript`; future adapters can add source roots, test roots,
+module roots, and allowed root files without changing gate behavior.
+
+## Local Policy
+
+Rules live in `.naome/repository-structure.json`. Product defaults contain no
+repository-specific paths. Local policy may add source roots, test roots,
+generated roots, allowed root files, directory role rules, and layer rules.
+
+Use local policy to document real repository conventions, not to grant special
+rights to one product or hide cleanup work. Loosening a structure rule to pass a
+feature diff requires human review.

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

@@ -58,6 +58,7 @@ phase is failing or missing.
 - Store long command output as a compact summary that preserves command, cwd,
   exit code, relevant lines, affected paths, and artifacts.
 - When intake defines change types, include `repository-quality-check` as a
-  required check for source, documentation, harness, template, and CI changes.
+  required check for source, structure, documentation, harness, template, and
+  CI changes.
 - Before completion, select proof from the Verification Map when possible.
 - Report exact commands and results. Do not claim proof that did not run.