harness-everything 0.2.2 → 0.4.0

package/hooks/scripts/stop-gate.js

@@ -1,80 +1,80 @@
-#!/usr/bin/env node
-/**
- * Stop Gate (Stop hook - Claude Code only)
- * The pre-delivery gate (verification-loop) was prose-only, and prose decays
- * as context grows. This makes the one check that matters mechanical: ending
- * the turn with edits that were never followed by a successful
- * verification-ish command (test/build/lint - tracked by state-persist.js)
- * while uncommitted changes sit in the tree gets bounced back ONCE per edit
- * batch. Objective facts only; fails open on any error.
- */
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-function decide(payload) {
-  try {
-    // Loop guard: if this stop already resulted from a Stop-hook block,
-    // always let it through - one bounce is the contract, never a cage.
-    if (payload && payload.stop_hook_active) {
-      process.exit(0);
-    }
-
-    const root = getWorkspaceRoot();
-    const sessionDir = getSessionDir(root, payload && payload.session_id);
-    const handoffFile = path.join(sessionDir, 'handoff-state.json');
-    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
-
-    if (!fs.existsSync(handoffFile)) process.exit(0);
-    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
-    const lastEditAt = handoff.lastEditAt || 0;
-    const lastVerifyAt = handoff.lastVerifyAt || 0;
-
-    // No edits this session, or verification already ran after the last edit.
-    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
-
-    // One bounce per edit batch: if we already blocked for this exact edit
-    // timestamp, the model either verified (which moves lastVerifyAt) or
-    // explicitly chose not to - don't nag twice for the same batch.
-    let gate = {};
-    if (fs.existsSync(gateFile)) {
-      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
-    }
-    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
-
-    // Only relevant when unverified work is actually sitting in the tree.
-    const dirty = execSync('git status --porcelain', {
-      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
-    }).trim();
-    if (!dirty) process.exit(0);
-
-    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
-
-    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
-    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
-    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
-    console.error(`This gate bounces at most once per edit batch.`);
-    process.exit(2);
-  } catch (err) {
-    // Fail open - a broken gate must never trap the session.
-    process.exit(0);
-  }
-}
-
-let inputData = '';
-const timeout = setTimeout(() => {
-  decide(null);
-}, 200);
-
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  clearTimeout(timeout);
-  let payload = null;
-  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
-  decide(payload);
-});
-process.stdin.on('error', () => {
-  clearTimeout(timeout);
-  decide(null);
-});
+#!/usr/bin/env node
+/**
+ * Stop Gate (Stop hook - Claude Code only)
+ * The pre-delivery gate (verification-loop) was prose-only, and prose decays
+ * as context grows. This makes the one check that matters mechanical: ending
+ * the turn with edits that were never followed by a successful
+ * verification-ish command (test/build/lint - tracked by state-persist.js)
+ * while uncommitted changes sit in the tree gets bounced back ONCE per edit
+ * batch. Objective facts only; fails open on any error.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function decide(payload) {
+  try {
+    // Loop guard: if this stop already resulted from a Stop-hook block,
+    // always let it through - one bounce is the contract, never a cage.
+    if (payload && payload.stop_hook_active) {
+      process.exit(0);
+    }
+
+    const root = getWorkspaceRoot(payload);
+    const sessionDir = getSessionDir(root, payload && (payload.session_id || payload.sessionId));
+    const handoffFile = path.join(sessionDir, 'handoff-state.json');
+    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
+
+    if (!fs.existsSync(handoffFile)) process.exit(0);
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    const lastEditAt = handoff.lastEditAt || 0;
+    const lastVerifyAt = handoff.lastVerifyAt || 0;
+
+    // No edits this session, or verification already ran after the last edit.
+    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
+
+    // One bounce per edit batch: if we already blocked for this exact edit
+    // timestamp, the model either verified (which moves lastVerifyAt) or
+    // explicitly chose not to - don't nag twice for the same batch.
+    let gate = {};
+    if (fs.existsSync(gateFile)) {
+      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
+    }
+    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
+
+    // Only relevant when unverified work is actually sitting in the tree.
+    const dirty = execSync('git status --porcelain', {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (!dirty) process.exit(0);
+
+    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
+
+    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
+    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
+    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
+    console.error(`This gate bounces at most once per edit batch.`);
+    process.exit(2);
+  } catch (err) {
+    // Fail open - a broken gate must never trap the session.
+    process.exit(0);
+  }
+}
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  decide(null);
+}, 200);
+
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  decide(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  decide(null);
+});

package/hooks/scripts/subagent-scope-guard.js

@@ -1,88 +1,194 @@
-#!/usr/bin/env node
-/**
- * Subagent Scope Guard (PreToolUse + PostToolUse: Task)
- * Grounded in a real incident: a subagent briefed as "read-only, verify and
- * report a verdict" still had full tool access by default and made
- * substantial unrequested edits (a GitBook restructure, ~115 deleted lines)
- * in a large parallel fan-out. It was only caught because someone happened
- * to run `git status` on the whole repo afterward.
- *
- * This hook makes that check automatic instead of relying on remembering to
- * do it: PreToolUse snapshots `git status --porcelain` the first time a Task
- * spawn starts (shared baseline across any parallel/nested Task calls in the
- * same burst), PostToolUse diffs the current status against that baseline
- * and surfaces every changed file - not just the ones the task was expected
- * to touch, since "expected" can't be reliably inferred from a natural-
- * language task brief. It cannot block (the subagent already ran), only
- * makes the diff impossible to miss.
- * Fails open on any error - this is visibility, not a hard gate.
- */
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-
-function gitStatus(root) {
-  try {
-    return execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch (err) {
-    return null;
-  }
-}
-
-let inputData = '';
-process.stdin.on('data', chunk => { inputData += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(inputData);
-    if (payload.tool_name !== 'Task') process.exit(0);
-
-    const root = getWorkspaceRoot();
-    const stateFile = path.join(getSessionDir(root, payload.session_id), 'subagent-scope-state.json');
-
-    if (payload.hook_event_name === 'PreToolUse') {
-      // Only set the baseline if one isn't already pending - parallel/nested
-      // Task calls in the same burst share it, so the eventual diff covers
-      // everything the whole burst touched, not just the last one.
-      if (!fs.existsSync(stateFile)) {
-        const status = gitStatus(root);
-        if (status !== null) {
-          fs.writeFileSync(stateFile, JSON.stringify({ baseline: status }, null, 2), 'utf8');
-        }
-      }
-      process.exit(0);
-    }
-
-    if (payload.hook_event_name === 'PostToolUse') {
-      if (!fs.existsSync(stateFile)) process.exit(0);
-
-      const { baseline } = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-      const current = gitStatus(root);
-      if (current === null) process.exit(0);
-
-      const baselineLines = new Set(baseline.split('\n').filter(Boolean));
-      const currentLines = current.split('\n').filter(Boolean);
-      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
-
-      if (newlyChanged.length > 0) {
-        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed since this Task burst started:`);
-        newlyChanged.forEach(line => console.error(`  ${line}`));
-        console.error(`Confirm every one of these was actually in scope before trusting or committing this output.`);
-        console.error(`Do not "git add -A" - stage files explicitly by path so anything unexpected here stays visible.`);
-      }
-
-      // Roll the baseline forward so the next Task burst only reports what's
-      // new since this report, not the same files over and over.
-      fs.writeFileSync(stateFile, JSON.stringify({ baseline: current }, null, 2), 'utf8');
-
-      if (newlyChanged.length > 0) {
-        process.exit(2);
-      }
-      process.exit(0);
-    }
-
-    process.exit(0);
-  } catch (err) {
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+/**
+ * Subagent Scope Guard (PreToolUse + PostToolUse: Task/Agent and
+ * SubagentStart/SubagentStop)
+ *
+ * Phase 3 snapshots both `git status --porcelain` and any active Fable stage
+ * write sets at the beginning of a subagent burst. At the end it classifies
+ * newly changed paths as declared, ambiguous, or out-of-scope. Machine-
+ * readable write sets may therefore clear expected changes without weakening
+ * the conservative legacy path: when no stage contract exists, any new
+ * change still exits 2 and requires explicit review.
+ *
+ * `writeSet: []` means read-only. Worker attribution is used when the host
+ * exposes a worker/subagent id and the stage contract records the same id;
+ * otherwise the audit remains stage-level. The hook never infers scope from
+ * a natural-language task brief.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const {
+  getSessionDir,
+  getSessionId,
+  getStateRoot,
+  getWorkspaceRoot,
+} = require('./lib/harness-state');
+const {
+  atomicWriteJson,
+  getActiveRunContracts,
+  getWorkerId,
+  stagesForChangedPath,
+} = require('./lib/fable-contracts');
+
+function gitStatus(root) {
+  try {
+    return execSync('git status --porcelain', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (_) {
+    return null;
+  }
+}
+
+function snapshotContracts(stateRoot, sessionId) {
+  return getActiveRunContracts(stateRoot, sessionId).map(({ contract }) => ({
+    planId: contract.planId,
+    runId: contract.runId,
+    stageId: contract.stageId,
+    sessionId: contract.sessionId || null,
+    workerId: contract.workerId || null,
+    writeSet: Array.isArray(contract.writeSet) ? contract.writeSet : [],
+  }));
+}
+
+function classifyChanges(newlyChanged, declaredContracts, payload) {
+  const workerId = getWorkerId(payload);
+  let scopedContracts = declaredContracts;
+  if (workerId) {
+    const attributable = declaredContracts.filter(contract => contract.workerId === workerId);
+    if (attributable.length > 0) scopedContracts = attributable;
+  }
+  const entries = scopedContracts.map(contract => ({ contract }));
+  const expected = [];
+  const ambiguous = [];
+  const outOfScope = [];
+
+  for (const statusLine of newlyChanged) {
+    const matches = stagesForChangedPath(statusLine, entries);
+    if (matches.length === 1) {
+      const contract = matches[0].contract;
+      expected.push({
+        statusLine,
+        planId: contract.planId,
+        runId: contract.runId,
+        stageId: contract.stageId,
+        workerId: contract.workerId || workerId || null,
+      });
+    } else if (matches.length > 1) {
+      ambiguous.push({
+        statusLine,
+        stages: matches.map(({ contract }) => ({
+          planId: contract.planId,
+          runId: contract.runId,
+          stageId: contract.stageId,
+          workerId: contract.workerId || null,
+        })),
+      });
+    } else {
+      outOfScope.push({ statusLine, workerId: workerId || null });
+    }
+  }
+
+  return { workerId: workerId || null, expected, ambiguous, outOfScope };
+}
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    const event = payload.hook_event_name;
+    const toolName = payload.tool_name || payload.tool;
+    const isSubagentEvent = event === 'SubagentStart' || event === 'SubagentStop';
+    if (!isSubagentEvent && toolName !== 'Task' && toolName !== 'Agent') process.exit(0);
+
+    const root = getWorkspaceRoot(payload);
+    const sessionId = getSessionId(payload);
+    const sessionDir = getSessionDir(root, sessionId, payload);
+    const stateRoot = getStateRoot(root, payload);
+    const stateFile = path.join(sessionDir, 'subagent-scope-state.json');
+
+    if (event === 'PreToolUse' || event === 'SubagentStart') {
+      if (!fs.existsSync(stateFile)) {
+        const status = gitStatus(root);
+        if (status !== null) {
+          atomicWriteJson(stateFile, {
+            startedAt: new Date().toISOString(),
+            baseline: status,
+            contracts: snapshotContracts(stateRoot, sessionId),
+          });
+        }
+      }
+      process.exit(0);
+    }
+
+    if (event === 'PostToolUse' || event === 'SubagentStop') {
+      if (!fs.existsSync(stateFile)) process.exit(0);
+
+      let state;
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (_) { process.exit(0); }
+      const current = gitStatus(root);
+      if (current === null) process.exit(0);
+
+      const baselineLines = new Set(String(state.baseline || '').split('\n').filter(Boolean));
+      const currentLines = current.split('\n').filter(Boolean);
+      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
+      const declaredContracts = Array.isArray(state.contracts) ? state.contracts : [];
+      const classified = classifyChanges(newlyChanged, declaredContracts, payload);
+      const audit = {
+        schemaVersion: 1,
+        sessionId: sessionId || null,
+        observedAt: new Date().toISOString(),
+        declaredContractCount: declaredContracts.length,
+        ...classified,
+      };
+      atomicWriteJson(path.join(sessionDir, 'subagent-scope-last.json'), audit);
+
+      if (newlyChanged.length === 0) {
+        console.log('[Subagent Scope Guard] No new changed files detected during the subagent burst.');
+      } else if (declaredContracts.length === 0) {
+        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed with no machine-readable writeSet contract:`);
+        newlyChanged.forEach(line => console.error(`  ${line}`));
+        console.error('Confirm every path was actually in scope before trusting or committing this output.');
+      } else {
+        for (const entry of classified.expected) {
+          console.log(`[Subagent Scope Guard] in-scope ${entry.statusLine} -> ${entry.planId}/${entry.runId}/${entry.stageId}${entry.workerId ? ` worker=${entry.workerId}` : ''}`);
+        }
+        for (const entry of classified.ambiguous) {
+          console.error(`[Subagent Scope Guard] ambiguous scope ${entry.statusLine}; matches ${entry.stages.map(stage => `${stage.runId}/${stage.stageId}`).join(', ')}`);
+        }
+        for (const entry of classified.outOfScope) {
+          console.error(`[Subagent Scope Guard] OUT-OF-SCOPE ${entry.statusLine}${entry.workerId ? ` worker=${entry.workerId}` : ''}`);
+        }
+      }
+
+      atomicWriteJson(stateFile, {
+        startedAt: new Date().toISOString(),
+        baseline: current,
+        contracts: snapshotContracts(stateRoot, sessionId),
+      });
+
+      const violated = declaredContracts.length === 0
+        ? newlyChanged.length > 0
+        : classified.ambiguous.length > 0 || classified.outOfScope.length > 0;
+      if (violated) {
+        console.error('Do not "git add -A"; stage files explicitly so unexpected paths stay visible.');
+        process.exit(2);
+      }
+      process.exit(0);
+    }
+
+    process.exit(0);
+  } catch (_) {
+    // This is a post-execution visibility gate. Runtime errors fail open; the
+    // actionGate in Phase 5 has a stricter fail-ask policy for side effects.
+    process.exit(0);
+  }
+});
+
+module.exports = {
+  classifyChanges,
+};

