@jamie-tam/forge 6.0.0

package/skills/support-gotcha/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: support-gotcha
+description: "Use when a subtle bug, surprising behavior, or hard-won lesson is uncovered that could recur — records it as a typed wiki page for future prevention."
+---
+
+# Support: Gotcha
+
+## Overview
+
+Every bug fixed, every failed approach, every "I wish I'd known that earlier" moment contains a lesson. This skill captures those lessons as typed wiki pages in `aiwiki/gotchas/` so future sessions hit them before the same mistake happens again.
+
+**Core Principle:** A gotcha recorded once should prevent the same mistake forever.
+
+**Announce at start:** "I'm using the support-gotcha skill to record this lesson learned."
+
+## When to Use
+
+**Automatic triggers (invoked by other skills):**
+- After `support-debug` resolves a bug
+- After `deliver-db-migration` encounters an issue
+- After `deliver-deploy` has a rollback or complication
+- After any skill encounters an unexpected failure
+
+**Manual triggers:**
+- User says "remember this" or "note this for next time"
+- A non-obvious library or tool behavior is discovered
+- A workaround is needed that should eventually be fixed properly
+- A pattern keeps recurring across features
+
+**Always record a gotcha when:**
+- A bug took longer than expected to fix
+- The fix was different from the initial hypothesis
+- A library behaved differently than documented
+- An environment-specific issue wasted time
+- A process step was skipped and caused problems
+
+**Do NOT write a gotcha for:** bugs in your own code that weren't framework- or pattern-related, one-off typos, problems already documented in `aiwiki/conventions/` (write the convention instead).
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Concrete lesson: what broke, why, how to prevent |
+| **Produces** | Gotcha page in `aiwiki/gotchas/{YYYY-MM-DD}-{slug}.md` (project) or `~/.claude/gotchas/{YYYY-MM-DD}-{slug}.md` (global) |
+| **Schema** | `aiwiki/schemas/gotcha.md` — LINT validates frontmatter + sections on write |
+| **Feeds into** | Future sessions (prevention), `gotcha-hunter` agent (surfaces relevant entries to reviewers), `/evolve` (skill improvement) |
+
+### Storage tiers
+
+| Tier | Location | Scope | When |
+|---|---|---|---|
+| Project | `aiwiki/gotchas/` | This codebase only | Issue specific to this stack, patterns, or config |
+| Global | `~/.claude/gotchas/` | All future projects | Issue applies universally — library behavior, general pattern |
+
+When uncertain, default to project. The gotcha can be promoted later by writing a global copy and retiring the project one.
+
+## The Gotcha Process
+
+### Step 1: Extract the lesson
+
+Three pieces of information must be concrete:
+
+1. **What broke** — the failure or surprise, not the symptom
+2. **Root cause** — what was actually wrong, not what looked wrong
+3. **Prevention** — actionable steps ("Check X before doing Y"), not "be more careful"
+
+### Step 2: Classify project vs global
+
+| Question | Answer |
+|---|---|
+| Would this happen in a different project with a different stack? | Yes → global |
+| Is this about a specific library version, config, or this project's architecture? | Yes → project |
+| Is this about Docker, CI, or deployment in general? | Yes → global |
+
+When genuinely ambiguous, ask the user: "Project-specific or universal?"
+
+### Step 3: Search for existing matches
+
+Before writing a new file, grep `aiwiki/gotchas/` (and `~/.claude/gotchas/` for global) for the same pattern. If a matching gotcha exists:
+
+- Bump its frontmatter `occurrences` field by 1
+- Update `status` per the auto-promotion path (see Step 5): 1 → `active`, 2 → `watch`, 3 → `promotion-pending`
+- Append a one-line entry under `## Reproducer` if the new occurrence has a different reproducer
+
+Do NOT write a duplicate file.
+
+### Step 4: Write the gotcha page
+
+**File naming:** `{YYYY-MM-DD}-{slug}.md`. Slug is kebab-case, ≤8 words, describes the pattern (not the symptom).
+
+**Schema-aligned frontmatter:**
+
+```yaml
+---
+schema_id: gotcha
+schema_version: 1
+severity: low | medium | high | critical
+date: YYYY-MM-DD
+occurrences: 1
+status: active
+---
+```
+
+**Required sections** (LINT will reject the file if any are missing or out of order):
+
+| Section | Content | Citation |
+|---|---|---|
+| `## What broke` | One sentence — what failed and where | Cite the failure point |
+| `## Reproducer` | Minimal steps or code link | Cite if linking to an existing test |
+| `## Root cause` | What was actually wrong | Cite with `file:line@<sha7>` |
+| `## Fix` | The resolution | Cite the fix code |
+| `## Prevention` | Rule, check, or pattern that prevents recurrence | Cite a convention or rule if one exists |
+
+**Line caps:** hard cap 150 lines, soft target 50-100. A gotcha that needs more than 150 lines is two gotchas, or it's narrative debug logs that don't belong here.
+
+**Citations:** every section needs at least one. Code references use `file:line@<sha7>` form. LINT auto-fills missing `@<sha7>` on first save.
+
+Skeleton example: see `aiwiki/schemas/gotcha.md`.
+
+### Step 5: Auto-promotion path (1 → 2 → 3 occurrences)
+
+The `occurrences` field drives `status` automatically. Step 3 bumps the count; this step records the corresponding state transition.
+
+| Occurrences | `status` | What happens |
+|---|---|---|
+| 1 | `active` | Newly recorded. Default state. |
+| 2 | `watch` | Pattern is accumulating. `gotcha-hunter` surfaces as "one more triggers promotion". No rule drafted yet. |
+| 3 | `promotion-pending` | Auto-draft a proposed rule into frontmatter (see below). The next session-start surfaces this as a hard-interrupt. |
+| 4+ | stays `promotion-pending` | Until the user reviews (Step 6), additional occurrences keep bumping `occurrences` but `status` stays at `promotion-pending`. |
+
+**When occurrences hits 3 — draft the proposed rule (mechanical only):**
+
+1. Set frontmatter `status: promotion-pending`.
+2. Identify the target rule file from the **Promotion paths** table below.
+3. Draft a one-to-three-sentence actionable rule based on the `## Prevention` section. Keep it imperative ("must / never / always") so it reads as a rule, not a tip.
+4. Add a `proposed_rule:` block to the frontmatter:
+
+   ```yaml
+   proposed_rule:
+     rule_path: rules/common/{relevant-rule}.md
+     draft: |
+       {actionable rule statement}
+     drafted_at: YYYY-MM-DD
+   ```
+
+5. Surface to the user: "3rd occurrence of <title> recorded. Proposed rule drafted in frontmatter; awaiting review at next session start."
+
+Do not edit any rule file at this step. Drafting is mechanical; promotion is reviewed at Step 6.
+
+**Promotion paths:**
+
+| Current page | Promotion target | When |
+|---|---|---|
+| Project gotcha (`aiwiki/gotchas/`) | Same gotcha as global (`~/.claude/gotchas/`) | Same pattern seen in a different project |
+| Project gotcha at occurrences=3 | Project rule (`.claude/rules/<area>.md`) — typically a phase-conditional or always-on rule | 3× in same project |
+| Global gotcha at occurrences=3 | Common rule (`rules/common/<area>.md`) | 3× across projects |
+
+### Step 6: Session-start review of pending promotions
+
+When session-start surfaces a gotcha with `status: promotion-pending` (always carries a `proposed_rule:` block), do not start new work. Process each one:
+
+1. Read the gotcha's `## Prevention` section and the `proposed_rule.draft` value.
+2. Ask the user: approve, defer, or reject.
+
+**On approve:**
+- Append the `draft` rule text to the file at `proposed_rule.rule_path` (create the file if needed; match its existing list/heading style).
+- Invoke `support-skill-validator` against the modified rule file. If it reports a contradiction with existing rules, revert the rule-file edit and surface the contradiction. The user resolves the conflict and re-runs this step.
+- On validator pass: change the gotcha's frontmatter `status: promotion-pending` → `status: promoted-to-rule`. Remove the `proposed_rule:` block. Cross-reference the rule path under `## Prevention`.
+- Also update any other gotchas that share the same pattern with a `Promoted to rule: <rule_path>` line under `## Prevention`.
+
+**On defer:** Leave `status: promotion-pending` and the `proposed_rule:` block in frontmatter. Append a `defer:` field with the user's rationale and date. Next session-start surfaces it again.
+
+**On reject:** Change frontmatter `status: promotion-pending` → `status: rejected`. Remove the `proposed_rule:` block. Add a one-line note under `## Prevention`: "Proposed rule rejected ({date}): {reason}". The gotcha is retained as a recorded lesson, but session-start will not re-prompt and `gotcha-hunter` skips it at session-start scope.
+
+### Step 7: Retiring a gotcha
+
+When a gotcha no longer applies (framework upgrade made it impossible, code path was removed, library fixed the underlying issue):
+
+- Change frontmatter `status` → `status: retired` (regardless of prior state)
+- Add a one-line note under `## Prevention`: "Retired ({date}): {reason}"
+
+LINT preserves retired entries — they're still searchable history. `gotcha-hunter` skips retired entries when surfacing context to reviewers.
+
+## Severity classification
+
+| Severity | Criteria | Example |
+|---|---|---|
+| `critical` | Data loss, security breach, production outage | Migration deletes production data |
+| `high` | Significant time waste (1+ hour), incorrect behavior shipped | Subtle race condition in auth |
+| `medium` | Moderate time waste (15-60 min), development friction | Docker seed duplication |
+| `low` | Minor inconvenience, cosmetic, easily worked around | Wrong import path convention |
+
+## Status values (schema-canonical)
+
+The unified status vocabulary spans the auto-promotion path and manual retirement. Transitions are governed by `occurrences` (auto) and user review (manual). `gotcha-hunter` and `support-wiki-lint` both validate against this enum.
+
+| Status | Meaning | How entered |
+|---|---|---|
+| `active` | Newly recorded; `occurrences = 1`. Default state. | Step 4 writes a new gotcha. |
+| `watch` | `occurrences = 2`. Pattern is accumulating; one more occurrence triggers promotion drafting. | Step 3 bumps a 1× gotcha to 2×. |
+| `promotion-pending` | `occurrences = 3` (or more, until reviewed). A `proposed_rule:` block is attached. Awaits user review at next session-start. | Step 5 auto-drafts. |
+| `promoted-to-rule` | The proposed rule was approved and appended to a rule file. Gotcha retained as cross-referenced provenance. | Step 6 approve path. |
+| `rejected` | User reviewed a `promotion-pending` gotcha and declined promotion. Do not re-prompt. Lesson stays recorded; `gotcha-hunter` skips at session-start scope. | Step 6 reject path. |
+| `retired` | Gotcha no longer applies (framework upgrade, code path removed, library fixed). Kept for searchable history; `gotcha-hunter` skips. | Step 7 manual. |
+
+## Session-start integration
+
+A session-start hook scans `aiwiki/gotchas/INDEX.md` (and `~/.claude/gotchas/INDEX.md`) for rows whose `status` cell is `promotion-pending` and surfaces them as a hard-interrupt before new work begins. Step 6 is the gate between "draft rule" and "ship rule".
+
+When no pending promotions exist, `gotcha-hunter` (separate agent) reads `aiwiki/gotchas/` to surface diff-relevant entries to reviewers in the `quality-code-review` chain.
+
+## Red flags — record a gotcha
+
+| Situation | Why |
+|---|---|
+| "Oh, I've seen this before" | If you've seen it and it isn't recorded, it will happen again |
+| Fix took more than 3 attempts | The debugging path itself is worth recording |
+| Library behaved differently than documented | Future sessions will hit this too |
+| "Works on my machine" issues | Environment differences are always gotcha-worthy |
+| Skipped a process step and paid for it | Process-compliance lessons are valuable |
+| Found a workaround instead of a fix | Both the workaround and the underlying issue need documenting |
+| Deployment had unexpected complications | Deployment lessons prevent outages |
+| Test was flaky or timing-dependent | Document the pattern; flaky tests erode confidence |
+
+## Integration with other skills and agents
+
+| Skill / agent | Interaction |
+|---|---|
+| `support-debug` | Invokes this skill after a successful fix |
+| `deliver-db-migration` | Records migration-related lessons |
+| `deliver-deploy` | Records deployment-related lessons |
+| `deliver-onboarding` | Reads `aiwiki/gotchas/` to populate troubleshooting sections |
+| `support-skill-validator` | Validates promoted rules at the approve step (Step 6) |
+| `gotcha-hunter` (agent) | Reads `aiwiki/gotchas/` and surfaces diff-relevant entries to reviewers; never writes |
+| `support-wiki-lint` | Validates frontmatter + sections on every write |
+| `support-dream` | At phase-close / PreCompact: consolidates raw entries, may merge similar gotchas, prunes retired entries (writes proposals to `aiwiki/proposed/{dream_id}/` for user review) |
+| `/evolve` command | Reads gotchas to identify skill improvement opportunities |
+
+## Quick reference
+
+| Step | Action | Output |
+|---|---|---|
+| 1. Extract | What broke / root cause / prevention | Three-part lesson |
+| 2. Classify | Project or global? | Storage location chosen |
+| 3. Search | Existing matching gotcha? | Bump `occurrences` instead of writing duplicate |
+| 4. Write | Schema-aligned page with required frontmatter + 5 sections | `aiwiki/gotchas/{YYYY-MM-DD}-{slug}.md` (`status: active`) |
+| 5. Auto-promote | 1 → `active`; 2 → `watch`; 3 → `promotion-pending` + `proposed_rule:` block | Awaits session-start review |
+| 6. Session-start review | Approve / defer / reject the proposed rule | `promoted-to-rule`, deferred (stays `promotion-pending`), or `rejected` |
+| 7. Retire (when no longer applies) | Set `status: retired` | Kept as searchable history |

