@lamentis/naome 1.2.1 → 1.3.1

package/Cargo.lock

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

package/README.md

@@ -1,70 +1,140 @@
-# 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.
+- Can install optional Codex hooks for earlier agent feedback without making
+  hooks a human workflow requirement.
+
+## 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 semantic check --changed
+naome task render-state --write --json
 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. It also migrates any active legacy
+task-state into the task ledger automatically. 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.
+- `docs/naome/codex-hooks.md` explains the optional Codex hook acceleration
+  layer.
+
+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.
+- `.codex/hooks.json` only when optional Codex hooks were explicitly enabled.
+
+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
+node .naome/bin/naome.js semantic 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]|context select --changed [--json]|context select --prompt-file <path> [--json]|context select --prompt <text> [--json]|doctor [--json]|install|sync [--check-update]|update [--json] [--execute]|task render-state [--write] [--json]|task migrate-ledger [--write] [--json]|quality init [--baseline|--deep-baseline] [--json]|quality reconcile [--write] [--json]|quality check --changed [--include-scanned-paths] [--json]|quality check --path <path> [--path <path>...] [--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 check --path <path> [--path <path>...] [--json]|semantic route --finding <id> [--json]|semantic loop [--json]|repo model [--write] [--json]|repo check [--json]|repo explain --path <path> [--json]|structure report [--json]|structure explain --path <path> [--json]|cleanup plan [--json]|cleanup route --path <path> [--json]|refresh-integrity [--json]|workflow agent-plan|context-delta|proof-plan|capabilities|edit-watchdog|decision-gate|digest [--json]|workflow search-profile|check-search|phases|processes|mutations [--json]|commit -m \"type(scope): message\"".split("|");
 
 if (isHelpRequest(args)) {
   printHelp();
@@ -31,6 +31,7 @@ if (command === "install" || command === "sync") {
   const qualityConfigExisted = existsSync(repositoryQualityConfigPath(process.cwd()));
   const result = runNativePackageCommand(args.filter((arg) => arg !== "--check-update"));
   if (result.status === 0) {
+    ensureTaskLedgerMigrated(result.nativeBinary);
     ensureRepositoryQualityInitialized(result.nativeBinary, qualityConfigExisted);
   }
   process.exit(result.status === null ? 1 : result.status);
@@ -281,8 +282,54 @@ function ensureRepositoryQualityInitialized(nativeBinary, qualityConfigExisted)
     }
   }
 
-  const result = spawnSync(nativeBinary, ["quality", "init", "--json"], {
-    cwd: root,
+  const output = runNativeJsonCommand(
+    nativeBinary,
+    ["quality", "init", "--json"],
+    "repository quality initialization failed"
+  );
+  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 ensureTaskLedgerMigrated(nativeBinary) {
+  const root = process.cwd();
+  if (!existsSync(join(root, ".naome"))) {
+    return;
+  }
+
+  const output = runNativeJsonCommand(
+    nativeBinary,
+    ["task", "migrate-ledger", "--write", "--json"],
+    "task ledger migration failed"
+  );
+  if (!output) {
+    return;
+  }
+
+  try {
+    const migration = JSON.parse(output);
+    if (migration.updated && migration.migration?.source === "task-state") {
+      console.log("task ledger migrated from task-state");
+    }
+  } catch (_error) {
+    console.log(output);
+  }
+}
+
+function runNativeJsonCommand(nativeBinary, commandArgs, failureLabel) {
+  const result = spawnSync(nativeBinary, commandArgs, {
+    cwd: process.cwd(),
     encoding: "utf8",
     env: {
       ...process.env,
@@ -291,15 +338,21 @@ function ensureRepositoryQualityInitialized(nativeBinary, qualityConfigExisted)
   });
 
   if (result.status !== 0) {
-    console.error("NAOME: repository quality initialization failed.");
-    if (result.stdout.trim()) {
-      console.error(result.stdout.trim());
-    }
-    if (result.stderr.trim()) {
-      console.error(result.stderr.trim());
+    exitNativeJsonFailure(failureLabel, result);
+  }
+
+  return result.stdout.trim();
+}
+
+function exitNativeJsonFailure(label, result) {
+  console.error(`NAOME: ${label}.`);
+  for (const stream of [result.stdout, result.stderr]) {
+    const text = stream.trim();
+    if (text) {
+      console.error(text);
     }
-    process.exit(result.status === null ? 1 : result.status);
   }
+  process.exit(result.status === null ? 1 : result.status);
 }
 
 function repositoryQualityConfigPath(root) {
@@ -324,8 +377,8 @@ function repositoryQualitySupportFilesExist(root) {
 function resolveNativePackageBinary() {
   const candidates = [
     process.env.NAOME_NATIVE_BIN && resolve(process.cwd(), process.env.NAOME_NATIVE_BIN),
-    join(packageRoot, "native", `${process.platform}-${process.arch}`, nativeBinaryName),
-    join(packageRoot, "target", "release", nativeBinaryName)
+    join(packageRoot, "target", "release", nativeBinaryName),
+    join(packageRoot, "native", `${process.platform}-${process.arch}`, nativeBinaryName)
   ].filter(Boolean);
 
   for (const candidate of candidates) {

package/crates/naome-cli/Cargo.toml

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

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

@@ -0,0 +1,47 @@
+use std::fs;
+use std::path::Path;
+
+use naome_core::{select_context_for_changed_paths, select_context_for_prompt};
+
+use crate::cli_args::option_value;
+
+pub fn run_context_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 context requires select.".into());
+    };
+    match subcommand {
+        "select" => run_context_select(root, args)?,
+        _ => return Err(format!("unknown naome context command: {subcommand}").into()),
+    }
+    Ok(())
+}
+
+fn run_context_select(root: &Path, args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
+    let selection = if args.iter().any(|arg| arg == "--changed") {
+        select_context_for_changed_paths(root)?
+    } else if let Some(prompt) = option_value(args, "--prompt") {
+        select_context_for_prompt(root, prompt)?
+    } else if let Some(prompt_file) = option_value(args, "--prompt-file") {
+        select_context_for_prompt(root, fs::read_to_string(prompt_file)?)?
+    } else {
+        return Err(
+            "naome context select requires --changed, --prompt <text>, or --prompt-file <path>."
+                .into(),
+        );
+    };
+
+    if args.iter().any(|arg| arg == "--json") {
+        println!("{}", serde_json::to_string_pretty(&selection)?);
+    } else {
+        println!(
+            "NAOME context capsule: {} ({} file(s), ~{} token(s))",
+            selection.capsule.id,
+            selection.budget_ledger.selected_files,
+            selection.budget_ledger.estimated_tokens
+        );
+        for item in &selection.required_context {
+            println!("- {}", item.path);
+        }
+    }
+    Ok(())
+}

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

@@ -1,13 +1,18 @@
 use std::path::Path;
 
 use crate::check_commands::{run_harness_health, run_task_state, run_verification_contract};
+use crate::context_commands::run_context_command;
 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::repository_model_commands::run_repo_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::task_commands::run_task_command;
+use crate::workflow_commands::{run_doctor, run_refresh_integrity, run_workflow_command};
 
 pub fn dispatch_command(
     root: &Path,
@@ -18,8 +23,13 @@ pub fn dispatch_command(
         "install" | "sync" => run_install_bridge(command, args)?,
         "install-plan" => print_install_plan(args)?,
         "seed-verification" => seed_verification(root)?,
+        "task" => run_task_command(root, args)?,
         "refresh-integrity" => run_refresh_integrity(root, args)?,
+        "context" => run_context_command(root, args)?,
+        "doctor" => run_doctor(root, args)?,
         "quality" => run_quality_command(root, args)?,
+        "semantic" => run_semantic_command(root, args)?,
+        "repo" => run_repo_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

@@ -1,10 +1,15 @@
 mod check_commands;
 mod cli_args;
+mod context_commands;
 mod dispatcher;
 mod install_bridge;
 mod prompt_commands;
 mod quality_commands;
+mod quality_output;
+mod quality_reconcile_command;
+mod repository_model_commands;
 mod simple_commands;
+mod task_commands;
 mod workflow_commands;
 
 use std::path::{Path, PathBuf};
@@ -22,19 +27,44 @@ const HELP: &str = r#"Usage:
   naome route --prompt <text> [--execute] [--json]
   naome explain --prompt-file <path> [--json]
   naome explain --prompt <text> [--json]
+  naome context select --changed [--json]
+  naome context select --prompt-file <path> [--json]
+  naome context select --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 task render-state [--write] [--json]
+  naome task migrate-ledger [--write] [--json]
   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 reconcile [--write] [--json]
+  naome quality check --changed [--include-scanned-paths] [--json]
+  naome quality check --path <path> [--path <path>...] [--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 check --path <path> [--path <path>...] [--json]
+  naome semantic route --finding <id> [--json]
+  naome semantic loop [--json]
+  naome repo model [--write] [--json]
+  naome repo check [--json]
+  naome repo explain --path <path> [--json]
   naome structure report [--json]
   naome structure explain --path <path> [--json]
   naome cleanup plan [--json]
   naome cleanup route --path <path> [--json]
   naome workflow search-profile [--json]
+  naome workflow agent-plan [--json]
+  naome workflow context-delta [--read-path <path>...] [--json]
+  naome workflow proof-plan [--json]
+  naome workflow capabilities [--json]
+  naome workflow edit-watchdog --path <path> [--path <path>...] [--json]
+  naome workflow decision-gate [--json]
+  naome workflow digest --command <cmd> --exit-code <code> [--output <text>|--output-file <path>] [--json]
   naome workflow check-search --command <cmd> [--json]
   naome workflow phases [--json]
   naome workflow processes [--json]
@@ -43,6 +73,33 @@ 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",
+    "task",
+    "refresh-integrity",
+    "context",
+    "workflow",
+    "quality",
+    "semantic",
+    "repo",
+    "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 +119,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());
     }
@@ -128,7 +166,13 @@ fn is_help_request(args: &[String]) -> bool {
 }
 
 fn find_harness_root(start: &Path) -> Option<PathBuf> {
-    find_root_with_marker(start, &[".naome", "task-state.json"])
+    find_root_with_any_marker(
+        start,
+        &[
+            &[".naome", "task-state.json"],
+            &[".naome", "tasks", "active.json"],
+        ],
+    )
 }
 
 fn find_manifest_root(start: &Path) -> Option<PathBuf> {
@@ -136,13 +180,18 @@ fn find_manifest_root(start: &Path) -> Option<PathBuf> {
 }
 
 fn find_root_with_marker(start: &Path, marker: &[&str]) -> Option<PathBuf> {
+    find_root_with_any_marker(start, &[marker])
+}
+
+fn find_root_with_any_marker(start: &Path, markers: &[&[&str]]) -> Option<PathBuf> {
     let mut current = start.to_path_buf();
     loop {
-        if marker
-            .iter()
-            .fold(current.clone(), |path, part| path.join(part))
-            .is_file()
-        {
+        if markers.iter().any(|marker| {
+            marker
+                .iter()
+                .fold(current.clone(), |path, part| path.join(part))
+                .is_file()
+        }) {
             return Some(current);
         }