@nurix/etna 0.20.36 → 0.20.37

package/data/catalog/skills/nustack/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nustack
-description: "The @nurix/* packaging and tooling skill — pnpm monorepo setup (workspace file, catalog, root scripts), publishing packages to npm, and distributable @nurix CLIs (npx self-update, managed blocks). Use when scaffolding a workspace, publishing a package, building a CLI, or debugging an npm publish."
+description: "Use when scaffolding a pnpm workspace, publishing an @nurix/* package to npm, building a distributable @nurix CLI (npx self-update, managed blocks), or debugging an npm publish."
 ---
 
 # NuStack
 
-The `@nurix/*` packaging and tooling skill. Always-loaded workspace doctrine — package naming, monorepo boundaries, consuming — is the [`pnpm.md`](../../rules/pnpm.md) rule; this skill carries the on-demand reference material, one area per reference, and grows a new reference as an area is needed.
+The `@nurix/*` packaging and tooling skill. Workspace doctrine that loads every session — package naming, monorepo boundaries, consuming — is the [`pnpm.md`](../../rules/pnpm.md) rule; this skill holds the on-demand material, one area per reference. Read the reference whose trigger matches the task before acting.
 
 | Reference | Load when |
 | --- | --- |

package/data/catalog/skills/nustack/references/cli-design.md

@@ -2,30 +2,28 @@
 
 Load when: building or changing a distributable `@nurix/*` command-line tool.
 
-Conventions for building a distributable Nurix command-line tool, distilled from the two we ship: **`@nurix/etna`** (`packages/cli/` in the etna repo — the harness installer, plain ESM JS) and **`@nurix/nustack`** (`~/dev/apollo/packages/cli/` — the service-bootstrap CLI, TypeScript → `dist/`). When you build or change a `@nurix` CLI, follow these. Where the two diverge, both variants are noted as valid.
+Conventions for a distributable `@nurix/*` command-line tool. The two reference CLIs are **`@nurix/etna`** (`packages/cli/` in the etna repo — the harness installer, plain ESM JS) and **`@nurix/nustack`** (`~/dev/apollo/packages/cli/` — the service-bootstrap CLI, TypeScript → `dist/`). Where they diverge, both variants are valid.
 
 ## 1. Packaging
 
-The base `package.json` fields — scope, `publishConfig.access: "restricted"`, `files`, build hooks — are [`publishing.md`](publishing.md) §2. CLI-specific on top:
+The base `package.json` fields — scope, `publishConfig.access: "restricted"`, `files`, build hooks — are [`publishing.md`](publishing.md) §2. A CLI adds:
 
 - **ESM only** — `"type": "module"`.
-- **`bin` maps the command to its entry** — `{ "etna": "bin/etna.js" }` / `{ "nustack": "dist/index.js" }`. The entry has a `#!/usr/bin/env node` shebang.
-- **`files` ships only the runnable artifact** — `["bin/", "data/", "README.md"]` (etna) or `["dist"]` (nustack). Never ship `src/`, tests, or the repo.
-- **`engines.node` ≥ 22** for new CLIs (matches the workspace Node baseline).
-- **One version source** — read the running version from `package.json` at startup; don't hardcode it elsewhere.
-- **Minimal deps.** Both ship with essentially one runtime dep (`@clack/prompts`); nustack adds `commander` + `ajv`. Keep the dependency surface tiny — it's installed on every `npx` run.
+- **`bin` maps the command to its entry** — `{ "etna": "bin/etna.js" }` / `{ "nustack": "dist/index.js" }`; the entry carries a `#!/usr/bin/env node` shebang.
+- **`files` ships only the runnable artifact** — `["bin/", "lib/", "data/"]` (etna) or `["dist"]` (nustack). **Never** `src/`, tests, or the repo.
+- **`engines.node` ≥ 22** for a new CLI, the workspace Node baseline.
+- **One version source** — read the running version from `package.json` at startup; never hardcode it elsewhere.
+- **Minimal deps** — essentially one runtime dep (`@clack/prompts`), because the dependency surface installs on every `npx` run; nustack adds `commander` and `ajv`.
 
 ## 2. Distribution: `npx`-first, install into the project, never globally
 
-- The canonical entry is **`npx @nurix/<tool>`** — no global install step, no marketplace, no plugin-enablement dance. The user runs `npx`, the tool does its job in the current directory.
-- **The CLI writes ONLY inside the folder it was invoked in.** An installer run as `npx @nurix/etna` in a project must touch only that project tree — never `$HOME`, never `~/.claude`, never any shared/user-level location. Reaching outside the target folder is surprising, clobber-prone, and wrong. (This is a hard-won rule: an earlier etna build installed agents to `~/.claude/agents/` and it was reverted precisely for this reason.)
-- **Idempotent refresh.** Re-running the CLI re-pulls the latest and overwrites the files it owns (force), while leaving anything the user authored untouched. "Re-run anytime to refresh" must always be safe.
+- The canonical entry is **`npx @nurix/<tool>`** — no global install, no marketplace, no plugin enablement. The tool does its job in the current directory.
+- **The CLI writes only inside the folder it was invoked in.** `npx @nurix/etna` in a project touches only that project tree — **never** `$HOME`, `~/.claude`, or any shared or user-level location, even where a tool conventionally installs globally (`~/.claude/agents/`): a write outside the target folder clobbers state the user never pointed the CLI at.
+- **Idempotent refresh.** Re-running re-pulls the latest and force-overwrites the files the CLI owns, leaving everything the user authored untouched — a re-run is **always** safe.
 
 ## 3. Always run the latest — self-update by re-exec
 
