@vextlabs/theron-cli 0.2.1 → 0.4.0

package/skills/recipe-develop.md

@@ -0,0 +1,109 @@
+---
+name: recipe-develop
+description: Develop, stress-test, and document a recipe end-to-end — ratio-first formulation, dual-unit (grams + volume) ingredient list, yield/serving breakdown, phase-by-phase technique with temperature/time/sensory doneness cues, food-science rationale, substitution tradeoffs, food-safety critical points, and non-linear scaling rules — invoke whenever the user asks to create, fix, scale, or deeply explain a recipe.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+
+1. RATIOS FIRST. State the backbone ratio (e.g., fat:flour:liquid, sugar:acid, meat:cure salt) before any absolute quantity. All absolutes derive from the ratio, not the reverse.
+2. DUAL UNITS MANDATORY. Every ingredient line must carry both metric (grams, ml, °C) AND practical volume/temp (cups, tsp, °F). Never omit either.
+3. SENSORY DONENESS > timer. Every cook step ends with the sensory cue that signals readiness (color, texture, aroma, resistance, internal temp). Timers are outer bounds, senses are the go/no-go signal.
+4. FOOD-SAFETY TEMPS ARE NON-NEGOTIABLE. State the minimum safe internal temperature for every protein or egg-containing element. Never soften, omit, or make optional.
+5. NO FABRICATED SCIENCE. If the mechanism is uncertain, say "likely" or "thought to be." Never state food-science causality as proven fact unless it is textbook-established.
+6. SCALE NON-LINEARLY WHERE PHYSICS DEMANDS IT. Leavening, salt, spice, gelatin, and bake time do NOT scale 1:1 with mass. Flag every non-linear dimension explicitly; scaling coefficients are starting-point conventions that must be verified by tasting and testing before service.
+7. SUBSTITUTIONS MUST STATE THE TRADEOFF. Never list a sub without naming what changes (texture, flavor, structure, color, shelf life).
+8. YIELD AND SERVINGS ARE SEPARATE LINES. Yield = total mass or volume of finished product. Servings = portion count and per-serving mass.
+9. TEMPERATURE DISCIPLINE IS MISE EN PLACE. Cold ingredients (butter for laminated doughs, cream for whipped applications) stay refrigerated until the moment of use. Warm ingredients (eggs for emulsions, milk for yeast activation) are brought to target temperature immediately before combining — not hours in advance. State temperature state for every functional ingredient.
+10. VOLATILE AROMA COMPOUNDS HAVE A TIMING RULE. High-volatility aromatics (fresh herbs, citrus zest, finishing oils, green spices) are added at the last possible moment. Low-volatility aromatics (dried spices, alliums, bark spices) require heat and time to bloom. State the timing rationale explicitly for every aromatic in the method.
+
+═══ PHASE A — CONCEPT AND RATIO FRAMEWORK ═══
+
+A1. Identify the recipe's structural family (emulsion, foam, gel, dough, brine, custard, sauce, braise, cure, ferment, candy, etc.). Each family has a canonical backbone ratio — state it before touching quantities. The structural family determines which failure modes are possible and which scaling rules apply.
+A2. Define the flavor target in three layers:
+   - Primary taste profile: sweet/salty/sour/bitter/umami balance and which is dominant
+   - Dominant aroma compound family: Maillard products (roasted, nutty), terpenes (citrus, herbal, piney), esters (fruity, floral), sulfur compounds (allium, cruciferous), lactones (creamy, coconut), pyrazines (earthy, roasted) — name the family, not just "savory" or "aromatic"
+   - Textural contract: the mouthfeel promise (crisp shell/tender crumb, silky/chunky, light/dense, short/chewy) that the ratio must deliver
+A3. Fix the reference batch size (e.g., 1 kg dough, 500 ml sauce, 12 portions). All scaling derives from this anchor. Choose a reference batch that fits a standard home or professional piece of equipment — do not anchor to an arbitrary mass.
+A4. List critical parameters as ratios against the dominant ingredient (e.g., hydration = water/flour by mass, fat ratio = butter/total flour, salt ratio = salt/total dough mass, sugar/acid ratio for a gel). These ratios are the recipe's DNA — protect them across scales and variations. A recipe that cannot be expressed as ratios is not yet understood.
+
+═══ PHASE B — INGREDIENT SPECIFICATION ═══
+
+B1. Write every ingredient with: (a) gram weight, (b) practical volume measure, (c) ingredient form/grade where it matters (e.g., "kosher salt, Diamond Crystal" vs. Morton changes density by ~1.5×; "00 flour" vs. AP changes protein and granulation; "Dutch-process cocoa" vs. natural changes acid balance), (d) temperature state where relevant (cold butter vs. room-temp butter are functionally different ingredients).
+   Format: `Unsalted butter, cold, cubed: 227 g | 1 cup (2 sticks)`
+B2. Flag ingredients as functional actives or flavor contributors. Functional actives (leavening, salt, gelatin, emulsifiers, acids, starches) require precision — measure by weight, not volume. Flavor contributors (herbs, most spices, vanilla) tolerate a range — measure by volume is acceptable.
+B3. Note shelf life, sourcing flags, or allergy class for every ingredient where relevant (e.g., "high-bloom gelatin: specify bloom strength, 200 bloom assumed; if using lower-bloom, increase quantity proportionally").
+B4. List substitutions per ingredient only if a viable one exists; format as:
+   `Sub: [ingredient] → [sub], ratio [X:1 by weight], tradeoff: [specific change in texture/flavor/structure/color/shelf life].`
+   Never write "can substitute freely" — all substitutions have consequences.
+
+═══ PHASE C — METHOD STEPS WITH SCIENCE ═══
+
+C1. Break the method into named stages (mise en place, primary transformation, rest/hydration/fermentation, finishing, plating). Each stage is a discrete heading. Passive stages (rest, chill, ferment) get the same rigor as active cook stages — describe the physical transformation occurring, not just "set aside."
+C2. Every active cook step must include:
+   - Action verb that encodes technique (fold, sear, temper, degas, emulsify, bloom, deglaze, reduce, mount — not generic "mix" or "cook")
+   - Temperature: vessel/oil/oven/water bath/sugar syrup (°C and °F)
+   - Time range (treat as outer bound, not target — sensory cue overrides it)
+   - Sensory doneness cue (visual, tactile, aural, aromatic, or probe temp) — the go/no-go signal
+   - The WHY in one sentence of food science (e.g., "Resting dough 30 min relaxes gluten networks, reducing elastic snap-back during rolling and preventing toughening.")
+C3. Mark CRITICAL CONTROL POINTS (CCPs) — steps where failure directly risks food safety or irreversible structural collapse. Prefix with ⚠ CCP.
+C4. State aromatic timing explicitly at each step: "Add [aromatic] NOW, not earlier" or "Bloom [spice] in fat for 60 s before adding liquid — the fat-soluble terpenes in [spice] require a lipid carrier to distribute; water addition before blooming traps them in the aqueous phase."
+C5. For any step involving emulsification, state the addition rate. Drop-by-drop for the first 10–20% of oil is not stylistic caution — it is the physics of building a continuous aqueous phase around discrete fat droplets. Rushing this step causes the emulsion to flip or break.
+
+═══ PHASE D — FOOD-SAFETY CRITICAL POINTS ═══
+
+⚠ This section is for educational and informational purposes. Always follow current guidance from your national food-safety authority (USDA/FDA in the US, FSA in the UK, EFSA in the EU) and local health codes, which may supersede the figures below.
+
+D1. For every protein: state minimum safe internal temp per current food-safety authority standards:
+   - Whole poultry (chicken, turkey, duck): 74°C / 165°F (instant read at thickest point, away from bone)
+   - Ground meat (beef, pork, lamb): 71°C / 160°F
+   - Whole cuts of beef, pork, veal, lamb: 63°C / 145°F + 3 min rest
+   - Fish and shellfish: 63°C / 145°F (flesh opaque, flakes easily); bivalves cooked until shells open
+   - Eggs (cooked in dish): yolk and white fully set, or use pasteurized eggs for soft-set applications
+D2. For custards and dairy-based preparations: state the pasteurization threshold (71°C / 160°F held for 15 s, or equivalent time-temperature combination) and the danger zone window (4°C–60°C / 40°F–140°F; do not hold food in this range beyond 2 hours cumulative for perishable preparations).
+D3. State cooling protocol for large batches: reduce from 60°C to 20°C within 2 hours, then to 4°C within a further 4 hours. Specify the method (ice bath with stirring, hotel pan in ice with shallow layer, blast chiller). A covered pot set on a counter does not meet this requirement.
+D4. Flag any raw or undercooked serving style (steak tartare, sashimi, carpaccio, soft-cooked egg, raw shellfish, rare duck breast) as elevated risk. State explicitly: "Immunocompromised individuals, pregnant people, the elderly, and children should avoid this preparation or use only pasteurized/fully cooked versions."
+D5. State cross-contamination controls: dedicated boards/utensils for raw protein vs. ready-to-eat foods, hand-wash moments (after handling raw protein, before touching anything else), allergen segregation if any of the top 14 allergens (or jurisdiction-specific list) are present.
+
+═══ PHASE E — YIELD, SCALING, AND NON-LINEAR ADJUSTMENTS ═══
+
+E1. State yield precisely:
+   `Yield: ~850 g finished product | Servings: 8 × ~106 g portions`
+   Include expected yield loss (evaporation, trimming, bones) if relevant: "Raw weight 1.2 kg → cooked yield ~850 g (29% moisture loss during braise)."
+E2. Provide a scaling table for 0.5×, 2×, and 4× batch. For each scaled quantity, explicitly separate:
+   - Mass-linear (multiply directly): flour, main liquid, main protein, sugar in most applications.
+   - NON-LINEAR — call out each individually:
+     - Leavening (baking powder/soda): scale at ~0.75× rate for batches above 2× to avoid over-aeration and metallic aftertaste. Verify by observing rise height and crumb structure, not by formula alone.
+     - Salt: start at 0.85× of linear scale for 2× batch and taste-adjust; saltiness perception is non-linear and influenced by fat content, acidity, and serving temperature.
+     - Gelatin and pectin: start at 0.9× for 2× batch; gel strength scales super-linearly with concentration — a 2× batch with 2× gelatin will produce a noticeably firmer set.
+     - Spices and dried aromatics: start at 0.7× of linear scale for 2× batch; potency-per-gram increases as the ratio of aromatics to diluting mass rises. Always taste before service.
+     - Bake time: does NOT scale with batch mass. It scales with the thickest cross-section of the individual unit. Two loaves baked simultaneously take the same time as one loaf; a doubled-height loaf takes longer. State the cross-section that governs time.
+     - High-fat emulsions (hollandaise, mayonnaise, béarnaise): do not scale up in a single batch beyond the equipment's shear capacity. Build in same-size batches and combine. Note: vinaigrette-style emulsions (oil/vinegar 3:1) scale without issue; only high-fat cooked or cold emulsions require per-batch rebuilding.
+E3. Note any equipment bottlenecks that set a practical batch ceiling (stand-mixer bowl capacity, oven deck space, pan thermal mass affecting sear quality, immersion circulator water volume).
+
+═══ PHASE F — FAILURE MODES AND FIXES ═══
+
+F1. List the 3–5 most common failure modes specific to the structural family identified in Phase A1 — not generic cooking failures, but the failure modes that characterize this recipe type (e.g., for a pâte à choux: insufficient drying of the panade causes steam loss before structure sets, producing flat hollow-free shells; for a custard: exceeding 85°C / 185°F denatures albumin past set-point, producing a curdled, weeping texture). For each:
+   - Symptom: what you see, taste, feel, or smell
+   - Root cause: the physical, chemical, or biological mechanism (state as "likely" if uncertain)
+   - Fix-in-progress: if the batch is still salvageable, state the intervention and its limit
+   - Prevention: the ratio or process change that eliminates the root cause next time
+F2. Distinguish structural failures (incorrect ratio — often unrecoverable: under-fat lamination, under-gel set, over-hydrated dough) from technique failures (incorrect execution of a correct formula — often recoverable: over-reduced sauce, slightly over-baked protein, broken emulsion before plating).
+F3. State the "point of no return" for each critical transformation: the moment after which correction is impossible and the batch must be discarded or repurposed.
+
+═══ PHASE G — FINAL RECIPE DOCUMENT FORMAT ═══
+
+G1. Deliver the recipe in this canonical order:
+   1. Recipe name + one-sentence flavor/texture promise
+   2. Backbone ratio (bolded)
+   3. Yield + Servings (with yield-loss note if applicable)
+   4. Ingredient list (dual-unit, temperature state noted, functional role flagged for actives)
+   5. Method by named stage, each step with temp/time/sensory cue/aromatic timing/why
+   6. Food-safety summary box (all CCPs consolidated, internal temps, cooling protocol)
+   7. Substitution table
+   8. Scaling notes (non-linear flags called out per ingredient)
+   9. Failure mode table (symptom / cause / fix / prevention)
+G2. No step may say "cook until done," "season to taste," or "bake until golden" without a measurable or sensory anchor (internal temp, specific color reference, resistance test, aroma marker). Ambiguity is a defect, not a stylistic choice.
+G3. The food-safety summary box in item 6 is never optional. If the recipe contains no protein, egg, or dairy, write "No protein/egg/dairy CCPs; standard cross-contamination hygiene applies" — do not omit the section.
+
+KEY PRINCIPLE: The ratio is the recipe; the instructions are physics operating on that ratio. Master the ratio and every variation, scale, and substitution becomes legible. A recipe that cannot survive a 2× scale test without adjustment was never fully understood.

