@renzrollon/interlock 1.0.0

package/shared/SESSION-SHAPES.md

@@ -0,0 +1,261 @@
+# Session Shapes
+
+Patterns that produce expert-level sessions. Use these as mental models when
+starting a session — or let `/interlock:dispatch` orient you first.
+
+The key insight: expert sessions are not longer or harder — they are better
+structured from the start. The right shape chosen upfront eliminates
+backtracking, scope drift, and wasted exploration. Score a live session against
+these shapes and against `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md`.
+
+---
+
+## Shape 1: Plan-then-Execute
+
+**Duration:** 15-25 min | **Agents:** 4-6 | **Pattern:** think → structure → do
+
+**Entry signal:** "I want to build X" — no active change exists, scope spans multiple files
+
+**Flow:**
+1. `/interlock:explore` (optional — skip if the domain is well-understood)
+2. `/interlock:spec` — generates proposal, design, tasks, delta specs, then gates them through an artifact review and **stops at the human checkpoint**
+3. Human reads the spec
+4. `/interlock:ship` — dependency-ordered waves of parallel implementers → verify → commit
+
+**Expert version:** State the full scope upfront. Let `spec` generate all artifacts
+and pass Gate 1 in one pass. Read the spec once. `ship` handles execution in
+parallel and produces one feature-level commit. No mid-session design changes.
+
+**Common failure mode (advanced, not expert):** Starting to code before speccing.
+Scope drifts mid-implementation. Multiple commits for what should be one logical
+change. 30+ minutes because exploration and execution are interleaved.
+
+**Preconditions for expert execution:**
+- Clear one-sentence scope statement before starting
+- No ambiguity about boundaries (what's in / out)
+- Domain knowledge sufficient to skip the explore phase
+
+---
+
+## Shape 2: Structured Execute
+
+**Duration:** 7-15 min | **Agents:** 3-13 (depends on task count) | **Pattern:** load → classify → do
+
+**Entry signal:** "Ship the change" or "execute the tasks" — an active change with reviewed artifacts already exists
+
+**Flow:**
+1. `/interlock:ship` — the workflow loads all artifacts, classifies tasks, and runs them in dependency-ordered waves
+2. Unit verification, then a single commit
+
+**Expert version:** Artifacts already exist and passed the checkpoint in a prior
+session. This session is pure execution — zero exploration, zero design decisions.
+Fastest path to done. The workflow reads everything before writing anything.
+
+**Common failure mode:** Re-implementing the change inline in the conversation
+instead of launching the `ship` workflow. Making implementation decisions that
+contradict the design doc. Speccing again when the spec is already reviewed.
+
+**Preconditions for expert execution:**
+- All artifacts exist and were reviewed (Gate 1 passed)
+- Tasks are well-defined with clear acceptance criteria
+- The Workflow tool is available (Claude Code v2.1.154+, dynamic workflows on)
+
+---
+
+## Shape 3: Investigate-then-Propose
+
+**Duration:** 20-35 min | **Agents:** 2-5 | **Pattern:** understand → capture → structure
+
+**Entry signal:** "How does X work? I might need to change it." — needs understanding before committing to a design
+
+**Flow:**
+1. `/interlock:explore` — fan out read-only investigators across subsystems, write a durable brief
+2. Synthesize findings into a scope definition
+3. `/interlock:spec` — convert understanding into durable artifacts (auto-loads the latest explore brief)
+4. Stop at the checkpoint (or continue to ship in the same session if scope is small)
+
+**Expert version:** Run `/interlock:explore` and let it fan out across threads
+without asking which to follow; it writes `.claude/handoff/explore-<slug>-<ts>.md`.
+Then `/interlock:spec` (possibly after `/clear` or cache expiry) auto-loads the
+latest matching brief and generates proposal artifacts — no re-discovery from chat.
+
+**Common failure mode:** Exploring in one long single-threaded chat. Findings live
+only in chat history and are lost after `/clear` or prompt-cache expiry. Never
+converting understanding into a spec or explore brief — the next session
+re-discovers everything.
+
+**Preconditions for expert execution:**
+- Multiple subsystems or modules are involved (justifies fan-out)
+- The question is specific enough to decompose into parallel investigations
+- Memory / prior briefs are checked first (avoid re-investigating known territory)
+
+---
+
+## Shape 4: Targeted Fix
+
+**Duration:** 5-12 min | **Agents:** 0-1 | **Pattern:** locate → fix → verify
+
+**Entry signal:** "X is broken" or "fix the error in Y" — specific bug, narrow scope
+
+**Flow:**
+1. Check memory / known constraints about this area
+2. Locate the issue (often a single file or function) — graph query or grep, not a full-file read sweep
+3. Fix it
+4. `/interlock:fix-tests` or run the suite to verify
+5. `/interlock:commit` (or report if more investigation is needed)
+
+**Expert version:** The relevant constraint is already known. No exploration needed
+— go directly to the fix. Verify immediately. Done in under 10 minutes.
+
+**Common failure mode:** Guessing at solutions without reading constraints. Trying
+three wrong approaches before finding the right one. Exploring broadly when the fix
+is narrow. Not running tests after the fix.
+
+**Preconditions for expert execution:**
+- The error is specific (not "something is slow" — that's Investigate-then-Propose)
+- Scope is genuinely narrow (one file, one concept)
+- If the fix touches a shared or derived value, its consumers are swept
+  (`${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md`)
+
+---
+
+## Shape 5: Workflow-Orchestrated
+
+**Duration:** 10-40 min | **Agents:** 10-50+ | **Pattern:** script controls flow, agents do work
+
+**Entry signal:** Complex work that benefits from deterministic orchestration — a reviewed change ready to ship, or a diff ready to review.
+
+**Flow (ship):**
+1. `/interlock:ship` launches `workflows/ship.js` on the Workflow runtime
+2. Load artifacts → classify tasks (schema-validated) → execute in parallel waves
+3. Inter-wave verification gates catch interface mismatches immediately
+4. Unit verify, then commit. `--strict` adds adversarial review, remediation, handoff, conformance
+5. Resumable — a stopped run picks up where it left off
+
+**Flow (review):**
+1. `/interlock:review-code` fans out up to six dimension reviewers (language, architecture, QA, delivery; devops and security when the diff earns them)
+2. Two skeptics try to refute every blocker and warning; a dismissal must cite a `file:line` span
+3. Only surviving findings reach you; the report states how many were dismissed
+
+**Expert version:** The script holds the plan, not the model's context window.
+Intermediate results stay in script variables, not chat history. Deterministic
+retry logic instead of prompt-based "hopefully it retries."
+
+**Common failure mode:** Re-implementing a workflow's job inline in the
+conversation. Using a workflow for work that is genuinely sequential or needs a
+human decision between steps.
+
+**Preconditions for expert execution:**
+- Tasks are independent (can parallelize without file conflicts)
+- Verification commands are detectable (typecheck, test, lint)
+- For `ship`: artifacts exist and passed Gate 1
+- For `review-code`: implementation is complete (files to review exist)
+
+---
+
+## Shape 6: Agent-Team Investigation
+
+**Duration:** 15-45 min | **Agents:** 3-6 persistent teammates | **Pattern:** debate → converge → decide
+
+**Entry signal:** "The root cause is unclear" or "we need to investigate from multiple angles simultaneously" — when competing hypotheses need adversarial testing, not just parallel exploration.
+
+**Flow:**
+1. Spawn 3-5 teammates, each assigned a different hypothesis or angle
+2. Teammates investigate independently AND challenge each other's findings
+3. The debate structure surfaces the theory that survives scrutiny
+4. The lead synthesizes consensus into a decision or a spec
+
+**Expert version:** Unlike a workflow fan-out (which collects results silently),
+agent teams *communicate*. Teammate A finds evidence that contradicts Teammate B's
+theory and messages them directly. The adversarial communication is the value — it
+prevents anchoring on the first plausible explanation.
+
+**Best use cases:**
+- Debugging with an unclear root cause (an investigator per hypothesis)
+- Architecture decisions with genuine tradeoffs (an advocate per approach)
+- Cross-layer coordination where subsystem owners negotiate interfaces
+
+**Common failure mode:** Using teams for work that's purely mechanical parallelism
+(use a workflow instead). Teams add coordination overhead — only worth it when
+agents need to *talk to each other*.
+
+**Preconditions:**
+- Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings
+- The problem has multiple plausible approaches / causes (not a single clear path)
+- Value comes from inter-agent communication, not just parallel execution
+
+---
+
+## Shape Selection Heuristic
+
+When in doubt, start with the simplest shape that fits:
+
+```
+Specific error + narrow scope           → Targeted Fix
+"Ship the tasks" + reviewed artifacts    → Structured Execute
+"Build X" + clear scope                  → Plan-then-Execute
+"How / why / what if" + broad scope      → Investigate-then-Propose
+Reviewed change ready, or a diff to vet  → Workflow-Orchestrated (ship / review-code)
+Unclear root cause + competing theories  → Agent-Team Investigation
+```
+
+If you pick Targeted Fix and discover the scope is broader than expected, escalate
+to Investigate-then-Propose. If you pick Plan-then-Execute and the change is already
+reviewed, downgrade to Structured Execute. Shape classification is a starting point,
+not a commitment.
+
+**Choosing between Workflow and Agent Team:**
+- Tasks are independent and the orchestration is known → Workflow (deterministic, cheaper)
+- Agents need to communicate, challenge, or negotiate → Agent Team (higher cost, richer coordination)
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| "Explore everything first" | Burns 20 min before any output | Pick a shape, start executing |
+| "Let me read the whole codebase" | Context window fills with irrelevant code | Query the graph / read artifacts, then act |
+| "I'll figure out the approach as I go" | Leads to backtracking and scope drift | Classify shape, announce scope, then execute |
+| "Just one more thing…" | Scope creep extends sessions past 30 min | Handoff + new session for new scope |
+| Single-threading work that could parallelize | 3x wall-clock for independent tasks | `ship` or an explore fan-out |
+| Re-implementing `ship` inline | Context fills, intermediate results lost | Launch the `ship` workflow — results stay in script variables |
+| Bridging `spec` → `ship` automatically | Skips the one human checkpoint | Stop at the checkpoint; let the human read |
+
+---
+
+## Expertise Level
+
+**expertise_level**: Rate the USER's demonstrated expertise in the domain/task of THIS
+   session — command of its terminology, structures, and conventions — ONCE for the WHOLE
+   conversation, from the user's turns only. Rate domain familiarity with the work AT HAND,
+   NOT general intelligence, NOT the agent's performance, NOT task difficulty (a senior
+   engineer can be a beginner at Rust or differential privacy). Weigh three CO-EQUAL signals
+   together:
+   - Setup specificity: does the framing use named entities/constraints that require domain
+     knowledge to even reach for? Naming files/paths visible on screen is NOT domain
+     knowledge — anyone using the agent does that.
+   - Verification type: generic asks ("please double-check", "are you sure?") are epistemic
+     humility, not expertise; targeted asks ("did you actually call commit()?", "what's the
+     cardinality of that join?") require knowing WHAT to check.
+   - Direction of correction: the agent correcting the user's terminology/mental model pulls
+     DOWN (1-2); the user catching the agent's domain mistakes pulls UP (4-5); neither
+     correcting the other is neutral.
+   Emit exactly ONE value (default `2_beginner` only when there's nothing to go on, e.g. a
+   warmup session):
+   - `1_novice` — generic/imprecise framing, no domain names; verification absent or fully
+     generic; doesn't notice wrong output; agent supplies basic domain concepts.
+   - `2_beginner` — some correct terms used loosely; mostly generic verification; pushes back
+     only on obvious errors; agent reframes the user at least once. A fluent technologist
+     working OUTSIDE their domain lands here.
+   - `3_intermediate` — precise at a directive level (names files, outputs, libraries) but
+     doesn't engage methodology/tradeoffs; mix of generic and targeted checks; catches
+     meaningful mistakes. A domain expert delegating a routine task can also land here.
+   - `4_advanced` — structural domain knowledge NOT readable off the screen (a specific edge
+     case, non-obvious constraint/invariant, version-specific behavior, known failure mode);
+     moderately specific verification; catches at least one of the agent's domain mistakes;
+     the agent doesn't have to correct the user's domain model.
+   - `5_expert` — insider-only jargon/conventions, unprompted tradeoff discussion, surgical
+     verification, authoritative corrections invoking specific technical reasoning,
+     preemptive edge-case handling. Direction of correction is user->agent. "Insider talking
+     to an equal," even in a short session.

package/shared/SKILL-CANDIDATE-BRIEF.md

@@ -0,0 +1,106 @@
+# Skill Candidate Brief — Author Contract
+
+A durable handoff from a retro/review skill into a skill-author agent. It
+captures evidence that a repeatable session procedure should become a new
+`SKILL.md`, without writing the skill itself.
+
+**Path:** `.claude/handoff/skill-candidate-<slug>-<YYYYMMDD-HHMMSS>.md`
+Slug = the proposed skill name in kebab-case. Same handoff directory as explore
+briefs (`${CLAUDE_PLUGIN_ROOT}/shared/EXPLORE-BRIEF.md`).
+
+**When to write**
+
+- The retro finds a repeatable procedure not covered by an existing skill.
+- Cap at the top 3 candidates per review. Skip one-offs, pure chat, and duplicates
+  of existing skills (suggest extending those instead).
+
+**Bound the brief** (~1–3k tokens): cite the concrete moments and the tool pattern;
+treat the procedure steps as hypotheses the author must refine.
+
+---
+
+## Template (stable — skill-author agents depend on these headings)
+
+```markdown
+# Skill Candidate Brief: <slug>
+
+## Meta
+- source: interactive | loop
+- slug: <kebab-case proposed skill name>
+- confidence: high | med | low
+- created: <ISO-8601 timestamp>
+- session_refs: <e.g. this session, 2026-08-20>
+- evidence_basis: current-session (live context, no transcript re-read)
+
+## Proposed Skill
+- name: <kebab-case>
+- description: <pushy trigger description — what it does AND when to use it>
+- when_to_use: <bullet list of user phrases / contexts>
+- when_not_to_use: <bullet list — overlaps, one-offs, better existing skills>
+
+## Evidence
+<!-- The concrete moments this session, the tool pattern, the assigned shape + score.
+     State clearly which steps below are inferred rather than directly observed. -->
+
+## Procedure to Encode
+<!-- Ordered steps a SKILL.md should teach. Hypotheses from what the session did — author must refine. -->
+1. ...
+2. ...
+
+## Inputs / Outputs / Exit Criteria
+- inputs: <args, flags, natural-language triggers>
+- outputs: <files written, chat summary shape>
+- exit_criteria:
+  - [ ] ...
+
+## Related Existing Skills
+<!-- From the enumerated skill list. Name overlaps and why this is NOT a duplicate
+     (or: "extend <skill> instead" and stop — do not invent a parallel skill). -->
+
+## Open Questions
+<!-- Gaps the author must resolve before writing SKILL.md (scope, tools, output path, etc.). -->
+
+## Author Checklist
+- [ ] Name + description are distinct from Related Existing Skills
+- [ ] Trigger phrases are concrete enough to avoid under-triggering
+- [ ] Procedure steps refined against at least one real session or user confirmation
+- [ ] Inputs / outputs / exit criteria are testable
+- [ ] Open questions resolved or explicitly deferred in the skill body
+```
+
+---
+
+## Section rules
+
+| Section | Rule |
+|---------|------|
+| **Meta.confidence** | `high` = a repeated procedural shape with durable domain knowledge; `med` = a single strong session; `low` = weak signal / thin evidence |
+| **Evidence** | Cite the concrete moments. Never invent tool calls, quotes, or token counts. |
+| **Procedure to Encode** | Hypotheses labeled as such. Prefer a locate → act → verify shape. |
+| **Related Existing Skills** | Must check the enumerated skill list. Prefer "extend X" over a new skill when overlap is high. |
+| **Author Checklist** | If unchecked blockers remain, say so when pointing the user at the brief. |
+
+## Candidacy signals (what a retro looks for)
+
+- The same multi-step procedure performed by hand that no skill covers
+- A long, high-tool-count stretch reinventing a workflow absent from existing skills
+- A mid/low shape score where a skill would have prevented the named failure mode
+- A clear procedural shape (locate → transform → verify) with durable domain knowledge
+
+**Skip:** one-off Targeted Fixes, chat-only stretches, and work already covered by
+an existing skill (suggest extending that skill instead).
+
+## Chat reply after write
+
+Do **not** re-dump full briefs into chat. Reply with:
+
+1. Paths to each `.claude/handoff/skill-candidate-*.md` written
+2. A one-line summary per candidate (slug + confidence + why)
+3. "Hand these to a skill-author agent to write the SKILL.md"
+
+## Author consumption
+
+A skill-author agent reads the brief, resolves the Open Questions with the user,
+then writes `skills/<name>/SKILL.md` (and docs / manifest wiring as needed). Prefer
+the brief's recommendations over re-deriving the procedure; reopen the session only
+for gaps or contradictions.

package/shared/TEST-PROFILE.md

@@ -0,0 +1,204 @@
+# Test Profile — Discovery & Persistence Contract
+
+Durable, machine-readable record of how a project's tests run. Owned by
+`/interlock:fix-tests` and reused by `/interlock:ship`, so neither has to
+re-sniff `package.json` on every run.
+
+**Path:** `.claude/testing/profile.json`  
+**Human mirror:** idempotent `## Testing` block in `CLAUDE.md` (or `AGENTS.md`
+on Cursor-only projects) between HTML comment markers (see below).
+
+Learned gotchas discovered mid-fix go to
+`.claude/memory/failure-modes/<slug>.md` (max 3 per session) — **not** into
+the profile.
+
+---
+
+## Schema (`profile.json`)
+
+```json
+{
+  "version": 1,
+  "updated": "<ISO-8601>",
+  "discovered_from": ["package.json#scripts.test", "CI", "interview"],
+  "unit": {
+    "command": "npm test",
+    "cwd": ".",
+    "filter_syntax": "node --test --test-name-pattern <pattern> <file>",
+    "single_file": "node --test path/to/file.test.mjs",
+    "env": {},
+    "timeout_ms": 120000,
+    "prerequisites": []
+  },
+  "e2e": {
+    "enabled": false,
+    "command": null,
+    "cwd": ".",
+    "filter_syntax": null,
+    "single_file": null,
+    "env": {},
+    "timeout_ms": 600000,
+    "prerequisites": []
+  },
+  "coverage": {
+    "enabled": false,
+    "command": null,
+    "report_path": "coverage/lcov.info",
+    "format": "lcov"
+  },
+  "typecheck": {
+    "command": null,
+    "cwd": "."
+  },
+  "lint": {
+    "command": null,
+    "cwd": "."
+  },
+  "known_flaky": [],
+  "notes": []
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `unit.command` / `e2e.command` | Full shell command that runs the suite (as in CI / `package.json`) |
+| `filter_syntax` | How to run a subset by name/pattern (string with `<pattern>` placeholder) |
+| `single_file` | How to run one file (string with path implied, or template) |
+| `env` | Extra env vars required for a green run (not secrets — names/placeholders only) |
+| `prerequisites` | Human-readable setup steps (dev server, seeded DB, `npx playwright install`, …) |
+| `timeout_ms` | Soft budget for one full suite run; do not raise to mask races |
+| `coverage.enabled` | Whether a coverage command is known. `false` = not configured (never an error) |
+| `coverage.command` | Full shell command that produces a coverage report (e.g. `npm run coverage`) |
+| `coverage.report_path` | Where the report lands, relative to `unit.cwd` (`coverage/lcov.info`, `coverage/coverage-summary.json`, …) |
+| `coverage.format` | Report format the path holds: `lcov`, `json-summary`, `cobertura`, … |
+| `typecheck.command` | Full shell command that type-checks the project (e.g. `npm run typecheck`). `null` = none found; the step is skipped with a reason, never guessed |
+| `lint.command` | Full shell command that lints the project (e.g. `npm run lint`). `null` = none found; the step is skipped with a reason, never guessed |
+| `known_flaky` | Paths or test-name patterns that flip on re-run (recorded, not "fixed") |
+| `notes` | Short freeform caveats (≤5 lines total) |
+
+`e2e.enabled` defaults to `false`. The skill never runs e2e unless the user
+passes `--e2e` **and** `e2e.command` is set.
+
+`coverage.enabled` also defaults to `false`, and coverage is always **advisory**
+— a missing coverage tool, a failed coverage run, or 0% covered changed lines
+must never fail a gate or turn a green suite red.
+
+---
+
+## Discovery precedence
+
+First run (or `--reconfigure`): derive in order, stop when confident enough to
+write a profile. Ask at most **4 questions** only when still ambiguous.
+
+1. **`package.json` / language manifests**
+   - `scripts.test`, `scripts.test:unit`, `scripts.test:e2e`, `scripts.test:ci`
+   - Python: `pytest` / `tox` / `pyproject.toml` `[tool.pytest]`
+   - Go: `go test ./…`
+   - Rust: `cargo test`
+2. **Runner config files** (infer filter + single-file syntax)
+   - `vitest.config.*`, `jest.config.*`, `playwright.config.*`
+   - `pytest.ini`, `pyproject.toml`, `.mocharc.*`
+   - Node built-in: `node --test` (filter: `--test-name-pattern`)
+3. **CI workflows** (`.github/workflows/*`, `.gitlab-ci.yml`, etc.)
+   - Prefer the job that runs unit tests on PRs
+   - Capture env and prerequisites from the job definition
+4. **Ask (≤4 questions, once)** — only for gaps that block a correct run:
+   - Unit command (if none found)
+   - Single-file / filter syntax (if not inferable)
+   - Required env or prerequisites
+   - E2e command (only if user asked about e2e / passed `--e2e`)
+
+Every later run is **zero-question** unless `--reconfigure`.
+
+### Coverage discovery
+
+`coverage` is resolved independently of `unit`/`e2e` and **never blocks**. Derive
+in this order, stop at the first hit, and persist what you find:
+
+1. `coverage.command` already in the profile → use it as-is
+2. `package.json` `scripts.coverage`
+3. `package.json` `scripts["test:coverage"]`
+4. `vitest --coverage` / `jest --coverage` when vitest or jest is the runner
+5. `c8` / `nyc` present in `devDependencies` → wrap `unit.command`
+6. `node --test --experimental-test-coverage` when the runner is node:test
+
+Never ask for a coverage command and never install tooling to obtain one —
+nothing found → `enabled:false`, report and continue; never block.
+
+### Typecheck and lint discovery
+
+`typecheck` and `lint` are resolved the same way `coverage` is — independently,
+never by asking, never by inventing a command. Without them a ship run's
+inter-wave checkpoint has no typecheck to run, and `typecheck` is a **halting**
+kind there: a type error must stop the next wave from building on top of it.
+
+Derive in this order, stop at the first hit, and persist what you find:
+
+1. the command already in the profile → use it as-is
+2. `package.json` `scripts.typecheck`, then `scripts["type-check"]`; for lint,
+   `scripts.lint`
+3. the step in the CI job that runs it (`.github/workflows/*`, `.gitlab-ci.yml`)
+
+Nothing found → `command: null`. **Never ask, and never invent one** — a guessed
+`tsc --noEmit` against a project that does not typecheck that way is a red step
+nobody asked for. A `null` command is skipped with
+`reason=no-detectable-command`, which is a stated absence rather than a silent
+one.
+
+**Stale profile:** rewrite when `unit.command` no longer exists in
+`package.json` / manifests, or the command exits 127 / "not found". Otherwise
+reuse as-is.
+
+---
+
+## Human mirror (`## Testing` block)
+
+Write (or replace) content **between** these markers inside `CLAUDE.md`
+(prefer) or `AGENTS.md` (if that is the project's agent doc and `CLAUDE.md`
+is absent):
+
+```markdown
+## Testing
+
+<!-- BEGIN interlock:testing -->
+**Unit:** `<unit.command>` (cwd: `<unit.cwd>`)
+**Filter:** `<unit.filter_syntax>`
+**Single file:** `<unit.single_file>`
+**E2E:** `<e2e.command or "opt-in via /fix-tests --e2e (not configured)">`
+**Prerequisites:** <list or "none">
+**Profile:** `.claude/testing/profile.json` (managed by `/interlock:fix-tests`)
+<!-- END interlock:testing -->
+```
+
+**Idempotency rules**
+
+- If both markers exist: replace only the interior; leave surrounding prose alone.
+- If `## Testing` exists without markers: insert markers + block immediately
+  under the heading (preserve any pre-existing bullet notes above the markers
+  only if they are clearly human-authored and outside a prior managed block).
+- If no `## Testing` section: append the full section (heading + markers) at
+  end of file (or before `## Git` / `## Hooks` if those headings exist).
+- Never duplicate the managed block. A second `/interlock:fix-tests` run must leave a
+  single pair of markers.
+
+---
+
+## Consumers
+
+Anything that needs to run this project's tests reads
+`.claude/testing/profile.json` first instead of sniffing `package.json`.
+
+- `/interlock:fix-tests` — owns discovery, and is the only skill allowed to
+  interview the user to fill a field.
+- `/interlock:ship` — reads the profile during its test wave and final
+  verification. Where the discovery ladder would ask a question, ship leaves the
+  field `null` and notes it. **Ship never interviews.**
+
+**Two writers, no fighting.** `/interlock:fix-tests` and `/interlock:ship` both write this file.
+Each writes only the fields it actually resolved and preserves every other key
+verbatim — `/interlock:ship` never clears `known_flaky`, human-authored `notes`, or
+`e2e` settings it did not discover, and `/interlock:fix-tests` leaves `coverage` alone
+unless it discovered coverage tooling itself. Neither writer interviews the user
+on behalf of the other: `/interlock:ship` is always headless and records
+unresolvable fields as `null` plus a line in `notes`, where the ladder above
+would have asked.