@lamentis/naome 1.0.2 → 1.1.1

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

@@ -5,29 +5,44 @@ Use this workflow after first-run intake is complete.
 ## Before Editing
 
 1. Read `.naome/task-state.json` and `execution.md`.
-2. Run `node .naome/bin/naome.js status` and use its allowed actions as the
-   current machine-generated decision.
-3. Run `node .naome/bin/check-harness-health.js`.
-4. If harness health fails, do not start new feature work. Ask the user to
+2. For a natural-language user request, prefer
+   `node .naome/bin/naome.js route --prompt-file <path> --execute --json`.
+   Use its `userMessage`, `humanOptions`, `requiredContext`, and
+   `canCreateTask` fields instead of inventing routing or final-response text.
+   If route returns a `taskRoot` different from the current directory, continue
+   the task from that path and leave the original worktree untouched.
+3. Use `node .naome/bin/naome.js explain --prompt-file <path> --json` only when
+   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
    choose `repair_harness`, `review_harness_diff`, or
    `cancel_repair_baseline`.
-5. Run `node .naome/bin/check-task-state.js --admission`.
-6. If task admission fails, do not start new feature work.
-   When the block is completed NAOME install or upgrade changes, ask the user
-   to choose `commit_upgrade_baseline`, `review_diff_first`, or
-   `cancel_upgrade_baseline`.
-   When the block is a completed task diff, ask the user to choose
-   `commit_task_baseline`, `review_task_diff`, `request_task_changes`, or
-   `cancel_task_changes`.
-7. Record the passed admission check in `.naome/task-state.json` when starting
+7. Run `node .naome/bin/check-task-state.js --admission`.
+8. 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
+   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
    the task.
-8. Restate the task in concrete terms.
-9. Read `.naomeignore`.
-10. Exclude every path matched by `.naomeignore` from context gathering.
-11. Read the task-relevant NAOME docs.
-12. Inspect the existing code or docs before proposing changes.
-13. Read `testing.md` and `.naome/verification.json`.
-14. Identify the required proof before claiming success.
+11. Restate the task in concrete terms.
+12. Read `.naomeignore`.
+13. Exclude every path matched by `.naomeignore` from context gathering.
+14. Read only the `requiredContext` returned by route/status plus the smallest
+    task-relevant NAOME docs.
+15. Inspect the existing code or docs before proposing changes.
+16. Read `testing.md` and `.naome/verification.json`.
+17. Identify the required proof before claiming success.
 
 ## Instruction Boundaries
 
@@ -62,19 +77,25 @@ Use this workflow after first-run intake is complete.
 5. Do not list `.naome/task-state.json` as task scope or proof evidence.
 6. Set task state to `complete`.
 7. Run `node .naome/bin/check-task-state.js`.
-8. If the task-state check prints a next-task admission notice, report it to
-   the user with the exact listed options.
+8. 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.
 9. If no rule matches or the task check fails, report the gap and ask for human
    review before claiming completion.
 10. Report changed files, exact commands, results, and remaining risk.
-11. Do not say there are no open gaps while the completed task diff still needs
-    a user baseline decision.
+11. Only ask the user for options when intent blocks, the user explicitly asks
+    to review/revise/cancel, or automatic baselining fails.
 
 ## Commit And Push
 
 - Prefer `naome commit -m "type(scope): summary"` for task baselines.
 - If `naome` is not on `PATH`, run
   `node .naome/bin/naome.js commit -m "type(scope): summary"`.
+- Never treat a blocked NAOME route as permission to run plain `git commit`.
+  A commit fallback is valid only when NAOME itself executed it successfully or
+  when the user explicitly leaves NAOME automation and owns the manual Git
+  action.
 - Manual `git commit` and IDE commits are guarded by local `.git/hooks` shims,
   but agents must still reconcile Git state because hooks can be bypassed.
 - If a user already committed the diff, compare current `HEAD`, task proof, and

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

