@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.6.0
+
+- Made all AI-visible operational guidance resolve the pinned project-local CLI through repository-root `pnpm exec nimicoding`, removing the false global-`PATH` availability assumption.
+- Added experimental `nimicoding code context`: a JSON-only, output-bounded TypeScript 5.9.3 root-direct static context over explicit current-filesystem inputs; it does not claim inbound impact, runtime dispatch, or complete task context. TypeScript 5.9.3 is now a package runtime dependency.
+- Added experimental `nimicoding code authority`: transient JSON-only Authority-to-Code, Code-to-Authority, and lifecycle audit for exact optional `nimi-authority` and `nimi-deprecated` markers in tracked current TypeScript, TSX, and Go source. Managed host instructions teach AI coding hosts to add markers only at key semantic owners and keep unannotated code unevaluated.
+- Removed the legacy optional `validate-ai-governance` command and its threshold, waiver, freshness, and metadata implementation surface without a compatibility path.
+
+## 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.

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-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.
+Nimi Coding accepts changes to canonical-authority products, formatter/compiler primitives, exact managed projections, and bounded read-only code queries over explicit inputs or markers. Historical-format reconstruction, product-semantic generation, AI-host control, provider execution, task-state management, and review-state management are outside this package. Code queries remain request-local and do not establish implementation conformance.
 
 Before opening a change:
 

package/README.md

@@ -4,13 +4,13 @@
 
 **Deterministic authority for AI coding systems and third-party extensions.**
 
-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, assemble evidence, navigate relationships, and review exact changes without treating model inference as repository truth.
+Nimi Coding turns project-owned normative specifications into stable identities, exact source locations, authored relations, and bounded fail-closed machine products. It also derives one bounded, read-only TypeScript outbound context from explicit repository, source, symbol, and tsconfig inputs. AI hosts can use these products 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 whether available evidence actually proves conformance.
+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:
 
@@ -19,11 +19,14 @@ Nimi Coding makes those questions explicit:
 | 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 selected TypeScript symbol still requires broad file reading | One explicitly bounded root-direct outbound code-context projection |
+| Authority-to-code links are guessed from names or nearby text | Optional exact authored markers with deterministic bidirectional lookup |
+| 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, completeness, gaps, refusal, and failure semantics |
+| “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 |
-| A file or test name is treated as proof | Evidence and conformance are separate product states |
+| Structural checks are read as product conformance | Business semantics and implementation conformance remain explicitly `not_evaluated` |
 
 ## Product model
 
@@ -38,7 +41,7 @@ Authority Foundation
                     ▼
 Spec Intelligence Plane
   discover · query · context · refs/path/subgraph
-  diff · impact · audit · review · evidence
+  diff · change-candidates · impact · audit · review
                     │
                     ▼
 Purpose-specific JSON / human output / SARIF (audit only)
@@ -56,12 +59,19 @@ Projects own all product meaning. Nimi Coding admits, locates, relates, and deri
 | 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 and relation-derived impact obligations | Impact is a review requirement, not synchronization proof |
-| Deterministic audit | Project-owned verifier bindings, observations/findings/required gaps, JSON and SARIF 2.1.0 | The current built-in detector is a narrow governance verifier, not a natural-language contradiction engine |
-| Git-aware review | Immutable base commit plus exact, race-checked current worktree snapshot composed through compile/diff/impact/audit | Read-only; not branch, PR, approval, or release orchestration |
-| Authority-to-code evidence | Exact authority/scope to declared package-script command/test target reachability | Static narrow slice only; commands/tests are not executed and completed evidence leaves conformance `not_evaluated` |
+| 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` |
+| TypeScript code context | Root declaration source plus root-direct static bindings, portable declaration loci, and eligible target source slices | Explicit `.ts`/`.tsx` root and tsconfig, TypeScript 5.9.3, outbound only; no locating, inbound impact, runtime dispatch, or task-completeness claim |
+| Explicit code-authority links | Transient Authority→Code, Code→Authority, and lifecycle audit over optional exact markers in tracked current `.ts`, `.tsx`, and `.go` source | Marker location only; no declaration ownership, annotation coverage, implementation conformance, or unannotated legacy detection |
 
-The current Nimi-realm validation corpus contains 38 canonical containers, 793 authority units, and 1,260 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.
+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.
+
+## Using the 0.6 code surface
+
+`start` writes package-managed guidance into the marked blocks in `AGENTS.md` and `CLAUDE.md`. On an existing installation, `doctor` diagnoses drift in that guidance and the compact methodology projection; `sync --apply` restores the exact current package projections while preserving host-owned text outside the managed blocks. An AI host that honors repository instructions can therefore learn when to request `code authority` or `code context`, and when a changed authority-governed feature warrants a small number of `nimi-authority` markers at key semantic owners.
+
+This is instruction-based integration, not an automatic execution layer. Nimi Coding installs no hook or daemon, intercepts no task, requires no fixed preflight, and owns no task or completion state. The host decides whether a query is useful for the current coding task. `code authority` only recalls explicit markers and current authority lifecycle; `code context` only returns the admitted root-direct TypeScript projection. Neither result proves conformance, replaces affected builds and tests, or evaluates unannotated code.
 
 ## Five-minute adoption path
 
@@ -74,6 +84,8 @@ pnpm exec nimicoding start --yes
 
 `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.
 
