@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0
+
+- Hard-cut canonical source admission to `nimicoding.authority/v2`; removed `fmt --upgrade`, `check --require-format`, and all v1 migration/history compatibility paths.
+- Hard-cut the public `authority evidence` surface and impact-disposition contract; implementation/test/gate execution and conformance remain host-project responsibilities.
+- Revised `authority audit`, `authority impact`, and `authority review` to v2 contracts: audit evaluates explicit graph and exact lexical-invariant bindings without positive proof packets, impact is pure before/after analysis, and review reports narrow assurance dimensions with business semantics and implementation conformance explicitly not evaluated.
+- Added explicit-channel `authority change-candidates`, immutable per-invocation compiler snapshots with transient indexes, acronym-bearing term support, and focused source-string escape handling for authority consumer paths; no SQLite, cache, ranking, inferred relation, or semantic judgment is introduced.
+- Reused one immutable snapshot pair across diff and change-derived recall, made audit consume the same read model, normalized fail-closed `partial: false` envelopes, hardened segment-aware path containment, and added corpus-bound audit surface consistency checks.
+- Renamed graph and audit traversal accounting away from proof terminology while preserving complete fail-closed budget enforcement.
+
+## 0.4.0
+
+- Added bounded fail-closed `authority anchors` validation for closed lexical file/script anchors and optional tracked-file scope globs against an exact Git repository root.
+- Added optional fail-closed `authority check --scope-bindings <file>` enforcement for exact bidirectional registration of active-rule scopes without repository path resolution.
+- Added strict single-unit Canonical Markdown and closed multi-unit Canonical YAML `authority fmt`, `authority check`, and package-private deterministic compilation with SourceMaps.
+- Added `nimicoding.authority/v2` container defaults plus deterministic `fmt --upgrade` from v1 while retaining v1 only as an explicit migration and history-facing input.
+- Hard-cut read-only fail-closed `authority discover` to `nimicoding.authority-discovery/v2`, adding singular exact kind/owner/scope/lifecycle filters, SourceMapped deterministic normalized-term snippets, and an optional complete M1 direct-authored relation preview; the ranking tuple is unchanged, and the product never selects authority, supplies context, or performs semantic search.
+- Added exact-ID `authority query` and complete fail-closed bounded `authority context` over admitted compiler products.
+- Added byte-bounded compiler-output `authority diff` and explicit-relation `authority impact` with retained tombstones and fail-closed consumer/test dispositions.
+- Added fail-closed `authority refs`, `authority path`, and `authority subgraph` over explicit admitted relations with portable SourceMap locations, deterministic traversal, and hop/unit/edge/UTF-8 byte budgets.
+- Added repository-bound `authority consumers`, `authority terms`, and `authority closed-sets` reports for deterministic spec-consumption inventory, exact identifier cross-reference, and paired closed-vocabulary drift detection.
+- Added project-bound deterministic `authority audit` with governance-bound observations/findings, required-coverage gaps, stable fingerprints, and SARIF 2.1.0 projection.
+- Added Git-aware exact `authority review`: one immutable base commit and one race-checked current worktree snapshot compose the existing compiler, diff, impact, and current-audit products without changing Git or authority.
+- Added machine-first current-worktree `authority evidence` with exact authority/package-script/test-target bindings, independent content identities, a closed static `package-script-target-reachability/v1` probe, and identity-bound external supplied results; it executes nothing and always leaves conformance not evaluated.
+- Corrected public CLI pipe flushing so large JSON diagnostics and bounded semantic payloads complete before process exit.
+- Hard-cut the legacy reconstruction, taxonomy, table, generation-audit, placement, and spec-governance command plane; `authority check` is now the sole `.nimi/spec` conformance gate.
+- Contracted bootstrap/sync to one exact compact-guide projection plus managed instruction blocks; unrelated host files are ignored and exact deprecated projection paths fail closed.
+- Retained `validate-ai-governance` only as optional L3 repository governance, separate from authority admission and host task execution.
+- Hardened managed project paths with no-follow/shared-inode preflight, fatal UTF-8 host-envelope reads, strict managed-block topology, exact-span clear behavior, and effective-final `.gitignore` rule matching; failed preflight performs no managed mutation.
+- Added behavioural product-conformance gates that verify the repository-bound command contracts against worktree and packed-package implementations.
+
 ## 0.3.1
 
 - Made `validate-spec-governance --scope all` fail closed on the canonical spec tree before running project-configured checks.

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Nimi Coding accepts changes to methodology, spec construction, managed projections, and deterministic governance validators. AI-host control, provider execution, task-state management, and review-state management are outside this package.
+Nimi Coding accepts changes to canonical-authority methodology, formatter/compiler primitives, exact managed projections, deterministic authority gates, and optional L3 repository checks. Historical-format reconstruction, product-semantic generation, AI-host control, provider execution, task-state management, and review-state management are outside this package.
 
 Before opening a change:
 
