<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">CARD: scaffold-f-structured-diagnostics — Structured, Requirement-Citing Diagnostics (TypeScript)</title>
  <status stage="spec" state="done"/>
  <p p="1"><fact id="status-line" status="impl/done">**Discipline v0.2 · BETA · T2 · TypeScript**</fact></p>
  <section id="band-one-identity" title="Band 1 — Identity &amp; Recognition">
    <p p="2"><fact id="CLASSIFICATION" status="impl/done">Classification: layer=E (verification) + C (meta); mechanism=scaffold F.</fact></p>
    <p p="3"><fact id="INTENT" status="impl/done">Intent: Engineer linter/checker output as agent input — stable, structured, citing the violated requirement and the fix surface — because error text is the highest-leverage prompt in the loop.</fact></p>
    <p p="4"><fact id="ALSO-KNOWN-AS" status="spec/done">Also Known As: actionable diagnostics; SARIF output; fix-it hints; structured errors; machine-readable lint; ESLint `messageId`.</fact></p>
    <p p="5"><fact id="APPLICABILITY-RECOGNITION" status="impl/done">Applicability / Recognition: Apply when — a custom `@typescript-eslint` rule (or a thrown domain error) emits free text; an error states what failed but not which REQ or where to fix; tool output is unstable across runs. *Detector seed:* a custom eslint/check message or a domain error without a `spec://` REQ URI and a fix-surface hint → recognition fires (tool output is the agent's percept, R3-011). Note: `tsc`'s own diagnostics (TS2322 etc.) are already coded — wrap them with REQ context, do not replace them.</fact></p>
  </section>
  <section id="band-two-justification" title="Band 2 — Justification &amp; Tradeoffs">
    <p p="6"><fact id="MOTIVATION" status="spec/done">Motivation: A weak agent sees `Type 'string' is not assignable to type 'never'` from a `satisfies never` exhaustiveness check — true but opaque. With the custom rule emitting `violates REQ spec://errors/r6: error union not exhaustively handled; fix surface: add a case for variant 'Timeout' before assertNever`, the agent acts directly. The strong author's "what to do when this fails" is materialized in the message.</fact></p>
    <p p="7"><fact id="STRUCTURE-AND-PARTICIPANTS" status="impl/done">Structure &amp; Participants: *Diagnostic* (an eslint report with a stable `messageId`) · *REQ citation* (`spec://` URI) · *Fix-surface hint* (where/what) · *Stable format* (SARIF / fixed grammar).</fact></p>
    <p p="8"><fact id="COLLABORATIONS" status="impl/done">Collaborations: Carries failures from Classes C/D/E and the §8 bans; feeds the agent loop's next prompt; in raids, structured diagnostics let the orchestrator triage misfires.</fact></p>
    <p p="9"><fact id="GOALS-AND-NON-GOALS" status="impl/done">Goals / Non-Goals: *Goals:* every custom check is agent-actionable. *Non-Goals:* NOT rewriting `tsc`'s own diagnostics (already good — wrap them); does NOT replace the contract that defines correctness.</fact></p>
    <p p="10"><fact id="CONSEQUENCES" status="spec/done">Consequences: (+) iterations-to-green drop, more for weaker models; (+) diagnostics double as a navigable requirement map. (−) message authoring cost; (−) verbosity vs token budget — keep a compact grammar.</fact></p>
    <p p="11"><fact id="ALTERNATIVES" status="spec/done">Alternatives: free-text errors (wasted conditioning); silent failure (worst). Neither acceptable for an agent loop.</fact></p>
    <p p="12"><fact id="RISKS-AND-ASSUMPTIONS" status="spec/done">Risks &amp; Assumptions: assumes a stable REQ namespace exists (it does — specmap, guide §9). *Sunset:* none material.</fact></p>
    <p p="13"><fact id="EVIDENCE-AND-TRANSFER-STRENGTH" status="spec/done">Evidence &amp; Transfer-strength: R3-011 (tool output is highest-leverage prompt, theory), R2C-004 (agent conditions on tool text, benchmark). Class: benchmark + theory. Tag: **[E-mid]**.</fact></p>
  </section>
  <section id="band-three-operation" title="Band 3 — Operation">
    <fence lang="card-ops" p="14">trigger: WHEN a custom eslint/check message or a domain error lacks a spec:// REQ URI + fix-surface hint THEN apply
mode: inline
routine:
  1. Add the violated REQ's spec:// URI to the message.
  2. Add a one-line fix surface: where to change and what.
  3. Emit in a stable structured form (eslint `messageId` + SARIF; fixed grammar for domain errors).
  4. Keep it compact (one line of why + one of where).
checker: `diagnostic-cites-req` in the flat-config plugin `@org.vibevm/eslint-plugin-ai-native` (rule key `ai-native/diagnostic-cites-req`; source `typescript-ai-native-lang/v1.0.0/tools/eslint-plugin-ai-native/`) — custom messages must match the grammar `violates REQ &lt;uri&gt;: &lt;why&gt;; fix surface: &lt;where&gt;`; wired via the project's own eslint config (demo: `research/ts-demo/eslint.config.js` at `error`)
raid_role: layer=tooling; order=after:none; batch=package
budget: active_rules=1; first_signal=lint pass (&lt;60s)</fence>
  </section>
</spec>
