devworkspace 0.3.1 → 0.3.2

package/docs/architecture-report/02-system-architecture.md

@@ -0,0 +1,356 @@
+# Chapter 2: System Architecture
+
+> **A deep dive into the layered architecture of DevWorkspace, component relationships, and boundary interfaces.**
+
+---
+
+## 1. Architectural Overview & Design Philosophy
+
+DevWorkspace is organized as a clean, unidirectional layered architecture. Data and control flow strictly downward from the presentation interface to the filesystem and external processes:
+
+```
++-----------------------------------------------------------------------------------+
+|                           1. CLI & PRESENTATION LAYER                             |
+|           (src/cli/main.ts, args.ts, run.ts, render.ts, help.ts)                  |
++-----------------------------------------------------------------------------------+
+                                        |
+                                        v
++-----------------------------------------------------------------------------------+
+|                        2. SERVICE ORCHESTRATION LAYER                             |
+|          (src/services/: init, analysis, status, doctor, agent, ...)              |
++-----------------------------------------------------------------------------------+
+                                        |
+                                        v
++-----------------------------------------------------------------------------------+
+|                               3. DOMAIN ENGINES                                   |
+|   Discovery        Agents        Integrations        Tasks & Gates     Knowledge  |
+| (src/discovery/) (src/agents/) (src/integrations/)  (src/tasks/)    (src/knowl.)  |
++-----------------------------------------------------------------------------------+
+                                        |
+                                        v
++-----------------------------------------------------------------------------------+
+|                      4. CORE FOUNDATION & SECURITY INVARIANTS                     |
+|    Security Invariants       Atomic Filesystem & Locks       Schemas & Validation |
+|     (src/security/)             (src/utils/, src/core/)        (src/config/)      |
++-----------------------------------------------------------------------------------+
+```
+
+### Key Architectural Invariants
+1. **Zero Runtime Dependencies**: The core codebase relies solely on Node.js built-in APIs (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:util`).
+2. **Pure Service Layer**: Service functions return plain JavaScript objects representing facts and outcomes; they never call `process.exit()` or print directly to `stdout`/`stderr`. This makes the entire service layer directly callable from a programmatic API (`src/index.ts`) for future IDE plugins or dashboards.
+3. **Immutable State & Atomic Writes**: Files are written using `atomicWriteJson` (writing to a temporary file, flushing to disk, and renaming atomically). Partial file writes never occur even during unexpected crashes or power interruptions.
+4. **Untrusted Repository Content**: Source code, test scripts, comments, documentation, and manifests are treated as untrusted data. They can be analyzed, but they can never override system safety rules or execute arbitrarily.
+
+---
+
+## 2. Diagram 1: High-Level System Architecture
+
+```mermaid
+flowchart TD
+    subgraph UI_Layer["1. Presentation Layer"]
+        CLI_Entry["CLI Entrypoint\n(src/cli/main.ts)"]
+        ArgParser["Arg Parser\n(src/cli/args.ts)"]
+        CommandRouter["Command Dispatcher\n(src/cli/run.ts)"]
+        TerminalRenderer["Terminal / JSON Renderer\n(src/cli/render.ts)"]
+    end
+
+    subgraph Service_Layer["2. Service Orchestration Layer"]
+        SvcInit["initWorkspace()"]
+        SvcAnalyze["analyzeWorkspace()"]
+        SvcStatus["getStatus()"]
+        SvcDoctor["runDoctor()"]
+        SvcAgent["installAgent()"]
+        SvcTask["createTask() / runTaskCheck()"]
+        SvcKnowledge["addFact() / getContext()"]
+        SvcIntegrations["setupIntegrations()"]
+    end
+
+    subgraph Engine_Layer["3. Domain Engine Subsystems"]
+        subgraph DiscoverySub["Discovery Engine"]
+            Scanner["Filesystem Scanner\n(src/discovery/scan.ts)"]
+            Detector["Stack & Framework Detector\n(src/discovery/detect.ts)"]
+            CommandBuilder["Testing Contract Builder\n(src/discovery/commands.ts)"]
+            DocScanner["Documentation Detector\n(src/discovery/docs.ts)"]
+            EntryScanner["Entry Points Detector\n(src/discovery/entrypoints.ts)"]
+        end
+
+        subgraph AgentsSub["Multi-Agent Compatibility Engine"]
+            AgentRegistry["Agent Registry\n(src/agents/index.ts)"]
+            ClaudeAdapter["Claude Code Adapter\n(CLAUDE.md & SKILL.md)"]
+            CodexAdapter["OpenAI Codex Adapter\n(AGENTS.md)"]
+            CursorAdapter["Cursor Adapter\n(.cursor/rules/)"]
+            CopilotAdapter["Copilot Adapter\n(.github/copilot-instructions.md)"]
+            SectionMerger["Non-Destructive Section Merger\n(src/agents/shared.ts)"]
+        end
+
+        subgraph TasksSub["Task & Verification Engine"]
+            TaskRouter["Request Classifier\n(src/tasks/routing.ts)"]
+            TaskLifecycle["Task State Machine\n(src/tasks/task.ts)"]
+            GateEvaluator["evaluateGate()\n(src/tasks/task.ts)"]
+            SafetyClassifier["classifyCommand()\n(src/verification/safety.ts)"]
+            ScopeTracker["Scope & Baseline Tracker\n(src/verification/scope.ts)"]
+        end
+
+        subgraph IntegrationsSub["External Integration Manager"]
+            IntManager["Integration Manager\n(src/integrations/manager.ts)"]
+            GraphifyAdapter["Graphify Adapter\n(graphifyy PyPI)"]
+            AgentSkillsAdapter["Agent Skills Adapter\n(addyosmani/agent-skills)"]
+            PonytailAdapter["Ponytail Adapter\n(DietrichGebert/ponytail)"]
+            OmniRouteAdapter["OmniRoute Adapter\n(Observed optional)"]
+        end
+    end
+
+    subgraph Foundation_Layer["4. Core Foundation & Security"]
+        WorkspaceCore["Workspace Root & Paths\n(src/core/workspace.ts)"]
+        SecurityFiles["safeReadText() & Path Guard\n(src/security/files.ts)"]
+        SecretRedact["findSecrets() & redact()\n(src/security/redact.ts)"]
+        AtomicFs["atomicWriteJson() & Lockfile\n(src/utils/fs.ts, lock.ts)"]
+        Schemas["Data Contracts & Validation\n(src/config/schemas.ts)"]
+    end
+
+    CLI_Entry --> ArgParser
+    ArgParser --> CommandRouter
+    CommandRouter --> Service_Layer
+    CommandRouter --> TerminalRenderer
+
+    SvcInit --> WorkspaceCore
+    SvcAnalyze --> DiscoverySub
+    SvcAgent --> AgentsSub
+    SvcTask --> TasksSub
+    SvcIntegrations --> IntegrationsSub
+
+    DiscoverySub --> SecurityFiles
+    TasksSub --> SafetyClassifier
+    TasksSub --> ScopeTracker
+    AgentsSub --> SectionMerger
+    IntegrationsSub --> AtomicFs
+
+    SecurityFiles --> WorkspaceCore
+    AtomicFs --> Schemas
+    SecretRedact --> AtomicFs
+```
+
+---
+
+## 3. Subsystem Breakdown and Responsibilities
+
+### Subsystem 1: CLI and Presentation Layer (`src/cli/`)
+- **`main.ts`**: The Node.js binary shebang (`#!/usr/bin/env node`). It hooks process signals (`SIGINT`, `SIGTERM`) to trigger cleanup handlers (`src/utils/cleanup.ts`), ensuring lockfiles are deleted and incomplete operations do not leave stale state. It translates asynchronous results into integer exit codes:
+  - `0`: Success (OK)
+  - `1`: Failure / error
+  - `2`: Usage error or manual approval needed
+  - `3`: Warnings encountered (under `--strict` mode)
+  - `130`: Terminated by signal (SIGINT/SIGTERM)
+- **`args.ts`**: Strict argument parser using `node:util/parseArgs`. It declares the exact supported flags (`--json`, `--cwd`, `--dry-run`, `--strict`, `--yes`, `--agent`, etc.). Unrecognized flags trigger a `DevWorkspaceError('USAGE')` so typos never fail silently.
+- **`run.ts`**: The main dispatcher. It builds the execution context (`Ctx`), maps aliases (e.g., `tasks` -> `task list`), routes commands to their respective async handler functions, and handles JSON vs human-readable output formatting.
+- **`render.ts`**: Pure visual presentation engine. Formats tables, checkmarks (`✓`, `✗`, `⚠`), badges, and hierarchical task summaries with optional ANSI colors. When `--ascii` or `NO_COLOR` is detected, it renders plain ASCII fallbacks.
+- **`help.ts`**: Contains command documentation, parameter guides, and examples printed during `devworkspace --help` and `devworkspace <command> --help`.
+
+---
+
+### Subsystem 2: Service Orchestration Layer (`src/services/`)
+The service layer implements the business logic of each CLI command. Every service function accepts a standard `ServiceOptions` object containing `{ cwd, dryRun, env, runner, homeDir }` and returns structured result data.
+
+| Service Module | Function | Responsibility |
+|---|---|---|
+| `init.ts` | `initWorkspace()` | Idempotently creates `.devworkspace/` directories, `project.json`, and `.gitignore`. |
+| `analysis.ts` | `analyzeWorkspace()` | Coordinates filesystem scanning, framework detection, testing contract construction, and onboarding prompt generation. |
+| `status.ts` | `getStatus()` | Aggregates high-level project health, uncommitted Git changes, knowledge facts count, active tasks, and integration summaries. |
+| `doctor.ts` | `runDoctor()` | Runs 20+ diagnostic checks inspecting Node version, Git status, workspace integrity, secret exposure, and integration readiness. |
+| `agent.ts` | `installAgent()`, `listAgents()` | Coordinates the multi-agent adapters to plan, create, or update agent instruction files (`AGENTS.md`, `CLAUDE.md`, etc.). |
+| `tasks.ts` | `createTask()`, `setTaskStatus()` | Manages task records in `.devworkspace/tasks/`, validates status transitions, and enforces the completion gate. |
+| `taskContext.ts` | `getTaskContext()` | Formats a compact, task-specific prompt containing only the facts, rules, and commands needed for a specific request. |
+| `verify.ts` | `runTaskCheck()`, `declareTestEnv()` | Executes testing contract commands safely, checking destructive keywords and test environment requirements. |
+| `knowledge.ts` | `addFact()`, `getContext()` | Stores, updates, and queries durable facts with authority ranking and source tracking. |
+| `refresh.ts` | `refreshWorkspace()` | Re-runs deterministic discovery and marks facts as `STALE` if their source files have changed. |
+| `records.ts` | `recordDecision()`, `recordSession()` | Appends Architecture Decision Records (ADRs) to `.devworkspace/decisions/` and session logs to `.devworkspace/sessions/`. |
+| `portability.ts` | `exportWorkspace()`, `importWorkspace()` | Bundles portable project knowledge into a single JSON file and validates imports against schema limits. |
+| `reset.ts` | `resetWorkspace()` | Safely resets `.devworkspace/` after generating an explicit deletion plan and requiring `--yes`. |
+| `migrate.ts` | `migrateWorkspace()` | Upgrades workspace data structures across schema versions, saving automatic backups in `.devworkspace/local/backups/`. |
+
+---
+
+### Subsystem 3: Discovery Engine (`src/discovery/`)
+The discovery engine analyzes a project repository without executing user code and without calling an AI model.
+
+```mermaid
+flowchart LR
+    Scan["scan.ts\n(Tree walk with ignore rules)"]
+    Detect["detect.ts\n(Framework & ecosystem detection)"]
+    Commands["commands.ts\n(Testing contract derivation)"]
+    Docs["docs.ts\n(Architecture & ADR discovery)"]
+    Entry["entrypoints.ts\n(Server & worker entrypoints)"]
+    
+    Scan --> Detect
+    Detect --> Commands
+    Detect --> Docs
+    Detect --> Entry
+    Commands --> Output["discovery.json\ncommands.json\nonboarding-prompt.md"]
+    Docs --> Output
+    Entry --> Output
+```
+
+- **`scan.ts`**: Walks the directory tree up to a bounded maximum (10,000 files). Automatically skips `node_modules/`, `.git/`, `dist/`, `build/`, `vendor/`, and paths specified in `.gitignore`. Detects symlinks and skips them to avoid circular traversal loops.
+- **`detect.ts`**: Inspects package manifests (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`) and file extensions to detect:
+  - Ecosystems (Node.js, Python, Go, Rust, Java, C#, PHP, Ruby)
+  - Frameworks (React, Fastify, Express, Next.js, NestJS, Vite, Django, FastAPI)
+  - Databases and ORMs (Drizzle, Prisma, TypeORM, Mongoose, PostgreSQL, Redis)
+  - Monorepo tools (npm/pnpm/yarn workspaces, Lerna, Turbo, Nx, Cargo/Go workspaces, or multi-package repos without a root manifest)
+- **`commands.ts`**: Inspects `scripts` in all package manifests across the repository. Maps them into standard contract checks: `typecheck`, `unit`, `integration`, `e2e`, `lint`, `format`, `build`, `migrations`, `security`. Tracks the exact `cwd` (working directory) for each script.
+- **`entrypoints.ts`**: Discovers application launch files by inspecting `main`, `bin`, and script definitions like `start`, `dev`, `server`, and `worker:*`.
+- **`docs.ts`**: Finds architecture docs, READMEs, and ADRs (Architecture Decision Records) up to a bounded limit of 25 files, ignoring changelogs and licenses.
+
+---
+
+### Subsystem 4: Multi-Agent Compatibility Engine (`src/agents/`)
+The multi-agent engine adapts DevWorkspace's instructions to the exact file formats expected by different coding agents:
+
+```mermaid
+flowchart TD
+    AdapterInterface["AgentAdapter Interface\n(src/agents/types.ts)"]
+    
+    AdapterInterface --> Claude["Claude Code Adapter\n(CLAUDE.md + .claude/skills/)"]
+    AdapterInterface --> Codex["OpenAI Codex Adapter\n(AGENTS.md)"]
+    AdapterInterface --> Cursor["Cursor Adapter\n(.cursor/rules/devworkspace.mdc)"]
+    AdapterInterface --> Copilot["Copilot Adapter\n(.github/copilot-instructions.md)"]
+
+    Claude --> SectionMerge["mergeSection()\n(Non-destructive managed block injection)"]
+    Codex --> SectionMerge
+    Cursor --> SectionMerge
+    Copilot --> SectionMerge
+
+    SectionMerge --> TargetFiles["User Repository Instruction Files"]
+```
+
+- **`types.ts`**: Defines the `AgentAdapter` interface. Every adapter implements `id`, `displayName`, `capabilities`, `detectExisting()`, `detectAvailable()`, `plan()`, and `unplan()`.
+- **`shared.ts`**: Provides `mergeSection()`, `removeManagedSection()`, and EOL detection (`\r\n` vs `\n`). When writing instructions, DevWorkspace encloses its content in:
+  ```markdown
+  <!-- devworkspace:start (managed by DevWorkspace - edit outside this block; run "devworkspace agent install" to refresh) -->
+  ## DevWorkspace
+  ...
+  <!-- devworkspace:end -->
+  ```
+  If a user has already written instructions above or below this block, **their custom instructions are 100% preserved**.
+- **`claude/adapter.ts`**: Writes `CLAUDE.md` and generates a dedicated skill at `.claude/skills/devworkspace/SKILL.md` containing task routing rules.
+- **`codex/adapter.ts`**: Writes standard `AGENTS.md` (which is also read by OpenAI Codex, Google Antigravity, and other open-spec agents).
+- **`cursor/adapter.ts`**: Writes `.cursor/rules/devworkspace.mdc` with YAML frontmatter `alwaysApply: true`, and falls back to legacy `.cursorrules` if present.
+- **`copilot/adapter.ts`**: Writes `.github/copilot-instructions.md` for GitHub Copilot in VS Code.
+
+---
+
+### Subsystem 5: Task and Verification Gate Engine (`src/tasks/` & `src/verification/`)
+Manages task lifecycles and enforces that work is verified before being declared complete.
+
+- **`routing.ts`**: Classifies incoming user prompts into 10 task types (`QUESTION`, `BUG`, `FEATURE`, `REFACTOR`, `DOCUMENTATION`, `TESTING`, `PERFORMANCE`, `SECURITY`, `ARCHITECTURE`, `RELEASE`) and detects explicit user constraints (e.g. `no-modify`, `no-commit`, `no-e2e`, `plan-only`).
+- **`task.ts`**: Represents tasks as JSON documents stored in `.devworkspace/tasks/active/` and moved to `.devworkspace/tasks/completed/` when finished. Holds verification checklists, test baselines, and attestations.
+- **`task.ts (evaluateGate)`**: Pure logic function that evaluates whether a task satisfies completion requirements:
+  - All required verification checks must be `PASS` or `SKIPPED` (with explicit user override).
+  - Test counts must not regress (`after.failed <= baseline.failed` and `after.passed >= baseline.passed`).
+  - Read-only tasks must not have modified any files.
+  - Three attestations must be checked: `userWorkIntact`, `knowledgeReviewed`, `finalStateInspected`.
+  - A completion summary must be provided.
+- **`safety.ts`**: Evaluates whether DevWorkspace may execute a command automatically. Classifies commands as:
+  - `safe`: `typecheck`, `lint`, `build`, and unit tests without external dependencies.
+  - `needs-test-environment`: Integration, security, or catch-all tests that require databases or queues (PostgreSQL, Redis, MongoDB). Blocked unless declared via `devworkspace testenv declare`.
+  - `blocked`: Commands that mutate files (`format`, `lint --fix`), run migrations (`db:migrate`), or contain destructive keywords (`drop`, `truncate`, `flushall`, `rm -rf`). DevWorkspace will never execute these commands automatically.
+- **`scope.ts`**: Captures a baseline fingerprint of uncommitted files at task creation. When verification runs later, DevWorkspace only requires checks for packages that were modified *by the current task*.
+
+---
+
+### Subsystem 6: External Integration Manager (`src/integrations/`)
+DevWorkspace does not invent its own AI models or code-graph parsers. Instead, it inspects and coordinates external tools installed on the developer's machine:
+
+```mermaid
+flowchart TD
+    Mgr["Integration Manager (src/integrations/manager.ts)"]
+    
+    subgraph ExternalTools["Observed / Coordinated Tools"]
+        Graphify["Graphify (PyPI: graphifyy)\nKnowledge graph of code structure\n(CLI + .claude/skills/graphify)"]
+        AgentSkills["Agent Skills (addyosmani/agent-skills)\nEngineering methodology slash commands\n(/spec /plan /build /test /review /ship)"]
+        Ponytail["Ponytail (DietrichGebert/ponytail)\nCode complexity & diff review\n(/ponytail-review, /ponytail-audit)"]
+        OmniRoute["OmniRoute (diegosouzapw/OmniRoute)\nModel routing proxy\n(Observed only; never required or executed)"]
+    end
+
+    Mgr -->|"inspect(deep) & plan()"| Graphify
+    Mgr -->|"inspect(deep) & plan()"| AgentSkills
+    Mgr -->|"inspect(deep) & plan()"| Ponytail
+    Mgr -->|"inspect(deep)"| OmniRoute
+```
+
+- **`manager.ts`**: Runs inspection, plans installation steps, checks prerequisites, and executes installations with user consent.
+- **`exec.ts`**: Safe process runner that checks PATH, executes `which`/`where`, parses semantic versions, and enforces timeouts so processes never hang indefinitely.
+- **`protect.ts`**: Takes pre-execution snapshots of files that third-party tools might mutate (such as `CLAUDE.md` or `.claude/settings.json`) and verifies that uncommitted user changes were not overwritten.
+
+---
+
+### Subsystem 7: Core Security and Foundation (`src/security/`, `src/utils/`, `src/core/`)
+Underpins the entire application with safety invariants:
+- **`files.ts` (`safeReadText`)**: Canonicalizes paths and strictly verifies that files reside inside the repository root. Rejects any file whose name matches sensitive patterns (`.env`, `.pem`, `.key`, `id_rsa`, `credentials`). Verifies that no intermediate symlink escapes outside the repository.
+- **`redact.ts`**: Scans text using regex patterns for API keys (AWS, GitHub, Slack, Google, npm, OpenAI, JWTs, private keys) and replaces them with `[REDACTED:<type>]`.
+- **`lock.ts`**: Implements file-based mutual exclusion (`.devworkspace/local/devworkspace.lock`). Prevents concurrent CLI invocations from corrupting workspace files.
+- **`fs.ts`**: Provides `atomicWriteJson` and `atomicWriteFile`. Writes to temporary files and executes atomic renames.
+- **`schemas.ts`**: Type-safe schema validation for all persisted JSON files (`project.json`, `facts.json`, `commands.json`, `discovery.json`, tasks, and sessions).
+
+---
+
+## 4. Diagram 4: Tool and Integration Map
+
+The following diagram maps which internal DevWorkspace modules interact with external tools and dependencies:
+
+```mermaid
+flowchart LR
+    subgraph InternalModules["Internal DevWorkspace Modules"]
+        CLI["src/cli/"]
+        SvcAnal["src/services/analysis.ts"]
+        SvcAgent["src/services/agent.ts"]
+        SvcInt["src/services/integrations.ts"]
+        SvcVer["src/services/verify.ts"]
+        Sec["src/security/"]
+    end
+
+    subgraph NodeBuiltins["Node.js 20+ Built-in APIs"]
+        FS["node:fs / node:fs/promises"]
+        Path["node:path"]
+        Proc["node:child_process (spawnSync)"]
+        Crypto["node:crypto (createHash, randomUUID)"]
+        Util["node:util (parseArgs)"]
+        OS["node:os (tmpdir, platform)"]
+    end
+
+    subgraph ExternalAgents["Coding Agent Instruction Targets"]
+        ClaudeCode["Claude Code (CLAUDE.md)"]
+        Codex["OpenAI Codex / Antigravity (AGENTS.md)"]
+        Cursor["Cursor IDE (.cursor/rules/)"]
+        Copilot["GitHub Copilot (.github/copilot-instructions.md)"]
+    end
+
+    subgraph ExternalToolchains["External Subprocesses (Observed / Coordinated)"]
+        Git["git (git status, rev-parse, diff)"]
+        GraphifyCli["graphify (Python / pipx / uv)"]
+        ClaudeCli["claude (plugin list, plugin install)"]
+        SkillsCli["skills (npx skills add)"]
+        NodeExe["node (for Ponytail lifecycle hooks)"]
+        ProjectNPM["npm / pnpm / yarn (running contract tests)"]
+    end
+
+    CLI --> Util
+    CLI --> FS
+    SvcAnal --> FS
+    SvcAnal --> Path
+    SvcAgent --> ExternalAgents
+    SvcInt --> Proc
+    SvcInt --> GraphifyCli
+    SvcInt --> ClaudeCli
+    SvcInt --> SkillsCli
+    SvcInt --> NodeExe
+    SvcVer --> Git
+    SvcVer --> ProjectNPM
+    Sec --> Crypto
+    Sec --> Path
+    Sec --> FS
+```
+
+---
+
+*Continue to [Chapter 3: Tools and Technologies](./03-tools-and-technologies.md) for the complete inventory of all libraries, tools, and integrations.*
+

package/docs/architecture-report/03-tools-and-technologies.md

@@ -0,0 +1,112 @@
+# Chapter 3: Tools & Technologies
+
+> **An exhaustive, evidence-backed inventory of every technology, library, framework, tool, and integration used by DevWorkspace.**
+
+---
+
+## 1. Runtime Technology Stack
+
+DevWorkspace is intentionally engineered with **zero external production runtime dependencies**:
+
+```json
+// package.json
+"dependencies": {}
+```
+
+Every runtime capability—from CLI parsing to atomic filesystem writing, child process execution, and cryptographic hashing—is implemented using the **Node.js 20+ standard library**.
+
+### Complete Runtime Inventory Table
+
+| Name | Category | Purpose in DevWorkspace | Responsibility | Input | Output | Integration / Callers | Execution | Status | Evidence |
+|---|---|---|---|---|---|---|---|---|---|
+| **Node.js (v20+)** | Runtime Platform | Execution environment | Executes JavaScript modules and provides system APIs | TS compiled JS files | Process execution | Entire application | Host machine OS | Verified | `package.json` (`engines.node: ">=20.11"`) |
+| **`node:util` (`parseArgs`)** | Standard Library | CLI Argument Parsing | Parses flags (`--json`, `--cwd`, `--agent`) and positional arguments | `process.argv` string array | Typed `values` and `positionals` | `src/cli/args.ts` | On CLI startup | Verified | `src/cli/args.ts#L1` |
+| **`node:fs/promises`** | Standard Library | Filesystem Operations | Async reads, directory creation, file stat, and unlinking | File paths, buffers | Text, metadata, void | `src/utils/fs.ts`, `src/core/workspace.ts` | Throughout all commands | Verified | `src/utils/fs.ts#L1` |
+| **`node:path`** | Standard Library | Path Manipulation | Resolves, normalizes, and compares filesystem paths | Path segments | Canonical path strings | `src/utils/paths.ts`, `src/security/files.ts` | Continuous | Verified | `src/utils/paths.ts#L1` |
+| **`node:child_process` (`spawnSync`)** | Standard Library | Subprocess Execution | Executes external tools (`git`, `npm`, `graphify`, `claude`) | Command string, args array, environment | Exit code, stdout, stderr | `src/utils/proc.ts`, `src/integrations/exec.ts` | During diagnostics, testing, setup | Verified | `src/utils/proc.ts#L1` |
+| **`node:crypto`** | Standard Library | Cryptographic Hashing | Generates SHA-256 file fingerprints and unique task IDs | File buffers, strings | Hex digests, UUIDs | `src/utils/fs.ts`, `src/tasks/task.ts` | During facts loading, task creation | Verified | `src/utils/fs.ts#L2` |
+| **`node:os`** | Standard Library | OS Abstraction | Resolves home directory, temp directories, and platform | System info | Paths (`tmpdir()`, `homedir()`) | `src/utils/paths.ts`, `src/integrations/manager.ts` | During path resolution | Verified | `src/integrations/manager.ts#L3` |
+| **`node:process`** | Standard Library | Process Lifecycle | Handles signals (`SIGINT`, `SIGTERM`), exit codes, and environment | OS signals, env vars | Exit code, cleanup execution | `src/cli/main.ts`, `src/cli/run.ts` | On startup and exit | Verified | `src/cli/main.ts#L7` |
+
+---
+
+## 2. Build & Development Tools
+
+The development and validation toolchain enforces strict code quality, type safety, and 90%+ test coverage.
+
+| Name | Category | Purpose in Project | Responsibility | Configuration Source | Status | Evidence |
+|---|---|---|---|---|---|---|
+| **TypeScript (v6.0)** | Compiler / Type Checker | Type safety & compilation | Compiles TypeScript in `src/` to ES modules in `dist/` | `tsconfig.json`, `tsconfig.build.json` | Verified | `package.json#L66`, `scripts/clean.mjs` |
+| **ESLint (v10.12)** | Static Analysis / Linter | Code quality enforcement | Detects syntax issues, unused variables, and style violations | `eslint.config.js` | Verified | `package.json#L65`, `npm run lint` |
+| **Vitest (v5.0)** | Test Runner | Unit, Integration, & E2E Testing | Runs 778 tests across 31 test suites with mock runners | `vitest.config.ts` | Verified | `package.json#L68`, `npm test` |
+| **`@vitest/coverage-v8`** | Code Coverage | Coverage threshold gate | Measures statement, branch, function, and line coverage | `vitest.config.ts` (`coverage` thresholds: 90%) | Verified | `package.json#L64`, `npm run coverage` |
+| **Release Check Script** | Internal Tool | Pre-release gate | Enforces clean Git tree, SemVer tag, changelog, and zero TODO/FIXME markers | `scripts/release-check.mjs` | Verified | `scripts/release-check.mjs` |
+| **Smoke Test Script** | Internal Tool | End-to-end packaging test | Packs npm tarball, installs in clean temp dirs, runs real CLI commands | `scripts/smoke.mjs` | Verified | `scripts/smoke.mjs` |
+
+---
+
+## 3. Coordinated External Tools & Coding Agents
+
+DevWorkspace coordinates external tools and coding agents through clean, documented boundaries:
+
+### A. Coding Agent Instruction Targets
+
+| Tool Name | Type | How DevWorkspace Integrates With It | Managed Files | Verified Working | Evidence |
+|---|---|---|---|---|---|
+| **Claude Code** | AI Coding Agent (CLI/Desktop) | Injects managed section into project instructions and generates custom task routing skill | `CLAUDE.md`, `.claude/skills/devworkspace/SKILL.md` | Yes | `src/agents/claude/adapter.ts` |
+| **OpenAI Codex** | AI Coding Agent | Generates repository instructions adhering to open agent standards | `AGENTS.md` | Yes | `src/agents/codex/adapter.ts` |
+| **Google Antigravity** | AI Coding Agent / IDE | Reads standard repository agent instructions | `AGENTS.md` | Yes | `src/agents/codex/adapter.ts` |
+| **Cursor** | AI Coding IDE | Writes project rules with YAML frontmatter `alwaysApply: true` | `.cursor/rules/devworkspace.mdc` (fallback: `.cursorrules`) | Yes | `src/agents/cursor/adapter.ts` |
+| **GitHub Copilot** | AI Coding Agent | Writes repository instruction file for Copilot in VS Code / GitHub | `.github/copilot-instructions.md` | Yes | `src/agents/copilot/adapter.ts` |
+
+### B. External Engineering Tools (Observed / Managed)
+
+| Tool Name | Package Source | Purpose in Ecosystem | DevWorkspace Integration Level | Status | Evidence |
+|---|---|---|---|---|---|
+| **Git** | CLI (`git`) | Version control & status tracking | Reads branch, HEAD commit, uncommitted diffs, and tracked files. Never runs destructive commands (`reset --hard`, `clean -fd`). | Core requirement for safety gates | `src/git/git.ts` |
+| **Graphify** | PyPI (`graphifyy`), binary `graphify` | Structural knowledge graph of code | DevWorkspace inspects executable on PATH, checks version, and coordinates project skill installation (`graphify install --project`). DevWorkspace **does not build the graph itself** (graph building uses an LLM). | Optional / Recommended | `src/integrations/adapters/graphify.ts` |
+| **Agent Skills** | GitHub: `addyosmani/agent-skills` | Engineering methodology slash commands (`/spec`, `/plan`, `/test`, `/review`, `/ship`) | Inspects native plugin in Claude Code (`claude plugin list`) or portable skills installed via `npx skills add`. | Optional / Recommended | `src/integrations/adapters/agent-skills.ts` |
+| **Ponytail** | GitHub: `DietrichGebert/ponytail` | Code complexity and diff review (`/ponytail-review`, `/ponytail-audit`) | Inspects native plugin or portable skills. Verifies that `node` is on PATH because Ponytail lifecycle hooks require Node.js. | Optional / Recommended | `src/integrations/adapters/ponytail.ts` |
+| **OmniRoute** | GitHub: `diegosouzapw/OmniRoute` | LLM model routing proxy | **Observed only**. DevWorkspace detects if `omniroute` is on PATH, but never installs it, never calls it, and never requires API keys. | Observed (Unused) | `src/integrations/adapters/omniroute.ts` |
+
+---
+
+## 4. Deep Component Analysis: Why Each Tool Exists & Impact If Removed
+
+### 1. `node:util (parseArgs)`
+- **Why it exists**: Provides strict, type-safe command-line argument parsing without needing heavy third-party libraries like `yargs`, `commander`, or `meow`.
+- **What happens if removed**: Argument parsing would break, or DevWorkspace would need to pull in an external dependency with hundreds of transitive dependencies, violating its zero-dependency invariant.
+
+### 2. `node:crypto (createHash)`
+- **Why it exists**: Computes SHA-256 hashes of repository source files and package manifests to detect when cached facts become `STALE`. Also generates deterministic task IDs (`T-YYYYMMDD-xxxx`).
+- **What happens if removed**: Staleness detection would have to rely on filesystem timestamps (`mtime`), which are notoriously unreliable across Git checkouts and CI environments.
+
+### 3. Git Integration (`src/git/git.ts`)
+- **Why it exists**: Detects uncommitted user work, captures baseline fingerprints at task start, and verifies whether credential files are accidentally tracked by Git.
+- **What happens if removed**: DevWorkspace still functions in non-Git folders, but cannot warn developers before running actions, cannot enforce baseline test comparison, and cannot attest that user work was untouched.
+
+### 4. Graphify Adapter (`src/integrations/adapters/graphify.ts`)
+- **Why it exists**: Knowledge graphs represent high-level architectural relationships between files, classes, and dependencies better than raw file dumps. DevWorkspace verifies that Graphify's skill is properly wired into the agent's environment.
+- **What happens if removed**: Coding agents would lack code-graph structural navigation and would rely entirely on text search (grep/glob). DevWorkspace core functionality would remain intact.
+
+### 5. Multi-Agent Adapters (`src/agents/`)
+- **Why it exists**: Prevents vendor lock-in to Claude Code. Allows teams using Cursor, Copilot, Codex, and Antigravity to share the exact same project facts, testing contracts, and verification rules.
+- **What happens if removed**: DevWorkspace would only work with Claude Code, severely limiting adoption in multi-agent engineering workflows.
+
+---
+
+## 5. Discrepancy & Gap Analysis
+
+Based on an exhaustive scan of the codebase vs documentation:
+
+| Documented Feature / Claim | Actual Implementation Status in Code | Notes & Evidence |
+|---|---|---|
+| **OmniRoute integration** | **Observed only (not executed)** | `src/integrations/adapters/omniroute.ts#L12` explicitly notes: `"Not used by DevWorkspace."` It inspects whether `omniroute` is on PATH for reporting, but never configures or invokes it. |
+| **Automatic Graph Construction** | **Delegated to agent / user** | DevWorkspace does not build the code graph itself because graph construction requires an LLM. It verifies that the `graphify` CLI exists and reminds the user to run `/graphify .` inside Claude Code. |
+| **Database Migrations Execution** | **Intentionally Blocked** | `src/verification/safety.ts#L84` explicitly blocks automatic execution of `migrations` or `db:migrate` scripts to protect live databases from unauthorized schema modifications. |
+| **Production Dependencies** | **Strictly Zero** | No external runtime dependencies exist in `package.json`. |
+
+---
+
+*Continue to [Chapter 4: Execution Flows](./04-execution-flows.md) for step-by-step traces of the CLI, analysis, skills, and task lifecycles.*
+