devworkspace 0.3.1 → 0.3.3

package/docs/architecture-report/04-execution-flows.md

@@ -0,0 +1,257 @@
+# Chapter 4: Execution Flows & Lifecycles
+
+> **Step-by-step operational traces of CLI startup, project analysis, agent skills coordination, and task completion verification.**
+
+---
+
+## 1. Workflow A: CLI Startup and Dispatch
+
+When a user or AI coding agent executes a DevWorkspace command in the terminal (e.g., `devworkspace status` or `npx devworkspace analyze`), the request flows through five distinct stages:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Developer / Agent
+    participant OS as Operating System / Shell
+    participant Main as CLI Entry (src/cli/main.ts)
+    participant Parser as Arg Parser (src/cli/args.ts)
+    participant Dispatcher as Dispatcher (src/cli/run.ts)
+    participant Service as Service Function (src/services/*)
+    participant Renderer as Renderer (src/cli/render.ts)
+
+    User->>OS: Runs "devworkspace analyze --cwd . --json"
+    OS->>Main: Launches node dist/cli/main.js
+    Note over Main: Hooks SIGINT & SIGTERM<br/>to run cleanups & release locks
+    Main->>Dispatcher: run(process.argv.slice(2))
+    Dispatcher->>Parser: parseCli(argv)
+    Note over Parser: Strict validation using node:util<br/>Rejects unknown flags immediately
+    Parser-->>Dispatcher: ParsedArgs { values, positionals }
+    Dispatcher->>Dispatcher: Resolve command alias ("tasks" -> "task list")
+    Dispatcher->>Dispatcher: Initialize Ctx (logger, styles, stdout/stderr, cwd)
+    Dispatcher->>Service: Call handler (e.g. analyzeWorkspace(ws, svc))
+    Service-->>Dispatcher: Returns structured result object
+    Dispatcher->>Renderer: Format output (JSON or styled ANSI/ASCII text)
+    Renderer-->>Main: Write to stdout / stderr
+    Main->>OS: Set process.exitCode (0, 1, 2, 3, or 130)
+    OS-->>User: Process terminates with output
+```
+
+### Detailed Trace:
+1. **OS Invocation**: The shell resolves `devworkspace` via the `bin` field in `package.json` (`dist/cli/main.js`).
+2. **Signal Traps**: `src/cli/main.ts` immediately attaches listeners for `SIGINT` (Ctrl+C) and `SIGTERM`. If triggered, it calls `runCleanups()` to remove temporary lockfiles and exits with status 130.
+3. **Strict Argument Parsing**: `src/cli/args.ts` passes flags to `node:util/parseArgs`. If an unrecognized flag is passed (e.g., `--dr-run` instead of `--dry-run`), it throws a `DevWorkspaceError('USAGE')` with exit code 2.
+4. **Context Construction**: `src/cli/run.ts` constructs a `Ctx` object containing `args`, `svc` (`cwd`, `dryRun`, `env`, `runner`), styling helpers (`makeStyle`), and output functions.
+5. **Execution**: The handler calls the pure service function (e.g. `analyzeWorkspace()`), which returns a typed result object.
+6. **Output Rendering**:
+   - If `--json` was passed, the raw JavaScript object is serialized with `JSON.stringify(value, null, 2)` and printed to `stdout`.
+   - Otherwise, the appropriate rendering function from `src/cli/render.ts` formats the result with badges, colors, and tables.
+7. **Exit Code Propagation**: `process.exitCode` is set to the exit code determined by the handler (0 for success, 1 for failure, 2 for usage errors, 3 for strict mode warnings).
+
+---
+
+## 2. Workflow B: Project Analysis Workflow
+
+Running `devworkspace analyze` scans the repository and creates the testing contract and onboarding prompt.
+
+```mermaid
+flowchart TD
+    Start["devworkspace analyze"] --> CheckWs["Find .devworkspace/<br/>(src/core/workspace.ts)"]
+    CheckWs --> Lock["Acquire File Lock<br/>(.devworkspace/local/devworkspace.lock)"]
+    
+    subgraph ScanningPhase["1. Bounded Filesystem Scan"]
+        Scan["scan.ts: readdirRecursive()<br/>• Max 10,000 files<br/>• Ignore node_modules, .git, dist<br/>• Detect symlinks (skip to prevent loops)"]
+    end
+    
+    subgraph DetectionPhase["2. Deterministic Detection"]
+        DetectStack["detect.ts:<br/>• Language extensions (.ts, .py, .go)<br/>• Frameworks from manifests<br/>• Monorepo structure"]
+        DetectCommands["commands.ts:<br/>• Inspect scripts in package.json<br/>• Map typecheck, unit, integration, build<br/>• Record exact cwd per command"]
+        DetectDocs["docs.ts:<br/>• Identify READMEs, docs/, ADRs (max 25)"]
+        DetectEntry["entrypoints.ts:<br/>• Identify server.ts, workers, CLIs"]
+        DetectSens["files.ts:<br/>• Record names of .env files (never read content)"]
+    end
+
+    subgraph OutputPhase["3. State & Prompt Generation"]
+        WriteDiscovery[".devworkspace/analysis/discovery.json"]
+        WriteCommands[".devworkspace/context/commands.json"]
+        GenPrompt["prompts/onboarding.ts:<br/>Generate onboarding-prompt.md"]
+        ValidateReqs["prompts/requirements.ts:<br/>Validate prompt against 21 requirements"]
+        SaveFacts["knowledge/facts.ts:<br/>Record 10+ DETECTED facts in facts.json"]
+    end
+
+    Lock --> ScanningPhase
+    ScanningPhase --> DetectionPhase
+    DetectionPhase --> OutputPhase
+    OutputPhase --> ReleaseLock["Release File Lock"]
+    ReleaseLock --> Finish["Render Analysis Summary to stdout"]
+```
+
+### Detailed Trace:
+1. **Workspace Verification**: `requireWorkspace(cwd)` walks upwards looking for `.devworkspace/project.json`.
+2. **Mutual Exclusion**: `withLock` acquires an exclusive lock (`.devworkspace/local/devworkspace.lock`) so concurrent CLI commands do not collide.
+3. **Filesystem Scanning (`scan.ts`)**: Bounded recursive walk. Collects relative paths, sizes, and file extensions while skipping `node_modules/`, `.git/`, `dist/`, `build/`, `vendor/`, and ignored entries.
+4. **Deterministic Stack Detection (`detect.ts`)**:
+   - Inspects manifests safely using `safeReadText` (bounded read up to 1MB).
+   - Identifies monorepo packages (e.g. `backend` and `frontend`).
+   - Identifies framework dependencies (React, Fastify, Drizzle, etc.).
+   - Notes presence of sensitive files (`backend/.env`) without opening them.
+5. **Testing Contract Derivation (`commands.ts`)**:
+   - Maps scripts from each package into standardized check IDs (`typecheck`, `unit`, `integration`, `lint`, `build`).
+   - Flags mutative scripts (`format: "prettier --write"`) with `mutates: true`.
+   - Identifies working directory (`cwd: "backend"`, `cwd: "frontend"`).
+6. **Prompt Assembly & Validation (`onboarding.ts` & `requirements.ts`)**:
+   - Generates `.devworkspace/analysis/onboarding-prompt.md`.
+   - Validates that the generated prompt passes all 21 prompt safety requirements (untrusted data rules, secrets rules, git safety rules, etc.).
+7. **Atomic Persistence**: Writes `discovery.json`, `commands.json`, and initial `DETECTED` facts into `facts.json` using atomic temporary file renames.
+
+---
+
+## 3. Workflow C: Agent Skills & Integrations Lifecycle
+
+Running `devworkspace setup --integrations` inspects external tools on the machine, checks their health, and plans their installation non-destructively:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Developer / Agent
+    participant Svc as setupIntegrations()
+    participant Mgr as IntegrationManager (src/integrations/manager.ts)
+    participant Adapter as Adapter (Graphify / Agent Skills / Ponytail)
+    participant Exec as Process Runner (src/integrations/exec.ts)
+    participant Protect as Snapshot Guard (src/integrations/protect.ts)
+    participant FS as Local Filesystem
+
+    User->>Svc: devworkspace setup --integrations [--yes]
+    Svc->>Mgr: run(options)
+    
+    loop For each adapter (Graphify, Agent Skills, Ponytail, OmniRoute)
+        Mgr->>Adapter: inspect(AdapterContext, deep=true)
+        Adapter->>Exec: which(toolName), run(tool --version)
+        Exec-->>Adapter: Tool status, version string
+        Adapter-->>Mgr: IntegrationReport { status: INSTALLED | NOT_INSTALLED | DEGRADED }
+        
+        Mgr->>Adapter: plan(AdapterContext, targetScope)
+        Adapter-->>Mgr: PlanResult { steps, protectPaths, blockers }
+    end
+
+    alt Dry-Run or Missing --yes
+        Mgr-->>User: Output planned steps & require confirmation (Exit Code 2)
+    else User Confirmed (--yes)
+        loop For each planned step
+            Mgr->>Protect: Take snapshot of protectPaths (e.g. CLAUDE.md)
+            Mgr->>Exec: Run installation command (e.g. "graphify install --project")
+            Mgr->>Protect: Verify snapshot; rollback if user changes overwritten
+            Mgr->>Adapter: Re-inspect to verify successful installation
+        end
+        Mgr->>FS: Save state to .devworkspace/state/integrations.json
+        Mgr-->>User: Report outcomes (VERIFIED, RESTART_REQUIRED, or DEGRADED)
+    end
+```
+
+### Key Safety Invariant: Pre-Execution Snapshots
+When an external tool modifies repository files (such as `graphify install --project` modifying `CLAUDE.md`), `src/integrations/protect.ts` records SHA-256 hashes of the files before running the tool. If the tool overwrites uncommitted user modifications outside its managed area, DevWorkspace immediately restores the snapshot and aborts with an error.
+
+---
+
+## 4. Workflow D: Task Lifecycle & The Completion Gate
+
+The task engine prevents coding agents from prematurely declaring tasks finished:
+
+```mermaid
+stateDiagram-v2
+    [*] --> IDEA: devworkspace task new "<description>"
+    
+    IDEA --> SPECIFIED: Specify acceptance criteria (task update)
+    SPECIFIED --> PLANNED: Add implementation steps (task update)
+    PLANNED --> IN_PROGRESS: Start coding / take baseline
+    
+    IN_PROGRESS --> TESTING: Code written; run test suite
+    TESTING --> REVIEW: Tests pass; review git diff
+    
+    REVIEW --> COMPLETED: devworkspace task status COMPLETED
+    
+    IN_PROGRESS --> BLOCKED: Unforeseen blocker / dependency
+    BLOCKED --> IN_PROGRESS: Blocker resolved
+    
+    TESTING --> FAILED: Verification failed
+    FAILED --> IN_PROGRESS: Fix applied
+    
+    COMPLETED --> [*]
+
+    note right of COMPLETED
+        evaluateGate() enforces:
+        1. All required checks == PASS (or user-override)
+        2. No test count regressions (passed >= baseline, failed <= baseline)
+        3. Read-only tasks modified 0 files
+        4. userWorkIntact == true
+        5. knowledgeReviewed == true
+        6. finalStateInspected == true
+        7. completionSummary is present
+    end note
+```
+
+### Detailed Trace of a Task:
+1. **Creation (`task new`)**:
+   - The user prompt is classified via regex and keyword matching in `routing.ts` (e.g. `FEATURE`).
+   - `captureScope()` records a snapshot of current Git HEAD and currently dirty files. Any files already dirty before this task are marked as `baseline` and will not be blamed on the task.
+   - Initial verification checks are configured from the project testing contract.
+2. **Execution & Evidence Recording (`task run` / `task verify`)**:
+   - The agent executes contract commands safely using `devworkspace task run <id> <check>`.
+   - Results are recorded with exact exit code, duration, timestamp, and kind (`executed` vs `claimed`).
+3. **Baseline Comparison (`task tests`)**:
+   - For bug fixes and refactors, the agent records baseline tests (`task tests <id> --phase baseline --passed 100 --failed 1`).
+   - After the fix, the agent records final tests (`--phase after --passed 101 --failed 0`).
+4. **Mandatory Attestations (`task attest`)**:
+   - The agent must explicitly confirm:
+     - `--user-work-intact`: No pre-existing user code was overwritten.
+     - `--knowledge-reviewed`: Durable conventions or decisions were logged.
+     - `--final-state-inspected`: `git status` was checked before closing.
+5. **Completion Transition (`task status COMPLETED`)**:
+   - `transitionTask()` calls `evaluateGate()`. If even one required check is `PENDING` or `FAIL`, or if test regressions occurred, or if an attestation is missing, it **throws an error** and keeps the task open.
+
+---
+
+## 5. Workflow E: Knowledge Refresh & Staleness Detection
+
+Running `devworkspace refresh` ensures project knowledge stays synchronized with the codebase:
+
+```mermaid
+flowchart TD
+    Start["devworkspace refresh"] --> Load["Load facts from .devworkspace/context/facts.json"]
+    
+    subgraph StalenessCheck["1. Inspect Evidence Files"]
+        CheckSource["For each fact: inspect its sources[] files"]
+        HashSource["Calculate current SHA-256 hash of source files"]
+        CompareHash{"Current hash ==<br/>Recorded hash?"}
+        
+        CompareHash -- Yes --> Keep["Status remains VERIFIED / DETECTED"]
+        CompareHash -- No or Missing --> MarkStale["Mark fact status as STALE<br/>(Authority rank drops to 1)"]
+    end
+    
+    subgraph ReDiscovery["2. Deterministic Re-Discovery"]
+        ReScan["Re-run detect.ts over manifests"]
+        MergeFacts["Merge new findings with existing facts<br/>(Higher authority rank wins)"]
+    end
+    
+    subgraph Output["3. Refresh Prompt Generation"]
+        SaveUpdated["Save updated facts.json atomically"]
+        WriteRefreshPrompt["Generate .devworkspace/analysis/refresh-prompt.md<br/>Listing all STALE facts for agent review"]
+    end
+
+    Load --> StalenessCheck
+    StalenessCheck --> ReDiscovery
+    ReDiscovery --> Output
+    Output --> Done["Display refresh summary"]
+```
+
+### Authority Ranking Rule:
+When merging new findings into existing facts, `authorityRank()` in `src/knowledge/facts.ts` enforces that a lower-ranked source can **never** silently overwrite a higher-ranked fact:
+- **Rank 5**: `USER_DECISION` (Direct human command or decision)
+- **Rank 4**: `DETECTED` (Extracted directly from package manifests)
+- **Rank 3**: `VERIFIED` (Derived by an AI agent and verified against repository evidence)
+- **Rank 2**: `INFERRED` (Heuristic guess)
+- **Rank 1**: `STALE` / `UNKNOWN`
+
+---
+
+*Continue to [Chapter 5: Codebase Map](./05-codebase-map.md) for the directory structure and module responsibility matrix.*
+

package/docs/architecture-report/05-codebase-map.md

@@ -0,0 +1,150 @@
+# Chapter 5: Codebase Map & Module Responsibilities
+
+> **A comprehensive structural map of the DevWorkspace codebase, module directory boundaries, and source file responsibilities.**
+
+---
+
+## 1. Diagram 7: Repository Structure Map
+
+```mermaid
+graph TD
+    Root["devworkspace/"]
+
+    subgraph Src["src/ (TypeScript Source Code)"]
+        CLI["cli/ - Entrypoints, argument parsing, command dispatch, and formatting"]
+        Services["services/ - Pure service orchestration layer (16 command handlers)"]
+        Discovery["discovery/ - Deterministic repository scanning and stack detection"]
+        Agents["agents/ - Multi-agent adapters (Claude, Codex, Cursor, Copilot)"]
+        Integrations["integrations/ - External tool management (Graphify, Skills, Ponytail)"]
+        Tasks["tasks/ - Task routing, state machines, and completion gates"]
+        Knowledge["knowledge/ - Facts engine, authority ranking, and staleness detection"]
+        Decisions["decisions/ - Architecture Decision Records (ADRs) management"]
+        Sessions["sessions/ - Compact engineering session handover logs"]
+        Verification["verification/ - Command safety checks and scope tracking"]
+        Security["security/ - Path traversal defense, symlink containment, secret redaction"]
+        Core["core/ - Workspace discovery, schema migrations, and versioning"]
+        Config["config/ - Type-safe data contracts and schema validators"]
+        Git["git/ - Read-only Git state and tracked file discovery"]
+        Prompts["prompts/ - Onboarding and refresh prompt generators and validators"]
+        Portability["portability/ - JSON export/import bundling and validation"]
+        Utils["utils/ - Atomic file operations, lockfiles, loggers, and cleanup"]
+        Errors["errors/ - Typed error hierarchy and exit code definitions"]
+    end
+
+    subgraph Scripts["scripts/ (Build & Release Automation)"]
+        Clean["clean.mjs - Build directory cleanup"]
+        ReleaseCheck["release-check.mjs - Pre-release quality gate"]
+        Smoke["smoke.mjs - Fresh-install smoke testing"]
+        Bench["bench.mjs - Performance and token usage benchmarking"]
+    end
+
+    subgraph Tests["tests/ (Automated Test Suites)"]
+        Unit["unit/ - 21 unit test suites for individual modules"]
+        Integration["integration/ - 5 integration suites testing full flows and shims"]
+        E2E["e2e/ - 2 end-to-end scenario suites testing real CLI execution"]
+        Helpers["helpers/ - Fake process runners and tool mocks"]
+    end
+
+    subgraph Docs["docs/ (Project Documentation)"]
+        UserDocs["User & Developer Guides (getting-started, architecture, security, etc.)"]
+        ReportDir["architecture-report/ - This comprehensive architecture documentation"]
+        ImplNotes["implementation/ - Internal design notes and historical ADRs"]
+    end
+
+    Root --> Src
+    Root --> Scripts
+    Root --> Tests
+    Root --> Docs
+```
+
+---
+
+## 2. Source Code Modules (`src/`) Directory Matrix
+
+| Directory | Responsibility | Primary Files | Key Functions / Types |
+|---|---|---|---|
+| **`src/cli/`** | Presentation layer: argument parsing, signal trapping, command routing, and ANSI/ASCII rendering. | `main.ts`, `args.ts`, `run.ts`, `render.ts`, `help.ts` | `run()`, `parseCli()`, `defaultIO()`, `makeStyle()` |
+| **`src/services/`** | Business logic layer: pure asynchronous functions coordinating workspace operations. | `init.ts`, `analysis.ts`, `status.ts`, `doctor.ts`, `agent.ts`, `tasks.ts`, `verify.ts`, `knowledge.ts`, `records.ts`, `portability.ts`, `reset.ts`, `migrate.ts` | `initWorkspace()`, `analyzeWorkspace()`, `getStatus()`, `runDoctor()`, `installAgent()`, `createTask()` |
+| **`src/discovery/`** | Deterministic repository discovery without AI models. | `scan.ts`, `detect.ts`, `commands.ts`, `docs.ts`, `entrypoints.ts`, `ignore.ts`, `cache.ts` | `scanRepository()`, `detectProject()`, `buildContract()`, `detectDocs()`, `discoverEntryPoints()` |
+| **`src/agents/`** | Multi-agent compatibility adapters for instruction files. | `index.ts`, `types.ts`, `shared.ts`, `claude/adapter.ts`, `codex/adapter.ts`, `cursor/adapter.ts`, `copilot/adapter.ts` | `AgentAdapter`, `mergeSection()`, `removeManagedSection()`, `getAgentAdapter()`, `detectAllAgentFiles()` |
+| **`src/integrations/`** | Inspection, planning, and execution of external engineering tools. | `manager.ts`, `exec.ts`, `protect.ts`, `types.ts`, `adapters/agent-skills.ts`, `adapters/graphify.ts`, `adapters/ponytail.ts`, `adapters/omniroute.ts` | `IntegrationManager`, `inspectAll()`, `setupIntegrations()`, `findClaudeCli()`, `createSnapshot()` |
+| **`src/tasks/`** | Task state machine, prompt classification, and completion gate evaluation. | `task.ts`, `routing.ts` | `Task`, `createTaskRecord()`, `transitionTask()`, `evaluateGate()`, `classifyRequest()`, `WORKFLOWS` |
+| **`src/knowledge/`** | Project knowledge facts storage, authority ranking, and staleness validation. | `facts.ts` | `loadFacts()`, `saveFacts()`, `addFact()`, `authorityRank()`, `evaluateStaleness()` |
+| **`src/decisions/`** | Architecture Decision Records (ADRs) in human-readable Markdown. | `decision.ts` | `Decision`, `renderDecision()`, `parseDecision()`, `listDecisions()`, `recordDecision()` |
+| **`src/sessions/`** | Engineering session handoff records. | `session.ts` | `Session`, `saveSession()`, `listSessions()` |
+| **`src/verification/`** | Pre-run safety classification, database protection, and package scoping. | `safety.ts`, `scope.ts` | `classifyCommand()`, `loadTestEnv()`, `captureScope()`, `dirtyFiles()`, `dirtyPackages()` |
+| **`src/security/`** | Secrets redaction and filesystem containment. | `files.ts`, `redact.ts` | `safeReadText()`, `isSensitiveFile()`, `findSecrets()`, `redact()`, `SECRET_PATTERNS` |
+| **`src/core/`** | Workspace discovery, versioned file read/write, and schema migrations. | `workspace.ts`, `versioned.ts`, `migrations.ts`, `version.ts` | `findWorkspaceRoot()`, `requireWorkspace()`, `wsPaths()`, `migrateData()`, `packageVersion()` |
+| **`src/config/`** | Schemas and pure validation functions. | `schemas.ts`, `validate.ts` | `ProjectConfig`, `Fact`, `CommandEntry`, `validateProject()`, `validateFacts()`, `validateCommands()` |
+| **`src/git/`** | Read-only Git state inspection and porcelain status parsing. | `git.ts` | `gitAvailable()`, `getGitState()`, `gitTrackedFiles()`, `parsePorcelainZ()` |
+| **`src/prompts/`** | Generation and validation of onboarding and refresh prompts. | `onboarding.ts`, `refresh.ts`, `requirements.ts` | `buildOnboardingPrompt()`, `buildRefreshPrompt()`, `validatePrompt()`, `ONBOARDING_REQUIREMENTS` |
+| **`src/portability/`** | Bundling and validating portable project knowledge for export/import. | `bundle.ts` | `Bundle`, `parseBundle()`, `isPortablePath()`, `isExportable()` |
+| **`src/utils/`** | Utility layer for atomic I/O, lockfiles, path handling, and child processes. | `fs.ts`, `paths.ts`, `lock.ts`, `proc.ts`, `logger.ts`, `cleanup.ts` | `atomicWriteJson()`, `readTextBounded()`, `isInside()`, `assertNoSymlinkEscape()`, `withLock()` |
+| **`src/errors/`** | Typed error hierarchy, exit code mapping, and user-facing formatting. | `index.ts` | `DevWorkspaceError`, `EXIT`, `formatError()`, `isDevWorkspaceError()` |
+
+---
+
+## 3. Automation Scripts (`scripts/`)
+
+| Script | Purpose | Execution Mechanism | Invariant Enforced |
+|---|---|---|---|
+| **`clean.mjs`** | Deletes output directory (`dist/`) before compilation. | `node scripts/clean.mjs dist` | Ensures no stale `.js` or `.d.ts` files linger across builds. |
+| **`release-check.mjs`** | Pre-publish verification gate that tests 12 criteria before release. | `node scripts/release-check.mjs` | Fails if Git tree is dirty, HEAD is untagged, coverage < 90%, docs are missing, or `TODO`/`FIXME`/`stub` markers exist in `src/`. |
+| **`smoke.mjs`** | End-to-end packaging and fresh-install smoke test. | `node scripts/smoke.mjs` | Packs the tarball with `npm pack`, installs in clean temporary directories, tests global and npx invocations, and verifies that `.env` secrets are never leaked. |
+| **`bench.mjs`** | Synthetic performance benchmark. | `node scripts/bench.mjs` | Generates a 3,000-file simulated monorepo and measures execution duration and estimated token counts for `analyze`, `refresh`, and `context`. |
+
+---
+
+## 4. Test Suite Structure (`tests/`)
+
+The repository maintains **31 test files** covering 778 test cases:
+
+```
+tests/
+├── unit/                               # Fast, isolated tests for pure functions & domain logic
+│   ├── agent-adapters.test.ts          # Tests Claude, Codex, Cursor, and Copilot adapters
+│   ├── agent-prompts.test.ts           # Tests onboarding prompt generation & requirements
+│   ├── aux-dirs.test.ts                # Tests auxiliary and build folder filtering
+│   ├── claude-plugin-list.test.ts      # Tests Claude Code plugin JSON output parsing
+│   ├── discovery-docs-entrypoints.test.ts # Tests doc & entry point discovery
+│   ├── discovery-packages.test.ts      # Tests monorepo & package manifest parsing
+│   ├── docs.test.ts                    # Tests documentation scanning limits
+│   ├── facts.test.ts                   # Tests authority ranking and fact storage
+│   ├── fs-lock-migrations.test.ts      # Tests lockfiles and schema migrations
+│   ├── git-detect.test.ts              # Tests git status and porcelain parsing
+│   ├── ignore-scan.test.ts             # Tests ignore patterns and directory walk
+│   ├── integrations-core.test.ts       # Tests integration manager planning & rollback
+│   ├── integrations-graphify.test.ts   # Tests Graphify inspection & version detection
+│   ├── integrations-path.test.ts       # Tests persistent PATH additions
+│   ├── integrations-plugins.test.ts    # Tests marketplace plugin verification
+│   ├── paths.test.ts                   # Tests path containment & symlink traversal
+│   ├── proc.test.ts                    # Tests child process execution & timeouts
+│   ├── records-bundle.test.ts          # Tests ADRs, sessions, and portability bundles
+│   ├── release-hygiene.test.ts         # Tests absence of TODO/FIXME markers in production
+│   ├── routing.test.ts                 # Tests task request classification & workflows
+│   ├── security.test.ts                # Tests safeReadText, secret redaction, and symlinks
+│   ├── staleness.test.ts               # Tests fact staleness detection on file changes
+│   ├── tasks.test.ts                   # Tests task lifecycle & completion gate
+│   └── verification-gate.test.ts       # Tests command safety & test environment gates
+│
+├── integration/                        # Multi-component flows using fake process runners
+│   ├── acceptance-022.test.ts          # End-to-end integration acceptance suite
+│   ├── discovery-monorepo.test.ts      # Tests complex monorepo discovery scenarios
+│   ├── flows.test.ts                   # Tests full init -> analyze -> task -> status flows
+│   ├── integrations-processes.test.ts  # Tests integrations with simulated child processes
+│   └── progressive-context.test.ts     # Tests tiered context retrieval
+│
+├── e2e/                                # Real CLI invocations driving compiled dist/
+│   ├── reset.test.ts                   # Tests reset safety, confirmation, and plans
+│   └── scenarios.test.ts               # Full lifecycle CLI scenarios in real temp projects
+│
+└── helpers/                            # Reusable test harnesses
+    ├── fakeRunner.ts                   # Deterministic process mock runner
+    ├── fakeTools.ts                    # Mock implementations of claude, graphify, npm
+    └── index.ts                        # Temp workspace builders & test assertions
+```
+
+---
+
+*Continue to [Chapter 6: Command Reference](./06-command-reference.md) for detailed documentation of all 16 CLI commands.*
+