-**The problem:** `npx` caches aggressively. A bare `npx @nurix/<tool>` can keep running a *stale* unpacked copy long after a newer version is published (npm's packument cache resolves an old `latest`, and npx reuses the matching install). Users shouldn't have to remember `@latest`.
-
-**The mechanism** (etna's `selfUpdateOrReexec()`, run before anything else): on startup, ask the registry for the latest version; if this copy is behind, re-exec the latest and hand off.
+A bare `npx @nurix/<tool>` keeps running an outdated unpacked copy long after a newer version publishes — npm's packument cache resolves an old `latest`, and npx reuses the matching install — so the CLI updates itself rather than relying on users to type `@latest`. Before anything else, ask the registry for the latest version; if this copy is behind, re-exec the latest and hand off (etna's `selfUpdateOrReexec()`):
 
 ```js
 function selfUpdateOrReexec() {
@@ -44,43 +42,45 @@ function selfUpdateOrReexec() {
 
 Required properties:
 
-- **`--prefer-online`** on both the `npm view` and the `npx` re-exec — defeats the metadata cache so npx fetches the fresh tarball.
-- **Loop guard** — set `<TOOL>_SELFUPDATED=1` in the child's env so the re-exec'd process doesn't try to update again.
-- **Opt-out** — `<TOOL>_NO_SELFUPDATE=1` skips the whole thing (CI, offline, or running an intentionally pinned/local-dev build). This is also how you test a local build.
-- **Degrade gracefully** — *any* failure (offline, unauthed, `npm`/`npx` missing, timeout) falls through to running the current copy. The update is a convenience, never a gate.
-- **Reuse existing npm auth** — the `npm view` rides the caller's npm credentials (the same auth that installed the restricted package); never prompt for login.
+- **`--prefer-online`** on both the `npm view` and the `npx` re-exec — it defeats the metadata cache, so npx fetches the fresh tarball.
+- **Loop guard** — set `<TOOL>_SELFUPDATED=1` in the child's env so the re-exec'd process never updates again.
+- **Opt-out** — `<TOOL>_NO_SELFUPDATE=1` skips the check: CI, offline, an intentionally pinned build, and testing a local build.
+- **Degrade gracefully** — *any* failure (offline, unauthed, `npm`/`npx` missing, timeout) falls through to running the current copy; the update is a convenience, **never** a gate.
+- **Reuse existing npm auth** — `npm view` rides the caller's credentials, the same auth that installed the restricted package; **never** prompt for login.
 
 ## 4. Editing the user's files: own a delimited block, idempotently
 
-When the CLI must modify a file it doesn't own (`.env`, `settings.json`, `.gitignore`), it **owns only a delimited region** and rewrites that region in place — never the whole file.
+When the CLI modifies a file it doesn't own (`.env`, `settings.json`, `.gitignore`), it **owns only a delimited region** and rewrites that region in place — **never** the whole file.
 
 - nustack wraps its `.env` writes in a managed block:
-  `# >>> nustack:managed — do not edit by hand; the nustack CLI rewrites this block >>>` … `# <<< nustack:managed <<<`. Reads/merges/removes happen *inside* the markers; everything outside belongs to the user.
-- etna merges its hooks into `.claude/settings.json` and migrates/retires only its own prior entries.
-- Rewrites are **idempotent** (re-running converges to the same block) and **reversible** (logout/uninstall removes exactly the managed region).
-- If the block holds secrets, ensure `.gitignore` covers the file so they're never committed.
+  `# >>> nustack:managed — do not edit by hand; the nustack CLI rewrites this block >>>` … `# <<< nustack:managed <<<`. Reads, merges, and removals happen *inside* the markers; everything outside belongs to the user.
+- etna merges its hooks into `.claude/settings.json` and migrates or retires only its own entries.
+- Rewrites are **idempotent** (a re-run converges to the same block) and **reversible** (logout or uninstall removes exactly the managed region).
+- A block holding secrets **must** sit in a file `.gitignore` covers.
 
 ## 5. Interactive when it can, flag-driven when it can't
 
-- Use **`@clack/prompts`** for the interactive path (TTY): intro/outro, spinners, notes.
-- When **not a TTY**, require explicit flags and fail loudly with the correct syntax rather than guessing — e.g. etna needs `--name=<harness>` outside a TTY, and a removed/renamed flag (the dropped positional form in 0.18.0) errors with the new syntax instead of silently misfiring.
-- A bare invocation in a TTY may present a menu; the same invocation headless must error, not hang.
+- Use **`@clack/prompts`** for the interactive (TTY) path: intro/outro, spinners, notes.
+- **Outside a TTY**, require explicit flags and fail loudly with the correct syntax rather than guessing — etna requires `--name=<harness>`, and an unsupported flag or argument form errors with the current syntax instead of silently misfiring.
+- A bare invocation in a TTY may present a menu; the same invocation headless **must** error, not hang.
 
 ## 6. Detect the package manager from the lockfile
 
-When the CLI installs packages or runs scripts on the user's behalf, detect the manager: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm. Never hardcode one. (nustack's `detectPackageManager()`.)
+When the CLI installs packages or runs scripts for the user, detect the manager from the lockfile — `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm (nustack's `detectPackageManager()`); **never** hardcode one.
 
 ## 7. Publishing is CI-owned
 
-Publish from CI on push to `dev`/`main`, path-filtered to the CLI package — never `npm publish` by hand for a routine change. The pipeline mechanics — workflow template, tags, skip directives, `registry-url`, monorepo `working-directory` — are [`publishing.md`](publishing.md) §3–5. CLI-specific on top:
+Publish from CI on push to `dev`/`main`, path-filtered to the CLI package — **never** `npm publish` by hand for a routine change. The pipeline mechanics — workflow template, tags, skip directives, `registry-url`, monorepo `working-directory` — are [`publishing.md`](publishing.md) §3–5. A CLI adds:
+
+| Version model | How it bumps |
+| --- | --- |
+| **Fingerprint auto-bump** (etna) | The build stamps a content hash (`fingerprint`) of the shipped payload; CI bumps the **patch** when it changes, publishes, and tags. **Never** hand-bump for a content change; hand-edit the version only for a deliberate minor/major |
+| **Manual bump input** (nustack) | A `workflow_dispatch` `bump` input (`patch`/`minor`/`major`) drives `npm version` |
 
-- **Two valid version models:**
-  - **Fingerprint auto-bump (etna):** the build stamps a content hash (`fingerprint`) of the shipped payload; CI bumps the **patch** automatically when the fingerprint changed, publishes, and tags. Never hand-bump for a content change — let the fingerprint drive it; hand-edit the version only for a deliberate minor/major.
-  - **Manual bump input (nustack):** a `workflow_dispatch` `bump` input (`patch`/`minor`/`major`) drives `npm version`.
-- **`npm version --no-git-tag-version`** (file-only), then commit + tag separately — `npm version` skips the git step when run in a subdirectory of the repo root.
+- **`npm version --no-git-tag-version`** (file-only), then commit and tag separately — `npm version` silently skips its git step in a subdirectory of the repo root.
 
 ## 8. Robustness defaults
 
-- **Never hard-block on an advisory/network check.** Version currency, registry lookups, telemetry — all degrade to a one-line notice and continue.
-- **Restricted-scope auth is ambient** — the read token in `~/.npmrc` (or `$NODE_AUTH_TOKEN` in CI) authenticates installs and `npm view`. Just attempt the operation; never prompt for `npm login` or reach for a substitute package.
-- **Keep the hot path fast** — everything runs on every `npx`, so avoid heavy startup work beyond the self-update check.
+- **Never hard-block on an advisory or network check.** Version currency, registry lookups, telemetry — each degrades to a one-line notice and continues.
+- **Restricted-scope auth is ambient** — the read token in `~/.npmrc` (or `$NODE_AUTH_TOKEN` in CI) authenticates installs and `npm view`. Attempt the operation; **never** prompt for `npm login` or reach for a substitute package.
+- **Keep the hot path fast** — startup runs on every `npx`; do no heavy work beyond the self-update check.

package/data/catalog/skills/nustack/references/monorepo-master-list.md

@@ -2,7 +2,7 @@
 
 Load when: auditing a workspace's health, reviewing a monorepo PR, scaffolding review gates, or deciding what to enforce next in an existing workspace.
 
-The definitive requirements for a `@nurix/*` monorepo, in three tiers: **required** (every workspace, day one), **trigger-bound** (required the moment its trigger exists), and **deferred** (explicitly not required before scale). Assembly mechanics are [`monorepo-setup.md`](monorepo-setup.md); the publishing pipeline is [`publishing.md`](publishing.md); naming doctrine is [`pnpm.md`](../../../rules/pnpm.md) §1. Every line is auditable — it holds or it doesn't — and names its enforcement mechanism in the closing table.
+The definitive requirements for a `@nurix/*` monorepo, in three tiers: **required** (every workspace, day one), **trigger-bound** (required the moment its trigger exists), and **deferred** (not required before scale). Assembly mechanics are [`monorepo-setup.md`](monorepo-setup.md); the publishing pipeline is [`publishing.md`](publishing.md); naming doctrine is [`pnpm.md`](../../../rules/pnpm.md) §1. Every line holds or it doesn't, and the closing table names how each is enforced.
 
 ## Required — every workspace, day one
 
@@ -17,22 +17,22 @@ The definitive requirements for a `@nurix/*` monorepo, in three tiers: **require
 9. **Source-first internals, one-way flow** — internal packages export `./src/index.ts` through typed subpaths, no build step; apps depend on packages, never the reverse; anything not exported stays unreachable.
 10. **Strict hoisting** — no `shamefully-hoist`, no `node-linker=hoisted`; an undeclared import must fail immediately.
 11. **CI that gates** — a workflow installs with `--frozen-lockfile` and gates merges on the root fan-out. No CI is a compliance failure; a CI that mutates manifests before building is worse than none.
-12. **A real suite behind `pnpm test`** — the canonical-command rule applies to every workspace; toolchain configs (eslint + prettier, root-only) are wired to `lint`/`format` scripts that actually run. A fan-out script with zero targets is decoration, not compliance.
+12. **A real suite behind `pnpm test`** — the `testing` rule's canonical-command convention applies to every workspace; root-only toolchain configs (eslint + prettier) are wired to `lint`/`format` scripts that actually run. A fan-out script with zero targets is decoration, not compliance.
 
 ## Required the moment the trigger exists
 
-- **Native or postinstall deps in the lockfile** → `onlyBuiltDependencies` in `pnpm-workspace.yaml` (never the root `package.json` `pnpm` field), kept current as native deps come and go — pnpm 10 silently skips unlisted builds and the failure surfaces at runtime.
-- **A vulnerable transitive** → one `overrides` block in the workspace file; never duplicated into the root manifest.
+- **Native or postinstall deps in the lockfile** → `onlyBuiltDependencies` in `pnpm-workspace.yaml` (**never** the root `package.json` `pnpm` field), kept current as native deps come and go — pnpm 10 silently skips unlisted builds and the failure surfaces at runtime.
+- **A vulnerable transitive** → one `overrides` block in the workspace file; **never** duplicated into the root manifest.
 - **A member crosses the publish boundary** (`private: false`) → the [`publishing.md`](publishing.md) fields; the build hook **inside** `scripts` (a top-level `prepublishOnly` key silently never runs); `sideEffects: false` (or the CSS-glob variant) so consumers tree-shake; and the parity harness — `pack` → tarball-install into fixtures → build → `publint` + `attw` — re-run on every `exports`-surface change. Dev-mode success proves nothing about what consumers get.
 
 ## Deferred until scale — explicitly not required before
 
-- **Affected-filtering and task-graph runners** (`--filter "...[origin/main]"`, turbo, nx) — adopt when full `pnpm -r` runs are slow enough to feel; never day one.
+- **Affected-filtering and task-graph runners** (`--filter "...[origin/main]"`, turbo, nx) — adopt once full `pnpm -r` runs are slow enough to feel; never day one.
 - **`CODEOWNERS` by directory** — when multiple teams own members; decoration before that.
 
 ## Enforcement — every rule names its mechanism
 
-A rule that depends on discipline drifts; a rule the tooling enforces doesn't. When adding a rule to this list, name the mechanism and what happens on violation — prefer the variant that fails loudly at install/CI over the one a reviewer must notice.
+A rule that depends on discipline drifts; a rule the tooling enforces doesn't. A rule added to this list **must** name its mechanism and what happens on violation — prefer the variant that fails loudly at install or CI over one a reviewer must notice.
 
 | Rule | Mechanism | On violation |
 | --- | --- | --- |

package/data/catalog/skills/nustack/references/monorepo-setup.md

@@ -2,11 +2,11 @@
 
 Load when: scaffolding a new pnpm workspace, converting a repo to one, adding a workspace member, or wiring the root toolchain (catalog, scripts, build gating).
 
-How a workspace is **assembled** — the root files, layout globs, catalog, and verification. What packages are *named* and how their boundaries work is [`pnpm.md`](../../../rules/pnpm.md) §1–2; how a member *publishes* is [`publishing.md`](publishing.md); the standing invariants to keep true after assembly are [`monorepo-master-list.md`](monorepo-master-list.md). Reference implementations: `~/dev/workflows` (the canonical `packages/*` + catalog shape), `~/dev/starter` (adds `fixtures/*` and the publish-parity harness), `~/dev/robin` and `~/dev/sync-info` (the `packages/*` + `apps/*` split).
+How a workspace is **assembled** — root files, layout globs, catalog, verification. Package naming and boundaries are [`pnpm.md`](../../../rules/pnpm.md) §1–2; how a member publishes is [`publishing.md`](publishing.md); the invariants to keep true after assembly are [`monorepo-master-list.md`](monorepo-master-list.md). Reference implementations: `~/dev/workflows` (the canonical `packages/*` + catalog shape), `~/dev/starter` (adds `fixtures/*` and the publish-parity harness), `~/dev/robin` and `~/dev/sync-info` (the `packages/*` + `apps/*` split).
 
 ## 1. Three root files own the workspace
 
-Everything workspace-wide lives in exactly three root files; packages stay thin. Nothing else at root compiles, publishes, or carries policy.
+Everything workspace-wide lives in exactly three root files; packages stay thin, and nothing else at root compiles, publishes, or carries policy.
 
 **`pnpm-workspace.yaml`** — membership + shared versions:
 
@@ -46,11 +46,11 @@ onlyBuiltDependencies:     # postinstall allow-list — see §4
 }
 ```
 
-- **Fan out with `pnpm -r`; alias with `--filter`.** `--if-present` when not every member has the script; per-app conveniences read `"dev:admin": "pnpm --filter @nurix/nustack-app dev"` (nustack) or `"worker:dev": "pnpm --filter @sync/worker dev"` (sync-info).
-- **One toolchain config at root.** `eslint`/`prettier` run from the root over the whole tree — never per-package configs.
-- **No turbo/nx.** Plain `pnpm -r` is the baseline; reach for a task-graph runner only when the build graph is slow enough to feel — the same threshold as TS project references (`pnpm.md` §2).
+- **Fan out with `pnpm -r`; alias with `--filter`.** Add `--if-present` when not every member has the script; a per-app convenience reads `"dev:marketplace": "pnpm --filter @nurix/nustack.marketplace dev"`.
+- **One toolchain config at root.** `eslint`/`prettier` run from the root over the whole tree — **never** per-package configs.
+- **No turbo/nx by default.** Plain `pnpm -r` is the baseline; adopt a task-graph runner only once the build graph is slow enough to feel — the same threshold as TS project references (`pnpm.md` §2).
 
-**`tsconfig.base.json`** — the single TS policy owner (`pnpm.md` §2). The workflows repo's base is the model: `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `noUnusedLocals` / `noUnusedParameters`, `declaration` + `declarationMap`, `skipLibCheck`. There is **no root `tsconfig.json`** — the base is extended by members, never compiled from.
+**`tsconfig.base.json`** — the single TS policy owner (`pnpm.md` §2). The workflows repo's base is the model: `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `noUnusedLocals` / `noUnusedParameters`, `declaration` + `declarationMap`, `skipLibCheck`. There is **no root `tsconfig.json`** — members extend the base; nothing compiles from it.
 
 ## 2. Layout — pick the globs by what the repo holds
 
@@ -62,17 +62,17 @@ onlyBuiltDependencies:     # postinstall allow-list — see §4
 | + `fixtures/*` | consumer-simulation apps for parity testing (§5) | starter |
 
 - **Dependency direction is one-way** — `apps/*` depend on `packages/*`, never the reverse; siblings import each other's typed subpath exports, never a deep path into `src/` (`pnpm.md` §2).
-- Flat globs are the default; a deep path in the list (`sdk/packages/node/iii`) is for polyglot trees only.
+- Default to flat globs; a deep path in the list (`sdk/packages/node/iii`) is for polyglot trees only.
 
 ## 3. `catalog:` — one version per shared dep
 
-Anything two or more members depend on goes in the catalog: the toolchain (`typescript`, `vite`, `vitest`, type packages) and the host singletons (`react`, `react-dom`, `zod`). Members reference it as `"react": "catalog:"` — never a literal version. **A member that pins its own version beside the catalog defeats it** — two `react` copies means two hook dispatchers and runtime errors, not a type error.
+Anything two or more members depend on goes in the catalog: the toolchain (`typescript`, `vite`, `vitest`, type packages) and the host singletons (`react`, `react-dom`, `zod`). Members reference it as `"react": "catalog:"` — **never** a literal version. **A member that pins its own version beside the catalog defeats it** — two `react` copies means two hook dispatchers and runtime errors, not a type error. Set `catalogMode: strict` in `pnpm-workspace.yaml` so such a pin is an install error ([`monorepo-master-list.md`](monorepo-master-list.md) rule 2).
 
-Internal siblings are `"workspace:*"`; both protocols are rewritten to real versions at publish time.
+Internal siblings are `"workspace:*"`; `pnpm publish` rewrites both protocols to real versions.
 
 ## 4. pnpm 10 build gating
 
-pnpm 10 refuses to run dependency postinstall scripts unless allow-listed. Keep the allow-list in `pnpm-workspace.yaml` — `onlyBuiltDependencies` (or the map-form `allowBuilds`; `pnpm approve-builds` writes it for you) — for native/codegen deps: `esbuild`, `@swc/core`, `better-sqlite3`. The failure mode is **not** an install error: install succeeds and the missing binary surfaces at runtime.
+pnpm 10 runs no dependency postinstall script unless allow-listed. Keep the allow-list in `pnpm-workspace.yaml` — `onlyBuiltDependencies` (or the map-form `allowBuilds`, which `pnpm approve-builds` writes) — for native and codegen deps: `esbuild`, `@swc/core`, `better-sqlite3`. A missing entry is **not** an install error: install succeeds and the missing binary surfaces at runtime.
 
 ## 5. Adding a member
 
@@ -82,15 +82,15 @@ pnpm 10 refuses to run dependency postinstall scripts unless allow-listed. Keep
 4. Dependencies: `workspace:*` for siblings, `catalog:` for shared externals.
 5. Publishable member: dist-based `exports`, `files: ["dist"]`, `publishConfig` — [`publishing.md`](publishing.md) §2 — and cover it with the parity check (§6).
 
-> **Agent guard — never commit a `link:` to a sibling repo on disk** (`"@nurix/contracts": "link:../../../NuStack-contracts"`). The path is machine-specific: every fresh clone and CI run breaks. Consume the published restricted package (`pnpm.md` §3); if the dep must be co-developed, that's the signal it belongs in this workspace.
+> **Agent guard — never commit a `link:` to a sibling repo on disk** (`"@nurix/contracts": "link:../../../NuStack-contracts"`). The path is machine-specific: every fresh clone and CI run breaks. Consume the published restricted package (`pnpm.md` §3); a dep that must be co-developed belongs in this workspace.
 
 ## 6. Verify — publish parity
 
-`pnpm install && pnpm -r typecheck` is the smoke test after any membership or catalog change. For workspaces with publishable members, the starter's `scripts/publish-parity.mjs` is the model harness: `npm pack` each publishable member, tarball-install into isolated copies of `fixtures/*`, build them, run `publint` + `attw` — proving consumers of the tarball get what workspace-source dev promises (a deep `src/` import or a missing `exports` entry works in dev and only breaks here). Wire it as the root `parity` script; run before first publish and after any change to an `exports` surface.
+Run `pnpm install && pnpm -r typecheck` after any membership or catalog change. A workspace with publishable members **also** needs a parity harness, because a deep `src/` import or a missing `exports` entry works in workspace-source dev and breaks only in the tarball. The starter's `scripts/publish-parity.mjs` is the model: `npm pack` each publishable member, tarball-install into isolated copies of `fixtures/*`, build them, run `publint` + `attw`. Wire it as the root `parity` script; run it before the first publish and after any change to an `exports` surface.
 
 ## 7. Quick checklist for a new workspace
 
-- [ ] `pnpm-workspace.yaml`: globs (§2) + `catalog:` + build allow-list if needed
+- [ ] `pnpm-workspace.yaml`: globs (§2) + `catalog:` + `catalogMode: strict` + build allow-list if needed
 - [ ] Root `package.json`: `private: true`, exact `packageManager` pin, `engines`, `pnpm -r` scripts
 - [ ] `tsconfig.base.json` with the strict policy set; no root `tsconfig.json`
 - [ ] First member added per §5; siblings via `workspace:*`, shared deps via `catalog:`

package/data/catalog/skills/nustack/references/publishing.md

@@ -2,21 +2,19 @@
 
 Load when: creating or publishing a `@nurix/*` package, wiring or debugging a publish workflow, or diagnosing a failed `npm publish`.
 
-How a `@nurix/*` package **ships**: the npm pipeline from `package.json` fields to a published restricted-access version. Naming a package and structuring the workspace it lives in are [`pnpm.md`](../../../rules/pnpm.md) §1–2; consuming an already-published package is `pnpm.md` §3.
+How a `@nurix/*` package **ships**: from `package.json` fields to a published version on **npmjs.org with `restricted` access**, installable only by npm users with read rights to the `nurix` org. Naming a package and structuring its workspace are [`pnpm.md`](../../../rules/pnpm.md) §1–2; consuming a published package is `pnpm.md` §3. Reference implementations: `~/dev/components` (`@nurix/components`, library) and `~/dev/etna/packages/cli` (`@nurix/etna`, CLI).
 
-`@nurix/*` packages publish to **npmjs.org with `restricted` access** — only npm users with read rights to the `nurix` org can install them. Reference implementations: `~/dev/components` (`@nurix/components`, library) and `~/dev/etna/packages/cli` (`@nurix/etna`, CLI).
-
-npmjs is the source of truth for **both publish and install**. A caching proxy may sit in front of it for reads, but it is **never a publish target** — treat a proxy URL in a publish path as a bug. And publish and install must name the **same** registry: a package published to one and installed from another 404s, and that 404 is indistinguishable from "never published", because a restricted read answers 404 rather than 401 so it doesn't leak which packages exist. (The consumer-side pairing check is [`pnpm.md`](../../../rules/pnpm.md) §3.)
+npmjs is the registry for **both publish and install**. A caching proxy may serve reads, but it is **never a publish target** — a proxy URL in a publish path is a bug. Publish and install **must** name the same registry: a restricted read answers `404`, not `401`, so a package published to one registry and installed from another looks exactly like one never published (the consumer-side pairing check is `pnpm.md` §3).
 
 ## 1. Prerequisites (one-time, org-wide)
 
-1. **npm org `nurix`** exists and you're a member with publish rights — <https://www.npmjs.com/settings/nurix/packages>.
-2. **An npm automation token** with `Read and write` for the `nurix` scope — npm → Generate New Token → Automation.
-3. **The token added as a GitHub Actions secret** named `NPM_PUBLISH_TOKEN` on every publishing repo. `NPM_PUBLISH_TOKEN` is the convention; pick another name only with a strong reason.
+1. Confirm you are a member of the npm org `nurix` with publish rights — <https://www.npmjs.com/settings/nurix/packages>.
+2. Generate an npm **Automation** token with `Read and write` on the `nurix` scope (npm → Generate New Token → Automation).
+3. Add it as the GitHub Actions secret `NPM_PUBLISH_TOKEN` on every publishing repo. Default to that name; use another only with a strong reason.
 
 ## 2. `package.json` — required fields
 
-**Private by default.** A package is born `"private": true` and stays there until someone needs it from *another repo*. Publishing is a deliberate act that creates a contract — once published, an export removed or a peer range widened is a breaking change for consumers you cannot see. Internal-to-the-repo packages never publish; they link with `workspace:*` ([`pnpm.md`](../../../rules/pnpm.md) §2). When a package does cross the boundary, the manifest carries:
+**Private by default.** A package is born `"private": true` and stays there until another repo needs it. Publishing creates a contract — once published, a removed export or a widened peer range breaks consumers you cannot see. A package used only inside its repo **never** publishes; it links with `workspace:*` (`pnpm.md` §2). A package crossing the boundary carries:
 
 ```jsonc
 {
@@ -28,12 +26,12 @@ npmjs is the source of truth for **both publish and install**. A caching proxy m
 }
 ```
 
-- **`publishConfig.access`** — `"restricted"` (recommended): visible only to `nurix`-org readers. `"public"`: world-readable (free, but only if you mean it). Omitting it on a scoped package defaults to `restricted`; be explicit anyway.
-- **`files`** — without it, npm publishes everything not in `.gitignore`, **including source**. Library → `["dist"]`; CLI (etna) → `["bin/", "data/", "README.md"]`. Don't list `package.json`/`README.md` — npm always includes them.
-- **Build to `dist` — never ship raw `src`.** A published library compiles with `tsc` (`declaration: true` + `declarationMap: true` come from `tsconfig.base.json`) and points `exports`/`types` at `./dist/*` — `types` first in each subpath block ([`pnpm.md`](../../../rules/pnpm.md) §2 owns the ordering rule). To keep the dev entry on source, use `publishConfig.exports` to swap source→dist at publish time.
-- **Build hooks** — `prepack` for build steps that must produce files in `files` (also runs on install-as-git-dep); `prepublishOnly` for publish-only steps. Either alone is fine; `@nurix/components` runs both. With the build hooked here, a publish can never ship a stale `dist`.
+- **`publishConfig.access`** — default `"restricted"`: visible only to `nurix`-org readers. `"public"` is world-readable — use it only when that is the intent. A scoped package without the field defaults to `restricted`; set it explicitly anyway.
+- **`files`** — without it, npm publishes everything not in `.gitignore`, **including source**. Library → `["dist"]`; CLI (etna) → `["bin/", "lib/", "data/"]`. Omit `package.json` and `README.md` — npm always includes them.
+- **Build to `dist` — never ship raw `src`.** A published library compiles with `tsc` (`declaration` and `declarationMap` come from `tsconfig.base.json`) and points `exports`/`types` at `./dist/*`, `types` first in each subpath block (`pnpm.md` §2 owns the ordering). To keep the dev entry on source, swap source→dist at publish time with `publishConfig.exports`.
+- **Build hooks** — `prepack` for build steps that must produce files in `files` (also runs on install-as-git-dep); `prepublishOnly` for publish-only steps. Either alone is fine; `@nurix/components` builds and verifies its types in `prepublishOnly`. With the build hooked here, a publish can never ship a stale `dist`.
 - **Host singletons are `peerDependencies`** — `react`, `react-dom`, the framework client — so consumers keep exactly one copy; **never** bundle them. Apps depend on them directly.
-- **Dependencies carry registry specs only** — **no** `file:`/`link:` (the workspace-root boundary, [`pnpm.md`](../../../rules/pnpm.md) §2). `workspace:*` between workspace members is fine: `pnpm publish` rewrites it into a real range.
+- **Dependencies carry registry specs only** — **no** `file:`/`link:` (the workspace-root boundary, `pnpm.md` §2). `workspace:*` between members is fine: `pnpm publish` rewrites it into a real range.
 - **Other useful fields** — `type: "module"`, `engines.node`, `bin` (CLIs), `main`/`module`/`types`/`exports` (libraries), `sideEffects: ["**/*.css"]`, `repository` (with `directory` for monorepos), `license: "UNLICENSED"`.
 
 ## 3. The publish workflow (generic template)
