map-gaps.md

Map gaps & cross-cutting findings

Surfaced during the phase-1 research pass (2026-06-08). These are structural observations about the taxonomy that feed phase 2 (skill-suite architecture) — especially the granularity decision (Q1). Kept separate from open-questions.md because each is a concrete design constraint, not an open question.

G1 — Concerns that are double/triple-booked → each needs ONE canonical owner

Several factors legitimately appear under multiple categories. For the map that's fine (it's a graph). For skills it's a hazard: two skills flagging the same issue produces duplicate, possibly-conflicting findings. Each concern below needs one owning skill; the others reference it.

Update (2026-09-05): phase 2 (skill-suite architecture) is long since built — every category named in the "Owner" column below shipped as a real lens (e.g. #18 → auditing-dependencies-and-supply-chain, #27 → auditing-compliance-and-provenance, #26 → auditing-config-and-build-hygiene, #16 → reviewing-observability-and-operability, #4 → tracing-correctness-and-invariants, #23 → reviewing-accessibility-and-i18n, #7 → reviewing-naming-and-readability), each carrying this table's single-owner split in its manifest cross_ref/dedupe notes. "TBD phase 2" below is a phase-1-era label; the assignments were decided and built, not left open.

Concern	Appears in	Owner (built)
Dependency / CVE / supply-chain	#14 security, #18 deps, #25 (LLM03)	#18, with #14 deferring to it
PII / sensitive-data handling	#14 security, #16 logging, #27 compliance	#27 detects, #14/#16 enforce at their boundary
Feature-flag hygiene & lifecycle	#12 arch, #16 operability, #26 config	#26 (lifecycle/cleanup), #12 (architecture only)
Graceful startup/shutdown	#16, #26	#16
Money / units / measurement	#4 correctness, #23 i18n	split: value-correctness → #4, formatting → #23
AI-generated code provenance	#25, #27	#27
Doc-drift vs comment-rot	#22 (doc drift), #7 (comment rot)	boundary: in-code comments → #7, external docs → #22

Principle to adopt: detection has a single owner; other categories may enforce at their boundary but don't re-report.

G2 — Candidate promotion: "Excessive Agency" / agentic tool-use safety

OWASP LLM Top 10 LLM06 (Excessive Agency) + Simon Willison's "lethal trifecta" (private-data access + untrusted-content exposure + exfiltration/action ability) may be big enough to pull out of #25 into its own category. It cross-cuts #14 (security) and #13 (API/contract design, since it's about what actions a tool surface permits). Decision deferred; flagged as the most likely next promotion after the v0.2 three.

Update (2026-06-12) — external validation landed. OWASP now treats agentic risk as its own discipline: a dedicated Top 10 for Agentic Applications (ASI01–ASI10, released 2025-12-09) separate from the LLM-app list, with the Agentic AI: Threats and Mitigations (v1.0, 2025-02) companion; the MCP spec ships its own security-best-practices page (confused deputy, token passthrough, tool poisoning). The references + nine agentic heuristics are filed under #25 in research/cluster-4-runtime.md regardless of the promotion call, so no research is blocked on it.

Resolved (2026-06-12, D14 / Q16): promoted to category #32 — Agentic & tool-use safety (cross-cutting #13/#14/#24/#25), scoped to the action/tool surface with a model-call↔action G1 boundary (lethal-trifecta framing stays in #25). taxonomy.md carries #32; the owning lens reviewing-agentic-safety shipped 2026-06-24 — the agentic heuristics moved from cluster-4 #25 into a new #32 research section (8 ASI heuristics + the lethal-trifecta exfil/action-leg mitigation, 2 ★), with manifest entry, generated skill, examples, 4 evals, and a dedicated router route; #25 keeps the model-call concerns behind a boundary note (drift clean). The trigger gap (agent-heavy repos that don't read as "LLM integration") was the decider over the cheaper "sharpen #25's trigger" path. Cross-model re-gate passed 2026-06-24 (qwen2.5:7b floor + llama3.1:8b cross-confirm; no over-flagging — see session-log).

G3 — Decomposition tension the suite MUST take a stance on

Category #6 (local readability, Clean-Code lineage: extract aggressively, many small functions) directly conflicts with #11/#9 (Ousterhout: deep modules, don't over-decompose; shallow wrappers are negative-value). A "split this up" reviewer and a "stop over-abstracting" reviewer will contradict each other on the same diff. The suite needs an explicit altitude/decomposition policy before either skill ships. Relates to counterweight enforcement (Q5).

G4 — Readability coverage seam

Category #5 (naming = intention-revealing meaning) and #8 (consistency = uniformity, casing/convention) overlap on naming rules. Split cleanly: meaning → #5, uniformity → #8.

G5 — Where LLM judgment is the ONLY tool (build here first)

These factors have little or no static-analysis coverage, so an LLM reviewer adds unique, non-redundant value — and they should be prioritized in phase 2 because tools don't already do them:

