@kodevibe/harness 0.11.1 → 0.11.3

package/README.ko.md

@@ -11,7 +11,7 @@
 
 > **AI 코딩 에이전트는 세션이 끝나면 모든 것을 잊습니다. kode:harness는 목표, 결정, 실패, 프로젝트 방향을 기억하게 합니다.**
 
-AI 코딩 에이전트를 위한 프로덕션급 가드레일. 컨텍스트 부패를 방지하고, 프로젝트 방향을 강제하며, 세션 간 상태를 유지합니다. **Copilot, Claude, Cursor, Codex, Windsurf, Gemini** 지원. 의존성 제로.
+AI 코딩 에이전트를 위한 pre-1.0 가드레일입니다. 실제 프로젝트 파일럿과 팀 사용을 기준으로 방향, proof, 세션 간 메모리를 유지합니다. 컨텍스트 부패를 방지하고, 프로젝트 방향을 강제하며, 세션 간 상태를 유지합니다. **Copilot, Claude, Cursor, Codex, Windsurf, Gemini** 지원. 의존성 제로.
 
 > **에코시스템 내 위치.** kode:harness는 **kode:vibe** 에코시스템의 *실행(execution)* 레이어입니다 — 계획 레이어(PRD / 아키텍처 / ARB)와 인프라 레이어(CI / 런타임) 사이에 위치하며, 코딩 중 AI의 방향을 잡아주는 역할을 합니다. 다른 레이어는 선택이며, kode:harness만 독립적으로 쓸 수 있습니다.
 
@@ -32,6 +32,8 @@ npx @kodevibe/harness init          # IDE 선택
 
 끝입니다. 이제 AI는 영속적인 메모리, 방향 가드레일, 자기 교정 루프를 갖게 됩니다.
 
+처음이라면 [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)부터 보세요. proof-first 흐름은 [docs/PROOF_LEDGER_WALKTHROUGH.md](docs/PROOF_LEDGER_WALKTHROUGH.md), 팀 도입은 [docs/TEAM_ONBOARDING.md](docs/TEAM_ONBOARDING.md), 설치/제거 안전 경계는 [docs/SAFETY_GUIDE.md](docs/SAFETY_GUIDE.md)에 정리했습니다.
+
 v0.11부터는 **Proof-First Enforcement**가 Common Mode Confidence Loop 위에 추가됩니다. pm은 실행 가능한 proof를 계획해야 하고, lead는 증거 없이 Story를 완료 처리하지 않으며, reviewer는 proof가 없거나 실패하면 커밋 안내 전에 멈추고, state-check는 Proof Ledger 누락을 점검합니다.
 
 <details>
