@lamentis/naome 1.1.2 → 1.2.1

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

@@ -11,6 +11,11 @@ Use this workflow after first-run intake is complete.
    `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.
+   When preparing the route prompt file, prepend a fenced `naome-intent-v2`
+   JSON envelope that states `workflowAction`, `taskIntent`, and `risk` using
+   canonical NAOME schema constants such as `commit_request`,
+   `task_revision`, and `credential_context`. Keep the original user text below
+   it. Do not derive workflow actions from natural-language keywords.
 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
@@ -38,11 +43,14 @@ Use this workflow after first-run intake is complete.
 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
+14. For broad searches, use `node .naome/bin/naome.js workflow search-profile`
+    or equivalent excludes for `.git`, `.naome/archive`, dependencies, build
+    outputs, caches, and `.naomeignore` paths.
+15. Read only the `requiredContext` returned by route/status plus the smallest
     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.
+16. Inspect the existing code or docs before proposing changes.
+17. Read `testing.md` and `.naome/verification.json`.
+18. Identify the required proof before claiming success.
 
 ## Instruction Boundaries
 
@@ -66,25 +74,30 @@ Use this workflow after first-run intake is complete.
 - Update NAOME docs only when the change reveals durable project knowledge.
 - 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.
 
 ## Before Completion
 
 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`, including every changed in-scope
-   path reported by git in proof evidence.
+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. 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, do not repeat
+6. 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
    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
+10. 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. Only ask the user for options when intent blocks, the user explicitly asks
+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.
 
 ## Commit And Push

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

@@ -13,10 +13,9 @@ You may start new feature work only when harness health and admission both pass.
 If health fails, ask the user to choose `repair_harness`,
 `review_harness_diff`, or `cancel_repair_baseline`.
 
-Harness health is a deterministic lifecycle gate, not an agent judgment call.
-When machine-owned harness files are unhealthy, normal task admission,
-progress, completion, commit, and push gates are blocked. Only status, health,
-review, and repair-baseline flows may continue until health is restored.
+Harness health is deterministic: unhealthy machine-owned files block normal
+admission, progress, completion, commit, and push. Only status, health, review,
+and repair-baseline flows may continue until health is restored.
 
 Also read `.naome/upgrade-state.json`. If upgrade status is
 `needs_agent_upgrade`, do not start feature work. Finish `upgrade.md` first.
@@ -100,7 +99,7 @@ When starting work, update `.naome/task-state.json`:
 - set `allowedPaths` to the narrowest expected path list
 - set `declaredChangeTypes` from `.naome/verification.json`
 - set `requiredCheckIds` from the matching change types
-- set `proofResults` to an empty array
+- set `proofResults` to an empty array while work is in progress
 - set `humanReview.required` when matching rules require review
 
 Use exact changed paths, not guessed shortcuts. If the user asks for `README.md`
@@ -118,8 +117,10 @@ 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
-the normal task-state check only when moving the task to `complete`.
+proof entries, and current diff scope without requiring completion proof. Both
+legacy `proofResults` and compact `proofBatches` are expanded into the same
+internal proof model before validation. Use the normal task-state check only
+when moving the task to `complete`.
 
 ## Human Review
 
@@ -141,7 +142,8 @@ fix the task state before asking the human to choose an option.
 
 Before claiming completion:
 
-1. Record every required proof in `activeTask.proofResults`.
+1. Record every required proof in `proofResults`, or compact `proofPathSets`
+   plus `proofBatches` for repeated evidence.
 2. Ensure proof evidence includes every changed in-scope path.
 3. Ensure `.naome/task-state.json` is not listed in `allowedPaths` or evidence.
 4. Set `status` to `complete`.
@@ -151,6 +153,11 @@ Before claiming completion:
 
 Completion is valid only when the task-state check passes.
 
+Compact proof batches are lossless: `proofPathSets` names shared evidence,
+`proofBatches[].checkedAt` shares a timestamp, and omitted proof-level
+`command`/`cwd` must exactly match `.naome/verification.json`; record deviations
+explicitly on the proof or batch.
+
 Do not reset `.naome/task-state.json` to idle just to hide the completed task.
 The completed task state is part of the task baseline and should be committed
 with the task diff. The next admitted task may overwrite it after the working