package/skills/support-runtime-reachability/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: support-runtime-reachability
+description: "Use to verify that every export in the slice diff has a production caller — the runtime-reach gate. Catches orphan exports (code defined but never reached at runtime) before the slice closes."
+---
+
+# Support: Runtime Reachability
+
+## Overview
+
+An export with no production caller is wiring debt: code that exists, passes its own tests against mocks, and ships unreached by production. Pattern review can't catch this — each file looks correct in isolation. This skill walks the slice diff, finds the exports it introduced, and proves each one is actually called.
+
+**Core principle:** wiring is reachability. If production never calls it, it doesn't exist.
+
+**Announce at start:** "I'm using the support-runtime-reachability skill to verify slice exports are wired."
+
+## When to Use
+
+- Per-slice gate after `build-tdd` completes — writes the `runtime-reach` gate result on the slice.
+- Before invoking `quality-code-review`'s pattern-conformance pass.
+- On-demand when investigating "code shipped but doesn't run".
+
+**Do NOT skip when:**
+- The slice "feels small" — the most common orphans are tiny (a hook, a route, a handler).
+- Tests pass — mocked tests prove behavior under test, not under production wiring.
+- A reviewer already approved the diff — pattern review and reachability are different bug classes.
+
+## Scope
+
+Catches **export-level orphans** in TS/JS and Python: a top-level `export` / `def` / `class` with no production call site and no escape-hatch annotation. Other failure classes are someone else's job:
+
+| Failure | Owner |
+|---|---|
+| No-op stubs (function called, body empty) | `craft-reviewer` Pass 2 |
+| Internal binding misses (handler not bound to JSX prop) | human review |
+| Method-on-object misses (`store.setUser` never called, where `store` is the export) | human review |
+| Behavioral completeness (caller exists, logic incomplete) | behavioral review |
+| Transitive runtime unreachability (caller exists, but its calling path is dead) | the `quality-test-execution` phase |
+
+Do not try to fold these into the runtime-reach result.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Slice diff file list, manifest path |
+| **Produces** | `runtime-reach` gate result (pass / fail with orphan list) |
+| **Feeds into** | `quality-code-review` (Pass 2 + reachability), slice-close gate |
+| **Updates manifest** | `slice_graph.slices.<id>.gates.runtime-reach.{status, gate-passed}` |
+
+## Process
+
+### Step 0: locate inputs
+
+Discover what the script needs before invoking it. Each input has a fallback if the primary source isn't available.
+
+| Input | How to find |
+|---|---|
+| Repo root | `git rev-parse --show-toplevel`, or `${CLAUDE_PROJECT_DIR}` if set. |
+| Manifest path | The single in-progress manifest under `.forge/work/*/*/manifest.yaml`. If multiple, ask the user which slice graph to validate against. |
+| Current slice id | `slice_graph.current_slice` field of that manifest. If the manifest has no `slice_graph` block, surface the gap and stop — this gate has nothing to attach its result to. |
+| Slice-parent ref | `slice_graph.slices.<current>.depends_on[0]`'s commit pointer if recorded; otherwise fall back to `origin/main`. If the repo has no `origin/main`, ask the user which ref to diff against. |
+| Script path | `<repo-root>/.claude/skills/support-runtime-reachability/scripts/check.mjs`. If missing, the skill isn't installed in this project — surface the gap. |
+
+### Step 1: collect slice diff files
+
+```bash
+git -C <repo-root> diff --name-only <slice-parent>...HEAD \
+  -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.mjs' '*.cjs' '*.py'
+```
+
+Skip deleted files. If the diff is empty (slice has no code changes), the gate passes trivially with `exports_found: 0`.
+
+### Step 2: invoke the check script
+
+```bash
+node "<repo-root>/.claude/skills/support-runtime-reachability/scripts/check.mjs" \
+  --files <comma-separated-paths-from-step-1> \
+  --root "<repo-root>"
+```
+
+Output: JSON to stdout, exit 0 on success and exit 2 on internal error. The `exports` array reports per-export production callers, test callers, and any escape-hatch annotation found.
+
+### Step 3: cross-check annotations against the manifest
+
+The script reports what it sees; you decide validity using the slice graph.
+
+**Decision rules:**
+
+| Script reports | Manifest cross-check | Verdict |
+|---|---|---|
+| `production_callers ≥ 1` | — | reachable |
+| `production_callers = 0`, `annotation = null` | — | **orphan** |
+| `annotation.kind = "untraceable"`, `value` non-empty | — | annotated, pass |
+| `annotation.kind = "untraceable"`, `value` empty/whitespace | — | **malformed annotation** |
+| `annotation.kind = "gated-pending"`, slice exists, status ∉ {complete} | — | annotated, pass |
+| `annotation.kind = "gated-pending"`, slice missing OR status `complete` | — | **stale annotation** |
+
+### Step 4: write the gate result
+
+| Outcome | Manifest write |
+|---|---|
+| All exports reachable or validly annotated | `gates.runtime-reach: { status: complete, gate-passed: true }` |
+| Any orphan / stale / malformed | `gates.runtime-reach: { status: complete, gate-passed: false }` |
+
+### Step 5: report
+
+If pass: one line — `runtime-reach: <N> exports checked, all wired.`
+
+If fail: structured report:
+
+```markdown
+## runtime-reach: FAILED (<N> findings)
+
+### Orphan exports
+1. `src/handlers/cases.ts:3` exports `casesRouter` (const)
+   Fix: wire it (e.g. `app.use('/cases', casesRouter)`), annotate `// gated-pending: <slice-id>`, or delete.
+
+### Stale gated-pending
+2. `src/future.ts:5` exports `futureHandler` annotated `// gated-pending: phase-2-wiring`,
+   but slice `phase-2-wiring` is `complete`. Wire it now.
+
+### Malformed untraceable
+3. `src/lazy.ts:2` exports `lazy` annotated `// untraceable:` with no rationale.
+```
+
+The user fixes; re-run.
+
+## Annotations
+
+Place on the line immediately preceding the export, or trailing on the same line:
+
+```ts
+// gated-pending: <slice-id>
+export function futureHandler() { ... }
+
+export const lateMount = ...; // gated-pending: phase-2-wiring
+```
+
+```python
+# gated-pending: phase-2-wiring
+def future_handler():
+    pass
+```
+
+| Annotation | Use when |
+|---|---|
+| `// gated-pending: <slice-id>` | Export is intentionally orphan in this slice; another (named, non-complete) slice will wire it. |
+| `// untraceable: <rationale>` | Export is consumed via mechanism the gate can't see: framework auto-discovery (Next.js routes), decorator mounts (NestJS, Spring), reflection-based loaders, defensive exports invoked only by upstream failures. |
+
+Use line comments (`//` for TS/JS, `#` for Python). Block comments and annotations separated from the export by blank lines, JSDoc, or decorators are not parsed — place the annotation immediately above.
+
+## When to Suspect a Finding
+
+When the script's verdict disagrees with what you can verify by reading the code, the cause is usually one of these. Each row's "signal" is something you can observe in the diff or a quick grep — no script-internals knowledge required.
+
+| Signal in the code | Likely cause | Fix |
+|---|---|---|
+| Script reports orphan, but you can grep a usage in a file that imports via `@/...`, `~/...`, or a non-relative path other than a known npm package | Path-aliased import — script can't resolve the alias to the export's file | Annotate `// untraceable: path-alias-consumer` |
+| Script reports orphan, but the only usage is inside an `import('./X')` call | Dynamic import not detected | Annotate `// untraceable: dynamic-import` |
+| Script reports orphan on a Next.js route, NestJS controller, Spring-annotated handler, or similar framework-mounted file | Framework auto-discovery — no explicit caller exists | Annotate `// untraceable: framework-mounted` |
+| Script reports orphan, but you can grep `export * from '<path-resolving-to-this-file>'` in a re-export module | Wildcard re-export not followed | Convert to a named re-export (`export { name } from ...`), or annotate |
+| Two source files in the diff both export the same identifier name | Same-name across modules — caller could be credited to the wrong export | Read the script output's `production_callers[].file` to confirm which export the call resolves to; restructure if needed |
+| Script reports a caller, but the caller file both imports `name` AND declares its own `const name = ...` / `function name(...)` | Local shadow — the call resolves to the local declaration, not the import | Rename the local; the script's name-based fallback can't distinguish shadows |
+
+The script's other constraints: regex (not AST); ESM only (no CommonJS `module.exports`); commented-out callers don't count (line comments are stripped).
+
+## Red Flags
+
+**Never:**
+- Add a no-op caller (`useless();`) to satisfy reachability — that's gaming, not wiring.
+- Annotate every orphan as `untraceable` to silence the gate. High annotation density signals architecture problems, not gate problems.
+- Suppress findings to make the slice look clean.
+
+**Always:**
+- Resolve orphans before closing the slice.
+- Re-run the script after every fix attempt.
+- Annotate genuine framework-mounted exports so the next reviewer doesn't relitigate.
+
+## Integration
+
+| Caller | When |
+|---|---|
+| `quality-code-review` | After Pass 1 safety and Pass 2 craft, before Codex adversarial cross-check. |
+| `/feature` and `/refactor` slice-close | Per-slice gate. |
+| Ad-hoc | When a reviewer suspects orphan code. |
+
+| Pairs with | For |
+|---|---|
+| `craft-reviewer` | Stubs the reachability gate accepts as called-but-empty. |
+| `verify-manifest` | Validates the slice graph this skill cross-references. |