• altitude/abstraction-level mixing (#6)
• symmetry of expression (#6)
• premature abstraction / the wrong abstraction (#11) — counterweight
• premature optimization (#15) — counterweight
• naming quality beyond casing (#5)
• agent-native parity (#24)
• caller ergonomics / "pit of success" (#9)

Corollary: where mature linters already cover a category well (formatting, basic complexity, many security/a11y rules), the skill's job is to orchestrate/triage tool output, not re-implement it.

G6 — #8 is probably a family, not a skill

Idiom/consistency is inherently per-ecosystem (the dhh-rails / kieran-* prior-art pattern). #8 likely becomes a language-agnostic core + opt-in idiom packs rather than one generic skill. Drives the language strategy question (Q6).

G7 — Some skills need git history, not just the diff

Category #21 (maintainability) is meaningfully VCS-history-aware: churn × complexity hotspots, change-coupling, bus factor (CodeScene / Adam Tornhill's Your Code as a Crime Scene). These can't be assessed from a single diff. Implies a class of repo/history-shaped skills distinct from diff-shaped ones (relates to Q8: are some skills cron-shaped?).

G8 — Detection vs. adjudication boundary (esp. #27)

Several #27 checks (regulatory interpretation, license-law compatibility) should escalate to a human, not be adjudicated by the agent. The agent's job is detection + flagging with evidence, not legal judgment. Generalize: every skill should know which findings it can resolve vs. which it must escalate. Matches Q9.

G9 — Factor-level propagation gap: category ownership is complete, factor surfacing leaks

Full taxonomy-vs-skills sweep (2026-06-12). All 27 categories have an owning skill — no orphaned research, no un-skilled area. But ~10 categories are only partially surfaced at the factor level: a factor lives in taxonomy.md (often also in the skill's heuristics.md) yet never reaches a top-level inlined check, so it almost never produces a finding. The originating observation was that the suite emits no naming findings in practice despite #5 being owned.

Three mechanisms drive the leak:

1. Router under-selection. A lens only fires when choosing-review-lenses picks it, and the 2-4 cap means soft lenses run on few change shapes — reviewing-naming-and-readability appears in just 3 of ~20 routes (feature, refactor, UI). On bug fixes, migrations, async, API, security, perf, LLM, config, and every repo audit it is never invoked. (This is the router-intent problem — see Q14.)
2. Bundle + ~8-check budget. Multi-category skills split a single ~8-check inlined budget, crowding out the junior category's factors: #5 naming + #6 readability + #7 comments, #9 module + #10 type-modeling, #19 build + #26 config/portability, #18 deps + #27 compliance.
3. Severity trimming. The synthesizer (D12) floats correctness/security to the top and ranks Nit last, so the readability class sinks and gets trimmed from the merged report even when produced.

Dropped (absent even from heuristics.md): #12 scalability-of-the-design; #12 feature-flag architecture (runtime flags are in #16; flag design is nowhere); #15 cloud-cost / FinOps (residual candidate); #16/#27 telemetry-analytics privacy (residual candidate).

Thin (heuristics-only or a single passing line, not a surfaced check): #26 portability / environment assumptions (OS/arch, hardcoded paths, locale/encoding/timezone); #16 SLO / error-budget instrumentation; #6 symmetry of expression & altitude mixing; #21 change-amplification & onboarding cost; #24 agent-native parity & CODEOWNERS; #9 caller ergonomics ("pit of success") & composition-vs-inheritance; #4 numeric overflow / counter wraparound.

Irony vs. G5. Several of the thin factors — altitude, symmetry, naming quality beyond casing, agent-native parity, caller ergonomics — are exactly the ones G5 flagged as build-here-first because LLM judgment is the only tool that covers them. The propagation gap hit the highest-unique-value factors hardest: the parts of the map that most justify an LLM reviewer are the parts most likely to go silent.

Fix surface (spans three layers): the manifest (promote dropped/thin factors into inlined checks; rebalance the bundled-category budgets), the research docs (the two genuinely-missing #12 factors need research before they can be a check), and the router (stop the under-selection — Q14). Diff-shaped factors regenerate from the manifest; #12 scalability/feature-flag-design need a research pass first.

✅ Partial fix shipped 2026-06-15 (the budget layer). Added an inline-priority marker (★) the generator honors: a research heuristic bullet flagged with it is additively inlined into the owning lens's Top checks regardless of position (marker stripped from all output; cross-ref lenses ignore it so a factor surfaces only in its owner; section_hash unchanged so drift stays clean). Because it is additive, promoting a deep factor never displaces a foundational position-based check — only a marked lens grows, by the number of marks, keeping it targeted rather than a blanket budget raise. Promoted the demonstrated leakers: calendar/clock time-bombs + numeric overflow (#4), claims-vs-evidence + agent-native parity (#24), caller-ergonomics / pit-of-success (#9), portability (#26), symmetry of expression (#6). ✅ The remaining two layers — router under-selection and severity-trimming — were resolved by D16 (Q14, 2026-06-24): the comprehensive depth mode runs every applicable lens (closes under-selection) and pins the severity floor at Nit with no per-round escalation (closes the trimming that silenced readability-class findings). Build deferred (manifest modes: + per-mode floor); design in review-depth-modes.md.

G10 — The enforcement apparatus (and the meta-layer generally) was never framed as a reviewable surface

Surfaced 2026-06-12 chasing "where would set up a vuln scanner or tidy up linter ignores live?" The answer split three ways and exposed a framing-level gap deeper than G9's propagation gap:

1. Tool-mechanization nudge — trivial, already latent. Every lens carries reference/tool-rules.md; surfacing "you detect this by hand — tool X gates it in CI, consider wiring it up" is additive output and advisory (not the Q8 fixing-mode). auditing-config-and-build-hygiene already does a version of it ("fix it or swap in a maintained equivalent", SKILL.md:39). Action: a generator pass appends an optional mechanize-with: line to each lens's finding contract.
2. Gate / enforcement health — already covered. "Is a quality gate disabled or soft-failed (continue-on-error / || true / allow_failure / a skipped check)?" is in the corpus (cluster-5-verification.md §19) and shipped (auditing-config-and-build-hygiene/SKILL.md:39 + an eval; reinforced by cluster-2:145 "presence and enforcement is itself the control" and cluster-6:175 actionlint/required-checks). The "re-enable / provision the missing scanner" case is live.
3. In-code suppression rot — a genuine research-corpus hole. # noqa / eslint-disable / # type: ignore accumulation, blanket-disabled rules, growing lint baselines, suppressions with no rationale or expiry: absent from docs/research/ entirely, owned by no skill. Falls between #8 (config conformance), #19 (gate config), and #21 (debt) — and because no category was shaped to attract it, it was never written.

The structural lesson (the reason this matters beyond the example). The map covers artifacts, their properties, and mistake-detection. It never framed the enforcement apparatus itself — the gates, suppressions, and tooling config wrapped around the code — as a first-class reviewable surface. Gate-health landed only because it fell incidentally inside #19; the code-level suppression residue had no home, so it went unresearched. Generalize:

A missing category does not yield a thin heuristic you can spot by auditing the skills (that is G9). It yields a silent hole — the factor is never written at all. G9-class gaps are findable by diffing taxonomy ↔ skills; framing-class gaps are invisible to that diff and only surface by asking "what kind of reviewable thing did we never put on the map?"

This is precisely why a taxonomy-vs-skills audit can't be the gap-hunting method for framing gaps. It motivates a second from-first-principles research pass over kinds of reviewable surface — the round-2 gap hunt (research/taxonomy-gap-hunt-round-2.md), seeded by the meta-layer and decision-lifecycle omissions this finding exposed (enforcement apparatus; documentation-as-designed-system; binary/generated artifacts; dependency selection & exit vs. mere patching; …).

Resolved (2026-06-12, taxonomy v0.3 / D13): the enforcement apparatus is now a first-class category — #30 Enforcement apparatus & meta-artifacts (suppression hygiene, monitoring-config-as-artifact, codegen↔source drift) — owned by the repo-shaped audit auditing-enforcement-and-meta-artifacts (research in research/cluster-5-verification.md #30). The framing hole this finding named is closed.

G11 — Artifact-authoring quality is a reviewable surface we hold ourselves to but never review

Surfaced 2026-06-12 (owner question: do we have anything correlating to Anthropic's Agent Skill authoring best-practices guide?). The answer split two ways and exposed a framing-class gap (the G10 kind — a silent hole, not a thin heuristic):

1. As authors — fully covered. The best-practices guide is D7, transcribed into our building standard and enforced in the pipeline: tooling/manifest.py validates description ≤1024 chars; tooling/generate_skill.py inlines top checks (progressive disclosure), emits gerund names, one-level-deep bundled files, no time-sensitive text. The suite is a reference implementation of the guide.
2. As a review lens — unowned. Nothing reviews someone else's SKILL.md / agent definition against that standard. The two nearest touchpoints miss it: #24 "agent-native parity" is about the product exposing agent-reachable actions; #22/#24's AGENTS.md-as-doc-artifact (added 2026-06-12) covers only drift (is it still true?), not authoring quality.

The generalization (the reason this matters beyond the example). "Is this SKILL.md well-authored?" is one instance of a broad class: files that are not application source but carry their own canonical "well-formed X" standard and dedicated linter — Dockerfiles (hadolint), Terraform (tflint/Checkov), K8s manifests (kube-linter), CI workflows (actionlint/zizmor), OpenAPI specs (Spectral/Zally), ADRs, changelogs, AGENTS.md, model cards, datasheets, SKILL.md. The atlas touches several of these but always folded into a topic cluster (migrations→#20, IaC→#31, CI→#19, API specs→#13), never as a declared artifact-scoped review shape with presence-based activation. That missing slot is why the SKILL.md case had nowhere to land.

Generalize G10's lesson once more: the map frames artifacts → properties → mistake-detection, and #30 framed the enforcement apparatus as reviewable — but neither framed "is this artifact well-formed per its own published standard" as a first-class, presence-activated review behavior spanning artifact types.

Three distinct agent-surfaces (this gap clarified that they're separate, which informs the Q16 call): runtime agent security (tool least-privilege, lethal trifecta) → Q16/#25; agent-facing docs drift (AGENTS.md stays true) → #22/#24; agent-artifact authoring quality (SKILL.md built to the guide) → this gap, unowned. Bundling authoring under a Q16 security category would blur the trigger.

Disposition (resolved 2026-06-12).

Concern	Decision
"Is this artifact well-formed per its standard?" (the factor)	→ #30 meta-artifact factor (D15) — keeps #32 = runtime agent safety, #22/#24 = doc-drift; three distinct agent-surfaces stay separate.
How to host many artifact lenses without top-level context bloat (the pattern)	→ a new shape: artifact (D15, Q18 option b) — one entry-point lens + manifest artifacts: table + bundled on-demand rubrics; SKILL.md-authoring is the first instance.

Full research — the artifact-standard catalog (the references beyond the one guide), the context-cost evidence (lost-in-the-middle, context rot, RAG-MCP, the OpenAI/Gemini ~128-function per-request cap — Anthropic ships a tool-search tool instead of a fixed ceiling), the presence-based-activation prior art (MegaLinter/ESLint-overrides/Spectral), and the three hosting options — is in research/artifact-scoped-lenses.md. Status: ✅ shipped 2026-06-24 — option (b) built as the shape: artifact family: the entry-point lens reviewing-artifact-conventions presence-detects an artifact and loads its bundled rubric, driven by a manifest artifacts: table; rubric sections live in research/artifact-rubrics.md (numbered ≥101 to stay clear of the 1–37 taxonomy in the G1 owner check). First rubric: SKILL.md authoring (the standard we already enforce on ourselves); the G11 factor lives at #30. Further artifact rubrics are additive (a research section + an artifacts: row each).

G12 — Validation vs. verification: the suite checks "does it match the intent," never "is the intent right"

Surfaced 2026-06-14 (owner question: are we accounting for alignment with stakeholder intentions at any level?). A framing-class gap (the G10 kind — invisible to a taxonomy-vs-skills diff, because the whole map presupposes intent-as-given).

The taxonomy is rooted at Cluster I — Does it work? — conformance to a stated intent is the floor of the entire atlas. Every correctness check takes that intent as a given: tracing-correctness-and-invariants asks "does the implementation match the spec/PR description's stated intent" (cluster-1-correctness.md #46, billed as "the check no linter can do"), but the spec itself is never questioned. That is verification (build the thing right), not validation (build the right thing).

The suite does ask "is this the right thing?" in exactly one place — reviewing-decision-lifecycle / the decision-time shape ("is this the right dependency / framework / platform to adopt vs. a smaller option or building it", decision-time-review-shape.md:18) — but scoped to decisions (ADR/RFC/adoption), never to a feature diff. So the suite already owns "right thing?" for one shape and withholds it for the rest.

Nothing reviews whether a diff satisfies the acceptance criteria of its linked issue, traces to a stated stakeholder/user need, or whether the intent it conforms to is itself sound. Acceptance-criteria / requirements-traceability on a diff (does this PR deliver what the issue asked — no more, no less) is a recognized review dimension with no owner here. Distinct from #1 (matches the stated intent) and #29 (decision soundness): this is diff-time alignment of the change to the requirement behind it.

Disposition (user, 2026-06-14): in-scope gap — a candidate review behavior, not a scope boundary. (The decision-lifecycle precedent cuts against treating "right thing?" as out of scope.) Candidate placement and shape — a diff-time acceptance-criteria/requirements-traceability lens vs. folding a "is the requirement sound" facet into the decision-time shape — left to a disposition pass. ✅ Shipped 2026-06-15 as a factor (Wave B, per the synthesis: start as a factor, earn a lens later): "acceptance-criteria traceability" on reviewing-pr-and-process-hygiene (#24) — does the PR deliver what its linked issue asked, no less (criteria met) and no more (no unrequested scope)? Framed as validation, distinct from #1 (code-vs-stated-intent) and #29 (decision soundness). Unmarked (full checklist); promote to a dedicated lens if it earns it. Eval added.

G13 — Tidy First?: the tidyings are in as review hints; the economics and the proactive mode are not

Surfaced 2026-06-14 (owner question: do we have equivalents to Kent Beck's Tidy First? catalog of tidyings and heuristics?). Tidy First? is already cited (references.md:22) and mined into cluster-2-readability.md #59 — but only one of its three parts landed:

1. The tidyings as review heuristics — covered. Guard clauses, explaining variables, dead-code removal, reading order, normalize symmetries, symmetry-of-expression all live in reviewing-naming-and-readability (alongside Fowler's smell→refactoring names). When reviewing a diff, the suite will recommend these.
2. The tidyings as a proactive maintenance action — unbuilt. Applying small structural refactorings rather than only flagging them in someone else's diff. This is the open half of Q3 (review-vs-maintenance) / Q8 (the fixing mode): detection ships, fixing does not. A named tidyings catalog is the natural content of that mode.
3. The economic heuristic — the book's actual thesis — unowned. Now / after / never timing, coupling-and-cohesion as the cost driver, the option value of structure, batch size, and separating structural changes from behavioral ones (own commit/PR). Pieces are scattered — connascence in reviewing-module-design; churn × complexity ("where it pays to tidy") in finding-maintainability-hotspots; "atomic commits / single purpose" in reviewing-pr-and-process-hygiene — but Beck's sequencing rule (tidy first, separately, before the behavior change) has no owner, and the now/after/never economics is nowhere.

The structural-vs-behavioral split (3) is adjacent to but not the same as #24's "atomic commits / no drive-by scope creep": hygiene wants one purpose per PR; Beck wants structural and behavioral changes in separate PRs even when they serve one feature. Worth deciding whether #24 absorbs it or it belongs to the tidying mode.

Disposition: open. (2) refined by G26 — the suggestion of a tidying is review-time (gated only by the defect-only guard, not by the unbuilt fixing capability); only auto-application is Q8. (3) is a candidate factor — likely #21 (maintainability economics) and/or #24 (commit sequencing) — pending a disposition pass. ✅ Part (3) shipped 2026-06-15 (Wave B): the now/after/never economics + coupling-as-cost-driver → finding-maintainability-hotspots (#21); the structural-vs-behavioral separation (Beck's stronger-than-atomic-commits rule: refactoring and the feature it enables in separate changes) → reviewing-pr-and-process-hygiene (#24, which absorbs it). Both unmarked (full checklist) — #21/#24 are already well-surfaced. Part (2) auto-application remains Q8.

Round-3 gap hunt (G14–G22)

Surfaced 2026-06-14 by a third gap hunt that reasons from outside the map — full method, prior art, and dispositions in research/taxonomy-gap-hunt-round-3.md. Each entry below is the yield of a distinct new gap-finding method (external completeness model, stakeholder-vantage rotation incl. the agent-as-reader vantage → G20, substrate sweep, shape-axis extrapolation, the failure-grounded model → G21, and adversarial/inversion → G22). All provisional — owner-gated, web-verified prior art cited in the research doc. No taxonomy.md edit or version bump yet.

G14 — Characteristic defects of AI-authored code

Surfaced via the substrate sweep (and reflexively — this suite is itself AI-built). The map reviews code that calls an LLM (#25) and tracks AI provenance markers (#27), but has no lens for the failure signature of machine-authored code itself, regardless of author: hallucinated/misused APIs, plausible-but-wrong logic that reads fluently, over-helpful unrequested additions (ties checking-restraint), and package hallucination → slopsquatting (~20% of LLM-recommended packages are non-existent; ~45% of LLM code carried security flaws in a 100+-model study — sources in the research doc). Distinct from #25 (code that uses AI) and #27 (a provenance marker). Diff-reviewable, high present-day base rate. Disposition (lean): promote (diff lens) — package-hallucination leg xref #18, plausible-wrong/over-helpful legs xref #1 and checking-restraint. Confidence: high. ✅ Shipped 2026-06-17 (Wave C, taxonomy v0.4) as reviewing-ai-authored-code — new category #34 (research cluster-4-runtime.md#34), primary-owns #34 and cross-refs #18 (the slopsquat leg dedupes under the supply-chain owner); attribution-agnostic, defers the deep verdict to #18/#14/#1/#11. Dedicated router route added; 4 evals; drift clean.

G15 — Production-evidence / runtime-informed review (a candidate fifth shape)

Surfaced via shape-axis extrapolation (the move that found round 2's decision shape). All four shapes — diff / repo / decision / artifact — are source-derived; none consumes the running system's own signals (error-rate deltas on the changed path, slow-query/trace evidence, real cardinality, actual usage) as a review input. The suite reviews observability code (#16) but never reads telemetry to find defects that only manifest at runtime. Prior art validates telemetry-as-truth (observability-driven development, trace-based testing) but mostly shift-left; the shift-right move of feeding live evidence into a change review is thinly precedented (signal: novel). Disposition (lean): promote as shape: runtime (sibling to the existing four), lower priority — needs a telemetry-access substrate and D12-style orchestration. Confidence: medium. Partially addressed 2026-08-23: field report #191 confirmed a real instance of this gap's static half — a repo audit blind to a deployment/execution arrangement that's dangerous by construction, discoverable from a checkout alone, no live telemetry needed. That half shipped as shape: repo category #45 (Deployment-pipeline & trust-boundary security, taxonomy v0.14) rather than waiting on the full shape: runtime substrate. This lens's own shape: runtime candidate — genuinely telemetry-informed review (error-rate deltas, trace evidence, real usage) — remains open and deferred; #45 cannot see it, only what's committed.

G16 — Ethical / responsible-design defects in non-ML code

Surfaced via stakeholder-vantage rotation (the end user as a subject of behavior, not a buyer). Ethics is reviewed today only where it is legal (#27) or ML-output (#25 harmful-output). The diff-visible, code-level class is unowned: dark patterns / deceptive flows, manipulative defaults (pre-checked consent, asymmetric opt-out), obstruction/sneaking/forced-action in ordinary control flow, and discriminatory business logic in plain conditionals (a hardcoded threshold disadvantaging a group — no model in sight). Operational taxonomies (Mathur 7-category; EDPB 6-family/16-subcategory) and live regulation make this concrete, not hand-wavy. Disposition (lean): promote, detect-and-escalate (G8) — flag with evidence; consent-as-legal defers to #27, pure-product judgment escalates to humans. Confidence: med-high. ✅ Shipped 2026-06-17 (Wave C, taxonomy v0.6) as reviewing-ethical-design — new Cluster IV category #36 (research cluster-4-runtime.md#36), the non-ML analog of #25 harmful-output and a sibling of #14. shape: diff; nine heuristics, two ★ (dark patterns; manipulative defaults), grounded in cited prior art (Mathur 7-category, EDPB 6-family, FTC report, sub-50%-detection-coverage, Deception at Scale). Strictly detect-and-route (relies on the shipped G23 axis): consent-as-law → #27/legal, product trade-off → product/leadership, a11y mechanics → #23. Discriminatory logic and consent-theater are typically defects; most dark-pattern verdicts route: product. Dedicated router route; a sweeping-for-security ↔ reviewing-ethical-design tension added (protective friction vs. obstruction — the long-noted security↔usability pair, now buildable); 4 evals; drift clean. Out of scope: deep model-fairness auditing (no diff artifact); transparency UX is the unbuilt G24 VII-G. A design-time arm is a noted follow-up.

G17 — Data-engineering & data-contract quality

Surfaced via the substrate sweep (the data/analytics plane). The map is OLTP-app-centric: #20 owns migration/persistence safety, #13 owns service API contracts, but nothing owns SQL/dbt transformation correctness, data tests (freshness/completeness/uniqueness/distribution), or producer↔consumer data contracts for events and analytics schemas — the silent break when an upstream field changes and downstream pipelines rot. Mature, standardizing prior art (data contracts, schema-registry compatibility, dbt + Great Expectations + Soda, CI enforcement). Disposition (lean): promote — a diff lens (transformation correctness + data-test adequacy) paired with a repo/cron arm (contract drift), mirroring the #13/#20 split; scope to data-as-code in the repo (warehouse governance escalates). Confidence: med-high.

✅ Diff arm shipped 2026-08-04 (Wave D, taxonomy v0.10) as reviewing-data-transformations-and-contracts — new Cluster V category #40 (research cluster-5-verification.md#40), sited next to #20 as its analytics-plane counterpart. shape: diff, design-capable (an event-schema proposal or pipeline design doc is as reviewable as the SQL). Thirteen heuristics, two ★: declare and defend the grain (fan-out joins silently inflating every downstream aggregate — the category's most expensive quiet defect) and a schema change crossing a consumer boundary must clear a compatibility gate (the registry's compatibility mode, additive-with-default, version bump, deprecation window, named consumers — "nothing failed in CI" is not evidence when no consumer lives in this repo). The rest: data-test adequacy proportional to how this model can be wrong, unit tests for non-trivial transformation logic (data tests can't reach an unexercised CASE branch), SQL three-valued-logic traps (NOT IN with NULLs, a LEFT JOIN degraded by a WHERE predicate), incremental idempotency and dropped late-arriving rows, backfill/history consistency, type fidelity, at-least-once duplicates and event-time windows, fail-loud-not-empty, lineage and blast radius, and PII entering the analytics plane. G1 single-owner: #40 owns the transformation and the data contract, deferring the store's DDL/lock/backfill mechanics to #20, the service API contract to #13, external wire-format conformance to #37, PII adjudication to #27, code-test craft to #17, query cost to #15, and the fail-loud verdict to #2; detect-and-escalates (G8) warehouse governance (data ownership, retention mandates, cost policy) to a data owner. Dedicated router route; a checking-restraint ↔ #40 tension (how much data-test and contract ceremony a model needs); 12 evals covering both ★ checks, the three delegate/escalate boundaries, one adversarial scenario, and two precision guards; drift clean. Cross-model re-gate: deferred, same recurring gap as the recent lenses.

✅ Repo/cron arm shipped 2026-08-04 (taxonomy v0.11) as auditing-data-pipeline-health — new Cluster V category #41, sited immediately after #40. The deferred decision resolved toward its own lens rather than folding into an existing audit: the standing-condition questions (is a declared contract enforced anywhere, has coverage decayed across the model graph, has a deprecation window expired with live readers) share no checklist with any current repo audit, and the #29↔#39 pairing one cluster over is the exact structural precedent — an authoring-time lens plus a scheduled currency audit that asks only whether time has invalidated something already declared. Eleven heuristics, two ★: declared contract vs. the plane it describes (is anything actually testing the dataset against it — and if not, the finding is declared but unverified, a real defect distinct from confirmed drift) and test/expectation coverage walked across the model graph, ranked by downstream fan-out plus exposures (an untested model with 46 descendants and an untested leaf are different findings; a flat count hides that). The rest: freshness expectations absent/lapsed/decorative, expired deprecation windows with live readers, ungated registry subjects and soft-failed contract checks, repo-vs-registry divergence, orphaned vs. consumed-but-undeclared models, lineage the ref() graph cannot see, permanently-warning tests, unowned/stale contract ownership, PII inventory drift, and reporting the direction rather than the snapshot.

The lens's defining constraint is evidence discipline — and it is what most distinguishes this arm from the diff arm. A repo audit reads the repo, not the warehouse, so drift it cannot observe is reported as declared but unverified and never as confirmed; asserting observed drift from repo evidence alone is this lens's characteristic false positive, and its coverage statement (G19) must name the plane it could not reach. One eval scenario is dedicated to refusing exactly that under pressure. G1 single-owner: #41 owns the analytics plane's standing condition, deferring diff-time review of a change to #40, the operational store's declared-vs-live drift to #20, docs drift to #22, suppression/monitoring/codegen drift to #30, and churn hotspots to #21; PII inventory routes to #27, the fail-loud verdict to #2, and contract ownership detect-and-escalates (G8) to a data owner. The tenth repo-shaped audit — whole-repo-audit route, router description, generator prose, and the auditing-a-repository entrypoint all updated nine → ten. 12 evals; drift clean. Cross-model re-gate: deferred, same recurring gap.

G17 is now complete — both arms of the disposition shipped.

G18 — The two ISO/IEC 25010:2023 characteristics with no owner: Interoperability and Safety

Surfaced via the external completeness model (a new standing method — sweep an independent standard, not the map's own categories). Mapping the atlas onto all nine ISO 25010:2023 product-quality characteristics, every one has an owner except two:

• Interoperability / compatibility (the missing "-ility"): #13 reviews the contract we publish, #8 reviews idiom, but nothing reviews whether the code correctly speaks an external standard — HTTP caching/idempotency semantics, OAuth/OIDC, semver, RFC date/email/URI formats, Unicode normalization & encoding, cron syntax, OpenTelemetry semconv, standard file formats. Scattered today as factor-notes across #4/#8/#13/#26.
• Safety (new top-level characteristic in the 2023 revision; distinct from #14 security — harm-prevention vs. attacker-prevention): fail-safe defaults, safe-mode-on-error, operational guardrails on dangerous actions, hazard warnings, risk identification for harm-causing state. #2 owns fail-loud-vs-degrade and #28 owns overload degradation, but neither asks "does this fail toward harm or toward safe?"

Disposition (lean): interoperability → promote or consolidate the scattered factor-notes into one lens/factor; safety → add-factor to #2/#28 + a detect-and-escalate boundary, with full hazard analysis (ISO 26262 / IEC 61508 / DO-178C) out-of-scope. Confidence: med-high (interop) / medium (safety). Method note: re-run the external-model sweep on each major revision of an external quality standard — it caught a characteristic ISO itself only promoted in 2023.

✅ Interoperability arm shipped 2026-06-24 (Wave C, taxonomy v0.7) as reviewing-interoperability — new Cluster IV category #37 (research cluster-4-runtime.md#37), the first of the two unowned ISO/IEC 25010:2023 characteristics. shape: diff; consolidates the scattered "does the code correctly speak an external standard" factor-notes into one owner: HTTP semantics (safe/idempotent methods, status codes, conditional requests & caching — RFC 9110/9111), OAuth 2.0/OIDC flow correctness (exact redirect_uri, state/nonce, PKCE — RFC 9700), SemVer discipline + wire/format back-compat, RFC formats (date RFC 3339, URI RFC 3986, email, JSON, CSV), Unicode normalization & encoding (NFC, UTF-8, the YAML "Norway" class), cron/schedule dialects (POSIX vs. Quartz), OTel semantic conventions, and the ISO co-existence facet. Eight heuristics, two ★ (standard protocol semantics; RFC/format conformance). G1 single-owner: #37 owns conformance to an external/published standard and cross-links #4 (internal correctness), #8 (idiom), #13 (the contract we author), #26 (config validity), deferring those verdicts; the auth-flow security verdict routes to #14. Dedicated router route; 4 evals; drift clean. Cross-model re-gate passed 2026-06-24 (qwen2.5:7b floor + llama3.1:8b cross-confirm; RFC 3339 / OAuth-state / cron-dialect all caught, clean scenario "No findings" — see session-log).

✅ Safety arm shipped 2026-06-24 — the second ISO/IEC 25010:2023 characteristic (safety = harm-prevention, distinct from #14 attacker-prevention), as the dispositioned add-factor pass: a ★ "fail toward safe, not toward harm" on #2 hunting-silent-failures (fail-closed on auth/permission/quota checks; destructive/financial/physical actions default to no-op/abort; failed validation rejects) and a "degrade toward safe, not just toward available" factor on #28 reviewing-resilience-and-scalability (a degraded/fallback path must not drop a safety-critical check — no fail-open fraud/authz under load, no harmful stale data, no killing a guard). Each detect-and-routes the acceptable-risk threshold to a human owner; deep hazard analysis (ISO 26262 / IEC 61508 / DO-178C) out-of-scope. Two evals each + examples; regenerated (drift clean); no new category / no version bump. Cross-model re-gate clean on the documented qwen2.5-coder:7b floor (hunting-silent-failures 6/6, resilience 6/6); the new factors also caught on general qwen2.5:7b + llama3.1:8b, with two clean-code over-flags appearing only on the general models (the documented general-vs-coder substrate gap, which the coder floor gets right). G18 is now complete — both unowned ISO/IEC 25010:2023 characteristics closed.

G19 — Review-coverage transparency / known-unknowns

Surfaced via vantage rotation turned on the suite itself (the reviewer's own epistemics; the meta-analog of #30). The synthesizer (D12) emits a verdict but never states what the review did not examine — lenses skipped and why, areas it could not verify, claims it had no evidence for. A confident review silent on its own gaps manufactures false assurance, itself a defect of the review. Thin prior art as a named practice (nearest: audit "scope & limitations", model-card "known limitations"). Disposition (lean): fold into the synthesizer as a required "coverage & limitations" contract field — not a new category. Confidence: high (additive, low-risk). ✅ Shipped 2026-06-15 (Wave A): a synthesis step + a Coverage & limitations report block that names which lenses ran, which the router did not select, and what could not be verified from the diff alone — always present, even on a "No findings" report. Generator prose only; eval added.

G20 — The codebase/repo as a working environment for AI maintainers

Surfaced 2026-06-14 (owner question: do we cover code agents as code-owners and as operators?). A vantage rotation the round-3 pass under-exploited — the AI agent as a first-class reader/operator — splitting into two roles with very different coverage.

Code-owner / maintainer role — a genuine framing gap. Cluster II of the taxonomy is titled "Can humans understand it?"; the whole readability/clarity axis (#5–#8) was never rotated to "Can an agent understand, navigate, and safely modify this within a context budget?" Absent: LLM-centric readability; context-window economy of the reviewed code (self-containment, depth-first-sliceability — the concept exists in-repo only as the suite's own design tax, never as a reviewed property); discoverability/navigability for agents; RAG/retrieval-friendliness. Partial: agent-instruction files (AGENTS.md/CLAUDE.md) — drift covered (#22/#24), authoring designed-unbuilt (#30/D15/G11), but "does the repo provide good, scoped agent onboarding" (the agent analog of #22's README front-door) is thin.

Two reasons to promote: it is the mirror image of G14 (G14 = quality of AI-authored code; G20 = quality of code for AI readers — same axis, opposite direction), and it is the G11 pattern again (the project optimizes its own artifacts for agent-legibility via D7 but never made it a review behavior). Prior art: "AI-friendly codebases"; coding-agents-as-a-first-class project-structure concern (the "40% context rule," depth-first slices, self-contained modules). Disposition (lean): promote — a cluster-II rotation into an agent-legibility lens: a diff arm (is this change agent-legible/context-economical?) + a repo arm (agent-navigable tree; AGENTS.md/CLAUDE.md present/accurate/scoped; llms.txt-style index). Confidence: med-high. ✅ Shipped 2026-06-17 (Wave C, taxonomy v0.5) as reviewing-agent-legibility — new Cluster II category #35 (research cluster-2-readability.md#35), the mirror of #34 (quality of code for AI readers ↔ by them). Ships the diff arm (shape: diff): context economy / self-containment (the "40% rule", grounded in lost-in-the-middle), retrieval-friendly + AST-navigable structure, local self-explanation, scoped AGENTS.md/CLAUDE.md onboarding with do-not-touch guardrails, llms.txt index, and no agent-hostile patterns. Two ★ priority checks (context economy; agent-onboarding) surface as top-checks. Cross-links #5–#8/#21/#22/#24/#30; defers human readability to #5–#8, operator parity to #24, runtime tool-safety to #32. Dedicated router route added; 4 evals; drift clean. The repo arm (whole-repo agent-navigability audit) is a noted follow-up (per the #32/#33 incremental precedent); the operator role stays a G9-deepen of #24 + the unbuilt #30/#32, not a new category.

Operator role (agent as user of the product) — mostly mapped; do not over-promote. The restraint check passes: UI parity for agents is #24 agent-native parity (surfaced but G9-thin); SKILL.md/MCP authoring → #30/D15 and safety → #32 (both mapped, unbuilt); LLM-accessible UI affordance is oblique (#23 a11y + #24); product/docs discoverability for agents (llms.txt, an emerging standard — Anthropic requested it; Google A2A includes it) has no home yet. Disposition: no new category — a G9-class deepening (#24) + build the mapped-but-unbuilt #32/#30 lenses + two add-factors (llms.txt discoverability; LLM-accessible UI affordance, → #22/#23/#24). Full reasoning in research/taxonomy-gap-hunt-round-3.md.

G21 — Operational time-bombs & exhaustion classes (latent "correct-now, broken-later" defects)

Surfaced 2026-06-14 via a failure-grounded completeness model (an incident/outage corpus, complementing the attribute-grounded ISO-25010 sweep of G18) — full method in research/taxonomy-gap-hunt-round-3.md §Method 5. An attribute model can't see these because they're not quality attributes but recurring failure modes. Sweep result:

• Config change (~50% of severe outages) — covered by #26; the outage-frequency framing reinforces #26 surfacing (G9-deepen).
• Expired TLS certs / OAuth tokens / API keys; missing rotation/renewal path — absent (#14 owns hardcoded secrets, not expiry/rotation). The single most preventable major-outage class (Microsoft/Spotify/Google/Bank of England).
• Calendar/clock time-bombs (leap year/second, DST, epoch-2038, year rollover) — thin (#4 has timezone/UTC/monotonic, not these triggers).
• Retry storms / thundering herd / cache stampede; retry budgets — partial (backoff+jitter present; #28 backpressure).
• Resource exhaustion (disk-full, file-descriptor/socket, ephemeral-port, connection-pool) — partial (pool bounded; #4 leaks; #28 unbounded).

Cohesion: several share a temporal signature — correct at merge, detonates later by passage of time (expiry, calendar) or accumulation (quota/capacity creep); the #29 ADR-assumption-expiry and #30 suppression-expiry checks are the same shape applied narrowly. Disposition (lean): primarily add-factors — expiry/rotation → #14/#26; calendar/clock time-bombs → #4; coordinated-retry patterns + retry budget → #2/#28; exhaustion classes → #4/#28. Flag the cohesive option: a "latent / time-delayed defect" thread asking "will this be fine today and page someone in 90 days?" — a question no current lens asks. Confidence: high. ✅ Shipped 2026-06-15 (Wave B): add-factors with single G1 owners — credential/cert expiry & rotation → #14 sweeping-for-security; calendar/clock time-bombs (leap year/second, DST, epoch-2038, rollover) → #4 tracing-correctness-and-invariants; thundering herd / cache stampede + resource-exhaustion classes (disk/fd/socket/port/pool) → #28 reviewing-resilience-and-scalability. The cohesive "correct at merge, detonates later (by time or accumulation)" framing is threaded into each factor rather than spun into a new lens (restraint). Each factor carries an eval; #14/#28 surface as top-checks, #4 lives in the full checklist (broader top-check surfacing tracked under the G9 budget rebalance). Regenerated from research; drift clean.

G22 — Diff-isolation blindness: interaction & composition defects

Surfaced 2026-06-14 via the adversarial / inversion method (design the defect that most easily evades the suite; name the assumption that let it through) — research/taxonomy-gap-hunt-round-3.md §Method 6. The load-bearing assumption is the diff is the unit of review. The suite reviews a single diff (diff-lenses) or repo state (cron audits); neither reviews the composition of multiple changes across time and space:

• Semantic / logical merge conflicts — two independently-correct changes that break when combined; textually merge-clean, behaviorally broken — explicitly noted in the literature as hard to catch in code review/testing.
• Assumption invalidation across in-flight changes — change A correct against an assumption a parallel/recent change B silently breaks.
• Load-bearing deletions — a removal locally fine but breaking a relier outside the diff (diffs foreground additions; removals are under-scrutinized).

A unit/granularity gap — the change-set across time/space is an un-owned review unit, the analog of round 2's decision shape gap (a missing unit, not a missing topic). Relates to G7 (history-shaped skills) and #21 change-coupling, but neither owns cross-change interaction at review time. Disposition (lean): promote (scoped) — heavy detection is tool-territory (variability-aware execution, static/pointer analysis); the LLM-review slice is "trace the ripple of deletions and assumption-changes beyond the diff; flag interaction with concurrent/recent changes", escalating the rest (G8). Confidence: medium.

Round-3 cont. — scope re-audit: the exclusion pile (G23–G26)

Surfaced 2026-06-14 via a distinct method — auditing the exclusions/conflations themselves (the inverse of hunting inside scope): when something was fenced off or folded, was it on the right axis? Yields the detect-and-route principle (G23), candidate Cluster VII (G24), the exclusion re-audit (G25), and the defect-only-by-construction finding (G26). Full write-up in research/product-experience-value-cluster.md.

G23 — Detect-and-route: surfacing ≠ deciding (a scope-principle fix)

Surfaced 2026-06-14 (owner challenge to the recurring "product/UX is out of scope" boundary) via a new method — auditing the exclusions themselves. The "out of scope" label conflated two independent questions: (1) is it reviewable at review time? and (2) who has authority to decide it? Product/UX/value findings often answer no to (2) but yes to (1) — a confusing error message, a missing empty-state, a deceptive default are right there in the diff. The map already owns the resolution for this shape: G8 detect-and-escalate (the compliance lens surfaces legal exposure and routes the decision to a human, never adjudicating).

Generalize G8 into a map-wide primitive — detect-and-route. A holistic review surfaces a finding with evidence and routes the decision to the right stakeholder (route: product / design / legal / leadership / eng), never silently dropping it for "not our call." Add a decider/route axis to the synthesizer (D12) alongside severity. Only concerns with no artifact at review time (market sizing, pricing, org politics) stay out — and those re-enter as #29 once written into a decision record. Consistent with the project's own rationale (overview.md): a narrow scope "would push the most expensive failure modes out of scope" — and product/UX/value failures are often the most expensive of all. Disposition (lean): adopt (low-risk, additive; formalizes existing G8 + the D12 contract). Confidence: high. Full write-up: research/product-experience-value-cluster.md. ✅ Shipped 2026-06-15 (Wave A): a route: axis (eng | implementer | product | design | legal | leadership) on the synthesizer finding contract, with a detect-and-route principle (surface + route the decision, never silently drop or self-adjudicate a non-engineering call) and a dedicated Routed — non-defect decisions outside engineering report section. Valence (not route) governs the verdict: a finding that is both a defect and routed (a GPL dependency → valence: defect, route: legal) still sets the verdict in its severity section and carries the route tag for escalation. Generator prose only; regenerates cleanly; tests + evals updated.

G24 — Candidate Cluster VII: Product, Experience & Value

Surfaced 2026-06-14, enabled by G23. The six clusters are all about the code and its lifecycle; none is about the product as experienced and valued by its users — a topic-cluster-sized hole (not a shape or unit, a genuine topic axis). The only user-facing lens today is #23 (a11y mechanics) + #24 (agent-native reachability, not UX). Candidate lenses, each skip-when no user-facing surface and detect-and-route (G23):

• VII-A Usability & interaction quality — Nielsen's 10 heuristics (the canonical UX completeness model); net-new. promote, route: design/product.
• VII-B Experiential / perceived quality — empty/loading/error states, perceived performance, optimistic UI (≠ #15 measured perf). promote/add-factor.
• VII-C UX consistency / design-system conformance — off-token, bespoke-vs-system components (UI analog of #8). add-factor/lens.
• VII-D Content & UX writing — error-copy helpfulness, voice/tone, jargon. add-factor.
• VII-E Inclusion & equitable access — ISO 25010:2023 inclusivity, cognitive a11y, low-end/low-bandwidth, affordability. add-factor #23.
• VII-F Product value & outcome instrumentation — is the change tied to a measurable outcome / falsifiable hypothesis (outcome metrics ≠ #16 ops metrics; overlaps G12). promote, route: product.
• VII-G Trust, transparency & user-facing accountability — automated-decision explainability (GDPR Art. 22), data-use transparency, honest defaults (overlaps G16/#27). promote, route: product/legal.
• VII-H Conceptual integrity / product coherence — Brooks's "most important consideration in system design"; the product counterweight to sprawl (as #11/#15 are the code counterweights). promote (design-shaped).
• VII-I Internationalization of experience — cultural fit, locale-correct flows, full RTL (beyond #23 strings). add-factor #23.
• VII-J Feature value lifecycle — unused/dead features (product analog of #1 dead-code; cross #29 retire). add-factor (repo/cron).

Restraint guardrails: skip-when-no-user-surface; detect-and-route (never blocks the engineering merge on a taste call); a separate routed synthesizer section so product findings neither drown nor are drowned by correctness/security; and VII-H as the cluster's own counterweight. Disposition (lean): promote a Cluster VII, built incrementally (VII-A + VII-F highest-leverage; VII-E/VII-I → #23; VII-C → #8). Granularity (lenses vs factors) is the open call, as Q1 was for the original map. Confidence: med-high (the cluster is a real hole). Full enumeration + external models in research/product-experience-value-cluster.md.

✅ Cluster opened 2026-08-07 (taxonomy v0.12) — following this disposition's own increment, VII-A + VII-F and nothing else. Two categories, a new research file research/cluster-7-product.md, and the first new cluster since the original map (an append to an existing one would have been wrong: the axis is a topic the six do not span).

• #42 reviewing-usability-and-interaction (VII-A) — grounded in Nielsen's 10 heuristics and ISO 9241-110 controllability. State completeness (an async read produces loading, empty, and error states whether or not anyone designed them — enumerate from the code, not the mockup; this folds in VII-B's single most diff-visible check rather than promoting it), reversibility (undo, or a confirmation that names what is lost; and the slip case — a destructive control identical to its safe neighbour — checked separately from the mistake case the copy addresses), system-status feedback, error recovery that preserves the user's input (an error path that clears a filled form is a data-loss defect wearing a copy problem's clothes), controllability, and conformity with what the product already taught the user. 10 evals.
• #43 reviewing-outcome-instrumentation (VII-F) — the question no other lens asks: after this ships, how will anyone know whether it worked? A stated outcome rather than an output; instrumentation in the same diff (deferred tracking is the category's characteristic failure — the feature works, so the follow-up is deprioritised, and it is permanently unmeasured rather than measured later); a losing condition (with "we'll keep it regardless" a legitimate recorded answer — the defect is leaving the question unasked); guardrail metrics alongside the win condition (Kohavi); assignment and exposure code checked now for the properties that silently invalidate a result later; events matching the tracking plan; flags with an owner and an end condition; and Goodhart surfaced, never adjudicated. 10 evals.

What makes the cluster safe to open. Every member carries skip-when-no-user-facing-surface, and every member is detect-and-route — but the two lenses draw the line the same way, and that is the load-bearing part: an unhandled state, an unrecoverable destructive action, lost input, or a claimed benefit with no way to observe it is an ordinary defect with engineering severity; which pattern, which words, and which outcome to chase are surfaced with evidence and routed with no engineering verdict. A lens that blocks a merge on a taste call has miscategorised its own finding. Each also states its own failure mode up front — #42's is manufacturing findings from a backend diff, #43's is demanding a metric on every commit — and #43 names checking-restraint as its standing opposition, winning by default on anything beyond the stated outcome.

Closes G31's security ↔ usability pair, which had been explicitly waiting on this lens, plus three more cross-quality tensions now buildable: restraint ↔ usability (handle the states the code can reach; polish beyond that is gold-plating), restraint ↔ outcome-instrumentation (instrument the claimed outcome and nothing else), and ethical-design ↔ outcome-instrumentation (Goodhart's seam — a proxy win a reasonable user would not have chosen, surfaced by both and decided by neither).

✅ VII-H shipped 2026-08-07 (taxonomy v0.13) as #44 reviewing-conceptual-integrity — the cluster's counterweight, built third on this disposition's own argument that it is needed before the cluster grows rather than after. Brooks's conceptual integrity made reviewable: a new user-facing concept duplicating one that exists (two nouns for one idea), a second path to a job the product already does, one term with two meanings across UI copy/docs/API fields (Evans's ubiquitous language, held in check by his bounded context), a special case carved into a general rule, and the Nth option on a surface with no governing idea (the second-system effect, made countable). Gated on evidence — name the existing concept, where it lives, and the one-sentence rule a user would apply to choose between them, or report nothing; a new concept filling a real gap is not a defect for being new. The defect half is narrow: a rule the product already enforces that the change breaks without saying so is a broken promise with ordinary severity; everything else routes to product/design. Three tensions added (restraint ↔ conceptual-integrity, which mostly agree and answer different questions; conceptual-integrity ↔ usability, split by mechanics-versus-model; conceptual-integrity ↔ api-contract-safety). 10 evals. Shape note: the two pre-build predictions disagreed — G24 above said design-shaped, research/cluster-7-product.md's open threads said decision-shaped (i.e. decision-only). Shipped diff + design-capable — a counterweight has to run where accretion happens, and accretion happens one ordinary feature PR at a time.

Still unbuilt, still owner-gated: VII-C (design-system conformance — plausibly an #8 arm), VII-D (UX writing — plausibly a #42 factor), VII-G (transparency — needs a G1 boundary against #36/#27 first), VII-J (feature value lifecycle — repo/cron). VII-E and VII-I remain add-factors to #23. Whether Cluster VII ends at four lenses or ten is the same Q1 granularity question the original map faced, now with three data points instead of none.

G25 — Re-audit of the remaining exclusion pile (applying G23's two-axis test)

Surfaced 2026-06-14. G23's reviewable-vs-authority test must apply to every prior exclusion, not just product, or the reframe is special-pleading. Result: most prior out-of-scope calls were correctly drawn on the no-artifact axis; only two were mis-folded.

• Sustainability / green-software (was "a carbon label on #15") → upgrade: diff-visible (inefficient queries, egress, over-provisioning) with carbon/cost weight → a routed factor (route: eng/leadership), more than a label.
• FinOps / cloud cost (#15 residual, thin) → upgrade thin→surfaced: per-request cost/egress/over-provisioning are reviewable → first-class routed factor.
• Contributor DevEx as a system → boundary held (right axis): the org-level metric has no review-time artifact; diff-visible dev-friction is already #19/#21.
• Deep model-fairness auditing → split confirmed: diff-visible fairness smells → G16/detect-and-route (in); dataset/metric auditing → out (no artifact).
• Build-vs-buy TCO / procurement → boundary held (right axis): TCO has no diff artifact; the decision record is #29.

Net: the reframe sharpens the boundary rather than erasing it (restraint preserved). Only sustainability + FinOps were mis-folded (under-surfaced); the genuine no-artifact exclusions stand. Disposition (lean): upgrade green + FinOps to routed #15 factors; confirm the rest out. Confidence: high. Detail in research/product-experience-value-cluster.md. ✅ Shipped 2026-06-15 (Wave B): green and FinOps share one diff signal (wasted work per request), so unified into a single routed factor on reviewing-performance-and-efficiency (#15) — "cost & carbon efficiency (FinOps + green), route: eng/leadership" (chatty egress, unbounded fan-out, over-provisioning, polling-vs-events, over-scanning queries). Marked priority; diff-visible inefficiency in scope, org-level target out. Eval added.

G26 — Detect-and-suggest ≠ apply; defect ≠ improvement (the suite is defect-only by construction)

Surfaced 2026-06-14 (owner: aren't tidyings / dead-code / dep-bumps decidable at review time — reviewer suggests a nit, implementer applies/defers/ignores?). Yes. This is the same wrong-axis error as G23, a third time: "is it reviewable?" was collapsed with an orthogonal axis — here, when it is applied and whether it is a defect or an improvement.

The actual blocker is not the unbuilt fixing capability (Q8) — it is a guard. Every SKILL.md carries the identical generated reviewer-discipline line: "…do not suggest changes to code that is already correct. This guards against false positives on correct code." So the suite is defect-only by construction: improving-valence findings on already-correct code (reorder symbols for cohesion, remove dead code, bump a stale-but-working dep, extract an explaining variable) are prohibited in every lens, independent of any apply-automation. "Maintenance" actually decomposes into three orthogonal things, only one of which is genuinely unbuilt:

1. Improvement detection + suggestion — review-time, detect-and-route (route: implementer; decision: apply/defer/ignore). Currently suppressed by the guard, not by missing capability.
2. Improvement application (the agent edits) — the Q8 capability axis; partly served already by the broader simplify / code-review --fix skills.
3. Proactive scanning with no triggering diff — the cron/repo shape; partly built (the repo audits, finding-maintainability-hotspots).

The tension to honor. The guard is not wrong — it prevents nagging and false positives, and it is why the suite earned trust (clean PRs return "No findings"). The fix is not to delete it but to add a valence axis to the finding contract (alongside severity and G23's route): valence: defect | improvement. Defects keep the strict anti-false-positive bar; improvements are admissible only as opt-in, nit-severity, route: implementer, volume-bounded suggestions ("could tidy / could remove / could bump — apply, defer, or ignore"). Volume is already controllable: the synthesizer's severity floor and REVIEW.md convergence (which keeps suppressed nits visible for optional tidy-up) are the throttle, so improvement-valence findings need not bury a review.

The guard is also a legitimate team preference, not a universal (owner, 2026-06-14). Some teams will want defect-only; that is a valid stance, not a misconfiguration. So the resolution is two-layered: the valence axis is the mechanism; the policy — how much improvement-valence to surface — is a preference-tier dial in the Q13 team-preferences overlay (which is designed and pending review). Default stays strict / defect-only (preserves the earned trust); teams opt up into improvement nits. Floor-tier (defects) is never dialed down.

Plus a built-in anti-churn discipline that holds at every verbosity setting (owner, 2026-06-14). An improvement suggestion must clear a value + confidence bar — it must improve, not merely offer an equivalent alternative (no change-for-change's-sake) — and must converge: once a dimension is "as good as we can confidently make it," no further suggestion on it, never a lateral re-order to an equivalent state, never oscillation (suggest A→B one round, B→A the next). This is the same termination guarantee REVIEW.md convergence gives the review loop, applied to improvement-valence nits — without it, an improvement-capable reviewer never settles. It is a built-in floor on how improvements may be suggested, not a team knob (a team can turn verbosity up, but cannot configure the suite to churn). Disposition (lean): keep the guard as the strict default; expose improvement-valence as a Q13 preference-tier dial (mechanism = the valence axis); make the anti-churn / value-threshold / convergence discipline a non-configurable built-in. Largely resolves Q3 (review-vs-maintenance is mostly a valence toggle at review time, not a separate mode) and narrows Q8 to genuine auto-application. Confidence: high (grounded in the verbatim guard across all ~24 lenses). ✅ Shipped 2026-06-15 (Wave A): the valence: defect | improvement axis is on the synthesizer finding contract; every lens's Reviewer discipline guard now reads "defect-only by default, improvements opt-in" instead of an absolute prohibition; the anti-churn floor (genuine-improvement bar + convergence/no-oscillation) ships as a non-configurable built-in; the report gains an Improvements — opt-in, optional section. Default behavior is unchanged (strict/defect-only); the team-tunable verbosity dial still depends on the Q13 overlay (designed, unbuilt). Generator prose only; regenerated across all lenses; tests + evals updated.

Round-3 cont. — cross-discipline review-analog sweep (G27–G29)

Surfaced 2026-06-14 via a new method — import mature review practices from other assurance disciplines (financial audit, scientific peer review, manufacturing QA, clinical, aviation, civil-eng), the inverse of the ISO/Nielsen quality-model sweep. Full map + validations in research/cross-discipline-review-analogs.md. The sweep mostly confirmed the atlas (poka-yoke ≡ #9/#10; checklists ≡ the whole form; adversarial ≡ #14/#32) and yielded three sharp net-new disciplines.

G27 — Segregation of duties / dual-control (maker-checker, four-eyes) in authorization logic

From financial-audit internal controls. Reviewable in code: can the same principal both initiate and approve a high-consequence action (payment, refund, role/permission grant, deletion, deploy)? Are sensitive ops gated by dual-authorization / maker-checker (two distinct actors)? Distinct from #14, which owns authn/IDOR/least-privilege — SoD is the orthogonal control that no single actor completes a sensitive workflow alone, a business-logic authorization pattern, not an access bug. SOX §404-mandated; the canonical anti-fraud/anti-collusion control. Prior art: maker-checker; SoD for SOX. Disposition (lean): add-factor #14 (or a dedicated check), detect-and-route (the policy of which ops need dual-control is a business call). Confidence: high — recognized, reviewable, currently unowned. Shipped 2026-06-15 (Wave B): promoted as an add-factor on sweeping-for-security (#14) — heuristic + Key reference in cluster-4-runtime.md#14, regenerated into the skill (now a Top check), with examples and eval scenarios (5 incl. a positive dual-control case). Phrased detect-and-route in prose (surface to security/compliance; threshold is a business call) ahead of the G23 route-axis primitive. Cross-model re-gate passed on the documented 7–8B floor (qwen2.5-coder:7b, 5/5) after one tuning pass added the decision rule a role/permission gate is not dual-control; the 3B tier stays below the precision floor (over-flags clean code, confabulates the self-approval guard), consistent with the standing model-capability ceiling. The re-gate also exposed and fixed a harness bug — the Ollama path didn't pin num_ctx, so it silently truncated the skill context and produced meaningless (generic) reviews until corrected.

G28 — Claims-vs-evidence verification (generalized)

From scientific peer review. Every PR claim — "fixes X", "faster", "no behavior change", "closes #N" — should be checkable against evidence in the diff (a regression test for a fix, a benchmark for a speed claim, genuine non-functionality for a "pure refactor"). The atlas does this in exactly one place today — reviewing-performance-and-efficiency "demands a profile before accepting optimization claims" — and nowhere generalizes it. Overlaps #1 (code-vs-stated-intent, not claim-vs-evidence), G12, #17, without any owning the general discipline: an unsupported claim is itself a finding. Disposition (lean): a cross-cutting factor / synthesizer principle (generalize the perf lens's profile-demand; pairs with G12 + G19). Confidence: med-high. ✅ Shipped 2026-06-15 (Wave B): a claims-vs-evidence factor on #24 reviewing-pr-and-process-hygiene (its single owner — it reviews the PR's stated claims) — every PR claim ("fixes X"/"closes #N", "faster", "pure refactor / no behavior change") must be checkable against evidence in the diff (a failing-without-the-fix regression test, a benchmark, genuine behavior-preservation); an unsupported claim is itself a finding. Generalizes the perf lens's profile-demand. Kept as a per-lens factor rather than a synthesizer check (the synthesizer adds no checks of its own); carries an eval. Lives in the full checklist.

G29 — Root-cause vs symptom (band-aid detection)

From manufacturing 5-whys + clinical differential diagnosis. For bug fixes: does the change address the root cause or paper over a symptom (catch-and-ignore, special-case the one bad input, retry a flaky call, bump a timeout)? Existing lenses verify a fix is correct; none asks whether it is at the right level. hunting-silent-failures is adjacent (dislikes swallowing errors); band-aid detection generalizes to "is this masking the problem rather than resolving it?" Disposition (lean): add-factor to tracing-correctness-and-invariants / hunting-silent-failures + the bug-fix router route. Confidence: medium. ✅ Shipped 2026-06-15 (Wave B): single-owner add-factor on hunting-silent-failures (#2) — "root cause vs. band-aid": catch-and-ignore, special-case the one bad input, retry a flaky call, bump a timeout, drop a guard at the crash site → ask what produced the bad state (5-whys) and whether the fix is at the right level. Marked priority (surfaces as a top-check on bug-fix review); eval added.

Feeds-existing (not new gaps): materiality/sampling → Q14 (the depth axis's missing name); differential-diagnosis → G19 (enumerate alternative causes before concluding); safety-margin/headroom → #28/G21; four-eyes-on-irreversible-ops → #24; blameless M&M → Q17/G15.

Round-3 cont. — shape & synthesizer sweeps (G30–G31)

Surfaced 2026-06-14: re-running shape-axis extrapolation on security (where is security reviewed at design time?) and auditing the synthesizer's own apparatus (is its tension table complete?).

G30 — Threat modeling as a design/decision-time security discipline

sweeping-for-security (#14) is diff-shaped vulnerability detection — it pattern-matches existing code for injection, IDOR, secrets, crypto. #32 covers agentic action-safety. Neither does proactive, structured threat enumeration at design time, before code exists: STRIDE (Spoofing / Tampering / Repudiation / Information-disclosure / DoS / Elevation per component), data-flow-diagram + trust-boundary analysis, attack trees, and abuse/misuse cases. Threat modeling is explicitly design-time ("examines what could go wrong before implementation begins… unlike vulnerability scanning, which evaluates systems after they are built") and answers Shostack's four questions (what are we building / what can go wrong / what do we do about it / did we do a good enough job). The design: true flag lets #14 run on a design doc, but executing diff-heuristics over prose is not the generative enumeration discipline. Grep confirms absence — "trust boundary" appears only in the parse-don't-validate (input-validation) sense, never as a security method. Prior art: STRIDE (Kohnfelder & Garg, MS 1999); Shostack, Threat Modeling; the Threat Modeling Manifesto; pytm (threat-modeling-as-code, mechanization). Disposition (lean): promote a decision/design-shaped security lens (threat-model an RFC / design doc / new feature), or add a decision-arm to #14; detect-and-route the high-stakes slice to human security review (G8). The security analog of #28's design-time operability and a strong instance of the Q15 decision shape. Cross #14/#32/#28/#13. Confidence: med-high. ✅ Shipped 2026-06-24 as reviewing-threat-model (#38, shape: diff, design-capable) — see taxonomy.md's v0.8 entry. Repo-shaped retrospective counterpart shipped 2026-08-23: field report #191 found a whole-repo audit had no way to reach #38's discipline at all — #38 is diff/decision-shaped and never runs in repo-audit mode. New category #45 (Deployment-pipeline & trust-boundary security, taxonomy v0.14, shape: repo) applies the same STRIDE/trust-boundary reasoning retrospectively, on a schedule, to the deployment/execution wiring already committed — CI/CD jobs, cron/systemd/launchd units, git-sync-then-execute patterns — rather than generatively to a design doc. Built as a dedicated lens rather than conditionally routing #38/#14 into repo mode, since both lenses' checklists are tuned for a diff or a design doc, not a static arrangement already at rest.

G31 — The synthesizer's tension table is restraint-centric; cross-quality tensions go unmanaged

Auditing D12's own apparatus: the synthesizer.tensions: table is entirely restraint-centric — every entry is checking-restraint ↔ X (module-design / performance / test-quality / api-contract / resilience) plus one performance ↔ readability. Tensions where neither side is restraint have no default resolution and fall back to the generic "prefer safer and simpler." As the map grows these multiply: observability ↔ privacy (log detail vs PII — #16 vs #27), security ↔ usability (friction vs safety — #14 vs G24 VII-A), transparency ↔ security (explainability vs information-disclosure — G24 VII-G vs #14), performance ↔ accessibility, consistency ↔ evolvability (#8 vs #21). Not broken (the fallback handles it), but under-specified, and the new Cluster VII (G24) + G16 sharply increase cross-quality collisions. Disposition (lean): enrich the manifest synthesizer.tensions: table with the cross-quality pairs above (additive; regenerates like the router/synthesizer — no docs drift). Low-risk. Confidence: high (the table is demonstrably under-populated). ✅ Shipped 2026-06-15 (Wave A): added the three cross-quality pairs whose both lenses exist today — observability ↔ privacy (reviewing-observability-and-operability ↔ auditing-compliance-and-provenance), performance ↔ accessibility (reviewing-performance-and-efficiency ↔ reviewing-accessibility-and-i18n), and consistency ↔ evolvability (checking-idioms-and-consistency ↔ finding-maintainability-hotspots). security ↔ usability shipped 2026-08-07 with G24's #42 (sweeping-for-security ↔ reviewing-usability-and-interaction: friction defending a named threat stands, friction with no threat behind it is an unconsidered flow — and it is deliberately distinct from the existing security ↔ ethical-design pair, which covers friction someone benefits from), along with three further cross-quality pairs the same build made buildable: restraint ↔ usability, restraint ↔ outcome-instrumentation, and ethical-design ↔ outcome-instrumentation (Goodhart's seam). Three more shipped 2026-08-07 with G24's #44 (reviewing-conceptual-integrity), and one of them is a shape the table had not carried before — a pair that mostly agrees: restraint ↔ conceptual-integrity answers two different questions (build it at all, versus does the product still say one thing once it does), so the entry tells the synthesizer to report the finding once rather than staging a contest, and states that restraint never suppresses a coherence finding on a change it has no objection to. Plus conceptual-integrity ↔ usability (split by mechanics-versus-model) and conceptual-integrity ↔ api-contract-safety (an endpoint can pass every contract check and still be the second way to fetch the same resource; #13's is the blocking one when they collide). transparency ↔ security still waits on the unbuilt VII-G.

Round-3 cont. — the conflation audit, run deliberately (G32 + closure)

Now that "reviewability is orthogonal to X" is a named method (G23/G20/G26), this pass enumerates every axis X that "is this reviewable at review time?" could be wrongly collapsed with, and tests each. One net-new find; the rest test as already-handled — a closure signal that the framing seam is largely mined.

Axis X (reviewability ⊥ X)	Status
Authority (who decides)	G23 — product/UX detect-and-route
Reader identity (who/what reads/operates)	G20 — the agent vantage
Application-timing / valence (when applied; defect vs improvement)	G26 — the valence axis
Attribution (who/what introduced it; "is it in the diff")	G32 — new (below)
Tooling/automatability ("a tool does/doesn't do it")	handled — G5 (LLM-only factors) + Q19 (mechanize-with)
Subjectivity ("it's a matter of taste")	handled — Q13 preference-tier + nit severity
Composition unit ("not in one diff")	handled — G22 (diff-isolation)
Lifecycle phase ("design not code", "runtime not source")	handled — the shape axis (Q15 decision, G15 runtime)
Localizability ("no single line to anchor it")	handled — G24 VII-H (conceptual integrity) + the repo audits
Ownership ("third-party / generated, not ours")	handled — #18 deps, #30 codegen
Valence-positive ("affirm good code")	considered, declined (restraint — noise risk outweighs value)

G32 — Reviewability ⊥ attribution: pre-existing / adjacent defects suppressed by the diff-only filter

The diff-only convention conflates "what changed" (attribution) with "what's reviewable." A pre-existing defect visible in the context the reviewer is already reading — the touched file/function or immediately adjacent code — is reviewable and worth surfacing, even though this PR didn't introduce it. This is the Boy Scout rule / opportunistic improvement ("leave it better than you found it"); the consensus is that pre-existing issues in touched code are fair to flag, balanced against scope (Boy Scout rule; opportunistic refactoring). Today the suite reviews "the diff" and has no surfacing path for a latent bug it notices in touched code; the repo audits own whole-repo hunting, but not the opportunistic, in-context surface. Disposition (lean): detect-and-route — surface tagged "pre-existing — not introduced by this change," non-blocking, scoped to code the PR actually touches (not a repo-wide sweep — that's the audits' job), and governed by the anti-churn / scope discipline (G26) + Q13 verbosity (it is un-attributed improvement-valence, so opt-in, default-quiet — never expand the PR's scope, just inform the implementer's fix-now / file / ignore call). The fourth instance of the conflation pattern. Confidence: med-high. ✅ Shipped 2026-06-16 (Wave B close-out): the attribution axis lands as cross-cutting generator prose — the fourth conflation-pattern primitive, sibling to G23 (route) and G26 (valence), not a single-lens topic factor. Every lens's Reviewer discipline guard gains a clause permitting a defect noticed in touched code that the change did not introduce to be surfaced, tagged "pre-existing — not introduced by this change," opt-in/default-quiet, route: implementer, non-blocking, scoped to touched code, never expanding the PR's scope. The synthesizer finding contract gains an attribution: introduced | pre-existing field, an Attribution (Boy-Scout, scoped) surfacing principle, a verdict rule (a pre-existing defect is routed to the implementer without setting this PR's verdict — the diff did not cause it), and a dedicated opt-in "Pre-existing — noticed in touched code, not introduced here" report section. Generator prose only; built_from unchanged so drift stays clean; tests + a synthesizer eval added.

Closure. Run deliberately, the conflation audit returns one new gap (G32) and otherwise confirms the prior axes are covered — evidence the high-value framing seam (rounds 1–3's richest vein) is largely exhausted. Remaining yield is shifting from framing gaps to add-factors and validations; the bottleneck is moving from finding to deciding.

Synthesis — what to promote first (G12–G32)

The mining phase is consolidated into a ranked, dependency-sequenced, decision-ready view in research/gap-hunt-synthesis.md: each gap typed (mechanism / new-lens / add-factor / tooling / fold), scored value × cost × confidence, deduped against overlaps, and placed in four waves — A foundations (the G23 route + G26 valence primitives, G19/G31 synthesizer upgrades, Q19), B high-value add-factors (G27, G21, G25, G28, G29, G13, G32, G12-as-factor), C new lenses (G14, G16, G20, G30, G18), D bigger bets (G24 Cluster VII incremental, G17, G22 scoped, G15 runtime shape). Top-five and the G1 single-owner boundaries to settle are called out there. Decision-support only — every item stays owner-gated.

The meta-principle (why this keeps recurring). Three times now a real gap hid behind a conflation: reviewability is orthogonal to authority (G23), to the reader's identity (G20), and to application-timing/valence (G26). Standing rule: test "is X reviewable / surfaceable at review time?" independently of who decides X, who reads X, when X is applied, and whether X is a defect or an improvement. Each conflation predicts an under-reach; auditing for them is a generative gap-finding method in its own right (the "conflation audit").

G33 — Named-framework provenance: #17 converged on Beck's & Farley's test criteria without citing them (and had thin spots)

Surfaced 2026-06-28 (owner question: do our test-quality lenses already factor in Dave Farley's criteria and Kent Beck's "Test Desiderata"?). The same owner-question-driven "do we have an equivalent to canonical X?" check that found G11 (the skill-authoring guide) and G13 (Tidy First?) — not a framing-class hole (G10) and not a pure factor-leak (G9), but a provenance + partial-coverage gap: reviewing-test-quality (#17) had independently converged on most of both canonical frameworks while citing neither, and three of their properties were thin or absent.

The finding. Mapping the lens's checks against the two frameworks: Beck's behavioral + structure-insensitive = our behavior-vs-implementation axis; isolated / deterministic / fast / readable / predictive all covered. Under-surfaced: Beck's specific (a failure localizes its cause), writable (cheap to write), and Farley's atomic / necessary / granular. The richest genuinely-missing material was the named, checklist-actionable literature the lens never referenced: the Pragmatic Unit Testing mnemonic family (Right-BICEP = what to test; CORRECT = boundary enumeration), the test-smell catalogs (Meszaros xUnit Test Patterns; van Deursen et al. XP2001; tsDetect's 19 lintable smells — Assertion Roulette, Mystery Guest, Conditional Test Logic, Sensitive Equality, Sleepy Test), and Fowler's five-part test-double taxonomy to sharpen the over-mocking check.

Research note (adversarially verified, 2026-06-28 deep-research run). Farley's own enumeration is seven properties (Understandable, Maintainable, Repeatable, Atomic, Necessary, Granular, Fast), not the "eight" some third-party summaries cite — the 8th ("test-first") comes from a third-party plugin, not Farley. Beck's Test Desiderata is exactly twelve; a "2.0" (Dec 2025) evolves but doesn't contradict it, so the lens cites the stable 1.0 (no time-sensitive text).

Disposition: ✅ shipped 2026-06-28. Source-of-truth edits to cluster-5-verification.md #17, regenerated drift-clean. Sources added: Beck (Test Desiderata, 12), Farley (Properties of Good Tests, 7 — with the "not eight" correction), Hunt/Thomas/Langr (Right-BICEP / CORRECT / FIRST / A-TRIP), Meszaros + van Deursen + tsDetect (test smells), Fowler ("Mocks Aren't Stubs", test doubles). Heuristics: enriched three existing checks (edge/boundary → CORRECT dims; over-mocking → least-powerful-double; meaningful-coverage → tautological/Sensitive-Equality/necessary) and added four — single reason to fail / Assertion Roulette (★ promoted to Top checks; closes Beck's specific gap), self-contained / Mystery Guest, DAMP over DRY / no Conditional Test Logic (closes writable), and Right-BICEP inverse + cross-check + forced-errors. Two evals added. Restraint: folded where the lens already covered the axis rather than adding parallel checks; promoted only one new Top check.

Deferred follow-up (noted, not shipped). The deep-research run's items 6–7 — Software Engineering at Google (Winters et al.: DAMP-over-DRY, small/medium/large test sizes, the Beyoncé rule) and the expert-philosophy perspectives (Bach & Bolton testing vs checking, Crispin & Gregory Agile Testing Quadrants, Kaner, Henney on test-naming, Seemann on test trustworthiness) — were found but dropped before the verification phase (budget), so they are unverified and were not cited. A second verification pass is the natural next step before folding any of them in; SE@Google's DAMP-over-DRY framing is the highest-value candidate. Review-driven adjustment (2026-06-28): the shipped writable heuristic originally used the DAMP acronym, but DAMP's canonical attribution (SE@Google / Jay Fields) sits in this deferred bucket — so to avoid shipping a named term ahead of its citation, the acronym was dropped and the heuristic now stands on the cited Conditional Test Logic smell (Meszaros/tsDetect) + Beck writable; DAMP's named reintroduction rides with the SE@Google/Fields verification pass.

The class (why this recurs). G11, G13, and G33 are the same shape: an owner names a canonical framework/standard and asks "do we reference an equivalent?" The atlas, built from a first-principles taxonomy, tends to converge on canonical frameworks' substance via research mining while under-citing them by name — leaving both a provenance gap (no authority trail) and predictable thin spots (the framework's less-obvious properties). Standing method: periodically sweep the named canonical frameworks in each lens's domain and check name-level coverage, not just substance — the dual of the conflation audit (which hunts un-framed surfaces; this hunts un-cited canonical ones).

G34 — Architectural gap vs. commercial AI-native review products: no deterministic-tool grounding, no durable custom rules, no auto-fix, no whole-repo index

Surfaced 2026-07-05 (owner question: how does this compare to CodeRabbit, Copilot code review, and other AI PR-review competitors, especially around static-analysis-tool integration?). Distinct in kind from G1–G33: those are taxonomy/framing gaps (is some topic unowned or under-surfaced); this is an architecture gap surfaced by comparing the atlas's runtime design against competing products that already ship, not by sweeping the map. Full verified findings, per-product detail, and citations in research/competitor-landscape.md (a new product-landscape doc, sibling to prior-art.md but scoped to commercial AI-native review products rather than skills/linters).

The finding. CodeRabbit and GitHub Copilot code review are both hybrid pipelines: CodeRabbit orchestrates 40+ deterministic linters/SAST tools (Infer, ast-grep, PMD, Semgrep, ESLint, …) and uses the LLM to contextualize and cut false positives on top of tool output, not to invent findings from scratch; Copilot leans more on instruction-file configuration (copilot-instructions.md, path-scoped applyTo-glob instruction files) and a two-tier reasoning effort setting. Both ship capabilities the atlas doesn't have today: auto-applied fixes (CodeRabbit Autofix, Copilot one-click/batchable suggested changes), a persistent, admin-approved preference ledger learned from review conversation (CodeRabbit Learnings), and (Greptile, partial confidence) whole-codebase indexing to catch cross-file "seam" bugs a diff-only review can't see.

The atlas is pure LLM judgment even in categories where mature deterministic tools already exist — the opposite of the principle the map already states in G5 ("where mature linters cover a category, the skill's job is to orchestrate/triage tool output, not re-implement it") but has never acted on at runtime. This is a new instance of the G5 principle going unenacted, not a new principle.

Disposition (lean), ranked value ÷ cost (detail + full reasoning in the linked doc):

• Tier 1 (high value, low cost, no new infrastructure): (1) a deterministic-tool pre-pass — shell out to whatever linter/SAST the repo already has configured and feed its raw output to the LLM lens as evidence to confirm/contextualize/dismiss, rather than re-deriving the finding by judgment alone; (2) an ast-grep-style durable custom-rule mechanism — let a team encode a repo-specific AST anti-pattern once as a deterministic, zero-token check instead of relying on the LLM to notice it every review; (3) auto-applied fixes for a narrow, high-confidence, mechanically-safe slice of findings (distinct from and narrower than the broader Q8/G26 fixing-mode question, which stays gated) — grouped here on value/cost, not on "no new infrastructure": unlike (1)/(2), applying a fix needs branch write access plus safety rails (revert path, scope limits) the atlas doesn't have today.
  • (1) ✅ Shipped 2026-08-07 as grounding-review-in-tool-output — a third composition skill alongside the router and synthesizer, generated from a prepass: manifest block (built_from: [], so docs drift never flags it) and bundled into every collapsed entrypoint as reference/tool-evidence.md. It runs between lens selection and the lenses: discover what the repo already gates on (.pre-commit-config.yaml → CI workflows → package manifests → per-tool configs → task runners, ordered enforced-before-installed-before-documented), run those and only those, scoped to the change and under the repo's own config, route each hit to the owning lens via a nine-family table whose grounds: names are validated against the manifest, and dispose of every hit exactly once — confirm (report as a lens finding with the rule id as evidence), contextualize (real, but restate the severity), or dismiss (with a written reason). Six discipline rules carry the weight: never introduce an unadopted tool; a clean run clears nothing (absence of tool output is absence of evidence, so every selected lens still runs); reproduce every hit against the diff before reporting it (#24's claims-vs-evidence rule turned on the reviewer); running the repo's tools runs the repo's code — lint/build config is executable and attacker-controlled on a fork branch, so the pre-pass runs only in CI's isolation or not at all; bound the cost and call a timeout a coverage gap (G19); and keep judgment and measurement distinguishable in the finding. Its second output is the coverage line the synthesizer's Coverage & limitations section already reserves, whose third fact — which selected lenses had no deterministic coverage at all — is the one a reader cannot reconstruct. 10 evals; wired into both commands, the router, the entrypoints, the routing snippet, and the SessionStart hook. (2) and (3) remain unbuilt and owner-gated.
• Tier 2 (real value, moderate cost, config/prompt-engineering only): a persistent, admin-approved preference ledger as a concrete production reference for the still-unbuilt Q13 team-preferences overlay (team-preferences-overlay.md) — CodeRabbit Learnings validates the "capture from review-thread conversation + approval gate before it takes effect" design.
• Tier 3 (high differentiation, high infrastructure cost): whole-repo indexing/RAG (Greptile-style) — the clearest capability gap in kind, not degree, but requires a persistent embeddings/graph index and incremental re-indexing service that doesn't fit a stateless per-invocation Claude Code skill without a companion backend. This is one concrete way to close G22 (diff-isolation blindness) at real infrastructure cost.
• Not a gap: Copilot's two-tier reasoning effort (already served by the atlas's depth-mode axis, review-depth-modes.md); re-review-on-push (an orchestration/CI-wiring concern, already documented in runbooks/pr-review-automation.md); multi-platform support (distribution, not a review-capability question).

Coverage caveat (own it explicitly). This pass verified CodeRabbit and Copilot in depth and Greptile partially; it produced no verified claims for Qodo/CodiumAI, Sourcery, Graphite Diamond, Codacy, DeepSource, Amazon CodeGuru Reviewer, Snyk Code, or SonarQube's AI features, nor for practitioner-sentiment/complaint claims — those remain open follow-up research, not confirmed non-gaps. See the linked doc's Open threads.

Confidence: high (the architectural pattern — deterministic-tool grounding + LLM contextualization — is confirmed from primary vendor docs across two independently-verified products). Owner-gated, like every prior G entry: no manifest/skill change ships from this finding alone.

G35 — Error taxonomy / typed error hierarchies as a design concern, distinct from error-handling mechanics

Surfaced 2026-08-17 by a direct owner question ("do we cover error handling and error taxonomy?") during a routine orientation pass — not a research sweep, external-standard cross-check, or failure-corpus method like G14–G34. Flagged here at lower confidence than the rest of this file by the owner's own framing: no independent evidence yet that this is a recurring real-world failure class worth a dedicated check, as opposed to a plausible-sounding topic that happens to be absent. Treat the confidence rating below as provisional pending exactly the kind of scrutiny G33's "named-framework provenance" method would apply — this entry hasn't had that pass yet.

The finding. Two existing owners cover adjacent ground but neither owns the shape of the error type system itself:

• hunting-silent-failures (#2/#4) owns error-handling mechanics — is an error swallowed, does it fail loud vs. degrade intentionally, fail-closed on safety-critical paths, retries/backoff, transaction consistency on partial failure, handled at the right layer, bugs-vs-recoverable-errors.
• reviewing-api-contract-safety (#13) requires "typed and stable error contracts," but only for consumer-facing API surfaces (a caller across a process/version boundary needs a stable, documented error shape) — it says nothing about a codebase's internal exception/error-type design.

Neither asks whether the taxonomy is coherent: does a new error type join an existing hierarchy or invent a parallel one: is there a principled operational-vs-programmer-error split (Node.js's own convention, and the general "expected failure vs. bug" distinction hunting-silent-failures already gestures at via "are bugs treated differently from recoverable errors" without asking whether the type system enforces that split); is exception granularity sane (one blanket exception type across a whole module vs. one type per call site with no shared base); do errors carry a stable, programmatically-matchable discriminant (a code/kind field or a sum-type variant) for upstream callers to branch on, or only a human-readable message string; does a catch/except block narrow on the type discrimination the type system actually offers, or does it narrow by string-matching a message. This is closer in shape to checking-idioms-and-consistency's "does new code converge on the pattern the codebase already chose (Result type, error-as-value)" — but that lens only fires once a pattern is already established and diverged from; it doesn't ask whether the established pattern (or its absence) is itself sound.

Disposition: open, deliberately not promoted or built. The owner's own suggestion is to surface this opt-in rather than as a default-on factor, given the weaker grounding — consistent with how this file already treats low-confidence/speculative items (G13's Tidy First? economics is "disposition open"; G21's round-3 entries are explicitly "provisional, owner-gated"). Unlike those, though, there is no existing opt-in mechanism at the factor level to hang this on — the closest built analogs are lens-granularity, not factor-granularity: the Q13 team-preferences overlay's tier: floor | preference (team-preferences-overlay.md) turns a whole lens on/off-by-default per repo, and G6's "opt-in idiom packs" is itself unbuilt. Open sub-questions, none resolved here:

• Is this a real gap or a plausible-sounding non-issue? Needs the same kind of grounding G33 gives named frameworks (is there a canonical reference — e.g. Node.js's operational/programmer-error split, Joyent's old error-handling guide, a language's own idiomatic error-type convention — worth citing, or does this dissolve into "just" checking-idioms-and-consistency once actually researched?).
• If real, does it become an add-factor on an existing owner (most likely hunting-silent-failures, alongside its existing bugs-vs-recoverable-errors line) rather than a new lens — matching G1's single-owner principle and this file's general bias toward folding into existing categories over minting new ones?
• What would factor-level opt-in actually mean mechanically — a per-check flag in the manifest schema (nothing like this exists today; eval_min and tier are both whole-lens), or just default-quiet valence/severity the way G32's pre-existing-defect surfacing is opt-in/default-quiet by convention rather than by a schema field?

No build follow-up. This is a candidate for a future research pass (grounding it against real sources, per the standing authoring rule against ungrounded behavioral/topic claims) before any promotion decision, not a decision itself.

G36 — Harness/orchestration gap vs. metareview: no terminal-escalation signal, no evidence-receipt input contract, no mechanized post-merge calibration loop

Surfaced 2026-08-24 (owner question: what can we learn from dsifry/metareview?). Distinct in kind from G34: G34 compared this suite's runtime architecture against commercial SaaS reviewers and found a content/grounding gap (mostly closed by grounding-review-in-tool-output). This gap comes from comparing against an open-source, unhosted, agent-native review harness with a persistent CLI, a five-gate lifecycle state machine, and its own local learning store — the closest thing found so far to a second implementation of "agent review harness" with real, inspectable dogfooded output. Full verified findings, per-mechanism detail, and primary-source citations in research/metareview-analysis.md (a new doc, sibling to prior-art.md/competitor-landscape.md but scoped to an agent-native review harness rather than skills/linters or a SaaS product).

The finding. metareview's runtime is built as a chain of five typed gates (artifact → task-done → epic-ready → pr-ready → learn --post-merge), each returning one of four verdicts — PASS / PASS_ADVISORY / NEEDS_REVISION / ESCALATED (stop autonomous retries, a human must redesign the target) — with findings carrying stable IDs a later run can reconcile against rather than re-litigate. Validation claims are backed by hash-verified JSON evidence receipts (command, cwd, exitCode, timestamps, stdoutSha256/stderrSha256) rather than prose, importable from local test runs or GitHub check results into one uniform format. After a PR merges, learn --post-merge forces every candidate lesson into an accepted or discarded bucket — accepted entries carry a stated confidence and provenance links back to the exact finding ID and the exact run that fixed it; discarded entries carry a typed rejection reason rather than a silent drop — and the accepted store feeds directly into the next automated run of the same CLI.

This suite has no equivalent of any of the three: findings ship with severity/tier but no terminal "stop iterating, escalate to a human" signal; there is no format for a caller to hand in externally-validated evidence in a way a later step could verify without re-running or re-embedding it; and the "what should change reviewer behavior next time" capture this repo already does (session-log entries, the standing authoring rules' own incident write-ups in research/README.md) is manual, per-incident, and has no forced accept/discard split, no typed discard reason, and no automatic feed-forward into a later review — because, unlike metareview, this suite runs as stateless per-invocation Claude Code skills with no persistent state between invocations to feed a calibration loop back into.

Disposition (lean), ranked value ÷ cost (full reasoning in the linked doc):

• Tier 1 (high value, low cost, fits a stateless skill): (1) a named terminal-escalation signal in the synthesizer's verdict contract — evaluable from the current round's findings (e.g., a CRITICAL architecture-level finding, or the same root cause recurring across rounds the caller already tracked) without needing new persistent state; check whether this belongs in synthesizing-review-findings or one layer up in runbooks/pr-review-automation.md. (2) Naming the specific deterministic sub-case a prepass: tool hit already owns inside the lens prompt itself (metareview's rubric text tells the LLM lens "the eval( gate covers bare eval( — don't re-flag it, flag SQL string interpolation instead"), not only at the synthesizer's dedup step — check whether reference/tool-evidence.md already does this per-lens or only at synthesis time.
• Tier 2 (real value, needs state this suite doesn't keep today): an evidence-receipt input format for a caller handing in external validation (a CI pipeline's test run) as first-class review input — an input-contract question for runbooks/pr-review-automation.md, not a lens-content change; and a mechanized post-merge calibration gate, whose value is contingent on a concrete answer to "where does an accepted learning get read on the next review" — plausibly a "reviewer calibration" tier on the still-unbuilt Q13 team-preferences overlay (team-preferences-overlay.md) rather than a new mechanism, since a calibration store with no read path is dead weight.
• Tier 3 (architecturally out of scope as designed): the gate lifecycle's mechanism itself (a persistent CLI, .metareview/ state, --previous-run chaining) — adopting the earlier-stage coverage (reviewing a spec/plan before code exists) is already a scope question this repo's shape/artifact routing and reviewing-decision-lifecycle partially own; adopting metareview's state-machine mechanism would mean building genuinely new infrastructure, not a skill change.

Not a gap. metareview's adversarial multi-lens panel and its unusually deep architecture/data-modeling rubric (schema invariants, TOCTOU, money-as-float, "be most suspicious where the code looks most idiomatic") read as convergent validation of this suite's own cluster-3-structure.md / reviewing-ai-authored-code coverage, not new coverage to add.

Coverage caveat. This pass read metareview's own repository directly (primary source, not rendered-page summaries) but did not clone or verify metaswarm, the sibling orchestrator metareview's docs describe as its intended lifecycle-owning companion and the stated source of its security rubric and golden-eval process — claims about metaswarm in the linked doc are metareview's own stated description, not independently confirmed. See the linked doc's Open threads.

Confidence: medium-high on the mechanism descriptions (primary-source read of metareview's own checkout, including real dogfooded review/learning output, not documentation claims alone); medium on the disposition tiers, which are this pass's own value/cost judgment rather than an external benchmark. Owner-gated, like every prior G entry: no manifest/skill change ships from this finding alone.

G37 — "Make illegal states unrepresentable" / "parse, don't validate" was siloed to the type substrate, not applied as the cross-substrate principle it is

Surfaced 2026-08-25, following on from the metareview read (G36) and a direct owner question about lens-level improvements derivable from it. Same shape as G33 (named-framework provenance / under-application): the suite had the canonical principle correctly sourced in exactly one place and applied unnamed — or not at all — everywhere else the same move belongs. Not a new principle; a distribution failure of one the map already held.

The finding. reviewing-module-design (#10) owns "make illegal states unrepresentable" (Minsky) and "parse, don't validate" (King), correctly cited in its reference/sources.md. But the whole category was phrased in type-system vocabulary — tagged unions, smart constructors, exhaustive enums — and its Minsky note actively asserted "the type system is the enforcement mechanism, not runtime checks," which contradicts the principle's substrate-independence (a DB CHECK is a runtime check that still makes the state unconstructible). The same move appeared, but unnamed and uncited, at other boundaries: config validation-at-startup (#26), UI state via a discriminated union (#42, its one fully-worked instance, cross-referencing #10 already), and was absent at the wire boundary (#13 — no parse-inbound-once / discriminated-response-shape check) and the IaC input boundary (#31 — no variable validation block / CRD admission-schema check). The persistence substrate was gestured at by a single weak #10 line ("do the types and the persistence schema agree?") with none of the DB-native mechanisms spelled out — the same DB-schema semantic gap noticed in metareview's own deep Architecture rubric (G36's linked doc).

Disposition: ✅ shipped 2026-08-25. #10 reframed as the canonical cross-substrate home: a priority-marked (★, Top-checks) general-principle heuristic stating the move and mapping each substrate to its enforcement mechanism with cross-refs (#26/#13/#42/#31/#20/#40), the Minsky note corrected to state substrate-independence, and two persistence-substrate bullets folding in the DB mechanisms (a CHECK forbidding a contradictory combination; a real FK vs. a polymorphic (entity_type, entity_id) pair; a status column split into orthogonal fields; scoped UNIQUE matching the real invariant; a partial unique index surviving soft-delete; an exclusion constraint for effective-dated overlap) — which also closes the DB-schema semantic gap from G36. Substrate instances added at the two boundaries that lacked them: #13 (parse inbound payloads into a validated shape once at the edge; make an impossible response shape — error and data both populated — unrepresentable) and #31 (constrain a module/CRD's own inputs via a Terraform validation block or a CRD openAPIV3Schema/CEL admission check, distinct from plan-time policy-as-code). #26's startup-validation bullet reframed from "validated" to "parsed into a typed object once at boot" with a #10 cross-ref. #42 was already substantively covered (its ★ state-completeness heuristic and tooling note already carry the move and cite #10) and received only an explicit in-heuristic cross #10 pointer — not a new check. Generator prose only (built_from unchanged, so docs drift stays clean); regenerated drift-clean; 435 tests pass. G1 respected: #10 owns the modeling decision, #20 the migration mechanics of adding a constraint, #40 the analytics-plane version — each cross-referenced, none duplicated.

The class (why this recurs). G33 and G37 are the same method: sweep a canonical principle across every lens whose substrate it touches, not just the one where it was first cited, and check name-level + mechanism-level coverage per substrate rather than assuming the idea propagated. The dual of the conflation audit — that one hunts un-framed surfaces; this hunts a correctly-framed principle that never travelled. Owner-gated: the edits are generator-source prose, reviewable in the PR.