@lamentis/naome 1.4.1 → 1.4.3

package/Cargo.lock

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

package/README.md

@@ -6,146 +6,41 @@
 <h1 align="center">NAOME</h1>
 
 <p align="center">
-  A deterministic repository harness for AI coding agents.
+  The repository harness for long-running Codex work.
 </p>
 
-```shell
-npm install -g @lamentis/naome
-```
+NAOME wraps your repository with deterministic controls and workflows so
+agentic AI systems can take on real software work: longer tasks, safer
+iterations, and eventually more autonomous execution.
 
-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.
+You install the harness. Codex and NAOME handle the workflow.
 
-## Quickstart
+## Start
 
-Install the CLI, then sync NAOME into a repository:
+Install the Lamentis NAOME package:
 
 ```shell
 npm install -g @lamentis/naome
-cd /path/to/repo
-naome sync
-```
-
-For an initialized repository, start with:
-
-```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
-```
-
-Prompt files should start with a fenced `naome-prompt-envelope-v1` JSON
-envelope that normalizes the raw user text into canonical routing fields. A raw
-natural-language prompt routes to a non-mutating normalization decision instead
-of becoming a task by keyword inference.
-
-## 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.
-
-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.
-
-## CLI Reference
-
-Common commands:
+Sync NAOME into your repository:
 
 ```shell
+cd /path/to/your/repo
 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 arch validate --changed-only
-naome task render-state --write --json
-naome commit -m "type(scope): summary"
 ```
 
-Architecture fitness builds a language-agnostic graph, extracts direct imports
-for TypeScript, JavaScript, Rust, Python, and Go, and can enforce configured
-layer dependency rules such as keeping domain code independent from
-infrastructure adapters.
-
-`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 local task ledger automatically and untracks local
-`.naome/tasks/` runtime folders from Git. 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/architecture-fitness.md` explains architecture graph validation
-  and agent feedback.
-
-Agents should follow the repository's NAOME docs instead of guessing workflow
-rules from generic project files.
+Open the repository in Codex and give the agent a normal task:
 
-## 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.arch.yaml` for language-agnostic architecture fitness rules.
-- `.naome/task-state.json` for the compact committed active task projection.
-
-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
-node .naome/bin/naome.js arch validate --changed-only --json
-git diff --check
+```text
+Use NAOME in this repository and implement the next change.
 ```
 
+That is the product flow. You do not need to learn NAOME commands, route
+prompts, select context, or manage task state. Codex follows the repository
+harness, and NAOME supplies the deterministic checks, boundaries, task memory,
+and verification flow behind the scenes.
+
 ## License
 
 NAOME is licensed under the [Apache License 2.0](../../LICENSE).

package/crates/naome-cli/Cargo.toml

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

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

@@ -37,12 +37,21 @@ const HELP: &str = r#"Usage:
   naome sync [--package-root <path>] [--installer-js <path>]
   naome install-plan [--harness-version <version>]
   naome seed-verification
-  naome task status [--json] [--exit-code]
-  naome task proof-plan [--json] [--exit-code]
-  naome task can-transition --to complete [--json]
+  naome task status [--json] [--exit-code] [--agent-session <id>]
+  naome task proof-plan [--json] [--exit-code] [--agent-session <id>]
+  naome task agent-snapshot --json [--exit-code] [--agent-session <id>]
+  naome task preflight (--path <path>...|--from-changed) --json [--agent-session <id>]
+  naome task commit-preflight --json [--exit-code] [--agent-session <id>]
+  naome task compact-proof [--dry-run] --json [--agent-session <id>]
+  naome task scope-suggestions --from-changed --json [--agent-session <id>]
+  naome task can-edit --path <path> --json [--agent-session <id>]
+  naome task run-check --check <check-id> [--record-proof] --json [--agent-session <id>]
+  naome task loop [--execute-safe] --json [--agent-session <id>]
+  naome task can-transition --to complete [--json] [--agent-session <id>]
   naome task can-commit --json