@@ -6,17 +6,8 @@ Use this protocol before starting or completing normal feature work.
 
 Read `.naome/task-state.json` before accepting a new user task.
 
-Before accepting feature work, run:
-
-```sh
-node .naome/bin/check-harness-health.js
-```
-
-Then run:
-
-```sh
-node .naome/bin/check-task-state.js --admission
-```
+Before accepting feature work, run `node .naome/bin/check-harness-health.js`,
+then `node .naome/bin/check-task-state.js --admission`.
 
 You may start new feature work only when harness health and admission both pass.
 If health fails, ask the user to choose `repair_harness`,
@@ -31,36 +22,53 @@ Also read `.naome/upgrade-state.json`. If upgrade status is
 `needs_agent_upgrade`, do not start feature work. Finish `upgrade.md` first.
 
 Task Control validates the real git diff. After installing or upgrading NAOME,
-ask the user to choose `commit_upgrade_baseline`, `review_diff_first`, or
-`cancel_upgrade_baseline` before starting normal feature work. Admission also
-fails for previous-task, setup, upgrade, or other unowned changes in the git
-diff.
-
-When admission fails because the git diff is dirty, use the exact options it
-prints:
-
-- Harness repair diff: `commit_repair_baseline`, `review_repair_diff`,
-  `cancel_repair_baseline`.
-- Completed task diff: `commit_task_baseline`, `review_task_diff`,
-  `request_task_changes`, `cancel_task_changes`.
-- Install or upgrade diff: `commit_upgrade_baseline`, `review_diff_first`,
-  `cancel_upgrade_baseline`.
-
-Do not commit NAOME install or upgrade changes unless the user explicitly
-chooses `commit_upgrade_baseline`. If they choose it, commit only NAOME install
-or upgrade files.
+normal feature work waits until setup is baselined. Admission also fails for
+previous-task, setup, upgrade, or other unowned changes in the git diff.
+
+Prompt intent routing is machine policy, not agent guesswork. When a user asks
+for work while task/setup/unowned diff exists, run
+`node .naome/bin/naome.js route --prompt-file <path> --execute --json`.
+Follow `policyAction`, `userMessage`, `humanOptions`, `requiredContext`, and
+`canCreateTask`. If route returns `taskRoot` different from the current
+directory, continue the task from that path and leave the original worktree
+untouched. Route performs valid automatic baselines, can create isolated task
+worktrees around unrelated user edits, and reruns admission when policy allows,
+so agents do not ask for internal baseline decisions on normal auto paths.
+Pure deterministic harness refresh diffs are baselined in the current worktree
+before new task creation; they do not create isolated repair-loop worktrees.
+
+When admission fails because the git diff is dirty, run route before presenting
+choices. Surface human choices only when route returns non-empty
+`humanOptions`; examples are harness repair, completed task, install, upgrade,
+review, revise, cancel, or manual baseline decisions.
+
+For unowned user changes, NAOME does not offer a generic commit-or-clear action.
+Route may create an isolated task worktree for a new task while leaving those
+edits untouched. If the prompt asks to commit or clear unowned changes, NAOME
+blocks deprecated generic options instead of mutating the repository. If the
+user explicitly asks to commit their current changes, route may run the
+configured user-diff quality gate. The gate uses the committed verification
+profile, requires quality coverage for every changed path, reruns checks until
+the diff stabilizes, rejects new or missing changed paths, and rechecks the
+final diff before committing only the evaluated path set. If any required check
+fails, no commit is created. Agents must not translate any blocker into plain
+`git add`, raw `git commit`, IDE commit, or hook bypass commands.
+
+When the dirty diff is a deterministic harness refresh plus unrelated user
+edits, repair intent may baseline only the harness refresh. It must not stage,
+clear, or commit unrelated user paths.
+
+Do not commit NAOME install or upgrade changes unless route returns an automatic
+setup baseline policy or the user explicitly chooses a manual setup baseline.
+Commit only NAOME install or upgrade files.
 
 If `status` is `planning`, `implementing`, `revising`, `verifying`,
 `needs_human_review`, or `blocked`, do not start the new task. Explain the
 active blocker, list the exact human options from `blocker.humanOptions`, and
 ask the user to resolve it first.
 
