@lamentis/naome 1.3.0 → 1.3.1

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
 

package/templates/naome-root/docs/naome/codex-hooks.md

@@ -0,0 +1,82 @@
+# Optional Codex Hooks
+
+NAOME can install repo-local Codex hooks as an optional acceleration layer for coding agents.
+
+Hooks are not the source of truth. They provide earlier feedback before an agent spends tokens on work that normal NAOME gates would reject later.
+
+Authoritative enforcement remains in:
+
+- `.naome/task-state.json` validation
+- `naome route`
+- `naome quality` and `naome semantic` gates
+- `naome commit`
+- repository Git hooks
+- verification proof checks
+
+## Install Or Skip
+
+`naome install` and `naome sync` may ask whether to install optional Codex hooks.
+
+Answering no is valid. The repository remains fully usable for humans, CI, and agents without Codex hook support.
+
+For non-interactive environments, NAOME skips optional hooks unless explicitly requested:
+
+```sh
+NAOME_CODEX_HOOKS=1 naome sync
+NAOME_CODEX_HOOKS=0 naome sync
+```
+
+## Events
+
+The installed dispatcher listens to these Codex events:
+
+- `UserPromptSubmit`: performs read-only prompt classification and repo/task inspection. Codex Desktop currently accepts no non-blocking warning decision here, so advisory output is intentionally silent.
+- `PreToolUse`: blocks clear unsafe commands before execution, including destructive Git operations, hook bypasses, force pushes, `.naome/archive` reads, `.naomeignore` reads, and broad searches that do not honor NAOME search boundaries. It also runs commit/push preflight checks.
+- `PostToolUse`: after edits, records changed-file state, narrows checks to files touched by the current tool call when Codex provides a path, compares those files with active task ownership, checks repository-model freshness, and runs cheap path-scoped gates. Non-blocking edit guidance is cached for later Stop/preflight decisions rather than emitted as an unsupported warning.
+- `PermissionRequest`: performs read-only escalation risk classification. Codex Desktop currently accepts no non-blocking warning decision here, so advisory output is intentionally silent.
+- `Stop`: prevents misleading completion claims when scope drift, stale repository-model data, missing proof, an unpushed requested branch, or unresolved requested review comments are still visible.
+
+## Blocking And Advisory Checks
+
+Hard blocks are reserved for clear safety violations:
+
+- destructive commands such as hard resets, forced cleans, and deleting `.git`
+- hook bypasses such as `--no-verify`
+- force pushes, including `--force`, `--force-with-lease`, and `-f`
+- reads or searches inside `.naome/archive` or paths matched by `.naomeignore`
+- broad search commands that fail NAOME search-profile validation
+- commit/push attempts that would skip required ownership, scope, proof, or repository-model checks
+- final responses that would claim completion while required proof or scope checks are still failing
+
+Hook output is conservative for Codex Desktop compatibility: hooks emit `{}` for allowed/advisory outcomes and emit only `{"decision":"block","reason":"..."}` for true blocks. Stable reason codes are embedded in the block reason text.
+
+## Edit-Time Gates
+
+After file edits, hooks run only fast deterministic gates. When the tool input identifies touched files, PostToolUse scopes these checks to those files instead of the whole diff:
+
+- `git diff --check -- <touched-paths>`
+- `node .naome/bin/naome.js quality check --path <touched-path>`
+- `node .naome/bin/naome.js semantic check --path <touched-path>`
+- active-task scope checking for the touched paths
+
+If the touched paths cannot be inferred, PostToolUse falls back to the current changed-file set. These checks are debounced by the current diff signature plus the checked path set. Repeated hook calls over the same content reuse the previous result so normal editing stays responsive.
+
+Stop, commit, and push preflight stay full-diff checks. They verify the complete changed-file set so earlier unrelated drift or proof failures cannot be hidden by a later narrow edit.
+
+Full suites such as installer tests, Rust builds, package dry-runs, and CI-like workflows are treated as owed proof based on changed paths. They are not run automatically after every edit because they are too slow and noisy for real-time feedback.
+
+Every hook advisory calculation maps to a normal NAOME command or gate. If hooks are unavailable, disabled, or not installed, humans can keep working by following the normal route, context-selection, task-state, quality, semantic, verification, and commit gates directly.
+
+## Local Files
+
+Opting in installs:
+
+- `.codex/config.toml`
+- `.codex/hooks.json`
+- `.naome/bin/codex-hook.js`
+- `.naome/bin/codex-hook-io.js`
+- `.naome/bin/codex-hook-policy.js`
+- `.naome/bin/codex-hook-runtime.js`
+- `docs/naome/codex-hooks.md`
+
+These files are repo-local. They are managed only after opt-in and are not required by repositories that decline hooks.