-  naome task repair --plan <id> --dry-run --json
-  naome task record-proof --from-proof-plan [--dry-run] --json
+  naome task complete --from-can-transition --json [--agent-session <id>]
+  naome task repair --plan <id> (--dry-run|--execute-safe) --json [--agent-session <id>]
+  naome task record-proof --from-proof-plan [--dry-run] --json [--agent-session <id>]
   naome task request-scope --path <path> --reason <reason> --json
   naome task timeline --json
   naome task loop-snapshot --json

package/crates/naome-cli/src/task_commands/agent_snapshot.rs

@@ -0,0 +1,173 @@
+use std::path::Path;
+
+use naome_core::{
+    task_proof_plan, task_status_exit_code, task_status_report, task_transition_readiness,
+};
+use serde_json::{json, Value};
+
+use super::common::{agent_session, print_json_with_session};
+use super::planner;
+
+pub(super) fn agent_snapshot(
+    root: &Path,
+    args: &[String],
+) -> Result<(), Box<dyn std::error::Error>> {
+    let session = agent_session(args)?;
+    let status = task_status_report(root)?;
+    let proof_plan = task_proof_plan(root)?;
+    let transition = task_transition_readiness(root, "complete")?;
+    let planned = merge_commands(
+        serde_json::to_value(&proof_plan.recommended_commands)?,
+        planner::planned_commands(
+            root,
+            &status.scope.in_scope_changed_paths,
+            Some(&status.proof),
+        ),
+    );
+    let (safe_to_run, deferred) = planner::split_safe_commands(&planned);
+    let can_commit = transition.allowed && status.agent_loop.can_commit;
+    let value = json!({
+        "schema": "naome.task.agent-snapshot.v1",
+        "state": snapshot_state(&status),
+        "task": {
+            "state": status.state,
+            "taskId": status.task_id,
+            "request": status.request
+        },
+        "git": {
+            "head": status.git.head,
+            "admissionHead": status.git.admission_head,
+            "admissionHeadReachable": status.git.admission_head_reachable,
+            "operationInProgress": status.git.operation_in_progress,
+            "branchDiverged": status.git.ahead > 0 || status.git.behind > 0
+        },
+        "scope": {
+            "allowedPaths": status.scope.allowed_paths,
+            "changedPaths": status.scope.changed_paths,
+            "editablePaths": editable_paths(&status),
+            "mustNotEditPaths": status.scope.out_of_scope_changed_paths,
+            "outOfScopeChangedPaths": status.scope.out_of_scope_changed_paths
+        },
+        "proof": status.proof,
+        "checks": {
+            "recommended": planned,
+            "safeToRun": safe_to_run,
+            "deferred": deferred
+        },
+        "commit": {
+            "canCommit": can_commit,
+            "blockingFindings": if can_commit { json!([]) } else { serde_json::to_value(&transition.blocking_findings)? }
+        },
+        "transition": {
+            "canComplete": transition.allowed,
+            "blockingFindings": transition.blocking_findings
+        },
+        "nextAction": snapshot_next_action(&status, &proof_plan, can_commit),
+        "agentLoop": status.agent_loop,
+        "repairPlan": status.repair_plan,
+        "findings": status.findings,
+        "agentInstruction": if can_commit { "Task is commit-ready; do not edit further before committing." } else { "Follow nextAction and only execute commands listed as safeToRun." }
+    });
+    let code = task_status_exit_code(&status.findings, &status.proof);
+    print_json_with_session(value, session.as_deref())?;
+    if args.iter().any(|arg| arg == "--exit-code") {
+        std::process::exit(code);
+    }
+    Ok(())
+}
+
+fn merge_commands(left: Value, right: Vec<Value>) -> Vec<Value> {
+    let mut commands = left
+        .as_array()
+        .cloned()
+        .unwrap_or_default()
+        .into_iter()
+        .chain(right)
+        .collect::<Vec<_>>();
+    commands.sort_by(|a, b| {
+        a.get("checkId")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .cmp(b.get("checkId").and_then(Value::as_str).unwrap_or(""))
+    });
+    commands.dedup_by(|a, b| {
+        a.get("checkId").and_then(Value::as_str) == b.get("checkId").and_then(Value::as_str)
+    });
+    commands
+}
+
+fn snapshot_state(status: &naome_core::TaskStatusReportV1) -> &'static str {
+    if status
+        .findings
+        .iter()
+        .any(|finding| finding.id.starts_with("task.git."))
+    {
+        "blocked_by_git_state"
+    } else if !status.scope.out_of_scope_changed_paths.is_empty() {
+        "blocked_by_scope_drift"
+    } else if !status.proof.missing_checks.is_empty() {
+        "blocked_by_missing_proof"
+    } else if !status.proof.stale_checks.is_empty() {
+        "blocked_by_stale_proof"
+    } else if status.agent_loop.can_commit {
+        "ready_to_commit"
+    } else {
+        "healthy"
+    }
+}
+
+fn editable_paths(status: &naome_core::TaskStatusReportV1) -> Vec<String> {
+    if matches!(
+        status.state.as_str(),
+        "idle" | "missing" | "complete" | "blocked" | "needs_human_review"
+    ) {
+        return Vec::new();
+    }
+    status.scope.allowed_paths.clone()
+}
+
+fn snapshot_next_action(
+    status: &naome_core::TaskStatusReportV1,
+    proof_plan: &naome_core::TaskProofPlanReport,
+    can_commit: bool,
+) -> Value {
+    let action_type = if !status.scope.out_of_scope_changed_paths.is_empty() {
+        "repair_scope"
+    } else if status
+        .findings
+        .iter()
+        .any(|finding| finding.id.starts_with("task.git."))
+    {
+        "recover_git"
+    } else if !status.proof.missing_checks.is_empty() || !status.proof.stale_checks.is_empty() {
+        "run_checks"
+    } else if !proof_plan.proof_recording.checks_to_record.is_empty() {
+        "record_proof"
+    } else if can_commit {
+        "commit_ready"
+    } else if status.state == "implementing" && status.agent_loop.can_continue_editing {
+        "edit"
+    } else {
+        "none"
+    };
+    if can_commit && action_type == "commit_ready" {
+        return json!({
+            "type": "commit_ready",
+            "reason": "Task is complete enough to commit; do not continue editing before commit.",
+            "commands": [],
+            "paths": status.scope.in_scope_changed_paths,
+            "checkIds": [],
+            "safeToExecute": false,
+            "requiresUserApproval": true
+        });
+    }
+    json!({
+        "type": action_type,
+        "reason": status.next_action_v2.reason,
+        "commands": status.next_action_v2.commands,
+        "paths": status.next_action_v2.paths,
+        "checkIds": status.next_action_v2.check_ids,
+        "safeToExecute": status.next_action_v2.safe_to_execute,
+        "requiresUserApproval": status.next_action_v2.requires_user_approval
+    })
+}

