@nurix/etna 0.19.27 → 0.19.29
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/data/harness-index.json +1 -1
- package/data/harnesses/code/CLAUDE.md +2 -0
- package/data/harnesses/code/agents/maintenance.md +7 -4
- package/data/harnesses/code/codex/agents/maintenance.toml +8 -4
- package/data/harnesses/code/harness.json +2 -2
- package/data/harnesses/code/rules/general.md +11 -10
- package/data/harnesses/etna/CLAUDE.md +2 -0
- package/data/harnesses/etna/agents/maintenance.md +7 -4
- package/data/harnesses/etna/codex/agents/maintenance.toml +8 -4
- package/data/harnesses/etna/harness.json +2 -2
- package/data/harnesses/etna/rules/general.md +11 -10
- package/data/harnesses/hr/harness.json +1 -1
- package/package.json +1 -1
package/data/harness-index.json
CHANGED
|
@@ -102,6 +102,8 @@ A commit marks the user's behavioral verification of the work, and the working s
|
|
|
102
102
|
- **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
|
|
103
103
|
- **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.
|
|
104
104
|
|
|
105
|
+
**One-shot migrations are a different genre.** Work that runs **once** against a live system — a data backfill, a schema cutover, a dependency or harness upgrade rolled across repos — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in the repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.
|
|
106
|
+
|
|
105
107
|
---
|
|
106
108
|
|
|
107
109
|
## Out-of-Scope Discovery
|
|
@@ -23,12 +23,14 @@ Out of scope (handled by the `boundary` skill, which derives contracts dynamical
|
|
|
23
23
|
|
|
24
24
|
Decide the mode once, up front, from the version marker — then run.
|
|
25
25
|
|
|
26
|
-
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
26
|
+
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
27
27
|
2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
|
|
28
28
|
- **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
|
|
29
|
-
- **Behind on major** ⇒
|
|
30
|
-
- **Behind on
|
|
29
|
+
- **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
|
|
30
|
+
- **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
|
|
31
31
|
- **Equal to installed** ⇒ **audit only** (the default spine).
|
|
32
|
+
|
|
33
|
+
> **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
|
|
32
34
|
3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
|
|
33
35
|
|
|
34
36
|
You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
|
|
@@ -139,6 +141,7 @@ docs/
|
|
|
139
141
|
│ ├── CHANGELOG.md # Master changelog index
|
|
140
142
|
│ ├── changelog/ # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
|
|
141
143
|
│ ├── plans/ # Implementation plans (Status field required)
|
|
144
|
+
│ ├── migrations/ # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
|
|
142
145
|
│ ├── brainstorms/ # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
|
|
143
146
|
│ └── backlog.md # Tracked work items by priority (P0-P3)
|
|
144
147
|
├── memory/ # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
|
|
@@ -201,7 +204,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
|
|
|
201
204
|
## Rules
|
|
202
205
|
|
|
203
206
|
- **Never delete feature docs** — only update or flag for review.
|
|
204
|
-
- **Never modify `docs/history/plans
|
|
207
|
+
- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/migrations/`** (frozen records — changelog entries are written only at commit time and distilled only by the `retro` agent; a migration runbook freezes at its Outcome stamp).
|
|
205
208
|
- **Preserve existing doc structure and formatting** when updating.
|
|
206
209
|
- **When in doubt, create a backlog item** rather than making a wrong update.
|
|
207
210
|
- **Be specific:** include file paths, line numbers, and what changed.
|
|
@@ -21,12 +21,14 @@ Out of scope (handled by the `boundary` skill, which derives contracts dynamical
|
|
|
21
21
|
|
|
22
22
|
Decide the mode once, up front, from the version marker — then run.
|
|
23
23
|
|
|
24
|
-
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
24
|
+
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
25
25
|
2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
|
|
26
26
|
- **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
|
|
27
|
-
- **Behind on major** ⇒
|
|
28
|
-
- **Behind on
|
|
27
|
+
- **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
|
|
28
|
+
- **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
|
|
29
29
|
- **Equal to installed** ⇒ **audit only** (the default spine).
|
|
30
|
+
|
|
31
|
+
> **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
|
|
30
32
|
3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
|
|
31
33
|
|
|
32
34
|
You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
|
|
@@ -137,6 +139,7 @@ docs/
|
|
|
137
139
|
│ ├── CHANGELOG.md # Master changelog index
|
|
138
140
|
│ ├── changelog/ # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
|
|
139
141
|
│ ├── plans/ # Implementation plans (Status field required)
|
|
142
|
+
│ ├── migrations/ # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
|
|
140
143
|
│ ├── brainstorms/ # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
|
|
141
144
|
│ └── backlog.md # Tracked work items by priority (P0-P3)
|
|
142
145
|
├── memory/ # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
|
|
@@ -165,6 +168,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
|
|
|
165
168
|
| repo-wide `docs/pillars/` | cross-module doctrine → `docs/architecture/`; delete the folder |
|
|
166
169
|
| `docs/boundaries/` (legacy persisted boundaries) | delete — boundary analysis is a plan-time diagnostic (the `boundary` skill reads contracts fresh from source); fold any human-authored knowledge (external consumers, intent, accepted exceptions) into `docs/architecture/` |
|
|
167
170
|
| `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
|
|
171
|
+
| `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
|
|
168
172
|
| `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
|
|
169
173
|
| `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
|
|
170
174
|
| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
|
|
@@ -198,7 +202,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
|
|
|
198
202
|
## Rules
|
|
199
203
|
|
|
200
204
|
- **Never delete feature docs** — only update or flag for review.
|
|
201
|
-
- **Never modify `docs/history/plans
|
|
205
|
+
- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/migrations/`** (frozen records — changelog entries are written only at commit time and distilled only by the `retro` agent; a migration runbook freezes at its Outcome stamp).
|
|
202
206
|
- **Preserve existing doc structure and formatting** when updating.
|
|
203
207
|
- **When in doubt, create a backlog item** rather than making a wrong update.
|
|
204
208
|
- **Be specific:** include file paths, line numbers, and what changed.
|
|
@@ -4,7 +4,7 @@ Runtime versions and the canonical package list — the workspace baseline every
|
|
|
4
4
|
|
|
5
5
|
## Runtime Versions
|
|
6
6
|
|
|
7
|
-
- **Node.js:** 24 LTS
|
|
7
|
+
- **Node.js:** 24 LTS
|
|
8
8
|
- **Package manager:** detect from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm). Don't hardcode one.
|
|
9
9
|
- **PostgreSQL:** 17 · **Redis:** 7.x (latest)
|
|
10
10
|
|
|
@@ -24,21 +24,22 @@ No alternatives. Just use these.
|
|
|
24
24
|
| axios | ^1.13.2 | HTTP requests | fetch |
|
|
25
25
|
| date-fns | ^4.1.0 | Date formatting | moment, dayjs |
|
|
26
26
|
| @dnd-kit/core | ^6.3.1 | Drag and drop | react-beautiful-dnd |
|
|
27
|
+
| @xyflow/react | ^12.11.0 | Node-based flow charts | reactflow, react-flow-renderer |
|
|
27
28
|
| motion | ^12.23.26 | Animations | react-spring |
|
|
28
29
|
| sonner | ^2.0.7 | Toast notifications | react-toastify |
|
|
29
30
|
| react-window | ^2.2.3 | List virtualization | react-virtualized |
|
|
30
|
-
| nanoid | ^
|
|
31
|
+
| nanoid | ^6.0.0 | ID generation | uuid |
|
|
31
32
|
| express | ^5.2.1 | HTTP server | fastify, koa |
|
|
32
|
-
| drizzle-orm |
|
|
33
|
-
| drizzle-kit |
|
|
33
|
+
| drizzle-orm | ^0.45.2 | Database ORM | prisma, sequelize, typeorm |
|
|
34
|
+
| drizzle-kit | ^0.31.10 | Schema tooling | - |
|
|
34
35
|
| zod | ^4.2.1 | Schema validation | yup, joi |
|
|
35
36
|
| jose | ^6.1.3 | JWT handling | jsonwebtoken |
|
|
36
37
|
| microdiff | ^1.5.0 | JSON object diffing | deep-diff, just-diff |
|
|
37
38
|
| react18-json-view | ^0.2.9 | JSON tree view | react-json-view |
|
|
38
39
|
| @tiptap/react | ^3.11.1 | Rich text editor | slate, quill, draft-js |
|
|
39
|
-
| shiki | ^3.
|
|
40
|
-
| lucide-react | ^
|
|
41
|
-
| @pdfme/generator | ^
|
|
40
|
+
| shiki | ^4.3.1 | Syntax highlighting | prism, highlight.js |
|
|
41
|
+
| lucide-react | ^1.26.0 | Icons | react-icons, heroicons |
|
|
42
|
+
| @pdfme/generator | ^6.1.12 | PDF generation | jspdf, pdfkit |
|
|
42
43
|
| cmdk | ^1.1.1 | Command palette | kbar, ninja-keys |
|
|
43
44
|
| @monaco-editor/react | ^4.7.0 | Code editor | codemirror, ace |
|
|
44
45
|
| localforage | ^1.10.0 | Client-side storage | idb, dexie |
|
|
@@ -50,11 +51,11 @@ No alternatives. Just use these.
|
|
|
50
51
|
|
|
51
52
|
## GitHub Actions
|
|
52
53
|
|
|
53
|
-
Pin the major
|
|
54
|
+
Pin the major, and check it against the action's releases — a major behind still runs, so a stale pin never fails, it only warns.
|
|
54
55
|
|
|
55
56
|
| Action | Version | Use |
|
|
56
57
|
| -------------------------- | ------- | -------------------------- |
|
|
57
|
-
| actions/checkout |
|
|
58
|
-
| actions/setup-node |
|
|
58
|
+
| actions/checkout | v7 | Repo checkout |
|
|
59
|
+
| actions/setup-node | v7 | Node toolchain + npm cache |
|
|
59
60
|
|
|
60
61
|
Set `node-version` from the Runtime Versions block above, not from whatever the runner defaults to.
|
|
@@ -120,6 +120,8 @@ A commit marks the user's behavioral verification of the work, and the working s
|
|
|
120
120
|
- **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
|
|
121
121
|
- **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.
|
|
122
122
|
|
|
123
|
+
**One-shot migrations are a different genre.** Work that runs **once** against a live system — a harness rollout across consumer repos, a catalog-wide cutover, a data backfill — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in this repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.
|
|
124
|
+
|
|
123
125
|
---
|
|
124
126
|
|
|
125
127
|
## Project Memory
|
|
@@ -23,12 +23,14 @@ Out of scope (handled by the `boundary` skill, which derives contracts dynamical
|
|
|
23
23
|
|
|
24
24
|
Decide the mode once, up front, from the version marker — then run.
|
|
25
25
|
|
|
26
|
-
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
26
|
+
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
27
27
|
2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
|
|
28
28
|
- **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
|
|
29
|
-
- **Behind on major** ⇒
|
|
30
|
-
- **Behind on
|
|
29
|
+
- **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
|
|
30
|
+
- **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
|
|
31
31
|
- **Equal to installed** ⇒ **audit only** (the default spine).
|
|
32
|
+
|
|
33
|
+
> **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
|
|
32
34
|
3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
|
|
33
35
|
|
|
34
36
|
You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
|
|
@@ -139,6 +141,7 @@ docs/
|
|
|
139
141
|
│ ├── CHANGELOG.md # Master changelog index
|
|
140
142
|
│ ├── changelog/ # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
|
|
141
143
|
│ ├── plans/ # Implementation plans (Status field required)
|
|
144
|
+
│ ├── migrations/ # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
|
|
142
145
|
│ ├── brainstorms/ # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
|
|
143
146
|
│ └── backlog.md # Tracked work items by priority (P0-P3)
|
|
144
147
|
├── memory/ # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
|
|
@@ -201,7 +204,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
|
|
|
201
204
|
## Rules
|
|
202
205
|
|
|
203
206
|
- **Never delete feature docs** — only update or flag for review.
|
|
204
|
-
- **Never modify `docs/history/plans
|
|
207
|
+
- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/migrations/`** (frozen records — changelog entries are written only at commit time and distilled only by the `retro` agent; a migration runbook freezes at its Outcome stamp).
|
|
205
208
|
- **Preserve existing doc structure and formatting** when updating.
|
|
206
209
|
- **When in doubt, create a backlog item** rather than making a wrong update.
|
|
207
210
|
- **Be specific:** include file paths, line numbers, and what changed.
|
|
@@ -21,12 +21,14 @@ Out of scope (handled by the `boundary` skill, which derives contracts dynamical
|
|
|
21
21
|
|
|
22
22
|
Decide the mode once, up front, from the version marker — then run.
|
|
23
23
|
|
|
24
|
-
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
24
|
+
1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
|
|
25
25
|
2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
|
|
26
26
|
- **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
|
|
27
|
-
- **Behind on major** ⇒
|
|
28
|
-
- **Behind on
|
|
27
|
+
- **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
|
|
28
|
+
- **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
|
|
29
29
|
- **Equal to installed** ⇒ **audit only** (the default spine).
|
|
30
|
+
|
|
31
|
+
> **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
|
|
30
32
|
3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
|
|
31
33
|
|
|
32
34
|
You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
|
|
@@ -137,6 +139,7 @@ docs/
|
|
|
137
139
|
│ ├── CHANGELOG.md # Master changelog index
|
|
138
140
|
│ ├── changelog/ # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
|
|
139
141
|
│ ├── plans/ # Implementation plans (Status field required)
|
|
142
|
+
│ ├── migrations/ # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
|
|
140
143
|
│ ├── brainstorms/ # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
|
|
141
144
|
│ └── backlog.md # Tracked work items by priority (P0-P3)
|
|
142
145
|
├── memory/ # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
|
|
@@ -165,6 +168,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
|
|
|
165
168
|
| repo-wide `docs/pillars/` | cross-module doctrine → `docs/architecture/`; delete the folder |
|
|
166
169
|
| `docs/boundaries/` (legacy persisted boundaries) | delete — boundary analysis is a plan-time diagnostic (the `boundary` skill reads contracts fresh from source); fold any human-authored knowledge (external consumers, intent, accepted exceptions) into `docs/architecture/` |
|
|
167
170
|
| `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
|
|
171
|
+
| `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
|
|
168
172
|
| `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
|
|
169
173
|
| `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
|
|
170
174
|
| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
|
|
@@ -198,7 +202,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
|
|
|
198
202
|
## Rules
|
|
199
203
|
|
|
200
204
|
- **Never delete feature docs** — only update or flag for review.
|
|
201
|
-
- **Never modify `docs/history/plans
|
|
205
|
+
- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/migrations/`** (frozen records — changelog entries are written only at commit time and distilled only by the `retro` agent; a migration runbook freezes at its Outcome stamp).
|
|
202
206
|
- **Preserve existing doc structure and formatting** when updating.
|
|
203
207
|
- **When in doubt, create a backlog item** rather than making a wrong update.
|
|
204
208
|
- **Be specific:** include file paths, line numbers, and what changed.
|
|
@@ -4,7 +4,7 @@ Runtime versions and the canonical package list — the workspace baseline every
|
|
|
4
4
|
|
|
5
5
|
## Runtime Versions
|
|
6
6
|
|
|
7
|
-
- **Node.js:** 24 LTS
|
|
7
|
+
- **Node.js:** 24 LTS
|
|
8
8
|
- **Package manager:** detect from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm). Don't hardcode one.
|
|
9
9
|
- **PostgreSQL:** 17 · **Redis:** 7.x (latest)
|
|
10
10
|
|
|
@@ -24,21 +24,22 @@ No alternatives. Just use these.
|
|
|
24
24
|
| axios | ^1.13.2 | HTTP requests | fetch |
|
|
25
25
|
| date-fns | ^4.1.0 | Date formatting | moment, dayjs |
|
|
26
26
|
| @dnd-kit/core | ^6.3.1 | Drag and drop | react-beautiful-dnd |
|
|
27
|
+
| @xyflow/react | ^12.11.0 | Node-based flow charts | reactflow, react-flow-renderer |
|
|
27
28
|
| motion | ^12.23.26 | Animations | react-spring |
|
|
28
29
|
| sonner | ^2.0.7 | Toast notifications | react-toastify |
|
|
29
30
|
| react-window | ^2.2.3 | List virtualization | react-virtualized |
|
|
30
|
-
| nanoid | ^
|
|
31
|
+
| nanoid | ^6.0.0 | ID generation | uuid |
|
|
31
32
|
| express | ^5.2.1 | HTTP server | fastify, koa |
|
|
32
|
-
| drizzle-orm |
|
|
33
|
-
| drizzle-kit |
|
|
33
|
+
| drizzle-orm | ^0.45.2 | Database ORM | prisma, sequelize, typeorm |
|
|
34
|
+
| drizzle-kit | ^0.31.10 | Schema tooling | - |
|
|
34
35
|
| zod | ^4.2.1 | Schema validation | yup, joi |
|
|
35
36
|
| jose | ^6.1.3 | JWT handling | jsonwebtoken |
|
|
36
37
|
| microdiff | ^1.5.0 | JSON object diffing | deep-diff, just-diff |
|
|
37
38
|
| react18-json-view | ^0.2.9 | JSON tree view | react-json-view |
|
|
38
39
|
| @tiptap/react | ^3.11.1 | Rich text editor | slate, quill, draft-js |
|
|
39
|
-
| shiki | ^3.
|
|
40
|
-
| lucide-react | ^
|
|
41
|
-
| @pdfme/generator | ^
|
|
40
|
+
| shiki | ^4.3.1 | Syntax highlighting | prism, highlight.js |
|
|
41
|
+
| lucide-react | ^1.26.0 | Icons | react-icons, heroicons |
|
|
42
|
+
| @pdfme/generator | ^6.1.12 | PDF generation | jspdf, pdfkit |
|
|
42
43
|
| cmdk | ^1.1.1 | Command palette | kbar, ninja-keys |
|
|
43
44
|
| @monaco-editor/react | ^4.7.0 | Code editor | codemirror, ace |
|
|
44
45
|
| localforage | ^1.10.0 | Client-side storage | idb, dexie |
|
|
@@ -50,11 +51,11 @@ No alternatives. Just use these.
|
|
|
50
51
|
|
|
51
52
|
## GitHub Actions
|
|
52
53
|
|
|
53
|
-
Pin the major
|
|
54
|
+
Pin the major, and check it against the action's releases — a major behind still runs, so a stale pin never fails, it only warns.
|
|
54
55
|
|
|
55
56
|
| Action | Version | Use |
|
|
56
57
|
| -------------------------- | ------- | -------------------------- |
|
|
57
|
-
| actions/checkout |
|
|
58
|
-
| actions/setup-node |
|
|
58
|
+
| actions/checkout | v7 | Repo checkout |
|
|
59
|
+
| actions/setup-node | v7 | Node toolchain + npm cache |
|
|
59
60
|
|
|
60
61
|
Set `node-version` from the Runtime Versions block above, not from whatever the runner defaults to.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nurix/etna",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.29",
|
|
4
4
|
"description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|