@kodevibe/harness 0.11.2 → 0.11.4

package/README.ko.md

@@ -409,7 +409,7 @@ Bootstrap이 `docs/crew/`, `docs/PM/`, `docs/Analyst/`, `docs/ARB/`에서 crew
 
 ## 로드맵
 
-kode:harness는 현재 **v0.11.2** — v0.11의 proof-first와 uninstall safety 기반 위에 deterministic source-repo guardrail과 manifest-sealed R10 model benchmark workflow를 추가했습니다.
+kode:harness는 현재 **v0.11.4** — v0.11 proof-first 기반 위에 R16 recovery hardening(거짓 clean state-check claim, surface-specific Story Contract, reviewer dependency evidence, dirty wrap-up guard)을 추가했습니다.
 
 | 단계 | 버전 | 상태 | 초점 |
 |------|------|------|------|
@@ -425,7 +425,9 @@ kode:harness는 현재 **v0.11.2** — v0.11의 proof-first와 uninstall safety
 | **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 |
-| **Deterministic Release Guard** | v0.11.2 | ✅ 현재 | R1-R10 guard scripts, package-boundary scan, dependency-map scan, R10 manifest-sealed bench workflow |
+| **Deterministic Release Guard** | v0.11.2 | ✅ 완료 | R1-R10 guard scripts, package-boundary scan, dependency-map scan, R10 manifest-sealed bench workflow |
+| **Experiment Hardening** | v0.11.3 | ✅ 완료 | R15 Recent Changes integrity, Wave Scope boundary drift checks, enum/filter coverage honesty |
+| **Recovery Hardening** | v0.11.4 | ✅ 현재 | R16 false PASS claim guard, surface-specific Story Contract checks, reviewer dependency evidence, dirty wrap-up guard |
 | **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

@@ -389,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.2** — adds deterministic source-repo guardrails and a manifest-sealed R10 model benchmark workflow on top of the v0.11 proof-first and uninstall safety foundation.
+kode:harness is at **v0.11.4** — adds R16 recovery hardening for false clean state-check claims, surface-specific Story Contracts, reviewer dependency evidence, and dirty wrap-up truthfulness on top of the v0.11 proof-first and deterministic release guard foundation.
 
 | Phase | Version | Status | Focus |
 |---|---|---|---|
@@ -405,7 +405,9 @@ kode:harness is at **v0.11.2** — adds deterministic source-repo guardrails and
 | **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 | ✅ Complete | Manifest-based uninstall, default state preservation, shared owner restore, purge cleanup |
-| **Deterministic Release Guard** | v0.11.2 | ✅ Current | R1-R10 guard scripts, package-boundary scan, dependency-map scan, R10 manifest-sealed bench workflow |
+| **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 | ✅ Complete | R15 Recent Changes integrity, Wave Scope boundary drift checks, enum/filter coverage honesty, R15 bench scenarios |
+| **Recovery Hardening** | v0.11.4 | ✅ Current | R16 false PASS claim guard, surface-specific Story Contract checks, reviewer dependency evidence, dirty wrap-up guard |
 | **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,8 +150,14 @@ 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
+- For semantic contracts with "always/every/all/항상", include public surfaces in the Wave proof target (for example: `create/list/get/resolve` return paths). A test that covers only one return path is partial proof.
 - 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.
 - This prevents context overload from modifying too many modules simultaneously

package/harness/agents/pm.md

@@ -42,24 +42,22 @@ One of:
 
 ### Step 0: State File Readiness
 
-Before proceeding, verify that required state files have content (not just TODO placeholders):
+Before proceeding, verify required state files have content:
 - `docs/project-brief.md` — Must have Vision and Goals filled
 - `docs/features.md` — Must have at least one feature row
 - `docs/dependency-map.md` — Must have at least one module row (for existing projects)
 