package/crates/naome-cli/src/task_commands/can_edit.rs

@@ -0,0 +1,64 @@
+use std::path::Path;
+
+use naome_core::{path_matches_any, task_status_report};
+use serde_json::json;
+
+use super::common::{agent_session, print_json_with_session, value_after};
+use super::path_policy::{edit_finding, is_control_path, is_ignored, normalize_requested_path};
+
+pub(super) fn can_edit(root: &Path, args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
+    let session = agent_session(args)?;
+    let Some(raw_path) = value_after(args, "--path") else {
+        return Err("naome task can-edit requires --path <path>".into());
+    };
+    let (path, path_error) = normalize_requested_path(raw_path);
+    let mut findings = Vec::new();
+    if let Some(message) = path_error {
+        findings.push(edit_finding("task.edit.unsafe_path", &message, raw_path));
+    } else if is_ignored(root, &path) {
+        findings.push(edit_finding(
+            "task.edit.ignored_path",
+            "Path is ignored by .naomeignore and is outside the active harness context.",
+            &path,
+        ));
+    } else if is_control_path(&path) {
+        findings.push(edit_finding(
+            "task.edit.control_path",
+            "NAOME control files cannot be edited through the autonomous can-edit path.",
+            &path,
+        ));
+    } else {
+        let status = task_status_report(root)?;
+        if status.task_id.is_none()
+            || matches!(
+                status.state.as_str(),
+                "idle" | "missing" | "complete" | "blocked" | "needs_human_review"
+            )
+        {
+            findings.push(edit_finding(
+                "task.edit.no_active_task",
+                "No editable active task is available for this path.",
+                &path,
+            ));
+        } else if !path_matches_any(&path, &status.scope.allowed_paths) {
+            findings.push(edit_finding(
+                "task.edit.out_of_scope",
+                "Path is outside activeTask.allowedPaths.",
+                &path,
+            ));
+        }
+    }
+
+    let allowed = findings.is_empty();
+    print_json_with_session(
+        json!({
+            "schema": "naome.task.can-edit.v1",
+            "path": path,
+            "allowed": allowed,
+            "reason": if allowed { "Path is inside active task scope." } else { "Path is not safe to edit for the active task." },
+            "findings": findings,
+            "agentInstruction": if allowed { "Agent may edit this path and must rerun task loop before completion." } else { "Do not edit this path unless task scope is explicitly revised." }
+        }),
+        session.as_deref(),
+    )
+}

