@lamentis/naome 1.2.1 → 1.3.0

package/crates/naome-core/tests/workflow_doctor.rs

@@ -0,0 +1,24 @@
+mod workflow_support;
+
+use naome_core::doctor_report;
+use workflow_support::WorkflowFixture;
+
+#[test]
+fn doctor_report_explains_active_task_and_policy_files() {
+    let repo = WorkflowFixture::new("doctor-active-task");
+    repo.init_git();
+    repo.write(".naome/repository-quality.json", "{}\n");
+    repo.write(".naome/repository-structure.json", "{}\n");
+    repo.write_task_state("implementing", &["README.md"], &["diff-check"]);
+
+    let report = doctor_report(repo.path()).unwrap();
+
+    assert_eq!(report.schema, "naome.doctor.v1");
+    assert!(!report.ok);
+    assert_eq!(report.task_state.status, "blocked");
+    assert_eq!(report.repository_quality.config_present, true);
+    assert_eq!(report.repository_structure.config_present, true);
+    assert!(report
+        .next_action
+        .contains("Finish or resolve the active task"));
+}

package/crates/naome-core/tests/workflow_policy.rs

@@ -115,6 +115,7 @@ fn mutation_classifier_recognizes_core_classes() {
             ".naome/archive/repair/AGENTS.md".to_string(),
             "coverage/report.json".to_string(),
             "packages/naome/native/darwin-arm64/naome".to_string(),
+            "packages/naome/templates/naome-root/AGENTS.md".to_string(),
             "notes/manual.md".to_string(),
         ],
     )
@@ -133,7 +134,11 @@ fn mutation_classifier_recognizes_core_classes() {
     assert_eq!(by_path["coverage/report.json"], "test artifact");
     assert_eq!(
         by_path["packages/naome/native/darwin-arm64/naome"],
-        "release artifact"
+        "user edit"
+    );
+    assert_eq!(
+        by_path["packages/naome/templates/naome-root/AGENTS.md"],
+        "user edit"
     );
     assert_eq!(by_path["notes/manual.md"], "user edit");
 }

package/installer/git-boundary.js

