@renzrollon/interlock 1.0.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@renzrollon/interlock",
+  "version": "1.0.0",
+  "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "interlock": "./bin/interlock",
+    "interlock-graph": "./bin/interlock-graph",
+    "interlock-run": "./bin/interlock-run",
+    "interlock-ship-acp": "./bin/interlock-ship-acp"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "workflows",
+    "skills",
+    "hooks",
+    "agents",
+    "shared",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test $(find test -name '*.test.mjs' | sort)",
+    "validate": "claude plugin validate . --strict"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/renzrollon/interlock.git"
+  }
+}

package/shared/CONTEXT-HYGIENE.md

@@ -0,0 +1,84 @@
+# Context Hygiene — `[[VARIABLE_NAME]]` Placeholder Pattern
+
+Shared discipline for all interlock skills that embed user-supplied strings in downstream prompts.
+
+## The problem
+
+Agents fill missing context with any string in their active window — leaking PII, credentials, deprecated endpoints, or plausible-but-wrong values. This is **context hallucination**: gap-filling from ambient context rather than verified sources.
+
+Hard-coded prompt rules ("don't leak PII") are insufficient. Contexts overflow; prompt injection bypasses inline constraints. The fix is **structural** — wrap sensitive values as opaque placeholders and let a resolver substitute them at call time.
+
+## The syntax
+
+Wrap any user-supplied or ambient value that will appear inside a prompt template as `[[VARIABLE_NAME]]`:
+
+```
+[[USER_PROMPT]]        Original user request
+[[CHANGE_NAME]]        OpenSpec change slug (kebab-case)
+[[REPO_ROOT]]          Absolute path to the current repo
+[[ISSUE_REF]]          Extracted from branch (e.g., RD-65)
+[[BASE_BRANCH]]        Merge target (main / master / trunk)
+[[SANITIZED_EMAIL]]    Redacted email from user input
+[[SANITIZED_TOKEN]]    Redacted 32+ char alphanumeric token
+[[SANITIZED_AUTH]]     Redacted Bearer/Basic auth header
+```
+
+Names are `SCREAMING_SNAKE_CASE`, enclosed in double brackets. No nesting, no expressions.
+
+## The rules
+
+1. **Wrap on emit, resolve on consume.** When a skill composes a downstream prompt, wrap sensitive values. The resolver runs immediately before the tool call.
+
+2. **Resolution order** (highest priority wins):
+   - Runtime state overrides (values captured this session)
+   - Environment variables of the same name
+   - Explicit `AskUserQuestion` prompt if the value is required
+
+3. **Unresolved placeholders stay visible.** Never silently substitute a plausible value. If `[[COMMENTER_EMAIL]]` reaches a tool call unresolved, halt and ask the user. Gap-filling is what this pattern exists to prevent.
+
+4. **Sanitize on ingress.** When a skill receives freeform user text that will be echoed downstream, redact obvious secrets to `[[SANITIZED_*]]` form immediately. Preserve the mapping in session state for later resolution.
+
+5. **Never round-trip through the model.** A resolved value must go directly from the resolver to the tool argument. Do not paste it into a prompt the model reads first.
+
+## Common patterns
+
+**Composing a subagent prompt:**
+
+```
+INVESTIGATE: [[USER_PROMPT]]
+CHANGE: [[CHANGE_NAME]]
+FILES TO READ:
+  - [[REPO_ROOT]]/openspec/changes/[[CHANGE_NAME]]/proposal.md
+```
+
+**Handing to `gh pr create`:**
+
+```
+--title "feat([[SCOPE]]): [[VERB_PHRASE]]"
+--body "$(...contains [[SUMMARY]], [[RISK]], [[TEST_PLAN]]...)"
+```
+
+**Detecting a leak in output:**
+
+If model output contains a literal email, phone number, or long token that was NOT in the user's input, treat it as a hallucination. Do not commit, do not send. Halt and ask.
+
+## What NOT to wrap
+
+Placeholders are for **values**, not concepts. Do not wrap:
+
+- Verbs or actions (`[[ACTION]]` is meaningless)
+- Boolean state (`[[IS_ACTIVE]]` — just use the boolean)
+- Full sentences (`[[FULL_PROMPT]]` — defeats the purpose)
+- Values already sourced from a schema-validated tool result (they're structured, not freeform)
+
+## Skill integration
+
+Skills that emit prompts to subagents or external tools:
+
+- **/interlock:spec** — wraps user description, change name, repo root before passing to `openspec new change` and downstream artifact generators.
+- **/interlock:explore** — wraps user question and any file references before fanning out to Explore subagents.
+- **/interlock:ship** — wraps goal and file lists in each subtask prompt.
+- **/interlock:mr** — wraps branch name, issue ref, summary before invoking `glab mr create` / `gh pr create`.
+- **dispatch** — sanitizes freeform user input (emails, tokens, auth headers) at ingress.
+
+When adding a new skill that echoes user-supplied strings into a prompt template or tool call, follow the same pattern.

package/shared/DECISION-LEDGER.md

@@ -0,0 +1,141 @@
+# Decision Ledger — Continuity Contract
+
+Durable record of every ambiguity a change hit and how it was settled. Lives
+with the change so it survives `/clear`, prompt-cache expiry, and a handoff to
+a different agent — and so a machine can read it.
+
+**Path:** `openspec/changes/<change>/decisions.md`
+Versioned with the change; committed alongside `proposal.md` / `design.md` /
+`tasks.md`.
+
+**Why a file and not chat:** a decision that exists only in chat does not
+exist. The readiness gate answers one question — *is there anything left here
+that only a human can decide?* — and it answers it by reading this file.
+
+---
+
+## Template (stable — tooling depends on the five columns)
+
+```markdown
+# Decisions — <change>
+
+| id | question | class | resolution | evidence |
+|----|----------|-------|------------|----------|
+| D1 | Pin zod version? | needs_human | — | — |
+| D2 | Use existing Session helper vs new | agent_resolved | Reuse lib/session.ts | explore brief §Critical Files |
+```
+
+- `id` — `D1`, `D2`, … unique within the change. Stable: never renumber, and
+  never reuse an id for a different question.
+- `question` — one line, answerable. Not a topic ("auth") but a decision
+  ("store the session in a cookie or in Redis?").
+- `class` — exactly `needs_human` or `agent_resolved`. Nothing else.
+- `resolution` — what was decided, in words.
+- `evidence` — where the answer came from.
+
+Use `—` for a cell with no value. `-` and an empty cell mean the same thing.
+Escape any literal `|` inside a cell as `\|`.
+
+---
+
+## The two classes
+
+| Class | Meaning |
+|-------|---------|
+| `needs_human` | Product, policy, pricing, legal, security-posture, pinned-version, or tenancy-boundary judgement the repo cannot answer. **Stops continuity.** |
+| `agent_resolved` | Answered from the repo, the explore brief, or a stated default — and written down. |
+
+There is no third class. A row that is neither is a malformed row.
+
+**Route to `needs_human` when in doubt.** A wrong `agent_resolved` ships an
+unreviewed product decision; a needless `needs_human` costs one question.
+
+---
+
+## When to write a row
+
+**Explore** — before the brief is finished:
+
+- Every item under `## Pending Clarifications` gets a `needs_human` row.
+- Every item under `## Assumptions Made` gets an `agent_resolved` row, with the
+  evidence pointing at the brief section or the file that justified it.
+
+**Spec** — while writing `proposal.md` / `design.md` / `tasks.md`:
+
+- Every open question that surfaces mid-flight gets a row before it is acted
+  on — never resolve an ambiguity silently in the design prose.
+- Every `agent_resolved` decision must also appear as a written assumption in
+  `design.md`, referenced by id (`D2`).
+- Carry forward the rows explore wrote; do not start a fresh ledger.
+
+**Answering a `needs_human` row:** edit the row in place — flip the class to
+`agent_resolved`, write the human's answer into `resolution`, and cite the
+human in `evidence` (for example `human decision 2026-08-12`). Do not delete
+the row; the history of what needed a person is the point.
+
+---
+
+## The `agent_resolved` evidence requirement
+
+`agent_resolved` is a **claim**, and it is audited.
+
+`interlock ledger <change>` checks all three parts of the claim. A row is
+**invalid** when it claims `agent_resolved` and any of these is true:
+
+- `resolution` is empty (`—`, `-`, `n/a`, `tbd`, blank), or
+- `evidence` is empty, or
+- the row's `id` appears nowhere in the change's `design.md`.
+
+An invalid row is treated as **unresolved** and blocks continuity exactly like
+`needs_human`. Writing the word `agent_resolved` is not a decision; saying what
+was decided and why is.
+
+Good evidence is a pointer someone else can follow:
+
+- `lib/session.ts:42` — the existing helper
+- `explore brief §Critical Files`
+- `openspec/specs/auth/spec.md §Scenario: expired token`
+- `human decision 2026-08-12`
+
+Not evidence: `obvious`, `standard practice`, `see above`, an empty cell. These
+are matched as the **whole cell**, after casing, surrounding whitespace and a
+trailing period are folded — so `Obvious.` is rejected the same way `obvious`
+is, while `lib/session.ts:42 — the obvious existing helper` is real evidence and
+is accepted.
+
+**The `design.md` reference.** The id is matched as a token anywhere in
+`design.md`, not as a heading: this contract does not say *where* in the design
+a decision has to be recorded, only that it is. A `design.md` that is missing or
+cannot be read makes every reference **unresolvable** — it is never treated as a
+document that happens to contain every id.
+
+---
+
+## What blocks continuity
+
+Continuity stops when **any** of these is true:
+
+1. One or more valid `needs_human` rows remain.
+2. One or more rows are invalid — bad class, missing id or question, wrong
+   column count, or an unsubstantiated `agent_resolved`.
+
+3. The ledger is **missing**, or present and unparseable.
+
+A ledger that cannot be parsed is never reported as empty. An empty ledger
+reads as "nothing needs a human", so unreadable rows are surfaced and blocking,
+not dropped.
+
+**An absent `decisions.md` is a failure of the audit, not an empty result.**
+`interlock ledger` exits non-zero and says *missing* — distinguishably from
+*present and empty*, and from *unparseable*. The likeliest way this audit fails
+is that nobody wrote the file, so that is the case it refuses to pass. If a
+change genuinely raised no ambiguity, write the ledger with its heading and no
+rows: an empty ledger is a statement, an absent one is a silence.
+
+---
+
+## Presenting blocked rows
+
+When decisions block, show **only** the blocking rows — id, question, and where
+the artifacts are. Do not ask a human to re-read the whole spec; they are here
+to answer questions, not to audit markdown.

package/shared/EXPLORE-BRIEF.md

@@ -0,0 +1,96 @@
+# Explore Brief — Spec Contract
+
+Durable handoff from `/interlock:explore` into `/interlock:spec`. Lives on disk
+so `/interlock:spec` can reload discovery after prompt-cache expiry or `/clear`
+without re-deriving it from chat.
+
+**Path:** `.claude/handoff/explore-<slug>-<YYYYMMDD-HHMMSS>.md`  
+Slug = topic or suggested change name in kebab-case. Same handoff directory
+across a context reset.
+
+**When to write**
+
+- **Required** in autonomous explore mode (exit criterion).
+- **Optional** in conversational explore when the user asks to “save
+  exploration” / “handoff for spec”.
+
+**Bound the brief** (~2–6k tokens): make it decision-oriented; cite paths and
+line refs; prefer pointers over pasted code; ASCII diagrams when useful. The
+brief carries conclusions into `/interlock:spec`, not an inventory of every
+file the investigators touched.
+
+---
+
+## Template (stable — `/interlock:spec` depends on these headings)
+
+```markdown
+# Explore Brief: <slug>
+
+## Meta
+- mode: autonomous | conversational-capture
+- topic: <one-line topic>
+- created: <ISO-8601 timestamp>
+- suggested_change_name: <kebab-case or none>
+- related_change: <existing openspec change name or none>
+
+## Problem / Intent
+<!-- Crystallized problem statement and desired outcome -->
+
+## Codebase Findings
+<!-- Decision-relevant conclusions about how it works today, constraints and
+     patterns. Cite file:line spans; do not enumerate every file touched. -->
+
+## Critical Files
+<!-- path:line — why it matters (citations over pasted code) -->
+
+## Options Considered
+<!-- Each option: tradeoffs + evidence; mark recommended vs rejected -->
+
+## Recommended Direction
+<!-- Chosen approach and why; pointer back to Options if needed -->
+
+## Assumptions Made
+<!-- Defaults taken when product intent was ambiguous -->
+
+## Pending Clarifications
+<!-- Only true product/policy unknowns that cannot be resolved from the repo.
+     In autonomous mode: list for the human later — do not AskUser mid-explore. -->
+
+## Risks / Gaps
+<!-- What could go wrong; layers not swept; contradictions -->
+
+## Spec Ready Checklist
+- [ ] Problem / intent is clear enough to name a change
+- [ ] Recommended direction is stated (or options narrowed to ≤2)
+- [ ] Critical files listed with why
+- [ ] Assumptions recorded
+- [ ] Residual unknowns are product/policy only (not “I didn’t look”)
+```
+
+---
+
+## Section rules
+
+| Section | Rule |
+|---------|------|
+| **Codebase Findings** | Conclusions + cited `file:line` spans only. Omit exhaustive file inventories and raw investigator output. |
+| **Critical Files** | Paths + line refs + why. No large code dumps. |
+| **Options Considered** | Tradeoffs + evidence. Mark recommended vs rejected with rationale. |
+| **Pending Clarifications** | Repo-unresolvable items only. Autonomous mode lists them; does not ask mid-explore. |
+| **Assumptions Made** | Prefer reasonable defaults over blocking; record them here. |
+| **Spec Ready Checklist** | If unchecked items remain that block a correct proposal, say so in chat when pointing at the brief. |
+
+## Chat reply after write
+
+Do **not** re-dump the full brief into chat. Reply with:
+
+1. Path to the brief
+2. A 3–5 line summary (intent + recommended direction + top risk)
+3. “Ready for `/interlock:spec`” (or the Copilot/VS Code equivalent)
+
+## Spec consumption
+
+`/interlock:spec` auto-finds the latest matching brief under
+`.claude/handoff/explore-*.md` (see that skill). Override: user passes an
+explicit brief path. Prefer brief recommendations over re-exploring; reopen
+code only for gaps or contradictions.

package/shared/INVARIANT-SWEEP.md

@@ -0,0 +1,57 @@
+# Invariant Sweep — The Unit of Work Is the Invariant, Not the File
+
+Shared discipline for all interlock skills that plan, review, or apply changes touching **shared or derived state**. Companion to `CONTEXT-HYGIENE.md`.
+
+## The problem
+
+Every gate after exploration is scope-leashed by design — `/interlock:spec` sees only artifacts, `/interlock:review-code` / `/interlock:ship` see only the diff. That leash is correct for most changes and wrong for exactly one class: **a change that transforms a value read in more than one place.**
+
+When a change normalizes, trims, encodes, or canonicalizes a value stored on shared/derived state, some code paths get updated and others don't. The updated paths are in the diff; the stale readers are not. A diff-scoped or artifact-scoped gate is **structurally blind** to the stale readers — it cannot see the bug, because the bug lives in a file the change never touched.
+
+Concrete failure (the one that motivated this file): a dedup change lower-cased an email in the write path. Readers that still compared the **raw** email case-sensitively silently stopped matching. No BDD scenario forced enumeration of mixed-case consumers; no reviewer was licensed to leave the diff. Only an ad-hoc agent sweep — the one thing with no scope leash — caught it.
+
+## The rule
+
+**When a change alters an invariant on shared or derived state, the unit of work is the invariant, not the file.** The change is not complete, and the review is not complete, until *every reader of that value* has been enumerated and confirmed to read the canonical form.
+
+Two halves, both mandatory:
+
+1. **Normalize once at the boundary, not at each call site.** If a value must be transformed, the design MUST state where the single canonical transform lives, and assert every consumer reads the canonical form. Scattering the transform across call sites guarantees one gets missed.
+2. **Sweep the consumers.** Enumerate every reader repo-wide — not just the diff. Any reader still consuming the raw/untransformed form, or comparing it case/format-sensitively, is part of the change, not opportunistic creep.
+
+## When it fires
+
+Fire the sweep when the change touches a value that is **stored on a shared object or derived and read elsewhere**. Signals:
+
+- A session / JWT / token field, request context, or auth principal
+- A cache key, map key, dedup key, or any identity used in a comparison, `Set`/`Map`, or `WHERE`/`===`
+- A normalized form of user input: casing, trimming, encoding, Unicode normalization, ID/slug canonicalization
+- Anything the design describes with "normalize", "canonical", "dedupe", "match", "lookup by"
+
+If none of these apply — the change is genuinely local, one reader, no shared identity — the sweep does **not** fire, and the normal diff/artifact leash holds. Do not sweep every change; that defeats the leash's purpose.
+
+## How to sweep
+
+**Structural + semantic — two layers**:
+
+1. **Structural (deterministic):** enumerate every reader of the value — the field name, its getter, the map/cache key, the comparison sites. Prefer the graph when present:
+   ```bash
+   interlock-graph consumers <field-or-symbol>
+   ```
+   Then `grep`/search the whole repo to catch **dynamic/stringly** readers the graph misses (bracket access, computed keys, SQL, codegen). Enumerate exhaustively. This is a mechanical enumeration, not a judgment call.
+2. **Semantic (judgment):** for each reader found, decide — does it consume the **canonical** form, or the **raw** form? A reader on the raw form, or a case/format-sensitive comparison, is a defect.
+
+**When fanning out** (e.g. in `/interlock:explore` Pattern 4): assign **one agent per layer** — data / API / business-logic / frontend / tests — and make the layers **disjoint** so findings merge without overlap or double-counting. Seed each agent with the relevant `interlock-graph consumers` / module slice from `GRAPH_REPORT.md` when the graph exists. Each agent enumerates readers in its layer only; you merge and flag the raw-form readers in synthesis.
+
+## Severity
+
+A reader consuming the raw form of a value the change canonicalized elsewhere is a **BLOCKER** — it is a live correctness bug with a data-dependent trigger (it fails only for the inputs that differ pre/post-transform, which is exactly the set no happy-path test exercises).
+
+## Skill integration
+
+- **interlock-graph** — `consumers` is the structural first pass when `.claude/graph/graph.json` exists.
+- **/interlock:explore** — Pattern 4 (Impact Analysis) is the mandatory fan-out for this class. It MUST fire on the signals above regardless of how the user phrased the question.
+- **/interlock:spec** — the BDD edge-case categories include casing/encoding/whitespace/Unicode; the design principle "normalize once at the boundary" is mandatory for identity/shared-value changes.
+- **review-code** — the "breaking API contracts" check is widened from shape to semantic value: graph consumers then grep repo-wide for raw-form readers and flag them BLOCKER. This gate is the licensed exception to the diff leash.
+
+When adding a new skill that plans or reviews changes to shared/derived state, wire it to this discipline.