package/crates/naome-cli/src/task_commands/check_run/output.rs

@@ -0,0 +1,34 @@
+use serde_json::{json, Value};
+
+pub(super) fn run_check_response(
+    check_id: &str,
+    executed: bool,
+    exit_code: Option<i32>,
+    recorded_proof: bool,
+    findings: Vec<Value>,
+    instruction: &str,
+    session: Option<&str>,
+) -> Value {
+    json!({
+        "schema": "naome.task.run-check.v1",
+        "checkId": check_id,
+        "executed": executed,
+        "exitCode": exit_code,
+        "recordedProof": recorded_proof,
+        "summary": instruction,
+        "findings": findings,
+        "agentInstruction": instruction,
+        "agentSession": session
+    })
+}
+
+pub(super) fn finding(id: &str, message: impl Into<String>) -> Value {
+    json!({
+        "id": id,
+        "severity": "error",
+        "message": message.into(),
+        "path": null,
+        "suggestedFix": "Use task proof-plan and declared safe checks before recording proof.",
+        "agentInstruction": "Do not record proof for failed, unknown, or unsafe checks."
+    })
+}

package/crates/naome-cli/src/task_commands/check_run/receipts.rs

@@ -0,0 +1,163 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use naome_core::task_evidence_fingerprint;
+use serde_json::{json, Value};
+
+const RECEIPTS_PATH: &str = "naome-task-check-runs.json";
+
+#[derive(Debug, Clone)]
+pub(in crate::task_commands) struct CheckRunReceipt {
+    pub(in crate::task_commands) task_id: Option<String>,
+    pub(in crate::task_commands) check_id: String,
+    pub(in crate::task_commands) command: String,
+    pub(in crate::task_commands) cwd: String,
+    pub(in crate::task_commands) exit_code: i32,
+    pub(in crate::task_commands) checked_at: String,
+    pub(in crate::task_commands) evidence_paths: Vec<String>,
+    pub(in crate::task_commands) evidence_fingerprint: String,
+    pub(in crate::task_commands) stdout_summary: String,
+    pub(in crate::task_commands) stderr_summary: String,
+    pub(in crate::task_commands) duration_ms: u128,
+    pub(in crate::task_commands) agent_session: Option<String>,
+}
+
+pub(in crate::task_commands) fn successful_receipts(
+    root: &Path,
+) -> Result<Vec<CheckRunReceipt>, Box<dyn std::error::Error>> {
+    let path = receipt_path(root)?;
+    let Ok(content) = fs::read_to_string(path) else {
+        return Ok(Vec::new());
+    };
+    let value: Value = serde_json::from_str(&content)?;
+    Ok(value
+        .as_array()
+        .into_iter()
+        .flatten()
+        .filter_map(receipt_from_value)
+        .filter(|receipt| receipt.exit_code == 0)
+        .collect())
+}
+
+pub(super) fn append_receipt(
+    root: &Path,
+    receipt: &CheckRunReceipt,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let path = receipt_path(root)?;
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let mut receipts = if path.exists() {
+        serde_json::from_str::<Value>(&fs::read_to_string(&path)?)?
+            .as_array()
+            .cloned()
+            .unwrap_or_default()
+    } else {
+        Vec::new()
+    };
+    receipts.push(receipt_to_value(receipt));
+    fs::write(
+        path,
+        format!("{}\n", serde_json::to_string_pretty(&receipts)?),
+    )?;
+    Ok(())
+}
+
+pub(in crate::task_commands) fn changed_paths(
+    root: &Path,
+) -> Result<Vec<String>, Box<dyn std::error::Error>> {
+    let output = Command::new("git")
+        .args(["status", "--porcelain=v1", "--untracked-files=all"])
+        .current_dir(root)
+        .output()?;
+    if !output.status.success() {
+        return Ok(Vec::new());
+    }
+    let mut paths = String::from_utf8_lossy(&output.stdout)
+        .lines()
+        .filter_map(|line| line.get(3..))
+        .map(|line| line.split(" -> ").last().unwrap_or(line).to_string())
+        .collect::<Vec<_>>();
+    paths.sort();
+    Ok(paths)
+}
+
+fn receipt_path(root: &Path) -> Result<PathBuf, Box<dyn std::error::Error>> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--git-path", RECEIPTS_PATH])
+        .current_dir(root)
+        .output()?;
+    if output.status.success() {
+        let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
+        if !path.is_empty() {
+            return Ok(root.join(path));
+        }
+    }
+    Ok(root.join(".git").join(RECEIPTS_PATH))
+}
+
+fn receipt_to_value(receipt: &CheckRunReceipt) -> Value {
+    json!({
+        "taskId": receipt.task_id,
+        "checkId": receipt.check_id,
+        "command": receipt.command,
+        "cwd": receipt.cwd,
+        "exitCode": receipt.exit_code,
+        "checkedAt": receipt.checked_at,
+        "evidencePaths": receipt.evidence_paths,
+        "evidenceFingerprint": receipt.evidence_fingerprint,
+        "stdoutSummary": receipt.stdout_summary,
+        "stderrSummary": receipt.stderr_summary,
+        "durationMs": receipt.duration_ms,
+        "agentSession": receipt.agent_session
+    })
+}
+
+fn receipt_from_value(value: &Value) -> Option<CheckRunReceipt> {
+    Some(CheckRunReceipt {
+        task_id: value
+            .get("taskId")
+            .and_then(Value::as_str)
+            .map(ToString::to_string),
+        check_id: value.get("checkId")?.as_str()?.to_string(),
+        command: value.get("command")?.as_str()?.to_string(),
+        cwd: value.get("cwd")?.as_str()?.to_string(),
+        exit_code: value.get("exitCode")?.as_i64()? as i32,
+        checked_at: value.get("checkedAt")?.as_str()?.to_string(),
+        evidence_paths: value
+            .get("evidencePaths")?
+            .as_array()?
+            .iter()
+            .filter_map(Value::as_str)
+            .map(ToString::to_string)
+            .collect(),
+        evidence_fingerprint: value
+            .get("evidenceFingerprint")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_string(),
+        stdout_summary: value
+            .get("stdoutSummary")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_string(),
+        stderr_summary: value
+            .get("stderrSummary")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_string(),
+        duration_ms: value.get("durationMs").and_then(Value::as_u64).unwrap_or(0) as u128,
+        agent_session: value
+            .get("agentSession")
+            .and_then(Value::as_str)
+            .map(ToString::to_string),
+    })
+}
+
+pub(in crate::task_commands) fn evidence_fingerprint(
+    root: &Path,
+    paths: &[String],
+) -> Result<String, Box<dyn std::error::Error>> {
+    Ok(task_evidence_fingerprint(root, paths)?)
+}