package/skills/red-team.md

@@ -0,0 +1,142 @@
+---
+name: red-team
+description: Adversarially review your own (or given) work — hunt for correctness bugs, edge cases, security holes, and false assumptions; severity-rate each with evidence and a fix.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+## STANCE RULE (non-negotiable)
+
+You are the adversary, not the author. Your job is to find what is WRONG. Praise is not output. Default posture: **assume it is broken until you prove otherwise.** Every "looks fine" is a failure of imagination — dig harder.
+
+---
+
+## PHASE 1 — INGEST WITHOUT JUDGMENT
+
+1. Read the entire artifact (code diff, plan, analysis, argument) in one pass without forming verdicts. Note what it *claims* to do and what it *actually* does.
+2. List the artifact's stated goals and success criteria. These are the bars it must clear.
+3. List every external dependency (libraries, APIs, env vars, DB schemas, other services). Each is an assumption and a potential failure point.
+4. Identify the trust boundary: what inputs arrive from untrusted callers? What outputs cross a trust boundary outward?
+
+---
+
+## PHASE 2 — CORRECTNESS (does it actually work?)
+
+5. Trace the primary happy-path logic step by step. Write out what each line/step does, not what it claims to do. Do they match?
+6. For code: run it if runnable (`Bash` to execute; `Read` the diff line by line — every line, no skimming).
+7. Check every branch: are all code paths reachable? Are any branches dead or contradictory?
+8. Verify loop termination. What guarantees loops exit? Off-by-one on bounds?
+9. Check return types, error propagation, and nullability at every function boundary. Does the caller handle every return variant the callee can produce?
+10. For plans/analyses: trace the causal chain. Does conclusion C follow from premises A and B, or is there an unstated leap? Find the leap.
+
+---
+
+## PHASE 3 — EDGE CASES & FAILURE MODES
+
+11. **Empty / zero / null / undefined:** Feed each input. What breaks?
+12. **Boundary values:** min, max, max+1, negative, zero, very large (beyond expected max).
+13. **Concurrent / race:** If two callers hit this simultaneously, what state corruption is possible? Are locks/transactions correct?
+14. **Network / I/O failures:** What if the DB, API, or filesystem call fails mid-operation? Is state left inconsistent? Is cleanup guaranteed?
+15. **Partial success:** Can this operation succeed halfway and leave garbage? Is rollback handled?
+16. **Retry storms:** If a caller retries on failure, is the operation idempotent? What breaks on double-execution?
+17. **Clock skew / ordering:** If events arrive out of order or timestamps disagree, what happens?
+
+---
+
+## PHASE 4 — SECURITY
+
+18. **Injection:** SQL, shell, template, path traversal, log injection. Trace every user-controlled value from entry point to use site. Is it sanitized at the use site (not just at the entry point)?
+19. **Authorization:** Does every protected action check *both* authentication (who are you?) and authorization (are you allowed?)? Are there shortcuts that bypass the auth layer?
+20. **Secrets / key hygiene:** Are secrets injected via env only? Is anything logged that should not be? Are tokens/keys rotated in error paths?
+21. **SSRF / open redirect:** Does any code fetch a URL derived from user input? Is the target restricted to an allowlist?
+22. **Mass assignment / over-posting:** Does any endpoint accept an object from a caller and pass it directly to a DB or constructor? Are extra fields stripped?
+23. **Denial of service:** Can a caller trigger unbounded computation, memory growth, or I/O by crafting input? Are there size/rate limits?
+24. **Dependency trust:** Are third-party packages pinned to exact versions? Do any fetch remote code at runtime?
+
+---
+
+## PHASE 5 — ASSUMPTIONS (hunt the unstated ones)
+
+25. List every assumption the artifact makes — about data shape, caller behavior, environment, timing, scale, availability.
+26. Mark each: **stated** (explicitly documented), **unstated** (implicit), or **false** (demonstrably wrong).
+27. For each unstated assumption, write the scenario in which it breaks and what the consequence is.
+28. For plans and arguments: find the premise that, if wrong, collapses the entire conclusion. That is the highest-priority finding.
+
+---
+
+## PHASE 6 — STRONGEST COUNTERARGUMENT
+
+29. For every major claim or design decision, construct the *strongest possible* case against it — steelman, do not strawman.
+30. If the counterargument has merit, say so explicitly. Do not bury it in qualifications.
+31. Identify what evidence or experiment would decisively settle the dispute. If it has not been run, say so.
+
+---
+
+## PHASE 7 — PRODUCTION FAILURE SCENARIOS
+
+32. Ask: "What would make this blow up at 3 AM, six months from now, when the author is unavailable?"
+33. Scenarios to check: schema migration without backward compatibility, config value missing in prod env, log volume spike that fills disk, secret rotation that invalidates live sessions, upstream API deprecation, traffic spike beyond tested scale.
+34. For each scenario: is there an alert, a circuit breaker, a fallback, or a runbook? If not, flag it.
+
+---
+
+## PHASE 8 — MISSING CASES
+
+35. What is NOT handled that callers might reasonably expect to be handled?
+36. Are all error codes / status codes / exceptions that the artifact can produce documented and handled by callers?
+37. For APIs: what happens on malformed JSON, wrong Content-Type, missing required field, extra unknown field?
+38. For plans: what is the rollback plan if step N fails? Is it documented? Is it tested?
+
+---
+
+## PHASE 9 — SEVERITY RATING
+
+Rate every finding on two axes, then combine:
+
+**Severity** (impact if it fires):
+- **CRITICAL** — data loss, security breach, silent corruption, production outage
+- **HIGH** — wrong results returned to users, auth bypass, unhandled crash path
+- **MEDIUM** — degraded behavior, performance cliff, bad DX, hard-to-debug failure
+- **LOW** — cosmetic, minor inefficiency, better style available
+
+**Likelihood** (probability it fires in realistic use):
+- **CERTAIN** — will fire on any non-trivial input
+- **PROBABLE** — fires under common conditions
+- **POSSIBLE** — fires under unusual but realistic conditions
+- **UNLIKELY** — only fires under contrived conditions
+
+Combine: CRITICAL×CERTAIN = P0. CRITICAL×PROBABLE = P1. HIGH×CERTAIN = P1. Everything else scaled accordingly.
+
+---
+
+## PHASE 10 — FINDINGS TABLE
+
+Produce one row per finding:
+
+| ID | Phase | Severity | Likelihood | Priority | Finding (one sentence) | Concrete evidence (file:line or quote) | Fix |
+|----|-------|----------|------------|----------|------------------------|----------------------------------------|-----|
+| F1 | 4 | CRITICAL | PROBABLE | P1 | SQL injection via unsanitized `user_id` param | `api.ts:47` passes `req.query.id` directly into template string | Use parameterized query |
+| F2 | 3 | HIGH | CERTAIN | P1 | Empty array input causes `.reduce()` to throw | `processor.ts:82` calls `.reduce()` with no initial value | Pass initial accumulator |
+
+---
+
+## PHASE 11 — GO / NO-GO VERDICT
+
+After the table:
+
+- **GO** — no P0/P1 findings; P2+ findings documented with owner and timeline.
+- **GO WITH CONDITIONS** — P1 findings present but each has a concrete fix committed or scheduled before next release gate.
+- **NO-GO** — any P0 finding; or three or more P1 findings without fixes.
+
+State the **top 3 risks** in order of priority even on a GO verdict. The author must acknowledge them.
+
+---
+
+## HARD RULES (never violate)
+
+- Never mark a finding "low priority" because fixing it is inconvenient. Rate on impact + likelihood only.
+- Never skip Phase 4 (security) because the artifact "isn't user-facing." Internal surfaces are attacked too.
+- Never accept "this can't happen in practice" without evidence. If it *can* happen, rate it.
+- Never treat passing tests as proof of correctness. Tests only cover what was tested. Ask what was not tested.
+- Never end a review with "looks good overall" unless every phase above produced zero findings. If you found nothing, say explicitly what you checked and why you are confident — that is the evidence for GO.
+- If you cannot run the code, say so — and raise the likelihood estimate on every correctness finding by one tier, because you have less evidence.
+- The review is not done until every finding has a **concrete fix**, not "consider adding validation."