package/templates/naome-root/docs/naome/context-economy.md

@@ -0,0 +1,73 @@
+# Context Economy
+
+NAOME reduces agent token use by selecting task context before broad reading.
+
+## Commands
+
+- `node .naome/bin/naome.js workflow agent-plan --json` returns the full
+  deterministic run-control bundle for the current task: execution plan,
+  context delta, proof plan, capability graph, edit watchdog, and decision
+  gate.
+- `node .naome/bin/naome.js context select --prompt-file <path> --json`
+  selects context from explicit file/path mentions in a user request.
+- `node .naome/bin/naome.js context select --changed --json` selects context
+  from the current diff.
+- `node .naome/bin/naome.js context select --prompt <text> --json` is useful
+  for diagnostics and small local prompts.
+
+## Output
+
+The selector returns:
+
+- `requiredContext`: read these files first.
+- `optionalContext`: read only when required context is insufficient.
+- `forbiddenContext`: paths that must not be used as agent context.
+- `capsule`: compact task type, such as `quality-work` or `source-work`.
+- `commands`: early path-scoped checks plus final changed gates.
+- `budgetLedger`: selected file count, avoided file count, estimated lines, and
+  estimated tokens.
+
+## Agent Rule
+
+After routing a task, run context selection and read only `requiredContext`.
+Do not read broad NAOME docs just because they exist. Use `optionalContext`
+only when blocked, and prefer path-specific commands such as
+`repo explain --path`, `structure explain --path`, and
+`quality check --path`.
+
+## Run-Control Models
+
+The agent-run plan combines seven token-saving models:
+
+- Execution plan ledger: ordered read, edit, quality, progress, and proof
+  steps for the active task.
+- Context delta: which already-read files are reusable, stale, or still
+  required.
+- Proof planner: the next minimal checks in verification phase order, with
+  broad checks withheld until earlier gates pass.
+- Output digest: stable command summaries that keep exit code, command, cwd,
+  relevant lines, affected paths, and artifacts without expanding full logs.
+- Capability graph: machine-readable languages, build systems, adapters, roots,
+  and verification edges.
+- Edit-session watchdog: path-scoped quality commands and scope-drift findings
+  for touched files.
+- Decision gate: `continue`, `create_task`, `ask_human`, or `stop` with reason
+  codes.
+
+Use the focused subcommands when only one model is needed:
+
+```text
+node .naome/bin/naome.js workflow context-delta --read-path <path> --json
+node .naome/bin/naome.js workflow proof-plan --json
+node .naome/bin/naome.js workflow capabilities --json
+node .naome/bin/naome.js workflow edit-watchdog --path <path> --json
+node .naome/bin/naome.js workflow decision-gate --json
+node .naome/bin/naome.js workflow digest --command <cmd> --exit-code <code> --output-file <path> --json
+```
+
+## Why Runs Get Faster
+
+Agent runs become faster because fewer files are loaded, fewer long outputs are
+expanded, and quality or structure issues are caught while the touched file is
+still small. The final changed-file gates remain required; context selection is
+an early feedback and read-boundary tool, not a replacement for verification.

package/templates/naome-root/docs/naome/first-run.md

