Nimi Coding

简体中文

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, 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

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:

pnpm add -D @nimiplatform/nimi-coding
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.

Author a complete canonical source such as .nimi/spec/checkout.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.

Format changed files, admit the complete root, and query one exact unit:

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:

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

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)

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:

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:

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

Complete authority command syntax

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]

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.

Project lifecycle, governance, and global syntax

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.

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

pnpm install
pnpm test
pnpm check:pack
pnpm check:ci

Requires Node.js 24+ and pnpm 10+.