@lamentis/naome 1.3.0 → 1.3.2

package/templates/naome-root/.naome/bin/codex-hook-runtime.js

@@ -0,0 +1,174 @@
+"use strict";
+
+const io = require("./codex-hook-io.js");
+const policy = require("./codex-hook-policy.js");
+
+function handleCodexHook() {
+  const payload = io.readPayload();
+  const event = io.eventName(payload);
+  try {
+    if (event === "UserPromptSubmit") return userPrompt(payload); if (event === "PreToolUse") return preTool(payload);
+    if (event === "PermissionRequest") return permission(payload); if (event === "PostToolUse") return postTool(payload);
+    if (event === "Stop") return stop(payload);
+  } catch {
+    return io.write({});
+  }
+  io.write({});
+}
+
+function userPrompt(payload) {
+  const prompt = io.promptOf(payload);
+  const classification = policy.classifyPrompt(prompt);
+  const risky = policy.riskyPromptCodes(prompt);
+  const status = io.parseJson(io.runNaome(["status", "--json"]).stdout);
+  const codes = [`prompt-${classification}`, ...risky];
+  if (status?.state === "dirty_unowned_diff") codes.push("repo-dirty-unowned");
+  if (["new_task", "ci_fix"].includes(classification)) codes.push("route-required", "context-selection-required");
+  io.decide("warn", "prompt-guidance", [`prompt:${classification}`, status?.state ? `repo:${status.state}` : null, risky.length ? `risk:${risky.join(",")}` : null, ["new_task", "ci_fix"].includes(classification) ? "run route and context select before feature work" : null], { classification, reasonCodes: codes });
+}
+
+function preTool(payload) {
+  const command = io.commandOf(payload);
+  const boundary = policy.forbiddenPath(payload, command);
+  if (boundary) return io.decide("block", boundary, [boundary], { reasonCodes: [boundary.split(":")[0]] });
+  if (!command) return io.write({});
+  const hard = policy.hardBlockedCommand(command);
+  if (hard) return io.decide("block", hard, [hard], { reasonCodes: [hard.split(":")[0]] });
+  const preflight = commitPushPreflight(command);
+  if (preflight) return io.decide("block", preflight, [preflight], { reasonCodes: [preflight.split(":")[0]] });
+  const search = validateSearch(command);
+  if (search) return io.decide("block", search, [search], { reasonCodes: [search.split(":")[0]] });
+  io.write({});
+}
+
+function permission(payload) {
+  const risks = policy.permissionRiskCodes(`${io.commandOf(payload) || ""} ${io.promptOf(payload)}`);
+  if (!risks.length) return io.write({});
+  io.decide("warn", "permission-risk-summary", [`permission risks: ${risks.join(",")}; approve only if this matches the current NAOME task.`], { riskCodes: risks, reasonCodes: ["permission-risk-summary"] });
+}
+
+function postTool(payload) {
+  const command = io.commandOf(payload);
+  const changedPaths = changedFiles();
+  if (!changedPaths.length) return io.write({});
+  if (!policy.looksLikeWriteTool(payload, command)) {
+    const cache = io.readCache();
+    io.writeCache({ ...cache, postToolUse: { signature: io.diffSignature(), decision: {} } });
+    return io.write({});
+  }
+  const checkedPaths = postToolCheckedPaths(payload, command, changedPaths);
+  if (!checkedPaths.length) return io.write({});
+  const signature = `${io.diffSignature()}:${checkedPaths.join("\0")}`;
+  const cache = io.readCache();
+  if (cache.postToolUse?.signature === signature) return io.write({});
+  const result = changedState(checkedPaths, { pathScoped: true });
+  const decision = result.codes.length ? io.decisionObject("warn", policy.primaryReason(result.codes), result.messages, { reasonCodes: result.codes, changedPaths: checkedPaths, owedProof: result.expensiveOwed, cheapGates: result.gates }) : {};
+  io.writeCache({ ...cache, postToolUse: { signature, decision, changedPaths, checkedPaths, cheapGateCommands: result.gateCommands } });
+  io.write(decision);
+}
+
+function stop(payload) {
+  const changedPaths = changedFiles();
+  const result = changedState(changedPaths);
+  for (const check of [io.taskCheck([]), io.taskCheck(["--progress"])]) {
+    const output = `${check.stdout || ""}\n${check.stderr || ""}`;
+    if (check.status && /outside allowedPaths|scope drift/i.test(output)) policy.pushUnique(result.codes, "scope-drift", result.messages, "scope drift blocks completion");
+    if (check.status && /missing proof|proofResults missing|failed proof/i.test(output)) policy.pushUnique(result.codes, "missing-proof", result.messages, "missing required proof blocks completion");
+  }
+  const prompt = io.promptOf(payload);
+  if (/push/i.test(prompt) && /\[ahead [1-9]/.test(io.runGit(["status", "--short", "--branch"]).stdout || "")) {
+    policy.pushUnique(result.codes, "unpushed-branch", result.messages, "branch has unpushed commits");
+  }
+  if (/resolve|review comment|github comment/i.test(prompt) && /CHANGES_REQUESTED/.test(io.run("gh", ["pr", "view", "--json", "reviewDecision"]).stdout || "")) {
+    policy.pushUnique(result.codes, "unresolved-review-comments", result.messages, "GitHub review still appears unresolved");
+  }
+  if (result.codes.length) return io.decide("block", policy.primaryReason(result.codes), result.messages, { reasonCodes: result.codes, changedPaths, cheapGates: result.gates });
+  io.write({});
+}
+
+function changedState(changedPaths, options = {}) {
+  const codes = [];
+  const messages = [];
+  const state = io.readJson(".naome/task-state.json");
+  const drift = policy.scopeDrift(changedPaths, state?.activeTask?.allowedPaths);
+  if (drift.length) policy.pushUnique(codes, "scope-drift", messages, `scope drift: ${drift.join(", ")}`);
+  const expensiveOwed = missingExpensiveProof(changedPaths, policy.expensiveProof(policy.owedProof(changedPaths, io.readJson(".naome/verification.json"))), state?.activeTask);
+  if (expensiveOwed.length) policy.pushUnique(codes, "owed-proof", messages, `owed proof: ${expensiveOwed.join(", ")}`);
+  if (repoStale()) policy.pushUnique(codes, "repository-model-stale", messages, "repository model is stale");
+  const gatePaths = options.pathScoped ? changedPaths : [];
+  const gates = cheapGates(gatePaths);
+  for (const gate of gates) policy.pushUnique(codes, gate.code, messages, gate.message);
+  return { codes, messages, expensiveOwed, gates, gateCommands: cheapGateCommands(gatePaths) };
+}
+
+function commitPushPreflight(command) {
+  if (!/\bgit\s+(commit|push)\b/.test(command.replace(/\s+/g, " "))) return null;
+  if (/\bgit\s+commit\b/.test(command)) return "commit-preflight: use `node .naome/bin/naome.js commit -m ...` so NAOME owns staging, proof, and commit gates.";
+  for (const gate of cheapGates()) return `push-preflight: ${gate.checkId} failed before git push.`;
+  return repoStale() ? "push-preflight: repository-model-stale failed before git push." : null;
+}
+
+function cheapGates(paths = []) {
+  return cheapGateChecks(paths).flatMap(([checkId, command, fn]) => fn().status ? [{ code: `${checkId}-failed`, checkId, command, message: `cheap gate failed: ${checkId}` }] : []);
+}
+function cheapGateCommands(paths = []) {
+  return cheapGateChecks(paths).map(([, command]) => command);
+}
+function cheapGateChecks(paths = []) {
+  const pathArgs = paths.flatMap((path) => ["--path", path]);
+  const displayPaths = paths.map(shellPath).join(" ");
+  const checks = [
+    ["diff-check", paths.length ? `git diff --check -- ${displayPaths}` : "git diff --check", () => io.runGit(paths.length ? ["diff", "--check", "--", ...paths] : ["diff", "--check"])],
+    ["repository-quality-check", paths.length ? `node .naome/bin/naome.js quality check ${pathArgs.join(" ")}` : "node .naome/bin/naome.js quality check --changed", () => io.runNaome(paths.length ? ["quality", "check", ...pathArgs] : ["quality", "check", "--changed"])],
+    ["repository-semantic-check", paths.length ? `node .naome/bin/naome.js semantic check ${pathArgs.join(" ")}` : "node .naome/bin/naome.js semantic check --changed", () => io.runNaome(paths.length ? ["semantic", "check", ...pathArgs] : ["semantic", "check", "--changed"])]
+  ];
+  if (!paths.length && hasActiveTask()) checks.push(["task-state-progress-check", "node .naome/bin/check-task-state.js --progress", () => io.taskCheck(["--progress"])]);
+  return checks;
+}
+function validateSearch(command) {
+  for (const segment of policy.searchSegments(command)) {
+    const result = io.runNaome(["workflow", "check-search", "--command", segment, "--json"]);
+    if (result.status === 0) continue;
+    const ids = io.parseJson(result.stdout)?.findings?.map((finding) => finding.id).filter(Boolean);
+    return ids?.length ? `${ids.join(",")}: NAOME rejected this broad search command.` : io.compact(`unsafe-search-command: ${result.stdout || result.stderr}`);
+  }
+  return null;
+}
+function changedFiles() {
+  const result = io.runGit(["status", "--porcelain=v1"]);
+  return result.status ? [] : result.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.replace(/^..\s+/, "").split(" -> ").pop()).filter((path, index, paths) => path && paths.indexOf(path) === index);
+}
+function postToolCheckedPaths(payload, command, changedPaths) {
+  const touched = policy.touchedPaths(payload, command);
+  if (!touched.length) return changedPaths;
+  return changedPaths.filter((path) => touched.some((touch) => path === touch || path.startsWith(`${touch}/`)));
+}
+function shellPath(path) {
+  return /[^A-Za-z0-9_./:-]/.test(path) ? JSON.stringify(path) : path;
+}
+function repoStale() {
+  const result = io.runNaome(["repo", "check", "--json"]);
+  return result.status !== 0 && /repository model is stale|repository-model-stale/i.test(`${result.stdout}\n${result.stderr}`);
+}
+
+function hasActiveTask() {
+  const state = io.readJson(".naome/task-state.json"); return Boolean(state?.activeTask && state.status === "implementing");
+}
+function missingExpensiveProof(changedPaths, checkIds, activeTask) {
+  const proofPaths = changedPaths.filter((path) => !isControlStatePath(path));
+  return proofPaths.length ? checkIds.filter((checkId) => !proofCoversChangedPaths(activeTask, checkId, proofPaths)) : [];
+}
+function proofCoversChangedPaths(activeTask, checkId, changedPaths) {
+  const proof = (activeTask?.proofResults || []).find((entry) => entry.checkId === checkId && entry.exitCode === 0);
+  const evidence = Array.isArray(proof?.evidence) ? proof.evidence : [];
+  return changedPaths.every((changedPath) => evidence.some((path) => evidenceCoversPath(path, changedPath)));
+}
+function evidenceCoversPath(evidencePath, changedPath) {
+  const evidence = String(evidencePath);
+  return evidence === changedPath || (evidence.endsWith("/") && String(changedPath).startsWith(evidence)) || (evidence.endsWith("/**") && String(changedPath).startsWith(evidence.slice(0, -3)));
+}
+function isControlStatePath(path) {
+  return path === ".naome/task-state.json" || path.startsWith(".naome/tasks/") || path.startsWith(".naome/cache/");
+}
+
+module.exports = { handleCodexHook };

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

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+
+const { handleCodexHook } = require("./codex-hook-runtime.js");
+
+handleCodexHook();

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

