devworkspace 0.3.1 → 0.3.2

package/docs/architecture-report/06-command-reference.md

@@ -0,0 +1,446 @@
+# Chapter 6: CLI Command Reference
+
+> **Exhaustive reference for all DevWorkspace CLI commands: syntax, flags, execution mechanics, filesystem side effects, and read-only safety guarantees.**
+
+---
+
+## 1. Overview & Command Safety Taxonomy
+
+The DevWorkspace CLI provides a suite of 18 commands designed for developers and autonomous AI coding agents (Claude Code, Cursor, Codex, Copilot, Antigravity).
+
+Every command adheres to strict architectural standards:
+1. **Zero Interactive Prompts**: DevWorkspace never hangs waiting for stdin (`readline`). Destructive or mutative operations require explicit command-line flags (e.g., `--yes`).
+2. **Dual Output Modes**: Commands output colorized/ASCII human-readable text by default, or deterministic JSON via `--json`.
+3. **Execution Safety Taxonomy**: Commands are strictly partitioned into **Read-Only / Safe**, **Managed Local Mutating**, and **Guarded Destructive** operations.
+
+| Safety Category | Description | Commands |
+|---|---|---|
+| 🟢 **Read-Only / Safe** | Inspects filesystem and environment without altering any files or process state. Zero risk. | `status`, `doctor` (without `--fix`), `context`, `fact list`, `task list`, `task show`, `testenv list`, `decision list`, `decision show`, `session list`, `agent list`, `integrations status` |
+| 🟡 **Managed Local Mutating** | Writes or updates structured records in `.devworkspace/` using atomic file operations. | `init`, `analyze`, `refresh`, `fact add`, `fact verify`, `fact remove`, `task new`, `task update`, `task verify`, `task tests`, `task attest`, `task status`, `testenv declare`, `testenv revoke`, `decision add`, `session save`, `agent install`, `export`, `import`, `doctor --fix`, `migrate` |
+| 🔴 **Guarded Destructive / Hazardous** | Permanently deletes workspace state or executes shell checks. Strictly blocked without `--yes` or testenv declaration. | `reset` (requires `--yes`), `task run` (restricted to safe read-only contract checks unless testenv is declared) |
+
+---
+
+## 2. Common Global Options
+
+Every DevWorkspace command supports the following global options:
+
+- `--json`: Formats stdout as machine-readable JSON for AI agents and scripts. All status and log messages route to stderr.
+- `--cwd <dir>`: Sets the target directory as if the command were executed directly from `<dir>`.
+- `--root <dir>`: Explicitly specifies the repository root (defaults to Git top-level or current working directory).
+- `--debug`: Prints full stack traces and debug logging to stderr.
+- `--no-color`: Disables ANSI color escapes (automatically detected if stdout is not a TTY or `NO_COLOR` is set).
+- `--ascii`: Replaces Unicode symbols (`✓`, `✗`, `→`) with ASCII equivalents (`[OK]`, `[FAIL]`, `->`).
+- `--dry-run`: Previews actions and changes without writing files or modifying state.
+- `--help` / `-h`: Displays command-specific help and exits with status `0`.
+- `--version` / `-v`: Displays package version (`0.3.1`) and exits with status `0`.
+
+---
+
+## 3. Comprehensive Command Catalog
+
+---
+
+### 3.1. `devworkspace init`
+**Summary**: Initializes `.devworkspace/` inside the current repository.  
+**Safety**: 🟡 Managed Local Mutating (Safe to re-run; idempotent).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `initWorkspace()` in [`src/services/init.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/init.ts).
+
+#### Syntax
+```bash
+devworkspace init [--root <dir>] [--dry-run] [--with-integrations [--yes] [--scope project|user]]
+```
+
+#### Options
+- `--root <dir>`: Sets custom project root.
+- `--dry-run`: Shows directories and files that would be created without touching disk.
+- `--with-integrations`: Immediately chains into integration setup (`setup --integrations`).
+- `--yes`: Approves user-level integration installations.
+- `--scope project|user`: Target scope for integrations (default: `project`).
+
+#### Execution Mechanics & Side Effects
+1. Creates directory hierarchy: `.devworkspace/`, `context/`, `tasks/active/`, `tasks/completed/`, `decisions/`, `sessions/`, `analysis/`, and `local/`.
+2. Creates `.devworkspace/project.json` containing repository UUID, project name, root path, and schema version.
+3. Automatically adds `.devworkspace/local/` and migration backups to `.devworkspace/.gitignore`.
+4. Initializes starter `context/facts.json`, `context/testing-contract.json`, and `context/commands.json`.
+
+---
+
+### 3.2. `devworkspace analyze`
+**Summary**: Performs deterministic repository discovery and generates AI onboarding prompt.  
+**Safety**: 🟡 Managed Local Mutating (Pure Read-Only with `--dry-run`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `analyzeWorkspace()` in [`src/services/analysis.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/analysis.ts).
+
+#### Syntax
+```bash
+devworkspace analyze [--dry-run] [--json]
+```
+
+#### Execution Mechanics & Side Effects
+1. Walks the repository using bounded traversal (`src/discovery/scan.ts`), pruning ignored folders (`node_modules`, `.git`, `dist`, `target`).
+2. Detects languages, package managers, frameworks, test runners, databases, and monorepo workspaces (`src/discovery/detect.ts`).
+3. Discovers scripts from package manifests and maps them to standard testing contracts (typecheck, lint, unit, integration, e2e, security, build).
+4. Discovers documentation files (`README.md`, `CONTRIBUTING.md`, `docs/`) and entrypoints (`main.ts`, `index.js`, `app.py`).
+5. Atomically writes `.devworkspace/analysis/discovery.json` and `.devworkspace/analysis/onboarding-prompt.md`.
+6. Generates or updates `.devworkspace/context/facts.json` with high-confidence detected facts.
+
+---
+
+### 3.3. `devworkspace status`
+**Summary**: Provides a high-level operational overview of repository and workspace health.  
+**Safety**: 🟢 Read-Only / Safe.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `getStatus()` in [`src/services/status.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/status.ts).
+
+#### Syntax
+```bash
+devworkspace status [--strict] [--deep] [--json]
+```
+
+#### Options
+- `--strict`: Returns exit code `3` if any warnings, stale knowledge, or missing onboarding files exist.
+- `--deep`: Runs deep integration connectivity checks (identical to `doctor`).
+
+#### Execution Mechanics & Side Effects
+- Reads `project.json`, Git status (`HEAD`, branch, clean/dirty), task count by status, active decisions, stale facts, and integration state.
+- Does not modify any files. Returns exit code `0` (healthy), `1` (unreadable or not initialized), or `3` (strict warnings).
+
+---
+
+### 3.4. `devworkspace doctor`
+**Summary**: Diagnoses workspace consistency, security integrity, and integration health.  
+**Safety**: 🟢 Read-Only / Safe (🟡 Managed Local Mutating when run with `--fix`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `runDoctor()` in [`src/services/doctor.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/doctor.ts).
+
+#### Syntax
+```bash
+devworkspace doctor [--fix] [--strict] [--json]
+```
+
+#### Options
+- `--fix`: Safely repairs missing directories, restores corrupt schema templates, and re-adds missing `.gitignore` rules (never deletes user data).
+- `--strict`: Exits with code `3` if any warnings are detected.
+
+#### Diagnostic Checks Performed
+- **Workspace**: Verifies `.devworkspace/project.json`, directory structure, schema migrations, and write permissions.
+- **Git**: Confirms Git repository presence, verifies `.gitignore` ignores `local/` and temporary files.
+- **Security**: Verifies absence of tracked secret files (`.env`, private keys) and checks for symlink escape risks.
+- **Integrations**: Checks PATH presence and tool versions for Graphify, Agent Skills, and Ponytail.
+
+---
+
+### 3.5. `devworkspace refresh`
+**Summary**: Re-evaluates repository state, updates discovery, and flags stale facts.  
+**Safety**: 🟡 Managed Local Mutating (Pure Read-Only with `--dry-run`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `refreshWorkspace()` in [`src/services/refresh.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/refresh.ts).
+
+#### Syntax
+```bash
+devworkspace refresh [--dry-run] [--json]
+```
+
+#### Execution Mechanics & Side Effects
+1. Re-runs detection engine across package manifests and codebase structure.
+2. Compares modification timestamps and content hashes of files evidencing existing facts.
+3. Automatically marks facts `STALE` if their source files have changed or been removed.
+4. Updates `.devworkspace/analysis/discovery.json` and refreshes `.devworkspace/context/facts.json`.
+
+---
+
+### 3.6. `devworkspace context`
+**Summary**: Displays project context, testing contracts, and architecture facts.  
+**Safety**: 🟢 Read-Only / Safe.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `getContext()` in [`src/services/knowledge.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/knowledge.ts) or `getTaskContext()` in [`src/services/taskContext.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/taskContext.ts).
+
+#### Syntax
+```bash
+devworkspace context [--for <request>] [--topic <prefix>] [--full] [--json]
+```
+
+#### Options
+- `--for <request>`: **Progressive Context Mode**. Dynamically classifies `<request>`, retrieving only the relevant package facts, commands, and active task info while suppressing irrelevant noise.
+- `--topic <prefix>`: Filters facts by namespace prefix (e.g., `auth`, `db`, `deploy`).
+- `--full`: Includes full text of all markdown files in `.devworkspace/context/`.
+
+---
+
+### 3.7. `devworkspace fact`
+**Summary**: Manages durable project knowledge facts with evidence tracking.  
+**Safety**: 🟢 Safe for `list`; 🟡 Managed Local Mutating for `add`, `verify`, `remove`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `addFact()`, `verifyFactByKey()`, `removeFactByKey()` in [`src/services/knowledge.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/knowledge.ts).
+
+#### Subcommands & Syntax
+```bash
+# Add or update a fact
+devworkspace fact add --key <key> --value <text> --source <desc> [--file <rel-path>...] [--source-type ai|user|file|git] [--confidence HIGH|MEDIUM|LOW] [--status VERIFIED|INFERRED|UNKNOWN]
+
+# Mark a fact VERIFIED
+devworkspace fact verify <key>
+
+# Delete a fact
+devworkspace fact remove <key>
+
+# List all facts
+devworkspace fact list [--json]
+```
+
+#### Authority Ranking Rules
+When an update is submitted, DevWorkspace enforces authority ranking:
+- `user` (Rank 4) can overwrite any fact.
+- `file` / `git` (Rank 3) can overwrite `ai` facts.
+- `ai` (Rank 2) **cannot** overwrite a `user` or `file`-derived fact.
+
+---
+
+### 3.8. `devworkspace task`
+**Summary**: Core engineering workflow engine tracking task lifecycles and enforcing completion gates.  
+**Safety**: 🟢 Safe for `list`, `show`; 🟡 Mutating for `new`, `update`, `status`, `verify`, `tests`, `attest`; 🔴 Guarded Execution for `run`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls handlers in [`src/services/tasks.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/tasks.ts) and [`src/services/verify.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/verify.ts).
+
+#### Subcommands & Syntax
+```bash
+# 1. Create a new task (auto-classified)
+devworkspace task new "<request>" [--type BUG|FEATURE|REFACTOR|DOCS|INVESTIGATION] [--title <text>]
+
+# 2. List tasks
+devworkspace task list [--all] [--json]
+
+# 3. Inspect task details & completion gate status
+devworkspace task show <id> [--json]
+
+# 4. Update task metadata, plan, or criteria
+devworkspace task update <id> [--title <t>] [--summary <s>] [--criteria <c>...] [--plan <p>...] [--area <a>...] [--blocker <b>...] [--clear-blockers] [--require <check>...]
+
+# 5. Execute a verification check from the testing contract
+devworkspace task run <id> <check> [--package <dir>] [--timeout <seconds>]
+
+# 6. Record external verification outcome
+devworkspace task verify <id> <check> pass|fail|skip|pending [--package <dir>] [--reason user-override] [--detail <text>]
+
+# 7. Record test suite execution counts
+devworkspace task tests <id> --phase baseline|after --passed <n> --failed <n>
+
+# 8. Submit mandatory completion attestations
+devworkspace task attest <id> [--user-work-intact] [--knowledge-reviewed] [--final-state-inspected]
+
+# 9. Update task status (enforces completion gate if target is COMPLETED)
+devworkspace task status <id> <TODO|IN_PROGRESS|BLOCKED|COMPLETED|CANCELLED> [--note <text>]
+```
+
+#### Completion Gate Requirements
+To transition a task to `COMPLETED`, `evaluateGate()` validates:
+1. All required testing contract checks have passed (executed or claimed with user override).
+2. Regression check passes: `after.failed <= baseline.failed`.
+3. Completion summary is populated (`devworkspace task update <id> --summary "..."`).
+4. Read-only requests made zero file mutations.
+5. All 3 human attestations are verified: `--user-work-intact`, `--knowledge-reviewed`, `--final-state-inspected`.
+
+---
+
+### 3.9. `devworkspace testenv`
+**Summary**: Declares local test environments so database-touching checks can execute safely.  
+**Safety**: 🟡 Managed Local Mutating (writes to git-ignored `.devworkspace/local/testenv.json`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `declareTestEnv()`, `listTestEnv()`, `revokeTestEnv()` in [`src/services/verify.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/verify.ts).
+
+#### Subcommands & Syntax
+```bash
+# Declare an isolated test environment
+devworkspace testenv declare --package <dir> --check <unit|integration|e2e|security> [--check ...] --target "<text>" --yes
+
+# List active declarations
+devworkspace testenv list [--json]
+
+# Revoke a declaration
+devworkspace testenv revoke --package <dir>
+```
+
+#### Security Guard
+- DevWorkspace blocks execution of checks requiring external services (PostgreSQL, Redis, MySQL, MongoDB) unless explicitly declared here.
+- The `--target` must describe the environment (e.g. `"disposable docker-compose container"`). Storing connection strings or credentials is strictly prohibited and rejected.
+
+---
+
+### 3.10. `devworkspace decision`
+**Summary**: Manages Architecture Decision Records (ADRs) as durable markdown documents.  
+**Safety**: 🟢 Safe for `list`, `show`; 🟡 Mutating for `add`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `recordDecision()`, `getDecisions()`, `getDecision()` in [`src/services/records.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/records.ts).
+
+#### Subcommands & Syntax
+```bash
+# Add a new ADR
+devworkspace decision add --title <text> --context <text> --decision <text> --consequences <text> [--supersedes <number>]
+
+# List all ADRs
+devworkspace decision list [--json]
+
+# Show specific ADR
+devworkspace decision show <number>
+```
+
+#### Filesystem Storage
+- Stored as sequential Markdown files: `.devworkspace/decisions/0001-use-postgresql.md`.
+- Implements standard ADR structure: Number, Title, Status (Proposed/Accepted/Superseded), Date, Context, Decision, Consequences.
+
+---
+
+### 3.11. `devworkspace session`
+**Summary**: Records concise engineering session handoffs and resumption points.  
+**Safety**: 🟢 Safe for `list`; 🟡 Mutating for `save`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `recordSession()`, `getSessions()` in [`src/services/records.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/records.ts).
+
+#### Subcommands & Syntax
+```bash
+# Save a session handoff
+devworkspace session save --goal <goal> [--done <item>...] [--area <path>...] [--tests-run <desc>...] [--decision-note <note>...] [--remaining <item>...] [--next <action>] [--task <id>]
+
+# List recent sessions
+devworkspace session list [--limit <n>] [--json]
+```
+
+#### Privacy & Token Economy
+DevWorkspace stores **summarized milestones and handoffs only**. It strictly rejects full conversation transcripts, preserving AI context windows and preventing sensitive conversational leaks.
+
+---
+
+### 3.12. `devworkspace agent`
+**Summary**: Manages multi-agent instruction files and rule synchronizations.  
+**Safety**: 🟢 Safe for `list`; 🟡 Mutating for `install`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `installAgent()`, `listAgents()` in [`src/services/agent.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/agent.ts).
+
+#### Subcommands & Syntax
+```bash
+# Install instructions for coding agents
+devworkspace agent install [--agent claude|codex|cursor|copilot|all] [--dry-run]
+
+# List supported and detected agent configurations
+devworkspace agent list [--json]
+```
+
+#### Supported Agents & Targets
+- `claude`: Injects managed block into `CLAUDE.md`.
+- `codex`: Injects managed block into `AGENTS.md`.
+- `cursor`: Writes `.cursor/rules/devworkspace.mdc` or merges into `.cursorrules`.
+- `copilot`: Injects into `.github/copilot-instructions.md`.
+- `all`: Installs/updates rules for all 4 agents simultaneously.
+
+---
+
+### 3.13. `devworkspace setup`
+**Summary**: Installs and verifies external developer tools (Graphify, Agent Skills, Ponytail).  
+**Safety**: 🟡 Managed Local Mutating (requires `--yes` for machine/user scope).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `setupIntegrations()` in [`src/services/integrations.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/integrations.ts).
+
+#### Syntax
+```bash
+devworkspace setup --integrations [--yes] [--dry-run] [--scope project|user] [--only graphify,agent-skills,ponytail] [--json]
+```
+
+#### Options
+- `--integrations`: Explicitly designates integrations setup.
+- `--yes`: Approves operations that modify user global settings or invoke package managers.
+- `--scope project|user`: Target scope (default: `project`).
+- `--only <ids>`: Restricts setup to comma-separated integration IDs.
+
+---
+
+### 3.14. `devworkspace integrations`
+**Summary**: Inspects observed installation health or repairs integrations.  
+**Safety**: 🟢 Safe for `status`; 🟡 Mutating for `repair`.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `integrationsStatus()` in [`src/services/integrations.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/integrations.ts).
+
+#### Subcommands & Syntax
+```bash
+# Check integration health
+devworkspace integrations status [--quick] [--restarted] [--strict] [--json]
+
+# Repair missing or corrupt integrations
+devworkspace integrations repair [--yes] [--dry-run] [--only <ids>] [--scope project|user]
+```
+
+#### Verification Lifecycle Statuses
+- `VERIFIED`: Tool is present on PATH, version meets requirements, and executable responds.
+- `OBSERVED`: Binary detected, but deep invocation was bypassed (`--quick`).
+- `RESTART_REQUIRED`: Installed successfully; waiting for Claude Code restart.
+- `PREREQUISITES_MISSING`: Host lacks Python, Git, or Node.js.
+- `FAILED`: Installation or verification exited with non-zero code.
+
+---
+
+### 3.15. `devworkspace export`
+**Summary**: Bundles all workspace knowledge, decisions, sessions, and tasks into a portable JSON package.  
+**Safety**: 🟡 Managed Local Mutating (Pure Read-Only with `--dry-run`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `exportWorkspace()` in [`src/services/portability.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/portability.ts).
+
+#### Syntax
+```bash
+devworkspace export [--out <file>] [--dry-run] [--json]
+```
+
+#### Portability Protections
+- Generates a standalone JSON payload with SHA-256 integrity checksums.
+- Automatically excludes machine-local state (`.devworkspace/local/`).
+- Validates that no absolute filesystem paths or secret patterns leak into the bundle.
+
+---
+
+### 3.16. `devworkspace import`
+**Summary**: Restores a portable knowledge bundle into `.devworkspace/`.  
+**Safety**: 🟡 Managed Local Mutating.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `importWorkspace()` in [`src/services/portability.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/portability.ts).
+
+#### Syntax
+```bash
+devworkspace import <file> [--dry-run] [--overwrite] [--allow-different-project] [--json]
+```
+
+#### Safeguards
+- Verifies SHA-256 payload checksum before parsing.
+- Verifies that `project.id` matches the current workspace (unless bypassed with `--allow-different-project`).
+- Keeps timestamped backups (`.devworkspace/.backup-<date>/`) of all replaced files if `--overwrite` is specified.
+
+---
+
+### 3.17. `devworkspace reset`
+**Summary**: Completely resets `.devworkspace/` to a clean slate.  
+**Safety**: 🔴 Guarded Destructive (Requires `--yes`).  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `resetWorkspace()` in [`src/services/reset.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/reset.ts).
+
+#### Syntax
+```bash
+devworkspace reset [--include-agent-files] [--yes] [--dry-run] [--json]
+```
+
+#### Safeguards & Behavior
+- If invoked without `--yes`, prints a dry-run plan of all directories scheduled for deletion and exits with code `2`.
+- When `--include-agent-files` is provided, safely extracts and strips managed DevWorkspace blocks from `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` without altering surrounding user text.
+
+---
+
+### 3.18. `devworkspace migrate`
+**Summary**: Upgrades `.devworkspace/` schema files to the latest version.  
+**Safety**: 🟡 Managed Local Mutating.  
+**Source Handler**: [`src/cli/run.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/cli/run.ts) calls `migrateWorkspace()` in [`src/services/migrate.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/services/migrate.ts).
+
+#### Syntax
+```bash
+devworkspace migrate [--dry-run] [--json]
+```
+
+#### Migration Mechanics
+- Checks `schemaVersion` in `project.json` against current package version (`0.3.1`).
+- Sequentially applies forward migrations ([`src/core/migrations.ts`](file:///d:/projects/codeing_stuff/devworkspace/src/core/migrations.ts)).
+- Retains automatic rollbacks and snapshots before mutating schema structures.
+
+---
+
+## 4. Exit Code Contract
+
+DevWorkspace adheres to POSIX exit code conventions to provide predictable integration with CI/CD runners and AI agents:
+
+| Exit Code | Meaning | Examples |
+|:---:|---|---|
+| `0` | **Success / OK** | Command completed normally; check passed; gate evaluated cleanly. |
+| `1` | **Execution Failure** | Workspace corrupt/unreadable; test verification failed; doctor health check failed. |
+| `2` | **Usage Error / Approval Required** | Missing required flags (e.g. `--yes` on `reset`); invalid subcommand; schema validation error. |
+| `3` | **Strict Warnings** | In `--strict` mode: doctor warnings detected; stale knowledge found; integrations incomplete. |
+| `130` | **Interrupted** | Process interrupted by `SIGINT` (Ctrl+C) or `SIGTERM`. Cleanups executed; locks released. |
+