baldart 5.8.0 → 5.10.0

package/framework/.claude/skills/simplify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: simplify
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Use when completing a coding task, after implementation, or when the user says /simplify. Covers deduplication (exact/near/inline), code quality patterns, and performance.
 ---
 
@@ -39,15 +39,31 @@ If the diff is empty (everything is committed), run `git diff HEAD~5..HEAD` to c
 
 If there are no git changes at all, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
 
-## Step 2: Launch Three Review Agents in Parallel
+> **Methodology SSOT**: the taxonomy (A1–A9), the canonical refactoring vocabulary (Fowler smells / Four Rules of Simple Design / AHA·YAGNI·Rule of Three), the clone-type vocabulary, the deterministic-tier contract, the internal-documentation awareness rules, and the judge-bias guards this skill applies all live in `framework/agents/simplify-protocol.md`. This body owns the OPERATIONAL workflow (Steps 1–5); it CITES the module for those rules rather than restating them (`SECTION=<taxonomy|canonical-vocab|clone-vocab|rubric|deterministic-tier|doc-awareness|bias-guards>`).
 
-Use the Agent tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+## Step 1.5: Run the Deterministic Clone Floor (before eyeballing)
 
-> **Author-time prevention mirror:** `coder` now applies an author-time subset of the Quality + Efficiency taxonomy below WHILE writing (`framework/.claude/agents/coder.md § Author-Time Simplicity Discipline`), so the diff this pass reviews should already be cleaner on those domains. This pass remains the **independent net** — its load-bearing value is the cross-codebase **Reuse** detection (exact/near duplicate, inline reimplementation, dependency-reimplements-native) that the author cannot see from inside the task. This Step 2 taxonomy is the SSOT; if you change it, keep the coder mirror in sync.
+An LLM eyeballing a diff misses clones exactly as it misses its own smells — so ground the Reuse lens with an EXTERNAL signal first (`agents/simplify-protocol.md SECTION=deterministic-tier`):
+
+```
+node framework/.claude/skills/simplify/scripts/simplify-scan.mjs --diff HEAD --json
+```
+
+(Zero-dep, identical on Codex; `--diff HEAD~5..HEAD` when the work is committed, or pass explicit file paths.) The scan PROPOSES anchored clone candidates (`path:line` × matching loci + type); it never decides. Pass its candidate list to Agent 1 below — Agent 1 verifies each (discards false positives like import blocks / boilerplate / fixtures, promotes real ones). A clean floor is a legitimate result, not a reason to invent duplicates.
+
+## Step 2: Launch the Code Simplifier
+
+Use the Agent tool to launch **one `code-simplifier` agent** (`subagent_type: code-simplifier`), passing it the diff path + the Step 1.5 clone-floor candidates. It covers ALL the lenses below as one persona (Reuse / Quality / Design-altitude / Efficiency) — it is the independent, evidence-grounded reviewer; you (the skill) apply its fixes in Step 4. The lens descriptions below are its operational rubric.
+
+> **Methodology SSOT**: the taxonomy, canonical vocabulary, clone-vocab, bias guards and doc-awareness the agent applies live in `framework/agents/simplify-protocol.md` — the lens descriptions here are the operational surface, not the SSOT. If you change a lens, keep the module + the `coder` author-time mirror (`framework/.claude/agents/coder.md § Author-Time Simplicity Discipline`) in sync.
+
+> **Author-time prevention mirror:** `coder` already applies an author-time subset of the Quality + Efficiency + Design-altitude taxonomy WHILE writing, so the diff this pass reviews should already be cleaner there. This pass remains the **independent net** — its load-bearing value is the cross-codebase **Reuse** detection (exact/near duplicate, inline reimplementation, dependency-reimplements-native) the author cannot see from inside the task.
 
 ### Agent 1: Duplication & Reuse Review
 
