<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">CARD: scaffold-i-codemods — Scaffolded Edit Operations / Codemods (TypeScript)</title>
  <status stage="spec" state="done"/>
  <p p="1"><fact id="status-line" status="impl/done">**Discipline v0.2 · BETA · T2 · TypeScript · [E-hyp] — validate before relying on it**</fact></p>
  <section id="band-one-identity" title="Band 1 — Identity &amp; Recognition">
    <p p="2"><fact id="CLASSIFICATION" status="impl/done">Classification: layer=H (weak-reader) + A (language-shape); mechanism=scaffold I.</fact></p>
    <p p="3"><fact id="INTENT" status="impl/done">Intent: Offer a capability-demanding multi-file change as ONE parameterized, checked operation — converting an edit a weak agent cannot safely coordinate into a parameter-filling task. TypeScript's mature codemod ecosystem (`ts-morph`, `jscodeshift`, typed ESLint autofix) makes this the most achievable scaffold here, where in Rust it is the least.</fact></p>
    <p p="4"><fact id="ALSO-KNOWN-AS" status="spec/done">Also Known As: codemod; AST rewrite; refactoring script; scripted migration; semantic patch; `jscodeshift` transform; ESLint autofix.</fact></p>
    <p p="5"><fact id="APPLICABILITY-RECOGNITION" status="impl/done">Applicability / Recognition: Apply when — a common change touches many files atomically (add a cell, register a variant, rename across a seam); the edit's size is itself the failure driver (R2C-006); the weakest swarm tier cannot coordinate it by hand. *Detector seed:* a recurring change-type that reliably requires touching &gt;1 file in lockstep → recognition fires.</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 asked to "rename this seam across its 7 call-sites + the barrel re-export + the discriminated error union" desynchronizes them. A `codemod rename-seam --from X --to Y` over TypeScript's mature AST tooling **would** perform the change atomically and verifiably, the agent filling two parameters instead of coordinating seven edits — that operation is specified and not yet built. The shipped codemod surface today is one verb, `typescript-ai-native codemod add-cell --cell &lt;cell&gt; --spec-uri &lt;uri&gt;`, which writes the seam module and its `node:test` smoke test atomically and rolls back on failure. This mirrors how constrained decoding lifts weak models (DR1-015): collapse the hard task into a constrained, parameterized one.</fact></p>
    <p p="7"><fact id="STRUCTURE-AND-PARTICIPANTS" status="impl/done">Structure &amp; Participants: *Codemod* (`ts-morph`/`jscodeshift` AST rewrite, or typed ESLint autofix) · *Parameters* (the small named inputs) · *Atomic application* (all-or-nothing) · *Post-check* (`tsc` + `vitest` green).</fact></p>
    <p p="8"><fact id="COLLABORATIONS" status="impl/done">Collaborations: Implements bulk application of Classes A/B/G in raids; emits Class F diagnostics on failure; the Class D oracle wraps it when it changes behavior.</fact></p>
    <p p="9"><fact id="GOALS-AND-NON-GOALS" status="impl/done">Goals / Non-Goals: *Goals:* convert capability-demanding multi-file edits into parameterized operations for the weak swarm. *Non-Goals:* NOT a general refactoring IDE; NOT for one-off changes; NOT a production transform of semantics.</fact></p>
    <p p="10"><fact id="CONSEQUENCES" status="spec/done">Consequences: (+) the weakest tier can perform edits otherwise beyond it; (+) atomicity kills desync and phantom diffs; (+) the tooling is mature, so the build-side cost is low — TypeScript's scaffold advantage. (−) codemods are code to maintain and test; (−) **[E-hyp] risk:** parameterizing a codemod may itself exceed the weakest models — the very build/use boundary in question.</fact></p>
    <p p="11"><fact id="ALTERNATIVES" status="spec/done">Alternatives: hand-editing (fails at scale for weak agents); a generator (Class A) when the artifact is derivable rather than transformed. Codemods are for TRANSFORMING existing code.</fact></p>
    <p p="12"><fact id="RISKS-AND-ASSUMPTIONS" status="spec/done">Risks &amp; Assumptions: **assumes weak agents can correctly parameterize the operation** — UNVALIDATED; this is the prime pilot question. If false, restrict the weakest tier to fixed-parameter invocations only. Unlike Rust, the tooling-immaturity risk does NOT apply here — `ts-morph`/`jscodeshift` are production-grade; only the parameterization question remains open. *Sunset:* if language/tooling makes the change trivial, the codemod retires.</fact></p>
    <p p="13"><fact id="EVIDENCE-AND-TRANSFER-STRENGTH" status="spec/done">Evidence &amp; Transfer-strength: first-principles from R3-013 (ownership graph bounds throughput) + R2C-006 (edit size drives failure) + DR1-015 (constraints lift weak models). The mature ecosystem is the one place TypeScript moves the [E-hyp] tag toward feasibility (the *build* half is solved; the *use*/parameterization half is the open question). Class: theory. Tag: **[E-hyp]**.</fact></p>
  </section>
  <section id="band-three-operation" title="Band 3 — Operation">
    <fence lang="card-ops" p="14">trigger: WHEN a recurring change-type reliably requires &gt;1 file edited in lockstep THEN apply
mode: raid            # bulk application; also offered as an on-demand command
routine:
  1. Identify the recurring multi-file change and its minimal parameters.
  2. Implement a ts-morph / jscodeshift codemod performing it atomically.
  3. Add a post-check: result type-checks (tsc) and per-cell tests (vitest) pass.
  4. Wrap behavior-changing codemods in a Class-D oracle.
  5. For the weakest tier, expose ONLY fixed-parameter invocations (no free parameterization) until the pilot validates parameterization.
checker: the codemod's own post-check (tsc + vitest) ; conform `multi-file-change-has-codemod` (advisory, WISH until pilot-validated)
raid_role: layer=any; order=wraps-with:differential-oracle; batch=package
budget: active_rules=1; first_signal=codemod post-check (&lt;60s/package)</fence>
  </section>
</spec>
