@lamentis/naome 1.2.0 → 1.3.0

package/Cargo.lock

@@ -76,7 +76,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "naome-cli"
-version = "1.2.0"
+version = "1.3.0"
 dependencies = [
  "naome-core",
  "serde_json",
@@ -84,7 +84,7 @@ dependencies = [
 
 [[package]]
 name = "naome-core"
-version = "1.2.0"
+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).