tech-debt-radar: sweep against the current Neo pattern canon

Context

Operator report (2026-07-23): .agents/skills/tech-debt-radar/references/tech-debt-radar-guide.md reads as outdated even though its last touch was ~2 months ago. V-B-A against the file confirms and sharpens this: the substantive content dates to the 2026-04/05 era (only compaction/path-hygiene touches since — a37b78988b, 2026-05-17), and parts of it are now canon-inverted, not merely stale. A tech-debt radar's entire value is its calibration against what the repo currently considers debt versus sanctioned design — placement ("what belongs where"), SSOT discipline, elegance/KISS, common patterns and anti-patterns. An inverted radar flags sanctioned shapes as debt and blesses real debt.

Second operator directive (same day) sharpened the target: the radar must also find structural architecture debt in ai/ itself — module shapes, folder taxonomy, file-size discipline, and concept↔code-home coherence — because that is where the highest-value ambient debt currently sits (see Problem 6).

The Problem

Concretely falsified items in the current guide:

1. §1 model tiering names "Gemini 3.1 Pro / Claude Opus 4.6" — two model generations stale; hard-pinned rosters decay by construction.
2. §2 pre-flight reads ONLY learn/benefits/ArchitectureOverview.md — it predates the decision-record system as pattern canon: no learn/agentos/decisions/ (ADR 0019's antipattern catalog IS the SSOT debt-list for ai/ config), no npm run ai:structure-map (the mechanical current-tree measurement reviews already mandate — where things ARE and how large; observation, not intended-placement authority), no AGENTS_ATLAS anchors, no structural-pre-flight.
3. §3.C example anti-patterns are inverted against today's canon: the guide hunts for "&& logic that should be optional chaining ?." — while ADR 0019 B3 classifies defensive ?. on config reads as the anti-pattern (let the SSOT fail loud); and it flags "deeply nested daemon configs instead of top-level paths" as legacy debt — while the reactive-Provider-SSOT redesign made the hierarchical tree the sanctioned shape.
4. §4 remediation instructs labeling tickets refactor(ai) (a commit-type scope, not a label — the label is refactoring), and frames an ad-hoc "Ticket Intake Bypass" that predates the mandatory ticket-create skill — so the radar's remediation path currently skips duplicate sweeps and the six-stage challenge chain entirely.
5. Missing sweep dimensions that now define the quality bar: core.Base as the standard, the apps/** data-path/style gate (Store-of-Models, SCSS-only, class components), the source-text-guard taxonomy (#15345 class), evidence-honesty classes, Progressive-Disclosure skill-shape debt, and the review-bar heuristics (right-thing / KISS / SSOT / ROI, subtractive-over-additive).
6. Missing entirely: the Brain-structural debt dimension — the class the radar would need to find to be "really valuable" (operator framing), and the one with hard evidence today:
   • Scale inversion: ai/ now carries 615 .mjs modules / ~188k LOC vs the Body's 475 / ~131k, with none of the Body's structural discipline.
   • File-size outliers beyond the Body's ceiling: ai/services/memory-core/MailboxService.mjs (3,000 lines), ai/daemons/wake/daemon.mjs (2,672 — an entire daemon as one file), ai/services/graph/providerReadinessHelper.mjs (2,506), vs src/component/Base.mjs (1,836) as the Body's densest, JSDoc-exemplary file.
   • Inconsistent daemon taxonomy: orchestrator/ is properly factored (control-plane/, scheduling/, services/) while wake/ is a monolith and embed/message/kb-* are ad-hoc flat — no shared module shape.
   • Concept↔code-home incoherence (operator-supplied specimen, 2026-07-23): the Dream Pipeline is a first-class concept with its own guide (learn/agentos/DreamPipeline.md) and a named Brain pillar — yet find ai -type d -iname '*dream*' returns nothing; the implementation is smeared across 25+ files in five technical-layer buckets (daemons/orchestrator/scheduling/dream.mjs, daemons/orchestrator/services/DreamService.mjs, ai/graph/, ai/services/graph/GoldenPathSynthesizer.mjs, the MC server surface, assorted ai/scripts/*). A documented concept with no legible domain home is exactly the technical-layer-first failure D#14302 names.

The Architectural Reality

• The root cause of the guide's staleness is structural, not editorial: it copied a point-in-time canon into skill substrate. Copies of a living canon decay by construction — the 2-month staleness is the expected outcome, and a rewrite that copies today's canon re-arms the same failure for two months from now.
• The canon has living homes: learn/agentos/decisions/ (graph-queryable ADRs), AGENTS.md/AGENTS_ATLAS.md (turn-loaded values + expansions), the pr-review guide's anti-pattern tables, and the apps/** gate in AGENTS.md §edge_case_triggers — plus ai:structure-map as the mechanical current-tree measurement (observation feeding the canon, not itself placement authority; per the PR #15777 review, authority/observation/hypothesis stay distinct classes). The radar's genuine, unduplicated substance is its sweep method (multi-vector: Knowledge Base + Memory Core mining + codebase vertical slicing) — that part remains sound.
• For the Brain-structural dimension (Problem 6) the prescriptive canon does not fully exist yet — by design. #14304 ("Agent OS Architecture Quality") is a deliberately deferred goal-anchor: its own body forbids implementation authority until a version-bound intended-architecture SSOT exists (its Lane-0 gate), reconciled with #13846, plus a coupling V-B-A matrix and migration tooling. D#14302 ("Restructure ai/ to domain-first", open, OQ_RESOLUTION_PENDING) and D#14305 ("Architecture immune system — keep ai/ elegant as it evolves") are the ideation surface for that canon. Two-layer rule for the radar: it MAY measure and report this debt class today from mechanical + documentary evidence (LOC outliers vs the Body baseline, daemon-shape inconsistency, concept-guide-without-code-home) — and a canon-hole is itself a reportable finding — but it MUST NOT prescribe target module shapes or file moves pre-SSOT; findings in this class route to the D#14302/#14304 canon lane, not to unilateral restructure tickets. This keeps radar output compatible with #14304's deferred-gates discipline.
• Skill-shape authority: ADR 0008 (SKILL.md anatomy, Map/Atlas split) via /create-skill; load-effect authority: ADR 0007 + /turn-memory-pre-flight — this is skill-loaded substrate.

The Fix

1. Rewrite §2 pre-flight as a canon-derivation step: at sweep time the radar loads its debt taxonomy FROM the living authorities — the learn/agentos/decisions/ index (at minimum ADR 0019's catalog for ai/-config debt and ADR 0008 for skill-shape debt), npm run --silent ai:structure-map -- --files --loc for current-tree size/placement evidence (observation, never intended-placement authority), and the pr-review anti-pattern tables — instead of restating any of them.
2. Add the Brain-structural sweep dimension with its evidence recipe and the two-layer rule: (a) mechanical probes — structure-map LOC outliers benchmarked against the Body's ceiling, folder-shape consistency across ai/daemons/*, concept-guide↔code-home coherence (every learn/agentos/*.md concept guide should map to a legible code home; the Dream Pipeline specimen is the calibration example); (b) routing — findings here cite #14304/D#14302 as the owning canon lane and never self-authorize restructuring pre-SSOT.
3. Remove the two canon-inverted §3.C examples; replace with pointers to the catalogs they should have come from. Preserve §3's vector methodology.
4. Route §4 remediation through /ticket-create (duplicate sweeps + Fat Ticket + live label rules: ai + one primary + refactoring as the secondary); drop the "intake bypass" framing.
5. Refresh §1 to roster-neutral capability language — no model-name pinning (same decay class as copied canon).
6. Implementer gates: /create-skill (ADR 0008 shape) + /turn-memory-pre-flight (load-runtime effect) + the ADR 0007 read before mutating the skill-loaded payload.
7. Optional: one freshness line in the guide naming its revalidation trigger (pattern-canon ADR graduations invalidate the §2 pointer list).

Acceptance Criteria

• The guide derives its debt taxonomy from named living authorities at sweep time; no copied pattern/anti-pattern lists remain in the skill.
• The Brain-structural sweep dimension exists with its mechanical evidence recipe (LOC-vs-Body baseline, daemon folder-shape consistency, concept-guide↔code-home coherence) AND the two-layer rule: measure-and-report now, no prescriptive shape claims pre-SSOT, findings route to the #14304/D#14302 canon lane.
• Both canon-inverted §3.C examples are gone; the multi-vector sweep method is preserved.
• Remediation routes through /ticket-create; label guidance matches the live label taxonomy.
• No model-name pinning remains anywhere in the skill.
• Net loaded bytes of SKILL.md + guide ≤ current (786 B router + 3,585 B guide) OR the delta carries explicit decay-mitigation rationale per the Substrate Accretion Defense (the new dimension is pointer-shaped, so the budget should hold).
• /create-skill and /turn-memory-pre-flight disciplines applied and documented in the implementing PR body.

Out of Scope

• Rewriting or extending the canon itself (ADRs, review guide, AGENTS.md) — this ticket re-points the radar at it, nothing more.
• Authoring the intended-architecture SSOT or restructuring ai/ (owned by the #14304 goal-anchor's deferred gates and the D#14302/D#14305 ideation lane).
• New tools or daemons; automated freshness enforcement (a future friction→gold candidate if manual revalidation proves insufficient).
• Retiring the skill — its sweep method is sound and unduplicated.

Avoided Traps

• Do NOT paste the ADR 0019 catalog (or any canon) into the guide — copied canon is the root cause being fixed, and it would double-load bytes for agents that already read the ADR through its own gate.
• Do NOT let the new structural dimension become implementation authority for file moves — #14304's body explicitly withholds that authority until its Lane-0 SSOT gate; the radar reports, the canon lane decides.
• Do NOT bloat the SKILL.md router with the taxonomy (Map/Atlas split per ADR 0008).
• Do NOT pin model names again.

Related

• ADR 0008 (skill anatomy) · ADR 0007 (compaction taxonomy) · ADR 0019 (the ai/-config debt catalog the radar should point at) · #11422 (router-hardening lineage) · #15345 (source-text-guard taxonomy — a debt class born after this guide was written).
• Brain-structural dimension anchors: #14304 (deferred goal-anchor — Brain domain-mapping + Body-idiom integrity; its Lane-0 SSOT gate is the canon dependency) · D#14302 (Restructure ai/ to domain-first) · D#14305 (Architecture immune system — keep ai/ elegant as it evolves) · #13846 (conceptual Body/Brain/Neural-Link authority) · #14714 (Body-idiom integrity strand) · learn/agentos/DreamPipeline.md (the concept↔code-home calibration specimen).

Decision Record impact: aligned-with ADR 0007 / ADR 0008; nothing amended. The structural dimension defers to #14304's future Decision Record rather than pre-empting it.

Release classification: not release-blocking (skill-substrate refresh; boardless).

Live latest-open sweep: checked latest 20 open issues at 2026-07-23T20:17:46Z; no equivalent found. A2A claim sweep (all-status, last 15): no overlapping [lane-claim]/[lane-intent] — recent claims (#15768→PR #15769, #15760, #15763) are disjoint. (Body updated same-day by the ticket author with the Brain-structural dimension after a second operator directive; no scope collision introduced — D#14302/#14304 own the canon lane, this ticket owns only the radar.)

Origin Session ID: 9af3c9a5-efc2-4716-bb5c-19289e22ddcc

Retrieval Hint: tech-debt-radar canon-inverted reference-derived taxonomy Brain structural debt DreamPipeline no domain home