package/skills/support-runtime-reachability/scripts/__fixtures__/case-01-passes-app-use/src/app.ts

@@ -0,0 +1,7 @@
+import express from 'express';
+import { casesRouter } from './handlers/cases';
+
+const app = express();
+app.use('/cases', casesRouter);
+
+export { app };

package/skills/support-runtime-reachability/scripts/__fixtures__/case-01-passes-app-use/src/handlers/cases.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+
+export const casesRouter = Router();
+
+casesRouter.get('/', (req, res) => {
+  res.json({ cases: [] });
+});

package/skills/support-runtime-reachability/scripts/__fixtures__/case-02-orphan-no-app-use/src/app.ts

@@ -0,0 +1,8 @@
+import express from 'express';
+// REACH-style failure: imported but never mounted.
+import { casesRouter } from './handlers/cases';
+
+const app = express();
+// app.use('/cases', casesRouter)  <-- forgotten
+
+export { app };

package/skills/support-runtime-reachability/scripts/__fixtures__/case-02-orphan-no-app-use/src/handlers/cases.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+
+export const casesRouter = Router();
+
+casesRouter.get('/', (req, res) => {
+  res.json({ cases: [] });
+});

package/skills/support-runtime-reachability/scripts/__fixtures__/case-03-orphan-import-only/src/App.tsx