package/hooks/scripts/subagent-start.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+// OpenAI's SubagentStart event has no Claude Task tool name. The shared guard
+// records the baseline, while this adapter adds the subagent's scope reminder
+// through the OpenAI hook output contract.
+process.on('exit', () => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: [
+        'Harness subagent scope guard is active.',
+        'Keep this worker within the requested scope and report every changed path before handoff.'
+      ].join('\n')
+    }
+  }) + '\n');
+});
+
+require('./subagent-scope-guard');

package/hooks/scripts/subagent-stop.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+// The shared guard emits exit code 2 and stderr when a subagent changed files;
+// OpenAI/Codex treats that as a continuation signal for SubagentStop.
+require('./subagent-scope-guard');

package/improve-codebase-architecture/SKILL.md

@@ -1,44 +1,38 @@
 ---
 name: improve-codebase-architecture
-description: Discovers and transforms shallow modules into deep ones to improve testability and AI navigability.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Discovers and transforms shallow or bloated modules into deep, SRP-compliant ones by splitting oversized objects/functions, extracting seams, and decoupling interfaces.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
-# Improve Codebase Architecture (Deep Architectural Optimization)
+# Improve Codebase Architecture (Deep & SRP Refactoring)
 
 ## 📋 Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Project shows tech debt, overly coupled modules, or the user requests to "refactor / improve architecture quality". |
