@nimiplatform/nimi-coding 0.2.8 → 0.3.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 (206) hide show
  1. package/CHANGELOG.md +10 -90
  2. package/CONTRIBUTING.md +5 -34
  3. package/README.md +47 -350
  4. package/README.zh-CN.md +33 -287
  5. package/cli/commands/start.mjs +48 -688
  6. package/cli/commands/validate-spec-audit.mjs +1 -5
  7. package/cli/commands/validate-spec-governance.mjs +20 -0
  8. package/cli/constants.mjs +9 -417
  9. package/cli/help.mjs +28 -145
  10. package/cli/index.mjs +5 -33
  11. package/cli/lib/blueprint-audit.mjs +5 -12
  12. package/cli/lib/bootstrap.mjs +0 -9
  13. package/cli/lib/contracts.mjs +0 -163
  14. package/cli/lib/doctor.mjs +155 -10
  15. package/cli/lib/entrypoints.mjs +63 -167
  16. package/cli/lib/internal/contracts-loaders.mjs +0 -85
  17. package/cli/lib/internal/contracts-parse.mjs +84 -520
  18. package/cli/lib/internal/governance/ai/check-agents-freshness.mjs +13 -8
  19. package/cli/lib/internal/surface-taxonomy-validators.mjs +316 -66
  20. package/cli/lib/internal/validators-shared.mjs +0 -16
  21. package/cli/lib/internal/validators-spec-helpers.mjs +7 -140
  22. package/cli/lib/internal/validators-spec.mjs +103 -342
  23. package/cli/lib/shared.mjs +1 -42
  24. package/cli/lib/validators.mjs +0 -48
  25. package/cli/seeds/seed-policy.yaml +0 -3
  26. package/config/bootstrap.yaml +4 -4
  27. package/config/spec-generation-inputs.yaml +6 -12
  28. package/contracts/domain-admission.schema.yaml +3 -3
  29. package/contracts/migration-inventory.schema.yaml +12 -75
  30. package/contracts/negative-fixtures.yaml +19 -99
  31. package/contracts/placement-contract.schema.yaml +49 -78
  32. package/contracts/projection-edge.schema.yaml +37 -121
  33. package/contracts/shared-enums.yaml +4 -8
  34. package/contracts/spec-generation-inputs.schema.yaml +15 -112
  35. package/contracts/spec-layout.schema.yaml +32 -0
  36. package/contracts/surface-taxonomy.schema.yaml +43 -94
  37. package/contracts/table-family.schema.yaml +1 -1
  38. package/contracts/tracked-output-admission.schema.yaml +13 -66
  39. package/methodology/core.yaml +33 -25
  40. package/methodology/four-closure-policy.yaml +18 -26
  41. package/methodology/role-separation-policy.yaml +21 -27
  42. package/methodology/spec-reconstruction.yaml +17 -34
  43. package/package.json +2 -4
  44. package/spec/_meta/spec-tree-model.yaml +5 -101
  45. package/spec/product-scope.yaml +25 -57
  46. package/adapters/README.md +0 -25
  47. package/adapters/claude/README.md +0 -89
  48. package/adapters/claude/profile.yaml +0 -70
  49. package/adapters/codex/README.md +0 -53
  50. package/adapters/codex/profile.yaml +0 -78
  51. package/adapters/oh-my-codex/README.md +0 -184
  52. package/adapters/oh-my-codex/profile.yaml +0 -46
  53. package/cli/commands/admit-high-risk-decision.mjs +0 -108
  54. package/cli/commands/audit-sweep.mjs +0 -364
  55. package/cli/commands/closeout.mjs +0 -186
  56. package/cli/commands/decide-high-risk-execution.mjs +0 -124
  57. package/cli/commands/handoff.mjs +0 -123
  58. package/cli/commands/ingest-high-risk-execution.mjs +0 -95
  59. package/cli/commands/review-high-risk-execution.mjs +0 -95
  60. package/cli/commands/sweep-design.mjs +0 -295
  61. package/cli/commands/sweep.mjs +0 -22
  62. package/cli/commands/topic-formatters.mjs +0 -382
  63. package/cli/commands/topic-goal.mjs +0 -33
  64. package/cli/commands/topic-options-shared.mjs +0 -27
  65. package/cli/commands/topic-options-workflow.mjs +0 -767
  66. package/cli/commands/topic-options.mjs +0 -626
  67. package/cli/commands/topic-runner.mjs +0 -169
  68. package/cli/commands/topic.mjs +0 -795
  69. package/cli/commands/validate-acceptance.mjs +0 -5
  70. package/cli/commands/validate-execution-packet.mjs +0 -5
  71. package/cli/commands/validate-orchestration-state.mjs +0 -5
  72. package/cli/commands/validate-prompt.mjs +0 -5
  73. package/cli/commands/validate-worker-output.mjs +0 -5
  74. package/cli/lib/adapter-profiles.mjs +0 -403
  75. package/cli/lib/audit-execution.mjs +0 -52
  76. package/cli/lib/audit-sweep-runtime/admissions.mjs +0 -508
  77. package/cli/lib/audit-sweep-runtime/audit-validity.mjs +0 -356
  78. package/cli/lib/audit-sweep-runtime/chunks.mjs +0 -697
  79. package/cli/lib/audit-sweep-runtime/claude-auditor.mjs +0 -658
  80. package/cli/lib/audit-sweep-runtime/closeout.mjs +0 -144
  81. package/cli/lib/audit-sweep-runtime/codex-auditor-evidence.mjs +0 -654
  82. package/cli/lib/audit-sweep-runtime/codex-auditor.mjs +0 -527
  83. package/cli/lib/audit-sweep-runtime/common.mjs +0 -341
  84. package/cli/lib/audit-sweep-runtime/coverage-quality.mjs +0 -172
  85. package/cli/lib/audit-sweep-runtime/evidence-assignment.mjs +0 -155
  86. package/cli/lib/audit-sweep-runtime/format.mjs +0 -57
  87. package/cli/lib/audit-sweep-runtime/ingest.mjs +0 -486
  88. package/cli/lib/audit-sweep-runtime/inventory-spec-chunks.mjs +0 -425
  89. package/cli/lib/audit-sweep-runtime/inventory.mjs +0 -798
  90. package/cli/lib/audit-sweep-runtime/ledger.mjs +0 -315
  91. package/cli/lib/audit-sweep-runtime/p0p1-profile.mjs +0 -101
  92. package/cli/lib/audit-sweep-runtime/remediation.mjs +0 -349
  93. package/cli/lib/audit-sweep-runtime/rerun.mjs +0 -129
  94. package/cli/lib/audit-sweep-runtime/risk-budget.mjs +0 -300
  95. package/cli/lib/audit-sweep-runtime/status.mjs +0 -62
  96. package/cli/lib/audit-sweep-runtime/validators-ledger.mjs +0 -215
  97. package/cli/lib/audit-sweep-runtime/validators.mjs +0 -797
  98. package/cli/lib/audit-sweep.mjs +0 -19
  99. package/cli/lib/authority-convergence.mjs +0 -720
  100. package/cli/lib/closeout.mjs +0 -732
  101. package/cli/lib/codex-sdk-runner.mjs +0 -76
  102. package/cli/lib/external-execution.mjs +0 -101
  103. package/cli/lib/handoff.mjs +0 -812
  104. package/cli/lib/high-risk-admission.mjs +0 -512
  105. package/cli/lib/high-risk-decision.mjs +0 -353
  106. package/cli/lib/high-risk-ingest.mjs +0 -321
  107. package/cli/lib/high-risk-review.mjs +0 -267
  108. package/cli/lib/internal/contracts-parse-high-risk.mjs +0 -131
  109. package/cli/lib/internal/contracts-validators.mjs +0 -399
  110. package/cli/lib/internal/doctor-bootstrap-surface.mjs +0 -406
  111. package/cli/lib/internal/doctor-delegated-surface.mjs +0 -256
  112. package/cli/lib/internal/doctor-finalize.mjs +0 -383
  113. package/cli/lib/internal/doctor-format.mjs +0 -286
  114. package/cli/lib/internal/doctor-inspectors.mjs +0 -327
  115. package/cli/lib/internal/doctor-state.mjs +0 -205
  116. package/cli/lib/internal/validators-artifacts.mjs +0 -515
  117. package/cli/lib/sweep-design-runtime/common.mjs +0 -246
  118. package/cli/lib/sweep-design-runtime/engine.mjs +0 -733
  119. package/cli/lib/sweep-design-runtime/fix-topic.mjs +0 -414
  120. package/cli/lib/sweep-design-runtime/lifecycle.mjs +0 -54
  121. package/cli/lib/sweep-design-runtime/results.mjs +0 -324
  122. package/cli/lib/sweep-design.mjs +0 -8
  123. package/cli/lib/topic-artifacts.mjs +0 -186
  124. package/cli/lib/topic-authority-coverage.mjs +0 -73
  125. package/cli/lib/topic-closeout.mjs +0 -560
  126. package/cli/lib/topic-common.mjs +0 -404
  127. package/cli/lib/topic-decisions.mjs +0 -332
  128. package/cli/lib/topic-draft-packets.mjs +0 -167
  129. package/cli/lib/topic-execution.mjs +0 -533
  130. package/cli/lib/topic-goal.mjs +0 -440
  131. package/cli/lib/topic-ledger.mjs +0 -281
  132. package/cli/lib/topic-lifecycle-artifacts.mjs +0 -173
  133. package/cli/lib/topic-root-validation.mjs +0 -288
  134. package/cli/lib/topic-runner-commands.mjs +0 -174
  135. package/cli/lib/topic-runner-deferral.mjs +0 -532
  136. package/cli/lib/topic-runner-stale-gates.mjs +0 -114
  137. package/cli/lib/topic-runner-validation.mjs +0 -138
  138. package/cli/lib/topic-runner.mjs +0 -727
  139. package/cli/lib/topic-scaffold.mjs +0 -252
  140. package/cli/lib/topic-waves.mjs +0 -403
  141. package/cli/lib/topic.mjs +0 -81
  142. package/config/audit-execution-artifacts.yaml +0 -20
  143. package/config/external-execution-artifacts.yaml +0 -16
  144. package/config/host-adapter.yaml +0 -30
  145. package/config/host-profile.yaml +0 -29
  146. package/config/installer-evidence.yaml +0 -31
  147. package/config/skill-installer.yaml +0 -23
  148. package/config/skill-manifest.yaml +0 -48
  149. package/config/skills.yaml +0 -30
  150. package/contracts/acceptance.schema.yaml +0 -16
  151. package/contracts/admission-checklist.schema.yaml +0 -15
  152. package/contracts/audit-chunk.schema.yaml +0 -123
  153. package/contracts/audit-closeout.schema.yaml +0 -51
  154. package/contracts/audit-finding.schema.yaml +0 -61
  155. package/contracts/audit-ledger.schema.yaml +0 -138
  156. package/contracts/audit-plan.schema.yaml +0 -138
  157. package/contracts/audit-remediation-map.schema.yaml +0 -52
  158. package/contracts/audit-rerun.schema.yaml +0 -31
  159. package/contracts/audit-sweep-result.yaml +0 -53
  160. package/contracts/authority-convergence-audit.schema.yaml +0 -19
  161. package/contracts/closeout.schema.yaml +0 -25
  162. package/contracts/decision-review.schema.yaml +0 -16
  163. package/contracts/doc-spec-audit-result.yaml +0 -19
  164. package/contracts/execution-packet.schema.yaml +0 -49
  165. package/contracts/external-host-compatibility.yaml +0 -22
  166. package/contracts/forbidden-shortcuts.catalog.yaml +0 -23
  167. package/contracts/high-risk-admission.schema.yaml +0 -23
  168. package/contracts/high-risk-execution-result.yaml +0 -20
  169. package/contracts/orchestration-state.schema.yaml +0 -41
  170. package/contracts/overflow-continuation.schema.yaml +0 -12
  171. package/contracts/packet.schema.yaml +0 -30
  172. package/contracts/pending-note.schema.yaml +0 -17
  173. package/contracts/prompt.schema.yaml +0 -12
  174. package/contracts/remediation.schema.yaml +0 -16
  175. package/contracts/result.schema.yaml +0 -24
  176. package/contracts/spec-reconstruction-result.yaml +0 -41
  177. package/contracts/sweep-design-result.yaml +0 -349
  178. package/contracts/topic-goal.schema.yaml +0 -87
  179. package/contracts/topic-run-ledger.schema.yaml +0 -72
  180. package/contracts/topic-step-decision.schema.yaml +0 -45
  181. package/contracts/topic.schema.yaml +0 -65
  182. package/contracts/true-close.schema.yaml +0 -15
  183. package/contracts/wave.schema.yaml +0 -29
  184. package/contracts/worker-output.schema.yaml +0 -15
  185. package/contracts/workflow-consumer.schema.yaml +0 -110
  186. package/methodology/audit-sweep-p0p1-recall.yaml +0 -45
  187. package/methodology/authority-convergence-policy.yaml +0 -42
  188. package/methodology/overflow-continuation-policy.yaml +0 -14
  189. package/methodology/skill-exchange-projection.yaml +0 -114
  190. package/methodology/skill-handoff.yaml +0 -34
  191. package/methodology/skill-installer-result.yaml +0 -27
  192. package/methodology/skill-installer-summary-projection.yaml +0 -181
  193. package/methodology/skill-runtime.yaml +0 -23
  194. package/methodology/spec-target-truth-profile.yaml +0 -46
  195. package/methodology/topic-lifecycle-report.yaml +0 -144
  196. package/methodology/topic-lifecycle.yaml +0 -37
  197. package/methodology/topic-naming-ontology.yaml +0 -21
  198. package/methodology/topic-ontology.yaml +0 -38
  199. package/methodology/topic-validation-policy.yaml +0 -9
  200. package/methodology/wave-dag-policy.yaml +0 -14
  201. package/spec/_meta/command-gating-matrix.yaml +0 -143
  202. package/spec/_meta/generate-drift-migration-checklist.yaml +0 -137
  203. package/spec/_meta/governance-routing-cutover-checklist.yaml +0 -35
  204. package/spec/_meta/phase2-impacted-surface-matrix.yaml +0 -44
  205. package/spec/_meta/spec-authority-cutover-readiness.yaml +0 -102
  206. package/spec/bootstrap-state.yaml +0 -99