@@ -27,7 +27,7 @@ function main(argv) {
     return;
   }
 
-  if (["status", "next", "intent", "route", "explain", "doctor", "quality", "semantic", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
+  if (["status", "next", "intent", "route", "explain", "context", "doctor", "task", "quality", "semantic", "repo", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
     runNativeDecisionCommand(command, args);
     return;
   }
@@ -143,6 +143,10 @@ function commit(args) {
   }
 
   const message = parseCommitMessage(args);
+  const renderResult = spawnNative(root, ["task", "render-state", "--write", "--json"]);
+  if (renderResult.status !== 0) {
+    fail(`Cannot render NAOME task-state projection: ${renderResult.stderr.trim() || renderResult.stdout.trim()}`);
+  }
   const taskState = readTaskState(root);
 
   if (taskState.status !== "complete") {
@@ -328,14 +332,17 @@ function gitHead(root) {
 }
 
 function findHarnessRoot(startPath) {
-  return findAncestorWithMarker(startPath, [".naome", "task-state.json"]);
+  return findAncestorWithAnyMarker(startPath, [
+    [".naome", "task-state.json"],
+    [".naome", "tasks", "active.json"]
+  ]);
 }
 
-function findAncestorWithMarker(startPath, markerParts) {
+function findAncestorWithAnyMarker(startPath, markers) {
   let current = resolve(startPath);
 
   while (true) {
-    if (existsSync(join(current, ...markerParts))) {
+    if (markers.some((markerParts) => existsSync(join(current, ...markerParts)))) {
       return current;
     }
 
@@ -358,21 +365,32 @@ function printHelp() {
     "naome route --prompt <text> [--execute] [--json]",
     "naome explain --prompt-file <path> [--json]",
     "naome explain --prompt <text> [--json]",
+    "naome context select --changed [--json]",
+    "naome context select --prompt-file <path> [--json]",
+    "naome context select --prompt <text> [--json]",
     "naome doctor [--json]",
+    "naome task render-state [--write] [--json]",
+    "naome task migrate-ledger [--write] [--json]",
     "naome quality init [--baseline|--deep-baseline] [--json]",
     "naome quality check --changed [--include-scanned-paths] [--json]",
+    "naome quality check --path <path> [--path <path>...] [--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 check --path <path> [--path <path>...] [--json]",
     "naome semantic route --finding <id> [--json]",
     "naome semantic loop [--json]",
+    "naome repo model [--write] [--json]",
+    "naome repo check [--json]",
+    "naome repo explain --path <path> [--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 agent-plan|context-delta|proof-plan|capabilities|edit-watchdog|decision-gate|digest [--json]",
     "naome workflow search-profile|check-search|phases|processes|mutations [--json]",
     "naome install",
     "naome sync",
@@ -399,6 +417,19 @@ function installOrSync(command, args) {
       join(packageRoot, "bin", "naome-node.js"),
       ...args
     ], { stdio: "inherit" });
+    if (result.status === 0) {
+      const migration = spawnNative(root, ["task", "migrate-ledger", "--write", "--json"]);
+      if (migration.status !== 0) {
+        fail("task ledger migration failed after sync.");
+      }
+      const output = (migration.stdout || "").trim();
+      if (output) {
+        const parsed = JSON.parse(output);
+        if (parsed.updated && parsed.migration && parsed.migration.source === "task-state") {
+          console.log("task ledger migrated from task-state");
+        }
+      }
+    }
     process.exit(result.status === null ? 1 : result.status);
   }
 

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

@@ -3,15 +3,17 @@
   "installedAt": null,
   "integrity": {
     ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
-    ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-    ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
+    ".naome/bin/check-task-state.js": "sha256:df54489a22b426180266e5e0fb5f9ec381477419f688435248afbf2b9b38ea81",
+    ".naome/bin/naome.js": "sha256:d343f367da21bf45272331eec2ea34862a0bf056978780c62d6cae02e0f7993a",
     ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
     ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
-    "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-    "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
+    "AGENTS.md": "sha256:e8b2fc786c1c72b69ba8f2b2ffce4f459e799c7453ce9ff4a9f6448a8f9e6b4f",
+    "docs/naome/agent-workflow.md": "sha256:78faeb4eed157b60f0b60bc43da36c713fc4a3436b93bd963ce5f3c12dc91f22",
+    "docs/naome/context-economy.md": "sha256:3ed5075815ecf4ada46a5e65438769310307c35759fcd46b13dc0b96e02bebd9",
     "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
-    "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
-    "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",
+    "docs/naome/first-run.md": "sha256:f1a2412f1b542e61c79b5ba65a3fdaa810b0f95cf79d9f734256418cdcfb19aa",
+    "docs/naome/index.md": "sha256:07ef776f49130319a5280bdb3ae38af22141708253f38eb983a4336fbae1b25a",
+    "docs/naome/task-ledger.md": "sha256:1e524085a2f88811941fd9f2f48ca826bc3e0e4816039d07e795637847714cbd",
     "docs/naome/upgrade.md": "sha256:2c60f0441bbd98bd528d109b30a7ded4b0ad55d61ffb9f52edac9e93b7999cb1"
   },
   "machineOwned": [
@@ -24,7 +26,9 @@
     "docs/naome/index.md",
     "docs/naome/first-run.md",
     "docs/naome/agent-workflow.md",
+    "docs/naome/context-economy.md",
     "docs/naome/execution.md",
+    "docs/naome/task-ledger.md",
     "docs/naome/upgrade.md"
   ],
   "name": "naome",
@@ -36,12 +40,14 @@
     ".naome/task-state.json",
     ".naome/upgrade-state.json",
     ".naome/verification.json",
+    ".naome/repository-model.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-model.md",
     "docs/naome/repository-quality.md",
     "docs/naome/repository-structure.md",
     "docs/naome/security.md",

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

@@ -0,0 +1,6 @@
+{
+  "schema": "naome.repository-model.v2",
+  "version": 2,
+  "status": "ready",
+  "facts": []
+}

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

@@ -13,7 +13,9 @@
   },
   "enabledAdapters": [],
   "disabledChecks": [],
-  "ignoredPaths": [],
+  "ignoredPaths": [
+    ".naome/tasks/**"
+  ],
   "generatedPaths": [
     "**/*.min.js",
     "**/*.map",

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

@@ -52,6 +52,19 @@
         ".naome/repository-quality-baseline.json"
       ],
       "lastVerified": null
+    },
+    {
+      "id": "repository-semantic-check",
+      "command": "node .naome/bin/naome.js semantic check --changed",
+      "cwd": ".",
+      "purpose": "Validate changed files against deterministic NAOME semantic cleanup rules.",
+      "cost": "fast",
+      "source": "NAOME built-in",
+      "evidence": [
+        ".naome/repository-quality.json",
+        ".naome/repository-quality-baseline.json"
+      ],
+      "lastVerified": null
     }
   ],
   "phases": [
@@ -67,7 +80,8 @@
       "id": "quality",
       "order": 20,
       "checkIds": [
-        "repository-quality-check"
+        "repository-quality-check",
+        "repository-semantic-check"
       ]
     },
     {

package/templates/naome-root/AGENTS.md

@@ -4,101 +4,56 @@ This repository uses NAOME as its coding-agent harness.
 
 ## Start Here
 
-1. Read `.naomeignore`.
-2. Do not read any file or directory matched by `.naomeignore`.
-3. If `docs/naome/index.md` or `.naome/bin/check-harness-health.js` is missing,
-   do not begin feature work. Install the NAOME CLI with
-   `npm install -g @lamentis/naome`, then run `naome sync --check-update`
-   from the repository root. Then restart this list.
-4. Read `docs/naome/index.md`.
-5. Read `.naome/init-state.json`.
-6. Read `.naome/task-state.json`.
-7. Read `.naome/upgrade-state.json`.
-8. Run `node .naome/bin/check-harness-health.js`.
-9. If harness health fails, do not begin feature work. Repair the machine-owned
-   harness files with `naome update` followed by `naome sync`, or ask the user
-   for one of the listed repair decisions.
-10. If upgrade status is `needs_agent_upgrade`, do not begin feature work. Run
-   or continue `docs/naome/upgrade.md`.
-11. If `initialized` is `false`, do not begin feature work. Run or continue the
-   NAOME first-run protocol in `docs/naome/first-run.md`.
-12. Before accepting feature work, run
-   `node .naome/bin/check-task-state.js --admission`.
-13. If task admission fails, follow `docs/naome/execution.md`.
-14. If `initialized` is `true`, follow `docs/naome/agent-workflow.md`.
+1. Read `.naomeignore`; it is a hard read boundary.
+2. Do not read paths matched by `.naomeignore`.
+3. If `.naome/bin/check-harness-health.js` is missing, run
+   `naome sync --check-update` from the repository root, then restart.
+4. Read `.naome/task-state.json`.
+5. Run `node .naome/bin/check-harness-health.js`.
+6. If harness health fails, stop normal feature work and repair with
+   `naome update` followed by `naome sync`, or ask for the listed decision.
+7. Run `node .naome/bin/check-task-state.js --admission` before accepting new
+   feature work.
+8. For natural-language work, write the request to a prompt file and run
+   `node .naome/bin/naome.js route --prompt-file <path> --execute --json`.
+9. Run `node .naome/bin/naome.js context select --prompt-file <path> --json`
+   after route, or `node .naome/bin/naome.js context select --changed --json`
+   when continuing an existing diff.
+10. Read only `requiredContext` from context selection. Read `optionalContext`
+    only when blocked.
+11. If first-run or upgrade state blocks work, read only the document named by
+    the blocker, such as `docs/naome/first-run.md` or `docs/naome/upgrade.md`.
 
 ## Core Rules
 
-- Prefer discovered repository facts over assumptions.
-- Do not look for generic root steering files such as `ARCHITECTURE.md` or
-  `docs/index.md` unless this repository's NAOME docs explicitly name them.
-  NAOME's default architecture and index files are
-  `docs/naome/architecture.md` and `docs/naome/index.md`.
-- Record only facts from this target repository or from the user. Do not import
-  parent-workspace, outer-agent, chat, or unrelated repository instructions into
-  this repository's NAOME docs.
+- Prefer deterministic NAOME JSON commands over broad Markdown reading.
 - Keep changes small and task-focused.
-- Read only the NAOME docs relevant to the current task.
-- Run Harness Health before Task Admission.
-- For natural-language work requests, prefer
-  `naome route --prompt-file <path> --execute --json` and follow its
-  `userMessage`, `humanOptions`, `requiredContext`, `taskRoot`, `worktree`, and
-  `canCreateTask` fields. If `taskRoot` differs from the current directory,
-  continue the task in `taskRoot`; the original worktree contains unrelated user
-  edits that must remain untouched. Pure deterministic harness refresh diffs
-  are baselined in the current worktree before task creation; they must not
-  create repair-loop task worktrees. Use `naome explain --prompt-file <path>
-  --json` only for debugging policy.
-- If route blocks or performs no mutation, do not fall back to raw `git commit`,
-  IDE commit, `git add`, or hook bypass commands. Only execute a commit when
-  NAOME route/commit performs it successfully or the user takes manual Git
-  ownership outside the agent task.
-- If the user explicitly asks to commit their own unowned changes, use NAOME
-  route so the configured quality gate runs first. NAOME commits only the exact
-  paths it evaluated, requires committed verification coverage for every path,
-  and rechecks the final stabilized diff before creating the commit.
-- Repair requests may baseline deterministic harness refresh files, but they
-  must leave unrelated user edits untouched unless the user explicitly takes
-  manual Git ownership.
-- Machine-owned NAOME command shims, schemas, workflow docs, archives, and
-  native binaries may be local-only ignored files. Missing local-only files are
-  repaired with `naome update` followed by `naome sync`; they are not project
-  context.
-- Enforce Task Admission before accepting new feature work.
 - Do not start feature work while the git diff contains setup, upgrade,
   previous-task, or other unowned changes.
-- Treat `.naomeignore` as a hard read boundary. Do not inspect ignored paths
-  unless the user first removes the path from `.naomeignore`.
-- Use `naome workflow search-profile` or equivalent excludes for broad searches;
-  hidden searches must exclude `.git`, `.naome/archive`, dependencies, build
+- If route blocks or performs no mutation, do not fall back to raw `git commit`,
+  IDE commit, `git add`, or hook bypass commands.
+- Use `node .naome/bin/naome.js repo explain --path <path> --json`,
+  `structure explain --path <path> --json`, and
+  `quality check --path <path>` for path-specific facts and early feedback.
+- 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.
-- Use `docs/naome/testing.md` and `.naome/verification.json` before claiming
-  completion.
-- Before claiming completion, run the narrowest meaningful verification that can
-  falsify the change.
+- Before claiming completion, use `docs/naome/testing.md` and
+  `.naome/verification.json`, run the narrowest meaningful proof, then run the
+  final changed-file gates.
 - Report what changed, what was verified, and what remains uncertain.
 
 ## Local Authority Boundary
 
 The root `AGENTS.md` and NAOME files are the repository harness authority.
-
-Global skills, editor rules, or agent defaults may be used only as generic
-execution technique. They must not add repository policy, required files,
-architecture layers, plan formats, verification rules, or product assumptions
-unless those rules exist in this repository or the user explicitly confirms them
-for this repository.
-
-If global instructions conflict with NAOME, follow NAOME for repository-local
-workflow. Record a conflict in `docs/naome/decisions.md` only when the user makes
-a durable local decision.
-
-## Nested Agent Instructions
-
-Nested `AGENTS.md` files may provide task-local evidence for the directory they
-govern. They must not override `.naomeignore`, NAOME workflow, security rules,
-or the root harness authority.
-
-## Archived Instructions
+Global skills or editor defaults may be used only as generic technique. They
+must not add repository policy, required files, architecture layers,
+verification rules, or product assumptions unless this repository or the user
+explicitly confirms them.
+
+Nested `AGENTS.md` files may provide task-local evidence for their directory.
+They must not override `.naomeignore`, NAOME workflow, security rules, or the
+root harness authority.
 
 Files matched by `.naomeignore` are not active instructions. Historical
 snapshots in `.naome/archive/` must not be read or used as context unless the

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

@@ -48,11 +48,30 @@ Use this workflow after first-run intake is complete.
 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.
-16. Read only the `requiredContext` returned by route/status plus the smallest
-    task-relevant NAOME docs.
-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.
+16. Run `node .naome/bin/naome.js context select --prompt-file <path> --json`
+    for the routed request, or `node .naome/bin/naome.js context select
+    --changed --json` when continuing an existing diff.
+17. Read only `requiredContext` from context selection. Read `optionalContext`
+    only when blocked.
+18. Run `node .naome/bin/naome.js workflow agent-plan --json` to get the
+    execution plan ledger, context delta, proof plan, capability graph,
+    edit-session watchdog, and decision gate before broad exploration.
+19. Inspect the existing code or docs before proposing changes.
+20. When stack, build, source-root, test-root, or generated-path facts matter,
+    run `naome repo check --json`. If it reports stale facts, run
+    `naome repo model --write --json`; use
+    `naome repo explain --path <path> --json` for path-specific facts instead
+    of reading broad Markdown summaries. Normal gates also report stale
+    repository facts through `naome doctor`, progress checks, and
+    `quality check --changed`.
+21. When adding or encountering a new language, framework, package manager,
+    build system, or generated-file convention, run
+    `naome quality reconcile --json`. If it reports missing adapters, run
+    `naome quality reconcile --write` instead of hand-editing
+    `enabledAdapters`. Quality gates also report `adapter-policy-stale` when
+    repository signals and committed policy drift.
+22. Read `testing.md` and `.naome/verification.json`.
+23. Identify the required proof before claiming success.
 
 ## Instruction Boundaries
 
@@ -74,6 +93,14 @@ Use this workflow after first-run intake is complete.
 - Do not read or use files matched by `.naomeignore`.
 - Do not overwrite user work or existing project policy.
 - Update NAOME docs only when the change reveals durable project knowledge.
+- Prefer deterministic NAOME JSON commands for repository facts; Markdown should
+  explain workflow or contain human-readable views, not become hidden policy.
+- After writing or heavily editing a file, run
+  `node .naome/bin/naome.js quality check --path <path>` for early feedback.
+- For a small touched set, run
+  `node .naome/bin/naome.js workflow edit-watchdog --path <path> --json` to
+  get path-scoped quality commands and scope-drift findings before the final
+  changed gate.
 - Use `node .naome/bin/check-task-state.js --progress` for in-flight task
   validation. Use the normal task-state check only after setting `complete`.
   Scope changes outside `allowedPaths` require human review before continuing.
@@ -83,24 +110,33 @@ Use this workflow after first-run intake is complete.
 1. Identify changed files.
 2. Match them against `.naome/verification.json`.
 3. Run the required checks when available.
-4. Record proof in `.naome/task-state.json`, using compact `proofPathSets` and
-   `proofBatches` when several checks share the same evidence or timestamp.
-   Include every changed in-scope path reported by git in expanded proof
-   evidence.
-5. Do not list `.naome/task-state.json` as task scope or proof evidence.
-6. Stop tracked long-running processes or mark them explicitly allowed in
+4. Prefer ledger-backed task updates. `naome sync` migrates active legacy
+   task-state automatically; if a legacy-only active task is still present, run
+   `node .naome/bin/naome.js task migrate-ledger --write --json` before adding
+   completion proof.
+5. Record proof in `.naome/tasks/<task-id>/proofs/`. If legacy compatibility
+   work is unavoidable, use compact `proofPathSets` and `proofBatches` in
+   `.naome/task-state.json` and include every changed in-scope path reported by
+   git in expanded proof evidence.
+6. Run `node .naome/bin/naome.js task render-state --write --json` before
+   external compatibility checks. Do not hand-edit the rendered projection when
+   `.naome/tasks/active.json` exists.
+7. Do not list `.naome/task-state.json` or `.naome/tasks/` as task scope or
+   proof evidence.
+8. Stop tracked long-running processes or mark them explicitly allowed in
    `.naome/processes.json`.
-7. Set task state to `complete`.
-8. Run `node .naome/bin/check-task-state.js`.
-9. If the task-state check prints a next-task admission notice, do not repeat
+9. Set task status to `complete` in the ledger event stream or legacy task
+   state, then render the projection.
+10. Run `node .naome/bin/check-task-state.js`.
+11. If the task-state check prints a next-task admission notice, do not repeat
    internal baseline options in the final response. Use the machine-generated
    `userMessage` from route/status and mention `humanOptions` only when that
    array is non-empty.
-10. If no rule matches or the task check fails, report the gap and ask for human
+12. If no rule matches or the task check fails, report the gap and ask for human
    review before claiming completion.
-11. Report changed files, exact commands, results, and remaining risk.
-12. Only ask the user for options when intent blocks, the user explicitly asks
-    to review/revise/cancel, or automatic baselining fails.
+13. Report changed files, exact commands, results, and remaining risk.
+14. Only ask the user for options when intent blocks, the user explicitly asks
+   to review/revise/cancel, or automatic baselining fails.
 
 ## Commit And Push