@rryando/arcs 4.0.0 → 4.2.0

package/opencode/arcs/skills/install-claude-code-hook/SKILL.md

@@ -1,143 +1,23 @@
 ---
 name: install-claude-code-hook
-description: Use when retrofitting the Claude Code session-bridge hook onto an already-inited ARCS project — triggers "install the claude code hook", "enable session bridge", "set up hook for this project", "hook up claude code to arcs", "the arcs web UI can't see my session". Claude Code only; detects existing state, then installs after explicit confirmation.
+description: Install the ARCS session-bridge hook into an existing Claude Code workspace
 ---
 
-# Skill: install-claude-code-hook
+# Install Claude Code Hook
 
-## When
+## Boundary
 
-The project is already in the DAG but its workspace never got the session-bridge hook — usually because `arcs project init` predated the offer, or the offer was declined. Triggers: "install the claude code hook", "enable session bridge", "set up hook for this project", "hook up claude code to arcs", "the arcs web UI can't see my session".
+Claude Code only. If the current harness is not Claude Code, stop. The hook changes `.claude/settings.local.json`, so obtain explicit confirmation before using `--write`.
 
-> **Claude-Code-only skill.** Step 0 is self-knowledge, not detection: if you are not running as Claude Code, say so and stop. The hook registers into Claude Code's own settings file; installing it from another harness configures a client that will never run it. There is no environment-variable heuristic here by design — you know your own harness.
+## Method
 
-> **Executes, unlike the proposal skills.** After explicit user confirmation this skill runs `arcs hooks install-claude-code <slug> --write` itself. That is not a `writing-knowledge`-style "propose, don't execute" case: the write is local machine config (`.claude/settings.local.json`), not a durable ARCS DAG mutation. It mirrors `promptAndInstallClaudeCodeHook`, which already executes directly inside `arcs project init` behind the same confirm.
+1. Run `arcs hooks status <slug> --json`.
+2. If already installed for this slug, report a no-op.
+3. Explain the file written, registered events, local token, and that a new Claude Code session is required.
+4. If the hook points at another slug, warn that installation will repoint it and confirm that effect.
+5. After explicit confirmation, run `arcs hooks install-claude-code <slug> --write --json` once.
+6. Report `settingsPath`, events, and next-session requirement.
 
-## Flow
+Do not hand-edit Claude settings. A malformed settings file is a stop condition: surface the CLI error and do not repair, reformat, or delete it. Do not rerun installation for reassurance because it may rotate the token.
 
