@rryando/arcs 4.1.0 → 4.2.1

package/opencode/arcs/skills/implementation/SKILL.md

@@ -1,61 +1,35 @@
 ---
 name: implementation
-description: Use for orchestrator-selected bounded or inspect implementation work. Bounded executes a fully specified change directly; inspect resolves limited uncertainty from the repo and DAG before coding.
+description: Inspect, edit, verify, or execute a ready plan node
 ---
 
-# Skill: implementation
+# Implementation
 
-## Work Mode Is Dispatch Authority
+## Work Modes
 
-The orchestrator selects exactly one work mode in the dispatch: `bounded` or `inspect`. Do not re-route yourself or silently expand scope.
+`bounded`, `inspect`, and `plan-node` are hints, not lifecycle gates:
 
-### `bounded`
+- **bounded:** files and behavior already clear; start directly.
+- **inspect:** smallest repository surface needed to resolve details.
+- **plan-node:** check declared dependencies, execute the ready node within its scope, run relevant verification, and align task/diagram state through ARCS CLI. Never edit DAG files directly, execute a blocked node, or absorb an adjacent outcome.
 
-Use when the task, files, acceptance criteria, and VERIFY command are fully specified.
+In any mode, ask only when evidence cannot resolve a change to goal, material scope, dependency strategy, or risk.
 
-- Execute directly with no repo exploration and no user questions.
-- Read only the dispatched files and context needed to make the change.
-- If a material decision or hidden scope appears, stop and return `STATUS: blocked`; do not guess or switch modes.
+## Method
 
-### `inspect`
+1. Inspect relevant code and tests.
+2. Reuse existing patterns and dependencies.
+3. Edit the minimum code needed for a complete result.
+4. Add proportionate tests for changed behavior.
+5. Verify with targeted checks; broader checks for broad or high-risk work.
+6. If verification fails, fix failures caused by the change and rerun the relevant check.
 
-Use when the goal is clear but limited implementation details remain.
+For `plan-node`, read current node metadata, confirm every predecessor is done, and use ARCS CLI task and diagram commands to keep completion state aligned. If dependencies are unmet or the node conflicts with its scope, stop with the concrete blocker instead of selecting other work.
 
-1. Inspect the repository and DAG first: search relevant knowledge, then inspect the smallest set of patterns, types, callers, and tests that can resolve the decision.
-2. Infer the answer when tools or established conventions make it clear.
-3. Ask at most one targeted user question, and only for a material decision that is not tool-resolvable.
-4. If uncertainty is design-shaping or scope expands, stop and return `STATUS: blocked` rather than improvising.
+Prefer necessity → standard library → platform capability → installed dependency → minimum custom code. Do not simplify away security, accessibility, validation, error handling, or data-loss protection.
 
-## Construction Discipline
+Do not commit, push, deploy, or modify unrelated files without an explicit request.
 
-Before adding code, stop at the first rung that satisfies the requirement:
+## Return
 
-1. **Necessity** — omit speculative or unrequested work.
-2. **Standard library** — use it when it correctly covers the need.
-3. **Native platform** — prefer a built-in platform capability.
-4. **Installed dependency** — reuse one before adding code or a dependency.
-5. **Minimum code** — write only the smallest correct implementation.
-
-Do not introduce abstractions, configuration, scaffolding, or dependencies for hypothetical consumers. Minimal does not mean flimsy: never simplify away security controls, accessibility basics, trust-boundary validation, or error handling that prevents data loss.
-
-Mark every deliberate simplification with its known ceiling and concrete revisit trigger:
-
-```
-// SHORTCUT: <ceiling>, upgrade when <trigger>
-```
-
-## Implementation And Verification
-
-- Follow existing repository conventions and the dispatch SCOPE.
-- Use test-driven-development when the dispatch requires it or when adding non-trivial behavior; structural changes may rely on existing focused contracts.
-- Run exactly the dispatch VERIFY command, scoped to touched files. NEVER the full suite, project-wide lint, or full build.
-- Fix failures in touched files and re-run VERIFY. Report failures originating outside SCOPE under `BLOCKED_BY`; do not edit those files.
-- Never commit unless explicitly asked.
-
-## Knowledge Exit
-
-Knowledge is proposal-only. For a durable, non-obvious pattern or gotcha, return a substantive ready-to-run proposal for orchestrator persistence at fan-in; do not execute `arcs knowledge upsert` yourself. Skip mechanical or easily re-derived observations.
-
-`arcs knowledge template --kind=<kind> --json`; `arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha|lesson|architecture|decision> --summary="<summary>" --body="<substantive filled template>" --keywords="<keywords>" --source-files="<path[:anchor]>" --json`
-
-Upsert is idempotent by title.
+Report changed files, verification actually run, remaining risk, and blockers.

