devworkspace 0.3.1 → 0.3.2

package/docs/architecture-report/07-data-flow-and-integrations.md

@@ -0,0 +1,268 @@
+# Chapter 7: Data Flow & Subsystem Integrations
+
+> **Comprehensive architectural analysis of how data enters, transforms, persists, and exports across DevWorkspace, detailing file schemas, atomic guarantees, and external agent boundaries.**
+
+---
+
+## 1. End-to-End Data Lifecycle
+
+DevWorkspace functions as a structured data pipeline that turns messy repository files, terminal commands, and AI interactions into durable, verifiable project state:
+
+```mermaid
+flowchart TD
+    subgraph Ingestion["1. Ingestion & Discovery"]
+        Manifests["Manifests & Configs\n(package.json, tsconfig.json, Cargo.toml)"]
+        GitMeta["Git Metadata\n(HEAD, branch, commit SHA, dirty state)"]
+        CLIInputs["CLI Arguments & Flags\n(parsed via node:util parseArgs)"]
+    end
+
+    subgraph Processing["2. Transformation & Validation"]
+        Scanner["Scanner & Detector\n(bounded depth, ignores node_modules)"]
+        Schemas["Schema Validation\n(Zod-like custom TS type guards)"]
+        AuthRank["Authority Engine\n(User Rank 4 > File Rank 3 > AI Rank 2)"]
+    end
+
+    subgraph AtomicStore["3. Persistence & Concurrency"]
+        TempWrite["Exclusive Temp Write\n(.tmp.<pid>.<random> with sync)"]
+        Rename["Atomic Rename with Retry\n(Windows EBUSY/EPERM backoff)"]
+        LockFile[".devworkspace/local/workspace.lock\n(PID + timestamp advisory lock)"]
+    end
+
+    subgraph StorageLayout["4. Storage Layout (.devworkspace/)"]
+        ProjJson["project.json"]
+        FactsJson["context/facts.json & testing-contract.json"]
+        TasksDir["tasks/active/*.json & tasks/completed/*.json"]
+        ADRDir["decisions/0001-*.md"]
+        SessDir["sessions/*.json"]
+        AnalysisDir["analysis/discovery.json & onboarding-prompt.md"]
+        LocalDir["local/ (git-ignored: testenv.json, locks)"]
+    end
+
+    subgraph Egress["5. Egress & Consumption"]
+        HumanOut["Terminal Styled Text / ANSI"]
+        JSONOut["Deterministic JSON (--json)"]
+        AgentRules["Managed Blocks in Instruction Files\n(CLAUDE.md, AGENTS.md, .cursorrules)"]
+        ExportBundle["Portable Knowledge Bundle\n(devworkspace-export-<date>.json)"]
+    end
+
+    Manifests --> Scanner
+    GitMeta --> Scanner
+    CLIInputs --> Schemas
+    Scanner --> Schemas
+    Schemas --> AuthRank
+    AuthRank --> LockFile
+    LockFile --> TempWrite
+    TempWrite --> Rename
+    Rename --> StorageLayout
+    StorageLayout --> HumanOut
+    StorageLayout --> JSONOut
+    StorageLayout --> AgentRules
+    StorageLayout --> ExportBundle
+```
+
+---
+
+## 2. The `.devworkspace/` Directory Schema
+
+All workspace state lives in a dedicated `.devworkspace/` directory located at the project root. This separation keeps the user's source code pristine while ensuring AI context is version-controlled and team-portable.
+
+### 2.1. Complete Directory Layout
+```text
+.devworkspace/
+├── .gitignore                   # Ignores local/ and migration backups
+├── project.json                 # Core repository identifier and schema version
+├── analysis/                    # Generated by "devworkspace analyze"
+│   ├── discovery.json           # Raw machine-readable detection output
+│   └── onboarding-prompt.md     # Optimized initialization prompt for Claude Code
+├── context/                     # Project knowledge and execution contracts
+│   ├── facts.json               # Key-value facts with evidence and confidence
+│   ├── testing-contract.json    # Discovered test, lint, and build commands
+│   ├── commands.json            # Discovered development and operational scripts
+│   └── *.md                     # Optional domain-specific architectural markdown
+├── tasks/                       # Task management subsystem
+│   ├── active/
+│   │   └── T-20261102-a1b2.json # Currently active engineering tasks
+│   └── completed/
+│       └── T-20261101-9f8e.json # Completed tasks with verification records
+├── decisions/                   # Architecture Decision Records (ADRs)
+│   ├── 0001-use-postgresql.md
+│   └── 0002-async-event-bus.md
+├── sessions/                    # Engineering session summaries (token-efficient)
+│   └── S-20261102-143022.json
+└── local/                       # MACHINE-LOCAL ONLY (Never committed to Git)
+    ├── testenv.json             # Declared local test environments
+    └── workspace.lock           # Concurrency lock file (pid, timestamp)
+```
+
+---
+
+### 2.2. Core JSON File Schemas
+
+#### 1. `project.json`
+Contains workspace identity and version tracking:
+```json
+{
+  "schemaVersion": 1,
+  "id": "c1f7b2e4-9843-4e8c-8712-42173160a221",
+  "name": "devworkspace",
+  "root": "d:/projects/codeing_stuff/devworkspace",
+  "createdAt": "2026-11-02T04:30:00.000Z",
+  "updatedAt": "2026-11-02T04:35:12.000Z"
+}
+```
+
+#### 2. `context/facts.json`
+Structured facts tagged with authority rank, source files, and status:
+```json
+{
+  "schemaVersion": 1,
+  "facts": [
+    {
+      "key": "stack.runtime",
+      "value": "Node.js v20+ with ES Modules",
+      "source": "package.json",
+      "sourceType": "file",
+      "sources": ["package.json"],
+      "confidence": "HIGH",
+      "status": "VERIFIED",
+      "authority": 3,
+      "updatedAt": "2026-11-02T04:31:00.000Z"
+    }
+  ]
+}
+```
+
+#### 3. `tasks/active/T-*.json`
+Lifecycle tracking and completion gate evidence:
+```json
+{
+  "schemaVersion": 1,
+  "id": "T-20261102-ab12",
+  "title": "Add PostgreSQL connection pool health check",
+  "type": "FEATURE",
+  "status": "IN_PROGRESS",
+  "request": "Add database healthcheck endpoint and verify pool recovers after timeout",
+  "classification": {
+    "confidence": "high",
+    "readOnly": false,
+    "packages": ["backend"]
+  },
+  "plan": [
+    "Write integration test simulating pool starvation",
+    "Implement healthcheck query in pool manager",
+    "Run verification suite"
+  ],
+  "verification": [
+    {
+      "check": "typecheck",
+      "status": "PASSED",
+      "evidence": [{ "kind": "executed", "at": "2026-11-02T04:33:00.000Z", "exitCode": 0 }]
+    },
+    {
+      "check": "integration",
+      "status": "PENDING"
+    }
+  ],
+  "testRunCounts": {
+    "baseline": { "passed": 142, "failed": 0 },
+    "after": { "passed": 145, "failed": 0 }
+  },
+  "attestations": {
+    "userWorkIntact": true,
+    "knowledgeReviewed": false,
+    "finalStateInspected": false
+  }
+}
+```
+
+---
+
+## 3. Atomic Persistence & Concurrency Guarantees
+
+DevWorkspace is engineered to never leave corrupt, truncated, or half-written JSON files on disk, even during unexpected system power loss, process termination, or concurrent multi-agent executions.
+
+### 3.1. Atomic Temporary Write & Rename Pattern
+Implemented in [`src/utils/fs.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/fs.ts):
+
+1. **Unique Staging File**: Rather than modifying the target file in place, DevWorkspace creates a staging file in the same directory using the format:
+   ```text
+   <targetFile>.<pid>.<hexRandom4Bytes>.tmp
+   ```
+2. **Exclusive File Creation (`wx` mode)**: Opened with OS flag `wx` to ensure no race conditions with other processes trying to use the same temporary filename.
+3. **Forced Flush (`fsync`)**: Calls `await fh.sync()` before closing the file handle, forcing OS kernel buffers to commit data directly to physical storage.
+4. **Pre-Commit Validation**: If writing JSON, DevWorkspace executes a `JSON.parse()` pass on the written text before replacing the real file. If invalid, the write aborts and the staging file is unlinked.
+5. **Atomic Rename with Windows Backoff**: Calls `fs.rename()`. On POSIX systems, `rename` is atomic. On Windows, file indexers, antivirus scanners, or IDE file watchers can hold momentary locks; DevWorkspace implements an exponential backoff retry loop (up to 20 attempts) catching `EPERM`, `EBUSY`, and `EACCES`.
+
+### 3.2. Advisory Workspace Locking
+Implemented in [`src/utils/lock.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/lock.ts):
+
+- **Mechanism**: Every mutating command executes inside `withLock(workspaceDir, fn)`. It acquires an exclusive lock file at `.devworkspace/local/workspace.lock`.
+- **Payload**: The lock contains `{ pid: process.pid, at: Date.now() }`.
+- **Dead Process Detection**: If a lock exists, DevWorkspace verifies if `pid` is still alive via `process.kill(pid, 0)`. If the process has died or the lock is older than 60 seconds, it is safely broken.
+- **Signal Trapping**: Node process traps `SIGINT` and `SIGTERM` to synchronously unlink the lock file via [`src/utils/cleanup.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/cleanup.ts).
+
+---
+
+## 4. Multi-Agent Data Boundaries
+
+DevWorkspace integrates with AI coding agents (Claude Code, Cursor, Codex, Copilot, Antigravity) while maintaining strict architectural boundaries.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Agent as AI Coding Agent
+    participant File as CLAUDE.md / AGENTS.md / .cursorrules
+    participant DW as DevWorkspace CLI
+    participant State as .devworkspace/ State
+
+    Note over DW,File: Non-Destructive Ingestion
+    DW->>File: Reads existing agent file
+    DW->>DW: Locates <!-- DEVWORKSPACE:START --> marker
+    DW->>File: Injects/Updates managed instruction block
+    Note over File: Preserves 100% of existing user rules
+
+    Note over Agent,DW: Progressive Context Loop
+    Agent->>DW: devworkspace context --for "Fix checkout tax error"
+    DW->>State: Queries facts, contract, and active tasks
+    DW->>DW: Classifies request & filters relevant packages
+    DW-->>Agent: Returns high-signal context (omits irrelevant facts)
+    
+    Note over Agent,DW: Verified Completion Loop
+    Agent->>DW: devworkspace task status T-01 COMPLETED
+    DW->>State: evaluateGate() checks contract, tests, attestations
+    alt Gate Fails
+        DW-->>Agent: Exit 1 + Warning: "Required check 'typecheck' has not passed"
+    else Gate Passes
+        DW->>State: Moves task from tasks/active/ to tasks/completed/
+        DW-->>Agent: Exit 0: Task COMPLETED
+    end
+```
+
+### 4.1. Non-Destructive Instruction Block Injection
+Implemented in [`src/agents/shared.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/agents/shared.ts):
+- DevWorkspace injects instructions into agent root files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`) using strict HTML boundary markers:
+  ```markdown
+  <!-- DEVWORKSPACE:START -->
+  <!-- Managed by devworkspace. Do not edit this block manually. -->
+  ... concise instructions, testing contracts, and commands ...
+  <!-- DEVWORKSPACE:END -->
+  ```
+- Any text written by developers outside this block is strictly preserved.
+- When `devworkspace reset --include-agent-files` is run, only the managed block is stripped; user comments and custom rules remain intact.
+
+### 4.2. Progressive Context Delivery
+Instead of overloading LLM context windows with thousands of lines of documentation, `devworkspace context --for "<request>"` performs dynamic filtering:
+1. Matches `<request>` keywords against known monorepo packages, stack technologies, and testing contract commands.
+2. Injects mandatory architectural invariants (e.g. "Do not mutate production DBs").
+3. Omits irrelevant microservice configs and secondary test suites.
+4. Returns token-efficient, high-density facts tagged with their origin.
+
+### 4.3. External Developer Tool Integrations
+
+| Integration | Primary Purpose | Execution Model | Data Exchanged |
+|---|---|---|---|
+| **Graphify** | Visual codebase dependency graphs & clustering | Managed external CLI (`graphify .` via Claude Code) | Generates `graphify-out/` and architecture visualizations |
+| **Agent Skills** | Extends coding agents with specialized command sets | Local skill scripts (`.agent-skills/` or user path) | Skill manifests and invocation protocols |
+| **Ponytail** | Terminal-based background process monitor | Standalone CLI on PATH (`ponytail`) | Process statuses, ports, log output |
+| **OmniRoute** | Observed network router / proxy | Passive detection (observed on PATH only) | None (zero execution, read-only observation) |
+

package/docs/architecture-report/08-build-test-deployment.md

@@ -0,0 +1,185 @@
+# Chapter 8: Build, Test & Deployment Architecture
+
+> **Complete technical breakdown of the TypeScript build pipeline, Vitest test suites, coverage gates, release verification scripts, and GitHub Actions CI/CD workflows.**
+
+---
+
+## 1. Diagram 6: Build, Test & Deployment Pipeline
+
+The following diagram illustrates the complete validation pipeline that code traverses—from developer source TypeScript to published npm registry artifact:
+
+```mermaid
+flowchart TD
+    subgraph Developer["Local Development"]
+        Source["TypeScript Source (src/)"]
+        Tests["Test Suites (tests/unit, integration, e2e)"]
+        Clean["scripts/clean.mjs\n(Purges dist/)"]
+    end
+
+    subgraph BuildPipeline["Compilation & Packaging"]
+        TSC["TypeScript Compiler (tsc -p tsconfig.build.json)\nES2022, NodeNext, Declarations (.d.ts), Maps (.js.map)"]
+        Pack["npm pack --ignore-scripts\n(Generates devworkspace-<version>.tgz)"]
+    end
+
+    subgraph TestGates["Quality & Verification Gates"]
+        Typecheck["npm run typecheck\n(Strict TS validation)"]
+        ESLint["npm run lint\n(ESLint flat config)"]
+        Vitest["npm run coverage\n(778 tests across Unit, Integration, E2E)"]
+        Audit["npm run audit:security\n(Production dependency audit)"]
+        ReleaseCheck["scripts/release-check.mjs\n(Hygiene, Semver, Docs, Tags, Clean Git)"]
+        Smoke["scripts/smoke.mjs\n(Tarball inspection & isolated CLI run)"]
+    end
+
+    subgraph CICD["GitHub Actions Automation"]
+        CIWorkflow[".github/workflows/ci.yml\n(Ubuntu, Windows, macOS on Node 20 & 22)"]
+        ReleaseWorkflow[".github/workflows/release.yml\n(Manual dispatch, OIDC Trusted Publishing)"]
+    end
+
+    subgraph Registry["Distribution"]
+        NPMRegistry["npm Registry (Public)\nhttps://www.npmjs.com/package/devworkspace"]
+    end
+
+    Source --> Clean
+    Clean --> TSC
+    TSC --> Pack
+    Source --> Typecheck
+    Source --> ESLint
+    Tests --> Vitest
+    Pack --> Smoke
+    Typecheck & ESLint & Vitest & Audit & Smoke --> ReleaseCheck
+
+    ReleaseCheck --> CIWorkflow
+    CIWorkflow --> ReleaseWorkflow
+    ReleaseWorkflow -->|"npm publish --access public (OIDC Token)"| NPMRegistry
+```
+
+---
+
+## 2. TypeScript Compilation Architecture
+
+DevWorkspace uses modern, native Node.js ES Modules (ESM) with TypeScript strict mode enabled throughout.
+
+### 2.1. Dual Configuration Model
+The repository maintains two TypeScript configuration files:
+
+1. **`tsconfig.json`**: Root configuration for local development, IDE language servers, and test running. Includes `tests/` and `scripts/`.
+2. **`tsconfig.build.json`**: Production compilation configuration used strictly for generating the distribution payload. Excludes `tests/`, `scripts/`, and mocks to ensure zero non-production code leaks into `dist/`.
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["tests/**/*", "scripts/**/*", "**/*.test.ts"]
+}
+```
+
+### 2.2. Key Compiler Settings
+- **`target: "ES2022"`**: Targets modern ECMAScript features (native private fields, `Object.hasOwn`, top-level await).
+- **`module: "NodeNext"` & `moduleResolution: "NodeNext"`**: Strictly enforces modern Node.js module resolution, requiring explicit `.js` extensions in all TypeScript import paths.
+- **`strict: true`**: Enforces strict null checks, no implicit any, and strict function types.
+- **`declaration: true`**: Emits complete TypeScript type declarations (`.d.ts`), enabling consumers to import DevWorkspace programmatically with full autocomplete and type safety.
+
+---
+
+## 3. Testing Strategy & Framework (Vitest)
+
+DevWorkspace uses **Vitest** as its unified test runner across all testing tiers.
+
+### 3.1. Test Suites Structure
+The test suite consists of **31 test files** comprising **778 passing tests**, categorized into three distinct layers:
+
+| Tier | Directory | Test Files | Focus & Scope |
+|---|---|:---:|---|
+| **Unit** | `tests/unit/` | 19 | Pure unit tests targeting isolated modules (argument parser, schema validators, path sanitization, redact engine, authority rankings). Runs in milliseconds without disk I/O. |
+| **Integration** | `tests/integration/` | 8 | Subsystem coordination tests. Tests atomic filesystem writes, locks, discovery scanning, task state transitions, and integration adapters using temporary directories. |
+| **End-to-End** | `tests/e2e/` | 4 | Full CLI end-to-end execution. Spawns real CLI commands via child processes against temporary mock repositories, verifying stdout, stderr, and exit codes. |
+
+### 3.2. Coverage Enforcement
+Test coverage is enforced via `@vitest/coverage-v8`. The build pipeline executes `npm run coverage`, which mandates strict statement, branch, function, and line coverage minimums across all modules in `src/`.
+
+---
+
+## 4. Release Verification & Quality Gates
+
+Publishing a release of DevWorkspace requires passing a multi-layer verification gate executed by `scripts/release-check.mjs`.
+
+### 4.1. `release-check.mjs` Gate Checks
+The script executes 11 sequential validation gates and aborts with exit code `1` upon the first failure:
+
+1. **Git State Verification**: Asserts that `git status --porcelain` is 100% clean (no uncommitted modifications).
+2. **Tag Alignment**: Verifies that the current `HEAD` commit is tagged with `v${version}` matching `package.json`.
+3. **Semver Compliance**: Asserts that `package.json` version conforms strictly to Semantic Versioning (`X.Y.Z`).
+4. **Changelog Integrity**: Confirms that `CHANGELOG.md` contains a dedicated entry header for the release version (`## [X.Y.Z] - YYYY-MM-DD`).
+5. **License Ownership**: Asserts `package.json` license is valid (e.g. `MIT`) and `LICENSE` exists.
+6. **URL Sanity**: Ensures `repository`, `bugs`, and `homepage` URLs in `package.json` do not contain placeholder strings (e.g. `OWNER`).
+7. **Documentation Presence**: Verifies existence of all 10 core documentation files in `docs/` (`getting-started.md`, `architecture.md`, `security.md`, etc.).
+8. **Production Hygiene Scan**: Recursively scans all `.ts` files in `src/` to ensure no active `TODO`, `FIXME`, `XXX`, `HACK`, or unapproved `stub`/`placeholder` markers exist.
+9. **Static Checks**: Executes `npm run typecheck` and `npm run lint`.
+10. **Test Coverage**: Executes `npm run coverage` to ensure all 778 tests pass with coverage thresholds met.
+11. **Production Dependency Audit**: Executes `npm run audit:security` to confirm zero vulnerabilities exist in production dependencies.
+
+---
+
+### 4.2. `smoke.mjs`: Fresh-Install Verification
+
+Before any package is released, `scripts/smoke.mjs` conducts a black-box verification of the published package:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Runner as Smoke Runner (scripts/smoke.mjs)
+    participant NPM as npm pack
+    participant FS as Temporary Filesystem
+    participant CLI as Published CLI (node dist/cli/main.js)
+
+    Runner->>NPM: npm pack --ignore-scripts
+    NPM-->>Runner: Creates devworkspace-0.3.1.tgz
+    Runner->>FS: Reads tarball contents (tar -tzf)
+    Note over Runner,FS: Verifies LICENSE, README.md, dist/<br/>Rejects any tests/, src/, or scripts/ leaks
+    Runner->>FS: Creates fresh temp project folder
+    Runner->>FS: Extracts tarball into temp project
+    Runner->>CLI: Executes "devworkspace --version"
+    CLI-->>Runner: Returns "0.3.1" (Exit 0)
+    Runner->>CLI: Executes "devworkspace init --dry-run"
+    CLI-->>Runner: Returns initialization plan (Exit 0)
+    Runner->>FS: Purges temporary directory
+    Note over Runner: Smoke test PASSED
+```
+
+- **Tarball Content Whitelist**: Ensures only `package.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, and compiled `dist/` files are present in the package. Source `.ts` files, test fixtures, scripts, and temporary files are strictly prevented from publishing.
+- **Real Execution**: Verifies that the packaged CLI entrypoint starts up without missing dependencies or broken import paths.
+
+---
+
+## 5. CI/CD & Deployment Workflows
+
+DevWorkspace uses GitHub Actions for continuous integration and automated releases.
+
+### 5.1. Continuous Integration (`.github/workflows/ci.yml`)
+- **Triggers**: Every push to `main` and all Pull Requests.
+- **Cross-Platform Matrix**: Runs across **Ubuntu Latest**, **Windows Latest**, and **macOS Latest** on Node.js **20** and **22**.
+- **Steps**:
+  - `npm ci`
+  - `npm run typecheck`
+  - `npm run lint`
+  - `npm run build`
+  - `npm run test:unit`
+  - `npm run test:integration`
+  - `npm run test:e2e`
+  - `npm run smoke`
+- **Coverage & Security Job**: Runs on Ubuntu to verify coverage thresholds and execute `npm audit`.
+
+### 5.2. Automated Release Workflow (`.github/workflows/release.yml`)
+DevWorkspace publishes packages using modern **GitHub Actions OIDC Trusted Publishing**:
+- **Manual Trigger (`workflow_dispatch`)**: Publishing requires an explicit maintainer trigger with a confirmation input matching the exact version string from `package.json`.
+- **Dry-Run Mode**: Defaults to `dry_run: true` so maintainers can preview all release checks and tarball contents in CI before pushing to the public registry.
+- **OIDC Token Permission (`id-token: write`)**: Generates short-lived, cryptographic OIDC tokens exchanged with npm. No permanent `NPM_TOKEN` secret is stored in repository settings.
+- **Environment Protection (`environment: publish`)**: Allows repository administrators to attach required reviewers and deployment rules to the `publish` environment.
+

