@nimiplatform/nimi-coding 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 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.

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,7 +4,7 @@
 
 **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.
+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.
 
@@ -19,6 +19,8 @@ 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 |
@@ -60,9 +62,17 @@ Projects own all product meaning. Nimi Coding admits, locates, relates, and deri
 | 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 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
 
 Install and initialize the package:
@@ -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
@@ -163,7 +175,7 @@ pnpm exec nimicoding authority review . \
   --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.
+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.
 
@@ -203,7 +215,7 @@ Diff, review, and change-derived recall reuse immutable per-invocation compiler
 | 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 |
+| 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 |
@@ -218,7 +230,7 @@ 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 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.
@@ -237,25 +249,14 @@ The long-term ceiling is high if Nimi Coding standardizes the authority protocol
 - 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 |
+## Future work
 
-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
 
@@ -268,8 +269,8 @@ The current public integration surface is the CLI. All budgets are explicit posi
 | 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` |
+| 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>
@@ -297,24 +298,48 @@ nimicoding authority review <repository-path> --base <git-ref> --bindings <file>
 
 </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
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 **面向 AI Coding 系统和第三方扩展的确定性 authority 控制层。**
 
-Nimi Coding 将项目自行拥有的规范性规则转化为稳定身份、精确源码位置、显式关系和有界、fail-closed 的机器产品。AI host、agent framework、CI、编辑器工具和第三方扩展可以据此发现 authority、导航关系并审查精确变更，而不把模型推断当作 repository truth。
+Nimi Coding 将项目自行拥有的规范性规则转化为稳定身份、精确源码位置、显式关系和有界、fail-closed 的机器产品。它也能从明确的 repository、source、symbol 和 tsconfig 输入即时派生一份有界、只读的 TypeScript outbound context。AI host 可以使用这些产品，而不把模型推断当作 repository truth。
 
 大多数最终用户不需要直接调用 `nimicoding`。当前主要 integration surface 是已文档化的 CLI 及其 purpose-specific JSON 产品。Nimi Coding 不是 AI agent、planner、代码生成器、审批 workflow 或万能规范语言。
 
@@ -19,6 +19,8 @@ Nimi Coding 把这些问题变成显式产品语义：
 | 多份文档看起来都像 authority | 一个封闭的 canonical authority 边界 |
 | 路径和 heading 发生变化 | 与文件和顺序无关的稳定 logical unit ID |
 | 搜索产生噪声或被截断的上下文 | 有界 discovery、exact query、declared context 和 graph 产品 |
+| 选定 TypeScript symbol 后仍需宽泛读取文件 | 一份有显式预算的 root-direct outbound code-context projection |
+| Authority-to-code 链接依赖名称或邻近文本猜测 | 可选的 exact authored marker 与确定性双向查询 |
 | Semantic hard cut 在 declared relations 之外留下 unchanged survivors | 基于 caller-selected exact owner/scope/term/relation/Definition channels 的 change-derived recall |
 | 模型无法精确引用规则来源 | 字段级和关系级的 portable SourceMap location |
 | 文本 diff 掩盖真实语义变化 | Stable-ID semantic diff 和 declared impact obligations |
@@ -60,9 +62,17 @@ AI host · 第三方扩展 · CI · future editor/UI surfaces
 | Change intelligence | Stable-ID semantic diff、change-derived active-survivor recall 和 relation-derived impact obligations | Candidate completeness 只覆盖显式 channels；impact 不接受 disposition 或 completion state |
 | Deterministic audit | Project-owned graph verifier 与 exact lexical invariant bindings，输出 JSON 和 SARIF 2.1.0 | 只做大小写敏感的 exact token/phrase 检查；不做 synonym、embedding 或自然语言矛盾推断 |
 | Git-aware review | Immutable base commit 加 exact、race-checked current worktree snapshot，并复用 compile/diff/impact/audit | 只读；business semantics 与 implementation conformance 固定为 `not_evaluated` |
+| TypeScript code context | Root declaration source、root-direct static bindings、portable declaration loci 和符合条件的 target source slices | 明确的 `.ts`/`.tsx` root 与 tsconfig、TypeScript 5.9.3、仅 outbound；不承诺 locating、inbound impact、runtime dispatch 或 task completeness |
+| 显式 code-authority 链接 | 对 Git tracked 当前 `.ts`、`.tsx`、`.go` 源码中的可选 exact marker 提供 transient Authority→Code、Code→Authority 和 lifecycle audit | 只声明 marker location；不声明 declaration ownership、annotation coverage、implementation conformance 或未标注 legacy detection |
 
 当前 Nimi-realm 验证 corpus 包含 33 个 canonical containers、2,212 个 authority units 和 2,159 条 authored relations。这些数字证明了真实大型 corpus replay，不是 package 上限，也不代表 grammar 已覆盖所有领域。
 
+## 使用 0.6 code surface
+
+`start` 会把 package 管理的指导写入 `AGENTS.md` 和 `CLAUDE.md` 的 marked blocks。对于已有安装，`doctor` 会诊断这些指导及 compact methodology projection 的 drift，`sync --apply` 则恢复当前 package 的精确 projections，同时保留 managed blocks 之外的宿主文本。因此，遵守 repository instructions 的 AI host 可以知道何时按需调用 `code authority` 或 `code context`，以及何时只在发生变更、受 authority 约束的功能中，为少数关键语义 owner 添加 `nimi-authority` marker。
+
+这是一种基于 instruction 的集成，不是自动执行层。Nimi Coding 不安装 hook 或 daemon，不拦截 task，不要求固定 preflight，也不拥有 task 或 completion state。是否需要查询由 host 根据当前 coding task 决定。`code authority` 只召回显式 marker 和当前 authority lifecycle；`code context` 只返回 admitted root-direct TypeScript projection。两者都不证明 conformance，不替代 affected build/tests，也不评价未标注代码。
+
 ## 五分钟接入
 
 安装并初始化：
@@ -74,6 +84,8 @@ pnpm exec nimicoding start --yes
 
 `start` 创建紧凑的 AI-visible authoring guide、`AGENTS.md`/`CLAUDE.md` 中的 managed instruction blocks，以及 ignored `.nimi/local/` root。它不会生成产品语义，也不会替项目创建 `.nimi/spec`。
 
+`pnpm exec nimicoding` 是受支持的宿主调用方式：应从仓库根目录执行，使自动化解析到项目锁定的本地 package。既不要求全局 `PATH` 中存在 `nimicoding`，也不能用它判断 CLI 是否可用。
+
 创建一个完整 canonical source，例如 `.nimi/spec/checkout.authority.yaml`：
 
 ```yaml