-| **Expected Output** | A "Deepening Opportunities" report naming shallow modules and improperly coupled seams, followed (after human approval) by `tdd`-guarded refactoring. |
-| **State Mutations** | Refactors module boundaries/interfaces; may add Characterization Tests before touching legacy code that has no existing coverage. |
-| **Enforcement Gate** | Blind refactoring is **PROHIBITED** — must scan `CONTEXT.md`/ADRs/interfaces first. Refactoring code with no test safety net **MUST** start with Characterization Tests. More than 3 cascading compile errors **MUST** trigger `zoom-out` and rollback, not continued patching. |
-
-Triggered when a project is full of "Tech Debt", modules are overly coupled, or the user requests to "refactor / improve architecture quality". This skill aims to transform "Shallow" modules into "Deep" modules to enhance testability and AI navigability.
-
-## 1. Architectural Exploration & Discovery `[Discover]`
-- **Blind Refactoring Prohibited**: Before proposing any modification suggestions, you MUST first scan `CONTEXT.md`, `docs/adr/`, and core interface definitions (Interfaces/Types).
-- Identify "Shallow Modules" (interfaces that are complex but have very little internal implementation).
-- Identify improperly coupled boundaries (Seams).
-
-## 2. Analysis & Proposal `[Think]`
-Use consistent domain terminology (Module, Interface, Implementation, Depth, Seam, Adapter) to communicate with the human.
-- Submit a "Deepening Opportunities" report to the user.
-- Explicitly point out which modules should be encapsulated and which boundaries (Seams) should be extracted into Adapters.
-
-## 3. Implementation Refactoring `[Try]`
-- After gaining human approval, launch `tdd` mode.
-- **Iron Rule of Refactoring**: MUST be done under the safety net of test coverage. If there are no tests, the first step MUST be to "write Characterization Tests for the legacy code" before modifying the architecture.
-
-## 4. Circuit Breaker & Evolution `[Summarize] & [Self-Evolve]`
-- If refactoring triggers more than 3 cascading compilation errors that cannot be fixed immediately, trigger the `zoom-out` circuit breaker and Rollback.
-- Write the discovered coupling traps into `self-evolve` memory, ensuring future newly generated code does not repeat the same mistakes.
-
-## Deep Reference Guides
-For precise architectural paradigms and deep module analysis, refer to:
-- `improve-codebase-architecture/guides/DEEPENING.md` — Deepening opportunities & modular depth rules
-- `improve-codebase-architecture/guides/INTERFACE-DESIGN.md` — Principles of interface design and seams
-- `improve-codebase-architecture/guides/LANGUAGE.md` — Language-specific refactoring and pattern guidelines
-- `improve-codebase-architecture/guides/HTML-REPORT.md` — Creating visual reports with Mermaid diagrams
+| **Trigger / Input** | "refactor architecture", "split object/class", "apply SRP", tech debt |
+| **Expected Output** | SRP proposal, Characterization Test safety net, TDD-guided extraction. |
+| **State Mutations** | Extracts classes/functions/objects; adds characterization tests. |
+| **Enforcement Gate** | Scan docs first; Characterization Tests before refactoring untested code; >3 cascading errors → rollback + `zoom-out`. |
+
+## Workflow
+
+1. `[Discover]`: no blind refactoring — scan `CONTEXT.md`, `docs/adr/`, core interfaces first. Targets: SRP violations (>300 lines / >10 complexity), shallow modules, coupled seams.
+2. `[Think]`: present the Deepening & SRP proposal (object splitting + seam abstraction) until approved.
+3. `[Try]`: launch `tdd`; Characterization Tests first if legacy code lacks tests; extract incrementally, verifying tests after each change.
+4. `[Summarize]`/`[Self-Evolve]`: >3 cascading errors → rollback + `zoom-out`; record traps in `self-evolve`.
+
+Deep dive: <this-skill-dir>/references/README.md
+
+## USE FOR:
+- "refactor this architecture"
+- "split this oversized class"
+- "apply SRP here"
+- "decouple these modules"
+
+## DO NOT USE FOR:
+- Features or bugfixes (use `tdd`)
+- Style-only cleanups with no structure change

package/improve-codebase-architecture/guides/DEEPENING.md

@@ -1,37 +1,37 @@
-# Deepening
-
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
-
-## Dependency categories
-
-When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
-
-### 1. In-process
-
-Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
-
-### 2. Local-substitutable
-
-Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
-
-### 3. Remote but owned (Ports & Adapters)
-
-Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
-
-Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
-
-### 4. True external (Mock)
-
-Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
-
-## Seam discipline
-
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
-- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
-
-## Testing strategy: replace, don't layer
-
-- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
-- Write new tests at the deepened module's interface. The **interface is the test surface**.
-- Tests assert on observable outcomes through the interface, not internal state.
-- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.