-```mermaid
-flowchart TD
-    classDef decision fill:#f59e0b,color:#fff
-    classDef terminal fill:#22c55e,color:#fff
-
-    A{Running as Claude Code?}:::decision -->|no| Stop[State Claude-Code-only, stop]:::terminal
-    A -->|yes| B[arcs hooks status slug --json]
-    B --> C{installed?}:::decision
-    C -->|false| D[Explain the bridge, ask to install]
-    C -->|true| E{matchesCurrentSlug?}:::decision
-    E -->|true| F[Report found, no-op]:::terminal
-    E -->|false| G[Warn: installing repoints matchedSlugs, re-confirm]
-    D -->|declines| H[Print manual fallback, no mutation]:::terminal
-    G -->|declines| H
-    D -->|explicit yes| I[arcs hooks install-claude-code slug --write]
-    G -->|explicit yes| I
-    I --> J{ok?}:::decision
-    J -->|true| K[Report settingsPath + events + new-session note]:::terminal
-    J -->|false| L[Surface the CLI error verbatim, no repair]:::terminal
-```
-
-## CLI Primer
-
-```bash
-arcs hooks status <slug> --json
-arcs hooks install-claude-code <slug> --write --json
-```
-Discovery: `arcs --commands --json`. Mutating commands run directly — no token.
-
-`hooks status` is read-only and rotates nothing, so it is safe to call as many times as you like. Its envelope:
-
-| Field | Meaning |
-|---|---|
-| `installed` | `true` only when ALL THREE events (`SessionStart`, `UserPromptSubmit`, `SessionEnd`) are registered. A partial registration is a broken bridge and reports `false`. |
-| `matchesCurrentSlug` | The registered hook carries `ARCS_HOOK_SLUG=<slug>` for the project you asked about. |
-| `matchedSlugs` | Every slug found on a matching hook command — how you see a hook wired to a *different* project. |
-| `hookScriptPath` | Absolute path of the script the hook entry runs; the key both status and install match on. |
-
-`hooks install-claude-code <slug> --write` performs the write via the same consent-gated merge `arcs project init` uses, and returns `settingsPath` and `events` alongside the pre-existing `token` / `hookScriptPath` / `serverUrl` / `settingsSnippet` fields. Omitting `--write` keeps the old snippet-only behavior — no file is touched — which is the manual fallback.
-
-## Constraints
-
-- Step 0 first: not Claude Code → state that this skill is Claude-Code-only and stop. No install, no status call.
-- Never write without EXPLICIT user confirmation. Default posture is do nothing; silence, ambiguity, or "sure, whatever you think" is not consent.
-- `matchesCurrentSlug: false` with a non-empty `matchedSlugs` demands a SECOND, explicit re-confirmation — the merge is keyed on `hookScriptPath`, so one workspace holds one hook and installing silently repoints it away from the other slug.
-- Never edit `.claude/settings.local.json`, `.claude/settings.json`, or `~/.claude/settings.json` yourself. `--write` is the only sanctioned mutation path.
-- Install failure (malformed existing settings file) → surface the CLI's own error message verbatim. Do NOT repair, reformat, or delete the settings file from this skill; the CLI aborted precisely so a hand-edited file is not clobbered.
-- Do not rerun `--write` "to be safe" — every run rotates the token and invalidates the previously installed entry.
-- Pass `--url` only when the user runs `arcs web` on a non-default port; the hook posts to `http://127.0.0.1:4173` otherwise.
-
-## Opt-In Copy (what the user must be told before confirming)
-
-State all four, plainly, before asking:
-
-1. **What it buys them** — the ARCS web UI can see this Claude Code session, and messages queued from the UI are delivered to the next prompt.
-2. **What is written** — `<workspacePath>/.claude/settings.local.json` and nothing else. Never the global config, never a committed file; `settings.local.json` is the git-ignored variant and the token in it is a secret.
-3. **What is registered** — one script under three events: `SessionStart`, `UserPromptSubmit`, `SessionEnd`.
-4. **When it takes effect** — a NEW Claude Code session. The session asking for the install will not pick it up.
-
-## Worked Example
-
-```bash
-# 0. Self-check: you are Claude Code. If not → "This skill is Claude-Code-only." Stop here.
-
-# 1. Read-only detection (rotates nothing; safe to repeat)
-arcs hooks status arcs --json
-# → {"installed":false,"matchesCurrentSlug":false,"matchedSlugs":[],
-#    "hookScriptPath":"/…/scripts/claude-code-session-hook.mjs"}
-
-# 2. Not installed → present the opt-in copy above, then ask:
-#    "Install the Claude Code session-bridge hook for `arcs` now?"
-#    Wait for an explicit yes. Anything else → step 4.
-
-# 3. Explicit yes → install and report
-arcs hooks install-claude-code arcs --write --json
-# → {"settingsPath":"/home/u/Work/arcs/.claude/settings.local.json",
-#    "events":["SessionStart","UserPromptSubmit","SessionEnd"], …}
-# Report: settingsPath, the three events, and "start a NEW Claude Code session to pick it up".
-
-# 4. Declined → no mutation. Print the manual fallback (snippet only, writes nothing):
-arcs hooks install-claude-code arcs --json
-# Paste `settingsSnippet` into .claude/settings.local.json by hand.
-```
-
-Already-installed branch:
-
-```bash
-arcs hooks status arcs --json
-# → {"installed":true,"matchesCurrentSlug":true,"matchedSlugs":["arcs"], …}
-# Report "session-bridge hook already installed for `arcs`". No-op. Done.
-```
-
-Different-slug branch:
-
-```bash
-arcs hooks status arcs --json
-# → {"installed":true,"matchesCurrentSlug":false,"matchedSlugs":["legacy-app"], …}
-# Warn: "This workspace's hook is registered for `legacy-app`. One workspace holds
-#        one hook by design — installing for `arcs` will silently repoint it and
-#        `legacy-app` will stop reporting sessions."
-# Require a SECOND explicit confirmation, then:
-arcs hooks install-claude-code arcs --write --json
-```
-
-Failure branch:
-
-```bash
-arcs hooks install-claude-code arcs --write --json
-# → {"ok":false,"code":"hook_install_error","message":"/…/.claude/settings.local.json exists
-#     but is not valid JSON — fix it manually or delete it, then re-run
-#     `arcs hooks install-claude-code arcs`. Nothing was written."}
-# Relay that message verbatim. Do not touch the file.
-```
-
-## Exit Conditions
-
-| Condition | Action |
-|-----------|--------|
-| Not running as Claude Code | Stop. State the skill is Claude-Code-only; run nothing |
-| `installed: true` and `matchesCurrentSlug: true` | Stop. Report already installed; no-op |
-| `installed: true` and `matchesCurrentSlug: false` | Warn that installing repoints the hook away from `matchedSlugs`; require a second explicit confirmation before `--write` |
-| `installed: false` | Present the opt-in copy; install only on explicit confirmation |
-| User declines at any confirmation | Stop. No mutation. Print the manual fallback: `arcs hooks install-claude-code <slug> --json` (snippet only, no `--write`) |
-| `--write` succeeds | Report `settingsPath` and `events`; tell the user a NEW Claude Code session is required |
-| `--write` fails (e.g. malformed settings file) | Surface the CLI's error message verbatim. Attempt no repair; nothing was written |
-| Project has no workspace path (`no_workspace_paths`) | Stop. Relay the error and offer the snippet-only fallback |
+Without confirmation, offer the snippet-only command without `--write`.

