baldart 5.8.0 → 5.10.0

package/framework/agents/security-review-protocol.md

@@ -0,0 +1,233 @@
+# Security Review Protocol — the AppSec verification engine
+
+**Purpose**: the security-specific passes that turn a generic code review into
+an adversarial AppSec audit — repository-scoped threat modeling, the modern
+high-miss discovery lens, class-specific proof tuples, structured attack-path →
+mechanical severity, adversarial self-refutation (attacker vs victim), and a
+coverage ledger so *"not observed" never reads as "not reviewed"*. Distilled
+from the Codex `codex-security` workbench + the Claude Code `security-guidance`
+agentic reviewer. This module is the **single SSOT** of that methodology.
+
+**Relationship to `review-protocol.md`**: that module owns the GENERIC verifier
+passes (Challenge, Actionability, Simulation, Chain-of-Verification, risk
+scoring). This module **extends**, never duplicates them: `adversarial-refute`
+is the security-specialized layer that runs *inside* the generic Challenge pass;
+`proof-tuples` is the security grounding for the generic CoVe pass. On the
+generic passes, `review-protocol.md` wins; on AppSec specifics, this module
+wins.
+
+**Consumer**: `security-reviewer` (body citations). Portable as-is across Claude
+Code and Codex (read at runtime by both).
+
+## Contract
+
+- **Dispatch**: cite `agents/security-review-protocol.md SECTION=<threat-model|discovery-lens|proof-tuples|attack-path|adversarial-refute|coverage-ledger|boundary-gate>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order of passes** (normative): `boundary-gate` (once, at kickoff) →
+  `threat-model` (adopt or generate) → discovery under the `discovery-lens` →
+  per candidate: `proof-tuples` (validation) → `attack-path` (structured facts)
+  → `adversarial-refute` → mechanical severity (`review-protocol.md
+  SECTION=risk-scoring`) → `coverage-ledger` close. The generic Challenge + CoVe
+  passes still run; the security passes feed them.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report —
+  the report/YAML shape stays defined in the agent body.
+
+---
+
+### SECTION: boundary-gate
+
+Run ONCE before confirming any finding. A vulnerability only exists when an
+attacker crosses a trust boundary of a **shipped/deployed** surface — so
+classify the surface first, or you will flag same-privilege local code as a
+"vuln".
+
+1. **Read the repo's own policy FIRST**: `SECURITY.md`, `AGENTS.md` deployment
+   notes, package metadata. They define which surfaces are in-scope and what the
+   supported threat model is. A finding that contradicts a documented,
+   intentional design is a policy question, not a confirmed vuln.
+2. **Classify the surface under review**:
+   - `product_surface`: hosted service | library API | CLI | local dev UI |
+     MCP/tooling | example/demo | test | docs | generated | vendored.
+   - `source_trust` of the input: untrusted (remote/attacker) |
+     trusted_operator | trusted_developer_config | local_only |
+     intentional_code_execution.
+   - `boundary_crossed`: does attacker-controlled input reach the sink across a
+     real privilege/trust boundary? true | false | unknown.
+3. **Gate**: no boundary crossed (attacker == victim, same privilege, local dev
+   tool with no request handler) → NOT a finding. Record the disposition in the
+   coverage ledger, do not emit it as LOW.
+
+### SECTION: threat-model
+
+Establish (or adopt) a **repository-scoped** threat model — deliberately NOT
+biased by the current diff, so it stays valid for any change in the same repo.
+
+- **Adopt** an existing model from the user, `SECURITY.md`, or `AGENTS.md` when
+  present. Only **generate** a fallback when none exists.
+- Fallback generation, repository-level (not diff-scoped):
+  1. Real-world purpose + primary product/runtime surfaces actually exposed
+     (separate them from test/demo/tooling/docs paths).
+  2. Trust boundaries + the actors on each side; separate **attacker-controlled**
+     vs **operator-controlled** vs **developer-controlled** inputs explicitly.
+  3. Sensitive assets: user data, auth artifacts, authorization state,
+     secrets/keys, config, models/weights, audit logs, availability-critical
+     resources, tenant-isolation state.
+  4. Vulnerability CLASSES relevant to this repo's context (not the diff's
+     findings) + existing mitigations grounded in real files.
+  5. When realistic vs out-of-scope: state attacker (non-)capabilities so
+     severity is not inflated.
+- Use it to pick **focus paths** for the review; do not let the diff recenter it
+  unless the user asks for a diff-scoped model.
+
+### SECTION: discovery-lens
+
+Beyond the OWASP core checklist (in the agent body), sweep for the **modern
+high-miss patterns** — the ones a generic checklist walks past. For each changed
+region, ask:
+
+- **FAIL-OPEN state drift**: a default that *allows* on the unknown/error path —
+  catch-all `default: allow`, `unwrap_or({})`, a removed `finally` that left the
+  deny, an early-return before the check. Security must fail *closed*.
+- **ALLOWLIST semantic escape**: a matcher weakened — a `||`/disjunction added, a
+  regex left unanchored (`^…$` missing), an allowlist checked by `startsWith`/
+  substring, a URL trusted by substring instead of parsed host.
+- **CONTROL regression**: a deny-by-default replaced by a single positive
+  condition; an authz/confirm/audit control loosened or removed in the diff.
+- **GATE / ACTION field mismatch**: the gate checks resource A (parent, id X) but
+  the action writes/reads resource B (child, id Y) — the check and the effect
+  disagree.
+- **UNDER-VALIDATED sink arg**: user data flows into sink arg *X* while a sibling
+  path validates arg *Y* — asymmetry between siblings is the tell.
+- **PARSER/VALIDATOR differential**: the validator and the consumer parse the
+  input differently (two URL parsers, JSON vs form, unicode/normalization) — the
+  gap is the exploit.
+- **SENSITIVE-to-observability**: secrets/tokens/PII reaching logs, traces,
+  error responses, analytics, crash dumps.
+- **CI/CD trust**: `pull_request_target` / `workflow_dispatch` / injectable
+  `${{ github.event.*.body }}` combined with secrets or repo-write; a workflow
+  running untrusted code with elevated tokens.
+- **IaC omitted arg**: a Terraform/CDK/K8s resource missing a security flag
+  (public bucket, open SG, no encryption, over-broad IAM `*`).
+- **OVER-BROAD grant**: an admin/`*` role/scope where a narrower one exists;
+  new IAM/RLS/role wider than the action needs.
+- **STALE identity mapping**: a window between unregister/rotate and the new
+  binding where the old identity still resolves.
+- **SECURITY-REGISTRY fanout**: a new entity type (model, scope, route, event)
+  added but missing from the sanitizer/allowlist/authz registries that must
+  enumerate it.
+- **RESOURCE-bound placement**: a cap/limit on the wrong accumulator; an
+  under/overflow; a size check after the allocation.
+
+### SECTION: proof-tuples
+
+A security finding is a *hypothesis* until its **class-specific proof tuple** is
+grounded against real code (this is the AppSec form of the CoVe pass). Confirm
+every element by grep/read before emitting; drop the finding if any element is
+missing.
+
+- **authz / IDOR**: attacker reachability path + the missing/bypassed guard + the
+  protected object or state it exposes.
+- **injection** (SQL/NoSQL/OS/LDAP/template): attacker-controlled bytes + the
+  sanitizer/parameterization result (or its absence) + the dangerous sink.
+- **deserialization**: attacker serialized input + the unsafe loader + the
+  execution/instantiation effect.
+- **SSRF / open redirect**: attacker-controlled destination + the control bypass
+  + the network reach / side effect.
+- **auth / token**: attacker-supplied value + the validator's exact semantics +
+  the mismatch with the trusted value.
+- **XSS**: attacker string + the encoding/escaping context at output + the sink
+  (`innerHTML`/`dangerouslySetInnerHTML`/template) with no encode.
+
+**Confidence anchored to validation METHOD, never to how scary the bug class
+sounds**:
+- reproduced PoC / failing test that triggers the sink → confidence 90–100.
+- debugger/trace or a proven interface reproduction → 75–90.
+- static source→sink trace fully grounded in read code → 60–80.
+- code-understanding argument with a defensible but not fully-traced path →
+  30–55. Below that, it is a hypothesis — do not ship as HIGH.
+
+**Instance-preserving**: do NOT collapse independently exploitable sibling
+instances (`execute` / `executemany` / `executescript`; two routes with the same
+flaw) into one finding. Each independently triggerable sink gets its own
+finding/closure row.
+
+### SECTION: attack-path
+
+BEFORE assigning severity, write the attack path as **structured facts**, then
+let severity fall out of them mechanically (`review-protocol.md
+SECTION=risk-scoring`) — this stops severity from being argued emotionally.
+
+- `attacker`: who, at what trust level, from where.
+- `entrypoint`: the exact reachable entry (route/RPC/CLI/webhook/MCP tool).
+- `preconditions`: conditions that must hold for the exploit (feature flag on,
+  authenticated user, specific config). A **precondition** narrows likelihood but
+  does NOT refute — keep it distinct from counterevidence (which kills the
+  finding, see `adversarial-refute`).
+- `dataflow`: source → sink in one line.
+- `outcome`: the concrete impact (data read/written, code executed, tenant
+  crossed).
+- `impact` (1–5) and `likelihood` (1–5), each with one line of repo evidence.
+
+Severity is then `review-protocol.md SECTION=risk-scoring` applied to
+`impact × likelihood` — do not re-argue it afterward.
+
+### SECTION: adversarial-refute
+
+The security-specialized layer of the generic Challenge pass. Stance: **a finding
+SURVIVES unless you produce concrete refuting evidence** — but the single most
+common false positive is a **missing privilege boundary**, so test that first.
+
+**Privilege-boundary test (BINDING)**: name the attacker (who controls the input)
+and the victim (who is harmed). If attacker == victim operating on their own
+machine / same-privilege process (a CLI arg in a same-trust process, a dev
+script, a local tool with no remote entrypoint) → **REFUTE**. Keep it only when
+the attacker is a lower-trust actor and the impact reaches other users, tenants,
+or infrastructure.
+
+**Refute the finding when**:
+- it is **pre-existing** code untouched by the diff (in diff-scoped review, flag
+  only newly introduced or newly reachable surface; an off-diff finding must name
+  the specific `+`/`-` line that enables the sink).
+- a sanitizer / validator / parameterization / authz check on the real path
+  already prevents the exploit.
+- the sink is not actually dangerous here (typed-schema decoder, hardcoded
+  `https` URL, ORM/parameterized query, non-HTML context for an "XSS").
+- a frontend-only gate is independently enforced by the backend (or vice-versa).
+- validation is delegated to a caller/framework that provably runs it.
+- it is throwaway/dev-only code (`scripts/`, `dev/`, `__main__`, fixtures, tests)
+  with no shipped surface.
+- a dependency bump moved the control into the library (documented).
+
+**Precondition vs counterevidence (keep precise)**: "deployment is internal-only"
+is a *precondition* on the finding (still exploitable if it holds) → keep, lower
+likelihood. "the code is test-only" is *counterevidence* → refute. Do not confuse
+the two.
+
+**Never-refute guard**: an item the agent's never-demote list marks (auth bypass,
+RCE, secret exposure, cross-tenant breach with a grounded proof tuple) is never a
+false positive — do not refute it however convincing the argument sounds.
+
+Record refuted candidates (title + one-line refutation) so the audit trail shows
+they were considered, not missed.
+
+### SECTION: coverage-ledger
+
+Make the review's *coverage* explicit so a clean verdict is honest and a gap is
+never silent. For each security-relevant surface in scope, record a disposition:
+
+- `reported` — a finding was emitted.
+- `no_issue_found` — reviewed, no credible issue survived the passes.
+- `not_applicable` — the class does not apply to this surface (with the reason).
+- `needs_follow_up` — a real concern out of this review's scope/ownership
+  (surfaces as residual).
+- `deferred` — could not complete (tool/access/time), with the reason + paths.
+
+Rules:
+- A **complete** review has zero `deferred` / `needs_follow_up` rows; otherwise
+  it is **partial** — say so. Zero findings on a fully-covered surface is a
+  legitimate, reportable outcome.
+- A seeded obligation (a CVE/advisory/user pointer at a specific file/function)
+  stays OPEN until its exact row is closed as reported / not_applicable /
+  deferred — a neighboring same-family finding does not close it.
+- In the pooled YAML mode, carry this as a compact `coverage:` block in the
+  `# Security Review Summary` header, not as fake LOW findings.