@@ -162,10 +169,9 @@ 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, 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.
+handoff short and use NAOME route/status `userMessage` for the next step. List
+internal baseline options only when route returns `humanOptions`, automatic
+baselining fails, or the user asks to review, revise, cancel, or commit manually.
 
 ## Git Reconciliation
 
@@ -181,16 +187,14 @@ 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.
+Completed task history is also written to local-only `.naome/task-journal.jsonl`
+when NAOME commit/route baselines a task or reconciles a clean externally
+committed completed task. Keep the journal out of project commits.
 
 ## Prompt Records
 
-`request` is a compact working summary. `userPrompt.text` is the exact user
-input that started the task or revision, so task intent survives context
-compaction and agent handoff. Store only user-provided task input. Do not store
-system prompts, developer prompts, outer-agent instructions, or unrelated chat
-history. If the user prompt contains secrets, pause for human review before
+`request` is a compact working summary. `userPrompt.text` is the exact task or
+revision prompt, so intent survives context compaction and handoff. Store only
+user-provided task input, not system/developer prompts, outer-agent instructions,
+or unrelated chat history. If it contains secrets, pause for human review before
 committing task state.

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

@@ -17,9 +17,11 @@ for the current step.
 10. `architecture.md`
 11. `testing.md`
 12. `.naome/verification.json`
-13. `security.md`
-14. `agent-workflow.md`
-15. `decisions.md`, when changing durable project policy
+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
 
 ## Source Types
 

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

@@ -0,0 +1,46 @@
+# Repository Quality
+
+NAOME keeps legacy debt visible without blocking unrelated feature work.
+
+## Gates
+
+- `naome quality check --changed` blocks only on files changed in the current
+  diff. If a legacy file is touched, that file must satisfy the configured
+  quality rules before commit.
+- `naome quality report` scans the repository and reports debt without failing
+  normal feature work.
+- `naome cleanup plan` groups report findings into deterministic cleanup tasks.
+- `naome cleanup route --path <path>` returns agent instructions for one file.
+
+## Configuration
+
+Repository-specific rules live in `.naome/repository-quality.json`.
+
+`quality init` selects deterministic built-in adapters from repository files.
+Adapters are plug-and-play profiles such as `rust` or
+`javascript-typescript`. They add stack-specific ignored/generated paths and
+path rules at runtime without hard-coding a specific product repository into
+the generic template.
+
+Local `pathRules` are project overrides, not product defaults. They may document
+repo-specific debt or special file roles, but loosening a rule to pass a feature
+diff requires human review.
+
+The default scanner is language-agnostic and uses text plus symbol heuristics:
+file length, diff growth, function or component length, top-level symbol count,
+duplicate regions, and near-duplicate functions. Duplicate regions are grouped
+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.
+
+## Baseline
+
+Existing debt is recorded in `.naome/repository-quality-baseline.json` by
+`naome quality init`. Baseline debt remains visible in reports, but only changed
+files are blocking during feature work.

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

@@ -16,6 +16,14 @@ Status: Uninitialized
 | diff-check | `git diff --check` | `.` | fast | null |
 | naome-harness-health | `node .naome/bin/check-harness-health.js` | `.` | fast | null |
 | naome-task-state | `node .naome/bin/check-task-state.js` | `.` | fast | null |
+| repository-quality-check | `node .naome/bin/naome.js quality check --changed` | `.` | fast | null |
+
+## Verification Phases
+
+Run checks in `.naome/verification.json` phase order:
+`shape-health`, `quality`, `focused-tests`, `broad-tests`, `package-release`,
+then `diff-check`. Do not recommend later expensive phases while an earlier
+phase is failing or missing.
 
 ## Change Type Rules
 
@@ -47,5 +55,10 @@ Status: Uninitialized
 - Keep instruction files under 200 lines. `.naome/verification.json` is machine
   state instead; keep it schema-valid and bounded to 20 checks, 12 change types,
   and 10 release gates.
+- 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, 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.