@@ -75,23 +73,23 @@ jobs:
       - run: git push --follow-tags # pushes the bump commit AND the v<version> tag npm created
 ```
 
-**Why dual-trigger is safe** — three safeguards prevent an infinite publish loop: (1) `paths:` scopes the push trigger to artifact-affecting files; (2) `[skip ci]` in the bump commit makes GitHub skip the workflow that bump would otherwise re-trigger; (3) `concurrency: cancel-in-progress: false` queues near-simultaneous merges instead of racing for a version number.
+**Keep all three loop safeguards** — dropping any one lets the dual trigger publish in a loop or race: `paths:` scopes the push trigger to artifact-affecting files; `[skip ci]` in the bump commit stops that commit re-triggering the workflow; `cancel-in-progress: false` queues near-simultaneous merges instead of racing for a version number.
 
-**`registry-url` is load-bearing** — without `registry-url: https://registry.npmjs.org` on `setup-node`, it never writes the `.npmrc` line that uses `$NODE_AUTH_TOKEN`, and the publish falls back to anonymous auth and fails.
+**`registry-url` is load-bearing** — without it on `setup-node`, no `.npmrc` line reads `$NODE_AUTH_TOKEN`, and the publish falls back to anonymous auth and fails.
 
-**The token never enters the repo checkout** — `setup-node` writes its auth `.npmrc` outside the workspace, so the bump commit the job pushes cannot pick it up; a hand-rolled auth line goes to `$HOME/.npmrc` for the same reason, never a repo-path `.npmrc`. Expand the token in the shell step that writes it (`echo "//registry.npmjs.org/:_authToken=$NPM_PUBLISH_TOKEN" >> "$HOME/.npmrc"`) rather than leaving a literal `${VAR}` for the npm client to expand at read time — read-time expansion silently breaks in any later step that lacks the variable.
+**The token never enters the repo checkout** — `setup-node` writes its auth `.npmrc` outside the workspace, so the pushed bump commit cannot pick it up; a hand-rolled auth line goes to `$HOME/.npmrc`, **never** a repo-path `.npmrc`. Expand the token in the shell step that writes it (`echo "//registry.npmjs.org/:_authToken=$NPM_PUBLISH_TOKEN" >> "$HOME/.npmrc"`), never a literal `${VAR}` left for npm to expand at read time — that breaks silently in any later step lacking the variable.
 
