@nimiplatform/nimi-coding 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/CODE_OF_CONDUCT.md +28 -0
  3. package/CONTRIBUTING.md +45 -0
  4. package/README.md +371 -343
  5. package/README.zh-CN.md +307 -0
  6. package/SECURITY.md +26 -0
  7. package/cli/constants.mjs +1 -1
  8. package/config/bootstrap.yaml +1 -1
  9. package/contracts/table-family.schema.yaml +7 -0
  10. package/package.json +15 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@nimiplatform/nimi-coding` are tracked here.
4
+
5
+ This project follows semantic versioning for published npm releases.
6
+
7
+ ## 0.2.1
8
+
9
+ - Added the `gate_registry` table family for product-owned release gate
10
+ registries that are not closed enums or generic product catalogs.
11
+
12
+ ## 0.2.0
13
+
14
+ - Split Nimi Coding into a standalone public package.
15
+ - Published the `nimicoding` CLI boundary for bootstrap, validation, handoff,
16
+ local closeout, topic lifecycle, sweep audit, sweep design, and high-risk
17
+ execution gates.
18
+ - Kept runtime execution, scheduling, notifications, provider invocation, and
19
+ self-hosted methodology execution outside the package boundary.
package/CODE_OF_CONDUCT.md ADDED
@@ -0,0 +1,28 @@
1
+ # Code Of Conduct
2
+
3
+ Nimi Coding follows the Nimi project expectation for direct, respectful, and
4
+ technical collaboration.
5
+
6
+ ## Expected Behavior
7
+
8
+ - Keep discussion focused on the work and its user impact.
9
+ - Challenge technical claims with evidence and concrete alternatives.
10
+ - Assume maintainers and contributors are trying to preserve project quality.
11
+ - Respect scope boundaries, especially around security reports and private
12
+ vulnerability handling.
13
+
14
+ ## Unacceptable Behavior
15
+
16
+ - Harassment, threats, or personal attacks.
17
+ - Publishing private security details outside the coordinated disclosure path.
18
+ - Repeatedly derailing issues or pull requests away from the stated technical
19
+ topic.
20
+ - Spam, impersonation, or knowingly misleading claims about project authority.
21
+
22
+ ## Enforcement
23
+
24
+ Maintainers may edit, hide, or remove comments; close issues; block users; or
25
+ restrict participation when behavior makes collaboration unsafe or unproductive.
26
+
27
+ Report conduct concerns privately through `security@nimi.ai` if they involve
28
+ security-sensitive material. Otherwise, use the repository maintainer channels.
package/CONTRIBUTING.md ADDED
@@ -0,0 +1,45 @@
1
+ # Contributing
2
+
3
+ Thanks for taking the time to improve Nimi Coding.
4
+
5
+ ## Project Boundary
6
+
7
+ This repository is the standalone `@nimiplatform/nimi-coding` package. Package
8
+ source lives directly under `config/**`, `contracts/**`, `methodology/**`, and
9
+ `spec/**`. Adopted projects receive `.nimi/**` projections at bootstrap time.
10
+
11
+ Do not add provider execution, scheduler ownership, notification backends,
12
+ packet-bound runtime orchestration, or self-hosted methodology execution unless
13
+ the active package contract explicitly admits that redesign.
14
+
15
+ ## Development Setup
16
+
17
+ ```bash
18
+ pnpm install
19
+ pnpm test
20
+ pnpm check:pack
21
+ ```
22
+
23
+ Use `pnpm check:ci` before larger pull requests. It runs tests, npm pack
24
+ dry-run, and CLI smoke checks.
25
+
26
+ ## Pull Request Expectations
27
+
28
+ - Keep changes scoped to one problem.
29
+ - Read existing files before editing.
30
+ - Prefer editing existing source over replacing whole files.
31
+ - Add or update focused tests for behavior changes.
32
+ - Update README or contract docs when user-visible behavior changes.
33
+ - Do not commit local `.nimi/local/**`, `.nimi/cache/**`, `.nimi/topics/**`, or
34
+ other generated operational artifacts.
35
+
36
+ ## Commit Sign-Off
37
+
38
+ This project accepts signed-off commits:
39
+
40
+ ```bash
41
+ git commit -s
42
+ ```
43
+
44
+ The sign-off certifies that you have the right to submit the contribution under
45
+ the project's license.
package/README.md CHANGED
@@ -1,347 +1,375 @@
1
1
  # @nimiplatform/nimi-coding
2
2
 
3
- `@nimiplatform/nimi-coding` is the standalone host-agnostic boundary package
4
- for the Nimi Coding methodology.
5
-
6
- The product goal is to let arbitrary projects install a reusable AI coding
7
- governance toolkit, bootstrap a project-local `.nimi/**` layer, and then use
8
- AI-native authority, packet, and acceptance discipline for high-risk work.
9
-
10
- ## Primary Path
11
-
12
- The primary `nimicoding` path is for an ordinary project with mixed inputs:
13
-
14
- 1. gather code/docs/structure/human notes
15
- 2. hand off `spec_reconstruction` to an external host
16
- 3. generate a canonical tree under `/.nimi/spec/**`
17
- 4. run `validate-spec-tree`
18
- 5. run `validate-spec-audit`
19
- 6. close out reconstruction
20
- 7. hand off `doc_spec_audit` and close it out locally
21
-
22
- `blueprint-audit` and benchmark parity remain available, but they are
23
- support-only package fixtures. They do not define default reconstruction
24
- completion for a host project.
25
-
26
- In a host project, `/.nimi/spec/**` becomes product authority only after that
27
- project admits or reconstructs it. `nimicoding` provides the CLI, injected
28
- `.nimi/{config,contracts,methodology}/**` contracts, and validators; it does
29
- not make a host read package source paths directly.
30
-
31
- ## Current Status
32
-
33
- This repository is boundary-complete for its intended standalone scope.
34
-
35
- Its completed standalone scope is:
36
-
37
- - package identity
38
- - repository foundation
39
- - initial AI-native methodology seed
40
- - package-owned support profile source for future governance slices
41
- - machine-readable reconstruction, doc-spec-audit, and high-risk execution result contracts
42
- - package-owned canonical high-risk admission schema contract
43
- - seed-only high-risk execution schemas for packet, orchestration-state, prompt, worker-output, and acceptance
44
- - vendor-neutral external host-profile seed
45
- - package-owned external host compatibility contract seed
46
- - host-adapter seed for constrained external execution-host interop
47
- - package-owned admitted host-profile overlay seed for `oh_my_codex`
48
- - package-owned external execution artifact landing-path contract seed
49
- - vendor-neutral external delegated skill runtime contract seed
50
- - vendor-neutral delegated skill installer seed
51
- - fail-closed delegated skill installer result-contract seed
52
- - local-only installer operational evidence-home seed
53
- - fail-closed collapsed installer summary projection lifecycle-contract seed
54
- - package-owned bootstrap source under `config/**`, `contracts/**`, `methodology/**`, and `spec/**`
55
- - a bounded standalone CLI with staged `start`, validation, handoff, local closeout projection, explicit admission, and mechanical execution-artifact validation
56
- - a host-agnostic semantic + interop boundary for external AI hosts such as OMX, Codex, Claude, Gemini, or another contract-observing host
57
-
58
- It intentionally defers:
59
-
60
- - packet-bound run kernel
61
- - provider-backed execution
62
- - scheduler, notification, and automation backend surfaces
3
+ **English** · [简体中文](README.zh-CN.md)
4
+
5
+ [![npm](https://img.shields.io/npm/v/@nimiplatform/nimi-coding.svg?label=npm)](https://www.npmjs.com/package/@nimiplatform/nimi-coding)
6
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+ [![node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](#requirements)
8
+
9
+ > A **vendor-neutral, AI-native methodology toolkit** for governing
10
+ > high-risk AI-assisted software work. Bootstraps a project-local
11
+ > `.nimi/**` truth surface, ships the `nimicoding` CLI, and turns
12
+ > "AI plausibly finished this" into "the four closure dimensions
13
+ > are evidenced."
14
+
15
+ Reader documentation: <https://docs.nimi.ai/nimicoding>
16
+ npm package: [`@nimiplatform/nimi-coding`](https://www.npmjs.com/package/@nimiplatform/nimi-coding)
17
+
18
+ ---
19
+
20
+ ## Why This Exists
21
+
22
+ AI-assisted implementation routinely produces output that **compiles,
23
+ passes existing tests, looks plausible to a reviewer, and is still
24
+ wrong** about authority, scope, semantics, or product meaning. These
25
+ are not bugs in the conventional sense — they are *closure failures*:
26
+ the work was claimed done in a state where the closure conditions had
27
+ not actually held.
28
+
29
+ A short, non-exhaustive list of failure shapes Nimi Coding is
30
+ designed to catch:
31
+
32
+ - **Stale-doc anchoring** — the assistant follows a document that
33
+ looked authoritative but had drifted from the active spec.
34
+ - **Implicit scope expansion** — the assistant edits an adjacent
35
+ surface "while it's in the file"; ownership silently shifts.
36
+ - **Plausible synthesis** — when authoritative source is missing,
37
+ the assistant invents a coherent answer indistinguishable from a
38
+ real one.
39
+ - **Old-route preservation** — a new route is added alongside the
40
+ old one as "safe migration"; the old route was supposed to be
41
+ deleted.
42
+ - **Build-pass closure** — work declared done because tests run,
43
+ even though consumer-facing behavior is wrong.
44
+ - **Pseudo-success** — a typed contract failure is hidden behind a
45
+ fallback that returns "something" instead of failing closed.
46
+
47
+ Better prompts and better tests do not address this. The loop
48
+ reviewing the AI's output is the same loop that produced it. Nimi
49
+ Coding introduces **structural separation** instead.
50
+
51
+ ## What Nimi Coding Is (And Is Not)
52
+
53
+ Nimi Coding is **not** another AI coding assistant. It does not write
54
+ code, dispatch to a provider, or run an agent loop.
55
+
56
+ It is the **standalone host-agnostic boundary package** that sits as
57
+ a governance layer under whichever AI host you use (Claude, Codex,
58
+ Gemini, OMX, or your own). It ships:
59
+
60
+ - a package-owned **methodology** under `methodology/**`
61
+ - typed **contracts** under `contracts/**`
62
+ - **bootstrap + host profile** config under `config/**`
63
+ - a **bootstrap spec seed** under `spec/**`
64
+ - the **`nimicoding` CLI** for bootstrap, validation, skill handoff,
65
+ local closeout, topic lifecycle, sweep audit, sweep design, and
66
+ high-risk execution gates
67
+ - **host adapter** profile overlays for external AI hosts
68
+
69
+ It deliberately does **not** ship:
70
+
71
+ - a packet-bound run kernel
72
+ - provider-backed AI execution
73
+ - a scheduler
74
+ - notification infrastructure
75
+ - an automation backend
63
76
  - self-hosted methodology execution
64
77
 
65
- ## CLI Status
66
-
67
- This repository now carries a boundary-complete standalone `nimicoding` CLI.
68
-
69
- At the current stage it provides:
70
-
71
- - executable package bin wiring
72
- - help and version output
73
- - a primary `nimicoding start` entrypoint for bootstrap, resume, and next-stage AI task prep
74
- - a conservative `nimicoding clear` entrypoint for removing package-managed setup without deleting project-owned truth
75
- - a bounded `nimicoding doctor`
76
- - an explicit `nimicoding blueprint-audit` equivalence check for comparing a fixture or host blueprint root with the candidate canonical tree under `.nimi/spec`
77
- - surface validators for placement, table-family, projection-edge, guidance-body, domain-admission, and tracked-output admission boundaries
78
- - an explicit `nimicoding handoff` export
79
- - an explicit `nimicoding admit-high-risk-decision` semantic admission surface
80
- - a local-only `nimicoding closeout` projection
81
- - a bounded local-only `nimicoding ingest-high-risk-execution` projection
82
- - a bounded local-only `nimicoding review-high-risk-execution` projection
83
- - a bounded local-only `nimicoding decide-high-risk-execution` projection
84
- - mechanical validators for execution-packet, orchestration-state, prompt, worker-output, and acceptance
85
- - skill-specific result contract seeding for reconstruction, doc/spec audit, and local-only high-risk execution closeout
86
- - seed-only execution contract extraction under `.nimi/contracts/**`
87
- - package-owned bootstrap source projection from `config/**`, `contracts/**`, `methodology/**`, and `spec/**`
88
-
89
- Current `nimicoding start` behavior is intentionally narrow:
90
-
91
- - detect the current project state and continue from the right stage
92
- - create or resume the `.nimi/**` seed by projecting package-owned source into host paths
93
- - seed AI-native spec-reconstruction guidance inside `.nimi/**`
94
- - keep support-only methodology assets package-owned unless a host explicitly opts into them
95
- - seed package-owned machine contracts inside `.nimi/contracts/**`
96
- - seed package-owned execution schemas for future high-risk methodology artifacts without admitting runtime ownership
97
- - seed canonical skill-manifest, host-profile, installer, delegated runtime contract, installer result contract, installer operational evidence home, and external handoff truth inside `.nimi/**`
98
- - seed canonical host-adapter truth inside `.nimi/**` so external execution hosts can be admitted without becoming semantic owners
99
- - seed canonical collapsed installer summary projection lifecycle truth inside `.nimi/**`
100
- - update `.gitignore` for local runtime state
101
- - optionally update `AGENTS.md` and `CLAUDE.md` as a staged confirmation inside `start`
102
- - explain one step at a time, confirm one step at a time, and apply one step at a time in interactive mode
103
- - prepare one authoritative JSON AI task package for `spec_reconstruction` or `doc_spec_audit` when the current project stage requires it
104
- - let the user choose a target host such as Codex, Claude, or oh-my-codex for that next AI task
105
- - print a short paste-ready prompt directly in the terminal during `start` instead of requiring users to open a generated prompt file
106
- - fail closed on unknown CLI options
107
- - validate bootstrap integrity and delegated-runtime posture with `doctor`
108
- - preserve existing truth files rather than overwriting them
109
- - refuse unsupported bootstrap contract versions
110
-
111
- Current `nimicoding clear` behavior is intentionally narrow:
112
-
113
- - remove only managed AI blocks in `AGENTS.md` and `CLAUDE.md`
114
- - remove only package-owned bootstrap files under `.nimi/config/**`, `.nimi/contracts/**`, and `.nimi/methodology/**` when the local file still exactly matches the packaged seed
115
- - preserve locally modified bootstrap files even when they live under those package-owned bootstrap paths
116
- - preserve `.nimi/spec/**`, `.nimi/local/**`, and `.nimi/cache/**`
117
- - avoid deleting project-owned truth or local operational artifacts implicitly
118
-
119
- ## Topic Lifecycle Reports
120
-
121
- Human-authored local report work now uses a topic lifecycle workspace rooted at:
122
-
123
- - `/.nimi/topics/**`
124
-
125
- Canonical topic lifecycle roots are:
126
-
127
- - `proposal`
128
- - `ongoing`
129
- - `pending`
130
- - `closed`
131
-
132
- The primary organization unit is a topic folder:
133
-
134
- - `.nimi/topics/<state>/YYYY-MM-DD-topic-slug/`
135
-
136
- Each topic folder should carry a lightweight `topic.yaml` state record and may
137
- include:
138
-
139
- - `README.md`
140
- - `design.md`
141
- - `preflight.md`
142
- - `waves.md`
143
- - `packet-*.md`
144
- - `closeout.md`
145
-
146
- Topic folder rules:
147
-
148
- - use sortable date-first topic ids: `YYYY-MM-DD-topic-slug`
149
- - express lifecycle by moving the topic folder between `proposal`, `ongoing`,
150
- `pending`, and `closed`
151
- - keep one canonical copy of a topic at a time
152
- - record lifecycle transitions in `topic.yaml`; do not rely on folder moves
153
- alone as the state evidence surface
154
-
155
- Canonical constraints:
156
-
157
- - human-authored topic lifecycle reports must use
158
- `/.nimi/topics/{proposal|ongoing|pending|closed}/<topic-id>/**`
159
- - flat markdown files directly under `/.nimi/topics/` are outside the
160
- admitted methodology model
161
- - `.local/report/**` is not an accepted root for human-authored topic
162
- lifecycle reports; keep it only for execution evidence or machine outputs
163
- - `.local/work/**` is no longer the primary methodology workspace for
164
- human-authored topic execution materials
165
-
166
- Applicability boundary:
167
-
168
- - topic workflow is intentionally heavy and not the default entrypoint for all
169
- engineering work
170
- - use a topic when the work is authority-bearing, high-risk, cross-module,
171
- multi-wave, or likely to need remediation / re-audit discipline
172
- - small low-risk changes should stay on the ordinary non-topic path unless there
173
- is an explicit reason they need topic-level governance
174
-
175
- Development rhythm:
176
-
177
- - a topic is the canonical home for one major iteration line, not a micro
178
- requirement backlog
179
- - waves are the bounded execution unit inside a topic
180
- - entering `ongoing` requires a topic-local `preflight.md` with one selected
181
- next execution target, a bounded stop line, consumed inputs/contexts, expected
182
- closeout checks, and explicit forbidden reopenings
183
- - `pending` is an optional no-active-development state for topics that are not
184
- ready to close: use it when you want to distinguish "waiting on evidence or
185
- an external trigger" from active `ongoing` work, and record explicit reopen
186
- or close criteria instead of leaving that wait implicit
187
- - each wave should own one primary closure goal and end in a bounded result such
188
- as an authority cut, implementation packet, bounded re-audit, or explicit
189
- pause/defer note
190
- - planning-only waves may harden one execution target, but they must not chain
191
- indefinitely; if no bounded closure is reached after a planning wave, pause or
192
- re-preflight instead of opening unbounded new planning waves
193
- - closeout stays layered: context closure, wave closeout, and final topic
194
- closeout are distinct evidence surfaces
195
-
196
- Avoid the older `slug-YYYY-MM-DD.md` shape because it sorts poorly and makes
197
- cross-report navigation harder. Stable machine report artifacts that are meant
198
- to behave like a current snapshot, such as `blueprint-equivalence-audit.json`,
199
- should keep their fixed names.
200
-
201
- ## Canonical Spec Surface Model
202
-
203
- The package seeds the host-local contracts needed to reconstruct and validate a
204
- canonical spec tree without putting package methodology or lifecycle state under
205
- the host product-authority root.
206
-
207
- At this stage:
208
-
209
- - `config/**`, `contracts/**`, `methodology/**`, and `spec/**` are package source for the npm package
210
- - generated host projects receive injected `.nimi/{config,contracts,methodology}/**` projections and own their `.nimi/spec/**` product authority
211
- - `start`, `doctor`, `handoff`, `closeout`, and high-risk gating read host-local `.nimi/**` projections instead of requiring access to package source paths
212
- - `nimicoding blueprint-audit` remains the explicit audit surface for benchmark-vs-canonical equivalence checks; it does not perform routing changes on its own
213
- - canonical spec generation now reads mixed inputs from `.nimi/config/spec-generation-inputs.yaml` and treats any blueprint root as an optional benchmark rather than a universal host assumption
214
- - completed canonical reconstruction now requires structural validity and may carry file-level auditability under `.nimi/local/state/spec-generation/spec-generation-audit.yaml`
215
- - `nimicoding validate-spec-tree` checks canonical tree structure, while `nimicoding validate-spec-audit` checks per-file grounding, inference, and unresolved-gap tracking
216
-
217
- Current `nimicoding doctor` behavior is intentionally narrow:
218
-
219
- - validate that `.nimi/**` bootstrap seed files are present
220
- - validate that `.nimi/local/` and `.nimi/cache/` exist and remain ignored
221
- - validate bootstrap contract compatibility metadata
222
- - validate bootstrap-only and reconstruction-seeded lifecycle markers
223
- - validate cross-contract reference alignment across manifest, handoff, runtime, installer, and host-profile truth
224
- - validate host-adapter boundary truth and adapter selection posture
225
- - validate admitted package-owned adapter profile overlays for named external hosts
226
- - validate the packaged external host compatibility contract
227
- - expose the supported external host posture, examples, and required/forbidden host behavior
228
- - validate skill result-contract alignment
229
- - validate the packaged high-risk execution result contract
230
- - validate the packaged canonical high-risk admission schema contract
231
- - validate the external execution artifact landing-path contract
232
- - validate seed-only high-risk execution schemas under `.nimi/contracts/**`
233
- - validate handoff context-order readiness for an external AI host
234
- - expose the standalone completion profile, status, completed surfaces, deferred execution surfaces, and promoted parity gaps
235
- - expose the generic external-host compatibility posture, admitted named overlay posture, and future-only host-specific surfaces
236
- - validate canonical `.nimi/spec/high-risk-admissions.yaml` record shape against the packaged admission schema contract when present
237
- - fail closed when lifecycle state, canonical tree readiness, and auditability drift apart
238
- - report local `doc_spec_audit` closeout artifact status without promoting it to semantic truth
239
- - emit either human-readable output or machine-readable JSON with `--json`
240
-
241
- Current `nimicoding handoff` behavior is intentionally narrow:
242
-
243
- - require explicit `--skill <skill-id>`
244
- - export an authoritative machine-readable external handoff payload with `--json`
245
- - optionally project a human-readable host briefing with `--prompt`
246
- - remain host-agnostic: Claude, Codex, Gemini, OMX, or another external host may consume the same contract if it respects the declared boundaries
247
- - export the package-owned host compatibility contract ref, supported host posture, supported host examples, and required/forbidden host behavior
248
- - expose whether a generic external host is compatible, whether a named admitted overlay is merely available or currently selected, and which host-specific surfaces remain future-only
249
- - reuse `doctor` validation and fail closed when bootstrap or delegated handoff posture is invalid
250
- - allow `spec_reconstruction` handoff during bootstrap-only mode
251
- - expose selected named adapter overlay metadata when an admitted host profile is selected
252
- - export `resultContractRef` plus skill-specific closeout summary expectations
253
- - export execution schema refs, expected artifact kinds, expected local artifact roots, and external execution summary status for `high_risk_execution`
254
- - refuse `doc_spec_audit` and `high_risk_execution` handoff until the canonical tree under `.nimi/spec` is ready
255
-
256
- Current `nimicoding closeout` behavior is intentionally narrow:
257
-
258
- - require explicit `--skill`, `--outcome`, and `--verified-at`
259
- - optionally import those fields plus an optional contract-validated `summary` from an external JSON payload with `--from`
260
- - project external skill results into a local-only closeout payload
261
- - optionally write the payload under `.nimi/local/handoff-results/` with `--write-local`
262
- - fail closed if a `completed` outcome contradicts the current canonical-tree or audit state
263
- - support contract-validated local-only summary import for `high_risk_execution`
264
- - fail closed if imported high-risk execution refs escape the declared local artifact roots
265
- - fail closed if imported high-risk execution summaries omit refs, drift in shape, or claim an illegal external execution status
266
- - fail closed if imported `summary` content violates the declared skill result contract
267
- - fail closed if an imported JSON summary does not match the current project or required shape
268
- - never promote local closeout artifacts to project semantic truth
269
-
270
- Current `nimicoding admit-high-risk-decision` behavior is intentionally narrow:
271
-
272
- - require explicit `--from <json>` and `--admitted-at <iso8601>`
273
- - accept only `nimicoding.high-risk-decision.v1` payloads with `decisionStatus: manager_decision_recorded`
274
- - derive `topic_id` and `packet_id` from the mechanically valid attached packet
275
- - project canonical admission preview for `.nimi/spec/high-risk-admissions.yaml`
276
- - write tracked semantic truth only when `--write-spec` is given explicitly
277
- - fail closed on malformed decision payloads, malformed admissions truth, or missing packet identity
278
-
279
- Current `nimicoding ingest-high-risk-execution` behavior is intentionally narrow:
280
-
281
- - require explicit `--from <json>` pointing at a local high-risk closeout artifact
282
- - accept only `high_risk_execution` closeout artifacts with `outcome: completed` and `summary.status: candidate_ready`
283
- - mechanically validate the referenced packet, orchestration-state, prompt, and worker-output artifacts using the packaged validators
284
- - require all evidence refs to exist under the declared local artifact roots
285
- - project a local-only ingest payload and optionally write it under `.nimi/local/handoff-results/`
286
- - fail closed on contract drift, root escape, missing artifacts, or invalid worker-output/prompt/schema shape
287
- - never decide semantic acceptance, disposition, or finding judgment
288
-
289
- Current `nimicoding review-high-risk-execution` behavior is intentionally narrow:
290
-
291
- - require explicit `--from <json>` pointing at a local high-risk ingest artifact
292
- - accept only `nimicoding.high-risk-ingest.v1` payloads with `ok: true`
293
- - project a local-only review-ready attachment payload for manager-owned review
294
- - carry attachment refs, ingest validation evidence, and the declared semantic review owner
295
- - fail closed if the ingest payload is malformed, not local-only, or mechanically invalid
296
- - never decide semantic acceptance, disposition, or finding judgment
297
-
298
- Current `nimicoding decide-high-risk-execution` behavior is intentionally narrow:
299
-
300
- - require explicit `--from <json>`, `--acceptance <path>`, and `--verified-at <iso8601>`
301
- - accept only `nimicoding.high-risk-review.v1` payloads with `ok: true`
302
- - require `reviewStatus: ready_for_manager_review`
303
- - mechanically validate the provided acceptance artifact and require an explicit `Disposition:` line
304
- - project a local-only manager decision payload and optionally write it under `.nimi/local/handoff-results/`
305
- - fail closed if the review payload is malformed, not local-only, or points at another project
306
- - never auto-promote the manager decision into canonical semantic truth without explicit admission
307
-
308
- Current mechanical validator behavior is intentionally narrow:
309
-
310
- - require an explicit artifact path for each validator command
311
- - emit machine-readable `validator-cli-result.v1` JSON on both success and refusal
312
- - validate only the package-owned seed contract shape for execution-packet, orchestration-state, prompt, worker-output, and acceptance
313
- - fail closed on missing required sections, malformed YAML, or seed-contract drift
314
- - avoid semantic acceptance, topic orchestration, scheduler ownership, or provider execution claims
315
-
316
- The package now carries package-owned bootstrap source under `config/**`,
317
- `contracts/**`, `methodology/**`, and `spec/**`. `nimicoding start`
318
- projects those files into a host project's `/.nimi/**`
319
- surface at runtime. The package also carries adapter overlays under
320
- `adapters/**/profile.yaml` so external execution hosts such as
321
- `oh-my-codex` can be admitted as constrained bridges instead of semantic
322
- owners while keeping external execution closeout local-only, root-bounded,
323
- and non-semantic until an explicit manager-owned admission writes canonical
324
- summary truth into `.nimi/spec/high-risk-admissions.yaml`.
325
-
326
- Boundary-complete in this package does not mean promoted-runtime parity. The
327
- package-owned source lives directly under `config/**`, `contracts/**`,
328
- `methodology/**`, and `spec/**`. Only generated or adopted host projects use
329
- `.nimi/**`. Standalone does not add `run-*` commands, provider invocation,
330
- scheduler logic, or transport adapters in this cut.
331
-
332
- ## Intended Direction
333
-
334
- The expected future experience is roughly:
335
-
336
- 1. install `@nimiplatform/nimi-coding`
337
- 2. run `nimicoding start`
338
- 3. confirm or accept managed AI entrypoints
339
- 4. let an external AI host use seeded `.nimi/**` reconstruction guidance, manifest, host-profile, installer, delegated runtime contract, installer result contract, collapsed installer summary projection lifecycle contract, installer operational evidence guidance, and the authoritative handoff JSON contract to
340
- reconstruct the project canonical tree
341
- 5. use the methodology for later high-risk work
342
-
343
- ## Development Posture
344
-
345
- This repository is the standalone boundary package. Deferred runtime surfaces
346
- such as packet-bound execution, provider-backed execution, scheduler,
347
- notification, and automation remain outside the packaged scope.
78
+ Runtime ownership stays with an external AI host. The methodology
79
+ and contracts stay portable. You can change AI hosts tomorrow
80
+ without changing the methodology contract.
81
+
82
+ When a host project runs `nimicoding start`, the package-owned
83
+ sources are *projected* into that project's
84
+ `.nimi/{config,contracts,methodology,spec}/**` surface. The adopted
85
+ project then owns its `.nimi/spec/**` product authority. **The
86
+ package does not make a host read package source paths directly** —
87
+ the adopted project always reads its own projected `.nimi/**`.
88
+
89
+ ## The Mental Model
90
+
91
+ Four moves separate Nimi Coding from a checklist:
92
+
93
+ | Move | What it means |
94
+ | --- | --- |
95
+ | **Authority is named** | Every change names where its truth lives (`.nimi/spec/**`), who owns the surface, and what kind of work is happening. |
96
+ | **Execution is packetized** | Implementation is bounded by a frozen packet declaring allowed reads, allowed writes, acceptance invariants, negative tests, stop lines, and reopen conditions — *before* the worker begins. |
97
+ | **Closure is multidimensional** | Four independent closure gates — Authority, Semantic, Consumer, Drift Resistance — must all hold. Three out of four is not closed. |
98
+ | **Roles are separated** | Manager owns wave admission and judgement; Worker owns the packet write set; Auditor performs structural review from a **structurally separate loop** (a different AI session, a different vendor). |
99
+
100
+ See [Four Closures](https://docs.nimi.ai/nimicoding/four-closures) and
101
+ [The Paradigm](https://docs.nimi.ai/nimicoding/the-paradigm) for the
102
+ full framework.
103
+
104
+ ## Who This Is For
105
+
106
+ | Persona | What you get |
107
+ | --- | --- |
108
+ | Solo founder shipping with AI | Team-scale review discipline without a team — route the auditor through a second AI session on the same laptop |
109
+ | Small team (2–5) adopting AI | Structural review redundancy that scales without headcount |
110
+ | OSS maintainer accepting AI-authored PRs | Provable contribution discipline — packet boundaries, typed evidence, four-closure gates |
111
+ | Organization under AI-coding compliance pressure | Audit trail and structured acceptance independent of any single AI vendor |
112
+ | Researcher studying AI engineering practice | Observable methodology corpus over real repository history |
113
+
114
+ If you have ever watched an AI-assisted change look complete to every
115
+ available signal — type checker green, tests green, reviewer
116
+ approved — and turn out to be wrong about authority, scope, or
117
+ product meaning, this package is for you.
118
+
119
+ ## Requirements
120
+
121
+ | Requirement | Version |
122
+ | --- | --- |
123
+ | Node.js | `>=24.0.0` |
124
+ | Package manager (consumer) | npm, pnpm, yarn, or compatible |
125
+ | pnpm (repository development) | `>=10.0.0` |
126
+
127
+ A version-controlled project is recommended — `start` creates files.
128
+
129
+ ## Install
130
+
131
+ In the repository that should receive the `.nimi/**` governance
132
+ layer:
133
+
134
+ ```bash
135
+ npm install --save-dev @nimiplatform/nimi-coding
136
+ # or
137
+ pnpm add -D @nimiplatform/nimi-coding
138
+ ```
139
+
140
+ Check the CLI:
141
+
142
+ ```bash
143
+ npx nimicoding --version
144
+ npx nimicoding --help
145
+ ```
146
+
147
+ ## 5-Minute Minimal Path
148
+
149
+ Most projects should start small. The first successful path is:
150
+
151
+ ```bash
152
+ # 1. Bootstrap .nimi/** in your project root
153
+ npx nimicoding start
154
+
155
+ # 2. Check the bootstrap is healthy
156
+ npx nimicoding doctor --json
157
+
158
+ # 3. Hand off canonical spec reconstruction to your AI host
159
+ npx nimicoding handoff --skill spec_reconstruction --json
160
+
161
+ # 4. After the host consumes that payload and materializes .nimi/spec/**,
162
+ # validate the canonical tree
163
+ npx nimicoding validate-spec-tree .nimi/spec
164
+ npx nimicoding validate-spec-audit
165
+ ```
166
+
167
+ After this, you have a project-local `.nimi/**` truth surface, a
168
+ typed reconstruction of project authority into `.nimi/spec/**`, and
169
+ mechanical validators you can re-run on every change.
170
+
171
+ `handoff` exports an authoritative task payload. It does not call an AI
172
+ provider or run the reconstruction itself; the external host must
173
+ consume the payload, write or return the expected artifacts, and then
174
+ the local validators check the result.
175
+
176
+ You do **not** need to create topics, freeze packets, or run
177
+ high-risk gates for ordinary low-risk changes. Those tools exist for
178
+ authority-bearing, cross-module, multi-wave, or audit-sensitive work.
179
+
180
+ To remove only package-managed bootstrap material from a test
181
+ project (preserves `.nimi/spec/**`, `.nimi/local/**`, `.nimi/cache/**`,
182
+ and locally modified bootstrap files):
183
+
184
+ ```bash
185
+ npx nimicoding clear --yes
186
+ ```
187
+
188
+ ## When You Need More: Topics, Waves, Packets
189
+
190
+ For authority-bearing, high-risk, or cross-module work, escalate to
191
+ the topic lifecycle. A topic groups one strategic change; waves split
192
+ the topic into bounded units of work; each wave freezes a **packet**
193
+ before the worker begins.
194
+
195
+ ```bash
196
+ nimicoding topic create <slug> --justification <text>
197
+ nimicoding topic wave add <topic-id> <wave-id> <slug> \
198
+ --goal <text> --owner-domain <domain>
199
+ nimicoding topic packet freeze <topic-id> --from <draft-path>
200
+ nimicoding handoff --skill high_risk_execution --json
201
+ nimicoding ingest-high-risk-execution --from result.json
202
+ nimicoding review-high-risk-execution --from ingest.json
203
+ nimicoding decide-high-risk-execution --from review.json \
204
+ --acceptance accept.md --verified-at <iso8601>
205
+ ```
206
+
207
+ Each step is bounded by typed validation. Skipping a step or
208
+ smuggling fields through means the CLI refuses (fail closed, no
209
+ exceptions).
210
+
211
+ ## The Four Declared Skills
212
+
213
+ External AI hosts implement these skills; the `handoff` CLI emits a
214
+ machine-readable payload for each:
215
+
216
+ | Skill | Purpose | Required at bootstrap |
217
+ | --- | --- | --- |
218
+ | `spec_reconstruction` | Reconstruct canonical project authority into `.nimi/spec/**` with source basis and unresolved-gap tracking | yes |
219
+ | `doc_spec_audit` | Audit per-file grounding and inference against the canonical tree | yes |
220
+ | `audit_sweep` | Split a target root into auditable chunks and record typed evidence | no |
221
+ | `high_risk_execution` | Execute admitted high-risk packets with typed packet / orchestration / prompt / worker-output / acceptance evidence | no |
222
+
223
+ See [Skills](https://docs.nimi.ai/nimicoding/skills) for contract
224
+ detail.
225
+
226
+ ## CLI Surface
227
+
228
+ Common commands, grouped by entry scenario:
229
+
230
+ ```bash
231
+ # Bootstrap
232
+ nimicoding start
233
+ nimicoding sync --check
234
+ nimicoding doctor --json
235
+ nimicoding clear --yes
236
+
237
+ # Skill handoff and local closeout
238
+ nimicoding handoff --skill <id> --json
239
+ nimicoding closeout --from result.json --write-local
240
+
241
+ # Spec audit
242
+ nimicoding validate-spec-tree .nimi/spec
243
+ nimicoding validate-spec-audit
244
+ nimicoding blueprint-audit
245
+
246
+ # Topic lifecycle
247
+ nimicoding topic create <slug> --justification <text>
248
+ nimicoding topic wave add|select|admit ...
249
+ nimicoding topic packet freeze ...
250
+ nimicoding topic worker dispatch ...
251
+ nimicoding topic result record ...
252
+ nimicoding topic closeout ...
253
+ nimicoding topic true-close-audit ...
254
+ nimicoding topic run-next-step <topic-id> --json
255
+
256
+ # Sweep audit / sweep design
257
+ nimicoding sweep audit plan --root <dir> --json
258
+ nimicoding sweep audit chunk ...
259
+ nimicoding sweep design intake|packet-build|result-ingest|finalize ...
260
+
261
+ # High-risk execution gates
262
+ nimicoding admit-high-risk-decision --from <json> --admitted-at <iso8601>
263
+ nimicoding ingest-high-risk-execution --from <json>
264
+ nimicoding review-high-risk-execution --from <json>
265
+ nimicoding decide-high-risk-execution --from <json> \
266
+ --acceptance <path> --verified-at <iso8601>
267
+
268
+ # Mechanical artifact validators
269
+ nimicoding validate-execution-packet <path>
270
+ nimicoding validate-orchestration-state <path>
271
+ nimicoding validate-prompt <path>
272
+ nimicoding validate-worker-output <path>
273
+ nimicoding validate-acceptance <path>
274
+ ```
275
+
276
+ Conceptual CLI overview:
277
+ <https://docs.nimi.ai/nimicoding/cli>
278
+ Field-level reference:
279
+ <https://docs.nimi.ai/nimicoding/reference/cli-commands>
280
+
281
+ ## How Does This Compare To …
282
+
283
+ | | Cursor / Copilot / Claude Code | Lint / TDD / Code review | Nimi Coding |
284
+ | --- | --- | --- | --- |
285
+ | Writes code | yes | no | **no** |
286
+ | Catches local bugs | partial | yes | n/a |
287
+ | Catches authority drift | no | no | **yes** |
288
+ | Catches consumer-closure failure | no | no | **yes** |
289
+ | Vendor lock-in | yes (per tool) | no | **no — host-agnostic** |
290
+ | Audit trail across AI sessions | chat transcript | PR comments | **typed evidence under `.nimi/**`** |
291
+
292
+ Nimi Coding sits *underneath* the AI host you already use. It is the
293
+ machinery that lets the work AI did graduate from "looks done" to
294
+ "closed across four dimensions, with evidence."
295
+
296
+ ## Repository Map
297
+
298
+ | Path | Purpose |
299
+ | --- | --- |
300
+ | `bin/nimicoding.mjs` | Executable package binary |
301
+ | `cli/**` | CLI implementation |
302
+ | `config/**` | Package-owned bootstrap and host profile source |
303
+ | `contracts/**` | Package-owned machine-readable schemas and contracts |
304
+ | `methodology/**` | Package-owned methodology source (policies) |
305
+ | `spec/**` | Bootstrap spec seed and package scope source |
306
+ | `adapters/**` | External host adapter profile overlays (e.g. `oh-my-codex`) |
307
+ | `test/**` | Node test suite and fixtures |
308
+
309
+ Adopted projects use `.nimi/**` for the projected layer. This
310
+ repository itself keeps the package-owned source directly under
311
+ `config/**`, `contracts/**`, `methodology/**`, and `spec/**`.
312
+
313
+ ## Development
314
+
315
+ ```bash
316
+ pnpm install
317
+ pnpm test # runs the node:test suite (329 tests at 0.2.1)
318
+ pnpm check:pack # npm pack --dry-run
319
+ pnpm check:ci # test + pack + CLI help/version smoke
320
+ ```
321
+
322
+ Local CLI smoke:
323
+
324
+ ```bash
325
+ node ./bin/nimicoding.mjs --version
326
+ node ./bin/nimicoding.mjs --help
327
+ ```
328
+
329
+ Before opening a pull request, read [CONTRIBUTING.md](CONTRIBUTING.md).
330
+ The short version: keep changes scoped, preserve the host-agnostic
331
+ boundary, do not add runtime ownership unless the methodology
332
+ contract is explicitly redesigned, and run the relevant tests before
333
+ claiming the work is done.
334
+
335
+ ## Publishing
336
+
337
+ Releases are tag-driven through GitHub Actions. A `vX.Y.Z` tag
338
+ publishes the matching `package.json` version after tests, dry-run
339
+ packing, and CLI smoke checks pass. The workflow also supports a
340
+ manual dry-run release gate.
341
+
342
+ The package publishes with npm provenance enabled.
343
+
344
+ ## Security
345
+
346
+ Do not disclose vulnerabilities in public GitHub issues. Use a
347
+ private channel:
348
+
349
+ - GitHub private security advisory for
350
+ [`nimiplatform/nimi-coding`](https://github.com/nimiplatform/nimi-coding/security/advisories/new)
351
+ - `security@nimi.ai`
352
+
353
+ See [SECURITY.md](SECURITY.md) for the supported reporting path.
354
+
355
+ ## Documentation
356
+
357
+ Full reader documentation lives at <https://docs.nimi.ai/nimicoding>,
358
+ including:
359
+
360
+ - [The Paradigm](https://docs.nimi.ai/nimicoding/the-paradigm)
361
+ - [Four Closures](https://docs.nimi.ai/nimicoding/four-closures)
362
+ - [False Closure Typology](https://docs.nimi.ai/nimicoding/false-closure-typology)
363
+ - [Forbidden Shortcuts](https://docs.nimi.ai/nimicoding/forbidden-shortcuts)
364
+ - [Role Separation](https://docs.nimi.ai/nimicoding/role-separation)
365
+ - [Topic Lifecycle](https://docs.nimi.ai/nimicoding/topic-lifecycle)
366
+ - [The Package](https://docs.nimi.ai/nimicoding/the-package)
367
+ - [CLI Surface](https://docs.nimi.ai/nimicoding/cli)
368
+ - [Installation](https://docs.nimi.ai/nimicoding/installation)
369
+ - [Adoption Path](https://docs.nimi.ai/nimicoding/adoption-path)
370
+ - [Comparison](https://docs.nimi.ai/nimicoding/comparison)
371
+ - [Walkthrough](https://docs.nimi.ai/nimicoding/walkthrough)
372
+
373
+ ## License
374
+
375
+ MIT. See [LICENSE](LICENSE).
package/README.zh-CN.md ADDED
@@ -0,0 +1,307 @@
1
+ # @nimiplatform/nimi-coding
2
+
3
+ [English](README.md) · **简体中文**
4
+
5
+ [![npm](https://img.shields.io/npm/v/@nimiplatform/nimi-coding.svg?label=npm)](https://www.npmjs.com/package/@nimiplatform/nimi-coding)
6
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+ [![node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](#环境要求)
8
+
9
+ > 一套**厂商中立、AI 原生的方法论工具**（vendor-neutral, AI-native
10
+ > methodology toolkit），专门用于治理高风险的 AI 辅助软件开发。它在项目里
11
+ > 搭建一层 `.nimi/**` 真相面，配套 `nimicoding` CLI，把"AI 看起来做完了"
12
+ > 变成"四个闭合维度都有证据。"
13
+
14
+ 读者文档：<https://docs.nimi.ai/nimicoding>
15
+ npm 包：[`@nimiplatform/nimi-coding`](https://www.npmjs.com/package/@nimiplatform/nimi-coding)
16
+
17
+ ---
18
+
19
+ ## 为什么需要这个项目
20
+
21
+ AI 辅助实现经常会产出**能编译、能跑通现有测试、Reviewer 看着合理、但实际上在权威、范围、语义或产品意义上是错的**代码。这些不是传统意义上的 bug——它们是*闭合失败*（closure failures）：在闭合条件还没真正成立的状态下，工作就被声明为"完成"了。
22
+
23
+ Nimi Coding 专门拦截的几种失败形态（非穷举）：
24
+
25
+ - **过期文档锚定**：模型跟随了一份看似权威、但已经偏离活跃 spec 的文档。
26
+ - **隐式范围扩张**：模型"顺手"改了相邻表面，所有权悄悄发生了转移。
27
+ - **看似合理的捏造**：缺乏权威源时，模型编造一个跟真实答案无法区分的连贯回答。
28
+ - **旧路径保留**：模型"为了安全迁移"在旧路径旁边加了新路径——而旧路径本来应该被删掉。
29
+ - **构建通过即闭合**：因为测试跑过了就宣告完成，但消费方面对的行为是错的。
30
+ - **伪成功**：强类型契约失败被一段返回"某种东西"的回退路径掩盖，没有 fail-closed（失败即关闭）。
31
+
32
+ 更好的 Prompt 和更全的测试都解决不了这个问题。**审查 AI 输出的回路，和产出这个 AI 输出的，是同一个回路。** Nimi Coding 引入的是**结构性的分离**。
33
+
34
+ ## Nimi Coding 是什么（不是什么）
35
+
36
+ Nimi Coding **不是**另一个 AI 写代码工具。它不写代码、不调度 provider、不跑 agent loop。
37
+
38
+ 它是**独立的、host-agnostic 的边界包**（standalone host-agnostic boundary package），作为治理层坐落在你使用的任意 AI host（Claude、Codex、Gemini、OMX 或自建）下面。它交付：
39
+
40
+ - 包内自有的**方法论**源（`methodology/**`）
41
+ - 强类型**契约**（`contracts/**`）
42
+ - **bootstrap + host profile** 配置（`config/**`）
43
+ - **bootstrap spec 种子**（`spec/**`）
44
+ - **`nimicoding` CLI**：用于 bootstrap、校验、skill 握手、本地 closeout、topic 生命周期、sweep audit、sweep design、高风险执行闸门
45
+ - 外部 AI host 的**适配器** profile overlay
46
+
47
+ 它**刻意不**交付：
48
+
49
+ - 一个 packet 绑定的运行内核
50
+ - provider-backed 的 AI 执行
51
+ - 一个调度器
52
+ - 通知基础设施
53
+ - 自动化后端
54
+ - 自托管方法论执行
55
+
56
+ 运行时所有权留在外部 AI host 那里。方法论和契约保持可移植。明天你想换 AI host，方法论合同不需要改。
57
+
58
+ 当一个 host project 跑 `nimicoding start` 时，包内自有的源会被**投影**到该项目的 `.nimi/{config,contracts,methodology,spec}/**`。被采纳的项目随后拥有自己 `.nimi/spec/**` 下的产品权威。**包不会让 host 直接读取包源路径**——被采纳的项目永远读它自己投影出来的 `.nimi/**`。
59
+
60
+ ## 心智模型
61
+
62
+ 让 Nimi Coding 区别于"另一个 checklist"的四个动作：
63
+
64
+ | 动作 | 含义 |
65
+ | --- | --- |
66
+ | **权威被显式命名** | 每次变更都先写清楚真相住在哪里（`.nimi/spec/**`）、表面归谁所有、属于哪一类工作。 |
67
+ | **执行被 packet 化** | 实现被一份开工前冻结的 packet 限定边界——允许的读、允许的写、验收恒定式、负面测试、停止线、重开条件。worker 不允许扩张范围。 |
68
+ | **闭合是多维的** | 四个独立闭合闸门——权威（Authority）、语义（Semantic）、消费方（Consumer，即真实用户/读者/运维有没有真的用上）、抗漂移（Drift Resistance）——必须全部成立。过三缺一不算关闭。 |
69
+ | **角色分离** | Manager 负责切边界和准入；Worker 在 packet 写集合内执行；Auditor 来自**结构上独立的回路**（另一个 AI 会话、另一家厂商）。 |
70
+
71
+ 完整框架见 [Four Closures](https://docs.nimi.ai/nimicoding/four-closures) 与 [The Paradigm](https://docs.nimi.ai/nimicoding/the-paradigm)。
72
+
73
+ ## 适合谁用
74
+
75
+ | 角色 | 收益 |
76
+ | --- | --- |
77
+ | 用 AI 推大项目的独立开发者 | 不需要团队就能拿到团队规模的复核纪律——同一台笔记本起第二个 AI 会话当 auditor |
78
+ | 小团队（2–5 人）引入 AI | 不需要扩招就能拿到结构性的复核冗余 |
79
+ | 接受 AI 辅助 PR 的开源维护者 | 可证的贡献纪律——packet 边界、强类型证据、四闭合闸门 |
80
+ | 有 AI 编程合规压力的工程组织 | 独立于任一 AI 厂商的审计轨迹和结构化验收 |
81
+ | 研究 AI 工程实践的研究者 | 一个可观测的方法论语料库，跑在真实仓库历史上 |
82
+
83
+ 如果你见过 AI 辅助的变更在所有信号上看起来完成了——类型检查绿、测试绿、Reviewer 批了——结果在权威、范围或产品意义上是错的，那这个包就是为你做的。
84
+
85
+ ## 环境要求
86
+
87
+ | 项 | 版本 |
88
+ | --- | --- |
89
+ | Node.js | `>=24.0.0` |
90
+ | 包管理器（消费方） | npm、pnpm、yarn 或兼容工具 |
91
+ | pnpm（仓库开发） | `>=10.0.0` |
92
+
93
+ 建议在版本控制下的项目里使用——`start` 会创建文件。
94
+
95
+ ## 安装
96
+
97
+ 在需要接入 `.nimi/**` 治理层的项目里：
98
+
99
+ ```bash
100
+ npm install --save-dev @nimiplatform/nimi-coding
101
+ # 或
102
+ pnpm add -D @nimiplatform/nimi-coding
103
+ ```
104
+
105
+ 确认 CLI：
106
+
107
+ ```bash
108
+ npx nimicoding --version
109
+ npx nimicoding --help
110
+ ```
111
+
112
+ ## 5 分钟最小路径
113
+
114
+ 大部分项目都应该从小路径开始。第一条跑通的路径是：
115
+
116
+ ```bash
117
+ # 1. 在项目根目录 bootstrap .nimi/**
118
+ npx nimicoding start
119
+
120
+ # 2. 检查 bootstrap 健康
121
+ npx nimicoding doctor --json
122
+
123
+ # 3. 把权威 spec 重建任务握手交给你的 AI host
124
+ npx nimicoding handoff --skill spec_reconstruction --json
125
+
126
+ # 4. host 消费该 payload 并落地 .nimi/spec/** 后，校验权威树
127
+ npx nimicoding validate-spec-tree .nimi/spec
128
+ npx nimicoding validate-spec-audit
129
+ ```
130
+
131
+ 走完这条路径，你会拥有：项目本地的 `.nimi/**` 真相面、一份重建到 `.nimi/spec/**` 的强类型项目权威，以及可以在每次变更上重跑的机械校验器。
132
+
133
+ `handoff` 导出的是权威任务 payload。它不会调用 AI provider，也不会自己执行 reconstruction；外部 host 必须消费 payload，写入或返回预期工件，然后本地校验器检查结果。
134
+
135
+ **普通的低风险改动不需要创建 topic、冻结 packet、跑高风险闸门。** 那些工具是给权威级、跨模块、多 wave 或对审计敏感的工作准备的。
136
+
137
+ 如果想从测试项目里只移除包托管的 bootstrap 内容（保留 `.nimi/spec/**`、`.nimi/local/**`、`.nimi/cache/**` 和被本地修改过的 bootstrap 文件）：
138
+
139
+ ```bash
140
+ npx nimicoding clear --yes
141
+ ```
142
+
143
+ ## 需要进阶时：Topic、Wave、Packet
144
+
145
+ 权威级、高风险或跨模块的工作，升级到 topic 生命周期。Topic 装一次战略性变更；wave 把 topic 拆成有边界的工作单元；每个 wave 在 worker 动手前冻结一份 **packet**。
146
+
147
+ ```bash
148
+ nimicoding topic create <slug> --justification <text>
149
+ nimicoding topic wave add <topic-id> <wave-id> <slug> \
150
+ --goal <text> --owner-domain <domain>
151
+ nimicoding topic packet freeze <topic-id> --from <draft-path>
152
+ nimicoding handoff --skill high_risk_execution --json
153
+ nimicoding ingest-high-risk-execution --from result.json
154
+ nimicoding review-high-risk-execution --from ingest.json
155
+ nimicoding decide-high-risk-execution --from review.json \
156
+ --acceptance accept.md --verified-at <iso8601>
157
+ ```
158
+
159
+ 每一步都被强类型校验约束。跳步或者偷塞字段，CLI 直接拒绝（fail closed，没有例外）。
160
+
161
+ ## 四个声明 Skill
162
+
163
+ 外部 AI host 实现这些 skill；`handoff` CLI 为每一个发出机器可读 payload：
164
+
165
+ | Skill | 用途 | Bootstrap 必需 |
166
+ | --- | --- | --- |
167
+ | `spec_reconstruction` | 把项目权威重建到 `.nimi/spec/**`，带源依据和未决 gap 追踪 | 是 |
168
+ | `doc_spec_audit` | 对照权威树校验每个文件的 grounding 和 inference | 是 |
169
+ | `audit_sweep` | 把目标根切成可审计的 chunk，记录强类型证据 | 否 |
170
+ | `high_risk_execution` | 在准入的高风险 packet 上执行，附带 packet / orchestration / prompt / worker-output / acceptance 强类型证据 | 否 |
171
+
172
+ 契约细节见 [Skills](https://docs.nimi.ai/nimicoding/skills)。
173
+
174
+ ## CLI 总览
175
+
176
+ 按使用场景分组的常用命令：
177
+
178
+ ```bash
179
+ # Bootstrap
180
+ nimicoding start
181
+ nimicoding sync --check
182
+ nimicoding doctor --json
183
+ nimicoding clear --yes
184
+
185
+ # Skill 握手与本地 closeout
186
+ nimicoding handoff --skill <id> --json
187
+ nimicoding closeout --from result.json --write-local
188
+
189
+ # Spec 审计
190
+ nimicoding validate-spec-tree .nimi/spec
191
+ nimicoding validate-spec-audit
192
+ nimicoding blueprint-audit
193
+
194
+ # Topic 生命周期
195
+ nimicoding topic create <slug> --justification <text>
196
+ nimicoding topic wave add|select|admit ...
197
+ nimicoding topic packet freeze ...
198
+ nimicoding topic worker dispatch ...
199
+ nimicoding topic result record ...
200
+ nimicoding topic closeout ...
201
+ nimicoding topic true-close-audit ...
202
+ nimicoding topic run-next-step <topic-id> --json
203
+
204
+ # Sweep audit / sweep design
205
+ nimicoding sweep audit plan --root <dir> --json
206
+ nimicoding sweep audit chunk ...
207
+ nimicoding sweep design intake|packet-build|result-ingest|finalize ...
208
+
209
+ # 高风险执行闸门
210
+ nimicoding admit-high-risk-decision --from <json> --admitted-at <iso8601>
211
+ nimicoding ingest-high-risk-execution --from <json>
212
+ nimicoding review-high-risk-execution --from <json>
213
+ nimicoding decide-high-risk-execution --from <json> \
214
+ --acceptance <path> --verified-at <iso8601>
215
+
216
+ # 机械工件校验器
217
+ nimicoding validate-execution-packet <path>
218
+ nimicoding validate-orchestration-state <path>
219
+ nimicoding validate-prompt <path>
220
+ nimicoding validate-worker-output <path>
221
+ nimicoding validate-acceptance <path>
222
+ ```
223
+
224
+ CLI 概念总览：<https://docs.nimi.ai/nimicoding/cli>
225
+ 字段级 reference：<https://docs.nimi.ai/nimicoding/reference/cli-commands>
226
+
227
+ ## 它和 X 是什么关系
228
+
229
+ | | Cursor / Copilot / Claude Code | Lint / TDD / Code review | Nimi Coding |
230
+ | --- | --- | --- | --- |
231
+ | 写代码 | ✅ | ❌ | **❌** |
232
+ | 抓局部 bug | 部分 | ✅ | n/a |
233
+ | 抓权威漂移 | ❌ | ❌ | **✅** |
234
+ | 抓消费方闭合失败 | ❌ | ❌ | **✅** |
235
+ | 厂商绑定 | 有（按工具） | 无 | **无——host-agnostic** |
236
+ | 跨 AI 会话的审计轨迹 | 聊天记录 | PR 评论 | **`.nimi/**` 下的强类型证据** |
237
+
238
+ Nimi Coding 坐在你已经用的 AI host *底下*。它是让 AI 做完的工作从"看起来完成"晋升到"四维闭合、有证据"的机器装置。
239
+
240
+ ## 仓库结构
241
+
242
+ | 路径 | 用途 |
243
+ | --- | --- |
244
+ | `bin/nimicoding.mjs` | 可执行的包二进制 |
245
+ | `cli/**` | CLI 实现 |
246
+ | `config/**` | 包内自有的 bootstrap 与 host profile 源 |
247
+ | `contracts/**` | 包内自有的机器可读 schema 与契约 |
248
+ | `methodology/**` | 包内自有的方法论源（policy） |
249
+ | `spec/**` | bootstrap spec 种子和包 scope 源 |
250
+ | `adapters/**` | 外部 host 适配器 profile overlay（例如 `oh-my-codex`） |
251
+ | `test/**` | Node 测试套件与 fixture |
252
+
253
+ 被采纳的项目使用 `.nimi/**` 作为投影层。这个仓库自身把包内自有源直接放在 `config/**`、`contracts/**`、`methodology/**`、`spec/**` 下。
254
+
255
+ ## 开发
256
+
257
+ ```bash
258
+ pnpm install
259
+ pnpm test # 跑 node:test 套件（0.2.1 共 329 用例）
260
+ pnpm check:pack # npm pack --dry-run
261
+ pnpm check:ci # test + pack + CLI help/version smoke
262
+ ```
263
+
264
+ 本地 CLI smoke：
265
+
266
+ ```bash
267
+ node ./bin/nimicoding.mjs --version
268
+ node ./bin/nimicoding.mjs --help
269
+ ```
270
+
271
+ 提交 PR 前请读 [CONTRIBUTING.md](CONTRIBUTING.md)。简版要求：改动有边界、守住 host-agnostic 边界、除非方法论合同显式重设计否则不引入运行时所有权、自称完成前跑过相关测试。
272
+
273
+ ## 发布
274
+
275
+ Release 由 tag 触发 GitHub Actions。一个 `vX.Y.Z` tag 在 test、pack dry-run、CLI smoke 都通过后，发布与 `package.json` 版本相匹配的包。Workflow 也支持手动的 dry-run release 闸门。
276
+
277
+ 包以启用 npm provenance 发布。
278
+
279
+ ## 安全
280
+
281
+ 不要在公开 GitHub issue 里披露漏洞。请走私密渠道：
282
+
283
+ - GitHub 私密安全公告：[`nimiplatform/nimi-coding`](https://github.com/nimiplatform/nimi-coding/security/advisories/new)
284
+ - `security@nimi.ai`
285
+
286
+ 支持的上报路径见 [SECURITY.md](SECURITY.md)。
287
+
288
+ ## 文档
289
+
290
+ 完整读者文档：<https://docs.nimi.ai/nimicoding>，包括：
291
+
292
+ - [The Paradigm](https://docs.nimi.ai/nimicoding/the-paradigm)
293
+ - [Four Closures](https://docs.nimi.ai/nimicoding/four-closures)
294
+ - [False Closure Typology](https://docs.nimi.ai/nimicoding/false-closure-typology)
295
+ - [Forbidden Shortcuts](https://docs.nimi.ai/nimicoding/forbidden-shortcuts)
296
+ - [Role Separation](https://docs.nimi.ai/nimicoding/role-separation)
297
+ - [Topic Lifecycle](https://docs.nimi.ai/nimicoding/topic-lifecycle)
298
+ - [The Package](https://docs.nimi.ai/nimicoding/the-package)
299
+ - [CLI Surface](https://docs.nimi.ai/nimicoding/cli)
300
+ - [Installation](https://docs.nimi.ai/nimicoding/installation)
301
+ - [Adoption Path](https://docs.nimi.ai/nimicoding/adoption-path)
302
+ - [Comparison](https://docs.nimi.ai/nimicoding/comparison)
303
+ - [Walkthrough](https://docs.nimi.ai/nimicoding/walkthrough)
304
+
305
+ ## 许可
306
+
307
+ MIT。见 [LICENSE](LICENSE)。
package/SECURITY.md ADDED
@@ -0,0 +1,26 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ Security fixes target the latest published version of
6
+ `@nimiplatform/nimi-coding`.
7
+
8
+ ## Reporting A Vulnerability
9
+
10
+ Do not disclose vulnerabilities in public GitHub issues.
11
+
12
+ Use one of these private channels:
13
+
14
+ - GitHub private security advisory for
15
+ `https://github.com/nimiplatform/nimi-coding/security/advisories/new`
16
+ - `security@nimi.ai`
17
+
18
+ Please include:
19
+
20
+ - affected version or commit
21
+ - reproduction steps
22
+ - expected impact
23
+ - any relevant logs, payloads, or proof-of-concept material
24
+
25
+ We will acknowledge valid reports privately and coordinate disclosure after a
26
+ fix or mitigation is available.
package/cli/constants.mjs CHANGED
@@ -1,4 +1,4 @@
1
- export const VERSION = "0.2.0";
1
+ export const VERSION = "0.2.1";
2
2
  export const PACKAGE_NAME = "@nimiplatform/nimi-coding";
3
3
  export const BOOTSTRAP_CONTRACT_ID = "nimicoding.bootstrap";
4
4
  export const BOOTSTRAP_CONTRACT_VERSION = 1;
package/config/bootstrap.yaml CHANGED
@@ -1,6 +1,6 @@
1
1
  version: 1
2
2
  initialized_by: "@nimiplatform/nimi-coding"
3
- cli_version: "0.2.0"
3
+ cli_version: "0.2.1"
4
4
  bootstrap_contract: "nimicoding.bootstrap"
5
5
  bootstrap_contract_version: 1
6
6
  profile: default
package/contracts/table-family.schema.yaml CHANGED
@@ -23,6 +23,7 @@ table_family_enum:
23
23
  - protocol_surface
24
24
  - owner_matrix
25
25
  - product_catalog
26
+ - gate_registry
26
27
  - support_registry
27
28
  authority_class_enum:
28
29
  - product_authority_table
@@ -53,6 +54,11 @@ table_families:
53
54
  required_fields: [table_family, owner, catalog_id, entries]
54
55
  allowed_fields: [description, authority_refs, id, name, semantics, owner]
55
56
  forbidden_fields: [done, covered, coverage_status, audit_date, evidence_report, current, proposed, backlog_status, migration_status, mapping_status, run_id, ledger_ref]
57
+ - table_family: gate_registry
58
+ authority_class: product_authority_table
59
+ required_fields: [table_family, owner, registry_id, schema_version, registry_version, profile_id, tiers, targets, reason_codes, gates]
60
+ allowed_fields: [description, authority_refs, id, command, tier, target, prerequisite, evidence, blocker_semantics]
61
+ forbidden_fields: [done, covered, coverage_status, audit_date, evidence_report, current, proposed, backlog_status, migration_status, mapping_status, run_id, ledger_ref]
56
62
  - table_family: support_registry
57
63
  authority_class: support_registry
58
64
  required_fields: [table_family, registry_id, owner, schema_ref, allowed_fields, forbidden_state_fields, entries]
@@ -112,3 +118,4 @@ semantic_constraints:
112
118
  - lifecycle_state_and_audit_coverage_must_move_local
113
119
  - unknown_table_family_fails_closed
114
120
  - product_authority_table_rows_must_define_stable_product_facts
121
+ - release_gate_registry_must_use_gate_registry_family_not_closed_enum
package/package.json CHANGED
@@ -1,13 +1,21 @@
1
1
  {
2
2
  "name": "@nimiplatform/nimi-coding",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "private": false,
5
5
  "description": "AI-native coding governance toolkit for bootstrapping .nimi/** into arbitrary projects.",
6
6
  "license": "MIT",
7
+ "homepage": "https://docs.nimi.ai/nimicoding",
7
8
  "repository": {
8
9
  "type": "git",
9
10
  "url": "git+https://github.com/nimiplatform/nimi-coding.git"
10
11
  },
12
+ "bugs": {
13
+ "url": "https://github.com/nimiplatform/nimi-coding/issues"
14
+ },
15
+ "funding": {
16
+ "type": "github",
17
+ "url": "https://github.com/sponsors/nimiplatform"
18
+ },
11
19
  "type": "module",
12
20
  "publishConfig": {
13
21
  "access": "public",
@@ -42,10 +50,16 @@
42
50
  "methodology",
43
51
  "spec",
44
52
  "README.md",
53
+ "README.zh-CN.md",
54
+ "CHANGELOG.md",
55
+ "CONTRIBUTING.md",
56
+ "SECURITY.md",
57
+ "CODE_OF_CONDUCT.md",
45
58
  "LICENSE"
46
59
  ],
47
60
  "scripts": {
48
61
  "test": "NIMICODING_LANG=en NO_COLOR=1 node --test",
62
+ "check:ci": "pnpm test && pnpm check:pack && node ./bin/nimicoding.mjs --help >/dev/null && node ./bin/nimicoding.mjs --version >/dev/null",
49
63
  "check:pack": "npm pack --dry-run"
50
64
  }
51
65
  }