@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.
- package/CHANGELOG.md +10 -90
- package/CONTRIBUTING.md +5 -34
- package/README.md +47 -350
- package/README.zh-CN.md +33 -287
- package/cli/commands/start.mjs +48 -688
- package/cli/commands/validate-spec-audit.mjs +1 -5
- package/cli/commands/validate-spec-governance.mjs +20 -0
- package/cli/constants.mjs +9 -417
- package/cli/help.mjs +28 -145
- package/cli/index.mjs +5 -33
- package/cli/lib/blueprint-audit.mjs +5 -12
- package/cli/lib/bootstrap.mjs +0 -9
- package/cli/lib/contracts.mjs +0 -163
- package/cli/lib/doctor.mjs +155 -10
- package/cli/lib/entrypoints.mjs +63 -167
- package/cli/lib/internal/contracts-loaders.mjs +0 -85
- package/cli/lib/internal/contracts-parse.mjs +84 -520
- package/cli/lib/internal/governance/ai/check-agents-freshness.mjs +13 -8
- package/cli/lib/internal/surface-taxonomy-validators.mjs +316 -66
- package/cli/lib/internal/validators-shared.mjs +0 -16
- package/cli/lib/internal/validators-spec-helpers.mjs +7 -140
- package/cli/lib/internal/validators-spec.mjs +103 -342
- package/cli/lib/shared.mjs +1 -42
- package/cli/lib/validators.mjs +0 -48
- package/cli/seeds/seed-policy.yaml +0 -3
- package/config/bootstrap.yaml +4 -4
- package/config/spec-generation-inputs.yaml +6 -12
- package/contracts/domain-admission.schema.yaml +3 -3
- package/contracts/migration-inventory.schema.yaml +12 -75
- package/contracts/negative-fixtures.yaml +19 -99
- package/contracts/placement-contract.schema.yaml +49 -78
- package/contracts/projection-edge.schema.yaml +37 -121
- package/contracts/shared-enums.yaml +4 -8
- package/contracts/spec-generation-inputs.schema.yaml +15 -112
- package/contracts/spec-layout.schema.yaml +32 -0
- package/contracts/surface-taxonomy.schema.yaml +43 -94
- package/contracts/table-family.schema.yaml +1 -1
- package/contracts/tracked-output-admission.schema.yaml +13 -66
- package/methodology/core.yaml +33 -25
- package/methodology/four-closure-policy.yaml +18 -26
- package/methodology/role-separation-policy.yaml +21 -27
- package/methodology/spec-reconstruction.yaml +17 -34
- package/package.json +2 -4
- package/spec/_meta/spec-tree-model.yaml +5 -101
- package/spec/product-scope.yaml +25 -57
- package/adapters/README.md +0 -25
- package/adapters/claude/README.md +0 -89
- package/adapters/claude/profile.yaml +0 -70
- package/adapters/codex/README.md +0 -53
- package/adapters/codex/profile.yaml +0 -78
- package/adapters/oh-my-codex/README.md +0 -184
- package/adapters/oh-my-codex/profile.yaml +0 -46
- package/cli/commands/admit-high-risk-decision.mjs +0 -108
- package/cli/commands/audit-sweep.mjs +0 -364
- package/cli/commands/closeout.mjs +0 -186
- package/cli/commands/decide-high-risk-execution.mjs +0 -124
- package/cli/commands/handoff.mjs +0 -123
- package/cli/commands/ingest-high-risk-execution.mjs +0 -95
- package/cli/commands/review-high-risk-execution.mjs +0 -95
- package/cli/commands/sweep-design.mjs +0 -295
- package/cli/commands/sweep.mjs +0 -22
- package/cli/commands/topic-formatters.mjs +0 -382
- package/cli/commands/topic-goal.mjs +0 -33
- package/cli/commands/topic-options-shared.mjs +0 -27
- package/cli/commands/topic-options-workflow.mjs +0 -767
- package/cli/commands/topic-options.mjs +0 -626
- package/cli/commands/topic-runner.mjs +0 -169
- package/cli/commands/topic.mjs +0 -795
- package/cli/commands/validate-acceptance.mjs +0 -5
- package/cli/commands/validate-execution-packet.mjs +0 -5
- package/cli/commands/validate-orchestration-state.mjs +0 -5
- package/cli/commands/validate-prompt.mjs +0 -5
- package/cli/commands/validate-worker-output.mjs +0 -5
- package/cli/lib/adapter-profiles.mjs +0 -403
- package/cli/lib/audit-execution.mjs +0 -52
- package/cli/lib/audit-sweep-runtime/admissions.mjs +0 -508
- package/cli/lib/audit-sweep-runtime/audit-validity.mjs +0 -356
- package/cli/lib/audit-sweep-runtime/chunks.mjs +0 -697
- package/cli/lib/audit-sweep-runtime/claude-auditor.mjs +0 -658
- package/cli/lib/audit-sweep-runtime/closeout.mjs +0 -144
- package/cli/lib/audit-sweep-runtime/codex-auditor-evidence.mjs +0 -654
- package/cli/lib/audit-sweep-runtime/codex-auditor.mjs +0 -527
- package/cli/lib/audit-sweep-runtime/common.mjs +0 -341
- package/cli/lib/audit-sweep-runtime/coverage-quality.mjs +0 -172
- package/cli/lib/audit-sweep-runtime/evidence-assignment.mjs +0 -155
- package/cli/lib/audit-sweep-runtime/format.mjs +0 -57
- package/cli/lib/audit-sweep-runtime/ingest.mjs +0 -486
- package/cli/lib/audit-sweep-runtime/inventory-spec-chunks.mjs +0 -425
- package/cli/lib/audit-sweep-runtime/inventory.mjs +0 -798
- package/cli/lib/audit-sweep-runtime/ledger.mjs +0 -315
- package/cli/lib/audit-sweep-runtime/p0p1-profile.mjs +0 -101
- package/cli/lib/audit-sweep-runtime/remediation.mjs +0 -349
- package/cli/lib/audit-sweep-runtime/rerun.mjs +0 -129
- package/cli/lib/audit-sweep-runtime/risk-budget.mjs +0 -300
- package/cli/lib/audit-sweep-runtime/status.mjs +0 -62
- package/cli/lib/audit-sweep-runtime/validators-ledger.mjs +0 -215
- package/cli/lib/audit-sweep-runtime/validators.mjs +0 -797
- package/cli/lib/audit-sweep.mjs +0 -19
- package/cli/lib/authority-convergence.mjs +0 -720
- package/cli/lib/closeout.mjs +0 -732
- package/cli/lib/codex-sdk-runner.mjs +0 -76
- package/cli/lib/external-execution.mjs +0 -101
- package/cli/lib/handoff.mjs +0 -812
- package/cli/lib/high-risk-admission.mjs +0 -512
- package/cli/lib/high-risk-decision.mjs +0 -353
- package/cli/lib/high-risk-ingest.mjs +0 -321
- package/cli/lib/high-risk-review.mjs +0 -267
- package/cli/lib/internal/contracts-parse-high-risk.mjs +0 -131
- package/cli/lib/internal/contracts-validators.mjs +0 -399
- package/cli/lib/internal/doctor-bootstrap-surface.mjs +0 -406
- package/cli/lib/internal/doctor-delegated-surface.mjs +0 -256
- package/cli/lib/internal/doctor-finalize.mjs +0 -383
- package/cli/lib/internal/doctor-format.mjs +0 -286
- package/cli/lib/internal/doctor-inspectors.mjs +0 -327
- package/cli/lib/internal/doctor-state.mjs +0 -205
- package/cli/lib/internal/validators-artifacts.mjs +0 -515
- package/cli/lib/sweep-design-runtime/common.mjs +0 -246
- package/cli/lib/sweep-design-runtime/engine.mjs +0 -733
- package/cli/lib/sweep-design-runtime/fix-topic.mjs +0 -414
- package/cli/lib/sweep-design-runtime/lifecycle.mjs +0 -54
- package/cli/lib/sweep-design-runtime/results.mjs +0 -324
- package/cli/lib/sweep-design.mjs +0 -8
- package/cli/lib/topic-artifacts.mjs +0 -186
- package/cli/lib/topic-authority-coverage.mjs +0 -73
- package/cli/lib/topic-closeout.mjs +0 -560
- package/cli/lib/topic-common.mjs +0 -404
- package/cli/lib/topic-decisions.mjs +0 -332
- package/cli/lib/topic-draft-packets.mjs +0 -167
- package/cli/lib/topic-execution.mjs +0 -533
- package/cli/lib/topic-goal.mjs +0 -440
- package/cli/lib/topic-ledger.mjs +0 -281
- package/cli/lib/topic-lifecycle-artifacts.mjs +0 -173
- package/cli/lib/topic-root-validation.mjs +0 -288
- package/cli/lib/topic-runner-commands.mjs +0 -174
- package/cli/lib/topic-runner-deferral.mjs +0 -532
- package/cli/lib/topic-runner-stale-gates.mjs +0 -114
- package/cli/lib/topic-runner-validation.mjs +0 -138
- package/cli/lib/topic-runner.mjs +0 -727
- package/cli/lib/topic-scaffold.mjs +0 -252
- package/cli/lib/topic-waves.mjs +0 -403
- package/cli/lib/topic.mjs +0 -81
- package/config/audit-execution-artifacts.yaml +0 -20
- package/config/external-execution-artifacts.yaml +0 -16
- package/config/host-adapter.yaml +0 -30
- package/config/host-profile.yaml +0 -29
- package/config/installer-evidence.yaml +0 -31
- package/config/skill-installer.yaml +0 -23
- package/config/skill-manifest.yaml +0 -48
- package/config/skills.yaml +0 -30
- package/contracts/acceptance.schema.yaml +0 -16
- package/contracts/admission-checklist.schema.yaml +0 -15
- package/contracts/audit-chunk.schema.yaml +0 -123
- package/contracts/audit-closeout.schema.yaml +0 -51
- package/contracts/audit-finding.schema.yaml +0 -61
- package/contracts/audit-ledger.schema.yaml +0 -138
- package/contracts/audit-plan.schema.yaml +0 -138
- package/contracts/audit-remediation-map.schema.yaml +0 -52
- package/contracts/audit-rerun.schema.yaml +0 -31
- package/contracts/audit-sweep-result.yaml +0 -53
- package/contracts/authority-convergence-audit.schema.yaml +0 -19
- package/contracts/closeout.schema.yaml +0 -25
- package/contracts/decision-review.schema.yaml +0 -16
- package/contracts/doc-spec-audit-result.yaml +0 -19
- package/contracts/execution-packet.schema.yaml +0 -49
- package/contracts/external-host-compatibility.yaml +0 -22
- package/contracts/forbidden-shortcuts.catalog.yaml +0 -23
- package/contracts/high-risk-admission.schema.yaml +0 -23
- package/contracts/high-risk-execution-result.yaml +0 -20
- package/contracts/orchestration-state.schema.yaml +0 -41
- package/contracts/overflow-continuation.schema.yaml +0 -12
- package/contracts/packet.schema.yaml +0 -30
- package/contracts/pending-note.schema.yaml +0 -17
- package/contracts/prompt.schema.yaml +0 -12
- package/contracts/remediation.schema.yaml +0 -16
- package/contracts/result.schema.yaml +0 -24
- package/contracts/spec-reconstruction-result.yaml +0 -41
- package/contracts/sweep-design-result.yaml +0 -349
- package/contracts/topic-goal.schema.yaml +0 -87
- package/contracts/topic-run-ledger.schema.yaml +0 -72
- package/contracts/topic-step-decision.schema.yaml +0 -45
- package/contracts/topic.schema.yaml +0 -65
- package/contracts/true-close.schema.yaml +0 -15
- package/contracts/wave.schema.yaml +0 -29
- package/contracts/worker-output.schema.yaml +0 -15
- package/contracts/workflow-consumer.schema.yaml +0 -110
- package/methodology/audit-sweep-p0p1-recall.yaml +0 -45
- package/methodology/authority-convergence-policy.yaml +0 -42
- package/methodology/overflow-continuation-policy.yaml +0 -14
- package/methodology/skill-exchange-projection.yaml +0 -114
- package/methodology/skill-handoff.yaml +0 -34
- package/methodology/skill-installer-result.yaml +0 -27
- package/methodology/skill-installer-summary-projection.yaml +0 -181
- package/methodology/skill-runtime.yaml +0 -23
- package/methodology/spec-target-truth-profile.yaml +0 -46
- package/methodology/topic-lifecycle-report.yaml +0 -144
- package/methodology/topic-lifecycle.yaml +0 -37
- package/methodology/topic-naming-ontology.yaml +0 -21
- package/methodology/topic-ontology.yaml +0 -38
- package/methodology/topic-validation-policy.yaml +0 -9
- package/methodology/wave-dag-policy.yaml +0 -14
- package/spec/_meta/command-gating-matrix.yaml +0 -143
- package/spec/_meta/generate-drift-migration-checklist.yaml +0 -137
- package/spec/_meta/governance-routing-cutover-checklist.yaml +0 -35
- package/spec/_meta/phase2-impacted-surface-matrix.yaml +0 -44
- package/spec/_meta/spec-authority-cutover-readiness.yaml +0 -102
- package/spec/bootstrap-state.yaml +0 -99
package/CHANGELOG.md
CHANGED
|
@@ -1,96 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## 0.3.1
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- Made `validate-spec-governance --scope all` fail closed on the canonical spec tree before running project-configured checks.
|
|
6
6
|
|
|
7
|
-
## 0.
|
|
7
|
+
## 0.3.0
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
1
|
+
# Nimi Coding
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
6
|
-
[](LICENSE)
|
|
7
|
-
[](#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
|
-
|
|
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
|
-
|
|
14
|
+
Bootstrap creates or updates only:
|
|
141
15
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
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
|
-
|
|
23
|
+
## Core commands
|
|
150
24
|
|
|
151
25
|
```bash
|
|
152
|
-
#
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
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
|
-
|
|
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
|
-
|
|
185
|
-
npx nimicoding clear --yes
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
## When You Need More: Topics, Waves, Packets
|
|
54
|
+
## Authority model
|
|
189
55
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
-
|
|
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
|
|
318
|
-
pnpm check:pack
|
|
319
|
-
pnpm check:ci
|
|
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
|
-
|
|
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+.
|