-**A pnpm workspace publishes with `pnpm publish --no-git-checks`** — swap it into the publish step above (and into flow C, §4). Only pnpm rewrites `catalog:`/`workspace:` specifiers into real ranges (§6); `--no-git-checks` is required because pnpm otherwise refuses to publish from a non-release branch or from a tree carrying the bump commit the previous step just made. `npm publish` stays correct only for a single-package repo on an npm lockfile.
+**A pnpm workspace publishes with `pnpm publish --no-git-checks`** — swap it into the publish step above and into flow C (§4). Only pnpm rewrites `catalog:`/`workspace:` specifiers into real ranges (§6); without `--no-git-checks`, pnpm refuses to publish from a non-release branch or from a tree carrying the bump commit the previous step made. `npm publish` is correct only for a single-package repo on an npm lockfile.
 
 ## 4. The three ways to ship
 
-- **A. Auto on merge (common).** Land on the default branch; if a `paths:`-filtered file changed, the workflow fires and ships a patch.
-- **B. Manual dispatch (minor/major/none).** **Actions → Publish to npm → Run workflow**, pick `bump = minor|major` — or `none`, which publishes the current version as-is: the CI-side bootstrap for a first publish when a repo ships exclusively from CI (§7's checklist bootstraps from a local publish instead; both paths are sanctioned).
-- **C. Local (CI down / one-off / pipeline bootstrap):** `npm version <patch|minor|major>` → publish → `git push --follow-tags` — sanctioned, at the cost that it bypasses CI's build, lockfile, and version-bump discipline. In a pnpm workspace the publish command is **`pnpm publish --no-git-checks`** (never `npm publish` — the catalog-protocol pitfall in §6; the flag rationale is §3); in a subdirectory of the repo root, `npm version` needs `--no-git-tag-version` plus a manual commit + tag.
+- **A. Auto on merge (default).** Land on the default branch; a change to a `paths:`-filtered file fires the workflow and ships a patch.
+- **B. Manual dispatch (minor/major/none).** **Actions → Publish to npm → Run workflow**, pick `bump = minor|major` — or `none`, which publishes the current version as-is: the first-publish bootstrap for a repo that ships only from CI. §7's checklist bootstraps from a local publish instead; both are sanctioned.
+- **C. Local (CI down, one-off, pipeline bootstrap).** `npm version <patch|minor|major>` → publish → `git push --follow-tags`. Sanctioned, at the price of bypassing CI's build, lockfile, and version-bump discipline. In a pnpm workspace the publish command is **`pnpm publish --no-git-checks`**, **never** `npm publish` (the catalog-protocol pitfall, §6); in a subdirectory of the repo root, `npm version` needs `--no-git-tag-version` plus a manual commit and tag.
 
-Local auth uses two tokens, two homes: a **read** token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=…`) for `npm install`, and `NPM_PUBLISH_TOKEN` as an env var (sourced from `~/.zsh_secrets` or equivalent, **not** in `.npmrc` or the repo) for `npm publish`.
+Local auth uses two tokens in two homes: a **read** token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=…`) for `npm install`, and `NPM_PUBLISH_TOKEN` as an env var (sourced from `~/.zsh_secrets` or equivalent, **never** in `.npmrc` or the repo) for `npm publish`.
 
