@nurix/etna 0.1.3 → 0.2.0

package/README.md

@@ -1,13 +1,6 @@
 # @nurix/etna
 
-CLI to bootstrap a project with a Nurix harness. Produces the same on-disk state as running
-
-```
-/plugin marketplace add nurixlabs/skills
-/plugin install nurix-harness@nurixlabs
-```
-
-inside Claude Code, plus drops the harness's `CLAUDE.md` at the project root. See [`../../harness/README.md`](../../harness/README.md) for what a harness is and why the install model is designed this way.
+CLI to bootstrap a project with a Nurix harness. Copies the harness's `CLAUDE.md`, skills, agents, rules, and scripts into the project so they live with the code — version-controllable, editable per project, and visible without leaving the repo.
 
 ## Usage
 
@@ -17,46 +10,60 @@ From the root of the project you want to bootstrap:
 npx @nurix/etna nurix-harness
 ```
 
-After this completes, three things have changed on disk:
+After this completes:
 
 ```
 your-project/
-├── CLAUDE.md                          ← bundled in this package; the harness's policy
+├── CLAUDE.md             ← harness policy (backup of any existing file is kept)
 └── .claude/
-    └── settings.json                  ← enabledPlugins["nurix-harness@nurixlabs"] = true
-
-~/.claude/settings.json                ← extraKnownMarketplaces["nurixlabs"] registered
+    ├── skills/           ← documentation, introspect, workflow-mapper
+    ├── agents/           ← spec-mode, maintenance, contract-monitor, …
+    ├── rules/            ← general.md, nomenclature.md
+    └── scripts/          ← build-ownership-index.sh, check-doc-drift.sh
 ```
 
-That's the entire footprint. Open Claude Code in the project; on next session start it resolves `nurix-harness@nurixlabs`, clones `nurixlabs/skills` into `~/.claude/plugins/marketplaces/`, fills the plugin cache at `~/.claude/plugins/cache/nurixlabs/nurix-harness/<version>/`, and loads the plugin. The CLI does not touch any of those Claude Code internals itself — that's deliberate (see [Installation goals](../../harness/README.md#installation-goals)).
+That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up project-scoped agents/skills/rules/scripts on its next session start.
 
-If Claude Code is already running, run `/reload-plugins`.
+Re-run `npx @nurix/etna nurix-harness` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. The previous `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>`.
+
+## Migrating from 0.1.x
+
+`0.1.x` registered the harness as a Claude Code plugin via the `nurixlabs/skills` marketplace. `0.2.0` switches to direct file installation. When you re-run `etna` on a project that has a `0.1.x` install, the CLI removes the stale `enabledPlugins["<plugin>@nurixlabs"]` entry from `<project>/.claude/settings.json` so Claude Code doesn't double-load the same content from the global plugin cache.
+
+The `nurixlabs` marketplace entry in `~/.claude/settings.json` is harmless to leave (it doesn't load anything by itself) — remove it manually if you want.
 
 ## Available harnesses
 
 Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json`.
 
-| Plugin name | Harness folder in etna | What it ships |
+| Plugin name | Source in etna | What it ships |
 |---|---|---|
-| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — governance agents, baseline workflow skills, ownership/drift scripts |
+| `nurix-harness` | [`plugins/nurix-harness.md`](../../plugins/nurix-harness.md) → top-level catalogs | Governance agents, baseline workflow skills, ownership/drift scripts |
+| `kb-agi` | [`plugins/kb-agi.md`](../../plugins/kb-agi.md) → top-level catalogs | Knowledge-vault scaffolding |
 
 ## How it works
 
