omc-os 0.3.0__tar.gz

omc_os-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lin-mouren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omc_os-0.3.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: omc-os
+Version: 0.3.0
+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"