-> **Agent guard — if `NPM_PUBLISH_TOKEN` isn't in the environment, do not work around it.** No `npm login` to swap the user's auth, no rewriting `~/.npmrc`, no substituting the read token (it lacks publish rights → `403`), no `--registry` overrides, no temp-file token. Instead **stop and report**: "This repo can't publish locally — `NPM_PUBLISH_TOKEN` isn't set. Source `~/.zsh_secrets` (or wherever you keep it) and re-run, or trigger the CI workflow." Some users publish exclusively from CI — that's the default path for a reason.
+> **Agent guard — if `NPM_PUBLISH_TOKEN` isn't in the environment, never work around it.** No `npm login` swapping the user's auth, no rewriting `~/.npmrc`, no substituting the read token (it lacks publish rights → `403`), no `--registry` override, no temp-file token. **Stop and report**: "This repo can't publish locally — `NPM_PUBLISH_TOKEN` isn't set. Source `~/.zsh_secrets` (or wherever you keep it) and re-run, or trigger the CI workflow."
 
 Verify after any flow: `https://www.npmjs.com/package/@nurix/<name>` and a clean-dir `npx @nurix/<name>@latest`.
 
@@ -99,27 +97,30 @@ Verify after any flow: `https://www.npmjs.com/package/@nurix/<name>` and a clean
 
 When the package lives in `packages/<pkg>/` of a multi-package repo:
 
