Metadata-Version: 2.4
Name: omc-os
Version: 0.3.9
Summary: OMC external-driver front door — goal -> dry-run composition plan over the harness modules (Evidence-First agent OS).
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Evidence-First OS for AI Coding Agents

[![CI](https://github.com/lin-mouren/evidence-first-os/actions/workflows/ci.yml/badge.svg)](https://github.com/lin-mouren/evidence-first-os/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Spec V3](https://img.shields.io/badge/Spec-V3.23-blue)](EVIDENCE-FIRST-OS-COMPLETE-SPEC.md)

🇨🇳 中文版: [README.zh.md](README.zh.md) · 📖 **New here?** See [docs/quickstart.md](docs/quickstart.md) for copy-paste onboarding prompts.

🧩 **Consuming the VCOS runtime in your own project?** See **[docs/CONSUMING-VCOS.md](docs/CONSUMING-VCOS.md)** — the complete end-to-end guide (idea → develop → ship → iterate), observer + harness modes, the `agent_step` protocol, conformance, and shipped-vs-gated boundaries.

📐 **Structuring your own repo for humans + AI agents?** See **[docs/STANDARD-PROJECT-STRUCTURE.md](docs/STANDARD-PROJECT-STRUCTURE.md)** — a portable, evidence-backed world-class standard (AGENTS.md/CLAUDE.md entry · README/ARCHITECTURE/ADR/Diátaxis · navigation-vs-architecture diagrams) you can copy into any project. 可移植的世界级项目结构规范。

User-level default configuration that makes **Claude Code + OpenAI Codex** refuse guess-based answers and shallow diagnoses by **default**, in every session, every project.

> "Verification > Instruction" (ETH Zurich 2026, arXiv:2602.11988) — long instruction files reduce success rate 3% and cost 20%. This repo enforces evidence-first behavior through **hooks** (deterministic gates), not prose.

## TL;DR — What you get (after `bash install.sh`)

- ✅ **Iron Law enforced**: hook-level blocking of unverified facts ("82k stars" without `gh repo view`), shallow fixes (`change line 42` without `Mechanism gap:`), and false completion claims ("done" without `npm test`)
- ✅ **L0-L4 diagnosis ladder** mandatory for debug tasks (Evidence → Root cause → Mechanism gap → Prevention)
- ✅ **Stop quality gate**: 7 numbered quality checks + spec archive guard + retired-recap drift guard; a non-blocking recap emitter adds one italic-gray `Stop says: 🛡️ <project> V3 — ...` line on rule-applied turns; set `CODEX_STOP_GATE_ADVISORY=1` to switch the Codex stop gate from hard-block to warn-only
- ✅ **V3.19' folded routing**: 8-pattern keyword router on every prompt — spec writing emits EARS/grilling pointer, debug emits taxonomy pointer, implement emits Simplicity reminder, goal-criteria emits Goal-Driven reminder
- ✅ **Audit-grade trace**: `~/.claude/audit/*.log` + `<project>/.ai/evidence.jsonl` prove every hook fire, every prompt classification, every tool call's claim type
- ✅ **Survives existing setup**: merge-preserve installer keeps your OMC, skill-os, claude-mem, mattpocock, oh-my-codex hooks intact

## One-command install

```bash
git clone https://github.com/lin-mouren/evidence-first-os.git
cd evidence-first-os
bash install.sh
```

Default behavior (`merge-preserve`):
- Renames existing `~/.claude/CLAUDE.md` → `~/.claude/OMC.md`, writes new `CLAUDE.md` that `@import`s both
- Backs up `settings.json` to `*.bak-<timestamp>`, `jq`-merges V3 hooks into existing array (no overwrites)
- Skills installed only if absent (preserves obra-superpowers `systematic-debugging` etc.)

For a clean machine: `bash install.sh --force` overwrites instead of merging.

## Verify install

```bash
bash verify.sh
# §9.1 anti-guessing verification       PASS
# §9.2 L0-L4 diagnosis ladder           PASS
# §9.3 completion claim gate            PASS
# §9.5 configuration integrity guard    PASS (2 checks)
# §9.5b reference-integrity scan        PASS (3 checks)
# Positive control                      PASS
# §9.6 Codex cross-stack hook smoke     PASS (4 checks)
# §9.7 Stop hook surgical gate          PASS (2 checks)
# §9.8 Project doctor                   PASS
# Result: 16 passed, 0 failed
```

After your next Claude Code session start:

```bash
tail -3 ~/.claude/audit/session-start.log
# Expect: "2026-... PWD=... HOOK_EVENT=... matcher=session-start-policy.sh"
```

---

# 🚀 Recommended efficient usage

This is the **single most important section of this README**. Read it before doing real work with V3.

## 1. The daily-driver mental model

V3 is invisible until you give it a signal. The signal lives **in your prompt**. Choose your verb wisely; the right verb activates the right rule pointer at zero token cost.

| What you want to do | Use these words in your prompt | What the hook injects |
|---|---|---|
| Write a new feature spec | `spec` · `requirements` · `feature` · `需求` · `specify` · `EARS` · `grilling` | `[vcos-spec]` pointer → grilling 8-field intake + EARS template (V3.19' P1+R1) |
| Implement / fix code | `方案` · `solution` · `implement` · `fix` · `修复` | `[simplicity-first]` Karpathy Rule 2 reminder |
| Define success criteria | `goal` · `criteria` · `success` · `measurable` · `verifiable` · `目标` · `指标` | `[goal-driven]` Karpathy Rule 4 + verify-after-each-step template |
| Debug / find root cause | `debug` · `root cause` · `why` · `为什么` · `最佳方案` | `[evidence-required]` Evidence/Symptom/Root cause/Gap/Prevention scaffold |
| Verify external facts | `verify` · `check` · `actual` · `latest` · `当前` · `最新` · `验证` | `[evidence-required]` 5-step claim protocol |
| Audit Claude Code config | `skill` · `hook` · `AGENTS` · `CLAUDE` · `settings` · `managed` | `[evidence-required]` |
| Hedge-flag self-check | `应该是` · `可能是` · `看起来` · `通常` · `显然` · `不可能` | `[evidence-required]` red-flag downgrade |

**Karpathy Simplicity hint**: do *not* try to use every signal in every prompt. Use the most relevant one. The hooks decay gracefully if no signal matches (silent — zero injection).

## 2. Per-project setup (one command, 5 seconds)

The fastest path is the **`init-project.sh`** helper. From any project root:

```bash
bash ~/.claude/scripts/init-project.sh
```

It is idempotent and skips any file that already exists. What it does:

1. Drops a portable `.envrc` (auto-discovers most-recent `.ai/specs/in-progress/<feature>/`, exports `V3_SPEC_ID` + `V3_CTX_MANIFEST_HASH`; safe to source in bash or zsh)
2. Drops a ≤30-line `CLAUDE.md` project pointer (lists active V3 indicators + spec lifecycle + V3.19' shared-schema names)
3. Ensures `.ai/specs/{in-progress,plans-executed}/` directories exist
4. Appends `.envrc.local` + `.ai/` to existing `.gitignore` if missing
5. Runs `direnv allow .` when direnv is installed; otherwise prints the manual `source .envrc` reminder

### Alternative: install + bootstrap in one shot

If you are installing V3 for the first time AND want to bootstrap the current project in the same call:

```bash
bash install.sh --with-direnv-template
```

The `--with-direnv-template` flag runs `init-project.sh` against the cwd at the end of the standard install. Useful when cloning evidence-first-os itself or installing into a brand-new repo.

### If your project already has CLAUDE.md (or AGENTS.md)

`init-project.sh` is **idempotent** — it never overwrites existing files. When you run it in a project that already has a project-level `CLAUDE.md` (e.g., AIEP / Spec Kit / company framework), the script will:

- `[skip]` CLAUDE.md (your project constitution is preserved verbatim)
- `[created]` `.envrc` (P3 env auto-export)
- `[ensured]` `.ai/specs/{in-progress,plans-executed}/`
- `[appended]` `.gitignore` (`.envrc.local` + `.ai/`)

This is by design: V3 user-level rules in `~/.claude/CLAUDE.md` coexist with any project-level `CLAUDE.md` (Karpathy Surgical Changes — V3 adds, project retains).

To explicitly cross-reference V3 indicators inside an existing project `CLAUDE.md`, prepend a small block at the top (≤10 lines):

```markdown
> **V3.19' Evidence-First OS integration** (added by `~/.claude/scripts/init-project.sh`)
> User-level V3 defaults from `~/.claude/CLAUDE.md` + `~/.ai-policies/core.md` apply.
> - **Active V3 indicators** (Stop hook check 8 auto-emit): Think-Before-Coding ✓ / Deep-Diagnosis ✓ / Surgical-Changes ✓ / Karpathy ✓ / Goal-Driven ✓
> - **Spec lifecycle**: `.ai/specs/in-progress/<feature>/` → `.ai/specs/plans-executed/`
> - **Templates**: `~/.claude/templates/ai-spec/{spec.md, grilling.md}`
> - **V3.19' shared schema** (env-gated via `.envrc`): `spec_id` / `task_id` / `failure_taxonomy` / `context_manifest_hash`

---
```

The block coexists with your project constitution; no conflict.

### Mid-session refresh (already-running Claude Code / Codex CLI)

`~/.claude/` hooks are read fresh per-tool invocation, so **new hook behavior is active on the very next prompt** without restart. But the LLM context (always-loaded rules) is cached at `SessionStart` (per ADR-0008 / 0012):

| You want to refresh | Action | Side effect |
|---|---|---|
| Hook behavior only | none — automatic next turn | — |
| LLM-side rules (e.g., new R2 taxonomy) | type `/clear` in the session | session history compacts |
| P3 env vars in tool calls (`V3_SPEC_ID`, `V3_CTX_MANIFEST_HASH`) | exit + `source .envrc` + relaunch CC/Codex | session history lost |
| All of the above | exit + `source .envrc` + relaunch | clean cold start |

Recommended daily-driver: `/clear` after running `init-project.sh` from another terminal — covers 90% (P3 env vars defer to next session).

## 3. The 5-minute new-feature workflow

```bash
# 1. Bootstrap a spec from V3.19' templates
FEATURE=add-payment-retry
mkdir -p ".ai/specs/in-progress/${FEATURE}"
cp ~/.claude/templates/ai-spec/grilling.md ".ai/specs/in-progress/${FEATURE}/"
cp ~/.claude/templates/ai-spec/spec.md     ".ai/specs/in-progress/${FEATURE}/"

# 2. Tell Claude Code (one prompt is enough)
#    > "Please grill me on the spec for add-payment-retry feature, then fill EARS requirements."
#    Hook auto-injects [vcos-spec] pointer; Claude runs the 8-field interview.

# 3. After grilling, set V3_TASK_ID per task focus
export V3_TASK_ID=T-01

# 4. Every subsequent tool call writes evidence linked to this spec.
#    Check it:
jq -c '. | select(.spec_id != null)' .ai/evidence.jsonl | tail -3
```

## 4. Reading the Stop hook recap

After each rule-applied turn, you'll see an italic-gray line like:

```
⎿ Stop says: 🛡️ Scope rules V3 — Think-Before-Coding ✓, Deep-Diagnosis ✓, Surgical-Changes ✓, Karpathy ✓, Goal-Driven ✓
```

**Interpret it as a positive ledger** — the more ✓'s, the more V3 rules engaged this turn. **Zero indicators** (no recap line) means a trivial turn that did not need rule enforcement (Karpathy Simplicity — no noise for typos / formatting / chat).

For project-name dynamic prefix:
- `🛡️ <basename(cwd)> V3` is emitted via `basename "$cwd"` so every project gets its own label

## 5. Common-task playbooks

### A. "Make Claude verify a fact before stating it"

Just include `verify` or `check` in your prompt. The hook injects the evidence-required scaffold. Claude must:
1. Identify the exact claim
2. Identify the source/tool that can verify it (curl/Read/WebFetch/`gh`/`npm view`)
3. Run the tool
4. Cite the raw output
5. Only then state the claim

If Claude tries to assert without running the tool, the Stop gate (check 1 — fact firewall) **blocks the final answer**.

### B. "Make Claude give a deep root-cause analysis, not a surface patch"

Include `debug`, `root cause`, `why`, or `为什么`. The Stop gate (check 5 — debug ladder) **requires L0–L4 structure** in the answer: Evidence / Symptom / Root cause / Mechanism gap / Prevention. Missing any → blocked.

### C. "Make Claude refuse to claim completion without running tests"

The Stop gate (check 2 — completion claim) **blocks** any final answer containing `done` / `fixed` / `verified` / `working` / `tests passed` / `已完成` / `已修复` / `已验证` unless the evidence ledger contains a recent `claim_type:"test"` entry. You don't have to do anything — it's automatic.

### D. "Make Claude avoid persona prompting"

Just don't write `"you are a senior engineer"`. V3.19' added a 1-line ban in `core.md §2` based on Wharton GAIL 2025-12. Use **role + authority + checklist + output schema** instead:

```yaml
role: code-reviewer
authority: block merge on Blocking finding
checklist:
  - No new untested branch in src/payments/**
  - No public-API change without ADR link
output_schema: review-report-v1
```

### E. "Make Claude track failure categories in postmortems"

Reference the V3.19' R/Q/S taxonomy in L3 (mechanism gap):

```
L3 Mechanism gap: QUALITY-MISSING-EDGE-CASE — autonomous-loop entry was not covered by the keyword router
L4 Prevention: add fallback `else echo "[no-match silent]"` + unit case '$PROMPT="" → silent'
```

Full 14-class taxonomy (4 Reliability + 5 Quality + 5 Safety) lives in `~/.claude/rules/deep-diagnosis.md` appendix.

## 6. Observe + measure your usage

```bash
# Real-time routing stats (current session-style)
tail -100 ~/.claude/audit/user-prompt.log | awk -F'matched_index=' '{print $2}' | sort | uniq -c | sort -rn

# Which specs have evidence entries in this project?
jq -r 'select(.spec_id != null) | .spec_id' "$PWD/.ai/evidence.jsonl" | sort | uniq -c

# 7 / 30 / 90-day V3.19' usage report
bash ~/.claude/scripts/integration-usage-report.sh 7
bash ~/.claude/scripts/integration-usage-report.sh 30
bash ~/.claude/scripts/integration-usage-report.sh 90

# How often did R/Q/S taxonomy actually surface in conversations?
grep -rcE "RELIABILITY-|QUALITY-|SAFETY-" ~/.claude/sessions/*.jsonl 2>/dev/null | awk -F: '$2 > 0' | wc -l
```

**Health baselines** (ADR-0013 soft 30-day gate):
- Week 4: `bash integration-usage-report.sh 30` → ≥3 invocations per component = KEEP; 0 = MONITOR / REMOVE
- Maintainer (you) decides; the script never auto-deletes

## 7. Anti-patterns to avoid

| ❌ Anti-pattern | Why it hurts | ✅ Replacement |
|---|---|---|
| Saying "you are a senior X expert" | Wharton GAIL 2025-12: low-knowledge persona harms coding tasks | role + authority + checklist + output_schema |
| Asking Claude to fix without writing what's wrong | Stop hook check 5 will block surface fixes | include `debug`/`root cause` in prompt; let L0–L4 scaffold engage |
| Loading every component into every session | ETH 2602.11988: long always-on instructions degrade success rate | rely on keyword routing — components are signal-gated |
| Hardcoding `V3_SPEC_ID="S-some-spec"` in `.envrc` | Stale on feature rotation | use the `ls -dt` dynamic discovery template above |
| Tracking "looks good" without rubric | violates Karpathy Goal-Driven | translate to scorable rubric (see `~/.claude/templates/ai-spec/grilling.md` Step 3) |
| Running 30-day report every week | Noise, no signal | Week 4 / 8 / 12 (3 data points trend-suffice) |

## 8. When *not* to use V3 signals

- Trivial typo / formatting fix → don't add any signal verb (hook stays silent, zero overhead)
- Conversational Q&A → no signal needed
- Reading code / exploration → no signal needed

V3 is designed to **disappear** for low-stakes work. The signals only fire when the prompt explicitly invites them.

---

# 📖 Detailed usage guide

## Architecture (11 layers, top-down)

| Layer | Purpose | Component |
|---|---|---|
| L0 | Shared policy source | `~/.ai-policies/core.md` |
| L1 | User-level entry | `~/.claude/CLAUDE.md` (≤ 120 lines) + 18 modular rules |
| L2 | Per-prompt context injection | `user-prompt-policy.sh` (8 trigger patterns, folded V3.19' routing) |
| L3 | Tool evidence ledger | `post-tool-evidence.sh` → `{cwd}/.ai/evidence.jsonl` (+ V3.19' spec_id/task_id/context_manifest_hash) |
| L4 | Final answer hard gate | `stop-quality-gate.sh` (7 numbered quality checks + spec archive guard + retired-recap drift guard; recap emitter is non-blocking transparency) |
| L5 | User-level skills | 5 skills with progressive disclosure |
| L6 | Config integrity guard | `config-integrity-guard.sh` + `config-change-audit.sh` |
| L7 | Managed policy (optional, enterprise) | `/Library/Application Support/ClaudeCode/managed-settings.d/` |
| L8 | Project H10-H13 gates (per-project) | `gates/H*.py` (deterministic UI semantic gates) |
| L9 | Spec-Driven external memory | `<project>/.ai/specs/{in-progress,plans-executed}/` + V3.19' templates |
| L10 | User-visible banner / Stop recap (V3.10 → V3.18.x) | `session-start-policy.sh` + JSON `systemMessage` field |
| L11 | Reference-driven debug methodology (V3.11) | ADR-0005 |

See [`EVIDENCE-FIRST-OS-COMPLETE-SPEC.md`](EVIDENCE-FIRST-OS-COMPLETE-SPEC.md) for the full 22-section spec including ETH 2026 research grounding, Karpathy-aligned rule integration, Matt Pocock skill mapping, the V3.2 → V3.11 9-iteration retrospective, and V3.18.x → V3.19' arbitration trails.

🏛️ **Architecture governance track** (SoR spine, reverse-coverage gate, Wave-0 closure): see **[docs/governance/README.md](docs/governance/README.md)** — status board, read order, and how-to for new modules/docs.

## Per-component walkthrough

### V3 baseline (always-loaded)
- **Iron Law (L0)** — 5-step claim protocol, hedge-word firewall, L0–L4 diagnosis ladder, completion-claim gate, compaction resilience
- **Rules (L1)** — think-before-coding / simplicity-first / surgical-changes / deep-diagnosis / goal-driven / evidence-first / completion-gate / + others (coding-style, autonomous-mode, fail-loud, checkpoint-steps, etc.; V3.23 — testing/security/patterns process detail moved to on-demand playbooks; full list: `templates/claude/rules/`)

### V3.19' VCOS-v2 selective import (signal-gated; cost only when invoked)

| ID | Component | Trigger | Effect |
|---|---|---|---|
| P1 | EARS requirements template | `spec` / `需求` / `requirements` | Hook emits pointer to `~/.claude/templates/ai-spec/spec.md` — 5 EARS patterns (Ubiquitous / Event-driven / State-driven / Unwanted / Optional) |
| P2 | Persona-ban | always-loaded (1 line in core.md §2) | Discourages "you are senior X" prompts; recommends role+authority+checklist |
| P3 | Ledger 3 fields | env-gated via `.envrc` | `spec_id` / `task_id` / `context_manifest_hash` appended to evidence.jsonl entries when env vars present |
| R1 | Grilling 8-field intake | `spec` / `grilling` (shares P1 trigger) | Hook points to `~/.claude/templates/ai-spec/grilling.md` — Goal/Context/Users/Non-goals/Risks/Constraints/Done-when/Success-metric |
| R2 | 14-class R/Q/S taxonomy | passive (in `deep-diagnosis.md` appendix) | 4 Reliability + 5 Quality + 5 Safety failure categories for L3 mechanism-gap classification |
| — | Soft 30-day gate | `bash ~/.claude/scripts/integration-usage-report.sh N` | Maintainer report; no runtime self-mutation |

See [docs/adr/0013-v3-19-vcos-v2-selective-import.md](docs/adr/0013-v3-19-vcos-v2-selective-import.md) for the 2-round 3-视角 arbitration trail.

## Spec lifecycle (V3 §17)

```
.ai/specs/
├── in-progress/              # active work; .envrc auto-discovers most-recent
│   └── <feature>/
│       ├── grilling.md       # 8-field intake (filled first)
│       ├── spec.md           # EARS R-1...R-N + non-goals + success metrics
│       ├── plan.md           # 9-section plan (per VCOS-v2 §3.2)
│       └── tasks.md          # TDD red→green checklist
└── plans-executed/           # archived after ship; preserves provenance
    └── <feature>/...
```

Move spec on ship: `mv .ai/specs/in-progress/<feature> .ai/specs/plans-executed/`

## Evidence ledger schema (V3.19')

Each `.ai/evidence.jsonl` line:

```json
{
  "ts": "2026-05-19T05:03:36Z",
  "session_id": "abc-123",
  "cwd": "/path/to/project",
  "tool": "Bash",
  "claim_type": "test",        // auto: web|file|test|package|repo|unknown
  "raw_ref": "toolu_xxx",
  "spec_id": "v3-19-vcos-selective-import",       // V3.19' P3 (optional)
  "task_id": "T-06",                              // V3.19' P3 (optional)
  "context_manifest_hash": "ff81667"              // V3.19' P3 (optional; git short SHA)
}
```

Last 3 fields appear only when env vars are set (via `.envrc` or manual export).

---

# 🔍 Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| No `Stop says:` recap line | No V3 rule indicator detected in your turn | Add a signal verb (see §1) or accept silent (trivial turn) |
| Stop hook blocks "done" without test | check 2 — completion gate | Run `npm test` / `bash verify.sh` first, then state the completion |
| `V3_SPEC_ID=unset` | `.ai/specs/in-progress/` is empty | Create one: `mkdir -p .ai/specs/in-progress/my-feature && source .envrc` |
| Project docs drift | README / ARCHITECTURE / CHANGELOG / banner / CI disagree with hook SoT | Run `bash scripts/doctor.sh`; it is also part of `bash verify.sh` |
| Banner not visible after `/clear` | Plugin hook order or claude-mem absent | `tail -10 ~/.claude/audit/session-start.log` — confirm hook fired |
| Audit log spam | Default — every prompt classification logs once | `truncate -s 0 ~/.claude/audit/user-prompt.log` |

## Non-goals

- Not a new IDE, agent runtime, or autonomous coding product.
- Not a portable policy compiler until the Claude/Codex SoT is stable.
- Not compliance-grade claim/evidence attestation yet; the current ledger is a developer quality gate, not a regulated audit model.
- Not market-validated by public adoption while the repository remains private.

---

# 📁 Project structure

```
evidence-first-os/
├── README.md                            # this file
├── CLAUDE.md                            # project-level V3 pointer
├── .envrc                               # P3 env auto-export (direnv-compatible)
├── install.sh                           # one-click installer (merge-preserve default)
├── uninstall.sh                         # rollback (preserves backups)
├── verify.sh                            # §9 smoke test harness
├── LICENSE                              # MIT
├── CHANGELOG.md                         # V3.1 → current rollout history
├── EVIDENCE-FIRST-OS-COMPLETE-SPEC.md   # 22-section authoritative spec
├── templates/
│   ├── ai-policies/core.md              # L0 Iron Law (+ V3.19' persona ban)
│   ├── claude/
│   │   ├── CLAUDE.md                    # L1 user-level entry
│   │   ├── rules/                       # 18 modular rules (+ V3.19' R/Q/S appendix)
│   │   ├── playbooks/                   # V3.23 on-demand process manuals (+ profiles/ ×4)
│   │   ├── RULES-ARCHITECTURE.md        # V3.23 layered rules architecture SSOT
│   │   ├── hooks/                       # 8 Claude hook scripts (+ V3.19' folded routing)
│   │   ├── templates/
│   │   │   ├── banner-v3.txt            # V3.10 banner content
│   │   │   └── ai-spec/                 # V3.19' EARS + grilling templates
│   │   └── scripts/
│   │       └── integration-usage-report.sh   # V3.19' 30-day soft gate
│   ├── codex/                           # Codex parallel install (AGENTS.md + 3 hooks)
│   └── settings/                        # claude-hooks.json / codex-hooks.json templates
├── scripts/
│   └── merge-settings.py                # idempotent jq-style settings merger
├── docs/
│   ├── quickstart.md                    # copy-paste onboarding prompts
│   ├── ARCHITECTURE.md                  # detailed layer-by-layer walkthrough
│   ├── deployment-guide.md              # platform-specific notes
│   ├── adr/                             # ADR-0002 to ADR-0014 (architectural decisions)
│   └── archive/                         # V1/V2 HTML + V3 banner retrospective (frozen)
├── VCOS-v2-Release/                     # VCOS v2.0 source-of-record bundle (per ADR-0013)
└── .github/workflows/ci.yml             # GitHub Actions smoke test
```

# Project status (2026-05-23)

- **V3.22.0** — banner trim + active-rule overview + integrity repair track
- **13 ADRs** capturing architectural decisions through ADR-0013
- **11-layer defense-in-depth** + **7 numbered quality checks + spec archive guard + retired-recap drift guard** active
- **Current product wedge**: completion-claim gate for Claude Code and Codex; other platform exports are deferred until the SoT is stable

# License

MIT — see [LICENSE](LICENSE). Cite the spec and ETH Zurich 2026 paper if you use this work academically.

# Acknowledgements

- ETH Zurich + LogicStar.ai 2026 (arXiv:2602.11988) — empirical foundation
- Karpathy's 4 LLM coding principles
- Matt Pocock's skills ecosystem (`mattpocock/skills`)
- obra-superpowers `systematic-debugging` skill (preserved via ADR-0004)
- claude-mem (thedotmack) — reference implementation that enabled V3.10 root cause via direct jsonl diff (ADR-0005)
- VCOS v2.0 spec authors — selective-import source-of-record for V3.19' (ADR-0013)
- Wharton GAIL 2025-12 (arXiv:2512.05858) — persona-stuffing empirical critique
- METR 2025-07 (arXiv:2507.09089) — AI productivity reality check (-19% measured)
- DORA 2025 — "AI is an amplifier, not an equalizer"
