@renzrollon/interlock 1.0.0

package/skills/explain-code/module-walkthrough.md

@@ -0,0 +1,358 @@
+# Module walkthrough — explain-code
+
+Teach TypeScript/React/Next.js code to a frontend beginner. Not reviewing — teaching.
+
+## Scope
+
+**Ecosystems covered:**
+- TypeScript (strict mode, generics, utility types, Zod, discriminated unions)
+- React 19 (hooks, components, context, refs, suspense, error boundaries)
+- Next.js 15 App Router (server components, client components, server actions, route handlers, middleware, layouts, streaming)
+- Related dependencies: Prisma ORM, Zustand, Radix UI, Tailwind CSS, better-auth, class-variance-authority
+
+**Infrastructure & cloud services — always include when called:**
+- PostgreSQL (via Prisma)
+- AWS S3 (file storage/retrieval)
+- AWS SQS (message queues)
+- Any HTTP/REST calls to external services
+- Authentication services (better-auth sessions)
+
+**Context sources:**
+- If `.claude/graph/DOCS_DIGEST.md` exists, Read it once as the domain primer (agent-only; see `/interlock:docs-digest`)
+- Then use `interlock-graph context "<scope terms>" --budget 2000` for task-specific prose — do **not** read all of `docs/` upfront (see `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md` Rule 0.5)
+- If graph missing: `interlock-graph docs "<terms>" --budget 800`, or grep headings in `docs/` then Read spans
+
+**Files to explain:**
+- **Module walkthrough:** every `.ts` / `.tsx` in the scoped tree (`src/`, `app/`, `lib/`, …)
+- **Commit teach-in:** every source file touched in the commit range (skip binaries/lockfiles; cap ~25)
+
+**Skip:**
+- Test files (`*.test.ts`, `*.test.tsx`, `__tests__/`) — unless they are the only files in a commit teach-in and the user asked about them
+- `node_modules/`, generated files, config files outside source trees
+- Boilerplate: import statements, simple variable declarations, trivial type aliases, basic for loops
+
+**This mode:** every `.ts` / `.tsx` in the scoped tree (`src/`, `app/`, `lib/`, …).
+
+## Steps
+
+1. Retrieve domain context on demand — Read `.claude/graph/DOCS_DIGEST.md` if present; then `interlock-graph context "<scope>" --budget 2000` (or `docs` with `--budget 800` if no graph). Do not preload every `docs/*.md`.
+2. If `$ARGUMENTS` specifies a directory or file, explain only that scope; pass paths to `--changed` when using `context`.
+3. If no arguments, use the graph to list modules/files in `app/`, `lib/`, `components/`, `types/`, and `prisma/` instead of blind `find`.
+4. Graph-backed scope and call links: if `.claude/graph/graph.json` exists, use `interlock-graph explain <file>` and `interlock-graph consumers <symbol>` for **Called by** / **Calls into**. If missing and scope is large, `interlock-graph build .` once first.
+5. Read each in-scope file; extract functions and logic blocks worth explaining (Read with offset/limit when locating via graph/grep).
+6. Trace imports only where the graph is incomplete.
+7. Order output: foundational files → data layer → components → pages/routes.
+8. Build flow diagrams last; write to the output path resolved in `SKILL.md` — `docs/CODE_EXPLANATION.md` for an ad-hoc walkthrough, or `openspec/changes/<change-name>/code-explanation.md` when the walkthrough is scoped to an OpenSpec change.
+
+## Per-file structure
+
+### File Header (module walkthrough)
+
+```markdown
+## `src/path/to/file.ts`
+
+**Role:** [one sentence — what this file's job is in the app]
+**Called by:** [files that import from this one]
+**Calls into:** [files this one imports, excluding node_modules]
+**Infra/services touched:** [PostgreSQL, S3, SQS, external APIs — or "None"]
+```
+
+### Function/Block Breakdown
+
+For each exported function, named function, or significant logic block:
+
+```markdown
+### `functionName(params)` → returnType
+
+**What it does:** [1-2 sentences in plain language]
+
+**How it works:**
+- [Step-by-step walkthrough of the logic, skipping boilerplate]
+- [Highlight conditionals, transformations, and side effects]
+
+**Cross-file calls:**
+- `helperFunction()` from `src/lib/helpers.ts` — [why it's called here]
+- `prisma.user.findMany()` → PostgreSQL — [what data it fetches]
+- `s3Client.send(PutObjectCommand)` → AWS S3 — [what it uploads and when]
+
+**Pattern:** [Name the pattern if one applies]
+```
+
+## API & Data Flows (Required for route handlers and server actions)
+
+### Route Handler Flow
+
+```markdown
+### API Flow: `POST /api/v1/batches`
+
+**Request:**
+- Method: POST
+- Body: `{ name: string, type: "BILLING" | "ACCRUAL", groupId: string }`
+- Auth: Session cookie (better-auth)
+- Headers: `Content-Type: application/json`
+
+**Processing:**
+1. Authenticate → `auth.api.getSession()` → checks session cookie
+2. Authorize → `makeAuthorizationChecker()` → verifies user belongs to group
+3. Validate → Zod schema `CreateBatchSchema` → rejects malformed input
+4. Execute → `prisma.batch.create()` → **PostgreSQL** INSERT
+5. Side effect → `sendToQueue()` → **AWS SQS** sends processing message
+6. Respond → return created batch with 201
+
+**Response:**
+- 201: `{ id, name, type, status, createdAt }`
+- 400: `{ error: "Validation failed", details: [...] }`
+- 401: `{ error: "Unauthorized" }`
+- 403: `{ error: "Forbidden" }`
+
+**Flow diagram:**
+```
+Browser (fetch POST)
+  → Next.js Route Handler (src/app/api/v1/batches/route.ts)
+    → better-auth session check
+    → Zod validation
+    → Prisma ORM
+      → [PostgreSQL] INSERT INTO batches
+    → SQS client
+      → [AWS SQS] SendMessage to processing queue
+  ← 201 JSON response
+← UI updates with new batch
+```
+```
+
+### Server Action Flow
+
+```markdown
+### Server Action: `submitBatch(batchId)`
+
+**Trigger:** Called from `SubmitButton` component via form action or onClick
+**Input:** `batchId: string`
+**Output:** `ActionResponse<{ batch: Batch }>` — `{ data }` or `{ error }`
+
+**Flow:**
+1. Client component calls `submitBatch(id)` — crosses network boundary
+2. `'use server'` — executes on the server process, not the browser
+3. `auth.api.getSession()` → validates session cookie
+4. `makeAuthorizationChecker()` → checks SUBMIT permission on this batch
+5. `prisma.batch.findUnique()` → **PostgreSQL** SELECT — verifies batch is DRAFT
+6. `prisma.batch.update({ status: 'SUBMITTED' })` → **PostgreSQL** UPDATE
+7. `sendToQueue(batch)` → **AWS SQS** — triggers async processing pipeline
+8. Returns `{ data: { batch } }` to client component
+9. Client re-renders with updated batch status
+
+**Infra calls and when they happen:**
+| Step | Service | Operation | Trigger condition |
+|------|---------|-----------|-------------------|
+| 3 | better-auth | Session lookup | Every call (authentication) |
+| 5 | PostgreSQL | SELECT batch | After auth passes |
+| 6 | PostgreSQL | UPDATE status | Only if batch is DRAFT |
+| 7 | AWS SQS | SendMessage | Only after successful UPDATE |
+
+**Error scenarios:**
+- No session → returns `{ error: { message: "Unauthorized" } }`
+- No permission → returns `{ error: { message: "Forbidden" } }`
+- Batch not DRAFT → returns `{ error: { message: "Batch already submitted" } }`
+- DB failure → caught by try/catch, logged via `logError()`, returns generic error
+```
+
+---
+
+## Infrastructure & Cloud Service Documentation
+
+Whenever a file interacts with an external service, document:
+
+```markdown
+### Infrastructure Call: `uploadToS3(file, key)`
+
+**Service:** AWS S3
+**SDK:** `@aws-sdk/client-s3` → `S3Client` + `PutObjectCommand`
+**When called:** User uploads a file via the batch item form
+**How called:**
+  - Client: form submission → server action `uploadFile()`
+  - Server: validates file type/size → generates S3 key → calls `s3Client.send()`
+**Configuration:** Bucket name from `process.env.S3_BUCKET`, region from `AWS_REGION`
+**What flows in:** File buffer + content type + generated key path
+**What flows out:** S3 URL (constructed from bucket + key)
+**Error handling:** Wrapped in try/catch → logs error → returns `{ error }` to client
+```
+
+Document these services whenever they appear:
+
+| Service | Look for | What to document |
+|---------|----------|------------------|
+| PostgreSQL | `prisma.*` calls | Which model, which operation (SELECT/INSERT/UPDATE/DELETE), what data |
+| AWS S3 | `s3Client`, `PutObjectCommand`, `GetObjectCommand` | Upload/download, bucket, key pattern, when triggered |
+| AWS SQS | `sqsClient`, `SendMessageCommand` | Queue name, message shape, what triggers the send |
+| External HTTP | `fetch()` to external URLs | URL pattern, method, request/response shape |
+| better-auth | `auth.api.*` | Which auth operation, what it returns, session shape |
+
+---
+
+## Design Patterns to Detect and Explain
+
+### TypeScript Patterns
+| Pattern | What to look for | Why it matters |
+|---------|-----------------|----------------|
+| Discriminated Unions | `type Result = { ok: true; data: T } \| { ok: false; error: E }` | Type-safe branching without runtime checks |
+| Type Guards | `function isX(val): val is X` | Narrows types so TS trusts your logic |
+| Generics | `function fetch<T>(url): Promise<T>` | One function works with any type safely |
+| Zod Schema Inference | `z.infer<typeof Schema>` | Single source of truth for runtime + compile-time types |
+| Utility Types | `Partial<T>`, `Pick<T, K>`, `Omit<T, K>` | Transform types without rewriting them |
+| Const Assertions | `as const` | Locks values to their literal types |
+| Branded Types | `type Id = string & { __brand: 'Id' }` | Prevents mixing up IDs that are all strings |
+
+### React Patterns
+| Pattern | What to look for | Why it matters |
+|---------|-----------------|----------------|
+| Custom Hooks | `function useX()` | Reusable stateful logic extracted from components |
+| Provider Pattern | Context + `useX()` hook | Dependency injection without prop drilling |
+| Compound Components | Related components sharing implicit state | Flexible API for complex UI (like Radix) |
+| Controlled Components | State owned by parent, passed via props | Predictable form behavior |
+| Composition | Small components assembled via children/slots | Flexible, testable, reusable UI |
+| Optimistic Updates | Update UI before server confirms | Feels instant to the user |
+| Memoization | `useMemo`, `useCallback`, `React.memo` | Avoids expensive re-renders |
+| Ref Forwarding | `forwardRef` | Lets parent access child's DOM node |
+| Error Boundaries | Class component with `getDerivedStateFromError` | Catches render crashes gracefully |
+
+### Next.js App Router Patterns
+| Pattern | What to look for | Why it matters |
+|---------|-----------------|----------------|
+| Server Components | No `'use client'`, no hooks, no browser APIs | Zero JS shipped to client, fast initial load |
+| Client Components | `'use client'` at top | Interactive, stateful, has access to browser |
+| Server Actions | `'use server'` functions | Server-side mutations callable directly from client |
+| Route Handlers | `route.ts` with `GET`/`POST`/etc exports | API endpoints within App Router |
+| Layout Nesting | `layout.tsx` wrapping child routes | Persistent UI across navigation |
+| Loading Convention | `loading.tsx` | Automatic Suspense boundary per route segment |
+| Error Convention | `error.tsx` | Automatic error boundary per route segment |
+| Middleware | `middleware.ts` at project root | Request interception (auth, redirects, headers) |
+| Streaming | `<Suspense>` wrapping async server components | Progressive rendering — show what's ready |
+| Metadata API | `export const metadata` or `generateMetadata()` | Per-route SEO and head management |
+
+### Architectural Patterns
+| Pattern | What to look for | Why it matters |
+|---------|-----------------|----------------|
+| Repository | Functions in `lib/db.ts` abstracting Prisma | Swap DB without touching business logic |
+| Singleton | Single `prisma` or `auth` instance exported | One connection pool, not one per request |
+| Adapter | Wrappers around S3/SQS SDK calls | Consistent interface; easy to mock/swap |
+| Middleware/Pipeline | Chained checks (auth → authz → validate → execute) | Each step has one job; easy to reorder |
+| Factory | Functions returning configured objects | Encapsulate complex creation logic |
+| Strategy | Behavior varies by parameter/config | Same interface, different implementations |
+
+## Important Scenarios to Cover
+
+For each file, identify and explain the scenarios that matter:
+
+- **Happy path** — normal successful flow from trigger to result
+- **Error propagation** — where errors are caught, how they travel back to the UI
+- **Edge cases** — empty arrays, null values, missing env vars, expired sessions
+- **State transitions** — DRAFT → SUBMITTED → APPROVED (explain the state machine)
+- **Permission gates** — who can call this, what roles/groups are checked
+- **Async behavior** — loading states, what happens during the await, cleanup on unmount
+- **Infra failure** — what if S3 is down? What if SQS rejects? What if DB times out?
+
+## Output Format
+
+### Module walkthrough
+
+```markdown
+# Code Explanation: [directory or feature area]
+
+## Overview
+[2-3 sentences: what this area of the codebase does, in plain language]
+
+## Tech & Services Involved
+| Layer | Technology | Role |
+|-------|-----------|------|
+| Frontend | React 19 + Next.js 15 | UI rendering, routing, server components |
+| State | Zustand | Client-side state management |
+| Validation | Zod | Runtime type checking |
+| Database | Prisma + PostgreSQL | Data persistence |
+| Storage | AWS S3 | File uploads |
+| Queue | AWS SQS | Async processing |
+| Auth | better-auth | Session management |
+
+## File Map
+[Simple tree showing which files exist and their one-line role]
+
+---
+
+## `src/path/to/file.ts`
+
+**Role:** ...
+**Called by:** ...
+**Calls into:** ...
+**Infra/services touched:** ...
+
+### `functionName(params)` → returnType
+[explanation]
+
+### Patterns Used
+- **Pattern Name:** one-line explanation of why it's used here
+
+---
+
+[...repeat for each file...]
+
+---
+
+## Full Data Flow Diagram
+
+```
+User clicks "Submit Batch"
+  → SubmitButton (client component, src/app/.../components/SubmitButton.tsx)
+    → submitBatch(batchId) — server action (src/app/.../actions.ts)
+      → [better-auth] session validation
+      → [PostgreSQL] SELECT batch WHERE id = ?
+      → [PostgreSQL] UPDATE batch SET status = 'SUBMITTED'
+      → [AWS SQS] SendMessage { batchId, action: 'process' }
+    ← { data: { batch: { ...updatedBatch } } }
+  ← Re-render with new status badge showing "SUBMITTED"
+
+Meanwhile, async:
+  [AWS SQS] → Processing Worker (separate service)
+    → [PostgreSQL] UPDATE batch SET status = 'PROCESSING'
+    → validate each batch item
+    → [PostgreSQL] UPDATE batch SET status = 'APPROVED' or 'REJECTED'
+```
+
+## Key Patterns Summary
+
+| Pattern | Where Used | Why |
+|---------|-----------|-----|
+| Server Action | `actions.ts` | Secure server-side mutations callable from client |
+| Discriminated Union | `ActionResponse<T>` | Type-safe success/error without exceptions |
+| Singleton | `src/lib/prisma.ts` | One DB connection pool for the whole app |
+| Adapter | `src/lib/s3.ts`, `src/lib/sqs.ts` | Wrap AWS SDK behind simple functions |
+| ... | ... | ... |
+
+## Concepts You Learned
+[Bulleted list of every concept explained, with one-line definition — becomes a reference card]
+```
+
+## Tone & Style
+
+## Tone & Style
+
+- **Friendly, encouraging, zero condescension** — "we" language, like a senior sitting next to you
+- **Skip the obvious** — don't explain what `const x = 5` does
+- **Explain the non-obvious** — why this pattern? why server vs client? why does this call SQS here?
+- **Name every external service call** — never skip an infra interaction, these are critical for understanding the system
+- **Use analogies** — "Think of SQS like a to-do list for a background worker — we drop a note saying 'process this batch', and a separate service picks it up later"
+- **Show the full journey** — from user action → through the code → to the database/service → back to the UI
+- **Keep it scannable** — headers, bullet points, tables, code blocks. No walls of text.
+
+---
+
+## What NOT to Do
+
+- Don't review or critique the code
+- Don't suggest improvements (unless asked)
+- Don't explain import statements, simple variable declarations, or trivial types
+- Don't explain test files
+- Don't use jargon without defining it on first use
+- Don't be condescending ("as you probably know" / "this is simple")
+- Don't explain node_modules or third-party library internals (just say what the library does)
+- Don't skip infrastructure calls — every DB query, S3 operation, SQS message, and auth check must appear in the flow
+- Don't use subagents or workflows — this skill requires sequential understanding across files
+- In commit teach-in, don't skip Change Context fields — every changed source file needs Why / What / Blast radius / If left out
+- Don't invent blast-radius callers or breakage modes not evidenced by the diff or reference search