package/framework/agents/security.md

@@ -55,72 +55,76 @@ Document security requirements, threats, and mitigation strategies.
 - [Sensitive data masking in logs]
 - [Secrets management]
 
-## Common Vulnerabilities (OWASP Top 10)
+## Common Vulnerabilities (OWASP Top 10 — 2021)
 
-### Injection Attacks
+> Modernized to the OWASP Top 10:2021 categories (the 2017 list — with XXE and
+> "Sensitive Data Exposure" as standalone entries — is superseded). XXE now folds
+> into Security Misconfiguration; insecure deserialization into Software & Data
+> Integrity Failures; XSS into Injection. A 2025 revision is in draft — revisit
+> when it is finalized (expected consolidation of supply-chain risks).
 
-- Use parameterized queries
-- Validate and sanitize inputs
-- Implement least privilege database access
+### A01 Broken Access Control
 
-### Broken Authentication
+- Enforce authorization on every request, server-side; deny by default
+- Prevent IDOR — never trust a user-supplied record/object identifier
+- Enforce ownership + tenant isolation on every sensitive action
+- Principle of least privilege; no privilege escalation via business logic
 
-- Implement secure session management
-- Use strong password policies
-- Implement account lockout
-- Protect against brute force
+### A02 Cryptographic Failures
 