-- **`working-directory: packages/<pkg>`** on the bump and publish steps so they operate on the right `package.json`.
+- **`working-directory: packages/<pkg>`** on the bump and publish steps, so they act on the right `package.json`.
 - **Scoped concurrency** — `group: publish-<pkg>` lets sibling packages publish in parallel.
-- **Tag prefix — only with multiple tagging packages.** `npm version --tag-version-prefix="<pkg>-v"` (→ `<pkg>-v0.2.0`) is worth it only when more than one package cuts release tags, so they don't collide. A single publishable package (etna's case, even though it's laid out as a monorepo) uses plain `v0.2.0`.
-- **One workflow file per published package** — each `publish-<pkg>.yml` owns its `paths:` filter, `working-directory`, and concurrency group. A single shared workflow couples every package's release cadence and republishes siblings on unrelated changes.
-- **Publish dependencies first.** If package `A` depends on `B` by `workspace:^`, `B` must already exist on the registry — otherwise `A`'s rewritten range resolves to nothing for every consumer.
+- **Tag prefix only when more than one package cuts release tags** — `npm version --tag-version-prefix="<pkg>-v"` (→ `<pkg>-v0.2.0`) keeps their tags from colliding.
+- **One workflow file per published package** — each `publish-<pkg>.yml` owns its `paths:` filter, `working-directory`, and concurrency group. One shared workflow couples every package's release cadence and republishes siblings on unrelated changes.
+- **Publish dependencies first.** If `A` depends on `B` by `workspace:^`, `B` **must** already exist on the registry, or `A`'s rewritten range resolves to nothing for every consumer.
 