package/skills/explore/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: explore
+description: Deep codebase reconnaissance with parallel read-only investigators — fans out automatically when a question spans multiple subsystems, options, or cross-cutting concerns, then synthesizes one coherent picture. Use before designing a change, when tracing how something works end to end, or when you need to know the blast radius of touching a shared value.
+license: MIT
+compatibility: Optional openspec CLI for change awareness. Node.js >= 18 for the bundled interlock-graph CLI.
+argument-hint: "[question] [--autonomous]"
+allowed-tools: Bash(interlock-graph *) Bash(openspec *) Agent Read Grep Glob
+metadata:
+  type: discovery
+  outputs:
+    - .claude/handoff/explore-<slug>-<timestamp>.md
+    - openspec/changes/<name>/decisions.md
+---
+
+Think deeply. Fan out when breadth is needed. Synthesize into understanding.
+
+**Explore is for thinking, not implementing.** Read files, search code, investigate freely — but never write code and never implement a feature here. If asked to implement, say so and point at `/interlock:spec`. Writing OpenSpec artifacts or an explore brief is capturing thinking, not implementing, and is allowed.
+
+---
+
+## Two modes
+
+**Conversational (default).** A thinking partner. Ask the user which thread to pull when several look interesting. Iterate.
+
+**Autonomous.** Activate on `--autonomous`, "no questions", "don't ask me", "pursue all threads", or when `/interlock:spec` invokes this skill. Then:
+
+1. **No user Q&A.** No AskUserQuestion, no "which thread interests you?" menus. Open threads are work items, not questions.
+2. **Fan out on every thread.** Each interesting thread or option gets a read-only investigator. Cap 2–5, merge in synthesis.
+3. **Prefer defaults.** Ambiguous product intent → pick a reasonable default, record it under Assumptions Made and Pending Clarifications. Non-blocking. Every one of them is also a ledger row — see below.
+4. **Write the explore brief.** Required exit criterion. Follow `${CLAUDE_PLUGIN_ROOT}/shared/EXPLORE-BRIEF.md`. Path: `.claude/handoff/explore-<slug>-<YYYYMMDD-HHMMSS>.md`.
+5. **Close short.** Brief path plus a 3–5 line summary. Do not re-dump findings into chat — they are in the brief.
+
+---
+
+## Graph-first reconnaissance, before any fan-out
+
+Follow Rule 0 of `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md`. If the graph exists, seed scopes then fan out:
+
+```bash
+interlock-graph query "<subsystem tokens>" --budget 1500
+interlock-graph consumers <symbol-or-field>
+interlock-graph path <A> <B>
+```
+
+Scope investigators by real module nodes and consumer lists. Each investigator: graph, then grep for string-keyed and dynamic readers, then Read spans. If the graph is missing and the question spans 3+ subsystems, build it once (`interlock-graph build .`). Never rebuild when it already exists.
+
+---
+
+## When to fan out
+
+**Fan out** when the question shows any of these:
+
+| Signal | Example |
+|--------|---------|
+| Multiple subsystems touched | "How does deployment work end to end?" |
+| Comparative analysis needed | "Redis or SQLite for this?" |
+| Cross-file tracing required | "What validates the uploaded archive?" |
+| Several options to research | "What are our options for real-time?" |
+| Architecture mapping | "Map how auth flows through the system" |
+
+**Mandatory fan-out — shared or derived value changes.** If the change alters what a value *means* or who reads it, run Pattern 4 per `${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md`. This overrides the single-threaded default.
+
+**Stay single-threaded** for conversational back-and-forth, single-file questions, quick clarifications, sequential discovery where A informs B, or when the user is thinking out loud.
+
+When genuinely unsure, start single-threaded and escalate once you realize the question is broader than it looked.
+
+---
+
+## The four patterns
+
+**Pattern 1 — Subsystem mapping.** The question spans several parts of the system. One investigator per stage of the flow. Synthesize into a diagram plus narrative.
+
+**Pattern 2 — Option comparison.** Several viable approaches. One investigator per option, each reporting fit against *this* codebase, not generic pros and cons. Synthesize into a comparison table plus a recommendation.
+
+**Pattern 3 — Layer sweep.** "Where does X happen?" when X could happen at several layers. One investigator per layer (client, API, business logic, persistence, post-processing). Synthesize into what each layer catches and where the gaps are.
+
+**Pattern 4 — Impact analysis.** A change would alter what a value means or who reads it. One investigator per **disjoint** layer of the blast radius. Synthesize into an impact map with severity per area, and explicitly flag readers still consuming the raw, untransformed form.
+
+---
+
+## Investigator rules
+
+1. **Focused prompts.** Not "explore everything about X" — "trace the exact flow of Y through files A, B, C".
+2. **Read-only.** Investigators search, read, and report. They never write.
+3. **Structured returns.** JSON only (schema below). No narrative dump.
+4. **2–5 agents.** Fewer than 2 is not a fan-out; more than 5 means the decomposition is too granular.
+5. **Disjoint scopes.** Non-overlapping assignments so findings merge cleanly. For Pattern 4 this is load-bearing: partition the search space so no reader is missed or double-counted.
+6. **Label clearly** so progress is visible.
+7. **Use `subagent_type: "Explore"`** for read-only investigation.
+8. **Context hygiene.** Wrap user-supplied values per `${CLAUDE_PLUGIN_ROOT}/shared/CONTEXT-HYGIENE.md` before echoing them into a subagent prompt.
+9. **Locate before Read** — graph, then grep, then Read spans.
+
+### Prompt template
+
+```
+Investigate: [[SPECIFIC_QUESTION]]
+
+Context: [[BROADER_TOPIC]]
+
+Look for:
+- [specific thing 1]
+- [specific thing 2]
+
+Return JSON only:
+{ "files": [{ "path": "", "lines": "" }], "how": "", "connections": [], "gaps": [] }
+```
+
+Resolve `[[SPECIFIC_QUESTION]]` and `[[BROADER_TOPIC]]` from session state at emit time. **An unresolved placeholder halts the fan-out — never gap-fill one.**
+
+---
+
+## Synthesis
+
+After investigators return, you **must** synthesize. Never dump raw agent output.
+
+1. **Merge overlapping findings** — agents often reach the same file from different angles.
+2. **Build one unified picture** — a diagram where structure matters.
+3. **Name the gaps** — what did no agent find? What is still unclear?
+4. **Surface contradictions** — when two agents disagree, say so; do not silently pick one.
+5. **Run a completeness check.** Before closing, ask what is missing: a layer not swept, a reader not checked, an option not costed. **For Pattern 4 this is mandatory** — if any layer of the blast radius went uncovered, say so outright. A silent gap reads as "we covered everything" when you didn't.
+6. **Offer direction.** What is worth exploring next? In autonomous mode, pursue it or record it in the brief rather than asking.
+
+The result should read like a senior engineer who just debriefed four specialists — not like four reports stapled together.
+
+---
+
+## OpenSpec awareness
+
+```bash
+openspec list --json          # is there an active change?
+```
+
+When a change exists, read its artifacts via `openspec status --change "<name>" --json` for context, and offer to capture decisions as they crystallize:
+
+| Insight | Captured in |
+|---|---|
+| New or changed requirement | `specs/<capability>/spec.md` |
+| Design decision | `design.md` |
+| Scope change | `proposal.md` |
+
+---
+
+## Every ambiguity becomes a ledger row
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/DECISION-LEDGER.md`. Do not restate its format.
+
+- `## Pending Clarifications` → `needs_human` rows.
+- `## Assumptions Made` → `agent_resolved` rows with followable evidence (`obvious` is not evidence).
+- Never only chat — a conversational answer still gets a row citing the human.
+
+Active change → write `openspec/changes/<change>/decisions.md` now and run `interlock ledger <change>`. No change yet → number them `D1`, `D2`, … in the brief (class stated) so `/interlock:spec` transcribes them. Never renumber; never reuse an id.
+
+---
+
+## Exit
+
+Conversational mode ends when the user has what they need.
+
+Autonomous mode ends by writing the explore brief and reporting its path — the brief is what `/interlock:spec` reads instead of re-deriving discovery. Writing it is how explore pays forward.