-If ALL files are empty/placeholder-only → **Stop and run the `setup` skill first.** Report: "State files are empty. Running setup to onboard this project."
-If `docs/project-brief.md` alone is empty → **Stop.** Without Vision/Goals, pm cannot check Non-Goals or provide direction guard. Run `setup` first.
+If ALL files are empty/placeholder-only → **Stop and run `setup` first.**
+If `docs/project-brief.md` alone is empty → **Stop.** Without Vision/Goals, pm cannot provide direction guard.
 
 > Step 0 runs BEFORE Step 1. If Step 0 stops (empty brief), Step 1 never executes. When Step 0 passes, Step 1 reads the now-confirmed non-empty project-brief.md for detailed content.
 
 ### Step 0.5: Load Agent Memory
 
 Read `docs/agent-memory/pm.md` for past learnings:
-- Estimation accuracy from previous sprints (did Wave estimates match reality?)
-- Architecture patterns that worked or failed in this project
-- Repeated planning mistakes to avoid
+- estimation accuracy, architecture patterns, repeated planning mistakes
 
-Apply these insights when creating the implementation plan. If the memory file is empty or contains only placeholders, skip this step.
+Apply these when planning. If memory is empty/placeholders only, skip.
 
 ### Step 0.7: Roadmap Draft
 
@@ -70,7 +68,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 +76,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 +129,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 +183,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 +201,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 +248,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

@@ -36,17 +36,15 @@ Before reviewing, verify that required state files exist and are not empty:
 - `docs/failure-patterns.md` — Must exist (needed for Step 5 cross-check)
 - `docs/project-state.md` — Must have current Sprint info (needed for scope check)
 
-If state files are empty/placeholder-only → Warn: "State files are not filled. Review will proceed but scope check and failure pattern cross-check will be limited. Consider running `setup` skill."
-If `docs/failure-patterns.md` is empty, FP-cross-check (Step 5) will be skipped. This increases risk of recurring bugs.
+If state files are empty/placeholder-only → warn that scope and FP checks are limited; suggest `setup`.
+If `docs/failure-patterns.md` is empty, skip FP cross-check.
 
 ### Step 0.5: Load Agent Memory
 
 Read `docs/agent-memory/reviewer.md` for past learnings:
-- Frequently missed review items in this project
-- Common code patterns that caused issues
-- Review statistics (pass rate, common failure categories)
+- missed review items, risky code patterns, review statistics
 
-Pay extra attention to items flagged in past reviews. If the memory file is empty or contains only placeholders, skip this step.
+If memory is empty/placeholders only, skip.
 
 ### Input
 
@@ -57,6 +55,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 +63,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. Compare each row against code, tests, API/UI, and proof.
+2. Output **Story Contract Review**: `Contract | Status | Evidence`.
+3. `FAIL`, `NOT_PROVEN`, blank Proof Status, or `needs-user-confirmation` blocks `DONE`.
+4. Wrong-contract tests fail.
+5. **R16 surface rule**: `always/every/all/항상` contracts must name/prove relevant public paths, e.g. `create/list/get/resolve`. Missing surfaces → `[CONTRACT-GAP: SURFACE_UNSPECIFIED]`.
+
 <!-- CREW_MODE_START -->
 **Step 2.5: CI Standards Compliance (🟣 Pipeline only)**
 
@@ -79,11 +87,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 +100,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.
@@ -111,9 +121,9 @@ Record the result as a **Proof Ledger** entry. Keep it short:
 If state files are in scope, write/request Proof Ledger / Evidence Summary immediately after proof passes.
 
 **Step 4: Security Check (secure skill)**
-- [ ] No credentials, .env, or temp files in staging (FP-004)
-- [ ] No hardcoded API keys or passwords
-- [ ] No injection vulnerabilities (SQL, XSS)
+- [ ] No credentials, hardcoded secrets, injection risks, or temp files
+- [ ] Evaluator artifacts require approval (`harness-owner: evaluator` → `harness-edit-approved`)
+- [ ] **R16 scope/dependency evidence**: For "no external deps/auth/persistence", cite `package.json` and actual `require`/`import` lines. Do not name absent modules; hallucinated deps block `DONE`.
 
 **Step 5: Failure Pattern Cross-Check**
 - Compare current changes against all FP-NNN items in docs/failure-patterns.md