@@ -30,21 +30,32 @@ context.
 
 1. Read `.naomeignore` and exclude every matched path from intake.
 2. Inspect existing repository instructions and docs, including README,
-   contributing docs, architecture docs, agent instruction files, and CI config.
-3. Detect stack, frameworks, package managers, project layout, entrypoints,
-   test tools, lint/typecheck/build commands, and deployment hints.
-4. Identify risky areas such as auth, billing, secrets, migrations, production
+   contributing docs, agent instruction files, and CI config.
+3. Refresh deterministic repository facts with
+   `naome repo model --write --json`. This records stack, package managers,
+   source roots, test roots, generated roots, and verification ids in
+   `.naome/repository-model.json`.
+4. Detect entrypoints, test tools, lint/typecheck/build commands, deployment
+   hints, and sensitive areas that are not yet derivable from deterministic
+   files.
+   Run `naome quality reconcile --json` after policy files exist; if detected
+   repository signals require missing adapters, use
+   `naome quality reconcile --write` so quality and structure policy match the
+   observed stack.
+5. Identify risky areas such as auth, billing, secrets, migrations, production
    config, customer data, generated files, or fragile inherited code.
-5. Build the Proof Harness:
+6. Build the Proof Harness:
    - inspect package files, build files, Makefiles, and CI workflows
    - record real checks in `.naome/verification.json`
-   - mirror the human-readable map in `testing.md`
+   - keep `testing.md` as a human-readable view, not the source of truth
    - run the fastest safe check when possible and record the result
    - preserve the JSON keys and allowed values documented below
-6. Fill `repo-profile.md`, `testing.md`, `architecture.md`, and `security.md`.
-7. Ask the user for critical missing product intent, forbidden zones, or
+7. Fill only the minimal human-readable notes still needed in `repo-profile.md`,
+   `testing.md`, `architecture.md`, and `security.md`. Do not duplicate facts
+   that already live in deterministic JSON.
+8. Ask the user for critical missing product intent, forbidden zones, or
    verification commands only if repository evidence is insufficient.
-8. Update `.naome/init-state.json`:
+9. Update `.naome/init-state.json`:
    - use `intakeStatus: "complete"` and `initialized: true` only when the
      completion gate is satisfied
    - use `intakeStatus: "needs_user_context"` and keep `initialized: false`
@@ -57,11 +68,11 @@ context.
 Initialization is complete only when:
 
 - `repo-profile.md` describes this specific repository.
-- `testing.md` records at least one real verification path.
-- `.naome/verification.json` contains the same durable checks and change-type
-  rules recorded in `testing.md`.
-- `architecture.md` describes observed structure and known or assumed
-  boundaries.
+- `.naome/repository-model.json` is current.
+- `.naome/verification.json` contains durable checks and change-type rules.
+- `testing.md` records a readable summary of the real verification paths.
+- `architecture.md` records only structure or boundaries that are not already
+  represented in deterministic model or structure policy.
 - `security.md` records sensitive areas or states that none are known yet.
 - remaining unknowns are explicit.
 

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

@@ -13,18 +13,23 @@ for the current step.
 6. `execution.md`, before accepting or completing feature work
 7. `first-run.md`, only when `initialized` is `false`
 8. `upgrade.md`, only when upgrade `status` is `needs_agent_upgrade`
-9. `repo-profile.md`
-10. `architecture.md`
-11. `testing.md`
+9. `.naome/repository-model.json`
+10. `context-economy.md`, when selecting task context
+11. `repository-model.md`, when stack, build, or path facts matter
 12. `.naome/verification.json`
-13. `repository-quality.md`, when repository-quality checks or cleanup are relevant
-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
+13. `repo-profile.md`, only for legacy human-readable project notes
+14. `architecture.md`, only for legacy human-readable project notes
+15. `testing.md`
+16. `repository-quality.md`, when repository-quality checks or cleanup are relevant
+17. `repository-structure.md`, when path roles or structure cleanup are relevant
+18. `security.md`
+19. `agent-workflow.md`
+20. `decisions.md`, when changing durable project policy
 
 ## Source Types
 