-### Sensitive Data Exposure
+- Encrypt sensitive data at rest and in transit (HTTPS/TLS everywhere)
+- Use strong, modern algorithms (no MD5/SHA1 for security, no AES-ECB, no static IV)
+- Proper key management + rotation; never log secrets or PII
+- Strong password hashing (argon2/bcrypt/scrypt) with per-user salt
 
-- Encrypt sensitive data
-- Use HTTPS everywhere
-- Don't log sensitive information
-- Implement secure key management
+### A03 Injection (incl. XSS)
 
-### XML External Entities (XXE)
+- Parameterized queries / ORM; never build queries by string concatenation
+- Validate + sanitize inputs; allowlists over denylists
+- Least-privilege database access
+- Output encoding at the right context + Content Security Policy for XSS
 
-- Disable XML external entity processing
-- Use safe XML parsers
-- Validate XML inputs
+### A04 Insecure Design
 
-### Broken Access Control
+- Threat-model the feature before building; secure-by-default patterns
+- Establish trust boundaries and enforce them; fail closed
+- Rate limits, resource bounds, and abuse cases considered up front
 
-- Implement proper authorization
-- Validate permissions on every request
-- Use principle of least privilege
+### A05 Security Misconfiguration (incl. XXE)
 
-### Security Misconfiguration
+- Harden defaults; remove unnecessary features/debug endpoints in prod
+- Set security headers; keep software updated
+- Disable XML external-entity processing; use safe parsers/validators
 