-1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder and the marketplace metadata.
-2. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md` (backing up any existing one to `CLAUDE.md.bak.<ISO-timestamp>`).
-3. Adds the marketplace entry to `~/.claude/settings.json` under `extraKnownMarketplaces`.
-4. Adds `<plugin-name>@<marketplace>: true` to `./.claude/settings.json` under `enabledPlugins`.
+Each harness has a folder under `etna/harness/<name>/` with:
+- `CLAUDE.md` — the project-root policy file
+- `index.md` — symlinked to `../../plugins/<plugin>.md` (the manifest)
 
-No GitHub fetch. No `.claude/plugins/<name>/` folder. Claude Code's plugin resolver handles all of that on next launch.
+The plugin manifest's YAML frontmatter declares which top-level `agents/`, `skills/`, `rules/`, and `scripts/` belong to that plugin:
 
-## Why two sources
+```yaml
+---
+name: nurix-harness
+skills: [documentation, introspect, workflow-mapper]
+agents: [spec-mode, maintenance, contract-monitor, …]
+scripts: [build-ownership-index, check-doc-drift]
+rules: [general, nomenclature]
+---
+```
 
-- **Plugin content** lives in the marketplace (`nurixlabs/skills`) and is fetched by Claude Code at session start — always the latest CI-published version.
-- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. A plugin cannot ship a project-root `CLAUDE.md` (Claude Code's plugin spec doesn't support it), so the CLI ships that half itself. Harness policy changes warrant a package version bump.
+`scripts/build-data.js` (run by `prepack`) resolves each manifest against the catalogs and bundles the result into `data/harnesses/<folder>/`. The installer (`bin/etna.js`) reads from that bundle at install time. No GitHub fetch at runtime — the published npm package contains everything.
 
 ## Building / contributing
 
-`data/` is generated. Don't edit by hand. To regenerate after touching anything under `etna/harness/`:
+`data/` is generated. Don't edit by hand. To regenerate after editing the etna catalogs or manifests:
 
 ```sh
 cd packages/cli
@@ -67,4 +74,4 @@ npm run build:data
 
 ## Publishing
 
-CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default.
+CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default. The `NPM_PUBLISH_TOKEN` GitHub Actions secret must be a granular access token with **Bypass 2FA** enabled — classic automation tokens are rejected by the npmjs.com 2FA policy on the `nurix-tools` account.