-For each new piece of code in the diff:
+**Consume the Step 1.5 clone-floor candidates FIRST** (pass them into this agent's briefing): for each anchored candidate, verify the match is a real duplicate/reuse-miss (not an import block, boilerplate, or fixture the scan over-matched) and confirm the "existing" side is LIVE code, not dead — then promote it to a finding with an `existing` pointer. The floor catches Type-1 and gapped Type-3; YOU still catch Type-2 (renamed identifiers, which the floor deliberately does not normalize) and Type-4 (semantic) via retrieval below. Classify every duplicate per `agents/simplify-protocol.md SECTION=clone-vocab`.
+
+Then, for each new piece of code in the diff:
 
 1. **Start with `${paths.references_dir}/component-registry.md`** — the authoritative inventory of all UI primitives, shared components, hooks, and utility modules. Scan the relevant tables before grepping. Then search for existing utilities and helpers that could replace newly written code in the project's utility roots (e.g. `${paths.components_root}/shared/`, `${paths.components_primitives}/`, and `src/lib/`, `src/hooks/` if they exist), and files adjacent to the changed ones.
 2. **For each new component**, Grep the codebase for components with similar names, similar prop signatures, or similar JSX structure. Check for copy-pasted layout components (`layout.tsx` files with near-identical structure).
@@ -82,11 +98,15 @@ Review the same changes for hacky patterns:
 5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
 6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior
 7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
+8. **Wrong-altitude abstraction (A4 — advisory)**: an interface/factory/generic/config-flag/parameter with exactly ONE caller or ONE implementation, or a speculative extension point with no present consumer — the Rule of Three is violated (do not abstract before the third occurrence). Name the smell (`Speculative Generality` / `Rule-of-Three`). Advisory, not a blocker — a *simplify* pass that fabricates abstraction complaints causes the very churn it exists to prevent (`agents/simplify-protocol.md SECTION=canonical-vocab`). Corollary caution (AHA): prefer a little duplication over unifying two blocks whose shared shape is only coincidental.
+9. **Pattern inconsistency vs siblings (A6 — advisory)**: the new code uses a different idiom / error-handling / naming / state pattern than the 2–3 nearest existing files it lives beside — align it to the established local convention.
+
+> **Bias guard (a simplify judge is inverted)**: NEVER prefer a change because it adds structure — longer code is a NEGATIVE signal for this pass, never positive. Every finding cites executed/retrieved evidence (a clone match, a zero-caller proof, an existing-utility `path:line`), never unaided opinion. Zero findings on a clean diff is the correct outcome. Full rules: `agents/simplify-protocol.md SECTION=bias-guards`.
 
 #### Agent 2 — Design System SSOT Compliance sub-checklist (MANDATORY for UI refactors)
 
-This is part of Agent 2's single task (NOT a separate fourth parallel agent — the three agents in
-Step 2 are Agents 1, 2, 3). When the diff includes files under `${paths.components_root}/`,
+This is part of the Quality lens (Agent 2), which the single `code-simplifier` agent covers alongside
+the other lenses — NOT a separate agent. When the diff includes files under `${paths.components_root}/`,
 `${paths.components_root}/**/*.tsx`, or any `.css`/`.module.css`, the simplify pass MUST NOT introduce
 hardcoded design values while refactoring. Agent 2 runs this as part of its quality review:
 
@@ -116,7 +136,7 @@ Review the same changes for efficiency:
 
 ## Step 3: Aggregate Findings
 
-Collect results from all three agents. For each finding, categorize as:
+Collect the `code-simplifier` findings (across all lenses). For each finding, categorize as:
 
 1. **Exact duplicate** — same logic exists elsewhere. Use the existing one. Delete the new one.
 2. **Near duplicate** — similar logic with minor differences. Extract a shared version with parameters.

