agentorch 0.1.0__tar.gz

agentorch-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: agentorch
+Version: 0.1.0
+Summary: DevTorch — AI reasoning capture, audit trail, and governance for agent-assisted development
+Author-email: Hemant Joshi <hemant@flotorch.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hemantcgi/DevTorch
+Project-URL: Repository, https://github.com/hemantcgi/DevTorch
+Project-URL: Documentation, https://github.com/hemantcgi/DevTorch/blob/main/Implementation/README.md
+Keywords: ai,agents,governance,audit,llm,reasoning,devtorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Provides-Extra: wrapper
+Requires-Dist: anthropic>=0.40.0; extra == "wrapper"
+Requires-Dist: openai>=1.50.0; extra == "wrapper"
+Requires-Dist: google-generativeai>=0.8.0; extra == "wrapper"
+Requires-Dist: boto3>=1.35.0; extra == "wrapper"
+Requires-Dist: tiktoken>=0.7.0; extra == "wrapper"
+Provides-Extra: proxy
+Requires-Dist: fastapi>=0.115.0; extra == "proxy"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "proxy"
+Requires-Dist: httpx>=0.27.0; extra == "proxy"
+Requires-Dist: pydantic>=2.9.0; extra == "proxy"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: agentorch[mcp,proxy,wrapper]; extra == "all"
+
+# DevTorch
+
+**Local-first AI agent governance.** DevTorch gives multi-agent systems a shared on-disk audit trail, coordination vector, privacy controls, and LLM integration layer — all without a remote service.
+
+```
+pip install devtorch
+devtorch init
+devtorch commit -m "Add payments service"
+devtorch debug timeline
+```
+
+---
+
+## What it does
+
+| Concern | DevTorch feature |
+|---------|-----------------|
+| Reasoning audit trail | Append-only `.GCC/events.log.jsonl` with SHA-256 hash chain |
+| Multi-agent coordination | Coordination vector Θ — shared sensitivity map across agents |
+| Privacy compliance | RDP ε-budget tracking; `[PRIVATE]` span suppression; SIS-TC quarantine |
+| LLM integration | SDK wrappers, HTTP proxy, Claude Code MCP server + hooks |
+| Governance observability | Structured reports, browser dashboard, VS Code extension (Antigravity-compatible) |
+| Alerting | Slack, Jira, PagerDuty outbound webhooks |
+| Metrics | MCS, DHS, ROI — all traceable to citations or explicit design choices |
+
+Everything lives in `.GCC/` — a local directory in your project. No database, no network service, no telemetry.
+
+---
+
+## Install
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+
+# Core CLI only
+pip install devtorch
+
+# With SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock)
+pip install devtorch[wrapper]
+
+# With HTTP proxy + dashboard API (FastAPI)
+pip install devtorch[proxy]
+
+# Everything
+pip install devtorch[all]
+```
+
+**Requirements**: Python 3.10+
+
+---
+
+## Quick start
+
+```bash
+cd /path/to/your/project
+devtorch init
+
+# Record reasoning commits
+devtorch commit -m "Chose idempotent transfer endpoint design"
+
+# Add per-agent branches
+devtorch branch app
+devtorch branch dba
+devtorch branch security-review
+
+# Add sensitivity information
+devtorch sensitivity add \
+  --source agent-app \
+  --concept api_contract \
+  --confidence 0.9 \
+  --disclosure PUBLIC \
+  -m "API shape depends on transaction schema"
+
+# Inspect state
+devtorch status
+devtorch debug timeline
+devtorch debug branch-compare app dba
+```
+
+---
+
+## LLM integration
+
+### Option 1 — SDK wrapper (you own the code)
+
+```python
+# One-line change — same API, governance captured automatically
+from devtorch_core.wrapper.anthropic import DevTorchAnthropic
+client = DevTorchAnthropic()   # replaces anthropic.Anthropic()
+
+# OpenAI
+from devtorch_core.wrapper.openai import DevTorchOpenAI
+client = DevTorchOpenAI()
+
+# Local models via Ollama (no API key required)
+from devtorch_core.wrapper.ollama import DevTorchOllama
+client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`
+
+# Google Gemini
+from devtorch_core.wrapper.gemini import DevTorchGemini
+client = DevTorchGemini(model_name="gemini-1.5-pro")
+
+# AWS Bedrock
+from devtorch_core.wrapper.bedrock import DevTorchBedrock
+client = DevTorchBedrock(region_name="us-east-1")
+```
+
+See `OLLAMA_SETUP.md` for the full Ollama guide.
+
+### Option 2 — HTTP proxy (Cursor, JetBrains, closed-source IDEs)
+
+```bash
+devtorch proxy install   # installs as macOS LaunchAgent or Linux systemd service
+devtorch proxy start     # runs on localhost:8765
+```
+
+Configure your IDE to use `http://localhost:8765/anthropic` (or `/openai`, `/gemini`). The proxy injects RACP context and captures responses with zero latency penalty.
+
+### Option 3 — MCP server + hooks (Claude Code, Cursor, Kiro, Antigravity)
+
+```bash
+devtorch setup   # one command: init + hooks + MCP config + CLAUDE.md + AGENTS.md
+```
+
+Claude Code / Cursor / Kiro / Antigravity then call `devtorch_commit`, `devtorch_sensitivity_add`, `devtorch_context`, and `devtorch_theta_read` as native MCP tools. See `IDE_SETUP.md` for per-IDE instructions.
+
+### Option 4 — OpenAI Codex CLI proxy
+
+```bash
+# Start the Codex-specific proxy on localhost:8766
+python -m devtorch_core.codex start
+
+# Point Codex CLI at it
+export OPENAI_BASE_URL=http://localhost:8766/v1
+codex "Add error handling to the payment service"
+```
+
+See `CODEX_SETUP.md` for the full guide.
+
+### Option 5 — Org gateway (enterprise, multi-developer)
+
+```bash
+cd deploy/
+cp .env.example .env   # set ANTHROPIC_API_KEY and/or OPENAI_API_KEY
+docker compose up      # gateway on :8080, dashboard on :3000
+```
+
+Developers point their IDE proxy URL to the gateway instead of api.openai.com. The gateway handles central API key management, SSO attribution, governance policy enforcement, and metrics aggregation. See `deploy/README.md` for Helm and Docker Compose instructions.
+
+---
+
+## Architecture
+
+```
+devtorch_core/           Pure library — all business logic
+  gcc.py                 GCCRepository: .GCC/ layout, event log, commits, branches
+  sensitivity.py         Sensitivity events + SensitivityStore
+  theta.py               Coordination vector Θ + AggPhi
+  capability.py          OmegaCapability (A1), Lipschitz bound, PST runner
+  invariants.py          I1 (commit-backed), I3 (semantic grounding)
+  variance.py            f_max formula, rolling monitor, VARIANCE_ALERT
+  rep.py                 REP ledger — append-only local transport
+  sis.py                 SIS-TC corpus evaluation + quarantine
+  rdp.py                 RDP ε-budget tracking
+  disclosure.py          [PRIVATE] span suppression
+  prompt_artifact.py     RACP system prompt artifact store
+  deltaf.py              Δf estimation
+  parser/                XML block extractor, thinking tokens, inference
+  wrapper/               SDK drop-in wrappers (Anthropic, OpenAI, Gemini, Bedrock)
+  proxy/                 HTTP reverse proxy (localhost:8765)
+  mcp/                   MCP/JSON-RPC server
+  hooks/                 Claude Code hooks + git commit-msg hook
+  metrics/               MCS, DHS, ROI, calibration, citation registry
+  observability/         Structured reports + enterprise metrics webhook
+  alerts/                Slack, Jira, PagerDuty outbound alerting
+  rep_network/           Multi-node REP ledger sync
+  github/                GitHub App webhook + PR comment builder
+  dashboard_api.py       REST API for browser dashboard
+
+devtorch_cli/
+  main.py                Thin argparse wrapper over devtorch_core
+
+extensions/vscode/       VS Code extension (read-only sidebar; installs in Antigravity via .vsix)
+dashboard/               React browser dashboard (Developer/Lead/CISO views)
+tests/                   637 tests across all sprints (S0–S18)
+examples/                end-to-end scenario examples
+```
+
+---
+
+## On-disk layout (`.GCC/`)
+
+```
+.GCC/
+  VERSION                    # format version
+  events.log.jsonl           # append-only audit stream (hash chain)
+  main.md / log.md           # reasoning roadmap + chronological log
+  refs/HEAD                  # current branch
+  refs/branches/<name>       # branch tip commit ID
+  commits/<id>.json          # commit objects
+  sensitivities/events.jsonl # raw sensitivity events
+  theta.json                 # coordination vector Θ
+  capabilities/omega.json    # A1 capability state
+  variance/                  # calibration_report.json, live_state.json
+  rep/rep_ledger.jsonl        # REP transport ledger
+  rep/peers.json             # peer list for multi-node sync
+  sis/                       # SIS-TC corpus, reports, quarantine events
+  rdp/rdp_state.json         # RDP ε-budget
+  concepts/<name>.json       # I3 concept definitions
+  prompts/                   # RACP system prompt artifact
+  deltaf/                    # Δf report
+  calibration.json           # team-specific metric calibration
+  context_bundles/           # MECW-bounded context snapshots
+  NODE_STATE                 # node state machine
+```
+
+---
+
+## Key safety properties
+
+| Property | Mechanism |
+|----------|-----------|
+| Commit-backed decisions (I1) | Merge/unlock blocked unless branch tips exist in commits/ and events log |
+| Semantic grounding (I3) | Operations using concepts_used require matching definitions in concepts/ |
+| Capability gate (A1) | Textual mode requires valid OmegaCapability + passing PST |
+| Variance control (A2) | f_max=0 forces deterministic mode; A1 gate blocks textual_mode |
+| Privacy budget (RDP) | epsilon exhaustion flips read_only=true in rdp_state.json |
+| Proxy trust boundary | Proxy binds to 127.0.0.1 only; API keys pass through, never stored |
+
+---
+
+## Run the tests
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .[dev,proxy]
+pytest tests/         # 637 tests
+```
+
+---
+
+## Configuration reference
+
+| Env var | Purpose |
+|---------|---------|
+| `DEVTORCH_DISABLE=1` | Disable all injection and capture (wrapper/proxy become transparent) |
+| `DEVTORCH_SLACK_WEBHOOK_URL` | Slack alert delivery |
+| `DEVTORCH_JIRA_URL` / `_PROJECT_KEY` / `_API_TOKEN` / `_EMAIL` | Jira issue creation |
+| `DEVTORCH_PAGERDUTY_ROUTING_KEY` | PagerDuty event trigger |
+| `DEVTORCH_ALERT_MIN_SEVERITY` | Minimum severity to alert on (`info`/`warning`/`critical`) |
+| `DEVTORCH_METRICS_WEBHOOK_URL` | Enterprise metrics webhook endpoint |
+| `DEVTORCH_ORG_ID` | Org identifier in metrics payloads |
+| `DEVTORCH_METRICS_API_KEY` | Auth for metrics webhook |
+| `DEVTORCH_GITHUB_WEBHOOK_SECRET` | HMAC secret for GitHub App webhook |
+
+---
+
+## Documentation
+
+| File | Contents |
+|------|----------|
+| `DOCS.md` | Architecture deep-dive, Sprint 4–6 feature reference, conformance matrix |
+| `OBSERVABILITY.md` | Observability pillars, daily-recall pattern, shell audit script template |
+| `CONTRIBUTING.md` | Dev environment, test commands, sprint structure, PR checklist |
+| `THREAT_MODEL.md` | Trust model, hash chain integrity, proxy trust boundary, known limitations |
+| `DESIGN_THOUGHTS.md` | Design decisions Q1–Q14 with full citation validation |
+| `IDE_SETUP.md` | VS Code, Cursor, Kiro, and Antigravity setup instructions |
+| `ANTIGRAVITY_SETUP.md` | Google Antigravity step-by-step onboarding |
+| `CLAUDE_CODE_QUICKSTART.md` | Claude Code step-by-step onboarding |
+| `OLLAMA_SETUP.md` | Local model setup with Ollama (Llama, Mistral, Gemma, Phi, Qwen) |
+| `CODEX_SETUP.md` | OpenAI Codex CLI proxy setup |
+| `AGENTS.md` | Persistent AI instructions for Antigravity/Kiro |
+| `deploy/README.md` | Enterprise org gateway — Docker Compose and Helm deployment |
+| `devtorch_core/metrics/README.md` | MCS/DHS/ROI formulas and calibration guide |
+| `devtorch_core/proxy/README.md` | HTTP proxy deployment options |
+| `devtorch_core/wrapper/README.md` | SDK wrapper quick-start for all providers |
+| `dashboard/README.md` | Browser dashboard setup and API reference |
+
+---
+
+## Metrics credibility
+
+DevTorch is explicit about what every number is based on:
+
+- **15 min context switch** — Parnin & Rugaber (2011), *Software Quality Journal*. DOI: [10.1007/s11219-010-9104-9](https://doi.org/10.1007/s11219-010-9104-9). Measured for programming tasks only.
+- **Auditor rate** — BLS SOC 13-2011 (2023): $39–40/hr employed staff. External rates ($75–400/hr) not used as defaults.
+- **MCS/DHS weights** — Design choices. No external benchmark. Calibrate with your team's data.
+- **Developer hourly rate** — No default. You must set it: `devtorch calibrate --set developer_hourly_rate=<value>`
+
+See `devtorch_core/metrics/credibility.py` for the full citation registry.
+
+---
+
+## License
+
+Apache 2.0

agentorch-0.1.0/README.md

@@ -0,0 +1,296 @@
+# DevTorch
+
+**Local-first AI agent governance.** DevTorch gives multi-agent systems a shared on-disk audit trail, coordination vector, privacy controls, and LLM integration layer — all without a remote service.
+
+```
+pip install devtorch
+devtorch init
+devtorch commit -m "Add payments service"
+devtorch debug timeline
+```
+
+---
+
+## What it does
+
+| Concern | DevTorch feature |
+|---------|-----------------|
+| Reasoning audit trail | Append-only `.GCC/events.log.jsonl` with SHA-256 hash chain |
+| Multi-agent coordination | Coordination vector Θ — shared sensitivity map across agents |
+| Privacy compliance | RDP ε-budget tracking; `[PRIVATE]` span suppression; SIS-TC quarantine |
+| LLM integration | SDK wrappers, HTTP proxy, Claude Code MCP server + hooks |
+| Governance observability | Structured reports, browser dashboard, VS Code extension (Antigravity-compatible) |
+| Alerting | Slack, Jira, PagerDuty outbound webhooks |
+| Metrics | MCS, DHS, ROI — all traceable to citations or explicit design choices |
+
+Everything lives in `.GCC/` — a local directory in your project. No database, no network service, no telemetry.
+
+---
+
+## Install
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+
+# Core CLI only
+pip install devtorch
+
+# With SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock)
+pip install devtorch[wrapper]
+
+# With HTTP proxy + dashboard API (FastAPI)
+pip install devtorch[proxy]
+
+# Everything
+pip install devtorch[all]
+```
+
+**Requirements**: Python 3.10+
+
+---
+
+## Quick start
+
+```bash
+cd /path/to/your/project
+devtorch init
+
+# Record reasoning commits
+devtorch commit -m "Chose idempotent transfer endpoint design"
+
+# Add per-agent branches
+devtorch branch app
+devtorch branch dba
+devtorch branch security-review
+
+# Add sensitivity information
+devtorch sensitivity add \
+  --source agent-app \
+  --concept api_contract \
+  --confidence 0.9 \
+  --disclosure PUBLIC \
+  -m "API shape depends on transaction schema"
+
+# Inspect state
+devtorch status
+devtorch debug timeline
+devtorch debug branch-compare app dba
+```
+
+---
+
+## LLM integration
+
+### Option 1 — SDK wrapper (you own the code)
+
+```python
+# One-line change — same API, governance captured automatically
+from devtorch_core.wrapper.anthropic import DevTorchAnthropic
+client = DevTorchAnthropic()   # replaces anthropic.Anthropic()
+
+# OpenAI
+from devtorch_core.wrapper.openai import DevTorchOpenAI
+client = DevTorchOpenAI()
+
+# Local models via Ollama (no API key required)
+from devtorch_core.wrapper.ollama import DevTorchOllama
+client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`
+
+# Google Gemini
+from devtorch_core.wrapper.gemini import DevTorchGemini
+client = DevTorchGemini(model_name="gemini-1.5-pro")
+
+# AWS Bedrock
+from devtorch_core.wrapper.bedrock import DevTorchBedrock
+client = DevTorchBedrock(region_name="us-east-1")
+```
+
+See `OLLAMA_SETUP.md` for the full Ollama guide.
+
+### Option 2 — HTTP proxy (Cursor, JetBrains, closed-source IDEs)
+
+```bash
+devtorch proxy install   # installs as macOS LaunchAgent or Linux systemd service
+devtorch proxy start     # runs on localhost:8765
+```
+
+Configure your IDE to use `http://localhost:8765/anthropic` (or `/openai`, `/gemini`). The proxy injects RACP context and captures responses with zero latency penalty.
+
+### Option 3 — MCP server + hooks (Claude Code, Cursor, Kiro, Antigravity)
+
+```bash
+devtorch setup   # one command: init + hooks + MCP config + CLAUDE.md + AGENTS.md
+```
+
+Claude Code / Cursor / Kiro / Antigravity then call `devtorch_commit`, `devtorch_sensitivity_add`, `devtorch_context`, and `devtorch_theta_read` as native MCP tools. See `IDE_SETUP.md` for per-IDE instructions.
+
+### Option 4 — OpenAI Codex CLI proxy
+
+```bash
+# Start the Codex-specific proxy on localhost:8766
+python -m devtorch_core.codex start
+
+# Point Codex CLI at it
+export OPENAI_BASE_URL=http://localhost:8766/v1
+codex "Add error handling to the payment service"
+```
+
+See `CODEX_SETUP.md` for the full guide.
+
+### Option 5 — Org gateway (enterprise, multi-developer)
+
+```bash
+cd deploy/
+cp .env.example .env   # set ANTHROPIC_API_KEY and/or OPENAI_API_KEY
+docker compose up      # gateway on :8080, dashboard on :3000
+```
+
+Developers point their IDE proxy URL to the gateway instead of api.openai.com. The gateway handles central API key management, SSO attribution, governance policy enforcement, and metrics aggregation. See `deploy/README.md` for Helm and Docker Compose instructions.
+
+---
+
+## Architecture
+
+```
+devtorch_core/           Pure library — all business logic
+  gcc.py                 GCCRepository: .GCC/ layout, event log, commits, branches
+  sensitivity.py         Sensitivity events + SensitivityStore
+  theta.py               Coordination vector Θ + AggPhi
+  capability.py          OmegaCapability (A1), Lipschitz bound, PST runner
+  invariants.py          I1 (commit-backed), I3 (semantic grounding)
+  variance.py            f_max formula, rolling monitor, VARIANCE_ALERT
+  rep.py                 REP ledger — append-only local transport
+  sis.py                 SIS-TC corpus evaluation + quarantine
+  rdp.py                 RDP ε-budget tracking
+  disclosure.py          [PRIVATE] span suppression
+  prompt_artifact.py     RACP system prompt artifact store
+  deltaf.py              Δf estimation
+  parser/                XML block extractor, thinking tokens, inference
+  wrapper/               SDK drop-in wrappers (Anthropic, OpenAI, Gemini, Bedrock)
+  proxy/                 HTTP reverse proxy (localhost:8765)
+  mcp/                   MCP/JSON-RPC server
+  hooks/                 Claude Code hooks + git commit-msg hook
+  metrics/               MCS, DHS, ROI, calibration, citation registry
+  observability/         Structured reports + enterprise metrics webhook
+  alerts/                Slack, Jira, PagerDuty outbound alerting
+  rep_network/           Multi-node REP ledger sync
+  github/                GitHub App webhook + PR comment builder
+  dashboard_api.py       REST API for browser dashboard
+
+devtorch_cli/
+  main.py                Thin argparse wrapper over devtorch_core
+
+extensions/vscode/       VS Code extension (read-only sidebar; installs in Antigravity via .vsix)
+dashboard/               React browser dashboard (Developer/Lead/CISO views)
+tests/                   637 tests across all sprints (S0–S18)
+examples/                end-to-end scenario examples
+```
+
+---
+
+## On-disk layout (`.GCC/`)
+
+```
+.GCC/
+  VERSION                    # format version
+  events.log.jsonl           # append-only audit stream (hash chain)
+  main.md / log.md           # reasoning roadmap + chronological log
+  refs/HEAD                  # current branch
+  refs/branches/<name>       # branch tip commit ID
+  commits/<id>.json          # commit objects
+  sensitivities/events.jsonl # raw sensitivity events
+  theta.json                 # coordination vector Θ
+  capabilities/omega.json    # A1 capability state
+  variance/                  # calibration_report.json, live_state.json
+  rep/rep_ledger.jsonl        # REP transport ledger
+  rep/peers.json             # peer list for multi-node sync
+  sis/                       # SIS-TC corpus, reports, quarantine events
+  rdp/rdp_state.json         # RDP ε-budget
+  concepts/<name>.json       # I3 concept definitions
+  prompts/                   # RACP system prompt artifact
+  deltaf/                    # Δf report
+  calibration.json           # team-specific metric calibration
+  context_bundles/           # MECW-bounded context snapshots
+  NODE_STATE                 # node state machine
+```
+
+---
+
+## Key safety properties
+
+| Property | Mechanism |
+|----------|-----------|
+| Commit-backed decisions (I1) | Merge/unlock blocked unless branch tips exist in commits/ and events log |
+| Semantic grounding (I3) | Operations using concepts_used require matching definitions in concepts/ |
+| Capability gate (A1) | Textual mode requires valid OmegaCapability + passing PST |
+| Variance control (A2) | f_max=0 forces deterministic mode; A1 gate blocks textual_mode |
+| Privacy budget (RDP) | epsilon exhaustion flips read_only=true in rdp_state.json |
+| Proxy trust boundary | Proxy binds to 127.0.0.1 only; API keys pass through, never stored |
+
+---
+
+## Run the tests
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .[dev,proxy]
+pytest tests/         # 637 tests
+```
+
+---
+
+## Configuration reference
+
+| Env var | Purpose |
+|---------|---------|
+| `DEVTORCH_DISABLE=1` | Disable all injection and capture (wrapper/proxy become transparent) |
+| `DEVTORCH_SLACK_WEBHOOK_URL` | Slack alert delivery |
+| `DEVTORCH_JIRA_URL` / `_PROJECT_KEY` / `_API_TOKEN` / `_EMAIL` | Jira issue creation |
+| `DEVTORCH_PAGERDUTY_ROUTING_KEY` | PagerDuty event trigger |
+| `DEVTORCH_ALERT_MIN_SEVERITY` | Minimum severity to alert on (`info`/`warning`/`critical`) |
+| `DEVTORCH_METRICS_WEBHOOK_URL` | Enterprise metrics webhook endpoint |
+| `DEVTORCH_ORG_ID` | Org identifier in metrics payloads |
+| `DEVTORCH_METRICS_API_KEY` | Auth for metrics webhook |
+| `DEVTORCH_GITHUB_WEBHOOK_SECRET` | HMAC secret for GitHub App webhook |
+
+---
+
+## Documentation
+
+| File | Contents |
+|------|----------|
+| `DOCS.md` | Architecture deep-dive, Sprint 4–6 feature reference, conformance matrix |
+| `OBSERVABILITY.md` | Observability pillars, daily-recall pattern, shell audit script template |
+| `CONTRIBUTING.md` | Dev environment, test commands, sprint structure, PR checklist |
+| `THREAT_MODEL.md` | Trust model, hash chain integrity, proxy trust boundary, known limitations |
+| `DESIGN_THOUGHTS.md` | Design decisions Q1–Q14 with full citation validation |
+| `IDE_SETUP.md` | VS Code, Cursor, Kiro, and Antigravity setup instructions |
+| `ANTIGRAVITY_SETUP.md` | Google Antigravity step-by-step onboarding |
+| `CLAUDE_CODE_QUICKSTART.md` | Claude Code step-by-step onboarding |
+| `OLLAMA_SETUP.md` | Local model setup with Ollama (Llama, Mistral, Gemma, Phi, Qwen) |
+| `CODEX_SETUP.md` | OpenAI Codex CLI proxy setup |
+| `AGENTS.md` | Persistent AI instructions for Antigravity/Kiro |
+| `deploy/README.md` | Enterprise org gateway — Docker Compose and Helm deployment |
+| `devtorch_core/metrics/README.md` | MCS/DHS/ROI formulas and calibration guide |
+| `devtorch_core/proxy/README.md` | HTTP proxy deployment options |
+| `devtorch_core/wrapper/README.md` | SDK wrapper quick-start for all providers |
+| `dashboard/README.md` | Browser dashboard setup and API reference |
+
+---
+
+## Metrics credibility
+
+DevTorch is explicit about what every number is based on:
+
+- **15 min context switch** — Parnin & Rugaber (2011), *Software Quality Journal*. DOI: [10.1007/s11219-010-9104-9](https://doi.org/10.1007/s11219-010-9104-9). Measured for programming tasks only.
+- **Auditor rate** — BLS SOC 13-2011 (2023): $39–40/hr employed staff. External rates ($75–400/hr) not used as defaults.
+- **MCS/DHS weights** — Design choices. No external benchmark. Calibrate with your team's data.
+- **Developer hourly rate** — No default. You must set it: `devtorch calibrate --set developer_hourly_rate=<value>`
+
+See `devtorch_core/metrics/credibility.py` for the full citation registry.
+
+---
+
+## License
+
+Apache 2.0