@@ -170,6 +172,27 @@ npx @kodevibe/harness validate  # state 파일에 실제 내용 확인
 npx @kodevibe/harness uninstall --dry-run --ide vscode  # 안전 제거 미리보기
 ```
 
+소스 repo maintainer는 결정론 guard와 model-tier 증거 체크도 함께 실행할 수 있습니다:
+
+```bash
+npm run harness:check-pack
+npm run harness:guard:all
+npm run harness:guard:wrap-up -- --quiet
+npm run harness:state-sync
+npm run harness:dependency-scan
+npm run harness:llm-bench:smoke
+```
+
+릴리즈 증거로 인정하려면 예시 fixture 대신 실제 3개 이상 모델 tier의 sealed result를 `docs/llm-bench-results.json`에 기록한 뒤 실행하세요. 각 run은 `docs/llm-bench-scenarios.json`의 표준 시나리오를 사용해야 하며, `capturedAt`, 일치하는 `promptHash`, `outputHash` 또는 `transcriptHash`가 필요합니다.
+
+```bash
+npm run harness:llm-bench:export
+node scripts/llm-bench.js --collect-results --model-id local-small-2026-06-08 --tier constrained --outputs bench/r10/local-small-2026-06-08 --out docs/llm-bench-results.json --append
+npm run harness:llm-bench:real
+```
+
+전체 3-model 증거 생성 절차는 `docs/LLM_BENCH_GUIDE.md`를 참고하세요.
+
 ---
 
 ## 지원 IDE
@@ -329,6 +352,12 @@ npx @kodevibe/harness init --team
 
 ---
 
+## 문서
+
+패키지 사용자는 이 README에서 시작하면 됩니다. 저장소 maintainer는 GitHub 전용 [docs/wiki-index.md](https://github.com/AIDD-Projects/harness/blob/main/docs/wiki-index.md)를 source repo 문서 지도로 사용합니다. 기여 가이드, 아키텍처 노트, 릴리스 기록, local docs hub 경계를 연결하되, source repo 안에 active harness instruction을 다시 설치하지 않습니다.
+
+---
+
 ## 왜 만들었나
 
 기존 AI 코딩 프레임워크는 **AI가 무엇을 하는지** — 코드 생성, 테스트 실행, 배포에 집중합니다. 하지만 진짜 문제는 능력이 아닙니다. **방향**입니다.
@@ -380,7 +409,7 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 ## 로드맵
 
-kode:harness는 현재 **v0.11.1** — manifest 기반 안전 제거를 추가해 설치 흔적을 미리보기, 보존, 복원, purge 흐름으로 관리합니다. Common Mode의 proof-first 동작도 계속 강제합니다.
+kode:harness는 현재 **v0.11.2** — v0.11의 proof-first와 uninstall safety 기반 위에 deterministic source-repo guardrail과 manifest-sealed R10 model benchmark workflow를 추가했습니다.
 
 | 단계 | 버전 | 상태 | 초점 |
 |------|------|------|------|
@@ -395,7 +424,8 @@ kode:harness는 현재 **v0.11.1** — manifest 기반 안전 제거를 추가
 | **Drift Guard & Positioning** | v0.9.7 | ✅ 완료 | `harness/`↔`.github/` drift 가드, reviewer working-proof 게이트, kode:vibe 위치 안내, IDE 선택 가이드, project-brief 예시 |
 | **Confidence Loop** | v0.10.0 | ✅ 완료 | Goal Card, Quiet Navigator, Evidence-Gated Progress Board, Proof Ledger, QA/content 회귀 테스트 |
 | **Proof-First Enforcement** | v0.11.0 | ✅ 완료 | Mandatory Proof Plan, lead proof blocker, reviewer proof blocker, state-check Proof Ledger coverage |
-| **Uninstall Safety** | v0.11.1 | ✅ 현재 | Manifest 기반 uninstall, state 기본 보존, shared owner 복원, purge cleanup |
+| **Uninstall Safety** | v0.11.1 | ✅ 완료 | Manifest 기반 uninstall, state 기본 보존, shared owner 복원, purge cleanup |
+| **Deterministic Release Guard** | v0.11.2 | ✅ 현재 | R1-R10 guard scripts, package-boundary scan, dependency-map scan, R10 manifest-sealed bench workflow |
 | **Docs Bridge** | v0.11.1 | 🧪 Experimental | Project Docs Hub Index, docs-bridge 스킬, visibility 경계를 가진 로컬 docs hub 인덱스 |
 | **Safety & Branding** | v0.9.6 | ✅ 완료 | init overwrite 백업, 배포 파일 pm 네이밍 정리, LICENSE 브랜딩 정리 |
 | **Validation** | v1.0 | 🔜 다음 | 실사용 검증, 사용자 피드백 수집 |

package/README.md

@@ -11,7 +11,7 @@
 
 > **Your AI coding agent forgets everything between sessions. kode:harness makes it remember — goals, decisions, failures, and project direction.**
 
-Production-grade guardrails for AI coding agents. Prevents context rot, enforces project direction, and persists state across sessions. Works with **Copilot, Claude, Cursor, Codex, Windsurf, and Gemini**. Zero dependencies.
+Pre-1.0 guardrails for AI coding agents, designed for real project pilots and teams that need direction, proof, and memory across sessions. Prevents context rot, enforces project direction, and persists state across sessions. Works with **Copilot, Claude, Cursor, Codex, Windsurf, and Gemini**. Zero dependencies.
 
 > **Where this fits.** kode:harness is the *execution* layer of the **kode:vibe** ecosystem — it sits between a planning layer (PRD / architecture / ARB) and an infrastructure layer (CI / runtime). kode:harness keeps the AI on direction while you code; the other layers are optional. You can use kode:harness alone.
 
@@ -32,6 +32,8 @@ npx @kodevibe/harness init          # pick your IDE
 
 That's it. Your AI now has persistent memory, direction guardrails, and self-correction loops.
 
+New to kode:harness? Start with [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md), then read [docs/PROOF_LEDGER_WALKTHROUGH.md](docs/PROOF_LEDGER_WALKTHROUGH.md) for the proof-first loop. Teams should also read [docs/TEAM_ONBOARDING.md](docs/TEAM_ONBOARDING.md). For install and uninstall trust boundaries, see [docs/SAFETY_GUIDE.md](docs/SAFETY_GUIDE.md).
+
 v0.11 adds **Proof-First Enforcement** on top of the Common Mode Confidence Loop: pm must define runnable proof, lead cannot mark a Story done without passing evidence, reviewer blocks commit guidance when proof is missing or failing, and state-check audits Proof Ledger coverage.
 
 <details>
@@ -182,6 +184,27 @@ npx @kodevibe/harness validate  # verify state files have real content
 npx @kodevibe/harness uninstall --dry-run --ide vscode  # preview safe removal
 ```
 
+Source repo maintainers can also run the deterministic guard and model-tier evidence checks:
+
+```bash
+npm run harness:check-pack
+npm run harness:guard:all
+npm run harness:guard:wrap-up -- --quiet
+npm run harness:state-sync
+npm run harness:dependency-scan
+npm run harness:llm-bench:smoke
+```
+
+For release evidence, replace the example fixture with sealed results from at least three real model tiers. Each run must use the standard scenarios in `docs/llm-bench-scenarios.json` and include `capturedAt`, a matching `promptHash`, and `outputHash` or `transcriptHash`.
+
+```bash
+npm run harness:llm-bench:export
+node scripts/llm-bench.js --collect-results --model-id local-small-2026-06-08 --tier constrained --outputs bench/r10/local-small-2026-06-08 --out docs/llm-bench-results.json --append
+npm run harness:llm-bench:real
+```
+
+See `docs/LLM_BENCH_GUIDE.md` for the full three-model evidence workflow.
+
 ## Supported IDEs
 
 Not sure which to pick? Use the IDE you already code in — each install path is generated from the same `harness/` source, so the underlying skills/agents are identical:
@@ -315,7 +338,7 @@ These 11 rules are enforced across all skills and agents. They form the quality
 
 ## Documentation
 
-See [docs/reference.md](docs/reference.md) for detailed descriptions of every skill, agent, rule, and state file.
+Package users can start with this README. Repository maintainers can use the GitHub-only [docs/wiki-index.md](https://github.com/AIDD-Projects/harness/blob/main/docs/wiki-index.md) as the source repo documentation map; it links the contribution guide, architecture notes, release history, and local docs hub boundaries without installing active harness instructions into this repo.
 
 ## Why We Built This
 
@@ -366,7 +389,7 @@ It adds a Project Docs Hub Index to `project-brief.md` with each local source, r
 
 ## Roadmap
 
-kode:harness is at **v0.11.1** — adds manifest-based safe uninstall so generated IDE files can be previewed, preserved, restored, or purged intentionally. Common Mode proof-first behavior remains enforceable.
+kode:harness is at **v0.11.3** — adds R15 experiment hardening for section integrity, Wave Scope drift, and filter coverage honesty on top of the v0.11 proof-first and deterministic release guard foundation.
 
 | Phase | Version | Status | Focus |
 |---|---|---|---|
@@ -381,7 +404,9 @@ kode:harness is at **v0.11.1** — adds manifest-based safe uninstall so generat
 | **Drift Guard & Positioning** | v0.9.7 | ✅ Done | `harness/`↔`.github/` drift detector, reviewer working-proof gate, kode:vibe positioning, IDE selection guide, project-brief example |
 | **Confidence Loop** | v0.10.0 | ✅ Done | Goal Card, Quiet Navigator, Evidence-Gated Progress Board, Proof Ledger, QA/content regression tests |
 | **Proof-First Enforcement** | v0.11.0 | ✅ Complete | Mandatory Proof Plan, lead proof blockers, reviewer proof blockers, state-check Proof Ledger coverage |
-| **Uninstall Safety** | v0.11.1 | ✅ Current | Manifest-based uninstall, default state preservation, shared owner restore, purge cleanup |
+| **Uninstall Safety** | v0.11.1 | ✅ Complete | Manifest-based uninstall, default state preservation, shared owner restore, purge cleanup |
+| **Deterministic Release Guard** | v0.11.2 | ✅ Complete | R1-R10 guard scripts, package-boundary scan, dependency-map scan, R10 manifest-sealed bench workflow |
+| **Experiment Hardening** | v0.11.3 | ✅ Current | R15 Recent Changes integrity, Wave Scope boundary drift checks, enum/filter coverage honesty, R15 bench scenarios |
 | **Docs Bridge** | v0.11.1 | 🧪 Experimental | Project Docs Hub Index, docs-bridge skill, local docs hub index with visibility boundaries |
 | **Safety & Branding** | v0.9.6 | ✅ Done | init overwrite backups, shipped pm naming cleanup, LICENSE branding cleanup |
 | **Validation** | v1.0 | 🔜 Next | Real-world project adoption, user feedback collection |

package/harness/agents/lead.md

@@ -104,15 +104,18 @@ After every status check, recommend the next action based on current context:
 
 **Request: "story done" / "S{N}-{M} done"**
 1. Read the Story's Proof Plan and current Evidence-Gated Progress Board row.
-2. Require proof before marking done:
+2. Read `## Story Contracts` rows for the Story. Every row must be proven before Done.
+3. Require proof before marking done:
    - Passing proof → set state to `Proven`, update Story status to `✅ done`, append Proof Ledger / Evidence Summary row.
    - Missing proof → keep state `Proof Pending`, output `[BLOCKER: PROOF_MISSING]`, and do not advance to the next Story.
    - Failing proof → keep state `Implementing`, output `[BLOCKER: PROOF_FAILING]`, and fix within current Story.
-3. Add completion record to "Recent Changes" section only after passing proof.
-4. **Commit/Push check**: If changes are uncommitted, remind:
+   - Unproven contract → keep state `Proof Pending`, output `[BLOCKER: CONTRACT_NOT_PROVEN]`, and update the contract Evidence target.
+4. If proof passes, update Story Contract Proof Status to `✅ pass` / `proven` with evidence. Never leave `needs-user-confirmation` on a done Story.
+5. Add completion record to "Recent Changes" section only after passing proof.
+6. **Commit/Push check**: If changes are uncommitted, remind:
    - "⚠️ S{N}-{M} 완료 — 커밋하셨나요? `git add <files> && git commit -m \"S{N}-{M}: {description}\"`"
    - Team mode: Also remind to push — "팀원에게 공유하려면 `git push origin {branch}` 실행"
-5. Guide to next Story only after proof passes.
+7. Guide to next Story only after proof passes.
 
 **Request: "new story" / "next task"**
 1. Find next `todo` Story in docs/project-state.md
@@ -147,7 +150,12 @@ When invoked after pm approval, verify that pm wrote state files correctly:
 
 When a Story contains multiple Tasks/Waves (from breakdown):
 - Guide implementation **one Wave at a time** (not one file at a time, not all at once)
+- For every Wave, print a compact **Wave Scope** before implementation:
+  `Wave {N} Scope: allowed files = <files>; expected proof = <command/manual observation>`
 - After each Wave is implemented, **run tests or smoke proof** to verify the Wave is clean before proceeding
+- After each Wave, compare changed files against the Wave Scope:
+  - Only allowed files changed → continue.
+  - Extra files changed → output `[SCOPE-DRIFT: WAVE_BOUNDARY]`, record the extra files, and ask whether the Wave should be collapsed/approved before proceeding.
 - Record a mini Proof Ledger row inline: Evidence, Result, Command / Observation
 - Only after verification passes, prompt: "Wave {N} 완료 (tests pass). Wave {N+1}로 넘어갈까요?"
 - If tests fail → output `[BLOCKER: WAVE_PROOF_FAILING]`, fix within the current Wave, and do NOT advance.

package/harness/agents/pm.md

@@ -70,7 +70,7 @@ Apply these insights when creating the implementation plan. If the memory file i
 <!-- CREW_MODE_END -->
 
 1. `docs/project-brief.md`의 Goals + `docs/dependency-map.md`의 현재 모듈 구조를 읽는다
-2. Feature Roadmap **초안** 생성:
+2. Roadmap 초안 생성:
    ```
    ## Feature Roadmap
    ### Phase 1 — Core (Goal 달성 필수)
@@ -78,9 +78,8 @@ Apply these insights when creating the implementation plan. If the memory file i
    ### Phase 2 — Enhancement (사용성/완성도)
    - [ ] F-002: ...
    ```
-3. 사용자에게 초안 제시: **"이 Feature Roadmap을 검토하고, 추가/삭제/순서 변경을 알려주세요."**
-4. 사용자 교정을 반영한 최종 Roadmap을 `docs/project-brief.md`에 `## Feature Roadmap` 섹션으로 기록한다
-5. Feature Roadmap이 확정되면 아래 "For New Feature" 절차로 진행한다
+3. 교정 후 `docs/project-brief.md`에 기록한다
+4. 확정되면 "For New Feature"로 진행한다
 
 ### For New Feature
 
@@ -132,10 +131,11 @@ Apply these insights when creating the implementation plan. If the memory file i
 10. Run **check-impact** skill for each existing module being modified (pm calls both skills independently — breakdown does NOT invoke check-impact internally. Ordering: breakdown first → register modules → check-impact second.)
 11. Check `docs/failure-patterns.md` for relevant past mistakes
 12. Produce a **Goal Card** (6 lines max) and implementation plan.
-13. Produce a **Proof Plan** per Story: exact test/smoke command or checklist; never TBD. No path → add Story 0: set up test/smoke proof. Any `TBD`/blank → `[ERROR: PROOF_PLAN_UNDEFINED]` and STOP before state writes.
-14. **Wait for Plan Confirmation** (see Plan Confirmation Gate below) — do NOT write state files yet
-15. **After user approves** → Update `docs/project-state.md` with the new Story
-16. **After user approves** → Update `docs/features.md` with the new feature entry
+13. Produce a **Proof Plan** per Story: exact test/smoke/manual proof; never TBD. No path → add Story 0: set up test/smoke proof. Blank → `[ERROR: PROOF_PLAN_UNDEFINED]` and STOP.
+14. Produce **Story Contracts**: Done-blocking field/API/UI/ARB assertions.
+15. **Wait for Plan Confirmation** (see Plan Confirmation Gate below) — do NOT write state files yet
+16. **After user approves** → Update `docs/project-state.md` with the new Story and Story Contract rows
+17. **After user approves** → Update `docs/features.md` with the new feature entry
 
 State writes (Steps 15-16) execute ONLY after user approval. Rejected plans never touch state.
 
@@ -185,8 +185,10 @@ After user approves the plan, perform all writes before 🧭:
    - If no Sprint exists, create Sprint 1 with theme
    - Add Story rows to the Story Status table (status = `⬜ todo`)
    - Each Story: ID (S{N}-{M}), Title, Status, Scope (files/modules), Proof Plan
+   - Add `## Story Contracts` rows. Initial status: `⬜ not proven` or `needs-user-confirmation`.
 <!-- CREW_MODE_START -->
    - If crew-driven, include FR reference
+   - Convert FR/ARB criteria naming fields, API contracts, invariants, proof gates, or UI requirements.
 <!-- CREW_MODE_END -->
    - Update Quick Summary section
 
@@ -201,10 +203,11 @@ After user approves the plan, perform all writes before 🧭:
    - ARB Fail Resolution: fill Story column with mapped Story IDs
 <!-- CREW_MODE_END -->
 
-**Completion Check**: Verify:
-- [ ] features.md has new feature row(s)
-- [ ] project-state.md has Story rows with `⬜ todo` status
-- [ ] dependency-map.md has new module rows (if plan introduces new modules)
+**Completion Check**:
+- [ ] features.md new row(s)
+- [ ] project-state.md Story rows with `⬜ todo`
+- [ ] project-state.md Story Contract rows or "none identified"
+- [ ] dependency-map.md new module rows (if any)
 <!-- CREW_MODE_START -->
 - [ ] project-brief.md Validation Tracker updated (if 🟣 pipeline)
 <!-- CREW_MODE_END -->
@@ -247,6 +250,11 @@ After the Post-Approval state writes complete, run the `state-check` skill:
 | S{N}-0 | Proof setup, if needed | `npm test` / `npm run smoke` / manual checklist |
 | S{N}-{M} | Tests / smoke / manual | exact command/checklist; never TBD |
 
+### Story Contract Plan
+| Story | Contract | Required Assertion | Initial Proof Status | Evidence Target |
+|-------|----------|--------------------|----------------------|-----------------|
+| S{N}-{M} | Field/API/domain/UI contract | assertion to prove before Done | ⬜ not proven | unit/API/smoke/manual |
+
 ### Implementation Plan
 [Output from breakdown skill]
 

package/harness/agents/reviewer.md

@@ -57,6 +57,7 @@ Changed file list (user-provided or from `git diff --name-only`)
 **Step 1: Identify Change Scope**
 - Run `git diff --cached --stat` or `git diff --stat` to see changed files
 - Compare against current Story scope in docs/project-state.md
+- If lead/pm named a Wave Scope, changed files outside that Wave are `[SCOPE-DRIFT: WAVE_BOUNDARY]`. Do not revert automatically; require user approval or a state note explaining the collapsed wave.
 
 **Step 2: Architecture Rule Check**
 - [ ] No imports from infrastructure in domain layer
@@ -64,6 +65,15 @@ Changed file list (user-provided or from `git diff --name-only`)
 - [ ] Constructor parameters match actual source (FP-002)
 - [ ] **Common First (Iron Law #9)**: No crew-specific logic outside crew marker blocks. All features must work without crew artifacts.
 
+**Step 2.2: Acceptance Contract Gate**
+
+If `docs/project-state.md` has `## Story Contracts` rows for the Story:
+1. Review each row before code-quality review.
+2. Compare assertion vs code, tests, API/UI output, and proof.
+3. Output **Story Contract Review**: `Contract | Status | Evidence`.
+4. `FAIL`, `NOT_PROVEN`, blank Proof Status, or `needs-user-confirmation` blocks `DONE` and commit guidance.
+5. Wrong-contract tests fail.
+
 <!-- CREW_MODE_START -->
 **Step 2.5: CI Standards Compliance (🟣 Pipeline only)**
 
@@ -79,11 +89,11 @@ Changed file list (user-provided or from `git diff --name-only`)
 1. Check if `docs/project-brief.md` has a `## CI Artifact Index` section (or `.harness/ci-index.md` exists). If neither → skip this step.
 2. Read the project's primary language/build tool from `docs/project-brief.md` Key Technical Decisions.
 3. Match the language/build tool to a row in the CI Artifact Index → get the reference URL and Key Constraints.
-4. Surface the reference in review output under a `### CI Standards Compliance` section:
+4. Surface the reference under `### CI Standards Compliance`:
    - Reference URL (the indexed guide)
-   - Key Constraints listed in the index (echoed back so the user does not need to re-read the guide)
-   - `[CI-STANDARD]` flag if any obvious mismatch is detected against a listed constraint (best-effort LLM judgment based only on the changed files)
-5. **Warning only — do NOT block commit**. The user (or a human reviewer) decides whether the changes meet company standards. The reviewer agent never asserts compliance; it only points to the authoritative guide.
+   - Key Constraints from the index
+   - `[CI-STANDARD]` if changed files obviously mismatch a listed constraint
+5. **Warning only — do NOT block commit**. Point to the guide; do not assert compliance.
 
 If neither `## CI Artifact Index` nor `.harness/ci-index.md` is present → skip this step entirely (also true for 🟢/🔵/🔴 pipelines).
 <!-- CREW_MODE_END -->
@@ -92,10 +102,12 @@ If neither `## CI Artifact Index` nor `.harness/ci-index.md` is present → skip
 - [ ] Interface changes have synchronized mocks (FP-001)
 - [ ] New features have tests
 - [ ] Existing tests pass
+- [ ] **Enum/filter coverage**: If the Story adds finite values (e.g. `normal/watch/breached`), tests must cover every value at the claimed boundary (domain/API/UI) or mark untested boundaries as partial. Claiming full API coverage while HTTP tests exercise one value → `[ACCEPTANCE-GAP: FILTER_COVERAGE]`.
 
-**Verification is a gate, not a suggestion.** Before continuing to Step 4, the reviewer must include concrete working proof:
-- Run the project's test/verification command when available (for example `npm test`, `pnpm test`, `pytest`, `go test ./...`, or the command recorded in docs/project-brief.md / package scripts).
-- If the change is user-facing and tests do not exercise the behavior, include a minimal smoke proof (command, URL, screenshot/manual action, or observed output).
+**Verification is a gate.** Before Step 4, include concrete working proof:
+- Run the project test/verification command (`npm test`, `pytest`, `go test ./...`, or recorded proof command).
+- If user-facing behavior is untested, include smoke proof (command, URL, screenshot/manual action, or observed output).
+- UI/manual proof needs artifact/checklist or URL + exact counts/elements.
 - If any existing test fails → output `[BLOCKER: TESTS_FAILING]`. STOP before Step 4.
 - If a Proof Plan command cannot run → output `[BLOCKER: PROOF_COMMAND_INVALID]` with the command. STOP.
 - If test files exist but no test command exists → output `[BLOCKER: NO_TEST_COMMAND]`. STOP.
@@ -114,6 +126,7 @@ If state files are in scope, write/request Proof Ledger / Evidence Summary immed
 - [ ] No credentials, .env, or temp files in staging (FP-004)
 - [ ] No hardcoded API keys or passwords
 - [ ] No injection vulnerabilities (SQL, XSS)
+- [ ] Evaluator artifacts require approval (`harness-owner: evaluator` → `harness-edit-approved`)
 
 **Step 5: Failure Pattern Cross-Check**
 - Compare current changes against all FP-NNN items in docs/failure-patterns.md
@@ -124,28 +137,9 @@ If state files are in scope, write/request Proof Ledger / Evidence Summary immed
 
 If `docs/project-brief.md` contains a `## Crew Artifact Index` table with entries:
 
-1. **ARB Fail Item Check**:
-   - Read Validation Tracker → ARB Fail Resolution section
-   - If the current Story addresses a Fail item (has `[ARB-FAIL]` prefix):
-     - Read the relevant section in the ARB checklist (path from Artifact Index)
-     - Verify implementation matches the recommended action
-     - If not → flag as `[ARB-COMPLIANCE]` in output
-   - **Indirect resolution check**: Even if the Story does NOT have `[ARB-FAIL]` prefix, scan the changed files against ARB Fail items. If a change resolves or partially addresses a Fail item (e.g., fixing a security vulnerability flagged by ARB), flag as `[ARB-INDIRECT]` in output with a recommendation to update the Validation Tracker.
-
-2. **NFR Spot Check** (lightweight — check only NFRs relevant to changed files):
-   - Read PRD's non-functional requirements section (path from Artifact Index)
-   - Check ONLY the NFRs related to changed code:
-     - Performance-related change? → Check performance NFRs
-     - Security-related change? → Check security NFRs
-     - API change? → Check scalability/reliability NFRs
-   - Flag violations as `[NFR-GAP]` in output
-   - Note: This is a best-effort check by the LLM, not a guarantee of 100% detection
-
-3. **FR Acceptance Criteria Check**:
-   - If the current Story has `[FR-NNN]` reference:
-     - Read the corresponding FR acceptance criteria from PRD (path from Artifact Index)
-     - Verify tests cover the acceptance criteria
-     - If missing → flag as `[ACCEPTANCE-GAP]` in output
+1. **ARB Fail Item Check**: If the Story has `[ARB-FAIL]`, verify the related ARB checklist recommendation. If changed files indirectly resolve a Fail item, flag `[ARB-INDIRECT]` and recommend Tracker update.
+2. **NFR Spot Check**: Read only NFRs relevant to changed files (security/performance/API/reliability). Violations → `[NFR-GAP]`.
+3. **FR Acceptance Criteria Check**: If the Story references `FR-NNN`, verify tests/proof cover the PRD acceptance criteria. Missing coverage → `[ACCEPTANCE-GAP]`.
 
 All flags (`[ARB-COMPLIANCE]`, `[ARB-INDIRECT]`, `[NFR-GAP]`, `[ACCEPTANCE-GAP]`) are warnings, not blockers. Include them in the review output under a new "### Crew Artifact Compliance" section.
 
@@ -171,6 +165,7 @@ Verify that state file updates actually happened. **Run the `state-check` skill
 
 After running state-check, also verify:
 - [ ] **docs/project-state.md**: If stories were worked on, is Quick Summary current? Are story statuses updated?
+- [ ] **docs/project-state.md section integrity**: `## Recent Changes` must not contain proof/evidence headings or UI checklist bullets. If it does, flag `[STATE-AUDIT: SECTION_CORRUPTION]` and fix before DONE.
 - [ ] **docs/features.md**: If new features were added, are they registered? If features were completed, is status updated?
 - [ ] **Cross-check features ↔ stories**: If a feature status is `✅ done` in features.md, verify all related stories in project-state.md are also `done`. If stories are `done` but their feature is still `🔄 in-progress`, flag as `[STATE-AUDIT]`.
 - [ ] **FR Coverage validation**: For the Story being reviewed, check if it implements a feature (FR-NNN reference in Story name, or changes to files listed in features.md Key Files):
@@ -223,6 +218,7 @@ If review is BLOCKED → do NOT suggest commit. Fix first.
 
 ### Passed Items
 - Architecture rules: ✅
+- Story Contract Review: ✅ / ❌ / ⚠️ (include table when contracts exist)
 - Test integrity: ✅ / ⚠️ (detail)
 - Working proof: command/evidence + PASS result
 - Proof Ledger: compact table with evidence, result, and command/observation
@@ -276,6 +272,7 @@ After review completes, always append a 🧭 block based on the outcome:
 | All checks pass, more stories remain | Commit → `lead` — "커밋 후 다음 Story는?" |
 | All checks pass, all stories done | Commit → `wrap-up` — "커밋 후 세션을 마무리해줘" |
 | STATE-AUDIT flags found | Two valid paths: (1) `wrap-up` now → "지금 state 파일을 정리해줘" or (2) `lead` → continue coding, resolve at session end |
+| FILTER_COVERAGE or SECTION_CORRUPTION found | [Fix] — "테스트/상태 구조 지적사항을 수정하세요. 완료 후 다시 reviewer 호출" |
 | Security/architecture issues blocking | [Fix] — "리뷰 지적사항을 수정하세요. 완료 후 **새 프롬프트**에서 다시 `@reviewer` 호출" |
 
 Example 🧭 block for passing review:

package/harness/project-state.md

@@ -61,6 +61,17 @@
    | S1-1 | First usable result | Proof Pending | npm test | - | tests not run |
 -->
 
+## Story Contracts
+
+<!-- Semantic acceptance contracts for active Stories.
+   Keep rows short and testable. Every row for a ✅ done Story must be proven.
+   Use this to prevent semantic drift such as implementing `risk` when the contract requires `slaRisk`.
+
+   | Story | Contract | Required Assertion | Proof Status | Evidence |
+   |-------|----------|--------------------|--------------|----------|
+   | S1-1 | Field contract | Public response exposes `expectedField`, not `wrongField` | ⬜ not proven | unit/API/UI assertion |
+-->
+
 ## Proof Ledger
 
 <!-- One line per completed proof. Do not paste long logs.

package/harness/skills/breakdown.md

@@ -78,6 +78,7 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 - Each task should be completable in one session
 - Every task must include its test files
 - Implementation and tests belong in the same Wave whenever possible. Do not defer tests to a later Wave unless the proof harness itself is the earlier Wave.
+- Each Story/Wave must preserve the Story Contracts defined by pm. If a task changes a public field, API response, domain invariant, UI label, persistence behavior, or ARB control, name the affected contract and the assertion that will prove it.
 - New modules MUST be registered in docs/dependency-map.md (Iron Law #6) — the breakdown OUTPUT section lists these registrations, and pm (or the user, if invoked directly) is responsible for executing the actual state file writes
 - If a task exceeds Story scope, stop and report to user
 
@@ -87,7 +88,7 @@ After completing the breakdown, update these files in the same session:
 
 - [ ] **docs/dependency-map.md**: Register all NEW_MODULE entries. Update "Depends On" / "Depended By" for INTERFACE_CHANGE entries.
 - [ ] **docs/features.md**: Add a new row for the feature with Status `🔧 active`, Key Files from Wave tasks, and Test Files.
-- [ ] **docs/project-state.md**: Add Stories to the Story Status table for each Wave.
+- [ ] **docs/project-state.md**: Add Stories to the Story Status table for each Wave and add/update `## Story Contracts` rows for semantic assertions that must be proven before Done.
 
 ### 🧭 Navigation — After Feature Breakdown
 

package/harness/skills/pr-review.md

@@ -40,6 +40,17 @@ Unlike the `reviewer` agent (which reviews your own changes pre-commit with full
 
 ### Step 4: Code Quality
 
+Before ordinary code-quality comments, run the **Acceptance Contract Gate**:
+
+1. Read `docs/project-state.md` → `## Story Contracts`.
+2. If the PR's Story has contract rows, verify each required assertion against the diff, tests, and proof evidence.
+3. Produce:
+   | Contract | Status | Evidence |
+   |----------|--------|----------|
+   | Field/API/domain/UI contract | PASS / FAIL / NOT_PROVEN | exact file/test/proof evidence |
+4. Any `FAIL`, `NOT_PROVEN`, blank Proof Status, or `needs-user-confirmation` → `REQUEST_CHANGES`.
+5. Green tests are insufficient if they assert the wrong semantic contract.
+
 Run through these checks for each changed file:
 
 - [ ] Architecture rules respected (no layer violations — check docs/dependency-map.md)
@@ -50,6 +61,7 @@ Run through these checks for each changed file:
 - [ ] No duplicated logic that should be extracted to a shared module
 - [ ] No circular imports (verify against docs/dependency-map.md)
 - [ ] Naming conventions follow project standards (per project-brief.md → Key Technical Decisions)
+- [ ] Evaluator/run-card/scorecard artifacts are not rewritten unless explicitly user-approved
 
 ### Step 5: Test Coverage
 
@@ -57,6 +69,7 @@ Run through these checks for each changed file:
 - [ ] Modified code has updated tests
 - [ ] No `.only` or `.skip` left in test files
 - [ ] Interface changes have synchronized mocks (Iron Law #1)
+- [ ] UI/manual proof is durable: artifact/checklist, or URL plus exact observed UI counts/elements
 
 ### Step 6: State File Compliance
 
@@ -85,6 +98,9 @@ Run through these checks for each changed file:
 - [issue 1]
 - [issue 2]
 
+### Story Contract Review
+- PASS / FAIL / NOT_PROVEN rows, when `## Story Contracts` exists
+
 ### Test Coverage: ✅ Sufficient / ⚠️ Gaps found
 [list of gaps if any]
 

package/harness/skills/setup.md

@@ -189,6 +189,7 @@ Using data from Phase 1 + Phase 2, fill the following files:
 - Quick Summary: filled with current project state
 - Sprint 1 stories: based on what setup discovered
 - Module Registry: summary from docs/dependency-map.md
+- Story Contracts: keep the section. Add compact `⬜ not proven` rows for explicit field/API/invariant/UI/ARB contracts; if unsure, write `needs-user-confirmation`.
 
 **docs/failure-patterns.md**:
 - Keep FP-001 through FP-004 as templates (Frequency: 0)

package/harness/skills/state-check.md

@@ -131,6 +131,49 @@ Outcomes:
 - Missing local path, blank required column, invalid vocabulary, local machine path leakage, or restricted row with external target → WARN
 - No `Project Docs Hub Index` section or no real rows → skip; this project may not use docs-bridge
 
+### Check 9: Story Contract Coverage
+
+1. Read `docs/project-state.md` (or `.harness/project-state.md` in Team mode).
+2. If any Story is marked `✅ done`, inspect `## Story Contracts`.
+3. Outcomes:
+   - Done Story has no `## Story Contracts` section → WARN: `[WARN] Story {S-N-M} done but no Story Contracts section — add semantic contract rows for new work`
+   - Done Story has no rows in `## Story Contracts` → WARN: `[WARN] Story {S-N-M} done but has no Story Contract rows`
+   - Story Contracts table is missing required columns `Story`, `Contract`, or `Proof Status` → FAIL
+   - Done Story has any contract row with blank / `⬜ not proven` / `NOT_PROVEN` / `FAIL` / `needs-user-confirmation` → FAIL
+   - Done Story has all rows `✅ pass`, `proven`, `verified`, or equivalent → PASS
+   - In-progress Story has unproven contracts → PASS; proof pending is normal
+
+This is the semantic acceptance gate. It exists to catch drift such as "contract requires `slaRisk`, implementation/tests/UI use `risk`" before DONE.
+
+### Check 10: Durable Smoke Evidence
+
+For each `✅ done` Story, any passing Proof Ledger row whose Evidence says `UI`, `browser`, `smoke`, or `manual` must include durable proof:
+- screenshot/trace/video/Playwright/Cypress artifact, or
+- checklist row, or
+- URL plus exact observed UI counts/elements.
+
+Vague rows like `UI manual | pass | checked browser` → FAIL.
+
+### Check 11: Evaluator Artifact Protection
+
+If changed files include `experiment/kode-harness-scorecard.md`, `experiment/run-card.md`, `experiment/evaluator-*.md`, or `docs/evaluator-*.md`, WARN unless explicitly requested by the user. If the file has `<!-- harness-owner: evaluator -->`, FAIL unless it also has `<!-- harness-edit-approved: <reason> -->`.
+
+### Check 12: Scope Split Approval
+
+If `docs/project-brief.md` maps one FR/KPI/ARB row to multiple Story IDs, require `Scope split approved: <reason>` or `<!-- harness-scope-split-approved: ... -->`. Without approval → FAIL.
+
+### Check 13: Recent Changes Section Integrity
+
+`docs/project-state.md` must keep session changelog entries separate from proof/evidence sections.
+
+1. Read `## Recent Changes`.
+2. FAIL if the section contains nested headings such as `### Scenario`, `### Color Coding`, or `### Conclusion`.
+3. FAIL if the section contains UI/proof checklist bullets such as dropdown/column/color-coding/evidence details.
+4. Valid Recent Changes entries should be compact changelog rows, preferably:
+   `- YYYY-MM-DD S{N}-{M}: {what changed} (STATUS: DONE)`
+
+This catches wrap-up corruption where `## Recent Changes` is inserted in the middle of `FR-008 Durable UI Evidence` and steals the remaining proof content.
+
 ## Output Format
 
 ```
@@ -158,6 +201,18 @@ Outcomes:
 ### Check 8: Project Docs Hub Index
 - {N} rows checked / {M} missing paths / {K} visibility warnings / skipped if unused
 
+### Check 9: Story Contract Coverage
+- {N} done Stories checked / {M} missing contract rows / {K} unproven contracts
+
+### Check 10: Durable Smoke Evidence
+- {N} UI/manual proof rows checked / {M} vague rows
+
+### Check 12: Scope Split Approval
+- {N} split tracker rows checked / {M} missing approval
+
+### Check 13: Recent Changes Section Integrity
+- Recent Changes contains only changelog entries / {M} misplaced evidence lines
+
 <!-- CREW_MODE_START -->
 ### Check 6: Validation Tracker (🟣)
 - {N} FR references checked / {M} drifted