@@ -163,7 +175,7 @@ pnpm exec nimicoding authority review . \
   --json
 ```
 
-这个例子假设 repository 已经拥有合法 verifier bindings，并且 `origin/main` 能解析到包含 `.nimi/spec` 的 commit。`start` 刻意不会创建这些项目语义或 governance files。
+这个例子假设 repository 已经拥有合法 verifier bindings，并且 `origin/main` 能解析到包含 `.nimi/spec` 的 commit。`start` 刻意不会创建这些项目语义或 policy files。
 
 Base ref 在开始时只解析一次并固定为 full commit OID。Base `.nimi/spec` tree 从 Git objects 读取；完整 current `.nimi/spec` filesystem tree 包含 tracked unchanged files、edits、deletions、untracked files 和 unsupported entries。Capture race、missing object、invalid corpus、malformed binding 或 budget 不足都会拒绝结果，而不是发布混合分析。该命令不会 checkout、stash、reset、stage、commit，也不管理 PR。
 
@@ -203,7 +215,7 @@ Diff、review 与 change-derived recall 复用 per-invocation immutable compiler
 | Semantic change | File diff 和 generated drift 占主导 | Stable-ID semantic diff；rename/regroup/format-only 可为 semantic zero | Prose 多为 line diff；专业格式可能有优秀 domain diff |
 | Impact 与 audit | Project scripts、maps 和团队知识共同决定 | Declared relation impact 加 configured graph 与 exact lexical findings | Build graph、CODEOWNERS、linters 和 tests 很强但分散 |
 | Git review | 没有统一 exact authority snapshot product | Immutable-base、race-checked worktree review | 通常是 Git diff 加多个独立 format-specific checks |
-| Spec-to-code | Direct paths 很细，但可能 stale | Authority core 当前不建模这一关系 | Codegen、type checking 和 contract tests 可能明显更强 |
+| Spec-to-code | Direct paths 很细，但可能 stale | Authority core 不保存 mapping；可选 exact code marker 只提供 authored locating，未标注代码与 conformance 均保持 `not_evaluated` | Codegen、type checking 和 contract tests 可能明显更强 |
 | Executable conformance | 部分 custom scripts 验证具体项目事实 | Review 显式固定为 `not_evaluated` | 高质量 tests 和 executable contracts 最强 |
 | 生态 | 高度 project-specific | 有稳定 CLI/JSON products，但还没有 public JS SDK 或模型/tool 标准 | OpenAPI/Schema/test 生态与第三方互操作最成熟 |
 | Authoring 成本 | 多种表示和 generators 成本高 | 必须维护 ID、owner、scope、lifecycle 和 relation | 探索期最低；corpus 扩大后治理成本上升 |
@@ -218,7 +230,7 @@ Diff、review 与 change-derived recall 复用 per-invocation immutable compiler
 必须始终区分三层产品事实：
 
 1. **当前已经很强：** stable identity、fail-closed admission、exact SourceMap、authored graph navigation、bounded machine products、semantic diff 和 exact Git review。
-2. **已经改善但仍不完整：** 为人/AI conflict review 定位和追踪 exact inputs、task-context assembly、owner/scope accountability 和 spec-to-code traceability；矛盾判定本身不是 deterministic product。
+2. **已经改善但仍不完整：** 可选 authored marker lookup 和 bounded TypeScript outbound context 减少 implementation navigation；完整 task context、未标注代码和 conformance 仍不评价。矛盾判定本身不是 deterministic product。
 3. **刻意没有解决：** 通用业务语义完备性、自动 authority selection、可执行 code conformance、模型推理和 AI workflow orchestration。
 
 如果 Nimi Coding 标准化的是 authority protocol，而不是试图吞并所有领域语言，它的长期上限很高。Model-native 生态可以训练 AI：先 discover 再猜测、解析 exact ID、区分 authored fact 与 inference、尊重 refusal 与窄作用域 status，并在编辑后主动请求有界分析。但 deterministic runtime product 必须继续作为 oracle；模型熟悉 Nimi Coding 不能替代 admission 或项目真实的 tests 和 gates。
@@ -237,25 +249,14 @@ Diff、review 与 change-derived recall 复用 per-invocation immutable compiler
 - Raw AuthorityIR、SourceMap internals 和 compiler implementation 都是 package-private。当前没有 public JavaScript API（`exports` 为空）。
 - `.nimi/local/**` 是 derived/local output，永远不是 product authority。
 
-## Future roadmap
-
-Roadmap 当前暂停在已经验证的 baseline。以下是 future candidate lanes，不代表 implementation authorization、release promise 或隐含顺序。未来每次迭代应只选择一个真实 adopter journey。
-
-| Candidate lane | 目标产品 | Entry condition |
-| --- | --- | --- |
-| Stateless AI tool adapter | 在现有 bounded JSON products 上提供 typed tools，可采用 MCP 或 extension API | 真实 host integration 证明直接调用 CLI 不足 |
-| Read-only unit/code locator | 精确的 project-declared unit → declaration/test/gate binding 和反向查询 | 真实 implementation-alignment journey 证明 binding 稳定；不加入执行或 conformance status |
-| D2 IDE/LSP | Live diagnostics、exact-ID navigation/completion、full-snapshot unsaved-buffer overlay | 持续 editor journey 足以支持独立 delivery unit |
-| D3 local Studio | Read-only unit/graph/diff/impact/audit exploration | 先验证多个真实 review/exploration journeys |
-| D4 external semantic candidates | 带 provenance 和 abstention 的 model/embedding/reranking candidates | 在 owner-approved task corpus 上量化 lexical/graph 不足 |
-| E1 multi-repository Atlas | Visibility-filtered canonical repository snapshot composition | Ecosystem repositories、identity、visibility、ownership 和 workspace membership 都已明确 |
+## Future work
 
-以下工作必须独立、按条件进入：
+0.6 有意停在当前 request-local products，不暗示下一阶段。后续迭代应从一个真实 adopter failure 开始，并且只增加解决它所需的最小机制：
 
-- Structured Definitions、replacement DAG、owner/scope registry 或 public library API，必须先证明真实 authoring/query/consumer loss。
-- Storage、SQLite、cache 或 incremental compilation，必须先有真实 workload 违反预先声明的 SLO，并由 profiling 证明瓶颈来自 repeated parse/index/join。
-- Version bump、tag、publish、ecosystem activation 和 release compatibility 都属于独立 release decision。
-- AI planning、delegation、execution、approval、task state、model/provider orchestration 和 inferred model findings 不属于 core package。
+- 只有真实使用证明直接调用 CLI 不足时，才增加 typed host adapter。
+- 只有持续的 editor journey 确实需要时，才增加 unsaved-buffer 支持。
+- 只有实测使用证明当前 transient exact products 无法解决具体损失时，才增加 storage、semantic retrieval 或 multi-repository composition。
+- AI planning、delegation、execution、approval、task state、model/provider orchestration、implementation conformance 和 completion tracking 继续位于 core package 之外。
 
 ## Command reference
 
@@ -268,8 +269,8 @@ Roadmap 当前暂停在已经验证的 baseline。以下是 future candidate lan
 | Navigate | `authority refs`、`authority path`、`authority subgraph` |
 | Analyze 和 review | `authority audit`、`authority diff`、`authority change-candidates`、`authority impact`、`authority review` |
 | 校验词法 anchors | `authority anchors` |
+| 读取 implementation context 与显式链接 | `code context`、`code authority` |
 | Project lifecycle | `start`、`sync`、`doctor`、`clear` |
-| 可选 L3 repository governance | `validate-ai-governance` |
 
 <details>
 <summary>完整 authority command syntax</summary>
@@ -297,24 +298,48 @@ nimicoding authority review <repository-path> --base <git-ref> --bindings <file>
 
 </details>
 
+<details>
+<summary>显式 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
+```
+
+Marker 是可选的 exact authored link。命令编译 repository 的完整 canonical `.nimi/spec`，一次扫描所选 Git tracked 当前文件系统源码范围，并返回一个完整 compact JSON result，否则拒绝。`nimi-deprecated` 记录开发者的显式判断并由 audit 报告；工具不推断该判断，也不证明 marker pairing、declaration ownership、conformance 或 hard-cut completion。未标注代码仍然合法并保持 `not_evaluated`。命令不写入 index、cache、scope binding、report 或 task state。
+
+</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
+```
+
+该命令读取当前文件系统，并向 stdout 写入一个 compact JSON response。`completed` 只覆盖封闭的 root-direct static-binding policy；`partial` 返回首个 output-budget frontier；`refused` 不包含可用 context product。命令不会编辑 repository，也不会选择、运行或保存 verification。
+
+</details>
+
 Relation types 是 closed set `applies_to,supersedes` 的非空、无重复 subset；discovery relation preview 必须同时提供 direction、relation types 和 edge budget。
 
 <details>
-<summary>Project lifecycle、governance 和 global syntax</summary>
+<summary>Project lifecycle 和 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 是 `--lang en|zh`、`--color` 和 `--no-color`。
 
 </details>
 
-Projection ownership 是精确的：`start`/`sync` 只拥有其已文档化的 managed paths 和 marked instruction blocks。Projection sync 不检查或修改这些 exact managed surfaces 之外的 files。可选 `validate-ai-governance` 与 authority admission、host task execution 保持分离。
+Projection ownership 是精确的：`start`/`sync` 只拥有其已文档化的 managed paths 和 marked instruction blocks。Projection sync 不检查或修改这些 exact managed surfaces 之外的 files。Code queries 是 request-local 的，不参与 authority admission 或 host task execution。
 
 ## Development
 

package/cli/commands/clear.mjs

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import process from "node:process";
 
+import { PROJECT_LOCAL_CLI_INVOCATION } from "../constants.mjs";
 import {
   previewBootstrapRemoval,
   previewEntrypointRemoval,
@@ -177,8 +178,8 @@ ${styleLabel(localize("What You Should Review Next:", "你下一步应该检查
     "如果你想完整移除项目本地 AI truth，请手动检查 .nimi/spec/** 和本地产物。",
   )}
   - ${localize(
-    "If you want nimicoding again later, run `nimicoding start`.",
-    "如果以后还要重新接入 nimicoding，请运行 `nimicoding start`。",
+    `If you want nimicoding again later, run \`${PROJECT_LOCAL_CLI_INVOCATION} start\`.`,
+    `如果以后还要重新接入 nimicoding，请运行 \`${PROJECT_LOCAL_CLI_INVOCATION} start\`。`,
   )}
 `);
 

package/cli/commands/code.mjs

@@ -0,0 +1,225 @@
+import { Buffer } from "node:buffer";
+import { queryCodeAuthority, CodeAuthorityFailure } from "../lib/code/authority-annotations.mjs";
+import {
+  completedCodeAuthorityResponse,
+  MIN_CODE_AUTHORITY_BYTES,
+  refusedCodeAuthorityResponse,
+  renderCodeAuthorityResponse,
+  serializeCodeAuthorityResponse,
+} from "../lib/code/authority-annotation-response.mjs";
+import { contextForTypeScript, CodeContextFailure } from "../lib/code/context.mjs";
+import {
+  MIN_CODE_CONTEXT_BYTES,
+  refusedCodeResponse,
+  renderContextResponse,
+  serializeCodeResponse,
+} from "../lib/code/response.mjs";
+
+export const CODE_CONTEXT_USAGE = "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";
+export const CODE_AUTHORITY_USAGE = "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";
+export const CODE_COMMAND_USAGE = [CODE_CONTEXT_USAGE, CODE_AUTHORITY_USAGE];
+
+const GLOBAL_FLAG_OPTIONS = new Set(["--color", "--no-color"]);
+const CODE_OPTIONS = new Set(["--repo", "--symbol", "--tsconfig", "--max-bytes"]);
+const CODE_AUTHORITY_VALUE_OPTIONS = new Set(["--repo", "--authority", "--source", "--max-files", "--max-bytes"]);
+const SUPPORTED_LANGUAGES = new Set(["en", "zh"]);
+
+function writeResponse(response) {
+  process.stdout.write(serializeCodeResponse(response));
+}
+
+function writeRefusal(code, message, exitCode) {
+  writeResponse(refusedCodeResponse(code, message));
+  return exitCode;
+}
+
+function writeAuthorityResponse(response) {
+  process.stdout.write(serializeCodeAuthorityResponse(response));
+}
+
+function writeAuthorityRefusal(code, message, exitCode) {
+  writeAuthorityResponse(refusedCodeAuthorityResponse(code, message));
+  return exitCode;
+}
+
+export function classifyCodeInvocation(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument) || argument.startsWith("--lang=")) continue;
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (value !== undefined && !value.startsWith("--")) index += 1;
+      continue;
+    }
+    return argument === "code" ? index : null;
+  }
+  return null;
+}
+
+function parseLeadingGlobals(args, commandIndex) {
+  for (let index = 0; index < commandIndex; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return false;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return false;
+      index += 1;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+function parseContextArguments(args) {
+  if (args[0] !== "context") return null;
+  const positional = [];
+  const options = new Map();
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return null;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return null;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--")) {
+      if (!CODE_OPTIONS.has(argument) || options.has(argument)) return null;
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) return null;
+      options.set(argument, value);
+      index += 1;
+      continue;
+    }
+    positional.push(argument);
+  }
+  if (positional.length !== 1 || options.size !== CODE_OPTIONS.size) return null;
+  const maxBytesText = options.get("--max-bytes");
+  if (!/^(?:0|[1-9][0-9]*)$/u.test(maxBytesText)) return null;
+  const maxBytes = Number(maxBytesText);
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < MIN_CODE_CONTEXT_BYTES) return null;
+  const symbol = options.get("--symbol");
+  if (!/^[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*$/u.test(symbol)) return null;
+  return {
+    source: positional[0],
+    repository: options.get("--repo"),
+    symbol,
+    tsconfig: options.get("--tsconfig"),
+    maxBytes,
+  };
+}
+
+function parseAuthorityArguments(args) {
+  if (args[0] !== "authority") return null;
+  const options = new Map();
+  let audit = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index];
+    if (GLOBAL_FLAG_OPTIONS.has(argument)) continue;
+    if (argument.startsWith("--lang=")) {
+      if (!SUPPORTED_LANGUAGES.has(argument.slice("--lang=".length))) return null;
+      continue;
+    }
+    if (argument === "--lang") {
+      const value = args[index + 1];
+      if (!SUPPORTED_LANGUAGES.has(value)) return null;
+      index += 1;
+      continue;
+    }
+    if (argument === "--audit") {
+      if (audit) return null;
+      audit = true;
+      continue;
+    }
+    if (!CODE_AUTHORITY_VALUE_OPTIONS.has(argument) || options.has(argument)) return null;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return null;
+    options.set(argument, value);
+    index += 1;
+  }
+  if (!options.has("--repo") || !options.has("--max-files") || !options.has("--max-bytes")) return null;
+  const selectors = Number(options.has("--authority")) + Number(options.has("--source")) + Number(audit);
+  if (selectors !== 1) return null;
+  const maxFilesText = options.get("--max-files");
+  const maxBytesText = options.get("--max-bytes");
+  if (!/^[1-9][0-9]*$/u.test(maxFilesText) || !/^(?:0|[1-9][0-9]*)$/u.test(maxBytesText)) return null;
+  const maxFiles = Number(maxFilesText);
+  const maxBytes = Number(maxBytesText);
+  if (!Number.isSafeInteger(maxFiles) || !Number.isSafeInteger(maxBytes) || maxBytes < MIN_CODE_AUTHORITY_BYTES) return null;
+  const selector = options.has("--authority")
+    ? { kind: "authority", id: options.get("--authority") }
+    : options.has("--source")
+      ? { kind: "source", path: options.get("--source") }
+      : { kind: "audit" };
+  return { repository: options.get("--repo"), selector, maxFiles, maxBytes };
+}
+
+async function runAuthorityInvocation(args) {
+  const parsed = parseAuthorityArguments(args);
+  if (parsed === null) return writeAuthorityRefusal("CODE_USAGE", "invalid code authority command arguments", 2);
+  try {
+    const result = await queryCodeAuthority(parsed);
+    const response = completedCodeAuthorityResponse(result);
+    const rendered = renderCodeAuthorityResponse(response, parsed.maxBytes);
+    if (rendered === null) {
+      const refusal = serializeCodeAuthorityResponse(refusedCodeAuthorityResponse(
+        "CODE_AUTHORITY_OUTPUT_BUDGET",
+        "max-bytes cannot contain the complete code authority response",
+      ));
+      if (Buffer.byteLength(refusal, "utf8") > parsed.maxBytes) {
+        throw new Error("minimum code authority response budget cannot contain its refusal envelope");
+      }
+      process.stdout.write(refusal);
+      return 1;
+    }
+    process.stdout.write(rendered);
+    return response.status === "findings" ? 1 : 0;
+  } catch (error) {
+    if (error instanceof CodeAuthorityFailure) {
+      return writeAuthorityRefusal(error.code, error.message, error.exitCode);
+    }
+    return writeAuthorityRefusal("CODE_AUTHORITY_INTERNAL", "code authority query failed unexpectedly", 2);
+  }
+}
+
+export async function runCodeInvocation(args, commandIndex) {
+  const operation = args[commandIndex + 1];
+  if (!parseLeadingGlobals(args, commandIndex)) {
+    return operation === "authority"
+      ? writeAuthorityRefusal("CODE_USAGE", "invalid code authority command arguments", 2)
+      : writeRefusal("CODE_USAGE", "invalid code command arguments", 2);
+  }
+  if (operation === "authority") return runAuthorityInvocation(args.slice(commandIndex + 1));
+  const parsed = parseContextArguments(args.slice(commandIndex + 1));
+  if (parsed === null) return writeRefusal("CODE_USAGE", "invalid code command arguments", 2);
+  try {
+    const { maxBytes, ...request } = parsed;
+    const { scope, projection } = await contextForTypeScript(request);
+    const rendered = renderContextResponse({ scope, projection, maxBytes });
+    if (rendered === null) {
+      const response = serializeCodeResponse(refusedCodeResponse(
+        "CODE_OUTPUT_BUDGET",
+        "max-bytes cannot contain the mandatory code context response",
+      ));
+      if (Buffer.byteLength(response, "utf8") > maxBytes) {
+        throw new Error("minimum code response budget cannot contain its refusal envelope");
+      }
+      process.stdout.write(response);
+      return 1;
+    }
+    process.stdout.write(rendered.text);
+    return 0;
+  } catch (error) {
+    if (error instanceof CodeContextFailure) return writeRefusal(error.code, error.message, 2);
+    return writeRefusal("CODE_INTERNAL", "code context failed unexpectedly", 2);
+  }
+}

package/cli/commands/start.mjs

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import { PROJECT_LOCAL_CLI_INVOCATION } from "../constants.mjs";
 import {
   integrateEntrypoints,
   pathExists,
@@ -65,8 +66,8 @@ export async function runStart(args) {
     entrypoints,
     next: [
       "Author project-owned canonical authority under .nimi/spec using only *.authority.yaml or *.authority.md.",
-      "Run nimicoding authority fmt on each changed authority file.",
-      "Run nimicoding authority check .nimi/spec on the complete canonical root.",
+      `Run ${PROJECT_LOCAL_CLI_INVOCATION} authority fmt on each changed authority file.`,
+      `Run ${PROJECT_LOCAL_CLI_INVOCATION} authority check .nimi/spec on the complete canonical root.`,
     ],
   };