@lamentis/naome 1.2.0 → 1.2.1

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]|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]|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("|");
 
 if (isHelpRequest(args)) {
   printHelp();
@@ -265,13 +265,19 @@ function runNativePackageCommand(args) {
 
 function ensureRepositoryQualityInitialized(nativeBinary, qualityConfigExisted) {
   const root = process.cwd();
-  if (qualityConfigExisted || !existsSync(join(root, ".naome"))) {
+  if (!existsSync(join(root, ".naome"))) {
     return;
   }
 
-  for (const path of repositoryQualityPaths(root)) {
-    if (existsSync(path)) {
-      unlinkSync(path);
+  if (qualityConfigExisted && repositoryQualitySupportFilesExist(root)) {
+    return;
+  }
+
+  if (!qualityConfigExisted) {
+    for (const path of repositoryQualityPaths(root)) {
+      if (existsSync(path)) {
+        unlinkSync(path);
+      }
     }
   }
 
@@ -303,10 +309,18 @@ function repositoryQualityConfigPath(root) {
 function repositoryQualityPaths(root) {
   return [
     repositoryQualityConfigPath(root),
+    join(root, ".naome", "repository-structure.json"),
     join(root, ".naome", "repository-quality-baseline.json")
   ];
 }
 
+function repositoryQualitySupportFilesExist(root) {
+  return [
+    join(root, ".naome", "repository-structure.json"),
+    join(root, ".naome", "repository-quality-baseline.json")
+  ].every((path) => existsSync(path));
+}
+
 function resolveNativePackageBinary() {
   const candidates = [
     process.env.NAOME_NATIVE_BIN && resolve(process.cwd(), process.env.NAOME_NATIVE_BIN),

package/crates/naome-cli/Cargo.toml

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

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

@@ -3,7 +3,7 @@ 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};
+use crate::quality_commands::{run_cleanup_command, run_quality_command, run_structure_command};
 use crate::simple_commands::{
     print_install_plan, run_commit_paths, run_journal_task, seed_verification,
 };
@@ -20,6 +20,7 @@ pub fn dispatch_command(
         "seed-verification" => seed_verification(root)?,
         "refresh-integrity" => run_refresh_integrity(root, args)?,
         "quality" => run_quality_command(root, args)?,
+        "structure" => run_structure_command(root, args)?,
         "cleanup" => run_cleanup_command(root, args)?,
         "workflow" => run_workflow_command(root, args)?,
         "check-harness-health" => run_harness_health(root, args)?,

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

@@ -30,6 +30,8 @@ const HELP: &str = r#"Usage:
   naome quality init [--json]
   naome quality check --changed [--json]
   naome quality report [--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]
@@ -71,6 +73,7 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
         && command != "refresh-integrity"
         && command != "workflow"
         && command != "quality"
+        && command != "structure"
         && command != "cleanup"
         && command != "install-plan"
         && command != "install"

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

@@ -1,8 +1,8 @@
 use std::path::Path;
 
 use naome_core::{
-    check_repository_quality, init_repository_quality, plan_quality_cleanup, route_quality_cleanup,
-    QualityMode,
+    check_repository_quality, explain_repository_structure, init_repository_quality,
+    plan_quality_cleanup, route_quality_cleanup, QualityMode,
 };
 
 use crate::cli_args::option_value;
@@ -44,6 +44,23 @@ pub fn run_cleanup_command(root: &Path, args: &[String]) -> Result<(), Box<dyn s
     Ok(())
 }
 
+pub fn run_structure_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 structure requires report or explain.".into());
+    };
+    let json = args.iter().any(|arg| arg == "--json");
+
+    match subcommand {
+        "report" => run_structure_report(root, json)?,
+        "explain" => run_structure_explain(root, args, json)?,
+        _ => return Err(format!("unknown naome structure command: {subcommand}").into()),
+    }
+    Ok(())
+}
+
 fn run_quality_check(
     root: &Path,
     args: &[String],
@@ -132,6 +149,77 @@ fn run_cleanup_route(
     Ok(())
 }
 
+fn run_structure_report(root: &Path, json: bool) -> Result<(), Box<dyn std::error::Error>> {
+    let mut report = check_repository_quality(root, QualityMode::Report)?;
+    report
+        .violations
+        .retain(|violation| is_structure_check(&violation.check_id));
+    report.summary.violation_count = report.violations.len();
+    report.summary.blocking_violation_count = report.violations.len();
+    report.summary.baseline_violation_count = report
+        .violations
+        .iter()
+        .filter(|violation| violation.baseline)
+        .count();
+    report.ok = report.violations.is_empty();
+    report.schema = "naome.repository-structure-report.v1".to_string();
+
+    if json {
+        println!("{}", serde_json::to_string_pretty(&report)?);
+    } else if report.violations.is_empty() {
+        println!("NAOME repository structure report: no debt found.");
+    } else {
+        println!(
+            "NAOME repository structure report: {} violation(s).",
+            report.violations.len()
+        );
+        for violation in report.violations.iter().take(20) {
+            print_quality_violation(violation);
+        }
+    }
+    Ok(())
+}
+
+fn run_structure_explain(
+    root: &Path,
+    args: &[String],
+    json: bool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let Some(path) = option_value(args, "--path") else {
+        return Err("naome structure explain requires --path <path>.".into());
+    };
+    let explanation = explain_repository_structure(root, path)?;
+    if json {
+        println!("{}", serde_json::to_string_pretty(&explanation)?);
+    } else {
+        println!(
+            "{} role={} layer={} directory={}",
+            explanation.path, explanation.role, explanation.layer, explanation.directory
+        );
+        if let Some(language) = explanation.language {
+            println!("language={language}");
+        }
+        if let Some(module) = explanation.module {
+            println!("module={module}");
+        }
+    }
+    Ok(())
+}
+
+fn is_structure_check(check_id: &str) -> bool {
+    matches!(
+        check_id,
+        "directory-role-mixing"
+            | "misplaced-file-role"
+            | "root-file-sprawl"
+            | "dumping-ground-directory"
+            | "directory-size"
+            | "path-depth"
+            | "case-collision"
+            | "test-source-pairing"
+    )
+}
+
 fn print_quality_violation(violation: &naome_core::QualityViolation) {
     let location = violation
         .line

package/crates/naome-core/Cargo.toml

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

package/crates/naome-core/src/decision/checks.rs

@@ -0,0 +1,64 @@
+use std::ffi::OsString;
+use std::path::Path;
+use std::process::Command;
+
+use crate::models::{CheckDecision, NaomeError};
+
+pub(super) fn run_node_check(
+    root: &Path,
+    script: &str,
+    args: &[&str],
+) -> Result<CheckDecision, NaomeError> {
+    let mut command_args = vec![script.to_string()];
+    command_args.extend(args.iter().map(ToString::to_string));
+    let node_bin = std::env::var_os("NAOME_NODE_BIN").unwrap_or_else(|| OsString::from("node"));
+    let output = Command::new(&node_bin)
+        .args(&command_args)
+        .current_dir(root)
+        .output()?;
+    let mut combined = String::new();
+    combined.push_str(&String::from_utf8_lossy(&output.stdout));
+    combined.push_str(&String::from_utf8_lossy(&output.stderr));
+
+    Ok(CheckDecision {
+        command: format!(
+            "{} {}{}",
+            node_bin.to_string_lossy(),
+            script,
+            if args.is_empty() {
+                String::new()
+            } else {
+                format!(" {}", args.join(" "))
+            }
+        ),
+        exit_code: output.status.code(),
+        ok: output.status.success(),
+        output: combined.trim().to_string(),
+    })
+}
+
+pub(super) fn extract_known_actions(output: &str) -> Vec<&'static str> {
+    const KNOWN: [&str; 11] = [
+        "commit_task_baseline",
+        "review_task_diff",
+        "request_task_changes",
+        "cancel_task_changes",
+        "commit_upgrade_baseline",
+        "review_diff_first",
+        "cancel_upgrade_baseline",
+        "run_first_run_protocol",
+        "run_upgrade_protocol",
+        "review_unowned_diff",
+        "create_task",
+    ];
+
+    let actions: Vec<&'static str> = KNOWN
+        .into_iter()
+        .filter(|action| output.contains(action))
+        .collect();
+    if actions.is_empty() {
+        vec!["review_task_admission"]
+    } else {
+        actions
+    }
+}

package/crates/naome-core/src/decision/idle.rs

@@ -0,0 +1,67 @@
+use std::path::Path;
+
+use crate::models::{Decision, NaomeError};
+use crate::paths;
+use crate::task_state::harness_refresh_diff;
+
+pub(super) fn idle_diff_decision(
+    root: &Path,
+    changed_paths: &[String],
+    machine_owned: &[String],
+    known_harness_paths: &[String],
+) -> Result<Decision, NaomeError> {
+    let all_machine_owned = !machine_owned.is_empty()
+        && changed_paths
+            .iter()
+            .all(|path| paths::matches_any(path, machine_owned));
+    let all_harness_owned = !known_harness_paths.is_empty()
+        && changed_paths
+            .iter()
+            .all(|path| paths::matches_any(path, known_harness_paths));
+
+    if harness_refresh_diff(root)?.is_some_and(|diff| diff.unrelated_paths.is_empty()) {
+        Ok(harness_repair_decision(
+            "Machine-owned NAOME harness refresh files changed outside an active task.",
+            "Run NAOME intent for the next natural-language request; deterministic policy can baseline a pure harness refresh automatically.",
+        ))
+    } else if all_machine_owned {
+        Ok(harness_repair_decision(
+            "Machine-owned NAOME harness files changed outside an active task.",
+            "Review and baseline the harness repair or cancel it before feature work.",
+        ))
+    } else if all_harness_owned {
+        Ok(Decision::new(
+            "install_or_upgrade_unbaselined",
+            true,
+            "NAOME setup or upgrade files changed outside an active task.",
+            vec![
+                "commit_upgrade_baseline",
+                "review_diff_first",
+                "cancel_upgrade_baseline",
+            ],
+            "Resolve the setup or upgrade diff before feature work.",
+        ))
+    } else {
+        Ok(Decision::new(
+            "dirty_unowned_diff",
+            true,
+            "The repository has changes not owned by an active NAOME task.",
+            vec!["review_unowned_diff"],
+            "Review the unowned diff, or route a new task so NAOME can isolate task work without touching it.",
+        ))
+    }
+}
+
+fn harness_repair_decision(user_message: &str, next_action: &str) -> Decision {
+    Decision::new(
+        "harness_repair_unbaselined",
+        true,
+        user_message,
+        vec![
+            "commit_upgrade_baseline",
+            "review_diff_first",
+            "cancel_upgrade_baseline",
+        ],
+        next_action,
+    )
+}

package/crates/naome-core/src/decision/json.rs

@@ -0,0 +1,36 @@
+use std::fs;
+use std::path::Path;
+
+use serde_json::Value;
+
+use crate::models::NaomeError;
+
+pub(super) fn read_json(root: &Path, relative_path: &str) -> Result<Value, NaomeError> {
+    let content = fs::read_to_string(root.join(relative_path))?;
+    Ok(serde_json::from_str(&content)?)
+}
+
+pub(super) fn json_bool(value: &Value, key: &str) -> Option<bool> {
+    value.get(key).and_then(Value::as_bool)
+}
+
+pub(super) fn json_string(value: &Value, key: &str) -> Option<String> {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .map(ToString::to_string)
+}
+
+pub(super) fn string_array_at(value: &Value, key: &str) -> Vec<String> {
+    value
+        .get(key)
+        .and_then(Value::as_array)
+        .map(|values| {
+            values
+                .iter()
+                .filter_map(Value::as_str)
+                .map(ToString::to_string)
+                .collect()
+        })
+        .unwrap_or_default()
+}

package/crates/naome-core/src/decision/states.rs

@@ -0,0 +1,165 @@
+use std::path::Path;
+
+use serde_json::Value;
+
+use crate::models::{Decision, NaomeError, TaskDecision};
+use crate::paths;
+use crate::task_state::harness_refresh_diff;
+
+use super::idle::idle_diff_decision;
+use super::json::{json_string, read_json, string_array_at};
+
+pub(super) fn completed_task_decision(
+    root: &Path,
+    changed_paths: Vec<String>,
+    task: Option<&TaskDecision>,
+) -> Result<Decision, NaomeError> {
+    let mut decision = if changed_paths.is_empty() {
+        Decision::new(
+            "ready_for_task",
+            false,
+            "The last completed NAOME task has no open diff.",
+            vec!["create_task"],
+            "Task admission is clear; create the next task before feature work.",
+        )
+    } else if has_completed_task_owned_paths(task, &changed_paths) {
+        Decision::new(
+            "completed_task_unbaselined",
+            true,
+            "A completed NAOME task is verified and waiting for the next routing decision.",
+            vec![
+                "commit_task_baseline",
+                "review_task_diff",
+                "request_task_changes",
+                "cancel_task_changes",
+            ],
+            "Run NAOME intent for the next natural-language request; deterministic policy can baseline a valid completed task automatically.",
+        )
+    } else if harness_refresh_diff(root)?.is_some_and(|diff| diff.unrelated_paths.is_empty()) {
+        Decision::new(
+            "harness_repair_unbaselined",
+            true,
+            "Machine-owned NAOME harness refresh files changed outside an active task.",
+            vec![
+                "commit_upgrade_baseline",
+                "review_diff_first",
+                "cancel_upgrade_baseline",
+            ],
+            "Run NAOME intent for the next natural-language request; deterministic policy can baseline a pure harness refresh automatically.",
+        )
+    } else {
+        Decision::new(
+            "dirty_unowned_diff",
+            true,
+            "The completed NAOME task has been baselined, but unrelated user changes remain.",
+            vec!["review_unowned_diff"],
+            "Review the unrelated diff, or route a new task so NAOME can isolate task work without touching it.",
+        )
+    };
+
+    decision.changed_paths = changed_paths;
+    decision.required_context = vec![
+        "docs/naome/execution.md".to_string(),
+        ".naome/task-state.json".to_string(),
+        "docs/naome/agent-workflow.md".to_string(),
+        "docs/naome/testing.md".to_string(),
+    ];
+    Ok(decision)
+}
+
+pub(super) fn active_task_decision(
+    changed_paths: Vec<String>,
+    task: Option<&TaskDecision>,
+) -> Decision {
+    let allowed_paths = task
+        .map(|task| task.allowed_paths.clone())
+        .unwrap_or_default();
+    let out_of_scope: Vec<String> = changed_paths
+        .iter()
+        .filter(|path| !is_control_state_path(path) && !paths::matches_any(path, &allowed_paths))
+        .cloned()
+        .collect();
+
+    let mut decision = if out_of_scope.is_empty() {
+        Decision::new(
+            "active_task_in_progress",
+            false,
+            "A NAOME task is active and the current diff is inside its declared scope.",
+            vec!["continue_task", "request_task_changes", "complete_task"],
+            "Continue the active task and keep proof current.",
+        )
+    } else {
+        Decision::new(
+            "active_task_blocked",
+            true,
+            "A NAOME task is active, but the current diff includes paths outside its declared scope.",
+            vec![
+                "revise_task_scope",
+                "revert_out_of_scope_diff",
+                "request_human_review",
+            ],
+            "Resolve out-of-scope changes before completing this task.",
+        )
+    };
+    decision.changed_paths = if out_of_scope.is_empty() {
+        changed_paths
+    } else {
+        out_of_scope
+    };
+    decision.required_context = vec![
+        "docs/naome/execution.md".to_string(),
+        ".naome/task-state.json".to_string(),
+        "docs/naome/testing.md".to_string(),
+    ];
+    decision
+}
+
+pub(super) fn classify_idle_diff(
+    root: &Path,
+    changed_paths: Vec<String>,
+) -> Result<Decision, NaomeError> {
+    let manifest = read_json(root, ".naome/manifest.json").unwrap_or(Value::Null);
+    let machine_owned = string_array_at(&manifest, "machineOwned");
+    let project_owned = string_array_at(&manifest, "projectOwned");
+
+    let mut known_harness_paths = machine_owned.clone();
+    known_harness_paths.extend(project_owned);
+    let mut decision =
+        idle_diff_decision(root, &changed_paths, &machine_owned, &known_harness_paths)?;
+
+    decision.changed_paths = changed_paths;
+    decision.required_context = vec![
+        "docs/naome/execution.md".to_string(),
+        ".naome/task-state.json".to_string(),
+    ];
+    Ok(decision)
+}
+
+pub(super) fn task_decision(task_state: &Value, status: &str) -> Option<TaskDecision> {
+    let active_task = task_state.get("activeTask")?;
+    if active_task.is_null() {
+        return None;
+    }
+
+    Some(TaskDecision {
+        id: json_string(active_task, "id"),
+        status: status.to_string(),
+        request: json_string(active_task, "request"),
+        allowed_paths: string_array_at(active_task, "allowedPaths"),
+        required_check_ids: string_array_at(active_task, "requiredCheckIds"),
+    })
+}
+
+fn has_completed_task_owned_paths(task: Option<&TaskDecision>, changed_paths: &[String]) -> bool {
+    let Some(task) = task else {
+        return false;
+    };
+
+    changed_paths
+        .iter()
+        .any(|path| is_control_state_path(path) || paths::matches_any(path, &task.allowed_paths))
+}
+
+fn is_control_state_path(path: &str) -> bool {
+    path == ".naome/task-state.json"
+}