package/framework/.claude/skills/simplify/scripts/simplify-scan.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * simplify-scan.mjs — deterministic clone floor for the /simplify pass.
+ *
+ * The always-on, zero-dependency, stack-agnostic near-duplicate detector that
+ * grounds the code-simplifier reviewer with an EXTERNAL signal it lacks by
+ * eyeballing (research: an LLM misses clones exactly as it misses its own
+ * smells). Twin of ui-design/scripts/craft-check.mjs — runs identically on
+ * Claude Code and Codex (Node >= 18, no deps).
+ *
+ * It PROPOSES anchored clone candidates (path:line x matching loci + type); the
+ * reviewer DISPOSES (verifies each, discards false positives, promotes real
+ * ones). It NEVER edits and NEVER decides. Contract + rationale:
+ * framework/agents/simplify-protocol.md SECTION=deterministic-tier.
+ *
+ * Scope: the CHANGED files' code windows matched against the whole repo
+ * (diff x repo) AND against each other. Catches Type-1 (exact modulo
+ * whitespace/comments) and gapped Type-3; Type-2 (renamed identifiers) is
+ * deliberately NOT normalized away (it explodes boilerplate false positives —
+ * that is the reviewer's job), and Type-4 is structurally invisible here.
+ *
+ * Usage:
+ *   node simplify-scan.mjs [--diff <ref-or-range>] [file ...] [--json]
+ *                          [--min-lines N] [--repo DIR]
+ *
+ *   --diff <range>  git range whose changed files are the "new" side
+ *                   (default: HEAD -> `git diff --name-only HEAD`; if that is
+ *                   empty, `HEAD~5..HEAD`). Positional files override detection.
+ *   --min-lines N   minimum window of non-trivial normalized lines (default 6).
+ *   --json          machine-readable output for the agent.
+ *   --repo DIR      repo root (default: `git rev-parse --show-toplevel` or cwd).
+ *
+ * Exit codes: 0 = ran (candidates, if any, are in the output — this is an
+ * advisory FEEDER, not a CI gate, so it never fails on findings), 2 = usage/env
+ * error. It is safe to run on any stack; a non-git or empty scope is a clean
+ * no-op, never an abort.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, extname, relative, isAbsolute } from 'node:path';
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const getOpt = (name, def) => {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : def;
+};
+const MIN_LINES = Math.max(3, parseInt(getOpt('--min-lines', '6'), 10) || 6);
+const DIFF_REF = getOpt('--diff', null);
+const positional = argv.filter(
+  (a, i) => !a.startsWith('--') && argv[i - 1] !== '--diff' && argv[i - 1] !== '--min-lines' && argv[i - 1] !== '--repo'
+);
+
+// ---- repo root ---------------------------------------------------------------
+let REPO;
+function git(args, opts = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...opts });
+}
+try {
+  REPO = getOpt('--repo', git(['rev-parse', '--show-toplevel']).trim());
+} catch {
+  REPO = getOpt('--repo', process.cwd());
+}
+
+// ---- what counts as a source file we index ----------------------------------
+const SOURCE_EXT = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt', '.swift', '.scala', '.php',
+  '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.m', '.lua', '.dart', '.sh',
+]);
+const IGNORE_DIR = /(^|\/)(node_modules|\.git|dist|build|out|\.next|coverage|vendor|__snapshots__|migrations|\.venv|venv|target|__pycache__)(\/|$)/;
+const IGNORE_FILE = /(\.min\.[a-z]+$|\.map$|\.snap$|-lock\.[a-z]+$|package-lock\.json$|yarn\.lock$|pnpm-lock\.yaml$|\.d\.ts$)/i;
+const MAX_BYTES = 512 * 1024; // skip huge/generated blobs
+
+function isSource(rel) {
+  if (IGNORE_DIR.test(rel) || IGNORE_FILE.test(rel)) return false;
+  return SOURCE_EXT.has(extname(rel));
+}
+
+// ---- normalization: strip comments + whitespace, drop trivial lines ----------
+// NO identifier normalization (deliberate — see header). A "trivial" line is
+// pure punctuation, an import, a bare export brace, or a single keyword: the
+// biggest false-positive sources for a naive hash.
+const TRIVIAL_RE = /^(?:[{}()\[\];,]*|import\b.*|export\s*\{?\s*|export\s+default\s*|module\.exports.*|use\s+strict;?|package\s+\w.*|from\b.*|['"]use client['"];?|else\s*\{?|try\s*\{?|finally\s*\{?|return;?|break;?|continue;?|pass|end)$/;
+
+function normalizeLines(text) {
+  // strip block comments spanning the file, then per-line line-comments.
+  const noBlock = text.replace(/\/\*[\s\S]*?\*\//g, '');
+  const out = [];
+  const rawLines = noBlock.split(/\r?\n/);
+  for (let i = 0; i < rawLines.length; i++) {
+    let s = rawLines[i];
+    s = s.replace(/(^|\s)(\/\/|#|--)\s.*$/, '$1'); // trailing line comment (space-guarded so it does not eat urls/operators mid-token)
+    s = s.replace(/\s+/g, ' ').trim();
+    if (!s) continue;
+    if (TRIVIAL_RE.test(s)) continue;
+    out.push({ norm: s, line: i + 1 }); // 1-based original line
+  }
+  return out;
+}
+
+// ---- window index ------------------------------------------------------------
+// key = MIN_LINES consecutive normalized lines joined. Value = list of loci.
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(36);
+}
+
+function windowsOf(nlines) {
+  const w = [];
+  for (let i = 0; i + MIN_LINES <= nlines.length; i++) {
+    const slice = nlines.slice(i, i + MIN_LINES);
+    // contiguity guard: the window must not span an enormous original gap
+    if (slice[slice.length - 1].line - slice[0].line > MIN_LINES * 4) continue;
+    const key = fnv1a(slice.map((x) => x.norm).join('\n'));
+    w.push({ key, start: slice[0].line, end: slice[slice.length - 1].line });
+  }
+  return w;
+}
+
+function listTrackedSource() {
+  try {
+    return git(['ls-files'], { cwd: REPO }).split('\n').filter((f) => f && isSource(f));
+  } catch {
+    return [];
+  }
+}
+
+function changedFiles() {
+  if (positional.length) {
+    return positional.map((p) => (isAbsolute(p) ? relative(REPO, p) : p)).filter(isSource);
+  }
+  const tryRange = (r) => {
+    try { return git(['diff', '--name-only', r], { cwd: REPO }).split('\n').filter(Boolean); }
+    catch { return []; }
+  };
+  let files = tryRange(DIFF_REF || 'HEAD');
+  if (!files.length && !DIFF_REF) files = tryRange('HEAD~5..HEAD');
+  return files.filter(isSource);
+}
+
+function readSafe(rel) {
+  try {
+    const abs = join(REPO, rel);
+    if (statSync(abs).size > MAX_BYTES) return null;
+    const buf = readFileSync(abs);
+    if (buf.includes(0)) return null; // binary
+    return buf.toString('utf8');
+  } catch { return null; }
+}
+
+// ---- run --------------------------------------------------------------------
+const changed = changedFiles();
+if (!changed.length) {
+  const msg = { candidates: [], scanned: 0, note: 'no changed source files in scope — clean no-op' };
+  console.log(asJson ? JSON.stringify(msg, null, 2) : 'simplify-scan: no changed source files in scope (clean no-op).');
+  process.exit(0);
+}
+
+// index the whole repo (so a new block matching OLD code is caught)
+const index = new Map(); // key -> [{file,start,end}]
+const repoFiles = new Set([...listTrackedSource(), ...changed]);
+for (const f of repoFiles) {
+  const txt = readSafe(f);
+  if (!txt) continue;
+  for (const w of windowsOf(normalizeLines(txt))) {
+    if (!index.has(w.key)) index.set(w.key, []);
+    index.get(w.key).push({ file: f, start: w.start, end: w.end });
+  }
+}
+
+// for each changed file window, report matches at OTHER loci
+const changedSet = new Set(changed);
+const seen = new Set();
+const candidates = [];
+for (const f of changed) {
+  const txt = readSafe(f);
+  if (!txt) continue;
+  for (const w of windowsOf(normalizeLines(txt))) {
+    const loci = index.get(w.key) || [];
+    const others = loci.filter((l) => !(l.file === f && l.start === w.start));
+    if (!others.length) continue;
+    const dedup = `${w.key}:${f}:${w.start}`;
+    if (seen.has(dedup)) continue;
+    seen.add(dedup);
+    const sameFile = others.every((l) => l.file === f);
+    candidates.push({
+      new: { file: f, start: w.start, end: w.end },
+      matches: others.map((l) => ({ file: l.file, start: l.start, end: l.end })),
+      clone_type: sameFile ? 'type-1 (intra-file)' : 'type-1/3 (cross-file)',
+      note: changedSet.has(others[0].file)
+        ? 'both sides are in the diff — likely copy-paste in this change'
+        : 'matches existing repo code — likely a reuse-miss (verify the existing side is live, not dead)',
+    });
+  }
+}
+
+// merge adjacent/overlapping candidate windows in the same new file into one
+// region candidate (a sliding window over one duplicated block emits N
+// overlapping hits — collapse them so the reviewer sees one finding per block).
+candidates.sort((a, b) => (a.new.file < b.new.file ? -1 : a.new.file > b.new.file ? 1 : a.new.start - b.new.start));
+const merged = [];
+for (const c of candidates) {
+  const prev = merged[merged.length - 1];
+  if (prev && prev.new.file === c.new.file && c.new.start <= prev.new.end + 2) {
+    prev.new.end = Math.max(prev.new.end, c.new.end);
+    const key = (m) => `${m.file}:${m.start}`;
+    const have = new Set(prev.matches.map(key));
+    for (const m of c.matches) if (!have.has(key(m))) { prev.matches.push(m); have.add(key(m)); }
+  } else {
+    merged.push({ new: { ...c.new }, matches: [...c.matches], clone_type: c.clone_type, note: c.note });
+  }
+}
+
+if (asJson) {
+  console.log(JSON.stringify({ candidates: merged, scanned: repoFiles.size, changed: changed.length, min_lines: MIN_LINES }, null, 2));
+} else {
+  if (!merged.length) {
+    console.log(`simplify-scan: 0 clone candidates across ${changed.length} changed file(s). Clean floor.`);
+  } else {
+    console.log(`simplify-scan: ${merged.length} clone candidate(s) (min ${MIN_LINES} lines) — VERIFY each (advisory, feeds the reviewer):\n`);
+    for (const c of merged) {
+      console.log(`  ${c.new.file}:${c.new.start}-${c.new.end}  [${c.clone_type}]`);
+      for (const m of c.matches) console.log(`      ↔ ${m.file}:${m.start}-${m.end}`);
+      console.log(`      ${c.note}\n`);
+    }
+  }
+}
+process.exit(0);

package/framework/.claude/skills/simplify/scripts/simplify-scan.test.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * simplify-scan.test.mjs — fixture test for the clone floor.
+ *
+ * Proves the two properties that make the floor a signal and not noise:
+ *   (1) SILENT on a boilerplate-heavy file (imports, component shell, braces).
+ *   (2) CATCHES a real cross-file duplicated block.
+ *
+ * Zero-dep, runnable directly (`node simplify-scan.test.mjs`) or via
+ * `node --test`. Uses positional-file mode so no git repo is needed.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'simplify-scan.mjs');
+
+function runScan(dir, files) {
+  const out = execFileSync('node', [SCRIPT, '--repo', dir, '--json', ...files], { encoding: 'utf8' });
+  return JSON.parse(out);
+}
+
+const BOILERPLATE = `import React from 'react';
+import { useState, useEffect } from 'react';
+import { Button } from '@/ui/button';
+import { Card } from '@/ui/card';
+
+export default function Widget() {
+  const [open, setOpen] = useState(false);
+  useEffect(() => {
+    setOpen(true);
+  }, []);
+  return (
+    <Card>
+      <Button onClick={() => setOpen(!open)}>Toggle</Button>
+    </Card>
+  );
+}
+`;
+
+// a genuine, non-trivial ~8-line block duplicated verbatim across two files
+const DUP_BLOCK = `function computeInvoiceTotal(items, taxRate, discount) {
+  let subtotal = 0;
+  for (const it of items) {
+    subtotal += it.unitPrice * it.quantity;
+  }
+  const taxed = subtotal * (1 + taxRate);
+  const afterDiscount = taxed - taxed * discount;
+  const rounded = Math.round(afterDiscount * 100) / 100;
+  return rounded;
+}
+`;
+
+test('silent on boilerplate-heavy file (no false positives)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'simpscan-'));
+  try {
+    const f = join(dir, 'widget.tsx');
+    writeFileSync(f, BOILERPLATE);
+    const res = runScan(dir, [f]);
+    assert.equal(res.candidates.length, 0, `expected 0 candidates, got ${res.candidates.length}`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('catches a real cross-file duplicated block', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'simpscan-'));
+  try {
+    const a = join(dir, 'billing.ts');
+    const b = join(dir, 'checkout.ts');
+    writeFileSync(a, `export const CFG = 1;\n${DUP_BLOCK}`);
+    writeFileSync(b, `export const OTHER = 2;\n${DUP_BLOCK}`);
+    const res = runScan(dir, [a, b]);
+    assert.ok(res.candidates.length >= 1, 'expected >=1 clone candidate for the duplicated block');
+    const hit = res.candidates.some(
+      (c) => c.matches.some((m) => m.file.endsWith('billing.ts') || m.file.endsWith('checkout.ts'))
+    );
+    assert.ok(hit, 'candidate should link billing.ts <-> checkout.ts');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/framework/.claude/workflows/new-card-review.js

@@ -385,9 +385,11 @@ const qaPrompt =
     : '')
 
 function simplifyPrompt(c) {
-  return `Simplify analysis (read-only — you do NOT edit, the workflow applies fixes afterward) over ONE card's committed diff, per ${protocolRef} (Phase 2.55). Cover all THREE lenses and return findings:\n` +
-    `  • Reuse — newly written code that duplicates an existing util/helper; inline logic that could use existing code; a NEW third-party dependency that reimplements a capability the language/stdlib/runtime/platform already provides (prefer the native primitive).\n` +
+  return `Simplify analysis (read-only — you do NOT edit, the workflow applies fixes afterward) over ONE card's committed diff, per ${protocolRef} (Phase 2.55) and your code-simplifier system prompt (agents/simplify-protocol.md). FIRST run the deterministic clone floor and verify its candidates, then cover ALL lenses and return findings:\n` +
+    `  • Clone floor — run \`node "$(ls .claude/skills/simplify/scripts/simplify-scan.mjs .framework/framework/.claude/skills/simplify/scripts/simplify-scan.mjs 2>/dev/null | head -1)" --diff /tmp/diff-${c.cardId}.txt --json\` (missing → skip, note 'scan-unavailable'); verify each anchored candidate (discard boilerplate/import/fixture false positives, confirm the existing side is LIVE) before promoting it.\n` +
+    `  • Reuse — newly written code that duplicates an existing util/helper (ground reuse-misses in the registry/code-graph/LSP per SECTION=doc-awareness, retrieve-then-verify); inline logic that could use existing code; a NEW third-party dependency that reimplements a stdlib/platform capability (prefer the native primitive).\n` +
     `  • Quality — redundant state, parameter sprawl, copy-paste with slight variation, leaky abstractions, stringly-typed code where enums exist, unnecessary JSX nesting, WHAT-comments / narration.\n` +
+    `  • Design-altitude (advisory) — single-caller/one-implementation abstraction, Rule-of-Three violation, speculative generality with no consumer, pattern inconsistency vs the 2-3 nearest sibling files. Do NOT fabricate abstraction complaints (churn is the anti-goal).\n` +
     `  • Efficiency — redundant computation, duplicate API calls, N+1, missed concurrency, hot-path bloat, missing change-detection guards, unbounded structures.\n\n` +
     `${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +
     `Run a false-positive check on every finding and SUPPRESS the unconvincing ones (your surviving findings are treated as validated). ` +
@@ -405,7 +407,7 @@ function securityPrompt(c) {
 const findThunks = []
 for (const c of cards) {
   if (c.runSimplify !== false) {
-    findThunks.push(() => reviewSafe('simplify', c, simplifyPrompt(c), { label: `simplify:${c.cardId}`, phase: 'Discovery', schema: FINDINGS_SCHEMA }))
+    findThunks.push(() => reviewSafe('simplify', c, simplifyPrompt(c), { label: `simplify:${c.cardId}`, phase: 'Discovery', agentType: 'code-simplifier', schema: FINDINGS_SCHEMA }))
   }
   if (c.hasSecurityFiles === true) {
     findThunks.push(() => reviewSafe('security', c, securityPrompt(c), { label: `security:${c.cardId}`, phase: 'Discovery', agentType: 'security-reviewer', schema: FINDINGS_SCHEMA }))

package/framework/agents/index.md

@@ -37,7 +37,8 @@ Route agents to the right module with minimal reading.
 - If touching terminology or naming -> read `agents/coding-standards.md`.
 - If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.
 - If touching operational procedures (backup, cleanup, secrets) -> read `docs/operations/` if it exists in your project.
-- If touching security or auth risk -> read `agents/security.md`.
+- If touching security or auth risk -> read `agents/security.md` (OWASP 2021 posture + secure-defaults). If performing a dedicated AppSec review (the `security-reviewer` agent, `/codexreview` security pass) -> also read `agents/security-review-protocol.md` (the matching `SECTION=` only): boundary-gate → repo-scoped threat-model → high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (attacker≠victim) → coverage-ledger. It EXTENDS `review-protocol.md` (generic passes), never duplicates it.
+- If reviewing changed code for reuse/duplication/simplicity (the `code-simplifier` agent, the `/simplify` skill, `/new` Phase 2.55) -> read `agents/simplify-protocol.md` (the matching `SECTION=` only): deterministic clone floor → doc-awareness retrieval → taxonomy (A1–A9) + canonical-vocab (Fowler / Four Rules / AHA·YAGNI·Rule-of-Three) + clone-vocab → rubric lenses → bias-guards (a simplify judge never rewards verbosity). It EXTENDS `review-protocol.md` (generic passes), never duplicates it; partitioned from `code-reviewer` (correctness/security stay there).
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
@@ -86,6 +87,8 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/runtime-portability-protocol.md` — Runtime-mechanics binding: the abstract-operation ↔ Claude/Codex map (spawn / permissions / workflow-accel / state-spine / decision-gate / read-write path / adversarial-vs-cross-model), detect-once capability contract; cited by `/new` + `/prd`. The runtime-mechanics twin of `effort-protocol.md` + `return-contract-protocol.md` (since the Codex-parity S4 wave)
 - `agents/agent-operating-protocol.md` — Shared operating procedures for the core agents (injection guard, doc-retrieval consumption, persistent-memory hygiene, tool-budget discipline), `SECTION=` dispatch, read only the matching section; agents keep 1-line binding versions inline (since v5.0.0)
 - `agents/review-protocol.md` — The shared verification engine for reviewers: Challenge + Actionability, Simulation (diff-walk / plan-walk), Chain-of-Verification, quantified risk scoring + absolute severity calibration, specialist-spawn discipline incl. orchestrated-mode `specialist_dispatch` suppression; `SECTION=` dispatch (since v5.0.0)
+- `agents/security-review-protocol.md` — The AppSec verification engine for `security-reviewer`: boundary-gate, repository-scoped threat-model, modern high-miss discovery-lens (fail-open / allowlist-escape / control-regression / gate-action mismatch / parser differential / CI-CD trust / IaC omitted arg / over-broad grant), class-specific proof-tuples (method-anchored confidence, instance-preserving), structured attack-path → mechanical severity, adversarial-refute (attacker≠victim, precondition vs counterevidence), coverage-ledger; `SECTION=` dispatch. EXTENDS `review-protocol.md`, never duplicates it. Portable Claude+Codex (since v5.9.0)
+- `agents/simplify-protocol.md` — The reuse & simplicity verification engine for `code-simplifier` (+ the `/simplify` skill + the `coder` author-time mirror): agentic-defect taxonomy (A1–A9 with detectable signals), canonical refactoring vocabulary (Fowler smells / Four Rules of Simple Design / AHA·YAGNI·Rule-of-Three / Beck tidyings), clone-type vocabulary (Type-1/2/3/4), the deterministic clone-floor contract (`simplify-scan.mjs`), internal-documentation awareness (retrieve-then-verify reuse retrieval), and the judge-bias guards a simplify reviewer needs (no verbosity reward, evidence-over-opinion, independence); `SECTION=` dispatch. EXTENDS `review-protocol.md`, never duplicates it. Portable Claude+Codex (since v5.10.0)
 - `agents/doc-audit-protocol.md` — doc-reviewer's audit-mode procedures (drift validator suite, topological generation, epistemic metadata, SCIP anchors, schema/registry drift, coverage gauges); read ONLY when invoked without card context; `SECTION=` dispatch (since v5.0.0)
 - `agents/research-protocol.md` — Research discipline: `PROFILE=<decision|deep|compare|regulatory>` output contracts (+ `DEPTH=` iterative loop), the research library (`paths.research_dir` — layout, report frontmatter, INDEX, archive-not-delete), the reuse pre-flight (`FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs), and the versioned source matrix with its growth loop (`SOURCE_MATRIX_CANDIDATE`); `SECTION=` dispatch. The research-side sibling of `analysis-profiles.md` (since v5.1.0)