@lamentis/naome 1.2.1 → 1.3.0

package/Cargo.lock

@@ -76,7 +76,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "naome-cli"
-version = "1.2.1"
+version = "1.3.0"
 dependencies = [
  "naome-core",
  "serde_json",
@@ -84,7 +84,7 @@ dependencies = [
 
 [[package]]
 name = "naome-core"
-version = "1.2.1"
+version = "1.3.0"
 dependencies = [
  "serde",
  "serde_json",

package/README.md

@@ -1,70 +1,131 @@
-# NAOME
-
-[![npm version](https://img.shields.io/npm/v/@lamentis/naome.svg)](https://www.npmjs.com/package/@lamentis/naome)
-[![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-
-NAOME is a deterministic repository harness for AI coding agents. It teaches an
-agent how to enter a repository, routes ambiguous user requests through explicit
-policy, gates work by task scope, and requires proof before completed changes
-are baselined.
-
-## What NAOME Provides
-
-- Repository intake with `.naomeignore`, workflow docs, and health checks.
-- Task admission and progress gates that prevent unowned diffs and scope drift.
-- Rust-backed `status`, `next`, `route`, `commit`, quality, and workflow
-  commands.
-- Intent routing that separates repository state from structured task intent.
-- Repository-quality checks for changed files, with old debt visible through
-  cleanup flows instead of blocking every legacy codebase.
-- Verification phases for health, quality, focused tests, broad tests, package
-  gates, and final diff checks.
-- Compact task proof data so repeated evidence and shared check metadata do not
-  bloat `.naome/task-state.json`.
-- Local Git hooks and commit gates that keep manual commits aligned with the
-  same harness policy.
-
-## Install
-
-```sh
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lamentis/naome"><img src="https://img.shields.io/npm/v/@lamentis/naome.svg" alt="npm version"></a>
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="Apache-2.0 license"></a>
+</p>
+
+<h1 align="center">NAOME</h1>
+
+<p align="center">
+  A deterministic repository harness for AI coding agents.
+</p>
+
+```shell
 npm install -g @lamentis/naome
 ```
 
-## Set Up A Repository
+NAOME gives coding agents a repository-local operating protocol: what to read,
+what to ignore, how to admit a task, which files are in scope, which checks are
+required, and when work is safe to commit.
+
+## Quickstart
 
-From the repository root:
+Install the CLI, then sync NAOME into a repository:
 
-```sh
+```shell
+npm install -g @lamentis/naome
+cd /path/to/repo
 naome sync
 ```
 
-If the CLI reports that an update is available, refresh the global CLI and then
-sync the harness files:
+For an initialized repository, start with:
 
-```sh
-naome update
-naome sync
+```shell
+naome status
+naome next
+naome doctor
+```
+
+For agent-driven work, route the user's request through the harness:
+
+```shell
+naome route --prompt-file /path/to/prompt.txt --execute --json
 ```
 
-Fresh repositories print a first-run prompt for your coding agent. Existing
-initialized repositories keep normal sync output compact and do not reprint the
-first-run protocol unless setup is still incomplete.
+## Why NAOME?
+
+- Keeps agents inside explicit task scope.
+- Blocks unowned diffs before new work starts.
+- Separates current task work from repository cleanup debt.
+- Runs changed-code quality gates without forcing legacy repositories to be
+  perfect on day one.
+- Records verification proof before a task can be treated as complete.
+- Keeps sync fast by making baseline and deep quality scans explicit.
+
+## Safety Model
+
+NAOME is repository-local. The files under `.naome/`, `.naomeignore`, and
+`docs/naome/` define the local harness contract for a repository.
 
-## Daily Workflow
+The harness enforces read boundaries, task admission, scope drift checks,
+repository-quality policy, verification phases, and commit gates. Existing debt
+is reportable through cleanup flows, while changed files are held to the active
+policy.
 
-Use NAOME commands from the target repository:
+## CLI Reference
 
-```sh
+Common commands:
+
+```shell
+naome sync
+naome update
 naome status
 naome next
+naome doctor
 naome route --prompt-file /path/to/prompt.txt --execute --json
+naome quality init
+naome quality init --baseline
+naome quality report
+naome quality report --deep
+naome quality check --changed
 naome commit -m "type(scope): summary"
 ```
 
-Agents should read the NAOME docs named by `status` or `route`, run harness
-health before feature work, keep changes inside the active task scope, and
-record verification proof before marking work complete.
+`naome sync` installs or repairs the local harness files. It does not run a
+hidden full-repository quality scan. If quality policy is newly seeded, run
+`naome quality init --baseline` deliberately; use `--deep` or
+`--deep-baseline` only when you want expensive repository-wide checks.
+
+## Repository Docs
+
+After sync, NAOME writes the agent-facing workflow into `docs/naome/`:
+
+- `docs/naome/index.md` is the entry point.
+- `docs/naome/agent-workflow.md` explains the active task workflow.
+- `docs/naome/testing.md` maps change types to required checks.
+- `docs/naome/repository-quality.md` explains quality, structure, and cleanup
+  policy.
+
+Agents should follow the repository's NAOME docs instead of guessing workflow
+rules from generic project files.
+
+## Configuration
+
+The main local policy files are:
+
+- `.naomeignore` for read boundaries.
+- `.naome/verification.json` for check phases and proof requirements.
+- `.naome/repository-quality.json` for file, symbol, duplicate, and semantic
+  quality policy.
+- `.naome/repository-structure.json` for path role, module, and directory
+  structure policy.
+- `.naome/task-state.json` for active task state and proof.
+
+Product defaults stay generic. Repository-specific policy belongs in the local
+`.naome/` config files.
+
+## Development
+
+Useful checks for this repository:
+
+```shell
+npm run build:rust
+npm run test:decision-engine
+npm run test:naome-installer
+npm run pack:dry-run
+node .naome/bin/naome.js quality check --changed --json
+git diff --check
+```
 
 ## License
 
-NAOME is licensed under the [Apache License 2.0](LICENSE).
+NAOME is licensed under the [Apache License 2.0](../../LICENSE).

package/bin/naome.js

@@ -12,7 +12,7 @@ const packageVersion = packageMetadata.version;
 const nativeBinaryName = process.platform === "win32" ? "naome.exe" : "naome";
 const args = process.argv.slice(2);
 const [command] = args;
-const helpCommands = "status [--json]|next [--json]|intent --prompt-file <path> [--json]|intent --prompt <text> [--json]|route --prompt-file <path> [--execute] [--json]|route --prompt <text> [--execute] [--json]|explain --prompt-file <path> [--json]|explain --prompt <text> [--json]|install|sync [--check-update]|update [--json] [--execute]|quality init [--json]|quality check --changed [--json]|quality report [--json]|structure report [--json]|structure explain --path <path> [--json]|cleanup plan [--json]|cleanup route --path <path> [--json]|refresh-integrity [--json]|workflow search-profile|check-search|phases|processes|mutations [--json]|commit -m \"type(scope): message\"".split("|");
+const helpCommands = "status [--json]|next [--json]|intent --prompt-file <path> [--json]|intent --prompt <text> [--json]|route --prompt-file <path> [--execute] [--json]|route --prompt <text> [--execute] [--json]|explain --prompt-file <path> [--json]|explain --prompt <text> [--json]|doctor [--json]|install|sync [--check-update]|update [--json] [--execute]|quality init [--baseline|--deep-baseline] [--json]|quality check --changed [--include-scanned-paths] [--json]|quality report [--deep] [--include-scanned-paths] [--json]|quality cache status [--json]|quality cache clear|semantic report [--deep] [--json]|semantic check --changed [--json]|semantic route --finding <id> [--json]|semantic loop [--json]|structure report [--json]|structure explain --path <path> [--json]|cleanup plan [--json]|cleanup route --path <path> [--json]|refresh-integrity [--json]|workflow search-profile|check-search|phases|processes|mutations [--json]|commit -m \"type(scope): message\"".split("|");
 
 if (isHelpRequest(args)) {
   printHelp();
@@ -300,6 +300,21 @@ function ensureRepositoryQualityInitialized(nativeBinary, qualityConfigExisted)
     }
     process.exit(result.status === null ? 1 : result.status);
   }
+
+  const output = result.stdout.trim();
+  if (output) {
+    try {
+      const init = JSON.parse(output);
+      if (init.configWritten || init.structureConfigWritten) {
+        console.log("repository quality policy initialized");
+      }
+      if (init.baselinePending) {
+        console.log("baseline pending: run naome quality init --baseline");
+      }
+    } catch (_error) {
+      console.log(output);
+    }
+  }
 }
 
 function repositoryQualityConfigPath(root) {

package/crates/naome-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "naome-cli"
-version = "1.2.1"
+version = "1.3.0"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true

package/crates/naome-cli/src/dispatcher.rs

@@ -3,11 +3,13 @@ use std::path::Path;
 use crate::check_commands::{run_harness_health, run_task_state, run_verification_contract};
 use crate::install_bridge::run_install_bridge;
 use crate::prompt_commands::{run_explain, run_intent, run_route};
-use crate::quality_commands::{run_cleanup_command, run_quality_command, run_structure_command};
+use crate::quality_commands::{
+    run_cleanup_command, run_quality_command, run_semantic_command, run_structure_command,
+};
 use crate::simple_commands::{
     print_install_plan, run_commit_paths, run_journal_task, seed_verification,
 };
-use crate::workflow_commands::{run_refresh_integrity, run_workflow_command};
+use crate::workflow_commands::{run_doctor, run_refresh_integrity, run_workflow_command};
 
 pub fn dispatch_command(
     root: &Path,
@@ -19,7 +21,9 @@ pub fn dispatch_command(
         "install-plan" => print_install_plan(args)?,
         "seed-verification" => seed_verification(root)?,
         "refresh-integrity" => run_refresh_integrity(root, args)?,
+        "doctor" => run_doctor(root, args)?,
         "quality" => run_quality_command(root, args)?,
+        "semantic" => run_semantic_command(root, args)?,
         "structure" => run_structure_command(root, args)?,
         "cleanup" => run_cleanup_command(root, args)?,
         "workflow" => run_workflow_command(root, args)?,

package/crates/naome-cli/src/main.rs

@@ -22,14 +22,21 @@ const HELP: &str = r#"Usage:
   naome route --prompt <text> [--execute] [--json]
   naome explain --prompt-file <path> [--json]
   naome explain --prompt <text> [--json]
+  naome doctor [--json]
   naome install [--package-root <path>] [--installer-js <path>]
   naome sync [--package-root <path>] [--installer-js <path>]
   naome install-plan [--harness-version <version>]
   naome seed-verification
   naome refresh-integrity [--root <path>] [--json]
-  naome quality init [--json]
-  naome quality check --changed [--json]
-  naome quality report [--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]
@@ -43,6 +50,30 @@ const HELP: &str = r#"Usage:
   naome check-task-state [--root <path>] [--admission|--progress|--commit-gate|--push-gate] [--allow-missing-archive]
   naome validate-verification [--root <path>]"#;
 
+const PUBLIC_COMMANDS: &[&str] = &[
+    "status",
+    "next",
+    "intent",
+    "route",
+    "explain",
+    "doctor",
+    "journal-task",
+    "commit-paths",
+    "seed-verification",
+    "refresh-integrity",
+    "workflow",
+    "quality",
+    "semantic",
+    "structure",
+    "cleanup",
+    "install-plan",
+    "install",
+    "sync",
+    "check-harness-health",
+    "check-task-state",
+    "validate-verification",
+];
+
 fn main() {
     if let Err(error) = run() {
         eprintln!("NAOME: {error}");
@@ -62,26 +93,7 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
         return Ok(());
     }
 
-    if command != "status"
-        && command != "next"
-        && command != "intent"
-        && command != "route"
-        && command != "explain"
-        && command != "journal-task"
-        && command != "commit-paths"
-        && command != "seed-verification"
-        && command != "refresh-integrity"
-        && command != "workflow"
-        && command != "quality"
-        && command != "structure"
-        && command != "cleanup"
-        && command != "install-plan"
-        && command != "install"
-        && command != "sync"
-        && command != "check-harness-health"
-        && command != "check-task-state"
-        && command != "validate-verification"
-    {
+    if !PUBLIC_COMMANDS.contains(&command) {
         print_help();
         return Err(format!("unknown command: {command}").into());
     }

package/crates/naome-cli/src/quality_commands.rs

@@ -1,30 +1,38 @@
 use std::path::Path;
 
 use naome_core::{
-    check_repository_quality, explain_repository_structure, init_repository_quality,
-    plan_quality_cleanup, route_quality_cleanup, QualityMode,
+    check_repository_quality, check_semantic_legacy, clear_quality_cache,
+    explain_repository_structure, init_repository_quality_with_mode, plan_quality_cleanup,
+    quality_cache_status, route_quality_cleanup, semantic_route_for_finding, QualityInitMode,
+    QualityMode,
 };
 
 use crate::cli_args::option_value;
 
 pub fn run_quality_command(root: &Path, args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
     let Some(subcommand) = args.get(1).map(String::as_str) else {
-        return Err("naome quality requires init, check, or report.".into());
+        return Err("naome quality requires init, check, report, or cache.".into());
     };
     let json = args.iter().any(|arg| arg == "--json");
 
     match subcommand {
         "init" => {
-            let result = init_repository_quality(root)?;
+            let result = init_repository_quality_with_mode(root, quality_init_mode(args)?)?;
             if json {
                 println!("{}", serde_json::to_string_pretty(&result)?);
             } else {
                 println!("NAOME repository quality initialized.");
-                println!("Baseline violations: {}", result.baseline_violations);
+                if result.baseline_pending {
+                    println!("repository quality policy initialized");
+                    println!("baseline pending: run naome quality init --baseline");
+                } else {
+                    println!("Baseline violations: {}", result.baseline_violations);
+                }
             }
         }
         "check" => run_quality_check(root, args, json)?,
-        "report" => run_quality_report(root, json)?,
+        "report" => run_quality_report(root, args, json)?,
+        "cache" => run_quality_cache(root, args, json)?,
         _ => return Err(format!("unknown naome quality command: {subcommand}").into()),
     }
     Ok(())
@@ -61,6 +69,25 @@ pub fn run_structure_command(
     Ok(())
 }
 
+pub fn run_semantic_command(
+    root: &Path,
+    args: &[String],
+) -> Result<(), Box<dyn std::error::Error>> {
+    let Some(subcommand) = args.get(1).map(String::as_str) else {
+        return Err("naome semantic requires report, check, route, or loop.".into());
+    };
+    let json = args.iter().any(|arg| arg == "--json");
+
+    match subcommand {
+        "report" => run_semantic_report(root, args, json)?,
+        "check" => run_semantic_check(root, args, json)?,
+        "route" => run_semantic_route(root, args, json)?,
+        "loop" => run_semantic_loop(root, json)?,
+        _ => return Err(format!("unknown naome semantic command: {subcommand}").into()),
+    }
+    Ok(())
+}
+
 fn run_quality_check(
     root: &Path,
     args: &[String],
@@ -69,9 +96,9 @@ fn run_quality_check(
     if !args.iter().any(|arg| arg == "--changed") {
         return Err("naome quality check requires --changed.".into());
     }
-    let report = check_repository_quality(root, QualityMode::Changed)?;
+    let report = check_repository_quality(root, QualityMode::ChangedFast)?;
     if json {
-        println!("{}", serde_json::to_string_pretty(&report)?);
+        println!("{}", report_json(&report, args)?);
     } else if report.ok {
         println!("NAOME repository quality OK.");
     } else {
@@ -89,10 +116,19 @@ fn run_quality_check(
     Ok(())
 }
 
-fn run_quality_report(root: &Path, json: bool) -> Result<(), Box<dyn std::error::Error>> {
-    let report = check_repository_quality(root, QualityMode::Report)?;
+fn run_quality_report(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let mode = if args.iter().any(|arg| arg == "--deep") {
+        QualityMode::DeepReport
+    } else {
+        QualityMode::Report
+    };
+    let report = check_repository_quality(root, mode)?;
     if json {
-        println!("{}", serde_json::to_string_pretty(&report)?);
+        println!("{}", report_json(&report, args)?);
     } else if report.violations.is_empty() {
         println!("NAOME repository quality report: no debt found.");
     } else {
@@ -108,6 +144,32 @@ fn run_quality_report(root: &Path, json: bool) -> Result<(), Box<dyn std::error:
     Ok(())
 }
 
+fn run_quality_cache(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let Some(action) = args.get(2).map(String::as_str) else {
+        return Err("naome quality cache requires status or clear.".into());
+    };
+    let status = match action {
+        "status" => quality_cache_status(root)?,
+        "clear" => clear_quality_cache(root)?,
+        _ => return Err(format!("unknown naome quality cache command: {action}").into()),
+    };
+    if json {
+        println!("{}", serde_json::to_string_pretty(&status)?);
+    } else if action == "clear" {
+        println!("NAOME quality cache cleared.");
+    } else {
+        println!(
+            "NAOME quality cache: {} entrie(s), {} byte(s).",
+            status.entry_count, status.bytes
+        );
+    }
+    Ok(())
+}
+
 fn run_cleanup_plan(root: &Path, json: bool) -> Result<(), Box<dyn std::error::Error>> {
     let plan = plan_quality_cleanup(root)?;
     if json {
@@ -206,6 +268,135 @@ fn run_structure_explain(
     Ok(())
 }
 
+fn run_semantic_report(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let mode = if args.iter().any(|arg| arg == "--deep") {
+        QualityMode::DeepReport
+    } else {
+        QualityMode::Report
+    };
+    let report = check_semantic_legacy(root, mode)?;
+    if json {
+        println!("{}", serde_json::to_string_pretty(&report)?);
+    } else if report.findings.is_empty() {
+        println!("NAOME semantic legacy report: no cleanup candidates found.");
+    } else {
+        println!(
+            "NAOME semantic legacy report: {} finding(s).",
+            report.findings.len()
+        );
+        for finding in report.findings.iter().take(20) {
+            println!(
+                "- {} {}: {}",
+                finding.kind, finding.occurrences[0].path, finding.summary
+            );
+        }
+    }
+    Ok(())
+}
+
+fn run_semantic_check(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    if !args.iter().any(|arg| arg == "--changed") {
+        return Err("naome semantic check requires --changed.".into());
+    }
+    let report = check_semantic_legacy(root, QualityMode::ChangedFast)?;
+    if json {
+        println!("{}", serde_json::to_string_pretty(&report)?);
+    } else if report.ok {
+        println!("NAOME semantic legacy check OK.");
+    } else {
+        eprintln!(
+            "NAOME semantic legacy check failed with {} finding(s).",
+            report.findings.len()
+        );
+        for finding in report.findings.iter().take(20) {
+            eprintln!(
+                "- {} {}: {}",
+                finding.kind, finding.occurrences[0].path, finding.summary
+            );
+        }
+    }
+    if !report.ok {
+        std::process::exit(1);
+    }
+    Ok(())
+}
+
+fn run_semantic_route(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let Some(finding_id) = option_value(args, "--finding") else {
+        return Err("naome semantic route requires --finding <id>.".into());
+    };
+    let report = check_semantic_legacy(root, QualityMode::DeepReport)?;
+    let Some(finding) = semantic_route_for_finding(&report, &finding_id) else {
+        return Err(format!("semantic finding not found: {finding_id}").into());
+    };
+    if json {
+        println!("{}", serde_json::to_string_pretty(&finding)?);
+    } else {
+        println!("NAOME semantic cleanup route for {}", finding.id);
+        println!("{}", finding.cleanup_route.intent);
+        for instruction in &finding.cleanup_route.agent_instructions {
+            println!("- {instruction}");
+        }
+        let paths = finding
+            .occurrences
+            .iter()
+            .map(|occurrence| occurrence.path.as_str())
+            .collect::<Vec<_>>()
+            .join(", ");
+        println!("Affected paths: {paths}");
+    }
+    Ok(())
+}
+
+fn run_semantic_loop(root: &Path, json: bool) -> Result<(), Box<dyn std::error::Error>> {
+    let changed = check_semantic_legacy(root, QualityMode::ChangedFast)?;
+    let (action, finding) = if let Some(finding) = changed.findings.first().cloned() {
+        ("cleanup_changed_finding", Some(finding))
+    } else {
+        let report = check_semantic_legacy(root, QualityMode::Report)?;
+        if let Some(finding) = report.findings.first().cloned() {
+            ("report_legacy_debt", Some(finding))
+        } else {
+            ("complete", None)
+        }
+    };
+
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string_pretty(&serde_json::json!({
+                "schema": "naome.semantic-loop.v1",
+                "ok": action != "cleanup_changed_finding",
+                "action": action,
+                "finding": finding
+            }))?
+        );
+    } else {
+        match finding {
+            Some(finding) => {
+                println!("NAOME semantic loop action: {action}");
+                println!("{} {}", finding.kind, finding.id);
+                println!("{}", finding.summary);
+                println!("Run: naome semantic route --finding {} --json", finding.id);
+            }
+            None => println!("NAOME semantic loop complete: no semantic cleanup candidates found."),
+        }
+    }
+    Ok(())
+}
+
 fn is_structure_check(check_id: &str) -> bool {
     matches!(
         check_id,
@@ -220,6 +411,34 @@ fn is_structure_check(check_id: &str) -> bool {
     )
 }
 
+fn quality_init_mode(args: &[String]) -> Result<QualityInitMode, Box<dyn std::error::Error>> {
+    let baseline = args.iter().any(|arg| arg == "--baseline");
+    let deep_baseline = args.iter().any(|arg| arg == "--deep-baseline");
+    if baseline && deep_baseline {
+        return Err("naome quality init accepts only one baseline mode.".into());
+    }
+    Ok(if deep_baseline {
+        QualityInitMode::DeepBaseline
+    } else if baseline {
+        QualityInitMode::Baseline
+    } else {
+        QualityInitMode::SeedOnly
+    })
+}
+
+fn report_json(
+    report: &naome_core::QualityReport,
+    args: &[String],
+) -> Result<String, Box<dyn std::error::Error>> {
+    let mut value = serde_json::to_value(report)?;
+    if !args.iter().any(|arg| arg == "--include-scanned-paths") {
+        if let Some(object) = value.as_object_mut() {
+            object.remove("scannedPaths");
+        }
+    }
+    Ok(serde_json::to_string_pretty(&value)?)
+}
+
 fn print_quality_violation(violation: &naome_core::QualityViolation) {
     let location = violation
         .line