package/bin/etna.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <plugin-name>` — bootstrap a Nurix harness in the current directory.
-// Produces the same on-disk state as running `/plugin marketplace add <repo>` followed by
-// `/plugin install <plugin>@<marketplace>` inside Claude Code, plus drops the harness's
-// CLAUDE.md at the project root. Claude Code's plugin resolver fills the cache on next launch.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, lstatSync } from 'node:fs';
-import { homedir } from 'node:os';
+// `npx @nurix/etna <plugin-name>` — copy a Nurix harness into the current
+// directory. Drops the harness's CLAUDE.md at the project root and copies its
+// skills, agents, rules, and scripts into <project>/.claude/. No marketplace,
+// no plugin enablement — files live in the project, version-controlled and
+// editable per project. Re-run `etna` to refresh.
+
+import {
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+    renameSync,
+    copyFileSync,
+    cpSync,
+    readdirSync,
+    lstatSync,
+} from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -14,17 +24,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 const dataDir = join(pkgRoot, 'data');
 
+// Subfolders bundled inside each harness payload that map 1:1 onto
+// <project>/.claude/<name>/. Order matches Claude Code's own folder layout.
+const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts'];
+
 function usage() {
     const idx = loadHarnessIndex();
     console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const names = Object.keys(idx.plugins);
     if (names.length) {
-        console.log(`Available harnesses (plugin → marketplace):`);
-        for (const name of names) {
-            console.log(`  ${name.padEnd(20)} → ${idx.marketplace.name}`);
-        }
+        console.log(`Available harnesses:`);
+        for (const name of names) console.log(`  ${name}`);
     }
-    console.log(`\nMarketplace: ${idx.marketplace.source.repo} (github)`);
     console.log();
 }
 
@@ -41,6 +52,14 @@ function die(msg, code = 1) {
     process.exit(code);
 }
 
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
 // Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
 function backupIfExists(path) {
     if (!existsSync(path) && !isSymlink(path)) return null;
@@ -50,14 +69,6 @@ function backupIfExists(path) {
     return backup;
 }
 
-function isSymlink(path) {
-    try {
-        return lstatSync(path).isSymbolicLink();
-    } catch {
-        return false;
-    }
-}
-
 function readJson(path) {
     if (!existsSync(path)) return {};
     try {
@@ -73,31 +84,44 @@ function writeJson(path, value) {
     writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
 }
 
-// Register the marketplace in ~/.claude/settings.json (extraKnownMarketplaces).
-// Mirrors what `/plugin marketplace add <owner>/<repo>` writes, plus opts the
-// marketplace into auto-updates (off by default for non-Anthropic marketplaces).
-function registerMarketplace(marketplace) {
-    const path = join(homedir(), '.claude', 'settings.json');
-    const settings = readJson(path);
-    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
-    settings.extraKnownMarketplaces[marketplace.name] = {
-        source: marketplace.source,
-        autoUpdate: true,
-    };
-    writeJson(path, settings);
-    return path;
+// Copy the harness's bundled .claude/<subdir>/ contents into <project>/.claude/<subdir>/,
+// merging with whatever's already there. Existing same-named entries are overwritten so
+// re-running `etna` always refreshes harness-provided content. Returns count copied.
+function copyHarnessSubdir(bundledSubdir, projectSubdir) {
+    if (!existsSync(bundledSubdir)) return 0;
+    mkdirSync(projectSubdir, { recursive: true });
+    let copied = 0;
+    for (const entry of readdirSync(bundledSubdir, { withFileTypes: true })) {
+        const src = join(bundledSubdir, entry.name);
+        const dest = join(projectSubdir, entry.name);
+        cpSync(src, dest, { recursive: true, force: true });
+        copied += 1;
+    }
+    return copied;
 }
 
-// Add `<plugin>@<marketplace>: true` to <target>/.claude/settings.json under enabledPlugins.
-// Mirrors what `/plugin install <plugin>@<marketplace>` writes at project scope.
-function enablePlugin(targetDir, pluginName, marketplaceName) {
-    const path = join(targetDir, '.claude', 'settings.json');
-    const settings = readJson(path);
-    settings.enabledPlugins = settings.enabledPlugins || {};
-    const key = `${pluginName}@${marketplaceName}`;
-    settings.enabledPlugins[key] = true;
-    writeJson(path, settings);
-    return { path, key };
+// Clean up any leftover marketplace/enabledPlugins entries from a previous 0.1.x
+// install. After 0.2.0 we don't use the marketplace flow at all — leaving stale
+// entries causes Claude Code to also resolve the plugin from the global cache,
+// double-loading the same skills under a different namespace.
+function migrateFromPluginInstall(targetDir, pluginName) {
+    const removed = [];
+    const projectSettingsPath = join(targetDir, '.claude', 'settings.json');
+    if (existsSync(projectSettingsPath)) {
+        const s = readJson(projectSettingsPath);
+        if (s.enabledPlugins) {
+            const keys = Object.keys(s.enabledPlugins).filter((k) =>
+                k.startsWith(`${pluginName}@`),
+            );
+            for (const k of keys) {
+                delete s.enabledPlugins[k];
+                removed.push(`enabledPlugins["${k}"] in ${projectSettingsPath}`);
+            }
+            if (Object.keys(s.enabledPlugins).length === 0) delete s.enabledPlugins;
+            writeJson(projectSettingsPath, s);
+        }
+    }
+    return removed;
 }
 
 async function main(args) {
@@ -115,34 +139,36 @@ async function main(args) {
         );
     }
 
-    const bundledClaude = join(dataDir, 'harnesses', harnessFolder, 'CLAUDE.md');
-    if (!existsSync(bundledClaude)) {
+    const bundledHarnessDir = join(dataDir, 'harnesses', harnessFolder);
+    const bundledClaudeMd = join(bundledHarnessDir, 'CLAUDE.md');
+    if (!existsSync(bundledClaudeMd)) {
         die(`Bundled CLAUDE.md missing for harness '${harnessFolder}'. Rebuild package data.`);
     }
 
     const targetDir = process.cwd();
     const claudeMdDest = join(targetDir, 'CLAUDE.md');
-    const marketplace = idx.marketplace;
-    const fqKey = `${pluginName}@${marketplace.name}`;
 
-    console.log(`\nInstalling ${fqKey} into ${targetDir}`);
+    console.log(`\nInstalling ${pluginName} into ${targetDir}`);
 
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
 
-    copyFileSync(bundledClaude, claudeMdDest);
+    copyFileSync(bundledClaudeMd, claudeMdDest);
     console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
 
-    const marketplacePath = registerMarketplace(marketplace);
-    console.log(`  registered marketplace '${marketplace.name}' → ${marketplacePath}`);
+    for (const sub of PLUGIN_SUBDIRS) {
+        const count = copyHarnessSubdir(
+            join(bundledHarnessDir, sub),
+            join(targetDir, '.claude', sub),
+        );
+        if (count > 0) console.log(`  copied ${count} ${sub} → ${targetDir}/.claude/${sub}/`);
+    }
 
-    const { path: enablePath } = enablePlugin(targetDir, pluginName, marketplace.name);
-    console.log(`  enabled '${fqKey}' → ${enablePath}`);
+    const migrated = migrateFromPluginInstall(targetDir, pluginName);
+    for (const entry of migrated) console.log(`  removed stale ${entry}`);
 
     console.log(`\nDone. Open Claude Code in ${targetDir}.`);
-    console.log(
-        `It will fetch ${marketplace.source.repo}, install ${pluginName}, and load it on next session start.\n`,
-    );
+    console.log(`Re-run \`npx @nurix/etna ${pluginName}\` anytime to refresh harness content.\n`);
 }
 
 main(process.argv.slice(2)).catch((e) => {

package/data/harness-index.json

@@ -1,11 +1,4 @@
 {
-    "marketplace": {
-        "name": "nurixlabs",
-        "source": {
-            "source": "github",
-            "repo": "nurixlabs/skills"
-        }
-    },
     "plugins": {
         "nurix-harness": "code",
         "kb-agi": "kb-agi"

package/data/harnesses/code/agents/change-review.md

@@ -0,0 +1,80 @@
+---
+name: change-review
+description: Velocity analysis — produces commit heatmap, risk-zone identification (high churn + low guardrail coverage), stabilization signals, team distribution. Consumes `git-history`'s CSV output rather than reanalyzing commits. Use when planning where to invest in better guardrails or rules.
+tools: Read, Glob, Grep, Bash
+model: inherit
+---
+
+# Change-Review Agent
+
+You analyze code-change velocity over time to identify risk zones. Where `git-history` classifies *what* changed (module, impact, severity), you ask *where is change accelerating or decelerating* — and whether guardrail coverage matches the risk.
+
+You answer: "where should the tech lead invest in better guardrails or rules next?"
+
+## Before Starting
+
+1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, and known concentration risks.
+2. If `./docs/memory/git-history.md` or a recent CSV from the git-history agent exists, prefer it as input — don't re-classify commits. If no recent run exists, ask the user to run `git-history` first or fall back to a direct `git log` analysis.
+3. Read `./docs/operations/guardrails.md` if it exists. Risk-zone scoring is "high churn + low guardrail coverage" — without guardrails, you can only produce a heatmap, not risk zones.
+4. Read `./docs/OWNERSHIP_INDEX.md` if it exists, to map churn to owning feature docs.
+
+## Step 1: Velocity Heatmap
+
+Compute commits-per-module over rolling windows:
+
+- **1 week** — what's hot right now
+- **1 month** — current rhythm
+- **3 months** — quarter-level pattern
+
+Aggregate by top-level module (`src/{module}/`). Report:
+
+| Module | Commits 1w | Commits 1m | Commits 3m | Trend |
+|--------|-----------:|-----------:|-----------:|-------|
+
+Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
+
+## Step 2: Risk Zones
+
+For each module with high churn (top quartile in 1m window), check guardrail coverage:
+
+- Does `docs/operations/guardrails.md` mention this module?
+- Is the module's `owns` doc up to date? (cross-reference with maintenance agent's last drift check if available)
+- Does the module appear in `docs/routing.md`?
+
+Flag risk zones: high churn × low coverage. These are where silent breakage is most likely.
+
+## Step 3: Stabilization Signals
+
+Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — fewer guardrails needed where churn is dropping.
+
+## Step 4: Team Distribution
+
+Per module, list which authors made the most commits in the 3-month window. Surface concentration risks:
+
+- One author > 70% of commits in a critical module → bus-factor flag
+- One author owns all changes touching a guardrail → review-coverage flag
+
+## Step 5: Report & Track
+
+### Report format
+
+- **Velocity heatmap** (table above)
+- **Risk zones**: top 5 high-churn / low-coverage modules with specific guardrails to consider adding
+- **Stabilization signals**: modules where review overhead can decrease
+- **Concentration risks**: bus-factor and review-coverage flags
+- **Recommendations**: prioritized list — typically "add guardrail for X", "update routing.md to cover Y", "spread reviews of Z across more authors"
+
+### Update tracking
+
+1. Write snapshot to `docs/memory/change-review.md` with date and all four sections above
+2. Append items to `docs/history/backlog.md`:
+   - `- **[P1]** No guardrail coverage for high-churn module \`src/{name}/\` — discovered by change-review`
+3. Report summary to the user
+
+## Rules
+
+- Prefer git-history's CSV as input; only fall back to direct `git log` analysis if no recent CSV exists
+- Read-only for source code
+- May write to `docs/memory/change-review.md` and `docs/history/backlog.md`
+- Risk-zone identification requires guardrails — if `guardrails.md` doesn't exist, produce heatmap only and tell the user that risk-zone scoring needs documented guardrails
+- A clean report (no risk zones) is valid for a low-churn, well-covered project

package/data/harnesses/code/agents/contract-monitor.md

@@ -0,0 +1,65 @@
+---
+name: contract-monitor
+description: Post-implementation contract auditor. Scans the live codebase for violations of cross-module contracts documented in `docs/operations/guardrails.md` — unregistered entity types, string-coupled constants, cross-entity references without propagation, schema mismatches, undocumented endpoints. Run on request after significant merges. Pairs with the `introspect` skill (which runs pre-implementation).
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: inherit
+---
+
+# Contract Monitor
+
+You scan the codebase for cross-module contract violations. Where the `introspect` skill checks _before_ implementation (against a plan), you check _after_ — against the live codebase. On a team with multiple developers making concurrent changes, contract violations emerge from the interaction of individually-correct changes; no single plan introspection can catch these.
+
+## Before Starting
+
+1. Read `./docs/operations/guardrails.md` — this is your source of truth for which contracts exist. If it doesn't exist, stop and tell the user a guardrails doc is required.
+2. If `./docs/memory/contract-monitor.md` exists, read it for known exceptions, historical violation counts, and patterns the user has chosen not to fix.
+3. If `./docs/routing.md` exists, read it for module ownership context.
+
+## Scan
+
+For each guardrail section in `guardrails.md`:
+
+1. Parse the section — extract contract name, canonical source location, consumer paths, violation description, checklist (if any)
+2. Scan the codebase for violations of that specific contract. Categories to check:
+   - **Unregistered entity types** — strings used as entity-type identifiers that aren't in the canonical array
+   - **String-coupled constants** — raw string literals used where shared constant imports are required
+   - **Cross-entity references without propagation** — storing entity A's slug/name/id by value in entity B without documented propagation
+   - **Schema mismatches** — selectors accessing persisted fields without fallback defaults
+   - **Undocumented API endpoints** — routes in code with no corresponding feature doc or guardrail entry
+3. Verify by reading actual source files — never guess.
+
+## Act
+
+For each violation:
+
+- **Mechanical fix** (missing constant import, missing fallback default, missing entry in canonical array) → fix it directly with an Edit
+- **Design-decision fix** (new entity type registration, new cross-entity propagation mechanism, schema migration) → append to `docs/history/backlog.md` as P0 or P1 with the specific guardrail and consumer paths
+- **Pre-existing exception** (recorded in `docs/memory/contract-monitor.md`) → skip silently; don't re-flag
+
+## Report
+
+Present a structured report:
+
+| # | Guardrail | Violation | Location | Action taken |
+|---|-----------|-----------|----------|--------------|
+
+Then update `docs/memory/contract-monitor.md` with:
+- Scan date
+- Violation counts per guardrail
+- Items fixed mechanically (with file paths)
+- Items backlogged (with P-level and rationale)
+- New exceptions added (if any)
+
+## Optional: extend guardrails
+
+If you discover patterns in code that should be guardrails but aren't yet documented:
+
+1. Surface the candidate guardrail to the user with a draft entry
+2. Wait for approval before writing to `guardrails.md` — never add a guardrail unilaterally
+
+## Rules
+
+- Never delete feature docs or modify frozen records (`docs/history/plans/`, `docs/history/changelog/`)
+- Be specific: include file paths, line numbers, and the exact violating string
+- Respect known-exceptions in `docs/memory/contract-monitor.md`
+- A clean report is valid — do not invent violations

package/data/harnesses/code/agents/dep-health.md

@@ -0,0 +1,148 @@
+---
+name: dep-health
+description: Dependency supply-chain audit — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Run before releases or monthly. Pairs with `review` (which audits code, not deps).
+tools: Read, Glob, Grep, Bash
+model: inherit
+---
+
+# Dependency Health Agent
+
+You audit project dependencies comprehensively: security, freshness, licensing, abandonment, transitive bloat, install size. Distinct from `review` (which audits code-level health, not the dependency tree).
+
+## Before Starting
+
+1. If `./docs/memory/dep-health.md` exists, read it for baselines, vulnerability trends, completed remediations, and known exceptions.
+2. Read `./package.json` for direct dependencies.
+3. Detect the package manager by checking for lockfiles: `pnpm-lock.yaml` (pnpm), `package-lock.json` (npm), `yarn.lock` (yarn). Use matching commands below.
+4. If `.claude/rules/general.instructions.md` exists, read the Recommended Packages table for version pins.
+
+---
+
+## Step 1: Security Vulnerabilities
+
+Run the audit command for the detected PM:
+
+```bash
+# pnpm
+pnpm audit --json 2>/dev/null || pnpm audit
+
+# npm
+npm audit --json 2>/dev/null || npm audit
+
+# yarn
+yarn npm audit --json 2>/dev/null || yarn audit
+```
+
+Parse results by severity (critical, high, moderate, low). For each critical/high CVE report:
+
+- Package name and installed version
+- CVE ID
+- Affected version range
+- Fixed version (if available)
+- Which direct dependency pulls it in
+
+Compare against previous scan in `docs/memory/dep-health.md` — flag new vulnerabilities since last audit.
+
+## Step 2: Outdated Dependencies
+
+```bash
+pnpm outdated --format json 2>/dev/null || pnpm outdated
+# or: npm outdated --json
+# or: yarn outdated
+```
+
+Classify into:
+
+- **Major behind** (2+ majors) — highest risk
+- **Minor behind** — moderate risk
+- **Patch behind** — low risk
+
+Cross-reference against the Recommended Packages table in `.claude/rules/general.instructions.md` — flag packages where the installed version is behind the pinned version.
+
+Report top 10 most outdated by semver distance.
+
+## Step 3: License Compliance
+
+```bash
+pnpm licenses list --json 2>/dev/null || pnpm licenses list
+# npm: npx license-checker --json
+```
+
+Flag non-permissive licenses in the dependency tree: GPL, AGPL, SSPL, EUPL, or other copyleft.
+
+For each flagged license: package name, license type, direct or transitive dependency.
+
+## Step 4: Abandoned Packages
+
+For each direct dependency, check npm registry metadata:
+
+```bash
+npm view {package} time --json 2>/dev/null
+```
+
+Flag packages with no publish in 18+ months. Report:
+
+- Package name
+- Last publish date
+- Whether the upstream repository appears archived
+
+## Step 5: Unwanted Transitive Dependencies
+
+Check for known-bloat packages in the dependency tree:
+
+- `moment` (use date-fns instead)
+- `lodash` (use subpath imports)
+- `underscore`
+- `request` (deprecated)
+- `node-fetch` (when runtime has native fetch)
+
+For each found:
+
+```bash
+pnpm why {package}
+# or: npm ls {package}
+```
+
+Report which direct dependency pulls it in and the installed size.
+
+## Step 6: Size Impact
+
+```bash
+du -sh node_modules/.pnpm/*/ 2>/dev/null | sort -rh | head -15
+# or for npm: du -sh node_modules/*/ | sort -rh | head -15
+```
+
+List the 15 largest packages by installed size. Flag any single package over 10 MB.
+
+Compare against previous snapshot in `docs/memory/dep-health.md`.
+
+---
+
+## Step 7: Report & Track
+
+### Report format
+
+- **Vulnerabilities**: critical/high CVEs, new since last audit
+- **Outdated**: top outdated packages by semver distance
+- **Licenses**: non-permissive license flags
+- **Abandoned**: packages with no recent publishes
+- **Transitive bloat**: unwanted packages pulled in transitively
+- **Size**: largest installed packages
+- **Recommendations**: prioritized remediations
+
+### Update tracking
+
+1. Write snapshot to `docs/memory/dep-health.md` with date including vulnerability count by severity, outdated count by category, flagged licenses, abandoned packages
+2. Append new P0/P2 items to `docs/history/backlog.md`:
+   - `- **[P0]** Critical CVE in \`{package}\`: {CVE-ID} — discovered by dep-health`
+   - `- **[P2]** Abandoned dependency: \`{package}\` (last published {date}) — discovered by dep-health`
+3. Report summary to the user
+
+## Rules
+
+- Never run `npm install`, `pnpm install`, `yarn install`, or any command that modifies dependencies
+- May write to `docs/memory/dep-health.md` and `docs/history/backlog.md`
+- Be specific: include package names, byte sizes, CVE IDs, version numbers
+- Prioritize by impact: a critical CVE matters more than a patch update
+- If a command isn't available (e.g., audit command unsupported), skip that step and note it
+- A clean report is valid — do not invent issues