omc-os 0.3.1

OMC external-driver front door — goal -> dry-run composition plan over the harness modules (Evidence-First agent OS).

Evidence-First OS for AI Coding Agents

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

🧩 Consuming the VCOS runtime in your own project? See 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 — 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

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 @imports 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 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:

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 ~/.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 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):

> **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

# 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:

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

# 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 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 — 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 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:

{
  "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. 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"