package/CHANGELOG.md CHANGED
@@ -1,96 +1,16 @@
1
1
  # Changelog
2
2
 
3
- All notable changes to `@nimiplatform/nimi-coding` are tracked here.
3
+ ## 0.3.1
4
4
 
5
- This project follows semantic versioning for published npm releases.
5
+ - Made `validate-spec-governance --scope all` fail closed on the canonical spec tree before running project-configured checks.
6
6
 
7
- ## 0.2.8
7
+ ## 0.3.0
8
8
 
9
- - Fixed Windows audit-sweep execution for JavaScript auditor entrypoints by
10
- invoking `.cjs`, `.js`, and `.mjs` binaries through the active Node runtime
11
- before passing CLI arguments to Codex or Claude auditors.
12
- - Hardened post-update proof lineage selection by ordering worker prompts with
13
- nanosecond file timestamps and explicit dispatch-time mtimes, so rapid
14
- remediation dispatches do not collapse into ambiguous or stale prompt
15
- lineage.
16
- - Made README example alignment tolerant of CRLF checkouts without relaxing the
17
- documented topic command shape.
9
+ - Hard-cut the package to methodology, spec construction, managed projections, and deterministic validation.
10
+ - Removed AI-host planning, delegation, execution, review-state, and provider-runtime ownership.
11
+ - Removed the Codex SDK dependency and all host-control adapters.
12
+ - Replaced execution-shaped migration output with non-mutating descriptive migration groups.
13
+ - Added explicit host spec-layout admission for instruction paths, tracked derived projections, and table-family extensions without granting product authority.
14
+ - Upgraded bootstrap and spec-surface contracts to fail closed on pre-0.3 structures.
18
15
 