package/docs/architecture-report/09-security-and-reliability.md

@@ -0,0 +1,165 @@
+# Chapter 9: Security, Privacy & System Reliability
+
+> **Exhaustive analysis of DevWorkspace's defense-in-depth security model: credential redaction, symlink escape containment, destructive command blocking, and crash-resilient concurrency.**
+
+---
+
+## 1. Security Architecture & Threat Model
+
+DevWorkspace operates on a **zero-trust local model**. It assumes that:
+1. Repositories may contain third-party open-source code or LLM-generated code that could introduce malicious symlinks, path traversals, or dangerous shell commands.
+2. Coding agents might attempt to read secrets (`.env`, private keys) or run destructive database migrations without human awareness.
+3. Multiple terminal sessions or agents could execute commands simultaneously, threatening workspace state corruption.
+
+To neutralize these threats, DevWorkspace enforces six non-bypassable layers of defense:
+
+```mermaid
+flowchart TD
+    subgraph InputDefense["Layer 1: Input & Filesystem Containment"]
+        NoSymlinks["Symlink Escape Guard\n(assertNoSymlinkEscape, realpath check)"]
+        PathBound["Path Boundary Assertion\n(isInside root check)"]
+        SensitiveBlock["Sensitive File Blocklist\n(.env, *.pem, id_rsa, .npmrc never read)"]
+    end
+
+    subgraph MemoryDefense["Layer 2: Resource & Memory Bounding"]
+        BoundedRead["Bounded File Streaming\n(maxBytes 512KB limit, MAX_JSON_BYTES 5MB)"]
+        NoInteractiveHangs["Zero Interactive Stdin\n(never hangs waiting for user prompt)"]
+    end
+
+    subgraph DataSanitization["Layer 3: Privacy & Secrets Redaction"]
+        RedactEngine["Multi-Pattern Redaction\n(AWS keys, Slack/GitHub tokens, JWTs, private keys)"]
+        SafeLogging["Deterministic Redacted Output\n(logs, error traces, and export bundles)"]
+    end
+
+    subgraph CommandSafetyEngine["Layer 4: Command Safety & Execution Sandbox"]
+        DestructiveFilter["Destructive Keyword Filter\n(blocks drop, truncate, flushall, migrate, rm -rf)"]
+        TestEnvGuard["Test Environment Enforcer\n(blocks DB-touching tests unless declared in testenv)"]
+    end
+
+    subgraph ConcurrencyResilience["Layer 5: Concurrency & Atomic State"]
+        AdvisoryLock["Workspace Advisory Lock\n(PID + timeout check, stale lock recovery)"]
+        AtomicFlush["Atomic File Writes\n(.tmp with fsync flush + Windows rename retry backoff)"]
+    end
+
+    subgraph ProcessSafety["Layer 6: Signal Trapping & Cleanup"]
+        SignalHandler["Process Signal Trapping\n(SIGINT / SIGTERM synchronously unlinks locks & temp files)"]
+    end
+
+    InputDefense --> MemoryDefense
+    MemoryDefense --> DataSanitization
+    DataSanitization --> CommandSafetyEngine
+    CommandSafetyEngine --> ConcurrencyResilience
+    ConcurrencyResilience --> ProcessSafety
+```
+
+---
+
+## 2. Secrets Redaction & Privacy Engine
+
+Implemented in [`src/security/redact.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/security/redact.ts):
+
+### 2.1. Monitored Credential Patterns
+DevWorkspace maintains an active regex registry matching industry credential signatures:
+
+| Credential Type | Regex Pattern / Signature | Redacted Token Output |
+|---|---|---|
+| **Private Keys** | `-----BEGIN (RSA\|EC\|DSA\|OPENSSH\|PGP)? PRIVATE KEY-----` | `[REDACTED:private-key]` |
+| **AWS Access Keys** | `\b(?:AKIA\|ASIA)[0-9A-Z]{16}\b` | `[REDACTED:aws-access-key]` |
+| **GitHub Tokens** | `\b(?:ghp\|gho\|ghu\|ghs\|ghr)_[A-Za-z0-9]{30,}\b` | `[REDACTED:github-token]` |
+| **Slack Tokens** | `\bxox[abprs]-[A-Za-z0-9-]{10,}\b` | `[REDACTED:slack-token]` |
+| **API Keys** | `\bsk-[A-Za-z0-9_-]{20,}\b` | `[REDACTED:api-key]` |
+| **Google API Keys** | `\bAIza[0-9A-Za-z_-]{34,36}\b` | `[REDACTED:google-api-key]` |
+| **npm Tokens** | `\bnpm_[A-Za-z0-9]{36}\b` | `[REDACTED:npm-token]` |
+| **JSON Web Tokens (JWT)**| `\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b` | `[REDACTED:jwt]` |
+| **URL Credentials** | `\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@` | `[REDACTED:url-credentials]` |
+| **Generic Secrets** | `(?:password\|secret\|passwd\|auth_key)[\"']?\s*[:=]\s*...` | `[REDACTED:generic-secret]` |
+
+### 2.2. Universal Application
+Redaction is applied deterministically across:
+- All CLI stdout and stderr formatting passes ([`src/cli/render.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/render.ts)).
+- Loggers and error messages (`formatError` in [`src/errors/index.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/errors/index.ts)).
+- Stored knowledge facts and session handoffs.
+- Exported JSON bundles (`devworkspace export`).
+
+---
+
+## 3. Path Traversal & Symlink Escape Defenses
+
+Implemented in [`src/security/files.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/security/files.ts) and [`src/utils/paths.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/paths.ts):
+
+### 3.1. Sensitive File Quarantine
+DevWorkspace enforces a strict file blocklist. When scanning repository text, the CLI **refuses to open**:
+- Any `.env` file (e.g. `.env`, `.env.local`, `.env.production`), **except** non-sensitive template files (`.env.example`, `.env.sample`).
+- Certificates and private keys (`*.pem`, `*.key`, `*.p12`, `id_rsa`, `id_ed25519`).
+- Cloud credentials and state (`service-account*.json`, `credentials`, `terraform.tfstate`, `*.tfvars`).
+- Package manager auth files (`.npmrc`, `.pypirc`, `.netrc`, `.git-credentials`).
+
+> **Architectural Invariant**: DevWorkspace records only that a credential file *exists* for stack detection; it never reads the contents.
+
+### 3.2. Bounded Traversal & Memory Limits
+To prevent denial-of-service via memory exhaustion:
+- Text file reads are capped by `safeReadText(root, rel, maxBytes = 524288)` (512 KB).
+- JSON configuration files are capped by `MAX_JSON_BYTES = 5 * 1024 * 1024` (5 MB). Files exceeding these bounds are rejected.
+
+### 3.3. Symlink Escape Prevention
+- `isInside(absRoot, full)` verifies the resolved absolute path starts within the workspace root.
+- `st.isSymbolicLink()` check returns `null` immediately on symlinks during scanning.
+- `assertNoSymlinkEscape(root, full)` resolves physical `realpath` and asserts that symlinks do not escape outside the project directory.
+
+---
+
+## 4. Destructive Command Guards & Safe Execution
+
+Implemented in [`src/verification/safety.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/verification/safety.ts):
+
+When an AI agent or developer executes `devworkspace task run <id> <check>`, the command safety engine inspects the package manifest and command string before spawning a child process:
+
+```mermaid
+flowchart TD
+    RunCmd["devworkspace task run <id> <check>"] --> InspectCmd["Inspect Command String & Manifest"]
+    
+    InspectCmd --> CheckDestructive{"Contains Destructive Keywords?\n(drop, truncate, flushall, migrate, seed, rm -rf)"}
+    CheckDestructive -- Yes --> Block["BLOCKED: Exit Code 2\nRefuses to auto-execute hazardous script"]
+    
+    CheckDestructive -- No --> CheckService{"Uses External Services?\n(pg, prisma, redis, mongoose, bullmq)"}
+    CheckService -- No --> ExecuteSafe["SAFE: Execute Subprocess\n(typecheck, lint, unit tests)"]
+    
+    CheckService -- Yes --> CheckDeclared{"Declared in testenv.json?\n(devworkspace testenv declare --yes)"}
+    CheckDeclared -- No --> RequireEnv["NEEDS TEST ENVIRONMENT: Exit Code 2\nRequires explicit local isolation declaration"]
+    CheckDeclared -- Yes --> ExecuteSafe
+```
+
+### 4.1. Hazardous Keyword Filtering
+Any script containing `drop`, `truncate`, `flushall`, `flushdb`, `reset`, `seed`, `migrate`, `db:push`, `--force`, or `rm -rf` is classified as `BLOCKED`. DevWorkspace refuses to auto-execute it under any circumstance.
+
+### 4.2. Database & Service Quarantine (`testenv`)
+If a package manifest lists database drivers (`pg`, `mysql2`, `mongodb`, `ioredis`, `prisma`, `typeorm`, `sequelize`, `drizzle-orm`, `bullmq`), integration and e2e checks are marked `needs-test-environment`.
+They can only run if the engineer explicitly ran:
+```bash
+devworkspace testenv declare --package <pkg> --check integration --target "disposable docker stack" --yes
+```
+This declaration is stored strictly in `.devworkspace/local/testenv.json` and is never committed to Git.
+
+---
+
+## 5. System Reliability, Locking & Signal Trapping
+
+### 5.1. Concurrency Control (`withLock`)
+- Mutating commands acquire an exclusive lock file at `.devworkspace/local/workspace.lock`.
+- Prevents split-brain state when multiple coding agents run parallel tasks in the same project.
+- Implements stale lock recovery: if the process holding the lock dies (`pidAlive()` check fails) or the lock exceeds 60 seconds, it is automatically broken.
+
+### 5.2. Atomic File Commits
+All updates to `.devworkspace/` utilize the atomic write pattern:
+1. Data written to unique staging file (`.tmp.<pid>.<hex>`).
+2. Data flushed to disk via `fsync()`.
+3. Validated via `JSON.parse()`.
+4. Atomically renamed into place with exponential backoff on Windows (`EPERM`/`EBUSY` handling).
+
+### 5.3. Signal Traps & Cleanup Handlers
+[`src/utils/cleanup.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/utils/cleanup.ts) registers lifecycle hooks on `process.on('SIGINT')` and `process.on('SIGTERM')`:
+- Unlinks temporary staging files immediately.
+- Releases `.devworkspace/local/workspace.lock`.
+- Terminates spawned child test processes cleanly, returning exit code `130`.
+- Ensures zero dangling lock files or half-written temporary files remain on the developer's machine.
+