devworkspace 0.3.1 → 0.3.2

package/docs/architecture-report/10-feature-status.md

@@ -0,0 +1,110 @@
+# Chapter 10: Feature Implementation Status & Discrepancy Analysis
+
+> **Comprehensive matrix of fully implemented, partially implemented, optional, and unverified capabilities across the DevWorkspace codebase, grounded in source-code evidence.**
+
+---
+
+## 1. Diagram 8: Feature Implementation Map
+
+The following architectural map illustrates the implementation status of all major functional areas in DevWorkspace v0.3.1:
+
+```mermaid
+flowchart TD
+    subgraph FullyImplemented["🟢 Fully Implemented & Verified in Source"]
+        CoreInit["Workspace Init & Reset\n(src/services/init.ts, reset.ts)"]
+        DiscoveryScan["Deterministic Discovery Scanner\n(src/discovery/scan.ts, detect.ts)"]
+        TestingContract["Testing Contract Mapping\n(src/discovery/commands.ts)"]
+        TaskEngine["Task Lifecycle & Verification Gates\n(src/tasks/task.ts, routing.ts)"]
+        SafeExecution["Safe Task Run (ReadOnly Checks)\n(src/services/verify.ts)"]
+        FactsEngine["Knowledge Facts & Authority Ranks\n(src/knowledge/facts.ts)"]
+        ADRRecords["Architecture Decision Records (ADRs)\n(src/services/records.ts)"]
+        MultiAgentAdapters["Agent Adapters (Claude, Codex, Cursor, Copilot)\n(src/agents/*)"]
+        SecretsRedaction["Secrets Redaction & Symlink Containment\n(src/security/*)"]
+        PortabilityBundle["Import / Export Knowledge Bundles\n(src/services/portability.ts)"]
+    end
+
+    subgraph PartialOrGuarded["🟡 Partial / Guarded by Design"]
+        DBExecution["Service & DB-Touching Test Execution\n(src/verification/safety.ts: requires testenv declare)"]
+        DeepIntegrations["Integration Auto-Repair & Verification\n(src/integrations/manager.ts: requires --yes)"]
+    end
+
+    subgraph OptionalOrDelegated["🔵 Optional / Ecosystem-Delegated"]
+        GraphifyGraph["Graphify Graph Construction\n(src/integrations/adapters/graphify.ts: delegated to Claude Code /graphify .)"]
+        OmniRouteObs["OmniRoute Model Routing\n(src/integrations/adapters/omniroute.ts: observed on PATH only, never invoked)"]
+    end
+
+    subgraph UnverifiedOrPlanned["⚪ External / Unimplemented in Core"]
+        LiveTranscripts["Live Interactive Transcripts\n(Explicitly avoided: only summary handoffs stored)"]
+        NetworkTelemetry["Cloud Telemetry / Remote Analytics\n(Explicitly avoided: zero network calls)"]
+    end
+```
+
+---
+
+## 2. Feature Implementation Status Matrix
+
+Every capability in the DevWorkspace codebase has been analyzed and classified into one of four statuses:
+- 🟢 **Fully Implemented**: Production-ready, fully backed by TypeScript source code and passing tests.
+- 🟡 **Guarded / Partial**: Implemented with intentional safety constraints or requiring human approval.
+- 🔵 **Optional / Delegated**: Tooling integration recognized by DevWorkspace but delegated to external CLIs or LLMs.
+- ⚪ **Excluded by Design**: Functionality intentionally excluded to preserve privacy, token economy, or zero-dependency invariants.
+
+| # | Feature Name | Category | Status | Verified Source Evidence | Architectural Notes & Invariants |
+|---|---|---|:---:|---|---|
+| **01** | **Workspace Initialization** | Core | 🟢 Fully Implemented | [`src/services/init.ts:25`](file:///d:/projects/codeing_stuff/devworkspace/src/services/init.ts#L25) | Creates `.devworkspace/`, `project.json`, starter facts, and ignore rules. Idempotent. |
+| **02** | **Workspace Reset** | Core | 🟢 Fully Implemented | [`src/services/reset.ts:20`](file:///d:/projects/codeing_stuff/devworkspace/src/services/reset.ts#L20) | Safe deletion guarded by mandatory `--yes` flag. Extracts agent blocks if requested. |
+| **03** | **Health Diagnostics (Doctor)** | Core | 🟢 Fully Implemented | [`src/services/doctor.ts:35`](file:///d:/projects/codeing_stuff/devworkspace/src/services/doctor.ts#L35) | Separately reports workspace state, git hygiene, security, and integrations. |
+| **04** | **Schema Migrations** | Core | 🟢 Fully Implemented | [`src/core/migrations.ts:18`](file:///d:/projects/codeing_stuff/devworkspace/src/core/migrations.ts#L18) | Forward migrations for schema version upgrades with automatic backups. |
+| **05** | **Repository Scanner** | Discovery | 🟢 Fully Implemented | [`src/discovery/scan.ts:40`](file:///d:/projects/codeing_stuff/devworkspace/src/discovery/scan.ts#L40) | Bounded directory traversal; ignores `node_modules`, `.git`, `dist`, `target`. |
+| **06** | **Stack & Framework Detection** | Discovery | 🟢 Fully Implemented | [`src/discovery/detect.ts:50`](file:///d:/projects/codeing_stuff/devworkspace/src/discovery/detect.ts#L50) | Detects Node, Python, Rust, Go, React, Next.js, Vitest, Jest, Docker, monorepos. |
+| **07** | **Testing Contract Mapping** | Discovery | 🟢 Fully Implemented | [`src/discovery/commands.ts:28`](file:///d:/projects/codeing_stuff/devworkspace/src/discovery/commands.ts#L28) | Maps package scripts to `typecheck`, `lint`, `unit`, `integration`, `e2e`, `security`, `build`. |
+| **08** | **Entrypoints & Docs Discovery**| Discovery | 🟢 Fully Implemented | [`src/discovery/docs.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/discovery/docs.ts), [`entrypoints.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/discovery/entrypoints.ts) | Discovers `README.md`, `CONTRIBUTING.md`, architectural docs, and application entrypoints. |
+| **09** | **Onboarding Prompt Generation**| Discovery | 🟢 Fully Implemented | [`src/services/analysis.ts:60`](file:///d:/projects/codeing_stuff/devworkspace/src/services/analysis.ts#L60) | Emits `.devworkspace/analysis/onboarding-prompt.md` optimized for Claude Code. |
+| **10** | **Task State Machine** | Tasks | 🟢 Fully Implemented | [`src/tasks/task.ts:30`](file:///d:/projects/codeing_stuff/devworkspace/src/tasks/task.ts#L30) | Full lifecycle: `TODO` → `IN_PROGRESS` → `BLOCKED` / `COMPLETED` / `CANCELLED`. |
+| **11** | **Task Routing & Classification**| Tasks | 🟢 Fully Implemented | [`src/tasks/routing.ts:25`](file:///d:/projects/codeing_stuff/devworkspace/src/tasks/routing.ts#L25) | Classifies requests into `BUG`, `FEATURE`, `REFACTOR`, `DOCS`, `INVESTIGATION`. |
+| **12** | **Completion Gate (`evaluateGate`)**| Tasks | 🟢 Fully Implemented | [`src/tasks/task.ts:165`](file:///d:/projects/codeing_stuff/devworkspace/src/tasks/task.ts#L165) | Blocks completion until contracts pass, regressions are zero, and attestations pass. |
+| **13** | **Read-Only Check Execution** | Verification | 🟢 Fully Implemented | [`src/services/verify.ts:80`](file:///d:/projects/codeing_stuff/devworkspace/src/services/verify.ts#L80) | `devworkspace task run` executes non-destructive checks (`typecheck`, `lint`, `unit`). |
+| **14** | **Database-Touching Execution** | Verification | 🟡 Guarded / Partial | [`src/verification/safety.ts:28`](file:///d:/projects/codeing_stuff/devworkspace/src/verification/safety.ts#L28)| Blocked unless developer declares local isolation via `devworkspace testenv declare`. |
+| **15** | **Hazardous Script Blocking** | Verification | 🟢 Fully Implemented | [`src/verification/safety.ts:28`](file:///d:/projects/codeing_stuff/devworkspace/src/verification/safety.ts#L28)| Scripts with `drop`, `truncate`, `flush`, `migrate`, `seed`, `rm -rf` are refused. |
+| **16** | **Durable Facts Engine** | Knowledge | 🟢 Fully Implemented | [`src/knowledge/facts.ts:30`](file:///d:/projects/codeing_stuff/devworkspace/src/knowledge/facts.ts#L30) | Key-value store with authority ranking (`user` > `file` > `ai`) and evidence hashes. |
+| **17** | **Staleness Invalidation** | Knowledge | 🟢 Fully Implemented | [`src/services/refresh.ts:40`](file:///d:/projects/codeing_stuff/devworkspace/src/services/refresh.ts#L40)| Automatically flags facts `STALE` when source files are modified or deleted. |
+| **18** | **Progressive Context (`--for`)**| Knowledge | 🟢 Fully Implemented | [`src/services/taskContext.ts:35`](file:///d:/projects/codeing_stuff/devworkspace/src/services/taskContext.ts#L35)| Filters context dynamically for specific requests, preserving token budgets. |
+| **19** | **Architecture Decision Records**| Records | 🟢 Fully Implemented | [`src/services/records.ts:45`](file:///d:/projects/codeing_stuff/devworkspace/src/services/records.ts#L45)| Generates and lists sequential markdown ADRs in `.devworkspace/decisions/`. |
+| **20** | **Session Handoffs** | Records | 🟢 Fully Implemented | [`src/services/records.ts:90`](file:///d:/projects/codeing_stuff/devworkspace/src/services/records.ts#L90)| Saves compact milestone handoffs in `.devworkspace/sessions/`. |
+| **21** | **Multi-Agent Adapters** | Agents | 🟢 Fully Implemented | [`src/agents/shared.ts:40`](file:///d:/projects/codeing_stuff/devworkspace/src/agents/shared.ts#L40) | Non-destructive block merge into `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, Copilot. |
+| **22** | **Graphify Integration** | Integrations | 🔵 Optional / Delegated | [`src/integrations/adapters/graphify.ts:153`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/graphify.ts#L153) | Installs CLI & Claude skill; graph generation is delegated to Claude Code (`/graphify .`). |
+| **23** | **Agent Skills Integration** | Integrations | 🟢 Fully Implemented | [`src/integrations/adapters/agent-skills.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/agent-skills.ts) | Clones and links agent skills repository; manages project-level and user-level skills. |
+| **24** | **Ponytail Process Monitor** | Integrations | 🟢 Fully Implemented | [`src/integrations/adapters/ponytail.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/ponytail.ts) | Verifies installation of Ponytail terminal background process manager. |
+| **25** | **OmniRoute Model Routing** | Integrations | 🔵 Optional / Delegated | [`src/integrations/adapters/omniroute.ts:4`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/omniroute.ts#L4) | Purely observed on PATH. Never executed, configured, or required by DevWorkspace. |
+| **26** | **Secrets Redaction** | Security | 🟢 Fully Implemented | [`src/security/redact.ts:48`](file:///d:/projects/codeing_stuff/devworkspace/src/security/redact.ts#L48)| Redacts AWS, GitHub, Slack, Google keys, JWTs, private keys from output and storage. |
+| **27** | **Symlink Escape Containment** | Security | 🟢 Fully Implemented | [`src/security/files.ts:53`](file:///d:/projects/codeing_stuff/devworkspace/src/security/files.ts#L53)| Resolves `realpath`, blocks symlink reading, and asserts containment inside root. |
+| **28** | **Sensitive File Quarantine** | Security | 🟢 Fully Implemented | [`src/security/files.ts:31`](file:///d:/projects/codeing_stuff/devworkspace/src/security/files.ts#L31)| Strictly refuses to read `.env`, `id_rsa`, `*.pem`, `service-account*.json`, `.npmrc`. |
+| **29** | **Advisory Workspace Locking** | Reliability | 🟢 Fully Implemented | [`src/utils/lock.ts:24`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/lock.ts#L24) | Stale lock recovery, PID liveness verification, and 60-second timeouts. |
+| **30** | **Atomic File Persistence** | Reliability | 🟢 Fully Implemented | [`src/utils/fs.ts:39`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/fs.ts#L39) | Temp file write + `fsync` flush + Windows retry backoff rename loop. |
+| **31** | **Signal Trapping (SIGINT/TERM)**| Reliability | 🟢 Fully Implemented | [`src/utils/cleanup.ts:15`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/cleanup.ts#L15)| Synchronously unlinks locks, clears temporary files, and stops child processes. |
+| **32** | **Knowledge Export & Import** | Portability | 🟢 Fully Implemented | [`src/services/portability.ts:35`](file:///d:/projects/codeing_stuff/devworkspace/src/services/portability.ts#L35)| Bundles workspace state into SHA-256 verified JSON; validates schema on import. |
+| **33** | **Conversation Transcripts** | Scope Boundary | ⚪ Excluded by Design | [`src/services/records.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/records.ts) | Transcripts consume massive token budgets; only structured summaries are kept. |
+| **34** | **Remote Telemetry / Analytics**| Scope Boundary | ⚪ Excluded by Design | [`package.json: dependencies: {}`](file:///d:/projects/codeing_stuff/devworkspace/package.json) | Zero network egress; all computation and data storage remain 100% project-local. |
+
+---
+
+## 3. Discrepancy & Reality Analysis
+
+During our rigorous audit of the code in `src/`, four specific architectural subtleties and design decisions were identified where runtime reality differs from high-level assumptions:
+
+### 3.1. OmniRoute: Passive Observation Only
+- **Assumption**: Developers might assume that because `omniroute` is listed among integration adapters alongside Graphify and Ponytail, DevWorkspace invokes or configures OmniRoute for LLM traffic routing.
+- **Source Code Reality** ([`src/integrations/adapters/omniroute.ts:4`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/omniroute.ts#L4)): OmniRoute is 100% passive and optional. It is checked on the host PATH solely for environment diagnostics (`doctor`). It is never installed, never executed, and passes zero traffic through DevWorkspace.
+
+### 3.2. Graphify: Graph Generation Delegated to LLM
+- **Assumption**: A user might expect `devworkspace setup --integrations` or `devworkspace analyze` to produce visual codebase knowledge graphs.
+- **Source Code Reality** ([`src/integrations/adapters/graphify.ts:153`](file:///d:/projects/codeing_stuff/devworkspace/src/integrations/adapters/graphify.ts#L153)): DevWorkspace installs the Python `graphifyy` CLI tool and wires the Claude Code skill into `.claude/settings.json`. However, knowledge graph construction requires semantic code understanding performed by an LLM. Therefore, DevWorkspace intentionally refrains from building the graph itself and instructs the developer/agent to invoke `/graphify .` within Claude Code.
+
+### 3.3. Database Execution Quarantine (`testenv`)
+- **Assumption**: Running `devworkspace task run <id> integration` will automatically run the repository's integration test suite.
+- **Source Code Reality** ([`src/verification/safety.ts:28`](file:///d:/projects/codeing_stuff/devworkspace/src/verification/safety.ts#L28)): If the package depends on SQL/NoSQL databases or queues (`pg`, `mongodb`, `redis`, `prisma`, etc.), DevWorkspace actively refuses to execute the test script and exits with code `2`. To run service-touching tests, the engineer must explicitly declare an isolated test environment via `devworkspace testenv declare --yes`.
+
+### 3.4. Signal Trapping & Non-Blocking Windows Rename
+- **Assumption**: Standard Node.js `fs.renameSync` is sufficient for file updates.
+- **Source Code Reality** ([`src/utils/fs.ts:21`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/fs.ts#L21)): On Windows platforms, background antivirus scanners, Windows Search indexers, and IDE language servers temporarily hold read locks on newly touched files. Attempting immediate renames causes `EPERM` or `EBUSY` crashes. DevWorkspace implements `renameWithRetry`, a 20-iteration exponential backoff loop with micro-sleeps, guaranteeing atomic file replacement across all operating systems.
+

package/docs/architecture-report/11-glossary.md

@@ -0,0 +1,97 @@
+# Chapter 11: Glossary of Terms & Core Concepts
+
+> **Beginner-friendly definitions and real-world analogies for technical terms, domain concepts, and architectural patterns used throughout DevWorkspace.**
+
+---
+
+### Architecture Decision Record (ADR)
+A short, standardized markdown document that captures an important architectural decision, the context in which it was made, and its anticipated consequences.  
+*In DevWorkspace*: Stored as sequential files in `.devworkspace/decisions/` (e.g. `0001-use-postgresql.md`). See [Chapter 6: Command Reference](./06-command-reference.md#310-devworkspace-decision).
+
+---
+
+### Atomic Temporary Write & Rename
+A filesystem persistence technique where data is first written to a temporary staging file (`<file>.<pid>.<random>.tmp`), flushed to physical storage using `fsync`, validated, and then atomically swapped into the destination path using the operating system's `rename` system call.  
+*Why it matters*: Prevents half-written or corrupted JSON files if the system crashes or loses power during a write. See [Chapter 7: Data Flow & Subsystem Integrations](./07-data-flow-and-integrations.md#3-atomic-persistence--concurrency-guarantees).
+
+---
+
+### Authority Rank
+A numerical hierarchy assigned to facts recorded in DevWorkspace to prevent AI hallucinations or automated tools from overwriting verified human knowledge:
+- **Rank 4 (User)**: Explicitly asserted by a human developer. Can overwrite any existing fact.
+- **Rank 3 (File / Git)**: Deterministically parsed from source manifests or git history. Can overwrite AI facts.
+- **Rank 2 (AI)**: Inferred by an AI model. **Cannot** overwrite human or file-derived facts.  
+See [Chapter 4: Execution Flows](./04-execution-flows.md#2-workflow-b-project-analysis--knowledge-derivation).
+
+---
+
+### Completion Gate
+A strict automated verification checkpoint enforced before any engineering task can transition to the `COMPLETED` state. It verifies that required testing contract checks have passed, tests have not regressed, file mutation rules were respected, and three human attestations have been signed.  
+*Real-world analogy*: The final checklist a pilot and co-pilot must sign before taking off. See [Chapter 4: Execution Flows](./04-execution-flows.md#4-task-lifecycle--completion-gate-state-machine).
+
+---
+
+### Monorepo / Multi-Package Workspace
+A repository structure containing multiple distinct applications or packages inside subdirectories (e.g., `packages/client`, `packages/server`, `apps/web`), often coordinated by pnpm, Yarn, npm workspaces, or Cargo.  
+*In DevWorkspace*: Detected during discovery; tasks, testing contracts, and testenv declarations can target specific sub-packages using `--package <dir>`.
+
+---
+
+### Non-Destructive Managed Block Injection
+A technique where DevWorkspace injects or updates tool instructions into agent configuration files (such as `CLAUDE.md`, `AGENTS.md`, or `.cursorrules`) between strict HTML boundary markers (`<!-- DEVWORKSPACE:START -->` and `<!-- DEVWORKSPACE:END -->`).  
+*Why it matters*: Existing human rules, instructions, or team guidelines written outside the markers are preserved 100% without modification. See [Chapter 7: Data Flow & Subsystem Integrations](./07-data-flow-and-integrations.md#41-non-destructive-instruction-block-injection).
+
+---
+
+### OIDC Trusted Publishing
+A modern security standard for publishing packages to npm directly from GitHub Actions without storing long-lived, reusable API tokens (`NPM_TOKEN`). It uses OpenID Connect (OIDC) to exchange short-lived, cryptographically signed tokens between GitHub and npm.  
+*In DevWorkspace*: Configured in `.github/workflows/release.yml` with `id-token: write`. See [Chapter 8: Build, Test & Deployment Architecture](./08-build-test-deployment.md#52-automated-release-workflow-githubworkflowsreleaseyml).
+
+---
+
+### Progressive Context
+An intelligent retrieval pattern that provides an AI coding agent with only the specific subset of project knowledge, testing commands, and package configurations required for the current task, rather than dumping the entire repository documentation into the prompt.  
+*Why it matters*: Prevents context window saturation, lowers LLM costs, and minimizes hallucination risk. Triggered via `devworkspace context --for "<request>"`. See [Chapter 7: Data Flow & Subsystem Integrations](./07-data-flow-and-integrations.md#42-progressive-context-delivery).
+
+---
+
+### Sensitive File Quarantine
+A defensive security boundary where DevWorkspace explicitly detects the presence of sensitive files (`.env`, `*.pem`, `id_rsa`, `service-account*.json`, `.npmrc`) for framework detection, but strictly refuses to open or stream their text contents under any circumstances.  
+*Why it matters*: Guarantees that production secrets and credentials never leak into AI prompts, logs, or exported bundles. See [Chapter 9: Security, Privacy & System Reliability](./09-security-and-reliability.md#31-sensitive-file-quarantine).
+
+---
+
+### Stale Fact & Fact Invalidation
+A condition where a recorded piece of project knowledge (such as "Database is PostgreSQL v15") was evidenced by specific source files, but those files were subsequently modified, renamed, or deleted in the repository.  
+*In DevWorkspace*: When `devworkspace refresh` runs, content hashes and modification timestamps are re-checked; affected facts are automatically flagged as `STALE`. See [Chapter 4: Execution Flows](./04-execution-flows.md#5-workflow-d-knowledge-staleness-invalidation).
+
+---
+
+### Symlink Escape & Path Containment
+A security vulnerability where a symbolic link inside a repository points to an arbitrary file or folder outside the project root (e.g. `/etc/passwd` or `C:\Users\username\.ssh`).  
+*In DevWorkspace*: All file reads pass through `safeReadText()`, which resolves the physical canonical path (`realpath`) and asserts that it remains strictly inside the workspace root. See [Chapter 9: Security, Privacy & System Reliability](./09-security-and-reliability.md#33-symlink-escape-prevention).
+
+---
+
+### Test Environment Quarantine (`testenv`)
+A safeguard that blocks automated execution of tests that touch external infrastructure (PostgreSQL, Redis, MongoDB, message queues) unless a developer explicitly registers a local, disposable test target using `devworkspace testenv declare --yes`.  
+*Why it matters*: Prevents automated agents from accidentally running integration tests against a developer's real local database or production instance. Stored in git-ignored `.devworkspace/local/testenv.json`. See [Chapter 9: Security, Privacy & System Reliability](./09-security-and-reliability.md#42-database--service-quarantine-testenv).
+
+---
+
+### Testing Contract
+A structured JSON map (`.devworkspace/context/testing-contract.json`) that establishes an explicit agreement between the project and coding agents on which commands correspond to standard verification phases: `typecheck`, `lint`, `unit`, `integration`, `e2e`, `security`, and `build`.  
+*Why it matters*: AI agents do not have to guess what command to run; they run the exact verified contract command. See [Chapter 4: Execution Flows](./04-execution-flows.md#2-workflow-b-project-analysis--knowledge-derivation).
+
+---
+
+### Workspace Advisory Lock (`withLock`)
+A file-based concurrency mechanism (`.devworkspace/local/workspace.lock`) that ensures only one DevWorkspace mutating command runs at a time in a given workspace. It stores the owning Process ID (PID) and timestamp, and automatically detects and clears abandoned locks if a process dies unexpectedly.  
+*In DevWorkspace*: Implemented in `src/utils/lock.ts`. See [Chapter 7: Data Flow & Subsystem Integrations](./07-data-flow-and-integrations.md#32-advisory-workspace-locking).
+
+---
+
+### Zero Runtime Dependencies Architecture
+An engineering design choice where an application ships with `dependencies: {}` in `package.json`, relying entirely on Node.js standard built-in modules (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:util`, `node:os`).  
+*Why it matters*: Eliminates supply-chain attack vectors, ensures zero transitive dependency vulnerabilities, provides instantaneous downloads, and guarantees identical execution across Node.js versions. See [Chapter 3: Tools & Technologies](./03-tools-and-technologies.md#2-runtime-technologies-node-built-ins).
+

package/docs/architecture-report/README.md

@@ -0,0 +1,103 @@
+# DevWorkspace Architecture & Visual Documentation Report
+
+> **Comprehensive, evidence-based architectural documentation for DevWorkspace v0.3.1**  
+> *Prepared for developers, architects, and engineering teams.*
+
+---
+
+## Welcome to the DevWorkspace Architecture Report
+
+**DevWorkspace** is a project-local AI engineering workspace CLI. It provides deterministic repository discovery, persistent portable project knowledge, structured engineering task tracking with mandatory verification gates, and multi-agent instruction integration—all with **zero runtime dependencies**.
+
+This report is a complete, beginner-friendly, and rigorously verified investigation of the DevWorkspace codebase. Every architectural claim, data flow, and mechanism described in this documentation is backed by evidence from the TypeScript source code in `src/`.
+
+---
+
+## Report Navigation
+
+This report is organized into 11 modular chapters and a dedicated visual diagrams catalog:
+
+| # | Chapter Document | Focus Area |
+|---|---|---|
+| **01** | [Executive Summary](./01-executive-summary.md) | High-level overview, core problem statement, 5 pillars, and real-world analogy |
+| **02** | [System Architecture](./02-system-architecture.md) | Layered subsystem model, component relationships, and communication boundaries |
+| **03** | [Tools & Technologies](./03-tools-and-technologies.md) | Exhaustive inventory of Node.js built-ins, dev tools, and external AI agent integrations |
+| **04** | [Execution Flows](./04-execution-flows.md) | Step-by-step trace of CLI startup, project analysis, skills, and task lifecycles |
+| **05** | [Codebase Map](./05-codebase-map.md) | Complete directory tree, module responsibility matrix, and source catalog |
+| **06** | [Command Reference](./06-command-reference.md) | Detailed reference for all 16 CLI commands with flags, side effects, and examples |
+| **07** | [Data Flow & Integrations](./07-data-flow-and-integrations.md) | How data enters, transforms, persists, and exports across `.devworkspace/` |
+| **08** | [Build, Test & Deployment](./08-build-test-deployment.md) | TypeScript compilation, Vitest test suites, release gates, and GitHub Actions CI/CD |
+| **09** | [Security & Reliability](./09-security-and-reliability.md) | Secrets redaction, symlink escape defenses, atomic writes, and database safeguards |
+| **10** | [Feature Implementation Status](./10-feature-status.md) | Verified matrix of fully implemented, partial, optional, and unverified features |
+| **11** | [Glossary of Terms](./11-glossary.md) | Beginner-friendly explanations of domain terms (Testing Contract, Gate, Authority Rank) |
+| **—** | [Visual Architecture Diagrams](./diagrams.md) | Standalone catalog containing all 8 Mermaid architecture and sequence diagrams |
+
+---
+
+## High-Level System Architecture at a Glance
+
+The following diagram illustrates how a developer, their coding agents, and the DevWorkspace CLI interact with a repository and its underlying files:
+
+```mermaid
+flowchart TD
+    subgraph UsersAndAgents["Users & Coding Agents"]
+        Dev["Developer / Engineer"]
+        Agent["AI Coding Agent\n(Claude Code / Cursor / Codex / Copilot / Antigravity)"]
+    end
+
+    subgraph DevWorkspaceCLI["DevWorkspace CLI (dist/cli/main.js)"]
+        Parser["Argument Parser & Router\n(node:util parseArgs)"]
+        Services["Service Orchestration Layer\n(init, analyze, status, doctor, task, agent)"]
+        
+        subgraph Subsystems["Core Engine Subsystems"]
+            Discovery["Discovery Engine\n(scan, detect, commands, entrypoints)"]
+            Knowledge["Knowledge & Facts Engine\n(authority ranking, staleness detection)"]
+            Tasks["Task & Gate Engine\n(routing, evidence, completion gate)"]
+            AgentsEng["Multi-Agent Adapters\n(CLAUDE.md, AGENTS.md, .cursorrules)"]
+            Integrations["Integrations Manager\n(Graphify, Agent Skills, Ponytail)"]
+            Security["Security & Redaction\n(safeReadText, symlink guard, redact)"]
+        end
+    end
+
+    subgraph LocalStorage["Project Repository Filesystem"]
+        RepoSource["Application Source Code & Manifests\n(package.json, src/, tests/, .env [never read])"]
+        
+        subgraph DevWsDir[".devworkspace/ (Workspace State)"]
+            ProjectConfig["project.json"]
+            FactsFile["context/facts.json & commands.json"]
+            TasksFiles["tasks/active/*.json & tasks/completed/*.json"]
+            DecisionsFiles["decisions/*.md (ADR records)"]
+            AnalysisFiles["analysis/discovery.json & onboarding-prompt.md"]
+            LocalDir["local/ (git-ignored machine state)"]
+        end
+
+        AgentInstructions["Agent Rule Files\n(AGENTS.md, CLAUDE.md, .cursor/rules/)"]
+    end
+
+    Dev -->|"Runs commands (init, status, task)"| Parser
+    Agent -->|"Invokes CLI or reads instructions"| Parser
+    Agent -->|"Reads progressive context"| AgentInstructions
+    AgentInstructions -.->|"Managed block links to"| FactsFile
+    
+    Parser --> Services
+    Services --> Subsystems
+    
+    Discovery -->|"safeReadText (bounded, no secrets)"| RepoSource
+    Discovery -->|"Generates deterministic facts"| FactsFile
+    Discovery -->|"Generates prompt"| AnalysisFiles
+    
+    Tasks -->|"Persists tasks & checks evidence"| TasksFiles
+    Knowledge -->|"Maintains durable project knowledge"| FactsFile
+    AgentsEng -->|"Non-destructive section merge"| AgentInstructions
+    
+    Security -->|"Enforces path boundary & secret redaction"| DevWsDir
+```
+
+---
+
+## How to Read This Report
+
+- **If you are new to DevWorkspace**: Start with [01-executive-summary.md](./01-executive-summary.md) and [04-execution-flows.md](./04-execution-flows.md) for a conceptual walkthrough of what happens when you run `devworkspace init` and `devworkspace analyze`.
+- **If you are integrating AI agents**: Read [02-system-architecture.md](./02-system-architecture.md) and [06-command-reference.md](./06-command-reference.md) to understand how `AGENTS.md`, `CLAUDE.md`, and task verification gates guide autonomous coding agents.
+- **If you are auditing security or reliability**: Jump directly to [09-security-and-reliability.md](./09-security-and-reliability.md) and [08-build-test-deployment.md](./08-build-test-deployment.md) for path boundary enforcement, symlink defense, credential redaction, and atomic file guarantees.
+