+`pnpm exec nimicoding` is the supported host invocation: run it from the repository root so automation resolves the pinned project-local package. A global `nimicoding` binary in `PATH` is neither required nor a valid availability check.
+
 Author a complete canonical source such as `.nimi/spec/checkout.authority.yaml`:
 
 ```yaml
@@ -97,7 +109,7 @@ units:
         target: definition.checkout-session
 ```
 
-> The example is the current v2 authoring format: the container carries `owner` and a single `scope`, and units omit `lifecycle` and empty `relations`. `nimicoding.authority/v1` is a migration input only -- `fmt --upgrade` reads it and emits v2, and history-facing commands still read it -- not a format to author in.
+> `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.
 
 Format changed files, admit the complete root, and query one exact unit:
 
@@ -132,7 +144,7 @@ Only active-unit `meaning`, `statement`, `condition`, and `failure` fields are s
 
 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 only through an explicitly admitted project binding or adapter; the current built-in evidence slice supports package-script targets, not general API, schema, consumer, or runtime integration. Do not add arbitrary canonical fields: unknown fields fail closed so that no consumer can silently ignore intended authority.
+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
 
@@ -145,12 +157,11 @@ Task has no exact authority ID
   → fmt changed sources + check the complete root
   → review immutable base versus exact worktree
       (semantic diff + declared impact + current audit)
-  → separately, if configured, inspect current-worktree evidence
 ```
 
 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 product-specific operation, completeness, policy, gap, and evidence states; never infer clean from an empty candidate/finding array. Invalid usage or internal failure and a completed-but-blocking or incomplete product have distinct command-specific exits.
+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:
 
@@ -158,16 +169,30 @@ In a configured Git project, use exact Git-aware review for one composed authori
 pnpm exec nimicoding authority review . \
   --base origin/main \
   --bindings .nimi/config/authority-verifiers.yaml \