package/skills/fix-tests/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: fix-tests
+description: Discover and persist how a project's tests run, then run the suite and repair failures by root cause — clustering failures by error signature, fixing the shared cause once, and asserting no test was weakened. Use when tests are failing, the suite is red, CI pasted a failure log, or someone asks to make the tests pass.
+license: MIT
+compatibility: Requires the project's own test tooling. Node.js >= 18 for the bundled interlock CLI.
+argument-hint: "[--e2e] [--dry-run] [--baseline <ref>] [--from-log <path>] [--reconfigure]"
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  type: execution
+  outputs:
+    - .claude/testing/profile.json
+    - .claude/metrics/fix-tests-<timestamp>.json
+---
+
+Make the suite green **without making it weaker**.
+
+The failure mode this skill exists to prevent is the one where a suite goes green by shrinking — a deleted assertion, a `.skip`, a narrowed glob, a loosened matcher. That is not a fix; it is the bug plus a lie. Every step below is built around detecting it.
+
+| Flag | Effect |
+|------|--------|
+| `--e2e` | Also run the e2e suite (only when `e2e.command` is configured) |
+| `--dry-run` | Diagnose and propose; edit nothing |
+| `--baseline <ref>` | Treat failures already present at `<ref>` as pre-existing |
+| `--from-log <path>` | Parse a pasted CI log instead of running the suite first |
+| `--reconfigure` | Re-run test discovery from scratch |
+
+---
+
+## 1. Resolve the test profile
+
+Read `.claude/testing/profile.json`. If it is missing or `--reconfigure` was passed, run the discovery ladder in `${CLAUDE_PLUGIN_ROOT}/shared/TEST-PROFILE.md`: manifests, then runner configs, then CI workflows, then **at most four questions** for gaps that genuinely block a correct run.
+
+Resolve `typecheck.command` and `lint.command` on the same pass, the way `coverage.command` is resolved: the profile's own value first, then `package.json` `scripts.typecheck` / `scripts["type-check"]` and `scripts.lint`, then the step in the CI job that runs it. Never ask for either and never invent one — nothing found is `command: null`, which a ship run skips with a stated reason. A ship run's inter-wave checkpoint has no typecheck to run unless this field is filled, and a typecheck failure is a halting kind there.
+
+This is the only skill permitted to interview the user about tests. Every later run is zero-question.
+
+Persist the profile and mirror it into the `## Testing` block in `CLAUDE.md` (or `AGENTS.md`), between the managed markers, idempotently.
+
+---
+
+## 2. Run and baseline
+
+Run the unit command. Record `total`, `passed`, `failed`, `skipped` — this is the baseline that step 6 asserts against.
+
+Split failures into:
+
+- **Newly broken** — not failing at `--baseline <ref>` (or all failures when no baseline was given)
+- **Pre-existing** — already failing at the baseline. **Report only.** Do not absorb them into this fix unless the user explicitly widens scope.
+
+---
+
+## 3. Flake check
+
+Re-run **only** the failing files or test names, once, using `single_file` / `filter_syntax`.
+
+- Still failing → a real failure; continue.
+- Passed on re-run → record it in `profile.known_flaky` and **do not "fix" it**. Mention it in the report. A test that passes on retry is a flaky test, and "fixing" it usually means deleting the thing that caught a race.
+
+---
+
+## 4. Cluster by error signature
+
+| Signature | Example | Likely shared root cause |
+|---|---|---|
+| Same missing import | `Cannot find module './utils'` | Missing export or wrong path |
+| Same type error | `Type 'X' not assignable to 'Y'` | Interface shape mismatch |
+| Same fixture or setup | `ReferenceError: db is not defined` | Missing shared setup |
+| Same env or config | `ECONNREFUSED`, `env.X is undefined` | Missing env or config |
+| Same assertion pattern | Many `expected X received Y` | Logic bug in shared code |
+
+With `--from-log`, parse the log into the same clusters without an initial run — but still record a live baseline before applying any fix.
+
+---
+
+## 5. Fix by root cause
+
+```
+iterations = 0, MAX = 5
+
+WHILE failures remain AND iterations < MAX AND NOT --dry-run:
+  1. Pick the cluster covering the MOST failures
+  2. Choose ONE fix — source first
+  3. Apply it
+  4. Re-run ONLY the affected tests
+  5. Drop resolved failures; iterations++
+```
+
+**Source first.** When a test and the code disagree, the default assumption is that the code is wrong. Change the test only when you can state why the test's expectation was incorrect — and say that out loud in the report.
+
+**Never**: delete a test, add `.skip`/`.only`, loosen an assertion to match observed output, narrow a glob, raise a timeout to hide a race, or catch-and-ignore an error to make a run pass.
+
+`--dry-run` stops after clustering: print the diagnoses and proposed fixes, edit nothing.
+
+After 5 iterations, stop and report the unresolved clusters and what was tried. Do not thrash.
+
+---
+
+## 6. Full re-run and no-regression assert
+
+Run the full suite again, then assert against the baseline:
+
+- `total >= baseline.total`
+- `skipped <= baseline.skipped`
+
+**If either assert fails, revert the weakening change** — something deleted tests or added skips. A green suite that runs fewer tests than it did before is a regression wearing a green badge.
+
+---
+
+## 7. Persist
+
+- Refresh `.claude/testing/profile.json` (`updated`, `known_flaky`, `notes`) with anything learned about running tests. Preserve every key you did not resolve yourself.
+- Confirm the `## Testing` block is still a single idempotent pair of markers.
+- Write at most **3** `.claude/memory/failure-modes/<slug>.md` entries for genuinely recurring gotchas, with index lines in `.claude/memory/MEMORY.md`. One-off typos do not belong in memory.
+- Write `.claude/metrics/fix-tests-<YYYYMMDD-HHMMSS>.json` with the baseline, final counts, clusters, fixes applied, and anything unresolved.
+
+---
+
+## 8. Report
+
+Baseline → final counts. Root causes fixed, one line each. Failures reverted as pre-existing. Flaky tests recorded. Anything still red, and what was tried. If you changed a test rather than source, say which and why.