@@ -11,6 +11,6 @@ pnpm check:pack
 pnpm check:ci
 ```
 
-Contract changes must update their parser or validator, negative cases, documentation, and package projection tests together. Do not add compatibility branches for pre-0.3 behavior; Git history is the migration evidence.
+Contract changes must update their parser or validator, negative cases, documentation, and package projection tests together. Do not add historical-format compatibility; Git history is the recovery evidence.
 
-Never commit `.nimi/local/**`, `.nimi/cache/**`, credentials, provider transcripts, or private repository evidence.
+Never commit `.nimi/local/**`, credentials, provider transcripts, or private repository evidence.

package/README.md

@@ -1,64 +1,320 @@
 # Nimi Coding
 
-Nimi Coding is an AI-native methodology and spec-governance package. It gives a repository a precise authority model, canonical spec construction contracts, managed governance projections, and deterministic validation.
+[简体中文](./README.zh-CN.md)
 
-Nimi Coding deliberately does not control an AI host. Planning, delegation, implementation, review, and task state belong to the host's native capabilities.
+**Deterministic authority for AI coding systems and third-party extensions.**
 
-## Install and bootstrap
+Nimi Coding turns project-owned normative specifications into stable identities, exact source locations, authored relations, and bounded fail-closed machine products. AI hosts, agent frameworks, CI systems, editor tooling, and third-party extensions can use those products to discover authority, navigate relationships, and review exact changes without treating model inference as repository truth.
+
+Most end users should not need to invoke `nimicoding` directly. The primary integration surface is the documented CLI and its purpose-specific JSON products. Nimi Coding is not an AI agent, planner, code generator, approval workflow, or universal specification language.
+
+## Why it exists
+
+AI models are good at generating code. They are less reliable at determining which document is authoritative, whether a search result is complete, how a rule moved across files, which declared relationships a change affects, or what a deterministic check actually evaluated.
+
+Nimi Coding makes those questions explicit:
+
+| AI coding problem | Nimi Coding control |
+| --- | --- |
+| Several documents appear authoritative | One closed canonical authority boundary |
+| Paths and headings change | Stable logical unit IDs independent of files and order |
+| Search returns noisy or truncated context | Bounded discovery, exact query, declared context, and graph products |
+| A semantic cut leaves unchanged survivors outside declared relations | Change-derived recall over caller-selected exact owner/scope/term/relation/Definition channels |
+| A model cannot cite the exact source | Portable field- and relation-level SourceMap locations |
+| Textual diffs obscure semantic change | Stable-ID semantic diff and declared impact obligations |
+| “No result” is presented as “clean” | Explicit budgets, scoped statuses, refusal, and failure semantics |
+| A Git review may mix moving inputs | Immutable base OID plus race-checked complete worktree capture |
+| Structural checks are read as product conformance | Business semantics and implementation conformance remain explicitly `not_evaluated` |
+
+## Product model
+
+```text
+Project-owned canonical authority
+  .nimi/spec/**/*.authority.{yaml,md}
+                    │
+                    ▼
+Authority Foundation
+  fmt · check · compile CLI over private AuthorityIR/SourceMap
+                    │
+                    ▼
+Spec Intelligence Plane
+  discover · query · context · refs/path/subgraph
+  diff · change-candidates · impact · audit · review
+                    │
+                    ▼
+Purpose-specific JSON / human output / SARIF (audit only)
+                    │
+                    ▼
+AI hosts · third-party extensions · CI · future editor/UI surfaces
+```
+
+Projects own all product meaning. Nimi Coding admits, locates, relates, and derives bounded products from that meaning; it does not invent it. OpenAPI, JSON Schema, Protobuf, tests, ADRs, and design documents remain the right tools for specialized structure, executable verification, rationale, examples, and diagrams.
+
+## What works today
+
+| Layer | Current capability | Truth boundary |
+| --- | --- | --- |
+| Authority Foundation | Canonical YAML/Markdown, formatter, complete-root check, private deterministic compiler and SourceMap | Unknown or unsupported canonical input is rejected, not ignored |
+| Discovery and exact reads | Exact kind/owner/scope/lifecycle filters, normalized lexical snippets, optional direct relation preview, exact query, bounded declared context | No semantic search, automatic authority selection, or absence proof |
+| Graph navigation | Incoming/outgoing refs, deterministic paths, bounded subgraphs over `applies_to` and `supersedes` | Only authored relations; no inferred semantic graph |
+| Change intelligence | Stable-ID semantic diff, change-derived active-survivor recall, and relation-derived impact obligations | Candidate completeness is scoped to explicit channels; impact accepts no disposition or completion state |
+| Deterministic audit | Project-owned bindings for the graph verifier and exact lexical invariants, with JSON and SARIF 2.1.0 | Exact case-sensitive token/phrase checks only; no synonym, embedding, or natural-language contradiction inference |
+| Git-aware review | Immutable base commit plus exact, race-checked current worktree snapshot composed through compile/diff/impact/audit | Read-only; business semantics and implementation conformance are explicitly `not_evaluated` |
+
+The current Nimi-realm validation corpus contains 33 canonical containers, 2,212 authority units, and 2,159 authored relations. Those figures demonstrate a real large-corpus replay; they are not package limits or a claim that the grammar covers every possible domain.
+
+## Five-minute adoption path
+
+Install and initialize the package:
 
 ```bash
 pnpm add -D @nimiplatform/nimi-coding
 pnpm exec nimicoding start --yes
 ```
 
-Bootstrap creates or updates only:
+`start` creates the compact AI-visible authoring guide, managed instruction blocks in `AGENTS.md` and `CLAUDE.md`, and the ignored `.nimi/local/` root. It does not generate product semantics or create `.nimi/spec` for the project.
 
-- `.nimi/config/**` — package defaults and host-owned spec input configuration
-- `.nimi/contracts/**` — authority, taxonomy, placement, and audit contracts
-- `.nimi/methodology/**` — reasoning and spec-construction methodology
-- managed guidance blocks in `AGENTS.md` and `CLAUDE.md`
+Author a complete canonical source such as `.nimi/spec/checkout.authority.yaml`:
 
-Canonical product authority remains under `.nimi/spec/**`. Local generation evidence belongs under `.nimi/local/state/spec-generation/**` and never becomes product authority.
+```yaml
+format: nimicoding.authority/v2
+owner: team.checkout
+scope: api.checkout
+units:
+  - id: definition.checkout-session
+    kind: definition
+    title: Checkout session
+    meaning: A server-owned session representing an active checkout.
+  - id: rule.checkout-session
+    kind: rule
+    title: Checkout requires a server-owned session
+    modality: must
+    statement: Checkout operations use a server-owned checkout session.
+    condition: Whenever a checkout operation begins.
+    failure: Reject the operation.
+    relations:
+      - type: applies_to
+        target: definition.checkout-session
+```
+
+> `nimicoding.authority/v2` is the only admitted source format. The container carries `owner` and a single `scope`, and units may omit `lifecycle` and empty `relations`. Older source formats fail closed in formatting, admission, compilation, and history-facing analysis; Git history remains the recovery record rather than a compatibility input.
 
-## Core commands
+Format changed files, admit the complete root, and query one exact unit:
 
 ```bash
-# Managed projection lifecycle
-pnpm exec nimicoding start --yes
-pnpm exec nimicoding sync --check
-pnpm exec nimicoding sync --apply
-pnpm exec nimicoding doctor --json
-pnpm exec nimicoding clear --yes
-
-# Spec construction evidence
-pnpm exec nimicoding blueprint-audit --json
-pnpm exec nimicoding classify-spec-tree --root .nimi/spec --json
-pnpm exec nimicoding generate-spec-migration-plan --root .nimi/spec --json
-pnpm exec nimicoding generate-spec-derived-docs --profile nimi --scope spec-human-doc
-
-# Deterministic validation
-pnpm exec nimicoding validate-spec-tree -- .nimi/spec
-pnpm exec nimicoding validate-spec-audit -- .nimi/local/state/spec-generation/spec-generation-audit.yaml
-pnpm exec nimicoding validate-placement --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-table-family --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-projection-edges --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-guidance-bodies --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-domain-admission --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-tracked-output-admission --profile nimi --root .nimi/spec
-pnpm exec nimicoding validate-spec-governance --profile nimi --scope all
-pnpm exec nimicoding validate-ai-governance --profile nimi --scope all
+pnpm exec nimicoding authority fmt .nimi/spec/checkout.authority.yaml
+pnpm exec nimicoding authority check .nimi/spec --json
+pnpm exec nimicoding authority query .nimi/spec rule.checkout-session --max-bytes 32768 --json
+```
+
+`authority check` on the complete root is the sole .nimi/spec conformance gate. Formatting a file does not admit its semantics, and checking only a changed file cannot replace the complete-root check. When `--scope-bindings <file>` is supplied, check also requires an exact bidirectional match between registered scopes and active-rule scope use; it validates binding declarations without resolving repository paths.
+
+### Static authority anchors
+
+`authority anchors` performs bounded, read-only lexical validation against one exact Git worktree root:
+
+```bash
+pnpm exec nimicoding authority anchors . \
+  --spec .nimi/spec \
+  --scope-bindings .nimi/config/authority-scope-bindings.yaml \
+  --max-units 1024 \
+  --max-anchors 4096 \
+  --max-bytes 2097152 \
+  --json
+```
+
+The anchor grammar is closed and case-sensitive. A **token** is one maximal non-whitespace sequence; punctuation attached without whitespace remains part of that token.
+
+- **Class A — file path:** a token containing at least one `/` and ending exactly in one of `.mjs`, `.js`, `.ts`, `.tsx`, `.rs`, `.go`, `.yaml`, `.yml`, `.md`, `.json`, `.proto`, or `.ps1`. Tokens beginning with `~` (including `~/`), `/`, an ASCII-letter Windows drive prefix such as `C:\` or `C:/`, or `\\` (UNC) are excluded by deterministic prefix checks because they denote runtime or host paths rather than repository paths. Every admitted token must equal a path returned by the repository-root `git ls-files` tracked-file inventory. There is no path normalization, prefix removal, or inferred match.
+- **Class B — package script:** the token `pnpm`, exactly one ASCII space, then one maximal non-whitespace script-name token. The name is admitted when it contains `:` or fully matches `[a-z][a-z0-9:-]*`; pnpm builtins `add`, `audit`, `create`, `dlx`, `exec`, `install`, `link`, `list`, `outdated`, `patch`, `publish`, `remove`, `run`, `update`, and `why` are excluded before exact own-key resolution against the root `package.json` `scripts` object. Nothing is executed.
+
+Only active-unit `meaning`, `statement`, `condition`, and `failure` fields are scanned. With `--scope-bindings`, every `path_glob` must match at least one tracked file; `*` excludes `/`, `?` matches one non-`/` character, and `**` crosses path segments. `module` and `command` bindings remain structure-only in this version. Human and JSON results report `{units, anchorsChecked, diagnostics}`; anchor diagnostics are ordered by unit ID, anchor text, field, and class and identify the exact unit and field. Unit, anchor, and compact UTF-8 result-byte budgets reject the whole validation rather than truncating it.
+
+Canonical YAML is a closed `format` plus non-empty `units` container. Canonical Markdown is a strict single-unit profile. The model is intentionally compact: `Rule` and `Definition`, `active` and `removed`, `must` and `must_not`, plus authored `applies_to` and linear `supersedes` relations.
+
+If a domain needs member-level API, schema, enum, state-machine, formula, or catalog structure that this grammar does not support, keep that precision in a specialized artifact outside the canonical grammar. Connect it through a project-owned adapter when a real integration requires it. Do not add arbitrary canonical fields: unknown fields fail closed so that no consumer can silently ignore intended authority.
+
+## AI host and extension journey
+
+```text
+Task has no exact authority ID
+  → discover bounded lexical candidates
+  → host or project authority chooses an exact ID
+  → query/context/refs/path/subgraph
+  → host plans and edits
+  → fmt changed sources + check the complete root
+  → review immutable base versus exact worktree
+      (semantic diff + declared impact + current audit)
 ```
 
-`classify-spec-tree` and `generate-spec-migration-plan` are non-mutating analysis commands. An emitted migration plan is local evidence, not an execution schedule.
+The host owns authority selection, planning, editing, retries, remediation, review state, and completion. Nimi Coding owns request validation, deterministic computation, explicit budgets, exact locations, and honest result boundaries.
+
+For machine integration, invoke the CLI with an argument array and consume both its exit status and JSON envelope. Read each product's scoped operation, analysis, and blocking status; never infer business or implementation conformance from an empty candidate/finding array. Invalid usage or internal failure and a completed-but-blocked product have distinct command-specific exits.
+
+In a configured Git project, use exact Git-aware review for one composed authority change product:
+
+```bash
+pnpm exec nimicoding authority review . \
+  --base origin/main \
+  --bindings .nimi/config/authority-verifiers.yaml \
+  --max-units 1024 \
+  --max-edges 4096 \
+  --max-bytes 2097152 \
+  --json
+```
+
+This example assumes that the repository already owns valid verifier bindings and that `origin/main` resolves to a commit containing `.nimi/spec`. `start` intentionally creates none of those project semantics or governance files.
+
+The base ref is resolved once to a full commit OID. The base `.nimi/spec` tree is read from Git objects; the complete current `.nimi/spec` filesystem tree includes tracked unchanged files, edits, deletions, untracked files, and unsupported entries. Capture races, missing objects, invalid corpora, malformed bindings, and insufficient budgets refuse the result instead of publishing mixed analysis. The command never checks out, stashes, resets, stages, commits, or manages a PR.
+
+For a redesign or rename that can leave unchanged active survivors outside the declared graph, run change-derived recall over an explicit channel set:
+
+```bash
+pnpm exec nimicoding authority change-candidates path/to/before-spec .nimi/spec \
+  --channels direct_relation,definition_identity,definition_title \
+  --max-candidates 2048 \
+  --max-reasons 20000 \
+  --max-bytes 33554432 \
+  --json
+```
+
+The result contains each recalled active non-root unit, its raw normative fields and modality, and exact side-qualified reasons. `complete: true` means the full union and all reasons for the caller-requested channels—not semantic relevance, conflict, retirement, authority validity, or implementation conformance. Owner, scope, and changed-term channels are available when the host explicitly wants their broader recall. Source-container proximity is excluded because regrouping is non-semantic and a complete annotation would grow as the root/candidate Cartesian product.
+
+Diff, review, and change-derived recall reuse immutable per-invocation compiler snapshots with transient `byId`, owner, scope, container, incoming, and outgoing indexes. Nothing is persisted: SQLite, cache invalidation, incremental compilation, embeddings, and cleanup state remain outside the product until a measured workload justifies them.
+
+## Comparison: old Nimi, current Nimi Coding, and a mature conventional spec stack
+
+“Conventional spec” here means a serious combination of Markdown/ADR, OpenAPI, JSON Schema or Protobuf, tests, and repository conventions—not an artificially weak pile of prose.
+
+| Dimension | Pre-refactor Nimi spec system | Current Nimi Coding | Mature conventional spec stack |
+| --- | --- | --- | --- |
+| Authority boundary | Human contracts, tables, generated views, maps, and profile rules required precedence conventions | One closed canonical authority root | Several specialized sources of truth, usually without one cross-format boundary |
+| Reference corpus shape | 144 mixed files: 101 Markdown, 43 YAML, including 33 generated views and 42 tables | 33 canonical containers compiling to 2,212 stable units | Project-specific and heterogeneous |
+| Identity | Contract IDs, `R-*` anchors, paths, and table rows were not universal | One stable ID per unit, independent of file, order, move, or regroup | Strong inside some formats, inconsistent across formats |
+| Domain-internal precision | Some tables modeled entities, required fields, API operations, Prisma/OpenAPI/service locators directly | Many enum/schema/state/catalog details remain atomic prose inside a Definition | OpenAPI, Schema, Protobuf, and dedicated DSLs are strongest in their domains |
+| Human rationale | Rich contracts and generated guides | Deliberately compact; long rationale belongs outside canonical authority | ADRs and design documents are strongest |
+| Admission | Multiple profile-specific validators and generators | One complete-root, fail-closed admission oracle | Strong per structured format; Markdown and cross-format admission vary |
+| Unknown input | Behavior depended on the consuming profile/tool | Rejected everywhere under the canonical root | Often preserved or silently ignored unless a schema/linter forbids it |
+| Duplication and drift | Human/table/generated/alignment representations could diverge | One canonical unit representation; derived products are rebuildable | Cross-document and cross-format drift remains common |
+| AI retrieval | Search and project-specific projections had duplicate/noisy inputs | Bounded discovery, exact query, and purpose-specific JSON | Full-text/RAG is flexible but completeness and noise vary |
+| Source traceability | Different profiles exposed locations differently | Uniform portable SourceMap for units, fields, and authored relations | Good within individual tools, inconsistent across tools |
+| Relationship graph | Links, maps, custom fields, and Atlas-like projections | One authored, bounded `applies_to`/`supersedes` graph | `$ref`, links, imports, and conventions remain format-specific |
+| Conflict discovery | Custom checks could find project-specific drift | Structural conflicts are deterministic; prose contradictions still require AI/human analysis | Format-local conflicts can be strong; cross-format conflict remains difficult |
+| Semantic change | File diff and generated drift dominated | Stable-ID semantic diff; rename/regroup/format-only changes can be semantic zero | Prose is line-diffed; specialized formats may have excellent domain diff tools |
+| Impact and audit | Project scripts, maps, and team knowledge | Declared relation impact plus configured graph and exact lexical findings | Build graphs, CODEOWNERS, linters, and tests are strong but fragmented |
+| Git review | No unified exact authority snapshot product | Immutable-base, race-checked worktree review | Usually Git diff plus independent format-specific checks |
+| Spec-to-code relationship | Direct paths were detailed but could become stale | Not currently modeled by the authority core | Codegen, type checking, and contract tests can be substantially stronger |
+| Executable conformance | Some custom scripts checked specific project facts | Explicitly `not_evaluated` by review | High-quality tests and executable contracts are strongest |
+| Ecosystem | Highly project-specific | Stable CLI/JSON products, but no public JS SDK or model/tool standard yet | OpenAPI/Schema/test ecosystems and third-party interoperability are mature |
+| Authoring cost | Multiple representations and generators were expensive | IDs, owners, scopes, lifecycles, and relations require discipline | Lowest during exploration; governance cost rises with corpus size |
+| Best fit | A project-specific integrated spec system | Stable normative authority control alongside a large, AI-consumed estate of specialized specs | Exploration and specialized API/data/behavior contracts |
+
+The redesign is not a universal win on every axis. It is a deliberate exchange: current Nimi Coding gains a uniform authority coordinate system, deterministic machine consumption, and exact review semantics, while specialized formats retain domain precision, executable verification, ecosystem maturity, and human explanation.
+
+## Comprehensive assessment
+
+The current architecture is already a strong substrate for AI coding because it addresses authority identity, retrieval, traceability, change review, and false-clean prevention without depending on a particular model.
+
+Three levels of product truth should remain distinct:
+
+1. **Strong today:** stable identity, fail-closed admission, exact SourceMap, authored graph navigation, bounded machine products, semantic diff, and exact Git review.
+2. **Improved but incomplete:** locating and tracing the exact inputs for human/AI conflict review, task-context assembly, owner/scope accountability, and spec-to-code traceability. Contradiction judgment itself is not a deterministic product.
+3. **Intentionally not solved:** universal business-semantic completeness, automatic authority selection, executable code conformance, model reasoning, and AI workflow orchestration.
+
+The long-term ceiling is high if Nimi Coding standardizes the authority protocol rather than attempting to absorb every domain language. A model-native ecosystem could train AI systems to discover before guessing, resolve exact IDs, distinguish authored facts from inference, honor refusal and scoped status, and request bounded analysis after edits. Deterministic runtime products must remain the oracle; model familiarity must never replace admission or the project's real tests and gates.
+
+## Safety and truth boundaries
+
+- Only `*.authority.yaml` and `*.authority.md` under `.nimi/spec/**` are canonical product authority.
+- IDs, relations, owners, and scopes are declared facts. Nimi Coding does not infer relations or organizational truth from prose.
+- `discover` is deterministic lexical candidate retrieval, not semantic search, selection, context assembly, or absence proof.
+- `change-candidates` returns the complete union only for explicitly requested deterministic channels. It does not rank, infer conflict, choose retirement, or prove absence outside those channels.
+- `context` is a complete bounded outgoing interpretation closure, not complete task context.
+- `audit` evaluates explicitly bound deterministic governance checks; it does not prove that all business rules are non-contradictory.
+- `impact` reports declared relation impact and host-owned consumer/test follow-up targets. It accepts no disposition or completion state.
+- `review` audits the captured current snapshot and reports `businessSemanticStatus` and `implementationConformanceStatus` as `not_evaluated`; it does not attribute a current finding to the change.
+- Snapshot no-follow hardening is platform-dependent. On `win32`, Node.js does not expose `O_NOFOLLOW`/`O_DIRECTORY`, so snapshot capture uses surrounding `lstat`/`realpath` validation without descriptor-level no-follow guarantees.
+- Raw AuthorityIR, SourceMap internals, and compiler implementation are package-private. There is currently no public JavaScript API (`exports` is empty).
+- `.nimi/local/**` is derived or local output, never product authority.
+
+## Future roadmap
+
+The roadmap is paused at the current validated baseline. The entries below are candidate lanes, not implementation authorization, release promises, or an implied sequence. A future iteration should select one real adopter journey at a time.
+
+| Candidate lane | Intended product | Entry condition |
+| --- | --- | --- |
+| Stateless AI tool adapter | Typed tools over current bounded JSON products, potentially via MCP or an extension API | A real host integration demonstrates that direct CLI invocation is insufficient |
+| Read-only unit/code locator | Exact project-declared unit → declaration/test/gate bindings and reverse lookup | A real implementation-alignment journey demonstrates stable explicit bindings; no execution or conformance status is added |
+| D2 IDE/LSP | Live diagnostics, exact-ID navigation/completion, full-snapshot unsaved-buffer overlays | A sustained editor journey justifies a separate delivery unit |
+| D3 local Studio | Read-only unit/graph/diff/impact/audit exploration | Several real review/exploration journeys are validated first |
+| D4 external semantic candidates | Model/embedding/reranking candidates with provenance and abstention | Lexical/graph shortcomings are measured on an owner-approved task corpus |
+| E1 multi-repository Atlas | Visibility-filtered composition of canonical repository snapshots | Ecosystem repositories, identity, visibility, ownership, and workspace membership are explicit |
+
+Conditional work remains separate:
+
+- Structured Definitions, replacement DAGs, owner/scope registries, or a public library API require demonstrated authoring/query/consumer loss.
+- Storage, SQLite, cache, or incremental compilation require a real workload to violate a predeclared SLO and profiling to identify repeated parse/index/join as the cause.
+- Version bump, tag, publish, ecosystem activation, and release compatibility are independent release decisions.
+- AI planning, delegation, execution, approval, task state, model/provider orchestration, and inferred model findings do not belong in the core package.
+
+## Command reference
+
+The current public integration surface is the CLI. All budgets are explicit positive safe integers; a product that cannot fit its required budget refuses rather than truncating a blocking-capable result.
+
+| Purpose | Commands |
+| --- | --- |
+| Author and admit | `authority fmt`, `authority check`, `authority compile` |
+| Find and read | `authority discover`, `authority query`, `authority context` |
+| Navigate | `authority refs`, `authority path`, `authority subgraph` |
+| Analyze and review | `authority audit`, `authority diff`, `authority change-candidates`, `authority impact`, `authority review` |
+| Validate lexical anchors | `authority anchors` |
+| Project lifecycle | `start`, `sync`, `doctor`, `clear` |
+| Optional L3 repository governance | `validate-ai-governance` |
+
+<details>
+<summary>Complete authority command syntax</summary>
+
+```text
+nimicoding authority fmt <file> [--check] [--json]
+nimicoding authority check <path> [--scope-bindings <file>] [--json]
+nimicoding authority compile <path> [--json]
+nimicoding authority anchors <repository-path> --spec <corpus-path> [--scope-bindings <file>] [--embedded-paths] --max-units <n> --max-anchors <n> --max-bytes <n> [--json]
+nimicoding authority consumers <repository-path> --spec <corpus-path> [--external-root <scheme>=<path>]... --max-files <n> --max-refs <n> --max-bytes <n> [--json]
+nimicoding authority terms <repository-path> --spec <corpus-path> [--term <t>] [--code] --max-units <n> --max-terms <n> --max-bytes <n> [--json]
+nimicoding authority closed-sets <repository-path> --spec <corpus-path> --max-units <n> --max-sets <n> --max-bytes <n> [--json]
+nimicoding authority discover <path> <query> [--kind <definition|rule>] [--owner <exact-owner>] [--scope <exact-scope>] [--lifecycle <active|removed>] --max-candidates <n> --max-snippet-terms <n> --max-bytes <n> [--preview-direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --max-edges <n>] [--json]
+nimicoding authority query <path> <id> --max-bytes <n> [--json]
+nimicoding authority context <path> <id> --max-units <n> --max-bytes <n> [--json]
+nimicoding authority refs <path> <id> --direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --max-units <n> --max-edges <n> --max-bytes <n> [--json]
+nimicoding authority path <path> <from-id> <to-id> --traversal <directed|incidence> --relations <comma-separated-relation-types> --max-hops <n> --max-units <n> --max-edges <n> --max-bytes <n> [--json]
+nimicoding authority subgraph <path> <id> --direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --depth <n> --max-units <n> --max-edges <n> --max-bytes <n> [--json]
+nimicoding authority audit <path> --bindings <file> --max-units <n> --max-edges <n> --max-bytes <n> [--json|--sarif]
+nimicoding authority diff <before-path> <after-path> --max-bytes <n> [--json]
+nimicoding authority change-candidates <before-path> <after-path> --channels <comma-separated-closed-set> --max-candidates <n> --max-reasons <n> --max-bytes <n> [--json]
+nimicoding authority impact <before-path> <after-path> --max-bytes <n> [--json]
+nimicoding authority review <repository-path> --base <git-ref> --bindings <file> --max-units <n> --max-edges <n> --max-bytes <n> [--json]
+```
+
+</details>
+
+Relation types are a non-empty unique subset of the closed set `applies_to,supersedes`; discovery relation preview requires direction, relation types, and edge budget together.
+
+<details>
+<summary>Project lifecycle, governance, and global syntax</summary>
+
+```text
+nimicoding start [--yes]
+nimicoding sync [--apply|--check|--dry-run] [--json]
+nimicoding clear [--yes]
+nimicoding doctor [--verbose|--json]
+nimicoding validate-ai-governance --profile <profile-id> --scope <all|agents-freshness|context-budget|structure-budget|high-risk-doc-metadata> [--json]
+```
 
-## Authority model
+Global presentation options are `--lang en|zh`, `--color`, and `--no-color`.
 
-1. The host's `.nimi/spec/**` is canonical product authority.
-2. Package methodology and contracts remain package authority and project into `.nimi/{methodology,contracts,config}/**`.
-3. Generated views, audit evidence, and operational state are non-authoritative.
-4. Unknown placement or unresolved semantic ambiguity fails closed.
+</details>
 
-See `methodology/spec-reconstruction.yaml`, `contracts/surface-taxonomy.schema.yaml`, and `contracts/placement-contract.schema.yaml` for the normative construction model.
+Projection ownership is exact: `start`/`sync` own only their documented managed paths and marked instruction blocks. Files outside those exact managed surfaces are not inspected or modified by projection sync. Optional `validate-ai-governance` remains separate from authority admission and host task execution.
 
 ## Development