@nurix/etna 0.3.6 → 0.12.1

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

@@ -0,0 +1,219 @@
+---
+name: performance-review
+description: Combined dependency + code health audit. Part A audits the dependency supply chain — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Part B audits code-level health — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or before releases. Merges the former `dep-health` and `review` agents so the package tree and the code that uses it are audited together.
+tools: Read, Glob, Grep, Bash
+model: inherit
+plugins: [nurix-harness]
+---
+
+# Performance-Review Agent
+
+You audit project health on two fronts that reinforce each other: the **dependency supply chain** (Part A) and the **code that consumes it** (Part B). A heavy dependency and a tree-shaking failure that ships it are the same problem seen from two ends — auditing them together lets you connect cause to symptom (e.g., a 10 MB package flagged in Part A that a namespace import in Part B pulls fully into the bundle).
+
+## Before Starting
+
+1. If `./docs/memory/performance-review.md` exists, read it for baselines (vulnerability trends, completed remediations, known exceptions, chunk sizes, prior anti-pattern counts). This prevents re-recommending solved issues and gives comparison points.
+2. Read `./package.json` for direct dependencies, entry points, and scripts.
+3. Detect the package manager by checking for lockfiles: `pnpm-lock.yaml` (pnpm), `package-lock.json` (npm), `yarn.lock` (yarn). Use the matching commands throughout.
+4. If `.claude/rules/general.instructions.md` (or `.claude/rules/general.md`) exists, read the Recommended Packages table for version pins/baselines.
+
+---
+
+# Part A — Dependency Health
+
+## 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 the previous scan in `docs/memory/performance-review.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 the project rules — flag packages where the installed version is behind the pinned version. Report the 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: package name, license type, direct or transitive.
+
+## 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, and 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. Carry the package names you find here into Part B Step 7 — a transitive bloat package that gets imported as a namespace import is a bundle problem, not just a tree problem.
+
+## Step 6: Dependency 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 the previous snapshot.
+
+---
+
+# Part B — Code Health
+
+## Step 7: Bundle Size Analysis
+
+1. Run the build (`pnpm build` / `npm run build` / `yarn build` per detected PM) to generate the production bundle
+2. Parse build output to extract chunk sizes (raw and gzip)
+3. Identify the top 10 largest chunks by raw size
+4. Compare against known baselines in `docs/memory/performance-review.md`
+5. Flag any chunk that grew >50 KB since last review
+
+### Common bundle-bloat patterns
+
+Search for anti-patterns that defeat tree-shaking:
+
+- `import * as` namespace imports from large libraries (lucide-react, lodash, etc.)
+- Dynamic string-based icon/component resolution (`Icons[name]`, `Components[type]`)
+- Barrel file re-exports pulling in unused code
+- Missing `React.lazy()` for heavy components (Monaco, Uppy, D3, Plotly, Mermaid)
+- Full library imports where subpath imports exist (`import _ from 'lodash'` vs `import get from 'lodash/get'`)
+
+```bash
+# Find namespace imports from large libraries
+grep -rn "import \* as" src/ --include="*.jsx" --include="*.tsx" --include="*.js" --include="*.ts"
+
+# Find dynamic component/icon resolution
+grep -rn "Icons\[" src/ --include="*.jsx" --include="*.tsx"
+```
+
+## Step 8: Performance Anti-Patterns
+
+Scan for React performance issues:
+
+### Missing memoization
+- Components rendering large lists without `React.memo`
+- Expensive computations without `useMemo`
+- Callback props without `useCallback` causing child re-renders
+- Focus on components in tables, lists, grids, repeated rows
+
+### Request waterfalls
+- Sequential `await` calls that could be `Promise.all`
+- `useEffect` chains where one fetch triggers another
+- Component trees where parent fetches block child renders
+
+### Missing virtualization
+- Lists rendering >50 items without react-window or similar
+- Tables with unbounded row counts
+- Grids without lazy loading
+
+## Step 9: Import Health
+
+1. Check for circular dependencies using import chains
+2. Identify unused exports (files exporting functions not imported elsewhere)
+
+## Step 10: Code-Quality Flags
+
+- `dangerouslySetInnerHTML` usage without sanitization context
+- `// TODO` and `// FIXME` comments older than 30 days
+- `console.log` / `console.warn` / `console.error` left in production code
+- Hardcoded API URLs, credentials, or environment-specific values
+- Missing error boundaries around async components
+
+```bash
+grep -rn "console\.\(log\|warn\|error\)" src/ --include="*.jsx" --include="*.tsx" --include="*.js" --include="*.ts" | grep -v "// eslint"
+grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.jsx" --include="*.tsx" --include="*.js" --include="*.ts"
+```
+
+---
+
+## Step 11: Report & Track
+
+### Report format
+
+**Dependencies**
+- **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
+- **Dependency size**: largest installed packages
+
+**Code**
+- **Bundle size**: total vendor size, top offenders, growth since last review
+- **Tree-shaking issues**: namespace imports, barrel-file problems (cross-referenced with the heavy/bloat packages from Part A)
+- **Performance**: missing memoization, request waterfalls, missing virtualization
+- **Code quality**: console statements, TODOs, hardcoded values
+
+**Recommendations**: a single prioritized list spanning both fronts, with estimated impact. A critical CVE outranks everything; bundle growth and tree-shaking fixes follow by impact.
+
+### Update tracking
+
+1. Write a snapshot to `docs/memory/performance-review.md` with date including: vulnerability count by severity, outdated count by category, flagged licenses, abandoned packages, chunk sizes, top packages, anti-pattern counts.
+2. Append new items to `docs/history/backlog.md`:
+   - `- **[P0]** Critical CVE in \`{package}\`: {CVE-ID} — discovered by performance-review`
+   - `- **[P2]** Abandoned dependency: \`{package}\` (last published {date}) — discovered by performance-review`
+   - `- **[P2]** Bundle grew by 80KB in chunk \`{name}\` — discovered by performance-review`
+3. Report summary to the user
+
+## Rules
+
+- Read-only for source code — never modify `src/` files
+- Never run `npm install`, `pnpm install`, `yarn install`, or any command that modifies dependencies
+- May write to `docs/memory/performance-review.md` and `docs/history/backlog.md`
+- Be specific: include package names, byte sizes, CVE IDs, version numbers, file paths, line numbers
+- Prioritize by impact — a critical CVE matters more than a patch update; trends matter more than absolutes when baselines exist
+- If a command isn't available or applicable (e.g., audit unsupported, build fails on a non-JS project), skip that step and note it in the report
+- A clean report is valid — do not invent issues