package/opencode/arcs/skills/init-project/SKILL.md

@@ -1,160 +1,22 @@
 ---
 name: init-project
-description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → codegraph ingestion → fan-out analysis across typed sub-agents.
+description: Initialize a repository as an ARCS project with useful minimal metadata
 ---
 
-# Skill: init-project
+# Initialize Project
 
-## When
+## Method
 
-User wants to track a new project, bootstrap documentation, or connect a repo to the ARCS DAG. Triggers: "new project", "track this repo", "add project X", "init <repo>".
+An explicit request to init or track a project authorizes local ARCS initialization. Ask only for missing user-owned identity such as name, description, workspace path, or dependency choice.
 
-> **Canonical orchestrator workflow:** `src/cli/arcs-orchestrate.ts` under `### INIT Workflow` — this skill mirrors that flow with full operational detail. If the two diverge, the orchestrator prompt wins.
+1. Check slug conflicts with `arcs project list`.
+2. Verify named dependency projects exist.
+3. Run `arcs project init` with the requested metadata.
+4. Add only requested or clearly useful overview/dependency documentation.
+5. Validate the new project and report slug and paths.
 
-## Flow
+Codegraph is optional. When available, initialization may index the workspace and emit structural proposals. When absent, continue without it. If `pending_enrichment` is true, process useful proposals with `enriching-codegraph-proposals`; no broad agent fan-out required.
 