-- Harden default configurations
-- Keep software updated
-- Remove unnecessary features
-- Implement security headers
+### A06 Vulnerable & Outdated Components
 
-### Cross-Site Scripting (XSS)
+- Keep dependencies patched; monitor security advisories (CVE/GHSA)
+- Run dependency + vulnerability scanning in CI (e.g. audit / govulncheck)
+- Remove unused dependencies and features
 
-- Escape output
-- Use Content Security Policy
-- Validate and sanitize inputs
-- Use framework protections
+### A07 Identification & Authentication Failures
 
-### Insecure Deserialization
+- Secure session management (rotation, expiry, secure cookies)
+- Strong password policy, account lockout / brute-force protection, MFA where applicable
+- No session fixation, no token leakage in URLs/logs
 
-- Validate serialized data
-- Use safe deserialization libraries
-- Implement integrity checks
+### A08 Software & Data Integrity Failures (incl. insecure deserialization)
 
-### Using Components with Known Vulnerabilities
+- Never deserialize untrusted data with unsafe loaders; validate + integrity-check
+- Verify integrity of updates/CI artifacts (signatures, SRI, pinned digests)
+- Guard the CI/CD supply chain — no untrusted code with elevated tokens
 
-- Keep dependencies updated
-- Monitor security advisories
-- Use dependency scanning tools
+### A09 Security Logging & Monitoring Failures
 
-### Insufficient Logging & Monitoring
+- Log security events; monitor for suspicious activity; alert
+- Protect log integrity; never log secrets/PII
+- Ensure exploitation attempts are detectable and auditable
 