@@ -149,6 +149,7 @@ function legacyLocalOnlyGitIgnoreEntries(ctx) {
     "# NAOME local machine-owned harness files.",
     ".naome/archive/",
     ".naome/bin/naome-rust*",
+    ".naome/cache/",
     ...ctx.localOnlyMachineOwnedPaths,
     ...ctx.localOnlyGitIgnoreEntries,
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamentis/naome",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Native-first CLI for the NAOME agent harness.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/naome-root/.naome/bin/check-harness-health.js

@@ -11,11 +11,11 @@ const nativeBinaryName = process.platform === "win32" ? "naome.exe" : "naome";
 const expectedMachineOwnedIntegrity = Object.freeze({
   ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
   ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-  ".naome/bin/naome.js": "sha256:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
+  ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
   ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
   ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
   "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-  "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+  "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
   "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
   "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
   "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",

package/templates/naome-root/.naome/bin/check-task-state.js

@@ -11,11 +11,11 @@ const nativeBinaryName = process.platform === "win32" ? "naome.exe" : "naome";
 const expectedMachineOwnedIntegrity = Object.freeze({
   ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
   ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-  ".naome/bin/naome.js": "sha256:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
+  ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
   ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
   ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
   "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-  "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+  "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
   "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
   "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
   "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",

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

@@ -27,7 +27,7 @@ function main(argv) {
     return;
   }
 
-  if (["status", "next", "intent", "route", "explain", "quality", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
+  if (["status", "next", "intent", "route", "explain", "doctor", "quality", "semantic", "structure", "cleanup", "refresh-integrity", "workflow"].includes(command)) {
     runNativeDecisionCommand(command, args);
     return;
   }
@@ -358,9 +358,16 @@ function printHelp() {
     "naome route --prompt <text> [--execute] [--json]",
     "naome explain --prompt-file <path> [--json]",
     "naome explain --prompt <text> [--json]",
-    "naome quality init [--json]",
-    "naome quality check --changed [--json]",
-    "naome quality report [--json]",
+    "naome doctor [--json]",
+    "naome quality init [--baseline|--deep-baseline] [--json]",
+    "naome quality check --changed [--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 route --finding <id> [--json]",
+    "naome semantic loop [--json]",
     "naome structure report [--json]",
     "naome structure explain --path <path> [--json]",
     "naome cleanup plan [--json]",

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

@@ -4,11 +4,11 @@
   "integrity": {
     ".naome/bin/check-harness-health.js": "sha256:dc4de52b79c69600b9ba47b924e2c2b8de61a2cbfab6d1ccc0f1924d963db657",
     ".naome/bin/check-task-state.js": "sha256:43c02868072d0d13499aefba2e9a5ec9517d59539fd19ff0f11e3e4623a51b44",
-    ".naome/bin/naome.js": "sha256:87eabd690bf55f0b0195446db46fa7c19bfa17395d31c2f34a9ef9339d2229e2",
+    ".naome/bin/naome.js": "sha256:3d2edd9cf7b04ffb8845db2c55ce1b9c243bd3aba112f53af4af3c11fae5b8e1",
     ".naome/package.json": "sha256:8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
     ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
     "AGENTS.md": "sha256:9192ea81f90bb19f8043513c49b5da9e9598ee694da8356f345e7ccbca0e28df",
-    "docs/naome/agent-workflow.md": "sha256:802eb34cf268fc9c5e7aefc28192efef4bf60302d30b3f78e5a61b876ce8a098",
+    "docs/naome/agent-workflow.md": "sha256:97788255e26282ca1b7fcaaf86c9408c9040246727e3de96b4126fcb68c10b38",
     "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
     "docs/naome/first-run.md": "sha256:a1dd0bd17ec9d71955a473cd2c4a615538e89a7d81e8f4e1015a50ab9efe3558",
     "docs/naome/index.md": "sha256:a674102cc801702dc77102afb59be0f5ab189dc638caf0bef358b9d6087d0742",

package/templates/naome-root/.naomeignore

@@ -2,3 +2,4 @@
 # Agents must not read, summarize, scan, import, or use these paths as context.
 
 .naome/archive/
+.naome/cache/

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

@@ -20,37 +20,39 @@ Use this workflow after first-run intake is complete.
    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
+5. Run `node .naome/bin/naome.js doctor --json` when state is unclear or a
+   gate blocks unexpectedly; use its `nextAction` as the first diagnostic.
+6. Run `node .naome/bin/check-harness-health.js`.
+7. If harness health fails, do not start new feature work. Ask the user to
    choose `repair_harness`, `review_harness_diff`, or
    `cancel_repair_baseline`.
-7. Run `node .naome/bin/check-task-state.js --admission`.
-8. If task admission fails for a natural-language work request, use
+8. Run `node .naome/bin/check-task-state.js --admission`.
+9. 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
+10. 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
+11. Record the passed admission check in `.naome/task-state.json` when starting
    the task.
-11. Restate the task in concrete terms.
-12. Read `.naomeignore`.
-13. Exclude every path matched by `.naomeignore` from context gathering.
-14. For broad searches, use `node .naome/bin/naome.js workflow search-profile`
+12. Restate the task in concrete terms.
+13. Read `.naomeignore`.
+14. Exclude every path matched by `.naomeignore` from context gathering.
+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.
-15. Read only the `requiredContext` returned by route/status plus the smallest
+16. Read only the `requiredContext` returned by route/status plus the smallest
     task-relevant NAOME docs.
-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.
+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.
 
 ## Instruction Boundaries
 

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

@@ -7,15 +7,26 @@ NAOME keeps legacy debt visible without blocking unrelated feature work.
 - `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 quality report` scans the repository with normal budgets and reports
+  debt without failing feature work. Full repository duplicate,
+  near-duplicate, and semantic grouping checks are deep-only.
+- `naome quality report --deep` runs the intentionally expensive full
+  repository checks.
 - `naome cleanup plan` groups report findings into deterministic cleanup tasks.
 - `naome cleanup route --path <path>` returns agent instructions for one file.
+  Structure findings include rule-specific guidance such as moving misplaced
+  tests, pairing source with nearby tests, splitting dumping-ground folders, or
+  resolving case collisions.
 
 ## Configuration
 
 Repository-specific rules live in `.naome/repository-quality.json`.
 
+`quality init` writes only policy files and an empty baseline placeholder. It
+does not deep-scan the repository. To record existing debt intentionally, run
+`quality init --baseline`; use `quality init --deep-baseline` only when broad
+duplicate and semantic grouping checks are expected.
+
 `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
@@ -26,6 +37,20 @@ 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 scanner has three modes:
+
+- `ChangedFast`: changed files are read fully; unchanged files may contribute
+  cached facts for duplicate comparison.
+- `Report`: repository-wide, budgeted debt visibility. If budgets are hit, JSON
+  sets `summary.truncated` and includes stable `reasonCodes`.
+- `DeepReport`: explicit expensive scan for full duplicate, near-duplicate, and
+  semantic grouping work.
+
+Per-file analysis facts are cached under `.naome/cache/quality/`. Cache entries
+are local-only, keyed by NAOME version, config hash, adapter version, path, and
+content hash. Cache corruption or misses cause a rescan, not a gate failure.
+Use `quality cache status --json` and `quality cache clear` for maintenance.
+
 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
@@ -39,8 +64,42 @@ path roles, module/layer policy, adapters, and cleanup routing.
 Agents may propose stricter repo-specific rules after inspecting the language
 and stack.
 
+## Planned Semantic Cleanup
+
+Some maintainability debt is semantic rather than purely syntactic. Examples
+include inline legacy compatibility fixtures, copied config objects, stale test
+builders, hand-written schema snapshots, and helper data that should move into a
+shared factory after enough call sites accumulate.
+
+NAOME should detect these with a generic semantic-cleanup layer instead of
+hard-coding product paths or deleting compatibility fixtures opportunistically.
+The planned model is:
+
+- detect repeated object shapes, schema literals, fixture builders, and config
+  snapshots across changed and report-mode files;
+- classify each finding as `legacy fixture`, `duplicated fixture`,
+  `schema snapshot`, `generated metadata`, or `inline builder`;
+- keep existing report-mode debt visible without blocking unrelated work;
+- block only changed/new semantic debt unless local policy marks it report-only;
+- route cleanup to extract a shared fixture, builder, schema writer, or generated
+  metadata refresh command;
+- preserve behavior by requiring tests before removing or consolidating legacy
+  compatibility fixtures.
+
+The first implementation exposes this as a scout, not an auto-fixer:
+
+- `naome semantic report --json` runs a budgeted semantic report.
+- `naome semantic report --deep --json` runs repo-wide semantic grouping.
+- `naome semantic check --changed --json` checks only changed semantic debt for
+  gate use.
+- `naome semantic route --finding <id> --json` gives an agent the complete
+  affected path list, cleanup intent, and required checks for one finding group.
+- `naome semantic loop --json` selects the next deterministic cleanup action:
+  changed-code findings first, then report-only legacy debt.
+
 ## 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.
+`naome quality init --baseline` or `naome quality init --deep-baseline`.
+Baseline debt remains visible in reports, but only changed files are blocking
+during feature work.