@@ -124,28 +134,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 +162,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):
@@ -181,6 +173,8 @@ After running state-check, also verify:
 - [ ] **docs/failure-patterns.md**: If a bug was fixed that matched a pattern, was frequency incremented?
 - [ ] **docs/project-brief.md**: If a technology or architectural decision was made, is it in Decision Log?
 - [ ] **docs/agent-memory/*.md**: If an agent (reviewer/pm/lead) was used this session, was its memory updated by the wrap-up skill?
+- [ ] **R16 guard evidence**: Run/request the guard command and include its exact summary. Any guard error forbids `DONE`/`DONE_WITH_CONCERNS`:
+  `HARNESS_GUARD_ROOT="$PWD" node /path/to/k-harness/scripts/harness-guard.js docs/project-state.md`
 
 For each missing update: flag as `[STATE-AUDIT]` in the output and provide the exact update that should be made.
 **Severity**:
@@ -210,6 +204,8 @@ When review result is DONE or DONE_WITH_CONCERNS (no blockers):
 
 If review is BLOCKED → do NOT suggest commit. Fix first.
 
+Before commit guidance, run `git status --short`; do not imply a commit exists unless `git log --oneline -1` confirms it.
+
 ### Output Format
 
 ```
@@ -223,6 +219,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 +273,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

@@ -61,10 +61,8 @@ Use `--overwrite` only to reset corrupted state after backup; then rerun setup t
      - `sprint-manager.md` → should be renamed to `lead.md`
      - `navigator.md` → should be renamed to `lead.md`
      - `builder.md` → should be renamed to `pm.md`
-   - For each legacy file found:
-     - If the new name does NOT exist → offer to rename: `mv {legacy}.md {new}.md` (preserves history)
-     - If BOTH exist → ask the user which to keep, or merge contents into the new name and delete the legacy
-   - Confirm with the user before renaming. Record the migration in `docs/project-state.md` Recent Changes.
+   - For each legacy file: offer rename if the new name is absent; if both exist, ask whether to keep or merge.
+   - Confirm before renaming and record the migration in Recent Changes.
 
 **Do NOT modify any code files in this phase.**
 
@@ -189,6 +187,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,61 @@ 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.
+
+### Check 14: Self-Verify Claim Integrity (R16)
+
+If `docs/project-state.md` or the caller output claims `state-check PASS`, `0 FAIL`, `0 WARN`, or `guard no issues`, the claim must be backed by deterministic evidence:
+
+1. Prefer running the installed guard command:
+   `HARNESS_GUARD_ROOT="$PWD" node /path/to/k-harness/scripts/harness-guard.js docs/project-state.md`
+2. If CLI execution is unavailable, do not claim `0 FAIL, 0 WARN`; say `manual state-check only`.
+3. FAIL if any markdown/state/contract/handoff/env-seal issue is visible while the file claims clean self-verify.
+4. FAIL if the guard output is summarized but not shown.
+
+This catches reports such as "state-check PASS: 0 FAIL, 0 WARN" when a Proof Ledger table is malformed or Environment Seal is missing.
+
 ## Output Format
 
 ```
@@ -158,6 +213,22 @@ 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
+
+### Check 14: Self-Verify Claim Integrity
+- Guard output: shown / missing
+- Clean PASS claim matches deterministic result: yes/no
+
 <!-- CREW_MODE_START -->
 ### Check 6: Validation Tracker (🟣)
 - {N} FR references checked / {M} drifted
@@ -197,7 +268,7 @@ When invoked by another agent (pm/reviewer/wrap-up), control returns to the call
 
 - Do NOT invent data. Read the files and report exactly what you find.
 - Do NOT modify state files in this skill — diagnosis only. Caller decides remediation.
-- Do NOT run shell scripts. All checks are markdown-described file reads + comparisons.
+- Do NOT invent deterministic results. If a guard CLI is available, run it; otherwise mark clean PASS claims as manual-only, not `0 FAIL, 0 WARN`.
 - If a check cannot be performed (e.g., `docs/` missing entirely), report it as FAIL and stop — further checks are meaningless.
 
 ## Anti-patterns