@nurix/etna 0.15.7 → 0.16.0

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

@@ -0,0 +1,218 @@
+---
+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
+---
+
+# 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-fable/agents/spec-mode.md

@@ -0,0 +1,56 @@
+---
+name: spec-mode
+description: Specification researcher for Feature and Product workflows. Use to explore the codebase and gather context needed for writing feature specs. Returns research findings — does not write files.
+tools: Read, Glob, Grep, WebSearch, WebFetch
+model: inherit
+skills:
+  - documentation
+---
+
+# Spec Mode Agent
+
+You are a specification researcher. Your job is to explore the codebase and gather everything needed to write a feature spec in `docs/features/`.
+
+You do NOT write the spec — you return structured research that the main agent uses to write it.
+
+## Before Starting
+
+First, understand the documentation landscape:
+
+1. Read `./docs/structure.md` to understand the documentation structure
+2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
+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. 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.
+
+## What You Research
+
+1. **Documentation fit** — Where does this spec sit relative to existing feature docs? Does it extend an existing spec or need a new one?
+2. **Existing patterns** — Find related features, similar implementations, and conventions in the codebase
+3. **Affected modules** — Identify what files, routes, components, and data flows are relevant
+4. **Current state** — Understand how the system works today in the area being specified
+5. **Dependencies** — Map what this feature touches and what depends on it
+6. **Ownership conflicts** — Compare the new feature's intended code paths against existing `owns`/`touches` declarations. Report overlaps.
+
+## What You Return
+
+Structure your findings as:
+
+- **Documentation context**: Existing specs that relate, whether to create new or update existing, suggested filename
+- **Related patterns**: What similar things exist in the codebase and where
+- **Affected modules**: Files, routes, components that will be involved
+- **Current behavior**: How the relevant part of the system works today
+- **Conventions**: Naming, structure, and patterns to follow based on existing code
+- **Ownership conflicts**: Existing feature docs whose `owns` or `touches` paths overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Risks or concerns**: Anything the spec should address or call out
+
+Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.
+
+## Rules
+
+- Read-only — you explore and report, you do not modify files
+- Be specific — include file paths, function names, route patterns
+- Be concise — return findings, not narratives
+- If the codebase has no relevant patterns, say so clearly

package/data/harnesses/code-fable/harness.json

@@ -0,0 +1,7 @@
+{
+  "harness": "code-fable",
+  "name": "code-fable",
+  "version": "0.15.3",
+  "epoch": 13,
+  "digest": "30d4aa84ee01"
+}

package/data/harnesses/code-fable/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-reflect.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-recall.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/data/harnesses/code-fable/hooks/lib/redact.js