package/opencode/arcs/skills/systematic-debugging/SKILL.md

@@ -1,162 +1,23 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: Diagnose bugs and failing tests from evidence before changing code
 ---
 
-# Skill: systematic-debugging
+# Systematic Debugging
 
-## When
+## Method
 
-Any bug, test failure, or unexpected behavior — before proposing fixes.
+Observe → reproduce → isolate → regression test → fix → verify.
 
-> Follows ARCS CLI Primer: `arcs --commands --json` for discovery, `--json --lean` on all calls.
+1. **Observe:** read the full error, logs, inputs, and recent relevant changes.
+2. **Reproduce:** find the smallest reliable reproduction. Add instrumentation when needed.
+3. **Isolate:** trace backward, compare a working path, and test one hypothesis at a time.
+4. **Regression test:** encode the failure when practical.
+5. **Fix:** change the root cause with the smallest targeted patch.
+6. **Verify:** show the reproduction and relevant checks pass.
 
-## Flow
+If three failed fixes do not improve the evidence, stop and question the architecture or assumptions instead of stacking another guess.
 
-```mermaid
-flowchart TD
-    classDef decision fill:#f59e0b,color:#fff
-    classDef stop fill:#ef4444,color:#fff
+Use ARCS knowledge only when a prior gotcha may save time. Capturing a durable discovery is optional, not part of the success condition.
 
-    Bug[Bug observed] --> ARCS[Check ARCS knowledge]
-    ARCS --> Found{Match found?}
-    Found -->|Yes| Verify[Verify it applies]
-    Found -->|No| Observe
-
-    Verify -->|Applies| Isolate
-    Verify -->|Doesn't apply| Observe
-
-    Observe[Phase 1: Observe] --> Repro{Reproducible?}
-    Repro -->|No| Instrument[Add logging/tracing]
-    Instrument --> Observe
-    Repro -->|Yes| Hypothesize[Phase 2: Hypothesize]
-
-    Hypothesize --> Compare[Find working example, list differences]
-    Compare --> Theory[Form single specific hypothesis]
-
-    Theory --> Isolate[Phase 3: Isolate]
-    Isolate --> Test{Root cause isolated?}
-    Test -->|Yes| WriteFail[Write failing regression test]
-    Test -->|No| FailCount{3+ failures?}
-    FailCount -->|No| Theory
-    FailCount -->|Yes| Arch[Question architecture]
-
-    WriteFail --> Implement[Single targeted fix]
-    Implement --> Green{Scoped verification passes?}
-    Green -->|Yes| Capture[Propose resolution as ARCS knowledge]
-    Green -->|No| FailCount
-
-    class Found,Repro,Test,FailCount,Green decision
-    class Arch stop
-```
-
-## Phase 1: Observe (Root Cause Investigation)
-
-- Read the actual error message completely
-- Reproduce consistently before proceeding
-- Check recent changes (`git log`, `git diff`)
-- Trace data flow backward from failure point
-- Instrument component boundaries if cause unclear
-- **Pre-step:** `arcs knowledge search <slug> "<error>" --json` for gotcha/lesson/pattern entries
-
-## Phase 2: Hypothesize (Pattern Analysis)
-
-- Find a working example in the same codebase
-- Compare working vs broken — list every difference
-- Understand the dependency chain
-- Form ONE specific hypothesis (not multiple)
-
-## Phase 3: Root Cause Isolation
-
-- Test the hypothesis with the smallest possible diagnostic change
-- One variable at a time — never stack fixes
-- If hypothesis fails, form a new one from evidence
-- Do not proceed until the evidence isolates the root cause
-- **Escalation:** 3+ failed fixes → question the architecture, not the symptom
-
-## Phase 4: Fix
-
-- Write a failing regression test FIRST (proves the bug exists and prevents a fix-before-test path)
-- Implement a single targeted fix
-- Run scoped verification for the files you changed (your dispatch VERIFY command — never the full suite; the devil-advocate completion gate owns that)
-- Prepare the resolution as an ARCS knowledge proposal after verification passes; do not execute `arcs knowledge upsert`
-- If your fix introduces new failures in YOUR scoped tests, revert and return to Phase 2. Failures in files outside your scope are report-only (BLOCKED_BY) — likely a sibling agent's in-flight work; never fix or revert it
-
-## Log Triage Protocol
-
-**Scan order:** failure point → errors → warnings → timing anomalies
-
-```bash
-rg -n "ERROR|FATAL|panic|exception" <logfile>   # Error grep
-jq 'select(.level == "error")' <json-log>       # Structured logs
-```
-
-**Output:** Timeline of events leading to failure (T-5m, T-3m, T-0).
-
-## Git Bisect (Regressions)
-
-```bash
-git bisect start
-git bisect bad HEAD
-git bisect good <last-known-good>
-git bisect run <test-command>
-```
-
-After finding the commit: read the diff, isolate specific lines, feed into Phase 2.
-
-## Dependency Conflict Diagnosis
-
-| Symptom | Likely Cause |
-|---------|-------------|
-| `instanceof` fails across modules | Duplicate package copies |
-| Type mismatch on same interface | Different versions loaded |
-| "Cannot find module" intermittent | Hoisting conflict |
-| Works with `--legacy-peer-deps` | Peer dep unsatisfied |
-
-Diagnose: `npm ls <pkg>`, `npm explain <pkg>`, check for multiple copies.
-
-## ARCS Knowledge Capture
-
-After root cause identification, propose durable knowledge for orchestrator fan-in persistence:
-- **gotcha** — environmental/config traps
-- **lesson** — architectural insights from this session
-- **pattern** — reusable solution to recurring problem
-
-Include: root cause summary, evidence, affected files, fix approach.
-
-### Propose Resolution as Knowledge
-
-After resolving the issue, choose the kind and obtain its required anatomy before authoring a complete entry:
-
-```bash
-arcs knowledge template --kind=gotcha --json
-# Fill every returned section with observed evidence, affected files, and the fix approach.
-arcs knowledge upsert <slug> "<specific debugging discovery>" \
-  --kind=gotcha --summary="<durable takeaway>" --body-file=<complete-body.md> \
-  --keywords="<error,component,root-cause>" --source-files=<affected-paths> --json
-```
-
-Return that command as a ready-to-run proposal. Do not execute `arcs knowledge upsert`; the orchestrator owns fan-in persistence. Use the same template-first flow for `lesson` and `pattern`; do not copy a body-shaped example that omits the selected kind's required sections.
-
-**Kind selection guide:**
-- `gotcha` — surprising behavior, trap, or non-obvious failure mode
-- `lesson` — learned technique, debugging approach, resolution method
-- `pattern` — reusable solution that should be applied going forward
-
-## Constraints
-
-- **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION.** If Phase 1 incomplete, you cannot propose fixes.
-- **One variable at a time.** Never apply multiple changes simultaneously.
-- **3+ failures = architectural problem.** Stop fixing symptoms, question the pattern.
-- **Test before fix.** Failing test proves the bug; green test proves the fix.
-- **Defense in depth:** After fixing root cause, add validation at multiple layers to prevent recurrence.
-- **Systematic is faster than thrashing.** 15-30min systematic vs 2-3h random fixes.
-
-## Red Flags (Return to Phase 1)
-
-- "Quick fix for now, investigate later"
-- "Just try changing X and see"
-- Proposing solutions before tracing data flow
-- Each fix reveals a new problem in a different place
-- "I don't fully understand but this might work"
-- Human says "stop guessing" or "is that not happening?"
+Optional references provide concise techniques for tracing, waiting, and defense in depth. Do not run destructive Git operations unless the user requests them.