-  --dispositions .nimi/local/authority-impact-dispositions.yaml \
   --max-units 1024 \
   --max-edges 4096 \
   --max-bytes 2097152 \
   --json
 ```
 
-This example assumes that the repository already owns valid verifier bindings and impact dispositions, and that `origin/main` resolves to a commit containing `.nimi/spec`. `start` intentionally creates none of those project semantics or governance files.
+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 policy 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.
 
-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/dispositions, and insufficient budgets refuse the result instead of publishing a mixed or false-clean review. The command never checks out, stashes, resets, stages, commits, or manages a PR.
+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
 
@@ -176,7 +201,7 @@ The base ref is resolved once to a full commit OID. The base `.nimi/spec` tree i
 | 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 | 38 canonical containers compiling to 793 stable units | Project-specific and heterogeneous |
+| 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 |
@@ -188,10 +213,10 @@ The base ref is resolved once to a full commit OID. The base `.nimi/spec` tree i
 | 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 project-bound finding/gap semantics | Build graphs, CODEOWNERS, linters, and tests are strong but fragmented |
+| 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 | A narrow, identity-bound package-script evidence slice exists | Codegen, type checking, and contract tests can be substantially stronger |
-| Executable conformance | Some custom scripts checked specific project facts | Intentionally not claimed by current evidence | High-quality tests and executable contracts are strongest |
+| Spec-to-code relationship | Direct paths were detailed but could become stale | Authority core stores no mapping; optional exact code markers provide authored locating only, with unannotated code and conformance not evaluated | 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 |
@@ -205,44 +230,33 @@ The current architecture is already a strong substrate for AI coding because it
 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.
+2. **Improved but incomplete:** optional authored marker lookup and bounded TypeScript outbound context reduce implementation navigation, while complete task context, unannotated code, and conformance remain unevaluated. 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 gaps and completeness, and request review/evidence after edits. Deterministic runtime products must remain the oracle; model familiarity must never replace admission or evidence.
+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` produces declared review obligations; a disposition does not prove implementation or tests are synchronized.
-- `review` audits the captured current snapshot and does not attribute a current finding to the change unless a future product explicitly compares finding fingerprints.
+- `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.
-- `evidence` currently proves only declared package-script target reachability. It executes no command or test; every completed evidence product reports `conformanceStatus: not_evaluated`, while refused input returns no evidence product.
 - 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 evidence, never product authority.
-
-## Future roadmap
+- `.nimi/local/**` is derived or local output, never product authority.
 
-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.
+## Future work
 
-| 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 |
-| General M4 API/consumer evidence | API/consumer locators and producer → API → consumer reachability | A real canonical-authority seam exists; no inference from the current package-script slice |
-| 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/evidence 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:
+Version 0.6 intentionally stops at the current request-local products. No next phase is implied. A later iteration should begin with one real adopter failure and add only the smallest missing mechanism:
 
-- 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.
+- Add a typed host adapter only if direct CLI invocation proves insufficient in actual use.
+- Add unsaved-buffer support only if a sustained editor journey requires it.
+- Add storage, semantic retrieval, or multi-repository composition only after measured use demonstrates a concrete loss that the current transient exact products cannot address.
+- AI planning, delegation, execution, approval, task state, model/provider orchestration, implementation conformance, and completion tracking remain outside the core package.
 
 ## Command reference
 
@@ -253,18 +267,17 @@ The current public integration surface is the CLI. All budgets are explicit posi
 | 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 impact`, `authority review` |
+| Analyze and review | `authority audit`, `authority diff`, `authority change-candidates`, `authority impact`, `authority review` |
 | Validate lexical anchors | `authority anchors` |
-| Connect bounded evidence | `authority evidence` |
+| Read implementation context and explicit links | `code context`, `code authority` |
 | 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] [--upgrade] [--json]
-nimicoding authority check <path> [--scope-bindings <file>] [--require-format <format>] [--json]
+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]
@@ -278,31 +291,55 @@ nimicoding authority path <path> <from-id> <to-id> --traversal <directed|inciden
 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 impact <before-path> <after-path> --dispositions <file> --max-bytes <n> [--json]
-nimicoding authority review <repository-path> --base <git-ref> --bindings <file> --dispositions <file> --max-units <n> --max-edges <n> --max-bytes <n> [--json]
-nimicoding authority evidence <repository-path> --bindings <tracked-.nimi/config-path> [--probe-results <.nimi/local-path>] --max-units <n> --max-bindings <n> --max-locators <n> --max-edges <n> --max-input-bytes <n> --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>
 
+<details>
+<summary>Explicit code-authority marker syntax</summary>
+
+```text
+// nimi-authority: <exact-authority-id>
+// nimi-deprecated: <exact-authority-id>
+
+nimicoding code authority --repo <exact-git-worktree-root> (--authority <exact-id>|--source <repo-relative-.ts-.tsx-or-.go-path>|--audit) --max-files <integer> --max-bytes <integer>=512
+```
+
+Markers are optional exact authored links. The command compiles the repository's complete canonical `.nimi/spec`, scans the selected Git-tracked current-filesystem source scope once, and returns one complete compact JSON result or refuses. `nimi-deprecated` records an explicit developer judgment and is reported by the audit; the tool does not infer that judgment or prove marker pairing, declaration ownership, conformance, or hard-cut completion. Unannotated code remains valid and `not_evaluated`. No index, cache, scope binding, report, or task state is written.
+
+</details>
+
+<details>
+<summary>TypeScript code context syntax</summary>
+
+```text
+nimicoding code context <repo-relative-.ts-or-.tsx-path> --repo <exact-git-worktree-root> --symbol <top-level-identifier> --tsconfig <repo-relative-tsconfig> --max-bytes <integer>=512
+```
+
+The command reads the current filesystem and writes one compact JSON response to stdout. `completed` covers only its closed root-direct static-binding policy. `partial` reports the first output-budget frontier; `refused` contains no usable context product. The command neither edits the repository nor selects, runs, or records verification.
+
+</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>
+<summary>Project lifecycle 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]
 ```
 
 Global presentation options are `--lang en|zh`, `--color`, and `--no-color`.
 
 </details>
 
-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.
+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. Code queries are request-local and do not participate in authority admission or host task execution.
 
 ## Development