19
- ## 0.2.7
20
-
21
- - Added delegated projection admissions for spec-authority sweeps so a host
22
- `.nimi/spec/**` subtree projected from a parent or external source authority
23
- can audit host-local projection evidence while delegating source-owned
24
- implementation refs through an explicit boundary.
25
- - Kept delegated projections as audit modeling only: the CLI records and
26
- validates source-authority boundaries, but does not read, sync, rewrite, or
27
- mutate parent/external source repositories.
28
- - Ignored npm package/import specifiers and explicit `./` relative refs when
29
- deriving declared evidence targets, so package subpaths and YAML fragment refs
30
- do not get promoted into project-local evidence paths.
31
-
32
- ## 0.2.6
33
-
34
- - Hard-cut high-risk admission records out of active `.nimi/spec/**`
35
- authority. Admission records are now local-only evidence under
36
- `.nimi/local/high-risk-admissions.yaml`; product authority must live in
37
- domain spec files.
38
- - Removed the `product_admission_registry` surface class and changed
39
- `admit-high-risk-decision` to write local evidence through `--write-local`
40
- instead of writing canonical spec truth.
41
-
42
- ## 0.2.5
43
-
44
- - Fixed the `cli_version` field in `config/bootstrap.yaml` drifting away from
45
- the package version; it had been stale since the 0.2.3 release missed the
46
- bump and 0.2.4 inherited the miss.
47
- - Added a release guard test asserting that `cli_version`, the `package.json`
48
- version, and the `VERSION` constant stay in lockstep, so future releases
49
- cannot silently miss the bump.
50
-
51
- ## 0.2.4
52
-
53
- - Added the `product_state_machine` and `product_record_schema` table families
54
- for product-owned kernel tables, covering state machines and record-schema
55
- tables that are neither closed enums, generic product catalogs, nor release
56
- gate registries.
57
- - Kept table-family admission fail-closed: any table family outside the
58
- admitted set is still rejected with `unknown_table_family`.
59
-
60
- ## 0.2.3
61
-
62
- - Added `nimicoding sweep audit chunk audit-claude` for Claude-backed sweep
63
- chunk audits with structured JSON output, evidence ingestion, review, freeze,
64
- post-chunk validation, and run-ledger events.
65
- - Hardened Claude auditor output handling by normalizing Claude CLI JSON result
66
- wrappers, including `structured_output` and replayed raw output files.
67
- - Tightened audit evidence normalization so AGENTS, README, spec, contract, and
68
- methodology refs are treated as context rather than implementation evidence.
69
- - Improved P0/P1 validity and spec-authority evidence mapping so context-only
70
- chunks can be marked not applicable while declared implementation refs,
71
- including `.prisma` surfaces, map to the correct owner roots.
72
- - Updated default audit-sweep exclusions for common tool state and archive
73
- directories while keeping host-specific `nimi/**` exclusions out of the
74
- package defaults.
75
-
76
- ## 0.2.2
77
-
78
- - Fixed v2 doctor lifecycle/readiness derivation so host projects using the
79
- class-filtered surface model no longer depend on legacy `.nimi/spec/_meta`
80
- carriers or `.nimi/spec/bootstrap-state.yaml`.
81
- - Fixed v2 handoff readiness for `doc_spec_audit` so it can run when the
82
- canonical tree is present but the local generation audit still needs repair.
83
-
84
- ## 0.2.1
85
-
86
- - Added the `gate_registry` table family for product-owned release gate
87
- registries that are not closed enums or generic product catalogs.
88
-
89
- ## 0.2.0
90
-
91
- - Split Nimi Coding into a standalone public package.
92
- - Published the `nimicoding` CLI boundary for bootstrap, validation, handoff,
93
- local closeout, topic lifecycle, sweep audit, sweep design, and high-risk
94
- execution gates.
95
- - Kept runtime execution, scheduling, notifications, provider invocation, and
96
- self-hosted methodology execution outside the package boundary.
16
+ Earlier release history remains available in Git.
package/CONTRIBUTING.md CHANGED
@@ -1,45 +1,16 @@
1
1
  # Contributing