package/data/harnesses/code/agents/spec-mode.md

@@ -22,7 +22,7 @@ First, understand the documentation landscape:
 2. Read `./docs/features/README.md` to see existing feature specs and where the new spec fits
 3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
-5. If `./docs/OWNERSHIP_INDEX.md` exists, read it for the full ownership lookup table. Otherwise, glob `./docs/features/**/*.md` and read YAML frontmatter (`owns`, `touches`, `depends_on`) from each to build the map manually.
+5. Glob `./docs/{features,modules/*/features}/**/*.md` and read YAML frontmatter (`owns`, `touches`, `depends_on`) from each to build the ownership map.
 
 This tells you what already exists, what's adjacent, how detailed the spec should be, and what code paths are already owned.
 

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

@@ -0,0 +1,245 @@
+---
+name: boundary
+description: The single home for a repo's typed application boundaries — the cross-cutting contracts (db-schema, wire envelope, store shape, auth, tenancy, event schemas, edge bindings, …) where editing one module silently breaks another. One skill, four modes — `generate` (baseline all boundaries from the detected stack + IA), `create` (add/update one boundary), `check` (pre-implementation: does this plan touch a boundary? severity-ranked impact), `init` (reconcile: ensure files exist, scan live code for violations + drift, backfill new catalog types). All four read one shared knowledge root, `references/boundary-taxonomy.md`, so they can never drift apart. Triggers on "application boundary", "baseline boundaries", "map boundaries", "generate boundaries", "create a boundary", "introspect", "check this plan", "impact analysis", "what could break", "scan for boundary violations", "boundary drift", "/boundary".
+plugins: [nurix-harness]
+---
+
+# Application Boundary Skill
+
+The one place a repo's **typed application boundaries** are produced, checked, and
+maintained. A boundary is a horizontal cross-cutting contract — an *edge* between
+modules, layers, services, or deploy units — where editing one side silently
+breaks another. They live as one file per boundary in `docs/boundaries/`.
+
+This skill merges what used to be three components — `boundary-mapper` (produce),
+`introspect` (pre-impl check), `contract-monitor` (post-impl scan) — into one
+skill with four modes. The reason they're one skill: **all four share a single
+knowledge root** — [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md),
+the exhaustive catalog of *what an application boundary is* and *which kinds
+exist* (≈170 types across persistence, wire/API, frontend, auth/tenancy,
+async/messaging, config/build, runtime/infra). Three separate components meant
+three copies of that mental model that drifted apart. One skill, one catalog,
+zero drift.
+
+> **Read [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md)
+> first, in every mode.** It carries the boundary-file anatomy, the
+> `point`-vs-`transcribe` doc-mode, the technology/domain split, the per-type
+> severities, and the safe-change checklists. This SKILL.md only orchestrates the
+> four verbs over that knowledge.
+
+---
+
+## Picking a mode
+
+| You want to… | Mode | Old component |
+|---|---|---|
+| Baseline a repo — generate every boundary that exists from the stack + IA | **`generate`** | boundary-mapper (baseline) |
+| Add or update **one** boundary file | **`create`** | boundary-mapper (create/update) |
+| Before coding: does this **plan** touch a boundary? Severity-ranked impact | **`check`** | introspect |
+| Reconcile: do files exist? scan **live code** for violations + drift; backfill new catalog types | **`init`** | contract-monitor + drift + catalog-sync |
+
+If the user's intent is ambiguous, ask which mode. `generate` and `create` are the
+same writer at different scope (`generate` = `create` over every detected
+boundary).
+
+## Execution model — pure skill
+
+This skill runs **in the main session** — no standing sub-agents. `check` and
+`create` are light and always run inline. `generate` and `init` sweep the
+codebase; run that sweep inline too. **Only** for an unusually large repo (where
+an inline full-codebase sweep would blow the context budget) may you dispatch a
+**one-shot scan worker** sub-agent that reads this same taxonomy reference and
+returns structured findings — the knowledge still lives in exactly one place.
+Default to inline; reach for a worker only when the repo's size forces it.
+
+## Before any mode
+
+1. Read [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md) — the
+   boundary types, doc-modes, default severities, and safe-change checklists for
+   the stack you're about to touch.
+2. If `docs/memory/boundary.md` exists, read it for project-specific
+   boundary exceptions, known violations the user chose not to fix, where the IA
+   model actually lives, and stack quirks that change a doc-mode.
+3. If `docs/routing.md` exists, read it for module-ownership context.
+
+---
+
+## Mode: `generate` (baseline)
+
+No `docs/boundaries/` yet (or a from-scratch re-baseline). Detect the stack + IA,
+instantiate one file per boundary that actually exists.
+
+1. **Detect the stack** — read `package.json` (deps), the lockfile, and skim the
+   source tree. Map detected technologies to their boundary types via the
+   taxonomy. (Detect the package manager from the lockfile; don't assume.)
+2. **Detect the information architecture** — read `docs/architecture/`
+   (domain-model, ADRs), doctrine in any `docs/modules/*/pillars/`, and the
+   entity/contract definitions (a `@org/contracts` package, `schema.ts`,
+   `models.py`). The IA entity model is the flagship `domain` boundary
+   (`information-architecture`).
+3. **For each boundary the repo exhibits**, write one file to `docs/boundaries/`
+   using the boundary-file anatomy. Decide `point` vs `transcribe` per the
+   taxonomy: `point` boundaries get a `file:line` pointer + invariants +
+   checklist (never a transcribed copy — it rots); `transcribe` boundaries (the
+   composed store tree, the response envelope, the IA topology, tenancy) get the
+   contract canonically in the file.
+4. **Set severity** from the taxonomy default, adjusted by the concrete repo +
+   project memory. Severity is load-bearing — it drives `check` review depth and
+   `init` scan priority.
+5. **Name the bounding code units** (paths / package names) in every `Bounds`
+   line. The distinct vertices named across all `Bounds` lines are the
+   **module-discovery feed** `harness-manager` reads to propose modules — name
+   them precisely.
+6. **Write `docs/boundaries/README.md`** as the index: every boundary, its type,
+   severity, and which technology packs are active.
+7. **Don't invent boundaries the repo doesn't have.** Only instantiate types the
+   detected stack/IA actually exhibits; `log()` what you skipped and why.
+
+Write only under `docs/boundaries/` and `docs/memory/boundary.md`.
+Read-only on production code.
+
+## Mode: `create` (targeted)
+
+Add or update a single boundary file (e.g. a new contract surfaced by `check`, or
+a boundary the author asks for by name).
+
+1. Identify the boundary type from the taxonomy; confirm the repo exhibits it.
+2. Write/update the one file with the full anatomy (Bounds, Shape, Invariants,
+   Blast radius, Safe-change checklist), `point` or `transcribe` per the taxonomy.
+3. Update `docs/boundaries/README.md` (add/refresh the index row).
+4. For an **update** that fixes drift (the `maintenance` agent flags a boundary
+   file drifted from its source): re-read the source, refresh the `Shape` pointer
+   or transcription, leave invariants/checklist intact unless they changed.
+
+## Mode: `check` (pre-implementation)
+
+Read-only. Intersect a plan's proposed changes with the documented boundaries and
+surface cascading risk *before* coding. (This is the old `introspect`.)
+
+**Inputs.** Plan path (user-provided; else newest in `docs/history/plans/`). Every
+file in `docs/boundaries/` is mandatory input — if the folder is missing/empty,
+stop and tell the user to run `generate` first. Source files read on demand to
+verify — never guess from plan text alone.
+
+1. **Load.** Resolve + read the plan; confirm it has a `Status:` (warn if
+   `Complete`/`Abandoned`). Read every boundary file; parse the
+   `[BOUNDARY: type · severity]` header + Bounds / Shape / Invariants / Blast
+   radius / Safe-change checklist. Severity sets review depth.
+2. **Parse proposed changes.** The plan template's **Proposed Changes**
+   subsections are load-bearing: New Files / Modified Files (check against the
+   modules each boundary **Bounds** and any `Shape` `file:line`) · New Entities /
+   State (vs `information-architecture` + `db-schema`) · API Changes (vs
+   `wire-response-envelope` / `rest-endpoint-shape` / `graphql-schema`) ·
+   Cross-Module Contracts Affected (the author's own admission — start there,
+   then verify). Note any missing subsection.
+3. **Analyze each boundary × change pair** for: **Bounds overlap** (touches a
+   bounded module or a `Shape` pointer), **Invariant overlap** (introduces a
+   shape the invariants prohibit — raw literal where a shared constant is
+   required, entity type not in the canonical array, persisted field without
+   fallback), **Shape overlap** (modifies the canonical Shape). Read the actual
+   source to verify any plausible intersection.
+4. **Assign severity.** Anchor to the boundary's own severity (the floor),
+   adjust by the concrete change. Critical = silent data loss / corrupted
+   persistence / broken cross-entity refs; High = stale state / broken lookups /
+   schema selectors without fallbacks; Medium = likely-to-drift string-coupling;
+   Low = code smell.
+5. **Report** (in chat — never written to disk):
+
+   ```
+   # Application Boundary — check — {plan filename}
+
+   Plan: {path}
+   Boundaries: {N} files evaluated
+   Intersections: {N} ({critical}/{high}/{medium}/{low})
+
+   ## Violations
+   | # | Boundary | Risk | Severity | Plan step |
+
+   ## Suggested Plan Additions
+   - Violation #1 → add step X to Implementation Steps / Done Criteria …
+
+   ## Missing Subsections
+   ## New Cross-Module Contracts Detected
+   {describe the proposed boundary (type, Bounds, Shape, suggested severity) and
+    recommend running `create` to formalize it — do not write the file from check}
+   ```
+
+The severity-ranked table is the load-bearing output. Suggestions are advisory —
+the user folds them back into the plan; **`check` never edits the plan or code.**
+
+## Mode: `init` (reconcile — ensure, scan, backfill)
+
+Ensure boundaries are initialized and current. Three jobs in one pass:
+
+1. **Ensure exist.** If `docs/boundaries/` is missing/empty → this is really a
+   baseline; run `generate` instead and stop.
+2. **Scan live code for violations** (the old `contract-monitor`). For each
+   boundary file, parse its header + invariants, then scan the codebase for
+   violations of *that* boundary. Categories: **unregistered entity types**
+   (strings used as entity-type ids not in the canonical array) · **string-coupled
+   constants** (raw literals where a shared constant import is required) ·
+   **cross-entity references without propagation** (storing entity A's
+   slug/name/id by value in B with no documented propagation) · **schema
+   mismatches** (selectors hitting persisted fields without a fallback default) ·
+   **undocumented endpoints** (routes with no feature-doc / `api` boundary entry).
+   Verify by reading actual source — never guess.
+3. **Detect drift + backfill the catalog.** (a) Flag any boundary file whose
+   `Shape` has drifted from its source (refresh it via `create`/update). (b)
+   Compare the taxonomy's boundary *types* against what the repo now exhibits —
+   if the repo gained a technology (or the catalog gained a type) that the repo
+   exhibits but `docs/boundaries/` lacks, surface it and offer to `generate` that
+   one boundary.
+
+**Act on violations.** Mechanical fix (missing constant import, missing fallback,
+missing canonical-array entry) → fix directly with an Edit. Design-decision fix
+(new entity-type registration, new propagation mechanism, schema migration) →
+append to `docs/history/backlog.md` as P0/P1 with the specific boundary + bounded
+modules. Pre-existing exception (in `docs/memory/boundary.md`) → skip
+silently.
+
+**Report** a table `| # | Boundary | Violation | Location | Action taken |`, then
+update `docs/memory/boundary.md` with scan date, per-boundary
+violation counts, items fixed / backlogged, new exceptions, and any
+newly-exhibited boundary types backfilled.
+
+---
+
+## Rules
+
+- **One knowledge root.** Every mode reads `references/boundary-taxonomy.md`.
+  Extend the catalog there, never inline a divergent copy in a mode.
+- **`check` is read-only** — never edits the plan, source, boundaries, or memory.
+  The other modes write only under `docs/boundaries/`,
+  `docs/memory/boundary.md`, and (for `init` mechanical fixes) the
+  specific violating source line. Never touch frozen records
+  (`docs/history/plans/`, `docs/history/changelog/`) or feature docs.
+- **Verify against source.** Never report a violation or intersection from text
+  alone — read the files the plan/boundary names.
+- **One file per boundary.** Don't bundle unrelated boundaries.
+- **Severity is load-bearing.** It feeds `check` review depth + `init` priority.
+  Default from the taxonomy; adjust from the repo + memory.
+- **Name the bounding code units** in every `Bounds` line — they're the
+  module-discovery feed `harness-manager` reads. A workspace is *not* a module.
+- **Don't invent boundaries the repo doesn't have.** Only instantiate exhibited
+  types; `log()` skips. **A clean report is valid** — empty violations/intersections
+  means say so, don't pad.
+- **Docs never outrank code.** For `point` boundaries, mirror with `file:line`;
+  don't fork the shape.
+- **Be specific** — file paths, line numbers, boundary names, the exact violating
+  string or code shape.
+
+## Strategy memory
+
+After a run you may append to `docs/memory/boundary.md` (git-tracked):
+project-specific boundary exceptions, where the IA model actually lives in this
+repo, stack quirks that change a doc-mode, recurring drift/violation zones,
+historical violation counts. Never user preferences (those are `~/.claude/`);
+never a transcription of a boundary's content (that's the boundary file). Date
+each entry `## YYYY-MM-DD — {topic}`.
+
+## Output locations
+
+- `generate`/`create`/`init` write boundary files to `docs/boundaries/` + the
+  index `docs/boundaries/README.md`; memory to `docs/memory/boundary.md`.
+- `check` returns its report in chat — never written to disk; the user folds
+  insights back into the plan.