-- Log security events
-- Monitor for suspicious activity
-- Implement alerting
-- Protect log integrity
+### A10 Server-Side Request Forgery (SSRF)
+
+- Validate + allowlist outbound destinations; parse (don't substring) URLs
+- Block internal metadata endpoints and private ranges
+- Enforce egress controls; treat any user-supplied URL/host as hostile
 
 ## Rate Limiting
 

package/framework/agents/simplify-protocol.md

@@ -0,0 +1,280 @@
+# Simplify Protocol — the reuse & simplicity verification engine
+
+**Purpose**: the simplification-specific methodology that turns a generic code
+pass into a ruthless anti-duplication / reuse-first / right-altitude audit — an
+agentic-defect taxonomy grounded in empirical research, a canonical refactoring
+vocabulary so findings are actionable, the clone-type vocabulary, a deterministic
+clone-floor contract, an internal-documentation awareness contract for reuse
+retrieval, and the judge-bias guards a *simplify* reviewer specifically needs
+(a simplify judge that rewards verbosity is inverted). This module is the
+**single SSOT** of that methodology.
+
+**Relationship to `review-protocol.md`**: that module owns the GENERIC verifier
+passes (Challenge, Actionability, Simulation, Chain-of-Verification, risk
+scoring). This module **extends**, never duplicates them — it supplies the
+simplify-specialized taxonomy, vocabulary and evidence rules that FEED those
+generic passes. On the generic passes, `review-protocol.md` wins; on
+simplification specifics, this module wins.
+
+**Relationship to the `simplify` SKILL**: the skill owns the OPERATIONAL
+workflow (identify diff → three-lens fan-out → aggregate → fix → verify). This
+module owns the taxonomy/vocabulary/bias/doc-awareness the lenses apply. The
+skill and the `code-simplifier` agent CITE this module; they do not restate it.
+
+**Consumers**: the `code-simplifier` agent (body citations), the `simplify`
+skill (Step 2), the `coder` author-time mirror (§ Author-Time Simplicity
+Discipline). Portable as-is across Claude Code and Codex (read at runtime by
+both).
+
+**Empirical anchors** (why this exists): LLM-authored code carries a
+duplication/inefficiency tax that generic linters miss — Abbassi et al.,
+*A Taxonomy of Inefficiencies in LLM-Generated Python Code* (arXiv:2503.06327,
+~90% of samples ≥1 inefficiency); Sonar, *The Coding Personalities of Leading
+LLMs* (>90% of introduced issues are code smells). Self-review is unreliable —
+Huang et al., *LLMs Cannot Self-Correct Reasoning Yet* (ICLR 2024,
+arXiv:2310.01798); Xu et al., *Pride and Prejudice: LLM Amplifies Self-Bias in
+Self-Refinement* (ACL 2024, arXiv:2402.11436). Hence: an INDEPENDENT reviewer,
+grounded in EXTERNAL evidence (clone match / zero-caller proof / resolved
+symbol), never the author's own opinion.
+
+## Contract
+
+- **Dispatch**: cite `agents/simplify-protocol.md SECTION=<taxonomy|canonical-vocab|clone-vocab|rubric|deterministic-tier|doc-awareness|bias-guards>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order** (normative): `deterministic-tier` (anchored clone candidates, once,
+  before eyeballing) → retrieval under `doc-awareness` → per candidate the
+  `rubric` lens applies its `taxonomy` class + `canonical-vocab` name →
+  `clone-vocab` classifies duplicates → generic Challenge + CoVe
+  (`review-protocol.md`) → `bias-guards` neutralize the verdict.
+- **Evidence rule (BINDING)**: every finding cites executed/retrieved evidence —
+  a clone match (`path:line` × 2), a zero-inbound-caller proof, a resolved-or-not
+  symbol, an existing-utility `path:line`. A finding whose only support is the
+  reviewer's unaided judgment is a HYPOTHESIS, not a finding — drop it or ground
+  it. This is the simplify twin of the anti-assertion-fitting rule: retrieve/run
+  first, judge second.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report —
+  the report/YAML shape stays defined in the agent/skill body.
+
+---
+
+### SECTION: taxonomy
+
+The agentic-defect taxonomy. Each class carries the DETECTABLE SIGNAL a reviewer
+or the deterministic tier keys on — never flag on vibes. Classes A1/A2/A4/A5 are
+the highest-yield agentic-specific findings (generic linters miss them; the
+research shows they are pervasive).
+
+- **A1 — Reuse-miss** (does an equivalent already exist in the repo?). Signal:
+  a new function/class/hook whose name, signature, or body is ≥Type-3 similar to
+  an existing exported symbol elsewhere; a local helper shadowing a public util;
+  no import added from the module that already owns the capability. **Highest
+  agentic-specific value.** Retrieval-driven (§ doc-awareness).
+- **A2 — Duplication / near-duplicate block**. Signal: identical token/line
+  sequence ≥ threshold in 2+ places (in the diff OR against the repo). The
+  deterministic tier (§ deterministic-tier) anchors these; classify per
+  § clone-vocab.
+- **A3 — Reinventing stdlib/native/framework capability**. Signal: hand-rolled
+  logic that is a one-liner in the language stdlib or an already-imported lib
+  (manual dedup vs `Set`, manual deep-clone vs `structuredClone`, manual date
+  math vs the date lib, manual debounce/groupBy/chunk). A new third-party
+  dependency for a stdlib-covered capability is A3 + an ADR trigger.
+- **A4 — Over-engineering / premature generalization / wrong altitude**. Signal:
+  an abstraction (interface/factory/generic/config flag) with exactly ONE
+  caller/one implementation; parameters never varied; speculative extension
+  points with no consumer; the Rule-of-Three violated (abstraction minted for the
+  first or second occurrence). See § canonical-vocab (Speculative Generality,
+  AHA, YAGNI).
+- **A5 — Dead / unused code left behind**. Signal: unused export/param/var/import;
+  unreachable branch; a function with zero inbound call-graph edges. **Advisory
+  by default** — dynamic dispatch / reflection / DI / side-effect imports produce
+  false positives; verify before deleting.
+- **A6 — Pattern inconsistency vs the surrounding codebase** (cargo-cult
+  boilerplate). Signal: the new code uses a different idiom / error-handling /
+  naming / state pattern than the 2–3 nearest sibling files; boilerplate copied
+  but partially wired.
+- **A7 — Unresolved/hallucinated API or package**. Signal: an import/call that
+  resolves to no real symbol/package (LSP "unresolved"); a method not on the
+  type's real surface. Cheap, high-value, security-adjacent (slopsquatting).
+- **A8 — Missed optimization**. Signal: quadratic where linear exists; repeated
+  recompute instead of hoist/memo; N+1; independent ops run sequentially; new
+  blocking work on a startup/per-request/per-render hot path.
+- **A9 — Complexity spike** (the umbrella smell). Signal: cyclomatic/cognitive
+  complexity, function length, nesting depth, or parameter count materially above
+  the surrounding code — see § canonical-vocab for the calibrated thresholds.
+
+### SECTION: canonical-vocab
+
+Map every finding to a NAMED refactoring concept so the fix is actionable and
+the severity is calibrated, not invented. Cite the name in the finding.
+
+**Fowler / refactoring.guru code smells** (`refactoring.com/catalog`):
+- *Bloaters* → Long Method, Large Class, Long Parameter List, Data Clumps,
+  Primitive Obsession. (A9 / A4)
+- *Dispensables* → **Duplicate Code** (A2), **Dead Code** (A5), **Speculative
+  Generality** (A4), Lazy Class, Comments-as-deodorant.
+- *Couplers* → Feature Envy, Message Chains, Middle Man, Inappropriate Intimacy
+  (leaky boundaries — A4/A6).
+
+**Four Rules of Simple Design** (Beck, `martinfowler.com/bliki/BeckDesignRules.html`),
+priority order — a finding that violates a higher rule outranks a lower one:
+1. Passes the tests. 2. Reveals intention. 3. **No duplication** (the simplify
+core — A1/A2/A3). 4. Fewest elements (A4 — no speculative parts).
+
+**Governing principles** (cite when scoping an abstraction finding):
+- **Rule of Three** — do NOT abstract until the third occurrence; abstracting on
+  the first/second is A4. The mirror caveat: `code-reviewer` will not *demand*
+  abstraction for ≤3 repetitions either — the two agents agree at the boundary.
+- **AHA** (*Avoid Hasty Abstractions*, Kent C. Dodds) / **"duplication is far
+  cheaper than the wrong abstraction"** (Sandi Metz) — prefer a little
+  duplication over a wrong/leaky abstraction. So an A2 duplicate is only worth
+  unifying when the shared shape is genuine, not coincidental.
+- **YAGNI / KISS** — no extension point, config flag, or parameter without a
+  present consumer (A4).
+
+**Calibrated complexity thresholds** (A9 — cite the number, never invent one;
+these are surrounding-code-relative signals, not absolute mandates):
+- Cyclomatic complexity per function **>10** warn / **>15** act (McCabe 1976;
+  NIST SP 500-235).
+- Cognitive complexity per function **>15** (SonarSource S3776 default;
+  Campbell white paper — penalizes nesting/flow-breaks over raw branch count).
+- Function length **>~50 LOC**, nesting depth **>4**, parameters **>3–4**
+  (ESLint `max-lines-per-function` / `max-depth` / `max-params` defaults).
+  Treat as *relative to the file's neighbours*; a spike vs siblings matters more
+  than the absolute number.
+
+### SECTION: clone-vocab
+
+Classify every A2 duplicate. The vocabulary sets the fix and who catches it.
+
+- **Type-1** — identical modulo whitespace/comments. Deterministic tier catches
+  it. Fix: delete + reuse, or extract.
+- **Type-2** — identical modulo renamed identifiers/literals/types. Deterministic
+  tier catches it only with identifier normalization (which the built-in floor
+  does NOT do — the reviewer catches these). Fix: extract parametrized shared.
+- **Type-3** — copied-then-modified (added/removed/changed statements — the gap
+  case). Partially caught by the floor's line-window overlap; the reviewer
+  confirms. Fix: extract with parameters for the delta.
+- **Type-4** — semantically equivalent, syntactically different. Structurally
+  invisible to any deterministic tier — **this is the reviewer's job**, backed by
+  retrieval (§ doc-awareness) and behavioural reasoning, never a hash.
+
+Fix-classification (reused by the skill's aggregation): Exact duplicate → delete
+new, use existing · Near duplicate → extract shared parametrized · Inline
+reimplementation → replace with the existing utility · Dependency-reimplements-
+native → native primitive + remove dep.
+
+### SECTION: rubric
+
+The lens checklists the operational pass applies. The `simplify` skill fans these
+out as its three parallel lenses; the `code-simplifier` agent runs them as one
+persona covering all lenses. Each lens tags findings with its `taxonomy` class.
+
+- **Reuse lens** (A1/A2/A3) — the load-bearing, cross-codebase job the author
+  could not see from inside the task. Consume the deterministic tier's anchored
+  clone candidates FIRST (§ deterministic-tier), then retrieve reuse candidates
+  (§ doc-awareness), then judge Type-2/3/4 the tier missed. Classify per
+  § clone-vocab.
+- **Quality lens** — redundant state (derivable values, effects where a direct
+  call works), parameter sprawl, copy-paste-with-variation, leaky abstractions,
+  stringly-typed code, unnecessary nesting/wrappers, unnecessary comments
+  (WHAT/change-narration — keep only non-obvious WHY).
+- **Design-altitude lens** (A4/A6 — the *design-defect* coverage) — single-caller
+  abstraction / Rule-of-Three violation / speculative generality / config flag
+  with no consumer (A4); pattern inconsistency vs the 2–3 nearest sibling files
+  (A6); leaky boundaries. **Advisory by default** — "wrong altitude" is the most
+  judgment-heavy class; a *simplify* pass that fabricates abstraction complaints
+  causes the churn it exists to prevent. Fold into the Quality lens (skill) /
+  cover as one persona (agent); do NOT spin a fourth parallel spawn.
+- **Efficiency lens** (A8) — unnecessary work, missed concurrency, hot-path
+  bloat, recurring no-op updates (add change-detection guards), unnecessary
+  existence checks (TOCTOU), memory leaks, overly broad reads.
+
+### SECTION: deterministic-tier
+
+The anchored clone floor. Grounds the reviewer with an external signal it lacks
+(the research: an LLM eyeballing a diff misses clones exactly as it misses its
+own smells). Run BEFORE eyeballing; feed anchored candidates to the Reuse lens.
+
+- **Tool**: `framework/.claude/skills/simplify/scripts/simplify-scan.mjs` — a
+  zero-dependency Node scanner (identical on Claude Code and Codex; the twin of
+  `ui-design/scripts/craft-check.mjs`). Rolling-hash near-duplicate detection
+  over `diff × repo`.
+- **Contract** (what it MUST do to be signal, not noise): whitespace + comment
+  normalization; NO identifier normalization by default (that explodes
+  boilerplate false positives — Type-2 is the reviewer's job); minimum window
+  (~6 lines / ~50 tokens) below which everything matches; an ignore-list that
+  reuses the project's `.gitignore` + generated/vendored/lockfile/min/snapshot/
+  migration conventions; import-block and trivial-statement suppression. It emits
+  anchored candidates (`path:line` × the matching loci + clone type). It NEVER
+  edits and NEVER decides — it PROPOSES; the reviewer DISPOSES (verifies each
+  candidate, discards false positives, promotes real ones).
+- **No external-tool tier in the floor** (deliberate, since v5.10.0): the floor
+  is the always-on, stack-agnostic capability. Richer external detectors (jscpd,
+  lizard, ast-grep, knip, vulture) are NOT wired here — they are 3-ecosystem
+  binaries whose silent presence would be non-deterministic capability drift, and
+  they break Codex portability. Should they ever be added, it is behind a
+  DEDICATED flag with full schema-change propagation + a documented Codex
+  fallback + a measured redundancy analysis vs this floor — never ambient
+  detection and never gated on `has_toolchain` (a proven false coupling: that
+  flag installs Biome/Vitest/tsc/Lefthook, none of these).
+
+### SECTION: doc-awareness
+
+Reuse-miss (A1) is a retrieval problem, and the highest-signal source in a
+BALDART consumer is the internal documentation that catalogs what already exists.
+The reviewer MUST consult it — but under a strict posture, because docs drift.
+
+**Retrieve-then-verify (BINDING)**: internal docs are a HIGH-RECALL INDEX for
+FINDING reuse candidates; **the code is the SSOT** and CONFIRMS the match. Never
+decide a reuse-miss on the doc alone (a stale registry entry may point at dead
+code); never feed a textual doc proxy where the ground-truth code is readable
+(the anti-assertion-fitting rule). Consult, in order of signal:
+
+1. **Component / utility registry** — `${paths.references_dir}/component-registry.md`
+   (the authoritative inventory of primitives, shared components, hooks, utility
+   modules). The #1 reuse map; scan it before grepping.
+2. **Design system** — `${paths.design_system}/INDEX.md` + `components/<Name>.md`
+   (UI reuse + closed-set members) when `features.has_design_system: true`.
+3. **Code graph** — Graphify `GRAPH_REPORT.md` (communities / god-node clusters)
+   + `graphify query`/`affected` when `features.has_code_graph: true`.
+4. **Symbol layer** — LSP `workspace/symbol` + `find-references` when
+   `features.has_lsp_layer: true`.
+5. **API / data-model / schemas** — `${paths.references_dir}/api/`,
+   `data-model.md` — to catch a reinvented endpoint/type/validator.
+6. **Wiki syntheses** — `${paths.wiki_dir}/` ("we already have a pattern X").
+7. **ADRs** — `${paths.adrs_dir}/` — a dependency/abstraction with a deliberate
+   ADR is NOT a removal candidate; respect the recorded intent.
+
+**Do NOT duplicate the retrieval protocols** — cite them: the search hierarchy is
+`agents/code-search-protocol.md`, the graph queries `agents/code-graph-protocol.md`,
+the registry-first cascade `agents/design-system-protocol.md`, path resolution
+`agents/project-context.md`. Universal fallback is grep (silent, never abort).
+
+**Doc-drift is a handoff, not a fix** (strict specialization): if the reviewer
+finds the registry stale w.r.t. a symbol (a new util duplicating an existing one
+that is not in the registry, or an entry pointing at dead code), it emits an
+**advisory** finding and hands the doc reconciliation to `doc-reviewer` — it does
+NOT rewrite the registry itself.
+
+### SECTION: bias-guards
+
+An LLM judge carries biases that are specifically corrosive to a *simplify* pass.
+Neutralize them mechanically.
+
+- **No verbosity reward (INVERTED for simplify)** — general LLM-judge verbosity
+  bias (MT-Bench; *Justice or Prejudice?* arXiv:2410.02736) rewards longer
+  answers. A simplify reviewer wants the SHORTER, fewer-elements solution; longer
+  code is a *negative* signal, never a positive. Never prefer a change because it
+  adds structure.
+- **Independence (no self-grading)** — the reviewer is INDEPENDENT of the author:
+  fresh-context minimum, cross-model ideal. On a same-model run it is
+  fresh-context adversarial, NOT cross-model — state that honestly, never claim
+  cross-model diversity the run does not have. The author (`coder`) applies an
+  author-time subset (its § Author-Time Simplicity Discipline) but never grades
+  the final diff for reuse — that is this pass's exclusive, load-bearing job.
+- **Evidence over opinion** — see the Contract's evidence rule; a survivor of the
+  generic Actionability pass that needs no change is a cleared concern, not a
+  finding.
+- **Severity is absolute, not a quota** — zero findings on a clean diff is a
+  legitimate, expected outcome. Do NOT invent problems (the skill says it
+  verbatim). A false abstraction complaint causes churn — the anti-goal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"