package/opencode/arcs/skills/systematic-debugging/condition-based-waiting.md

@@ -1,115 +1,12 @@
 # Condition-Based Waiting
 
-## Overview
+Wait for an observable condition, not an arbitrary duration.
 
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+Use a bounded poll or event with:
 
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
+- a clear success condition;
+- a timeout;
+- useful timeout evidence;
+- cleanup for listeners or timers.
 
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
-
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
-```
-
-**Use when:**
-- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
-- Tests are flaky (pass sometimes, fail under load)
-- Tests timeout when run in parallel
-- Waiting for async operations to complete
-
-**Don't use when:**
-- Testing actual timing behavior (debounce, throttle intervals)
-- Always document WHY if using arbitrary timeout
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise(r => setTimeout(r, 50));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined);
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario | Pattern |
-|----------|---------|
-| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state | `waitFor(() => machine.state === 'ready')` |
-| Wait for count | `waitFor(() => items.length >= 5)` |
-| Wait for file | `waitFor(() => fs.existsSync(path))` |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
-
-## Implementation
-
-Generic polling function:
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-    }
-
-    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
-  }
-}
-```
-
-See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
-
-## Common Mistakes
-
-**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
-**✅ Fix:** Poll every 10ms
-
-**❌ No timeout:** Loop forever if condition never met
-**✅ Fix:** Always include timeout with clear error
-
-**❌ Stale data:** Cache state before loop
-**✅ Fix:** Call getter inside loop for fresh data
-
-## When Arbitrary Timeout IS Correct
-
-```typescript
-// Tool ticks every 100ms - need 2 ticks to verify partial output
-await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
-await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
-// 200ms = 2 ticks at 100ms intervals - documented and justified
-```
-
-**Requirements:**
-1. First wait for triggering condition
-2. Based on known timing (not guessing)
-3. Comment explaining WHY
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions
+Fixed sleeps are acceptable only when time itself is the behavior under test.