@@ -0,0 +1,5 @@
+import { RingingBanner } from './components/RingingBanner';
+
+export function App() {
+  return <RingingBanner />;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-03-orphan-import-only/src/components/RingingBanner.tsx

@@ -0,0 +1,7 @@
+// REACH-style failure: hook imported but never invoked.
+import { useTwilioDevice } from '../hooks/useTwilio';
+
+export function RingingBanner() {
+  // useTwilioDevice() <-- forgotten
+  return <div>Incoming call</div>;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-03-orphan-import-only/src/hooks/useTwilio.ts

@@ -0,0 +1,6 @@
+export function useTwilioDevice() {
+  return {
+    accept: () => {},
+    reject: () => {},
+  };
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-04-jsx-component-rendered/src/App.tsx

@@ -0,0 +1,5 @@
+import { MyComp } from './components/MyComp';
+
+export function App() {
+  return <MyComp label="hello" />;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-04-jsx-component-rendered/src/components/MyComp.tsx

@@ -0,0 +1,3 @@
+export function MyComp({ label }: { label: string }) {
+  return <span>{label}</span>;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-05-jsx-component-not-rendered/src/App.tsx

@@ -0,0 +1,3 @@
+export function App() {
+  return <div>Hello</div>;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-05-jsx-component-not-rendered/src/components/Orphan.tsx

@@ -0,0 +1,3 @@
+export function Orphan() {
+  return <div>I'm not rendered anywhere</div>;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-06-class-instantiated/src/lib/Service.ts

@@ -0,0 +1,6 @@
+export class Service {
+  constructor(public name: string) {}
+  greet() {
+    return `hello from ${this.name}`;
+  }
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-06-class-instantiated/src/main.ts

@@ -0,0 +1,4 @@
+import { Service } from './lib/Service';
+
+const svc = new Service('alpha');
+console.log(svc.greet());

package/skills/support-runtime-reachability/scripts/__fixtures__/case-07-class-not-instantiated/src/lib/Lonely.ts

@@ -0,0 +1,5 @@
+export class Lonely {
+  greet() {
+    return 'no one calls me';
+  }
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-07-class-not-instantiated/src/main.ts

@@ -0,0 +1,2 @@
+// Lonely is exported but never instantiated.
+console.log('main runs without using Lonely');

package/skills/support-runtime-reachability/scripts/__fixtures__/case-08-default-export-imported-and-called/src/handler.ts

@@ -0,0 +1,3 @@
+export default function handler(req: { id: string }) {
+  return { ok: true, id: req.id };
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-08-default-export-imported-and-called/src/main.ts

@@ -0,0 +1,3 @@
+import handle from './handler';
+
+handle({ id: '42' });

package/skills/support-runtime-reachability/scripts/__fixtures__/case-09-default-export-orphan/src/handler.ts

@@ -0,0 +1,3 @@
+export default function handler(req: { id: string }) {
+  return { ok: true, id: req.id };
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-09-default-export-orphan/src/main.ts

@@ -0,0 +1,2 @@
+// Default export from handler.ts is never imported.
+console.log('main runs');

package/skills/support-runtime-reachability/scripts/__fixtures__/case-10-aliased-named-export/src/lib.ts

@@ -0,0 +1,5 @@
+function foo() {
+  return 'foo';
+}
+
+export { foo as bar };

package/skills/support-runtime-reachability/scripts/__fixtures__/case-10-aliased-named-export/src/main.ts

@@ -0,0 +1,3 @@
+import { bar } from './lib';
+
+console.log(bar());

package/skills/support-runtime-reachability/scripts/__fixtures__/case-11-re-export-chain/src/lib/index.ts

@@ -0,0 +1 @@
+export { doStuff } from './internal';

package/skills/support-runtime-reachability/scripts/__fixtures__/case-11-re-export-chain/src/lib/internal.ts

@@ -0,0 +1,3 @@
+export function doStuff(value: number) {
+  return value * 2;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-11-re-export-chain/src/main.ts

@@ -0,0 +1,3 @@
+import { doStuff } from './lib';
+
+console.log(doStuff(21));

package/skills/support-runtime-reachability/scripts/__fixtures__/case-12-test-only-caller/src/util.test.ts

@@ -0,0 +1,5 @@
+import { helperOnly } from './util';
+
+test('helperOnly increments', () => {
+  if (helperOnly(1) !== 2) throw new Error('fail');
+});

package/skills/support-runtime-reachability/scripts/__fixtures__/case-12-test-only-caller/src/util.ts

@@ -0,0 +1,3 @@
+export function helperOnly(n: number) {
+  return n + 1;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-13-gated-pending-annotation/src/future.ts

@@ -0,0 +1,4 @@
+// gated-pending: phase-2-wiring
+export function futureHandler() {
+  return { ok: true };
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-14-untraceable-annotation/src/decorated.ts

@@ -0,0 +1,4 @@
+// untraceable: framework-mounted (Next.js app router)
+export default function GET(req: Request) {
+  return new Response('ok');
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-15-untraceable-empty/src/lazy.ts

@@ -0,0 +1,4 @@
+// untraceable:
+export function lazy() {
+  return 1;
+}

package/skills/support-runtime-reachability/scripts/__fixtures__/case-16-python-module/src/lib.py

@@ -0,0 +1,15 @@
+def public_fn(value):
+    return value + 1
+
+
+def _private_helper(value):
+    return value * 2
+
+
+class PublicClass:
+    def __init__(self, name):
+        self.name = name
+
+
+class _PrivateClass:
+    pass

package/skills/support-runtime-reachability/scripts/__fixtures__/case-16-python-module/src/main.py

@@ -0,0 +1,5 @@
+from .lib import public_fn
+
+# PublicClass is exported but never instantiated -> orphan.
+
+print(public_fn(41))