-Allowed meta-actions while blocked:
-
-- show the blocker
-- approve a listed human option
-- request a smaller diff
-- cancel or mark the active task blocked
+Allowed meta-actions while blocked: show the blocker, approve a listed human
+option, request a smaller diff, or cancel/mark the active task blocked.
 
 ## Revisions
 
@@ -106,11 +114,8 @@ NAOME control state, not task work.
 
 ## Progress Check
 
-While a task is `planning`, `implementing`, `revising`, or `verifying`, use:
-
-```sh
-node .naome/bin/check-task-state.js --progress
-```
+While a task is `planning`, `implementing`, `revising`, or `verifying`, use
+`node .naome/bin/check-task-state.js --progress`.
 
 This validates the active task shape, admission record, check IDs, existing
 proof entries, and current diff scope without requiring completion proof. Use
@@ -156,17 +161,11 @@ between `activeTask.admission.gitHead` and current `HEAD`. The checker uses
 that historical task diff after the working tree is clean, so completed task
 state can stay committed without requiring the deleted file to exist.
 
-If the check passes but prints a next-task admission notice, include that notice
-in the handoff. Ask the user to choose exactly one:
-
-- `commit_task_baseline`: run `naome commit` or
-  `node .naome/bin/naome.js commit` to commit the completed task and NAOME
-  task-state diff.
-- `review_task_diff`: summarize the completed task diff and wait.
-- `request_task_changes`: keep the task open for follow-up changes.
-- `cancel_task_changes`: leave the diff unresolved and do not start new work.
-
-Do not start another feature task until one option is resolved.
+If the check passes but prints a next-task admission notice, keep the final
+handoff short: say the task is complete and verified, and use NAOME route/status
+`userMessage` for the next step. Do not list internal baseline options unless
+route returns non-empty `humanOptions`, automatic baselining fails, or the user
+explicitly asks to review, revise, cancel, or commit manually.
 
 ## Git Reconciliation
 
@@ -182,6 +181,11 @@ commits or pushes outside NAOME, do not assume the harness is broken:
 The installed git hooks run commit and push gates, but hooks are guardrails, not
 the source of truth. Checks must still recover from manual Git operations.
 
+Completed task history is also written to the local-only
+`.naome/task-journal.jsonl` when NAOME commit/route baselines a task or when
+route reconciles a clean externally committed completed task. The journal is
+machine-owned working memory and should stay out of project commits.
+
 ## Prompt Records
 
 `request` is a compact working summary. `userPrompt.text` is the exact user

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

@@ -33,6 +33,8 @@ for the current step.
 
 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 search for generic root `ARCHITECTURE.md` or `docs/index.md` files unless
+this repository's NAOME docs explicitly reference them.
 
 ## Proof Rule
 
@@ -42,9 +44,14 @@ report the exact command and result.
 
 ## Task Control Rule
 
-Use `naome status` or `node .naome/bin/naome.js status` to get the
-machine-generated next decision. Use `execution.md` and `.naome/task-state.json`
-before starting new work and before claiming completion. First run
+Use `naome route --prompt-file <path> --execute --json` or
+`node .naome/bin/naome.js route --prompt-file <path> --execute --json` for
+natural-language work requests. Route returns the deterministic next decision,
+human-facing `userMessage`, `humanOptions`, and `requiredContext`. Use
+`naome explain --prompt-file <path> --json` only for debugging why a policy won.
+Use `naome status` or `node .naome/bin/naome.js status` to report state without
+routing a request. Use `execution.md` and `.naome/task-state.json` before
+starting new work and before claiming completion. First run
 `node .naome/bin/check-harness-health.js`, then run
 `node .naome/bin/check-task-state.js --admission` before accepting feature work.
 If either check fails, do not accept a new feature task until the user resolves