+- Deterministic repository facts live in `.naome/repository-model.json` and are
+  refreshed with `naome repo model --write`.
 - Discovered facts come from repository files and commands.
 - Confirmed facts were explicitly confirmed by a human or existing
   authoritative documentation.
@@ -33,8 +38,11 @@ for the current step.
 
 ## Context Rule
 
-Do not load every NAOME document by default. Start from this index, then open the
-smallest set of files needed for the task.
+Do not load every NAOME document by default. Run
+`node .naome/bin/naome.js context select --prompt-file <path> --json` after
+routing natural-language work, or `node .naome/bin/naome.js context select
+--changed --json` for an existing diff. Read `requiredContext` first and
+`optionalContext` only when blocked.
 Do not search for generic root `ARCHITECTURE.md` or `docs/index.md` files unless
 this repository's NAOME docs explicitly reference them.
 

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

@@ -0,0 +1,92 @@
+# Repository World Model
+
+The repository model is the deterministic source for machine-readable facts
+about this repository. It keeps stack and layout facts out of free-form
+Markdown so agents can make repeatable decisions.
+
+## Files
+
+- `.naome/repository-model.json` stores canonical facts.
+- `.naome/verification.json` stores runnable checks and change-type proof
+  policy.
+- Repository-quality and repository-structure policy store quality adapters and
+  layout rules.
+- Markdown documents explain workflow and summarize human context; they are not
+  the primary store for build, stack, or path-role facts.
+
+## Commands
+
+- `naome repo model --write --json` refreshes the model from repository files.
+- `naome repo check --json` verifies the committed model is current.
+- `naome repo explain --path <path> --json` explains the role and language for a
+  path using the canonical model.
+
+## Facts
+
+`naome.repository-model.v2` keeps the backward-compatible flat `facts[]` list
+and adds typed world-model sections. `naome.repository-model.v1` remains
+readable; new writes prefer v2.
+
+Flat facts are deterministic records with stable ids:
+
+- `language:<value>`
+- `packageManager:<value>`
+- `buildSystem:<value>`
+- `sourceRoot:<path>`
+- `testRoot:<path>`
+- `docsRoot:<path>`
+- `generatedRoot:<path>`
+- `artifactRoot:<path>`
+- `verificationCheck:<id>`
+
+Each fact includes evidence paths and a source. Do not hand-edit generated facts
+as normal workflow. Refresh them with the command above.
+
+## World Sections
+
+The v2 model stores typed sections so agents do not need to infer repository
+shape from prose:
+
+- `languages`, `packageManagers`, and `buildSystems`
+- `adapters` detected from deterministic stack signals
+- `roots` for source, test, docs, generated, and artifact paths
+- `entities` for packages, apps, and modules
+- `pathFacts` for significant paths with role, module, entity, language, and
+  generated/artifact flags
+- `verificationChecks` copied from `.naome/verification.json`
+
+These sections are generic and adapter-extensible. Product defaults must not
+contain repository-specific exceptions.
+
+## Agent Rule
+
+When a task depends on the stack, package manager, build system, source roots,
+test roots, generated roots, or verification ids, read or refresh the repository
+model instead of searching broad Markdown files. If the model is stale, update it
+first, then continue with the task.
+
+For a specific path, use:
+
+```text
+naome repo explain --path <path> --json
+```
+
+The explanation returns the canonical role, language, module, entity, matching
+facts, and evidence for that path.
+
+## Drift Gates
+
+NAOME does not silently rewrite `.naome/repository-model.json` during normal
+gates. Instead, stale facts are reported deterministically:
+
+- `naome doctor --json` reports a stale repository model section.
+- `node .naome/bin/check-task-state.js --progress` blocks active work until the
+  model is refreshed.
+- `naome quality check --changed --json` emits `repository-model-stale` as a
+  changed-code finding.
+
+The fix is explicit and idempotent:
+
+```text
+naome repo model --write --json
+```