-```mermaid
-flowchart TD
-    classDef sub fill:#8b5cf6,color:#fff
+Raw proposals are not knowledge. Inspect before keep, merge, drop, or promote decisions. Never infer destructive cleanup, deployment, publication, or Git permission from initialization.
 
-    A[Gather: name, description, repoUrl?, dependsOn?] --> B[arcs project list → conflict check]
-    B --> C[Present summary to user]
-    C -->|user confirms| D[arcs project init]
-    D --> E[arcs project update-doc × 4]
-    E --> F{codegraph on PATH?}
-    F -->|yes| G[codegraph index --force --quiet]
-    F -->|no| H[Skip graph step, log gap]
-    G --> G2[ingestGraph → ≤20 proposals]
-    G2 --> G3[Enrich queue: list → keep/merge/drop → promote/drop]
-    G3 --> I[Fan out: tech-architect analysis + research modes]:::sub
-    H --> I
-    I --> K[Done]
-```
-
-## CLI Primer
-
-```bash
-arcs project init "Foo" --description="..." --path="$(pwd)" --json
-```
-Discovery: `arcs --commands --json`. Mutating commands run directly — no token.
-
-## Constraints
-
-- Do NOT read repo to infer name/description — gather from user
-- Verify `dependsOn` targets exist via `arcs project list --json`
-- `arcs project init` creates empty `plans/`, `knowledge/`, `tasks/` indexes — don't pre-populate
-- Repo analysis is **fan-out across typed agents**, never a generic "analysis sub-agent" (see Agent Dispatch below)
-- Never block INIT on codegraph — it's optional. Skip cleanly if missing.
-
-## Codegraph Sub-Flow (DEFAULT: ON when binary present)
-
-The orchestrator runs codegraph directly during INIT to produce structural **proposals** before any sub-agent reads code. Proposals are durable on the proposal-store ledger; agents enrich them into knowledge entries via the `enriching-codegraph-proposals` skill. This is the default path when `codegraph` is on PATH; skip cleanly otherwise.
-
-1. **Detect:** call `detectCodegraph()` from `src/utils/codegraph.ts`. If unavailable, log "codegraph not on PATH; proceeding without graph signal" and skip steps 3–6.
-2. **Trust the gitignore guarantee:** `runIndex()` already auto-appends `.codegraph/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running the index is sufficient.
-3. **Index** (project-based; CLI drives the bundled runtime — no LLM API key required):
-   ```bash
-   codegraph index <workspacePath> --force --quiet
-   ```
-   Builds a per-project codegraph index under `<workspacePath>/.codegraph/`.
-4. **Ingest as proposals:** `arcs project init` internally calls `ingestGraph(slug)`, which parses codegraph CLI `--json` output and writes up to 20 structural proposals to `proposals/graphify.json` (filename retained for compatibility; rename pending; test files filtered):
-   - 8 god nodes (`kind=module`, ranked by callers+callees / impact as a proxy for degree)
-   - 8 architecture clusters (`kind=architecture`, synthesized pseudo-communities by directory prefix — codegraph has no community/cluster export)
-   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs; relations hard-coded as `["calls"]`)
-
-   Codegraph never writes directly to the knowledge surface. The init envelope returns `data.codegraph.pending_enrichment: true` to signal that proposals are waiting.
-5. **Enrich** with the `enriching-codegraph-proposals` skill — read `arcs proposal list <slug> --json`, decide per-proposal verdicts (keep / merge / drop), and return exact proposed promote/drop commands for orchestrator application. Pending codegraph proposals never bypass this lifecycle into knowledge.
-6. **Optional graph queries** for evidence during enrichment (sub-agents may run these via the codegraph MCP server, which auto-syncs through its own file watcher):
-   - `codegraph_search "entry points and main commands"` → seeds for "key files" reference entries
-   - `codegraph_explore` on core modules → seeds for "core modules" entries
-   - `codegraph_node "<godNodeLabel>"` → structural summary for module entry bodies
-   - `codegraph_impact "<critical-symbol>"` → reverse-impact map for high-risk modules
-   - `codegraph_callers` / `codegraph_callees "<symbol>"` → dependency paths for architecture entries
-7. **Hand to typed agents** (in parallel) for independently authored, code-grounded follow-up entries beyond the proposal queue — see **Agent Dispatch** below.
-
-## Content Guidelines
-
-| Doc | Format |
-|-----|--------|
-| `overview.md` | 2-3 sentence summary + goals |
-| `tasks.md` | `[ ]` backlog / `[/]` in-progress / `[x]` done |
-| `dependencies.md` | Upstream + downstream sections |
-| `knowledge.md` | High-level context + pointers to structured entries |
-
-Update via `arcs project update-doc <slug> <doc> --content="..."`.
-
-## Agent Dispatch (named typed agents — DO NOT default to a generic analysis agent)
-
-| Sub-agent | Owns | Knowledge kinds it produces |
-|-----------|------|----------------------------|
-| `tech-architect` (analysis mode) | Module boundaries, clusters, dependency direction, cross-module couplings, structural gotchas, lessons | `architecture`, `module`, `gotcha`, `lesson` |
-| `tech-architect` (`AGENT_MODE: research`) | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
-| `code-reviewer` (audit mode, optional) | Coding-style + convention scan from existing code | `pattern` |
-
-Dispatch in parallel — all agents in one message, per the orchestrator's Parallelism rules. Each agent receives:
-- The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what codegraph already found)
-- Targeted codegraph queries for evidence (e.g., `codegraph_node` / `codegraph_impact` output for the modules they own)
-- Explicit scope (which files / which kinds to produce)
-
-Raw `KnowledgeProposal` records stay in the proposal lifecycle above. Each typed agent may instead return an independently authored finding: `{title, kind, summary, keywords, sourceFiles, body}`. Workers do not execute `arcs knowledge upsert`; after deduplication they return substantive ready-to-run commands for orchestrator fan-in persistence.
-
-## Knowledge Categories for Analysis Sub-Agents
-
-| Category | Kind | What to discover | Primary agent |
-|----------|------|------------------|---------------|
-| tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `tech-architect` (`AGENT_MODE: research`) |
-| key files | `reference` | Entry points, config files, main modules, purposes | `tech-architect` (`AGENT_MODE: research`; use `codegraph_search "entry points"`) |
-| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `code-reviewer` (audit mode) or `tech-architect` |
-| coding style | `pattern` | Formatting, linting, import ordering, file organization | `code-reviewer` (audit mode) |
-| core modules | `module` | Core modules / shared functions — what, where, interconnections | `tech-architect` (god nodes from codegraph) |
-| external services | `module` | APIs, databases, message queues the project interacts with | `tech-architect` (`AGENT_MODE: research`) |
-| third-party libraries | `reference` | Key dependencies and why they are used | `tech-architect` (`AGENT_MODE: research`) |
-| features | `feature` | Major user-facing or system-facing features | `tech-architect` (`AGENT_MODE: research`) |
-| cross-module couplings | `gotcha` | Hot edges between modules surfaced by codegraph | `tech-architect` (auto from `ingestGraph`) |
-| architecture clusters | `architecture` | Pseudo-community / directory groupings from codegraph | `tech-architect` (auto from `ingestGraph`) |
-
-## Worked Example
-
-```bash
-# 1. Conflict check
-arcs project list --json
-
-# 2. Present summary to user; on confirmation, init
-arcs project init "Foo" --description="Foo CLI tool" --path="$(pwd)" --json
-
-# 3. Update docs
-arcs project update-doc foo overview --content="..." --json
-# ... repeat for tasks, dependencies, knowledge
-
-# 4. Codegraph (if available) — runs inside `arcs project init`
-codegraph index . --force --quiet
-# ingestGraph parses codegraph CLI --json → proposals/graphify.json (filename retained; rename pending)
-# init envelope: data.codegraph.pending_enrichment === true → load
-# `enriching-codegraph-proposals` and run the verdict loop:
-arcs proposal list foo --json
-# keep: promote only after authoring the required title, summary, body, and source files
-arcs proposal promote foo <id> --title="..." --summary="..." --body-file=... --kind=module --source-files=... --json
-# merge: promote with --merge-with=<existing-knowledge-id> and append graph evidence
-arcs proposal promote foo <id> --merge-with=<existing-knowledge-id> --body-file=... --source-files=... --json
-arcs proposal drop foo <id> --reason="..." --json
-
-# 5. Fan out typed agents (parallel) for entries beyond proposal scope
-#    tech-architect (analysis mode)          → architecture/module/gotcha/lesson entries
-#    tech-architect (AGENT_MODE: research)   → reference/feature entries
-
-# 6. Propose only independently authored, non-proposal-derived findings.
-# Obtain the kind-specific body anatomy before authoring the ready-to-run command:
-arcs knowledge template --kind=architecture --json
-arcs knowledge upsert foo "Tech stack: TypeScript + Node 20" --kind=architecture --summary="..." --body-file=... --source-files=package.json --json
-# Return the upsert; do not execute it. The orchestrator persists it at fan-in.
-```
-
-## Exit Conditions
-
-| Condition | Action |
-|-----------|--------|
-| Project already in DAG (slug collision) | Stop. Surface conflict; ask user to rename or use existing |
-| User declines summary | Stop. No mutations performed |
-| `codegraph` missing | Continue without graph signal; sub-agents run with code reading only |
-| `dependsOn` target missing | Stop. Ask user to init dependencies first or remove the link |
-| Init succeeds but knowledge fan-out fails | Project exists in DAG; rerun knowledge phase later via SYNC |
+If a write fails, stop and report partial state instead of layering more mutations on an uncertain project.

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 evidence, stop and question 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 durable discovery is optional, not part of success.
 
-    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.