2
2
 
3
- Thanks for taking the time to improve Nimi Coding.
3
+ Nimi Coding accepts changes to methodology, spec construction, managed projections, and deterministic governance validators. AI-host control, provider execution, task-state management, and review-state management are outside this package.
4
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
5
+ Before opening a change:
16
6
 
17
7
  ```bash
18
8
  pnpm install
19
9
  pnpm test
20
10
  pnpm check:pack
11
+ pnpm check:ci
21
12
  ```
22
13
 
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
- ```
14
+ Contract changes must update their parser or validator, negative cases, documentation, and package projection tests together. Do not add compatibility branches for pre-0.3 behavior; Git history is the migration evidence.
43
15
 
44
- The sign-off certifies that you have the right to submit the contribution under
45
- the project's license.
16
+ Never commit `.nimi/local/**`, `.nimi/cache/**`, credentials, provider transcripts, or private repository evidence.
package/README.md CHANGED
@@ -1,375 +1,72 @@
1
- # @nimiplatform/nimi-coding
1
+ # Nimi Coding
2
2
 
3
- **English** · [简体中文](README.zh-CN.md)
3
+ Nimi Coding is an AI-native methodology and spec-governance package. It gives a repository a precise authority model, canonical spec construction contracts, managed governance projections, and deterministic validation.
4
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)
5
+ Nimi Coding deliberately does not control an AI host. Planning, delegation, implementation, review, and task state belong to the host's native capabilities.
8
6
 
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
76
- - self-hosted methodology execution
77
-
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:
7
+ ## Install and bootstrap
133
8
 
134
9
  ```bash
135
- npm install --save-dev @nimiplatform/nimi-coding
136
- # or
137
10
  pnpm add -D @nimiplatform/nimi-coding
11
+ pnpm exec nimicoding start --yes
138
12
  ```
139
13
 
140
- Check the CLI:
14
+ Bootstrap creates or updates only:
141
15
 
142
- ```bash
143
- npx nimicoding --version
144
- npx nimicoding --help
145
- ```
16
+ - `.nimi/config/**` — package defaults and host-owned spec input configuration
17
+ - `.nimi/contracts/**` — authority, taxonomy, placement, and audit contracts
18
+ - `.nimi/methodology/**` — reasoning and spec-construction methodology
19
+ - managed guidance blocks in `AGENTS.md` and `CLAUDE.md`
146
20
 
147
- ## 5-Minute Minimal Path
21
+ Canonical product authority remains under `.nimi/spec/**`. Local generation evidence belongs under `.nimi/local/state/spec-generation/**` and never becomes product authority.
148
22
 
149
- Most projects should start small. The first successful path is:
23
+ ## Core commands
150
24
 
151
25
  ```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
26
+ # Managed projection lifecycle
27
+ pnpm exec nimicoding start --yes
28
+ pnpm exec nimicoding sync --check
29
+ pnpm exec nimicoding sync --apply
30
+ pnpm exec nimicoding doctor --json
31
+ pnpm exec nimicoding clear --yes
32
+
33
+ # Spec construction evidence
34
+ pnpm exec nimicoding blueprint-audit --json
35
+ pnpm exec nimicoding classify-spec-tree --root .nimi/spec --json
36
+ pnpm exec nimicoding generate-spec-migration-plan --root .nimi/spec --json
37
+ pnpm exec nimicoding generate-spec-derived-docs --profile nimi --scope spec-human-doc
38
+
39
+ # Deterministic validation
40
+ pnpm exec nimicoding validate-spec-tree -- .nimi/spec
41
+ pnpm exec nimicoding validate-spec-audit -- .nimi/local/state/spec-generation/spec-generation-audit.yaml
42
+ pnpm exec nimicoding validate-placement --profile nimi --root .nimi/spec
43
+ pnpm exec nimicoding validate-table-family --profile nimi --root .nimi/spec
44
+ pnpm exec nimicoding validate-projection-edges --profile nimi --root .nimi/spec
45
+ pnpm exec nimicoding validate-guidance-bodies --profile nimi --root .nimi/spec
46
+ pnpm exec nimicoding validate-domain-admission --profile nimi --root .nimi/spec
47
+ pnpm exec nimicoding validate-tracked-output-admission --profile nimi --root .nimi/spec
48
+ pnpm exec nimicoding validate-spec-governance --profile nimi --scope all
49
+ pnpm exec nimicoding validate-ai-governance --profile nimi --scope all
165
50
  ```
166
51
 
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):
52
+ `classify-spec-tree` and `generate-spec-migration-plan` are non-mutating analysis commands. An emitted migration plan is local evidence, not an execution schedule.
183
53
 
184
- ```bash
185
- npx nimicoding clear --yes
186
- ```
187
-
188
- ## When You Need More: Topics, Waves, Packets
54
+ ## Authority model
189
55
 
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.
56
+ 1. The host's `.nimi/spec/**` is canonical product authority.
57
+ 2. Package methodology and contracts remain package authority and project into `.nimi/{methodology,contracts,config}/**`.
58
+ 3. Generated views, audit evidence, and operational state are non-authoritative.
59
+ 4. Unknown placement or unresolved semantic ambiguity fails closed.
194
60
 
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/**`.
61
+ See `methodology/spec-reconstruction.yaml`, `contracts/surface-taxonomy.schema.yaml`, and `contracts/placement-contract.schema.yaml` for the normative construction model.
312
62
 
313
63
  ## Development
314
64
 
315
65
  ```bash
316
66
  pnpm install
317
- pnpm test # runs the node:test suite
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
67
+ pnpm test
68
+ pnpm check:pack
69
+ pnpm check:ci
327
70
  ```
328
71
 
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).
72
+ Requires Node.js 24+ and pnpm 10+.