-A repo with one publishable package only needs `working-directory`; skip the prefix, and concurrency scoping is optional.
+A repo with one publishable package needs only `working-directory`: plain `v0.2.0` tags, concurrency scoping optional.
 
 ## 6. Common pitfalls
 
-- **402 Payment Required** — `access: "public"` on an org without a plan for free public scoped packages. Use `"restricted"` (or upgrade the plan).
-- **403 Forbidden** — `NPM_PUBLISH_TOKEN` missing/wrong, or its user lacks `nurix` write access, or it's a read-only (not Automation) token.
-- **"Cannot publish over previously published version x.y.z"** — a bump ran but publish failed and was re-run without rebasing. `git reset` the bump and let CI re-bump, or `npm version patch && git push --follow-tags && npm publish`.
-- **Publish succeeds but `npx @nurix/foo` is "command not found"** — no `bin` field, or `bin` points outside `files`, or the script is missing its `#!/usr/bin/env node` shebang.
-- **"Git working directory not clean" on `npm version`** — the checkout has untracked/modified files; build only into `.gitignore`d paths (the components repo builds into `dist/`).
-- **Published tarball contains source** — missing `files` in `package.json`. Add `["dist"]` and republish.
-- **pnpm consumers fail with "external package declared a dependency using the catalog protocol"** — the package was published with `npm publish` from a pnpm workspace: only **`pnpm publish`** rewrites `catalog:`/`workspace:` specifiers to real versions; npm ships them verbatim. A workspace member must always publish via `pnpm publish` (locally too, not just CI). Deprecate the broken version and republish.
-- **Tarball has no `dist/` even though `prepublishOnly` ran clean + build** — a stale `tsconfig.tsbuildinfo` (which `incremental: true` writes *next to tsconfig.json*, outside `dist/`) survived `rm -rf dist`, so `tsc` trusted it and silently emitted nothing. The `clean` script must purge it: `rm -rf dist *.tsbuildinfo`. The parity harness catches this class before it ships.
-- **Auto-publish fires too often** — no `paths:` filter or one that's too broad. Tighten it to artifact-affecting files, or drop the push trigger for `workflow_dispatch`-only.
-- **Workflow loops forever** — the bump commit lacks `[skip ci]`. Invoke `npm version` with `-m "chore: release v%s [skip ci]"`.
-- **A normal commit silently skips its own push** — the inverse trap. GitHub scans the head commit's **whole message** (subject _and_ body) for skip directives (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***`). If any hand-written commit merely _mentions_ the literal token in prose, the entire push is skipped and the publish never fires (symptom: branch moved, paths matched, Actions on — yet zero runs for the SHA). Never write the literal token in a commit message or PR body unless you mean it; to ship a push that carried it by accident, re-trigger via **Run workflow** / `gh workflow run … --ref dev`.
+| Symptom | Cause → fix |
+| --- | --- |
+| **402 Payment Required** | `access: "public"` on an org without a plan for free public scoped packages → use `"restricted"` (or upgrade the plan) |
+| **403 Forbidden** | `NPM_PUBLISH_TOKEN` missing or wrong, its user lacks `nurix` write access, or it is a read-only (not Automation) token |
+| **"Cannot publish over previously published version x.y.z"** | a bump ran, the publish failed, and it was re-run without rebasing → `git reset` the bump and let CI re-bump, or `npm version patch && git push --follow-tags && npm publish` |
+| **Publish succeeds but `npx @nurix/foo` is "command not found"** | no `bin` field, `bin` points outside `files`, or the script lacks its `#!/usr/bin/env node` shebang |
+| **"Git working directory not clean" on `npm version`** | the checkout has untracked or modified files → build only into `.gitignore`d paths (`dist/`) |
+| **Published tarball contains source** | `files` missing from `package.json` → add `["dist"]` and republish |
+| **Auto-publish fires too often** | no `paths:` filter, or one too broad → tighten it to artifact-affecting files, or drop the push trigger for `workflow_dispatch` only |
+| **Workflow loops forever** | the bump commit lacks `[skip ci]` → invoke `npm version` with `-m "chore: release v%s [skip ci]"` |
+
+- **pnpm consumers fail with "external package declared a dependency using the catalog protocol"** — the package went out via `npm publish` from a pnpm workspace, which ships `catalog:`/`workspace:` specifiers verbatim. A workspace member **always** publishes via `pnpm publish`, locally as well as in CI. Deprecate the broken version and republish.
+- **Tarball has no `dist/` though `prepublishOnly` ran a clean build** — `incremental: true` writes `tsconfig.tsbuildinfo` *next to `tsconfig.json`*, outside `dist/`; a stale one survives `rm -rf dist`, so `tsc` trusts it and emits nothing. The `clean` script **must** purge it: `rm -rf dist *.tsbuildinfo`. The parity harness catches this class before it ships.
+- **A normal commit silently skips its own push** — GitHub scans the head commit's **whole message**, subject _and_ body, for skip directives (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***`); a hand-written commit that merely _mentions_ one skips the entire push, and the publish never fires (symptom: branch moved, paths matched, Actions on — zero runs for the SHA). **Never** write a literal skip token in a commit message or PR body unless you mean it; to ship a push that carried one by accident, re-trigger via **Run workflow** / `gh workflow run … --ref dev`.
 
 ## 7. Quick checklist for a new `@nurix/*` package
 
@@ -128,5 +129,5 @@ A repo with one publishable package only needs `working-directory`; skip the pre
 - [ ] Name follows [`pnpm.md`](../../../rules/pnpm.md) §1; if it's a workspace member, boundaries follow `pnpm.md` §2
 - [ ] `.github/workflows/publish.yml` from §3
 - [ ] `NPM_PUBLISH_TOKEN` secret added to the repo
-- [ ] First publish from local (flow C, §4) to verify the pipeline end-to-end, then a no-op commit to verify CI — a repo that ships exclusively from CI bootstraps with `bump = none` instead (§4B)
+- [ ] First publish from local (flow C, §4) to verify the pipeline end to end, then a no-op commit to verify CI — or, for a repo that ships only from CI, bootstrap with `bump = none` (§4B)
 - [ ] README notes the `@nurix` scope so consumers know they need org access

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "e13062907688",
+    "fingerprint": "899bed2c91e6",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/harness.json

@@ -29,5 +29,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "8b47c959f89f"
+  "digest": "068ff439e1f9"
 }

package/data/harnesses/code/skills/boundary/SKILL.md