package/skills/refactor.md

@@ -0,0 +1,58 @@
+---
+name: refactor
+description: Behavior-preserving refactoring — pin behavior with tests first, one small transformation at a time, run tests after each, never mix refactor with behavior change.
+allowed-tools: Read, Edit, MultiEdit, Bash, Grep, Glob
+---
+
+## PHASE 0 — CHARACTERIZE (non-negotiable before any edit)
+
+1. Read the target file end-to-end. Identify the smell by name: duplication, long function (>40 lines doing multiple things), feature envy (function reaching into another object's guts), primitive obsession (stringly-typed IDs, bare booleans for state), shotgun surgery (one change touches 10 files), divergent change, data clump, switch smell, parallel inheritance.
+2. State the END STATE in one sentence before touching anything: "Extract `parseHeaders` into its own function; caller unchanged."
+3. Find existing tests: `find . -name "*.test.*" -o -name "*.spec.*" | grep -i <module>`. If none cover the target path, write CHARACTERIZATION TESTS first (tests that record current behavior without judging it). Commit them as "test: characterize <module> before refactor". They are your safety net — they must stay green throughout.
+4. Capture baseline: `bash -c "npm test -- --testPathPattern=<file> 2>&1 | tail -20"` and note pass count. Record it. If the suite is slow, identify the minimal subset covering the target and run only that subset on every step.
+
+## PHASE 1 — SCOPE
+
+5. Before renaming or changing any signature, find ALL call sites:
+   - `grep -rn "functionName\|ClassName\|TYPE_NAME" --include="*.ts" --include="*.tsx" .`
+   - Check re-exports: `grep -rn "export.*functionName" .`
+   - Check dynamic references: `grep -rn "['\"]\functionName['\"]" .`
+6. List every file that imports the target. You will re-run typecheck after touching each one.
+7. Define the transformation atomically: one extract, one rename, one inline, one introduce-parameter-object. Write it down. If you find yourself writing two things, stop — do them in separate commits.
+
+## PHASE 2 — TRANSFORM (one step at a time)
+
+Each numbered step below is a COMPLETE cycle. Do not batch steps.
+
+**Step cycle:**
+  a. Make the single smallest behavior-preserving edit (Read → Edit/MultiEdit).
+  b. `bash -c "npx tsc --noEmit 2>&1 | head -30"` — must be 0 errors before proceeding.
+  c. `bash -c "npm test -- --testPathPattern=<file> 2>&1 | tail -20"` — all prior green tests must stay green.
+  d. If anything breaks: REVERT the edit immediately (`git diff` + Edit back), diagnose, retry smaller.
+  e. Commit: `git add -p && git commit -m "refactor(<scope>): <what you did>"` — one transformation per commit.
+
+**Common safe transformations in dependency order:**
+- **Extract function**: copy the block, give it a name, replace original with call, run tests.
+- **Rename** (local var/param): IDE-style find-replace within one file, typecheck, test.
+- **Rename** (exported symbol): update declaration, then ALL import sites (grep found in Phase 1), typecheck, test.
+- **Introduce parameter object**: add new overload accepting object, migrate call sites one file at a time, delete old signature last.
+- **Inline variable/function**: substitute usages, delete declaration, typecheck, test.
+- **Replace conditional with polymorphism**: add interface + implementations behind the abstraction, swap one call site at a time, remove the switch last.
+- **Move function to better module**: add it in new location, re-export from old location, migrate imports gradually, delete re-export last.
+
+## PHASE 3 — VERIFICATION
+
+8. After all transformations are done, run the FULL test suite (not just the subset): `bash -c "npm test 2>&1 | tail -30"`.
+9. Run a full typecheck: `bash -c "npx tsc --noEmit 2>&1"`.
+10. Do a semantic diff review: `git diff <start-sha>..HEAD -- <files>`. Read every changed line. Ask: "Did I accidentally change a condition, a default value, an error message, or a return type?" If yes, that is a behavior change — revert it or move it to a separate follow-up commit marked `fix:` or `feat:`, never inside a `refactor:` commit.
+11. Grep for any TODO/FIXME you introduced during the refactor and resolve or file as a tracked issue before closing.
+
+## HARD RULES
+
+- **NEVER mix refactor + behavior change in the same commit.** A refactor commit must be a no-op to any consumer. If you need to change behavior, finish the refactor, commit, then change behavior in a separate commit.
+- **Build must be green continuously.** Red typecheck = stop, fix, do not proceed.
+- **Tests must be green after every single transformation.** A failing test is a revert signal, not a "fix later."
+- **Characterization tests are sacred.** Never delete or weaken them during the refactor. They may only be updated if the agreed behavior change commit explicitly intends to change that behavior.
+- **Do not gold-plate.** Refactor enough to make the intended change safe and clear, then stop. Opportunistic cleanup of unrelated code creates noise, obscures history, and risks unintended breakage.
+- **Know when to stop.** If the smell is deep (cross-cutting architectural issue), document it, do the minimum safe extract to unblock the current task, and file the larger refactor as a separate tracked work item.
+- **One commit per safe transformation.** Atomic history is the audit trail — it lets you bisect to the exact step that broke something downstream.

package/skills/reflection-session.md

@@ -0,0 +1,115 @@
+---
+name: reflection-session
+description: Run a structured, CBT/ACT-informed EDUCATIONAL reflective session with a user who wants to process an emotion, thought pattern, stressor, or difficult experience — asking reflective questions, validating feelings, gently surfacing cognitive distortions, and closing with one concrete micro-action; escalates immediately to crisis resources on any risk signal.
+allowed-tools: Read, Write
+---
+
+KEY PRINCIPLE: Ask before you assert. The user's own words, reflected back with care, do more therapeutic work than any reframe you could offer. You are a skilled witness, not a problem-solver. Insight belongs to the user; your job is to slow down what is already there.
+
+═══ HARD RULES ═══
+
+1. REFLECTIVE, NOT DIRECTIVE. Aim for at least two questions per assertion. The user's language — not yours — should drive the session. If you catch yourself leading, drop back to a reflect-and-check.
+2. VALIDATE BEFORE REFRAME. Never challenge a thought, name a distortion, or introduce a CBT/ACT concept until the user has demonstrably felt heard (they have confirmed your reflection is accurate or offered more detail voluntarily). Premature reframing ruptures therapeutic alliance.
+3. NEVER DIAGNOSE. Do not name disorders, predict prognosis, or interpret beyond what the user explicitly offered. "This might be depression" is out of bounds. "That sounds exhausting" is not.
+4. NO FABRICATED EVIDENCE. Do not cite statistics, studies, or named theorists with specific numbers unless you are confident of the general, widely-established finding. Say "research suggests" only when you genuinely are. Never invent a figure or an author.
+5. RISK SIGNAL = IMMEDIATE PIVOT. Any mention of self-harm, suicidal ideation, harm to others, active crisis, or abuse triggers Phase RISK before any other response. No exceptions, no delays, no "let me just finish this point first."
+6. ONE MICRO-STEP ONLY. Close with exactly one small, self-directed behavioural or reflective action — not a self-improvement programme, not a list.
+7. DISCLAIMER IS NON-NEGOTIABLE. Every session output, regardless of how brief, must close with the full disclaimer block verbatim. Even a one-turn exchange requires it.
+8. CONFIDENTIALITY HONESTY. If a user asks whether this is private, acknowledge the limits of AI-session storage honestly. Do not promise confidentiality you cannot guarantee.
+9. STAY IN LANE. If the user asks for medication guidance, a clinical diagnosis, medical advice, or legal counsel, name clearly what you cannot provide and redirect: "That's really a question for a doctor / therapist / lawyer — I can't give you a sound answer on that, but I can keep exploring what's underneath it with you, if that's useful."
+10. PACING. Do not rush toward closure. If a user is mid-thought, use a minimal encourager ("Say more about that" / "What else comes up when you sit with it?") and follow before moving to the next phase.
+
+═══ PHASE RISK — Immediate Escalation ═══
+
+Trigger: any language suggesting self-harm, suicidal ideation, harm to others, active abuse, or acute crisis — whether stated directly, alluded to, or described in the past tense with present-tense weight.
+
+R1. Acknowledge with warmth, not clinical alarm: "What you're sharing sounds really heavy, and I'm glad you told me."
+R2. Ask one grounding question before anything else: "Are you safe right now?"
+R3. Surface crisis resources explicitly and immediately — do not bury them:
+    - US/Canada: 988 Suicide & Crisis Lifeline (call or text 988)
+    - Crisis Text Line: text HOME to 741741 (US) / 686868 (Canada) / 85258 (UK)
+    - International resources: https://www.iasp.info/resources/Crisis_Centres/
+    - Emergency services: 911 (US/Canada) or local equivalent
+R4. Do not proceed to Phase A until safety is affirmed or the user redirects. If the user cannot confirm safety, keep reflecting toward help-seeking — mirror their words, validate the weight, and return to the resources. Do not attempt to be the crisis intervention; that is not a role an AI educational tool can fill safely.
+R5. If the user says they are safe but the content remains heavy, acknowledge that explicitly and move forward at their pace: "I'm glad you're safe. We don't have to rush. What feels right to talk about next?"
+
+═══ PHASE A — Open and Ground (turns 1-2) ═══
+
+Objective: create psychological safety; understand the presenting experience in the user's own words without steering toward any particular frame.
+
+A1. Open with an inviting, non-leading question. Match the register to what the user came in with — if they were brief, be brief. Examples (adapt, do not copy verbatim):
+    "What's on your mind that brought you here today?" or
+    "What would be most useful to sit with together right now?"
+A2. Receive the user's first response without interpretation. Reflect the emotional content back using their own words before adding any of yours. The CBT-standard form is:
+    "It sounds like [their language] — is that close to what you're feeling?"
+    If they named a feeling: "You said [word] — I want to make sure I'm tracking that right. Can you say more about what that feels like for you?"
+A3. Clarify scope — narrow before deepening: "Is there a specific moment or situation you'd like to focus on, or is this more of a recurring pattern?"
+A4. Do NOT offer any framework, reframe, psychoeducation, or homework in Phase A. No CBT vocabulary. No "that sounds like it could be…" Your only job is to receive.
+
+═══ PHASE B — Deepen and Validate (turns 3-5) ═══
+
+Objective: help the user articulate the emotion with precision; normalise the reaction without minimising the experience.
+
+Move from Phase A to Phase B when: you have a clear enough picture of the situation and the user has confirmed your reflection, even partially.
+
+B1. Emotion granularity — use the affect differentiation technique: "You said [word]. If you had to be more specific — is it closer to [word-a] or [word-b]?" Choose differentiation pairs from their emotional register, e.g., frustrated vs. defeated; anxious vs. ashamed; sad vs. disappointed. The goal is precision, not correction.
+B2. Body check-in — offer, do not insist; give an explicit opt-out: "Some people find it useful to notice where that feeling lives in the body — do you notice anything like that, or would you rather stay with what's happening at the thought level?" If they decline, move to B3 without any push.
+B3. Validation statement — name the legitimacy of the emotion before anything else: "Given what you're describing, that reaction makes a lot of sense." Do not follow this immediately with "but" or "however." Allow the validation to land. Wait for the user's response.
+B4. History probe — one question only, do not interrogate: "Has this feeling shown up for you before, or does it feel like new territory?"
+    If they say "it always happens": note it — this suggests a schema-level pattern, relevant later in Phase C.
+    If they say "this is new": note it — this may indicate a situational trigger rather than a core belief, which shapes Phase C.
+B5. Check your understanding before moving forward: "I want to make sure I'm following this correctly — [brief summary in their language]. Does that feel accurate, or is there something I'm missing?"
+
+═══ PHASE C — Explore the Thought Layer (turns 6-9) ═══
+
+Objective: surface the automatic thoughts driving the emotion; invite gentle examination using CBT Socratic questioning; introduce ACT defusion if the user is fused to a thought. Do not begin Phase C until Phase B is complete (the user has confirmed B5).
+
+C1. Thought elicitation — use CBT's hot-thought probe: "When this situation is at its worst, what's the thought that goes through your mind? Sometimes it's almost like a sentence — what does it say?"
+C2. Meaning probe — follow the thought to the core belief level: "If that were true — really true — what would that mean about you? About what's possible for you?"
+C3. Evidence inquiry — Socratic, not prosecutorial; use both directions: "What experiences fit that story?" [pause, let them answer] "Is there anything that doesn't quite fit it, even a little?"
+    If the user can't find counter-evidence: do not push. Move to C4 or C5 and return here if the user opens it.
+C4. Perspective shift — offer, do not impose; use the compassionate-other technique from CFT: "If a close friend described exactly the same situation to you — same facts, same feelings — what would you notice? What would you say to them?"
+C5. ACT defusion option — use when the user appears fused to the thought (speaking about it as fact, not as a mental event): "What if that thought is one story your mind is running right now — not a fact, not a verdict on you? When you look at it that way, even slightly, what shifts?"
+    Follow this with: "You don't have to believe that or disbelieve it. Just notice whether there's any space around the thought."
+C6. Name a cognitive distortion ONLY when: (a) the pattern is clear across at least two examples, (b) the user seems open to reflection rather than defended, and (c) you frame it as a common human process, not a pathology or flaw:
+    "This sounds a bit like what CBT calls [name] — a really common mental habit that tends to amplify under stress. Does that resonate, or does it feel like it's missing something?"
+    Recognised CBT distortions you may name: all-or-nothing thinking, catastrophising, mind-reading, emotional reasoning, personalisation, should statements, discounting the positive, mental filter, fortune-telling, labelling.
+    Do NOT name a distortion if the user's thought is accurate — a thought about a genuinely bad situation is not a distortion.
+
+═══ PHASE D — Meaning and Values (turns 9-11) ═══
+
+Objective: connect the exploration to what genuinely matters to the user (the ACT values axis); ground the micro-step in intrinsic motivation, not willpower. Move to Phase D when the thought layer has been examined and the user has some spaciousness around the material — not necessarily resolution, but room to look broader.
+
+D1. Values probe — use the ACT life-areas frame but without jargon: "Underneath all of this — what actually matters most to you in this part of your life? Not what you think you should want — what genuinely matters?"
+D2. Gap question — surface the ACT committed-action tension: "Is the way things are right now in tension with that? What does that gap feel like?"
+D3. Strengths inventory — draw on the user's own coping history using a behavioural activation lens: "When you've faced something that stretched you before — not necessarily this exact thing — what did you draw on that helped you move even slightly? Not a cure, just movement."
+    If the user says "I don't know" or "nothing": "Sometimes it's things so small they don't feel like strengths — getting through the day, reaching out, noticing something. Does anything like that come to mind?"
+D4. Do not prescribe values or tell the user what should matter to them. Your role is to reflect and inquire only. If a user's values include harming themselves or others, do not affirm them — return to Phase RISK.
+
+═══ PHASE E — Close with One Micro-Step (final turn) ═══
+
+Objective: end with agency, not dependency. One small, self-directed, behavioural or reflective action the user chooses or co-selects.
+
+E1. Summarise the session in 3-4 sentences using the user's own language — what they brought in, what shifted or clarified, and where they are now. Do not introduce new material.
+E2. Invite the user to name the step themselves first — this is the CBT behavioural activation principle: "If there were one small thing — not a fix, just a small move — that felt right to do in the next day or two, what might it be?"
+E3. If the user cannot identify one: offer exactly two concrete options at different effort levels and let them choose. Each option must be:
+    - Specific, not "practice self-care" or "be kind to yourself"
+    - Actionable within 48-72 hours without depending on another person's behaviour
+    - Self-directed
+    - Reflective or behavioural in nature
+    Examples tied to common CBT/ACT micro-steps (select and adapt to the session's content):
+      LOW EFFORT: "Write one sentence — not an essay, just one — answering: 'What I was really feeling under all of this was ___.'"
+      LOW EFFORT: "Set a 5-minute timer and let yourself feel [the emotion they named] without trying to fix it or move away from it."
+      MODERATE: "The next time [the situation] happens, notice the thought before you respond to it — you don't have to do anything with it, just catch it."
+      MODERATE: "Have one honest, two-sentence conversation with [person, if relevant] — just the two sentences, nothing more."
+      HIGHER: "Write out the evidence on both sides of [the specific thought they identified] — not to disprove it, but to look at it clearly."
+E4. Close with: "You don't have to figure everything out right now. This was one window into it."
+
+═══ MANDATORY CLOSING DISCLAIMER ═══
+
+Include this block verbatim at the end of every session output, every time, with no modifications:
+
+---
+EDUCATIONAL TOOL — NOT THERAPY OR PROFESSIONAL ADVICE
+This session is an educational, AI-assisted reflective exercise informed by CBT and ACT principles. It is not a substitute for professional mental health care, psychotherapy, counselling, or medical advice. If you are experiencing persistent distress, mental health difficulties, or a crisis, please reach out to a licensed mental health professional or your primary care provider. In an emergency or if you are in crisis, contact 988 (US/Canada Suicide & Crisis Lifeline), text HOME to 741741 (Crisis Text Line, US), or your local emergency services. The AI facilitating this session is not a therapist and cannot diagnose, treat, or provide clinical care.
+---

package/skills/regulatory-compliance.md

@@ -0,0 +1,136 @@
+---
+name: regulatory-compliance
+description: Map a product or process to a named regulation (GDPR/CPRA, HIPAA, SOC 2, FTC Act §5, PCI-DSS v4.0, EU AI Act, CCPA, etc.), enumerate every applicable obligation with exact cited section, distinguish control gaps from evidence gaps, rank remediation items by legal exposure and breach probability, surface cross-jurisdiction conflicts, and flag all items requiring licensed counsel — use when the user asks about compliance gaps, regulatory mapping, audit readiness, or legal risk for a specific product or workflow.
+allowed-tools: Read, WebSearch, WebFetch, Write
+---
+
+DISCLAIMER: THIS SKILL PRODUCES AN ANALYSIS, NOT LEGAL ADVICE. Nothing in any output produced by this skill constitutes legal advice, establishes an attorney-client relationship, or may be relied upon as a substitute for qualified legal counsel in the applicable jurisdiction. Compliance gap reports generated here must be reviewed by a licensed attorney before being acted upon. Treat every output as a working draft for counsel review.
+
+═══ HARD RULES ═══
+
+1. NEVER assert a regulatory interpretation as settled law; flag contested interpretive questions explicitly as "contested — counsel required" and cite the competing positions where known.
+2. NEVER fabricate section numbers, article citations, official guidance URLs, enforcement actions, fine amounts, or penalty figures — cite only what is verified in this session or mark explicitly as "UNVERIFIED — confirm before use."
+3. NEVER collapse distinct regulations into one bucket; each named regulation gets its own obligation inventory even when obligations overlap.
+4. NEVER treat output as legal advice; every deliverable closes with a mandatory LICENSED-COUNSEL REQUIRED section that is non-optional and non-waivable.
+5. NEVER assume a prior version of a regulation applies; fetch or note the current effective version and date. Statutory text AND regulatory guidance (agency opinions, supervisory authority decisions, enforcement letters) both shift interpretation — flag when guidance post-dates the statute you are citing.
+6. ALWAYS scope to the jurisdictions and data subjects actually in play — a SaaS serving EU residents triggers GDPR regardless of company incorporation; a US app processing California residents' data triggers CPRA regardless of where servers are located.
+7. ALWAYS distinguish CONTROL GAP (control does not exist) from EVIDENCE GAP (control exists but is undocumented or unprovable to an auditor). Remediation cost and legal exposure differ by an order of magnitude; conflating them wastes resources and leaves real exposure unaddressed.
+8. ALWAYS check whether an obligation is gated on a threshold (e.g., GDPR Art. 37 DPO requirement; CPRA Cal. Civ. Code §1798.199.10 revenue/volume thresholds; PCI-DSS merchant level tiers; EU AI Act Annex III risk categories). Never assume a threshold is met — require factual confirmation.
+9. ALWAYS surface cross-jurisdiction conflicts where two regulations impose contradictory obligations on the same data (e.g., GDPR Art. 17 erasure vs. HIPAA 45 CFR §164.530(j) six-year retention; CPRA right-to-know vs. trade-secret exemptions). Flag conflicts explicitly; resolution requires counsel.
+10. ALWAYS note that compliance gap reports may themselves be discoverable in litigation. Advise the recipient to discuss attorney-client privilege or work-product protection with counsel before distributing the report.
+
+═══ PHASE A — REGULATORY SCOPING ═══
+
+A1. Identify the product/process type precisely — SaaS B2B/B2C, medical device (FDA 21 CFR Part 820 or EU MDR 2017/745), financial product (GLBA, Reg E), payment processor, consumer mobile app, internal HR tool, AI decision system, clinical software. The product type determines which regulatory families are candidates; do not guess — read the product description or codebase to confirm what data is collected, from whom, and for what purpose.
+
+A2. Enumerate jurisdictions on four independent axes, because each axis can independently trigger a different regulatory body:
+   (a) Where is data collected (point of interaction)?
+   (b) Where are data subjects located (residency of users)?
+   (c) Where is the controller/processor incorporated or established?
+   (d) Where is data stored and processed?
+
+A3. For each candidate regulation, apply its own jurisdictional trigger test before including it in scope. Run each test explicitly and record the outcome:
+   - GDPR (EU) 2016/679 Art. 3: Is the controller/processor established in the EU? OR are EU data subjects targeted (goods/services offered) or monitored (tracking behavior)?
+   - CPRA (California) Cal. Civ. Code §1798.100 et seq. (CPRA as of Jan 1, 2023 supersedes and amends CCPA; cite the consolidated CPRA text, not the 2018 CCPA original): Does the business exceed $25M revenue, buy/sell/share 100K+ consumers' data, or derive 50%+ revenue from selling/sharing personal information?
+   - HIPAA 45 CFR §160.103: Is the entity a covered entity (healthcare provider, health plan, healthcare clearinghouse) or business associate handling PHI? Applies to PHI in any medium, not just electronic.
+   - FTC Act §5 (15 U.S.C. §45): Does the entity engage in commerce and make material representations (express or implied) about privacy or security practices? FTC's deceptive-practices authority is jurisdiction-independent for entities subject to FTC Act; also check FTC Health Breach Notification Rule (16 CFR Part 318) if health data is involved.
+   - PCI-DSS v4.0 (effective March 2024, v3.2.1 sunset March 2025) Requirement 1.1 / Scope §1: Does the entity store, process, or transmit cardholder data (CHD) or sensitive authentication data (SAD)?
+   - EU AI Act (Regulation 2024/1689, effective Aug 1, 2024; high-risk provisions apply from Aug 2026): Is the AI system placed on the EU market or put into service in the EU? Is it in a high-risk category per Annex III? Is it a prohibited practice per Art. 5?
+   - SOC 2 (AICPA Trust Services Criteria): Is the entity a service organization whose controls are relevant to user entities' financial reporting or operational risk? SOC 2 is a voluntary attestation framework, not a regulation — clarify whether the user needs the attestation or only wants to assess against the Trust Services Criteria.
+   - State breach notification laws: Every US state has one; cite the applicable state law if a breach scenario is in scope.
+
+A4. Produce a Regulatory Scope Table for every regulation assessed (in-scope and out-of-scope):
+   | Regulation | Version / Effective Date | Trigger Test | Trigger Met? | Jurisdiction | Primary Enforcer | Max Penalty (cite source) |
+   Populate Max Penalty only from cited official text with article/section. Mark thresholds as "unconfirmed" where factual inputs are missing.
+
+A5. Flag any regulations that are "likely in scope but threshold unconfirmed" — list exactly which facts are needed to confirm and from whom those facts must be obtained.
+
+A6. Note the date this scoping was performed. Instruct the recipient to re-run Phase A whenever: a new data category is collected; a new jurisdiction is entered; a regulation is amended or a significant enforcement decision is published; or a new vendor with data access is onboarded.
+
+═══ PHASE B — OBLIGATION INVENTORY ═══
+
+B1. For each in-scope regulation, enumerate EVERY applicable obligation as a numbered line item. Format each item:
+   [REG-SECTION] | Obligation description | Trigger condition | Obligation type: TECHNICAL / ORGANIZATIONAL / LEGAL / DOCUMENTATION
+
+B2. Cover all of the following obligation categories for each regulation; do not skip a category without noting why it does not apply:
+   - Lawful basis / consent / legitimate interest (where applicable — GDPR Art. 6/7/9; CPRA consent for sensitive PI; HIPAA minimum-necessary standard)
+   - Data minimization, purpose limitation, storage / retention limits (GDPR Art. 5(1)(c)(e); HIPAA 45 CFR §164.530(j); PCI-DSS Req 3.2)
+   - Individual / data subject rights: access, correction, deletion/erasure, portability, objection, restriction, opt-out of sale/sharing (GDPR Arts. 15-22; CPRA §§1798.100-1798.125; HIPAA 45 CFR §164.524-§164.528)
+   - Security controls: encryption at rest and in transit, access control (least privilege, MFA), audit logging, vulnerability management, breach detection (GDPR Art. 32; HIPAA Security Rule 45 CFR Part 164 Subpart C; PCI-DSS v4.0 Reqs 3-12; FTC Safeguards Rule 16 CFR Part 314 where applicable)
+   - Vendor / processor agreements: DPAs (GDPR Art. 28), BAAs (HIPAA 45 CFR §164.314), service provider contracts (CPRA §1798.100(e)), PCI-DSS Requirement 12.8
+   - Notification obligations: breach notification timelines (GDPR Art. 33 72-hour to supervisory authority / Art. 34 to individuals; HIPAA Breach Notification Rule 45 CFR Part 164 Subpart D 60-day; CPRA §1798.150 civil right of action; state laws vary 30-90 days; FTC HBNR 60-day)
+   - Documentation and record-keeping: Records of Processing Activities (GDPR Art. 30), Data Protection Impact Assessment (GDPR Art. 35), HIPAA risk analysis (45 CFR §164.308(a)(1)), audit logs, policy versioning
+   - Appointment obligations: Data Protection Officer (GDPR Art. 37-39 — threshold-gated), Privacy Officer and Security Officer (HIPAA 45 CFR §164.308(a)(2) and §164.530(a)), QMS officer (EU AI Act high-risk Art. 17)
+   - Cross-border data transfer mechanisms: SCCs (Commission Decision 2021/914), BCRs, adequacy decisions (GDPR Art. 45-46), UK IDTA, APEC CBPR where relevant; EU AI Act cross-border scope
+   - Design and product obligations: Privacy by design and default (GDPR Art. 25), algorithmic transparency and human review rights (EU AI Act Arts. 13-14; CPRA §1798.185(a)(16) automated decision-making regulations in progress), EU AI Act technical documentation (Art. 11) and conformity assessment (Art. 43)
+   - Consumer-facing notices: Privacy policy content requirements (CPRA §1798.130; GDPR Arts. 13-14 — distinct requirements for data collected directly vs. indirectly)
+
+B3. For each obligation, record the penalty regime tied to THAT specific obligation — not the global maximum. Some obligations carry fixed administrative fines; others are percentage-of-global-annual-turnover; others give rise to private rights of action with statutory damages. Note which.
+
+B4. Mark each obligation: ACTIVE (product is live and processing the relevant data now) vs. FUTURE (planned feature not yet deployed). Active obligations carry immediate exposure; future obligations allow design-time compliance but must be built to spec before launch.
+
+B5. Where two in-scope regulations impose conflicting obligations on the same data or workflow, flag the conflict with a CONFLICT tag and describe both obligations precisely. Do not propose a resolution — escalate to the licensed-counsel flag list in Phase E.
+
+═══ PHASE C — GAP ASSESSMENT ═══
+
+C1. For each obligation inventoried in Phase B, assess current state against exactly one status:
+   - COMPLIANT: Control exists, is enforced in production, is documented, and evidence is available and auditor-ready.
+   - EVIDENCE GAP: Control exists operationally (code, process, or contract is in place) but lacks retrievable documentation or audit trail that would satisfy an external auditor.
+   - PARTIAL: Control is partially implemented; specify exactly which sub-obligations are met and which are not.
+   - CONTROL GAP: No control exists; the obligation is wholly unmet.
+
+C2. To assess each obligation, apply this four-question test explicitly:
+   (a) Does a technical or organizational control address this specific obligation? (Read codebase, architecture docs, vendor contracts, policy documents — do not assume.)
+   (b) Is the control enforced in production, not just described in a document?
+   (c) Is there a dated, retrievable artifact proving compliance that would survive regulatory review (log export, signed DPA, policy version with effective date, penetration test report, signed BAA)?
+   (d) Would an external auditor or the primary regulatory enforcer for this obligation consider the evidence sufficient under that regulation's audit or investigation standard?
+
+C3. Document each gap with: Obligation ref | Gap type (CONTROL / EVIDENCE / PARTIAL) | Current state description | Specific evidence that is missing or insufficient.
+
+C4. For each CONTROL GAP or PARTIAL gap, flag if there is a known enforcement precedent — a published fine, consent decree, or regulatory action where an enforcer has sanctioned this exact gap. These are acute exposure items. Cite the enforcement action (case name, enforcer, year, penalty) if known; if you cannot verify the citation do not fabricate it — note "enforcement precedent likely — verify before use."
+
+C5. Note where a gap assessment could not be completed due to missing factual inputs (architecture not shared, vendor contracts not available, data maps not produced). Record what information is needed and from whom.
+
+═══ PHASE D — RISK RANKING AND REMEDIATION ROADMAP ═══
+
+D1. Score each gap on two axes:
+   - LEGAL EXPOSURE: Penalty magnitude × enforcement probability × regulatory/public visibility. Rate H / M / L and provide written reasoning, including any enforcement trends or active regulatory investigations in this domain. Do not use bare numbers or made-up percentages.
+   - REMEDIATION EFFORT: Estimated effort, separated into engineer-days (for technical controls), policy-days (for organizational documents), and legal-days (for attorney-required work). Use ranges, not false precision.
+
+D2. Assign each remediation item a priority tier:
+   - CRITICAL (remediate before the next data processing cycle or product launch): Control gaps with H legal exposure, or any gap where a regulatory investigation or enforcement action is already underway or publicly threatened.
+   - HIGH (remediate within 30 days): Partial controls or evidence gaps with H or M exposure where the relevant enforcer has an active enforcement program in this gap category.
+   - MEDIUM (remediate within 90 days): Evidence gaps or partial controls with M exposure and no known active enforcement trend.
+   - LOW (remediate in next planning cycle): Documentation hygiene, policy refresh, low-exposure items, cosmetic notice updates.
+
+D3. For each CRITICAL and HIGH item, provide a concrete, specific remediation action — not a category but a task:
+   - Technical gap: specific code or infrastructure change with named components (e.g., "add AES-256 encryption at rest to the `pii_profiles` table; document key rotation schedule and store in runbook at [path]; test with [method]").
+   - Organizational gap: specific document or process artifact to create, including mandatory clauses where regulation specifies them (e.g., "execute a GDPR Art. 28 DPA with [vendor name] covering all mandatory clauses in Art. 28(3); confirm subprocessor list is appended").
+   - Legal gap: specific legal instrument required and the form it must take (e.g., "adopt EU SCCs Module 2 (controller-to-processor) for the [vendor] data transfer; confirm Annex I, II, and III are completed with actual technical and organizational measures, not placeholders").
+
+D4. Produce a Remediation Roadmap Table:
+   | # | Obligation Ref | Regulation + Section | Gap Type | Priority | Action | Owner Type (Eng / Legal / Ops / Exec) | Estimated Effort |
+
+D5. Separately list items where remediation REQUIRES a licensed attorney in the relevant jurisdiction — not an engineer or compliance analyst alone:
+   - Negotiating, drafting, or reviewing DPAs, BAAs, SCCs, or data transfer agreements with enterprise vendors.
+   - Determining the correct lawful basis under GDPR Art. 6 where legitimate interest is contested or where the supervisory authority of the lead establishment has issued conflicting guidance.
+   - Responding to a regulatory investigation, supervisory authority inquiry, or enforcement letter.
+   - Drafting or reviewing a breach notification to a supervisory authority or to affected individuals.
+   - Assessing whether an AI system qualifies as high-risk under EU AI Act Annex III, or falls under a prohibited practice under Art. 5.
+   - Resolving any cross-jurisdiction conflict identified in Phase B (B5).
+   - Making a determination on attorney-client privilege or work-product protection for this gap report before it is distributed.
+   - Any situation where criminal liability (e.g., intentional HIPAA violation 42 U.S.C. §1320d-6; CPRA AG enforcement) is a plausible outcome.
+
+═══ PHASE E — OUTPUT AND HANDOFF ═══
+
+E1. Produce a single Compliance Gap Report containing, in order: Regulatory Scope Table (Phase A), Obligation Inventory (Phase B), Gap Assessment (Phase C), Risk-Ranked Remediation Roadmap (Phase D), Cross-Jurisdiction Conflicts list, and the Licensed-Counsel Required section. Do not omit any section.
+
+E2. Every regulatory citation must include: regulation name, version/effective date, article/section/rule number, and — if fetched live — the URL and the date retrieved. Every enforcement action cited must include: case name or docket number, enforcing authority, year, and penalty. If any citation could not be verified in this session, mark it "UNVERIFIED — confirm with counsel before relying on this."
+
+E3. Close the report with a LICENSED-COUNSEL REQUIRED section listing every item flagged in D5 and B5, plus the standing disclaimer that this report is not legal advice and must be reviewed by qualified counsel in each relevant jurisdiction before any action is taken or any representation is made to a regulator, customer, or counterparty.
+
+E4. Add a REPORT SENSITIVITY notice: This compliance gap report documents identified weaknesses in the organization's regulatory posture. Distribution of this report may have legal consequences, including potential use in litigation or regulatory investigations. The recipient should consult legal counsel about privilege protection before distributing this report outside the legal and compliance team.
+
+E5. Record the date of assessment and the specific product/process version or codebase commit that was reviewed. Instruct the recipient to re-run Phase A whenever: (a) a new category of personal or sensitive data is collected; (b) a new jurisdiction is entered or a new user population is targeted; (c) a regulation is amended, a new enforcement decision is published, or supervisory authority guidance material to this product is issued; (d) a new vendor with access to regulated data is onboarded; or (e) a material change is made to the product's data architecture or processing purpose.
+
+KEY PRINCIPLE: Compliance is an obligation inventory matched to evidence — every gap is either a missing control or missing proof, and conflating the two wastes money and leaves real exposure unfixed. Regulations impose specific obligations with specific cures; treat each one as an engineering requirement with a named acceptance criterion, not a general standard to aspire toward.