@renzrollon/interlock 1.0.0

package/shared/TOOL-ECONOMY.md

@@ -0,0 +1,155 @@
+# Tool Economy — Locate Before You Read, Batch Your Bash, Read State Don't Re-Derive It
+
+Shared discipline for all interlock skills that investigate a codebase or
+gather project state. Companion to `CONTEXT-HYGIENE.md` and `INVARIANT-SWEEP.md`.
+
+## Rule 0 — Query the graph before you Grep (when it exists)
+
+If `.claude/graph/graph.json` exists, treat it as the first locator for
+structural questions — “where is X”, “who uses Y”, “how does A reach B”:
+
+```bash
+interlock-graph query "<tokens>" --budget 1500
+interlock-graph consumers <symbol-or-file>
+interlock-graph path <A> <B>
+interlock-graph explain <node>
+```
+
+(`interlock-graph` is on PATH whenever this plugin is enabled — never probe for it.)
+
+Read `.claude/graph/GRAPH_REPORT.md` once for hubs/modules when scoping a
+fan-out. Then Grep/Read only for detail the graph lacks (dynamic imports,
+stringly keys, generated code, languages outside the graph walk).
+
+If the graph is missing and the session will do heavy exploration, prefer
+`interlock-graph build .` (or `/interlock:graph rebuild`) once over repeated blind greps.
+Do **not** rebuild on every query when the graph already exists — use
+`interlock-graph update` after large merges.
+
+## Rule 0.5 — Budgeted documentation retrieval (don't preload `docs/`)
+
+Do **not** read all `docs/*.md` or concatenate OpenSpec markdown into context
+upfront. Prefer the agent-only digest, then retrieve cited excerpts on demand.
+
+**Digest-first ladder**
+
+1. If `.claude/graph/DOCS_DIGEST.md` exists → Read it **once** as the default docs
+   primer (bounded agent-only file; prose twin of `GRAPH_REPORT.md`). Do not also
+   preload raw `docs/`.
+2. Task-specific drill-down → budgeted retrieve:
+
+```bash
+interlock-graph context "<task tokens>" --budget 2000 --changed path/a.ts,path/b.ts
+interlock-graph docs "<domain terms>" --budget 800
+```
+
+3. If digest missing/stale and the session needs domain prose → run `/interlock:docs-digest`
+   (rebuilds via `interlock-graph docs-index` + compress), else proceed with `context` only.
+4. Fallback when retrieve is empty (at most one query rewrite, then stop sprawl):
+   - broaden terms once (`auth` → `authentication session`)
+   - `grep` headings in `docs/` / `openspec/`, then Read spans
+   - if graph missing: `docs` only, or read `docs/architecture.md` headings via grep
+
+> **Widening is a deliberate position, not an oversight.** [The Spec Growth
+> Engine](https://arxiv.org/abs/2606.27045) §5.3 argues the opposite: *"the
+> default repair for an insufficient context is to fix the spec graph, not to
+> widen the context."* That is right when every module is required to carry a
+> machine-readable contract — an empty retrieval then means the architecture has
+> a hole, and widening hides it. Interlock targets brownfield repos where the
+> spec graph is incomplete by construction, and "fix the spec graph" is not an
+> action available mid-task. So we widen once, bounded, and stop. Take the
+> paper's repair instead whenever the spec genuinely should have covered it.
+
+**Default budgets**
+
+| Command | Budget | Role |
+|---------|--------|------|
+| `DOCS_DIGEST.md` | ~2500 soft / ~3200 hard | Agent-only prose bootstrap (via `/interlock:docs-digest`) |
+| `context` | 2000 tokens | Combined structural + documentation bundle |
+| `docs` | 800 tokens | Prose/domain context only |
+| `query` / `consumers` | 1500 tokens | Structural navigation |
+| `docs-index` | (index JSON) | Deterministic TOC/hashes for digest rebuild |
+
+**Provenance** — every excerpt must cite `file:heading (Lstart-Lend)`.
+Treat graph `INFERRED` edges as hints; verify with Read spans before claims.
+
+**Authoritative artifact exception** — when implementing against an active OpenSpec
+change, still read **all** of `proposal.md`, `design.md`, `tasks.md`, and delta
+specs for that change first. Rule 0.5 replaces exploratory preload, not the
+implementation contract leash (`/interlock:ship`).
+
+**Batch gathers** — a non-interactive run that needs project prose should pull a
+single bounded bundle via `interlock-graph context`, never `find docs -exec cat`.
+If `context` fails, prefer `.claude/graph/DOCS_DIGEST.md` over reading the head
+of an architecture doc.
+
+## Rule 1 — Locate before you Read
+
+Use `grep` / the Grep tool to find the file and line first, then Read with
+`offset`/`limit` around the hit. Do **not** Read whole files sequentially to
+discover where something lives. Read a file in full only once you know it's the
+one you need. When Rule 0 applies, graph query/consumers counts as “locate.”
+
+## Rule 2 — Batch and background your Bash
+
+- **Independent read-only commands** go in one message (multiple tool calls) or
+  joined with `;` — not `&&`. `&&` short-circuits: if an early command exits
+  non-zero, the later ones never run and their output is silently lost. For a
+  status sweep (`git branch`, `git status`, `git log`, `openspec status`) you
+  want them all regardless, so batch them.
+- **Reserve `&&` for dependency-ordered chains** where a later step is meaningless
+  if an earlier one failed — e.g. `npm run typecheck && npm run lint && npm test
+  && npm run build`.
+- **Quote shell globs** in filter arguments (`--include='*.ts'`,
+  `--glob '*.ts'`) so zsh does not expand them before the command sees them.
+  Prefer the Grep tool for `--include`-style file filtering when available.
+- **Background the long-running.** Builds, full test suites, and installs run with
+  `run_in_background` so you can continue other work while they execute.
+
+## Rule 3 — Read state, don't re-derive it
+
+At session start, current-task context comes from a few cheap, authoritative
+sources — `git log --oneline`, `git status --short`, `openspec status --json`,
+an open-task grep over `openspec/changes/*/tasks.md`, and the latest handoff.
+Front-load these in one pass. Read them,
+then act. Do not re-traverse the tree to reconstruct what they already tell you.
+
+**Explore brief as Rule-3 state:** when `/interlock:spec` runs after explore
+(especially after `/clear` or prompt-cache expiry), read the latest matching
+`.claude/handoff/explore-*.md` first (see `EXPLORE-BRIEF.md`).
+Prefer the brief’s recommendations over re-deriving discovery from the codebase
+or chat. Reopen code only for gaps or contradictions. Writing that brief in
+autonomous explore is how explore pays forward — spec should not re-pay.
+
+## Rule 4 — Spilled verify output: locator then Read spans, never the whole file
+
+`interlock verify spill` writes a command's full stdout/stderr to
+`.claude/ship/spill/<runId>/<seq>-<kind>.log` once it passes
+`LIMITS.verifySpillBytes`, and hands back `{ locator, preview, bytes, sha256 }`.
+The `preview` is already a head-and-tail slice bounded by
+`LIMITS.verifyPreviewChars` — read it from the result, do not re-open the
+locator to get what the preview already gives you.
+
+Only reopen the locator when the preview genuinely does not answer the
+question (a failure whose stack trace was in the omitted middle). Then Read it
+the same way Rule 1 says: with `offset`/`limit` around the span you need, not
+the whole file. A spilled suite log can be hundreds of KB — reading it in full
+defeats the reason it was spilled instead of pasted into the result.
+
+Never paste spilled bytes back into a verify result field (`detail`,
+`cliStdout`, `reason`, `stdout`, `stderr`, `output`, or a `failures[]` entry).
+`interlock verify judge` / `verify unit` check every one of those fields
+against the preview budget and reject the result outright — "oversized result
+field(s)" — if any exceeds it. The locator is not a courtesy; the anti-swallow
+check enforces it.
+
+## When NOT to apply
+
+This targets *wasted* exploration, not legitimate reconnaissance:
+
+- Genuine cross-subsystem investigation still warrants a fan-out
+  (`/interlock:explore`). Rule 1 applies *within* each investigator; the
+  decision to fan out is unchanged.
+- The artifact leash still holds: when you're about to implement against a
+  proposal/design/tasks set, read all of it first (see `/interlock:ship`).
+  That is not the sprawl this file is about.

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: bootstrap
+description: Onboard a brownfield project into OpenSpec — analyze the existing codebase with parallel explorer agents, write an initial architecture document, then generate one spec per discovered feature describing what is already built. Use when adopting spec-driven development on a repo that has code but no specs.
+license: MIT
+compatibility: Requires the openspec CLI. Node.js >= 18 for the bundled interlock-graph CLI.
+argument-hint: "[--quick] [--scope <path>]"
+allowed-tools: Bash(openspec *) Bash(interlock-graph *) Bash(git check-ignore *) Agent Read Write Glob Grep
+metadata:
+  type: discovery
+  outputs:
+    - openspec/initial-architecture.md
+    - openspec/specs/<feature>/spec.md
+---
+
+Document what a codebase **already is**, in OpenSpec form, so that every later change has something to change *from*.
+
+This is archaeology, not design. Every spec you write describes behavior that exists in the code today. If you cannot point at the code that implements a requirement, it does not belong in the spec.
+
+| Flag | Effect |
+|------|--------|
+| `--quick` | Sequential, single-context. For small repos (< ~50 source files). |
+| `--scope <path>` | Restrict the whole run to a subdirectory. |
+| *(none)* | Full parallel run. |
+
+---
+
+## 0. Pre-flight
+
+```bash
+# Initialize OpenSpec if this repo has never been initialized.
+# `openspec init` creates openspec/config.yaml, so its absence is the real signal.
+test -f openspec/config.yaml || openspec init --tools claude
+
+# Build the structural graph once — it seeds every explorer below.
+# Never swallow the outcome: stderr stays visible, and both failure modes
+# (build errored / nothing indexable) get a banner.
+graph_log=$(interlock-graph build .)
+graph_status=$?
+printf '%s\n' "$graph_log"
+if [ "$graph_status" -ne 0 ]; then
+  echo "GRAPH UNAVAILABLE: build errored (exit $graph_status) — explorers fall back to grep and will be slower"
+elif printf '%s' "$graph_log" | grep -q 'nodes=0'; then
+  echo "GRAPH UNAVAILABLE: nothing indexable found — explorers fall back to grep and will be slower"
+fi
+```
+
+**A graph failure is not a stop.** Bootstrap works without it — docs and OpenSpec indexing still happen — so print the banner, carry it to the final report, and continue with degraded expectations: the explorers grep instead of following edges, and they are slower for it.
+
+`nodes=0` is the ordinary case for a repo the graph doesn't structurally index (Go, Rust, Java, Ruby — structural indexing covers JavaScript/TypeScript, Python and shell). Say which of the two reasons applied rather than presenting either as a defect.
+
+When the build did produce a graph, **read `.claude/graph/GRAPH_REPORT.md` before spawning anything**. Its hub nodes and module boundaries tell the explorers where to look, so they don't rediscover the tree from scratch.
+
+Then check whether `openspec/specs/` already has content. If it does:
+
+> "This project already has N specs. Bootstrap will ADD specs for undocumented features but will never overwrite an existing one. Continue?"
+
+---
+
+## 1. DISCOVER — parallel exploration
+
+Spawn five explorer subagents via the Agent tool (`subagent_type: "Explore"`), or run them in sequence under `--quick`. Each returns structured JSON.
+
+**Before writing the prompts, establish the stack.** Read the dependency manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, …) and the top-level layout. Then phrase each prompt in that stack's vocabulary. The categories below are universal; examples in your head are *illustrative only* — replace them with the frameworks this repo actually uses. Asking a Go service about React hooks wastes a whole agent.
+
+Shared skeleton — fill `{role}`, `{task}`, `{schema}` from the table:
+
+```
+You are the {role} explorer for this repo. Phrase findings in this stack's vocabulary.
+{task}
+Prefer GRAPH_REPORT.md / interlock-graph when a graph exists; otherwise grep.
+Return JSON only: {schema}
+```
+
+| Role | Task | JSON schema |
+|------|------|-------------|
+| Structure Mapper | Map layout. Prefer GRAPH_REPORT modules/hubs, then verify on disk. Report organization (feature/layer/hybrid), entry points and routes, naming conventions, key config files, monorepo yes/no. | `{ organization, entryPoints[], conventions[], configFiles[], monorepo }` |
+| Dependency & Data Model Analyzer | Prefer `interlock-graph query` / `path`. Report third-party deps by role, internal layer imports, persistence schema/models, entity relationships, outbound integrations. | `{ dependencies[], internalLayers[], dataModels[], entityRelationships[], integrations[] }` |
+| Pattern Extractor | Recurring composition (components/handlers/services), state/lifecycle, errors, auth, data fetch/mutate, testing, code style. | `{ compositionPatterns[], stateManagement, errorHandling, auth, dataFlow, testing, codeStyle }` |
+| Interface Scanner | External surface: endpoints and protocol, mutations, schemas/validators, public exports/SDK, realtime/streaming, CLI. | `{ endpoints[], mutations[], schemas[], publicExports[], realtime[], cli[] }` |
+| Infrastructure & Config Reader | Build/task-runner entry points, env vars referenced in code, CI/CD, deploy target, lint/format, typecheck/static analysis. | `{ buildSystem, tasks[], envVars[], cicd, deployment, linting, staticAnalysis }` |
+
+Cap: 8 agents in this phase.
+
+---
+
+## 2. SYNTHESIZE — the architecture document
+
+One synthesis pass reads all five outputs and writes `openspec/initial-architecture.md`:
+
+```markdown
+# Initial Architecture
+
+> Auto-generated by /interlock:bootstrap on {date}.
+> Point-in-time snapshot, not a living document.
+
+## Stack & Infrastructure
+## Project Organization
+## Architecture Overview          <- ASCII diagram, subsystem boundaries, data flow
+## Data Model
+## Subsystems & Features          <- table: subsystem | location | responsibility | patterns
+## Established Patterns           <- composition, data flow, state, errors, auth, testing
+## Interface Surface
+## Design Decisions (Inferred)
+- [EXTRACTED]  stated outright in comments or docs
+- [INFERRED]   deduced from a consistent pattern
+- [AMBIGUOUS]  unclear — several patterns coexist
+## Gaps & Risks                   <- incomplete work, conflicting patterns, hazards
+```
+
+Tag every design decision with its confidence. An `[INFERRED]` decision that turns out wrong is recoverable; one presented as fact is not.
+
+---
+
+## 3. IDENTIFY FEATURES — boundary detection
+
+From the synthesis, pick the units that each deserve a spec:
+
+- **Entry-point based** — each major route group, command, or consumer
+- **Domain based** — each data model with a full lifecycle
+- **Capability based** — cross-cutting concerns (auth, observability, error handling)
+- **Module based** — feature directories and barrel exports
+
+Present the list for confirmation before generating:
+
+```
+Discovered N features to spec:
+1. authentication — login, register, session management
+2. task-crud      — create, read, update, delete tasks
+3. app-shell      — layout, navigation, route protection
+
+Generate specs for all, or select specific ones?
+```
+
+---
+
+## 4. SPEC GENERATION — one agent per feature
+
+For each confirmed feature, spawn a subagent (cap: 12).
+
+> You are writing an OpenSpec spec for an **existing** feature. Document what IS built, not what SHOULD be.
+> Feature: `{name}`. Architecture context: `{relevant section}`. Source files: `{paths}`.
+> Read the implementation. Write requirements in the repo's OpenSpec spec format, each one traceable to code. Where behavior is genuinely unclear, mark it rather than guessing.
+
+Write to `openspec/specs/<feature>/spec.md`. **Never overwrite an existing spec file.** If one exists, skip it and report the skip.
+
+Then validate:
+
+```bash
+openspec validate
+```
+
+---
+
+## 5. UPDATE PROJECT CONTEXT
+
+Fill in the project context in `openspec/config.yaml` with what was discovered — stack, architecture summary, conventions, domain — so later `openspec instructions` calls carry it. Merge into the existing file; never clobber unrelated keys a user has set.
+
+---
+
+## 6. REPORT
+
+- Any `GRAPH UNAVAILABLE: <reason> — explorers fall back to grep and will be slower` banner from pre-flight, repeated verbatim. If the graph built, say so in one line instead — a report that mentions neither reads like a graph-backed run that never happened.
+- Architecture doc path and what it covers
+- Specs created, and specs skipped because they already existed
+- Features deliberately not specced, with the reason
+- `openspec validate` result
+- Corpus-persistence posture (below)
+- Suggested next step: `/interlock:docs-digest` to build the agent prose primer
+
+### Corpus-persistence posture
+
+This is the one moment the repository is looked at before any run has written to
+it, so raise the question now: will its run corpora be kept?
+
+Observe the current state with git's own matcher — do **not** read or parse
+`.gitignore`. Its semantics include negation, directory-only trailing slashes,
+nested files, `.git/info/exclude` and the user's global excludes file, and a
+hand-rolled match gets some of those wrong:
+
+```bash
+git check-ignore -q .claude/ship/ ; echo "ship=$?"
+git check-ignore -q .claude/learning/ ; echo "learning=$?"
+git check-ignore -q .claude/metrics/ ; echo "metrics=$?"
+```
+
+Exit 0 means the path is excluded, 1 means it is tracked territory.
+
+Report **each of the three separately** — never collapse them into one verdict.
+A split state, where one is excluded and the others are not, is the case most
+likely to be unintentional, and collapsing hides exactly that.
+
+State the recommendation as **conditional**, never as a verdict about this
+repository. Nothing you can observe tells you whether the repo will run
+`/interlock:ship` against its own product, so say which posture fits which
+intent and let the reader choose:
+
+> `.claude/ship/` and `.claude/metrics/` are excluded, `.claude/learning/` is
+> not. If this repository will run `/interlock:ship` on its own product, those
+> exclusions drop the audit trail — remove them from `.gitignore`. If it is a
+> harness whose ship runs are development exhaust, add `.claude/learning/` so
+> all three match. Rationale and both `.gitignore` blocks: docs/11, "Whether to
+> keep them".
+
+**Never write to `.gitignore`.** Not to create it, not to append, not to "fix"
+a split state. Name the entries a person could add and let them add them — this
+skill was invoked to produce specs, and an edit to an unrelated file is a
+surprise in someone's diff, not a service.
+
+If any `git check-ignore` exits non-zero for a reason other than "not ignored"
+— an unreadable `.gitignore`, or a directory that is not a git repository at all
+— report the posture as **undetermined and say why**, then carry on. Bootstrap
+completes and writes every artifact it would otherwise have written; a failed
+check never fails the onboarding.
+
+---
+
+## Guardrails
+
+- **Never overwrite an existing spec.** Add only.
+- **Never modify source code.** This skill is read-only outside `openspec/` and `.claude/graph/`.
+- Respect `.gitignore`; skip vendored and generated trees.
+- Max 8 explorer agents in phase 1, 12 spec agents in phase 4.
+- **Idempotent.** Re-running adds newly-discovered features and leaves everything else alone.
+- If a feature's behavior can't be determined from the code, say so in the spec rather than inventing a requirement.
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md`.

package/skills/commit/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: commit
+description: Create a single feature-level commit after a change is implemented. Reads the OpenSpec change artifacts to write a verb-phrase conventional-commit message with an outcome summary and optional issue reference. Commit only — never runs tests, typecheck, lint or build, and never pushes.
+license: MIT
+compatibility: Requires git. Optional openspec CLI for change context.
+argument-hint: "[ISSUE-REF] [--yes]"
+disable-model-invocation: true
+allowed-tools: Bash(git *) Bash(openspec *) Bash(interlock *) Read Glob
+metadata:
+  type: execution
+---
+
+Write one good commit for a completed change.
+
+**Commit only.** This skill never runs tests, typecheck, lint, or a build — not in any mode, `--yes` included. Something else already verified; if nothing did, that is a gap in the caller, not work for this skill to absorb.
+
+`--yes` runs non-interactively: no confirmation prompt. It is **not** permission to push or amend.
+
+---
+
+## 1. Resolve the change and the issue reference
+
+Resolve the change by trying, in order:
+
+1. An explicit change name argument
+2. The current branch name (`feat/<name>`, `fix/<name>`)
+3. The most recently modified `openspec/changes/*/` directory
+
+Ask only when the session is interactive **and** all three fail. Under `--yes`, never ask — report which rungs were tried and stop with a one-line message.
+
+Extract an issue reference from the branch when one was not passed:
+`feat/RD-65-task-page` → `RD-65` · `fix/PROJ-123-login-bug` → `PROJ-123`
+
+If the branch looks like a feature branch but no reference was found:
+> ⚠️ No issue reference found. Branch `<name>` looks like a feature branch — pass one as `/interlock:commit <REF>` to avoid rewriting the message later.
+
+Interactive: wait for the user to confirm or supply one. Under `--yes`: emit that single line, **proceed without a ref**, and surface it again in the final report. On `main`, `develop`, or any branch without a `feat/`/`fix/` prefix, proceed silently — the reference is genuinely optional there.
+
+---
+
+## 2. Gather context
+
+```bash
+openspec status --change "<name>" --json
+git status --short
+git diff --stat
+```
+
+Read `proposal.md` for the one-line intent, `design.md` for scope, and the checked items in `tasks.md` for what was actually done. Inspect the diff to confirm the message matches reality rather than matching the plan.
+
+---
+
+## 3. Compose the message
+
+```
+<type>(<scope>): <verb phrase, imperative, lowercase>
+
+Summary of changes:
+- <outcome, not task completion>
+- <outcome>
+
+Refs: <ISSUE-REF>
+```
+
+- **Scope** is the issue reference when one exists (`feat(RD-65): …`), otherwise the primary module or feature area (`feat(tasks): …`).
+- **Summary bullets describe outcomes**, not "completed task 2.3".
+- **`Refs:` line** appears only when a reference exists. Omit the line entirely otherwise — never write `Refs: none`.
+
+| | |
+|---|---|
+| Good | `feat(RD-65): add task list page with filtering and status badges` |
+| Good | `fix(PROJ-123): resolve token refresh race condition` |
+| Good | `feat(tasks): add task list page with filtering` |
+| Bad | `feat(tasks): Task List Page` — not a verb phrase |
+| Bad | `feat(tasks): added the new task list page` — past tense, wordy |
+
+---
+
+## 4. Preview and commit
+
+Show the full message. Interactive: ask "Commit with this message?" and allow edits. Under `--yes`: print it and commit.
+
+Stage by naming **every path explicitly**, then commit.
+
+---
+
+## Guardrails
+
+- **Never `git add -A` or `git add .`.** Name every path. Leave unrelated dirty files unstaged.
+- **Never push.** `--yes` is not that permission.
+- **Never amend** unless the user explicitly asks and the amend conditions hold. `--yes` is not that permission.
+- **Never run tests, typecheck, lint, or build** — in any mode.
+- **Never re-implement or quick-fix failing code here.** If the tree looks broken: interactive, warn and ask whether to commit anyway; under `--yes`, commit and report the observation. Never start a verify/fix loop either way.
+
+---
+
+## 5. Report
+
+Commit hash and subject, files committed, anything left unstaged, and the warning from step 1 if it fired. Suggest the next step: `/interlock:mr` to open or update the merge request.

package/skills/dispatch/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: dispatch
+description: Route a request to the right interlock skill, after one batched pre-flight that loads git state, OpenSpec status, open tasks and graph presence in a single pass. Use when you are not sure which skill applies, or at the start of a session to orient before doing anything else.
+license: MIT
+compatibility: Optional openspec CLI and git. Node.js >= 18 for the bundled interlock CLI.
+allowed-tools: Bash(git *) Bash(openspec *) Bash(interlock *) Bash(interlock-graph *) Read Glob
+metadata:
+  type: routing
+---
+
+Figure out where the user actually is in the flow, then route. One cheap pre-flight beats an exploratory warm-up.
+
+---
+
+## Step 0 — Pre-flight, batched
+
+Run these **in one turn**, joined with `;` not `&&` — you want every answer regardless of which ones fail:
+
+```bash
+git branch --show-current; git status --short; git log --oneline -5
+openspec list --json 2>/dev/null
+interlock changes 2>/dev/null
+ls -t .claude/handoff/explore-*.md 2>/dev/null | head -3
+ls .claude/graph/GRAPH_REPORT.md .claude/graph/DOCS_DIGEST.md 2>/dev/null
+```
+
+That is Rules 2 and 3 of `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md`: read state, do not re-derive it. Do not traverse the tree to reconstruct what these already tell you.
+
+---
+
+## The flow
+
+```
+graph → docs-digest → bootstrap        (once per repo)
+/interlock:spec    explore → artifacts → review     ⟵ STOPS. Human reviews.
+/interlock:ship    waves → verify → commit  (workflow, zero-touch; --strict adds review)
+/interlock:mr      summary → merge request
+```
+
+The gap between `spec` and `ship` is deliberate. Never bridge it automatically — if a spec is ready, say so and let the user start ship. The user can bridge it themselves with `/interlock:spec --continue`, but that is theirs to ask for; routing never offers it.
+
+`ship` is a dynamic workflow. `/interlock:ship` is a skill trampoline that launches it via the Workflow tool (`scriptPath` → `workflows/ship.js`). Invoke the **skill** `interlock:ship` (or call Workflow with that scriptPath yourself). Do not treat a missing Workflow-namespaced command as "ship does not exist" — the skill is the entry point. If the trampoline halts because the Workflow tool is unavailable, that is the runtime gap (v2.1.154+, Dynamic workflows on in `/config`); do not implement the loop inline.
+
+---
+
+## Routing table
+
+| Situation | Route to |
+|---|---|
+| No `openspec/` directory, or no specs on an existing codebase | `/interlock:bootstrap` |
+| No `.claude/graph/`, and the session will explore or review heavily | `/interlock:graph` (build) |
+| Docs context too large, or the digest is stale | `/interlock:docs-digest` |
+| "How does X work?", "what breaks if I change Y?", tracing, comparing options | `/interlock:explore` |
+| "I want to build / fix X" — no change exists yet | `/interlock:spec` |
+| A change exists with reviewed artifacts and unchecked tasks | `/interlock:ship` — only if the user asked to ship, and this conversation has not already run ship |
+| Leftover unchecked boxes after a ship workflow just returned | Report them. Do not route to ship. |
+| Implementation done, diff needs review | `/interlock:review-code` |
+| Artifacts written but not yet reviewed | `/interlock:review-artifacts` |
+| Suite is red, or a CI log was pasted | `/interlock:fix-tests` |
+| "Explain this code" / "what changed in that commit?" | `/interlock:explain-code` |
+| Need a QA checklist for a change | `/interlock:manual-test-plan` |
+| Work is done and needs committing | `/interlock:commit` |
+| MR or PR needs creating or updating | `/interlock:mr` |
+| "I want to skip the checkpoint" / "don't stop and make me read it" | `/interlock:spec --continue` — **advanced**. Opt-in, fail-closed, and it stops anyway on anything a machine cannot settle. It cannot catch a wrong idea; only the read can. |
+
+**Prerequisite checks before routing:**
+
+- Routing to `ship` — run `interlock validate <change>` first. Not ready means route to `spec`, not ship. If a ship workflow already returned in this conversation, leftover boxes are a report, not a retry.
+- Routing to `spec` with no explore brief and a question that spans subsystems — run `explore` first.
+- Routing to anything that reads the graph when `.claude/graph/` is absent — offer to build it once.
+
+---
+
+## Ambiguity
+
+When two routes fit, prefer the **earlier phase**. Exploring when you should have specced costs one turn; shipping when you should have specced costs a bad change and a review cycle.
+
+When the request genuinely does not fit any skill, say so and handle it directly. Not everything is a workflow, and forcing an ordinary question through a skill is worse than just answering it.

package/skills/docs-digest/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: docs-digest
+description: Compress a repo's docs and OpenSpec specs into one token-dense, agent-only primer at .claude/graph/DOCS_DIGEST.md — the prose twin of GRAPH_REPORT.md. Use when docs context is too large to load, after substantial docs or spec edits, or when asked to rebuild or refresh the docs digest. Not for producing human-readable documentation.
+license: MIT
+compatibility: Requires Node.js >= 18. The interlock-graph CLI ships with this plugin and is on PATH automatically.
+allowed-tools: Bash(interlock-graph *) Read Write
+metadata:
+  type: discovery
+  outputs:
+    - .claude/graph/docs-index.json
+    - .claude/graph/DOCS_DIGEST.md
+---
+
+Produce **one agent-only primer** that lets a fresh agent understand this repo's documented domain without reading `docs/` end to end.
+
+`GRAPH_REPORT.md` answers *what connects to what*. This answers *what this project means*. They are siblings, both under `.claude/graph/`.
+
+**Inputs:** `docs/**` and `openspec/specs/**`, via the deterministic index.
+**Output:** `.claude/graph/DOCS_DIGEST.md`, overwritten in place.
+**Never indexed:** `openspec/changes/**`. Active change artifacts are read directly, not digested.
+
+Run this when: the digest is missing or stale, docs or living specs changed substantially, or the user asks to rebuild it. **Do not run it per query** — interactive skills should read an existing fresh digest, not regenerate one.
+
+---
+
+## Execution
+
+### 1. Index (deterministic — no model judgement)
+
+```bash
+interlock-graph docs-index . --write
+```
+
+Writes `.claude/graph/docs-index.json` covering `docs/` and `openspec/specs/`, with a `sha256` and heading spans per file.
+
+If the index is empty, stop and report that: a repo with no `docs/` and no `openspec/specs/` has nothing to digest, and inventing one is worse than having none.
+
+### 2. Staleness check
+
+If `.claude/graph/DOCS_DIGEST.md` exists, compare its frontmatter `source_hashes` against each `files[].sha256` in the index. All match, and the user didn't force a refresh? Report fresh and stop.
+
+Rebuild when: hashes mismatch, the digest is missing, or the user says rebuild / refresh / force.
+
+### 3. Selective read — never concatenate the corpus
+
+Read `.claude/graph/docs-index.json` in full. It is an inventory, not the corpus.
+
+Then read **section spans only** (`offset`/`limit` from each entry's `startLine`/`endLine`), highest signal first. Rank the index entries yourself using these signals, in order:
+
+1. **Entry points.** A file whose path or title matches `readme`, `architecture`, `overview`, `getting-started`, `contributing`, or `adr` — these state intent and structure.
+2. **Inbound references.** Files linked to most often from other indexed files. The index records outbound links; invert them. A doc everything points at is load-bearing.
+3. **Spec coverage.** Every `openspec/specs/*/spec.md` capability gets at least its title and requirement blurbs — the capability map is the single most useful thing in the digest.
+4. **Breadth over depth.** Prefer one section from each of ten documents over ten sections from one. You are building a map, not a summary.
+
+Drop first under token pressure: long analysis or research write-ups, changelogs, meeting notes, anything whose blurb already conveys the point, and peripheral spec capabilities. For those, use the index blurb instead of reading a span.
+
+Rank what the repo actually contains. Do not assume any particular filename exists.
+
+**Forbidden:** `find docs -exec cat`, reading every `docs/**/*.md` or `openspec/specs/**/*.md` end to end, reading anything under `openspec/changes/`, and writing output anywhere under `docs/` or `openspec/`.
+
+### 4. Write the digest
+
+Overwrite `.claude/graph/DOCS_DIGEST.md` with exactly this contract:
+
+```markdown
+---
+audience: agent-only
+target_tokens: 2500
+generated_at: <ISO-8601>
+source_hashes:
+  <path>: <sha256>
+  # one entry per indexed file
+---
+# docs-digest
+## map
+- <short-key> → <path>
+## facts
+- <dense telegraphic facts; ;-joined clauses fine>
+## workflows
+- <agent-relevant workflows and constraints>
+## specs
+- <capability> → key requirements / constraints (telegraphic, pointer-heavy)
+## pointers
+- <path>#<heading> Lstart-Lend
+```
+
+Omit `## specs` entirely when the index contains no `openspec/specs/` files.
+
+**Style — this is read by agents, not people.** Telegraphic. Abbreviations fine. Lists and `→`. No tutorial tone, no narrative padding, no worked examples. Prefer a pointer over a paraphrase whenever the reader could drill down with `interlock-graph context` or a Read span.
+
+**Budgets:** soft cap ~2500 tokens (`ceil(chars/4)`), hard stop ~3200. Drop lowest-priority content first. Never state a fact that isn't in the index or a span you actually read.
+
+### 5. Report (≤10 lines)
+
+Output path, token estimate, file count split by `docs/` vs `openspec/specs/`, fresh-vs-rebuilt, and a reminder that humans should keep reading `docs/` — this artifact is not for them.
+
+---
+
+## Relation to the graph skill
+
+| Need | Use |
+|------|-----|
+| Prose bootstrap / domain primer | This digest (`DOCS_DIGEST.md`) |
+| Structural bootstrap | `GRAPH_REPORT.md`, `interlock-graph query` |
+| Task-specific cited excerpts | `interlock-graph context` / `docs` |
+| Active change artifacts | Read `openspec/changes/<name>/` directly — **never** this digest |
+| TOC and hashes for this skill | `interlock-graph docs-index` |
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md`.