@@ -7,35 +7,38 @@ description: "Use when a plan or diff might break a cross-cutting contract. Boun
 
 You diagnose whether a plan's changes would break an application boundary.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Your job is to find those edges in the plan's path _before_ execution.
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Find those edges in the plan's path _before_ execution.
 
-**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — a change that fails the build loudly needs no diagnostic. Spend your reading on the edges with no static link.
+**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — spend your reading on the edges with no static link.
 
 ## Contract sources
 
 Three layers tell you what to look for; the code tells you what exists.
 
-- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
-- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
-- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
-
-The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
+- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md): the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal fix, and severity, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
+- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code; each pack carries one technology area's detect patterns, gotchas, and safe-change sequences. Load **only** the packs the touch list exhibits. The packs are a floor, not a fence: a contract no pack covers is still in scope — diagnose it from its mechanism and report it if it passes the litmus.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how a greenfield plan, with no code to trace, still gets checked.
 
 ## Run
 
-**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff / named code area for non-plan work. Everything below is identical either way; a diff's hunks stand in for the plan's steps.
+**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff or named code area for non-plan work, where the diff's hunks stand in for the plan's steps. Steps 1–5 are identical either way; the report's **Missing plan subsections** and **Docs the plan's ledger missed** sections, and step 6, apply only to a plan.
+
+1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities or state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+
+2. **Identify the contracts.** Read each touched file and its immediate imports. Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
 
-1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+3. **Trace the other side.** The danger lives on the side the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`, doctrine as the doc path. At ≳10 contracts, fan the tracing out to parallel sub-agents — one per pack area, each prompt self-contained with its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
 
-2. **Identify the contracts.** Read each touched file (and its immediate imports). Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
+4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Grade it:
 
-3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`; record doctrine as the doc path. When the touch list is large (≳10 contracts), fan the tracing out to parallel sub-agents — one per pack area, each with a self-contained prompt naming its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
+   | Severity | Meaning |
+   | --- | --- |
+   | **CRITICAL** | Can corrupt persisted data, or open an auth/money path — trust-invariants and persisted or replayed shapes live here |
+   | **HIGH** | Silent cross-module breakage that ships green |
+   | **MEDIUM** | Drift-prone coupling not yet broken (string-matched, duplicated constants) |
+   | **LOW** | Smell |
 
-4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Severity:
-   - **CRITICAL** — can corrupt persisted data, or open an auth/money path.
-   - **HIGH** — silent cross-module breakage that would ship green.
-   - **MEDIUM** — drift-prone coupling (string-matched, duplicated constants).
-   - **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH.
+   Loud, immediately visible runtime breakage caps at HIGH. Severity is intrinsic to the finding, never curved — three genuine CRITICALs in a small repo is signal, not inflation.
 
 5. **Report in chat:**
 
@@ -61,15 +64,23 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
    | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
-   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+   **Fill the doc cross-check from the touch list you already hold:** resolve its paths against the ownership index and compare the result to the plan's **Doc Obligations** rows. The plan's author wrote that ledger and nobody else checks it — a `None` that contradicts your touch list is the failure this section catches. Report the gap; **never** edit the ledger yourself.
+
+   **BLOCK** = any CRITICAL; a blocked plan folds the amendments and re-runs the check. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the pack entry's **Safe change** or the mechanism's **Universal fix**.
+
+6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly one of:
 
-   **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
+   | Verdict | Segment |
+   | --- | --- |
+   | PASS | `Boundary: passed YYYY-MM-DD` |
+   | PASS WITH AMENDMENTS | `Boundary: passed YYYY-MM-DD` — written only once the amendments are folded |
+   | BLOCK | `Boundary: blocked YYYY-MM-DD` |
 
-6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps exactly this segment — implementation edits inside the plan's scope stay blocked while it reads `Boundary: pending` (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
+   The compliance hook greps exactly this segment and blocks implementation edits inside the plan's scope until it reads `passed` — `pending` and `blocked` wall alike (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line gets one added; never skip the write-back.
 
 ## Rules
 
-- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan in the same pass, then writes the segment to `passed`; a plan is not finished until it does. The single write you own is the plan's `Gates:` line (step 6), your segment only.
-- **Verify in source.** Never flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
-- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it isn't a violation — it's a **new edge**: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
+- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan; a plan is not finished until its segment reads `passed`. The single write you own is the plan's `Gates:` line (step 6), your segment only.
+- **Verify in source.** **Never** flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
+- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it is a **new edge**, not a violation: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
 - **A clean report is valid.** Zero violations means say so — the coverage table is the evidence it was checked, not skipped. Don't pad findings.

package/data/harnesses/code/skills/boundary/references/index.md

@@ -1,16 +1,14 @@
 # Pack routing index
 
-Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes. Several packs matching is normal (a full-stack feature typically routes 2–4). A technology matching nothing here is still in scope — diagnose it from its mechanism, and check `packs/generic-tail.md` for a thin entry.
+Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes — a full-stack feature typically routes 2–4. A technology matching no row has a thin entry in `packs/generic-tail.md` or none; either way, diagnose it from its mechanism.
 
 | Pack | Load when the touch list shows |
 | --- | --- |
 | `packs/persistence.md` | `schema.ts`, `init.sql`, `sqliteTable(`, `drizzle-kit`, `pgTable`, migrations, `*.seed.sql`, seed generators, JSON columns, `pgEnum`, pgvector, Redis `get`/`set` caching |
 | `packs/wire-api.md` | Express routes/middleware (`app.use(`, `router.`), `res.json({ status`, zod schemas on requests, axios clients/interceptors, `cors(`, inbound webhooks, `rateLimit(` |
-| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
+| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `design.tokens.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
 | `packs/auth.md` | `jwtVerify(`/jose, `betterAuth(`/`auth.api.`, session cookies, CSRF, OAuth callbacks/`redirect_uri`, `tenantId`/`organizationId` scoping, password hashing, auth middleware mounts |
 | `packs/cloudflare.md` | `wrangler.jsonc`/`wrangler.toml`, `env.X` bindings, `extends DurableObject`/`[[migrations]]`, KV/R2/D1/Queues, `scheduled(`/crons, `WorkerEntrypoint`, `compatibility_date`, static assets config |
 | `packs/async-messaging.md` | BullMQ (`new Queue(`/`new Worker(`), Redis pub/sub or Streams, WebSockets/socket.io, SSE (`text/event-stream`), channel-name templates, outbound webhook senders |
 | `packs/build-config-runtime.md` | `package.json` (deps/`exports`/scripts/`packageManager`), lockfiles, `.env*`, tsconfig `paths`, Dockerfiles/compose, `.github/workflows/`, pino config, `trust proxy`, ports/healthchecks |
 | `packs/generic-tail.md` | GraphQL, gRPC/protobuf, tRPC, OpenAPI codegen, Kafka/schema registry/CDC, workflow engines, event sourcing, Postgres RLS/pooling/collation, SSR/hydration, module federation, i18n, analytics plans, hosted feature flags, K8s probes/shutdown/limits, service mesh, IaC outputs, SAML, Lambda, IPC |
-
-Two files never route — they always load: `mechanisms.md` (the seven failure mechanisms + domain contracts) and this index.