package/opencode/arcs/skills/systematic-debugging/defense-in-depth.md

@@ -1,122 +1,10 @@
-# Defense-in-Depth Validation
+# Defense in Depth
 
-## Overview
+After fixing the root cause, add another guard only when it prevents a distinct realistic failure:
 
-When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+- validate at an input boundary;
+- preserve an invariant in the domain layer;
+- make an unsafe state unrepresentable;
+- monitor a failure that cannot be prevented.
 
-**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
-
-## Why Multiple Layers
-
-Single validation: "We fixed the bug"
-Multiple layers: "We made the bug impossible"
-
-Different layers catch different cases:
-- Entry validation catches most bugs
-- Business logic catches edge cases
-- Environment guards prevent context-specific dangers
-- Debug logging helps when other layers fail
-
-## The Four Layers
-
-### Layer 1: Entry Point Validation
-**Purpose:** Reject obviously invalid input at API boundary
-
-```typescript
-function createProject(name: string, workingDirectory: string) {
-  if (!workingDirectory || workingDirectory.trim() === '') {
-    throw new Error('workingDirectory cannot be empty');
-  }
-  if (!existsSync(workingDirectory)) {
-    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
-  }
-  if (!statSync(workingDirectory).isDirectory()) {
-    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
-  }
-  // ... proceed
-}
-```
-
-### Layer 2: Business Logic Validation
-**Purpose:** Ensure data makes sense for this operation
-
-```typescript
-function initializeWorkspace(projectDir: string, sessionId: string) {
-  if (!projectDir) {
-    throw new Error('projectDir required for workspace initialization');
-  }
-  // ... proceed
-}
-```
-
-### Layer 3: Environment Guards
-**Purpose:** Prevent dangerous operations in specific contexts
-
-```typescript
-async function gitInit(directory: string) {
-  // In tests, refuse git init outside temp directories
-  if (process.env.NODE_ENV === 'test') {
-    const normalized = normalize(resolve(directory));
-    const tmpDir = normalize(resolve(tmpdir()));
-
-    if (!normalized.startsWith(tmpDir)) {
-      throw new Error(
-        `Refusing git init outside temp dir during tests: ${directory}`
-      );
-    }
-  }
-  // ... proceed
-}
-```
-
-### Layer 4: Debug Instrumentation
-**Purpose:** Capture context for forensics
-
-```typescript
-async function gitInit(directory: string) {
-  const stack = new Error().stack;
-  logger.debug('About to git init', {
-    directory,
-    cwd: process.cwd(),
-    stack,
-  });
-  // ... proceed
-}
-```
-
-## Applying the Pattern
-
-When you find a bug:
-
-1. **Trace the data flow** - Where does bad value originate? Where used?
-2. **Map all checkpoints** - List every point data passes through
-3. **Add validation at each layer** - Entry, business, environment, debug
-4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
-
-## Example from Session
-
-Bug: Empty `projectDir` caused `git init` in source code
-
-**Data flow:**
-1. Test setup → empty string
-2. `Project.create(name, '')`
-3. `WorkspaceManager.createWorkspace('')`
-4. `git init` runs in `process.cwd()`
-
-**Four layers added:**
-- Layer 1: `Project.create()` validates not empty/exists/writable
-- Layer 2: `WorkspaceManager` validates projectDir not empty
-- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
-- Layer 4: Stack trace logging before git init
-
-**Result:** All 1847 tests passed, bug impossible to reproduce
-
-## Key Insight
-
-All four layers were necessary. During testing, each layer caught bugs the others missed:
-- Different code paths bypassed entry validation
-- Mocks bypassed business logic checks
-- Edge cases on different platforms needed environment guards
-- Debug logging identified structural misuse
-
-**Don't stop at one validation point.** Add checks at every layer.
+Do not duplicate the same check across layers without a concrete failure mode.