@@ -0,0 +1,37 @@
+// harness/code/hooks/lib/redact.js — shared privacy filter: redacts secret shapes before ledger append.
+
+"use strict";
+
+// Patterns ordered most-specific first; each replaces a match with [redacted:{kind}].
+const RULES = [
+  // PEM private/public key blocks (multiline).
+  { kind: "pem", re: /-----BEGIN[\s\S]*?-----END[^-]*-----/g },
+  // OpenAI / Anthropic-style keys (sk-..., sk-ant-...).
+  { kind: "api-key", re: /\bsk-(?:ant-)?[A-Za-z0-9_-]{8,}\b/g },
+  // AWS access key IDs.
+  { kind: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  // Bearer tokens in Authorization context.
+  { kind: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+  // password= / passwd= / secret= / token= / api_key= style assignments (= or :).
+  {
+    kind: "credential",
+    re: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["']?[^\s"'&)\]},;[]{3,}/gi,
+  },
+  // Generic long hex/base64 token ONLY in a key-value credential context.
+  {
+    kind: "credential",
+    re: /\b(?:key|auth|cred|credential|signature|sig)\b\s*[:=]\s*["']?[A-Za-z0-9+/=_-]{32,}/gi,
+  },
+];
+
+// Redact secret shapes in arbitrary text; returns a string with placeholders.
+function redact(text) {
+  if (text == null) return "";
+  let out = String(text);
+  for (const rule of RULES) {
+    out = out.replace(rule.re, `[redacted:${rule.kind}]`);
+  }
+  return out;
+}
+
+module.exports = { redact };

package/data/harnesses/code-fable/hooks/prompt-recall.js

@@ -0,0 +1,157 @@
+// plugins/code/hooks/prompt-recall.js — UserPromptSubmit hook: surface fact-cards relevant to the prompt via qmd BM25; stdout is injected as context.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const MIN_PROMPT_CHARS = 24;
+const MIN_SCORE = 0.45;
+const MAX_CARDS = 3;
+const MAX_STATEMENT_CHARS = 300;
+const MAX_KEYWORDS = 8;
+
+const STOPWORDS = new Set(
+  "a an and are as at be but by can could do does for from has have how i in is it its me my of on or our should so that the their then there these this to was we what when where which who why will with would you your".split(
+    " ",
+  ),
+);
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Map a qmd://collection/relpath hit URI to the card file under docs/memory/facts/.
+function cardPath(factsDir, fileUri) {
+  return path.join(factsDir, String(fileUri || "").replace(/^qmd:\/\/[^/]+\//, ""));
+}
+
+// A card's atomic statement: the body after frontmatter, whitespace-flattened and clipped.
+function cardStatement(file) {
+  try {
+    const body = fs
+      .readFileSync(file, "utf8")
+      .replace(/^---\n[\s\S]*?\n---\n?/, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    return body.length > MAX_STATEMENT_CHARS ? body.slice(0, MAX_STATEMENT_CHARS) + "…" : body;
+  } catch (e) {
+    return "";
+  }
+}
+
+// Run one qmd search mode against the facts collection; [] on any failure — recall is strictly optional.
+function qmdHits(mode, query, collection) {
+  try {
+    const out = JSON.parse(
+      execFileSync("qmd", [mode, query, "--format", "json", "-n", String(MAX_CARDS + 2), "-c", collection], {
+        encoding: "utf8",
+        timeout: 10000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+    );
+    return Array.isArray(out) ? out : [];
+  } catch (e) {
+    return [];
+  }
+}
+
+// Main: search the facts collection for the prompt and emit unseen high-score cards.
+function main() {
+  if (process.env.ETNA_REFLECT) return;
+
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+
+  const prompt = String(payload.prompt || "").trim();
+  if (!prompt || prompt.startsWith("/") || prompt.length < MIN_PROMPT_CHARS) return;
+
+  const projectDir = resolveProjectDir(payload);
+  const factsDir = path.join(projectDir, "docs", "memory", "facts");
+  let hasCards = false;
+  try {
+    hasCards = fs.readdirSync(factsDir).some((f) => f.endsWith(".md"));
+  } catch (e) {
+    return;
+  }
+  if (!hasCards) return;
+
+  // BM25 keywords first (fast, strict-AND), vector similarity as the natural-language
+  // fallback (~1s warm) — `qmd query` (LLM expansion + rerank) is too slow to block a prompt.
+  const collection = `${path.basename(projectDir)}-facts`;
+  const keywords = Array.from(
+    new Set(
+      prompt
+        .toLowerCase()
+        .replace(/[^a-z0-9\s_./-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOPWORDS.has(w)),
+    ),
+  )
+    .slice(0, MAX_KEYWORDS)
+    .join(" ");
+  let hits = keywords ? qmdHits("search", keywords, collection) : [];
+  if (!hits.length) hits = qmdHits("vsearch", prompt.replace(/\s+/g, " ").slice(0, 300), collection);
+  if (!hits.length) return;
+
+  // Inject each card at most once per session.
+  const sessionKey = String(payload.session_id || "any").replace(/[^a-zA-Z0-9-]/g, "");
+  const stateFile = path.join(os.tmpdir(), `etna-recall-${sessionKey}.txt`);
+  let seen = [];
+  try {
+    seen = fs.readFileSync(stateFile, "utf8").split("\n").filter(Boolean);
+  } catch (e) {
+    seen = [];
+  }
+
+  const fresh = hits
+    .filter((h) => h && h.score >= MIN_SCORE && h.file && !seen.includes(h.file))
+    .slice(0, MAX_CARDS);
+  const lines = [];
+  for (const hit of fresh) {
+    const statement = cardStatement(cardPath(factsDir, hit.file));
+    if (statement) {
+      lines.push(`- ${statement} [${String(hit.file).replace(/^qmd:\/\/[^/]+\//, "docs/memory/facts/")}]`);
+    }
+  }
+  if (!lines.length) return;
+
+  try {
+    fs.appendFileSync(stateFile, fresh.map((h) => h.file).join("\n") + "\n", "utf8");
+  } catch (e) {
+    // Dedupe state is best-effort; a re-injection is harmless.
+  }
+
+  process.stdout.write(
+    `<memory-recall>\nProject memory possibly relevant to this prompt (distilled fact-cards):\n${lines.join("\n")}\n</memory-recall>\n`,
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`prompt-recall hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}