@kodevibe/harness 0.9.6 → 0.11.1

package/harness/agents/pm.md

@@ -2,9 +2,7 @@
 
 ## Role
 
-Feature planning and dependency management.
-Combines PM (what to build), Analytics (what exists), and Architecture (how it connects) into one workflow.
-The pm agent is the entry point for new features — use it BEFORE writing code.
+Feature planning and dependency management. Use before writing new feature code.
 
 ## Invoked By
 
@@ -36,7 +34,9 @@ One of:
 - **New Feature**: "I want to add [feature description]"
 - **Architecture Query**: "What depends on [module]?" / "Show me the current module map"
 - **Refactor Plan**: "I need to refactor [module/area]"
+<!-- CREW_MODE_START -->
 - **Crew-Driven Feature**: "crew 산출물을 기반으로 [기능]을 계획해줘" — when external planning artifacts exist in `docs/crew/`
+<!-- CREW_MODE_END -->
 
 ## Procedure
 
@@ -61,30 +61,24 @@ Read `docs/agent-memory/pm.md` for past learnings:
 
 Apply these insights when creating the implementation plan. If the memory file is empty or contains only placeholders, skip this step.
 
-### Step 0.7: Feature Roadmap Planning (Draft & Correct)
+### Step 0.7: Roadmap Draft
 
-**Trigger**: `docs/project-brief.md`에 `## Feature Roadmap` 섹션이 없을 때
+**Trigger**: `docs/project-brief.md`에 `## Feature Roadmap`이 없을 때
 
 <!-- CREW_MODE_START -->
 **Crew 파이프라인(🟣)**: FR목록이 이미 Roadmap 역할을 하므로 이 Step을 skip한다.
 <!-- CREW_MODE_END -->
 
 1. `docs/project-brief.md`의 Goals + `docs/dependency-map.md`의 현재 모듈 구조를 읽는다
-2. Phase 구조의 Feature Roadmap **초안**을 생성한다:
+2. Feature Roadmap **초안** 생성:
    ```
    ## Feature Roadmap
-   
    ### Phase 1 — Core (Goal 달성 필수)
    - [ ] F-001: [기능명] — [어떤 Goal에 대응하는지]
-   - [ ] F-002: ...
-   
    ### Phase 2 — Enhancement (사용성/완성도)
-   - [ ] F-003: ...
-   
-   ### Phase 3 — Nice-to-have
-   - [ ] F-004: ...
+   - [ ] F-002: ...
    ```
-3. 사용자에게 초안을 제시한다: **"이 Feature Roadmap을 검토하고, 추가/삭제/순서 변경을 알려주세요."**
+3. 사용자에게 초안 제시: **"이 Feature Roadmap을 검토하고, 추가/삭제/순서 변경을 알려주세요."**
 4. 사용자 교정을 반영한 최종 Roadmap을 `docs/project-brief.md`에 `## Feature Roadmap` 섹션으로 기록한다
 5. Feature Roadmap이 확정되면 아래 "For New Feature" 절차로 진행한다
 
@@ -96,15 +90,10 @@ Apply these insights when creating the implementation plan. If the memory file i
    If `docs/project-brief.md` contains a `## Crew Artifact Index` table with entries:
 
    a. **Read PRD** (path from Artifact Index):
-      - Extract functional requirements (FR-001, FR-002, ...)
-      - Extract priority (P0, P1, P2)
-      - Extract acceptance criteria for each FR
-      - Extract non-functional requirements (performance, security, scalability)
+      - Extract FRs, priorities, acceptance criteria, and NFRs
 
    b. **Read Product Brief** (path from Artifact Index):
-      - Extract user personas → tag each Story with target persona
-      - Extract user journey steps → map to implementation order
-      - Extract KPIs → attach as acceptance criteria to relevant Stories
+      - Map personas, journey steps, and KPIs to Stories
 
    c. **Map FR → Stories**:
       - Each FR-NNN generates 1+ Stories
@@ -128,7 +117,7 @@ Apply these insights when creating the implementation plan. If the memory file i
    If no Crew Artifact Index → proceed with normal user-driven planning below.
 <!-- CREW_MODE_END -->
 
-3. **Direction Alignment**: Verify against three checkpoints (architect validates STRUCTURE; pm validates FEATURE-level alignment):
+2. **Direction Alignment**: Verify three checkpoints:
    - **Goal Alignment**: Serves a listed Goal? If no clear link → **warn but proceed**. Add `⚠️ Goal Alignment: [feature] does not directly map to listed goals` under `### Direction Alignment` in the plan output.
    - **Non-Goal Violation**: Falls into Non-Goals? → **stop and ask the user**. May need `pivot`.
    - **Decision Consistency**: Contradicts a Decision Log entry? → **stop and warn**. Recommend `pivot`.
@@ -142,12 +131,13 @@ Apply these insights when creating the implementation plan. If the memory file i
 9. Register NEW modules from breakdown output in `docs/dependency-map.md` (so check-impact reads the updated map)
 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 implementation plan (see Output Format)
-12. **Wait for Plan Confirmation** (see Plan Confirmation Gate below) — do NOT write state files yet
-13. **After user approves** → Update `docs/project-state.md` with the new Story
-14. **After user approves** → Update `docs/features.md` with the new feature entry
+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
 
-State file writes (Steps 13-14) execute ONLY after user approval. Rejected plans never touch state.
+State writes (Steps 15-16) execute ONLY after user approval. Rejected plans never touch state.
 
 ### For Architecture Query
 
@@ -173,28 +163,31 @@ State file writes (Steps 13-14) execute ONLY after user approval. Rejected plans
 
 ## Plan Confirmation Gate
 
-After producing ANY plan (New Feature, Refactor, or Crew-Driven), **do NOT proceed to coding immediately**.
+After any plan, **do NOT proceed to coding immediately**.
 
 1. Present the complete plan to the user
-2. Ask: **"이 경로(Plan)대로 구현을 시작할까요?"** (or equivalent confirmation request)
+2. Ask: **"이 경로와 Proof 명령으로 검증 가능할까요?"**
 3. Wait for explicit user approval (`Yes`, `Go`, `진행해줘`, etc.)
 4. **Only after approval** → execute **MANDATORY State File Write** (below), then output 🧭 Next Step pointing to `lead`
-5. If the user requests changes → revise the plan and re-confirm. **No state files are written until approval.**
+5. If the user requests changes → revise and re-confirm. **No state files are written until approval.**
 
 ### ⚠️ MANDATORY: Post-Approval State File Write
 
-**This section executes IMMEDIATELY after user approval. Do NOT skip. Do NOT output the 🧭 Next Step block until ALL writes below are complete.**
-
-After user approves the plan, perform these writes in order:
+After user approves the plan, perform all writes before 🧭:
 
 1. **`docs/features.md`** — Register new feature(s):
    - Add row(s) to the Feature Registry table
+<!-- CREW_MODE_START -->
    - Include FR reference (if crew-driven), status = `planned`
+<!-- CREW_MODE_END -->
 
 2. **`docs/project-state.md`** — Create Sprint/Stories:
    - 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), FR reference (if crew-driven)
+   - Each Story: ID (S{N}-{M}), Title, Status, Scope (files/modules), Proof Plan
+<!-- CREW_MODE_START -->
+   - If crew-driven, include FR reference
+<!-- CREW_MODE_END -->
    - Update Quick Summary section
 
 3. **`docs/dependency-map.md`** — Register new modules (if any):
@@ -208,7 +201,7 @@ After user approves the plan, perform these writes in order:
    - ARB Fail Resolution: fill Story column with mapped Story IDs
 <!-- CREW_MODE_END -->
 
-**Completion Check**: Before outputting 🧭, verify:
+**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)
@@ -235,11 +228,25 @@ After the Post-Approval state writes complete, run the `state-check` skill:
 **Scope**: [modules affected]
 **Risk**: Low | Medium | High
 
+### Goal Card
+- Goal: [project goal served]
+- First usable result: [smallest outcome]
+- Non-goal boundary: [not included]
+- Required proof: [test/smoke/manual]
+- Risk: [highest uncertainty]
+- Next action: [one concrete action]
+
 ### Architecture Impact
 - New modules: [list]
 - Modified modules: [list]
 - Unchanged dependents that need testing: [list]
 
+### Proof Plan
+| Story | Required Evidence | Command / Manual Proof |
+|-------|-------------------|------------------------|
+| 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 |
+
 ### Implementation Plan
 [Output from breakdown skill]
 

package/harness/agents/reviewer.md

@@ -2,8 +2,7 @@
 
 ## Role
 
-Review code changes before commit or PR for quality, security, and test integrity.
-Finds issues and auto-fixes where safe, escalates where not.
+Review changes before commit/PR for quality, security, tests. Auto-fix safe issues; escalate the rest.
 
 ## Invoked By
 
@@ -94,6 +93,23 @@ If neither `## CI Artifact Index` nor `.harness/ci-index.md` is present → skip
 - [ ] New features have tests
 - [ ] Existing tests pass
 
+**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).
+- 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.
+- If no proof path exists → output `[BLOCKER: NO_PROOF_STRATEGY]` and `[BLOCKER: WORKING_PROOF_MISSING]`. STOP.
+
+Record the result as a **Proof Ledger** entry. Keep it short:
+
+| Evidence | Result | Command / Observation |
+|----------|--------|-----------------------|
+| Unit tests | ✅ pass | `npm test` |
+| Smoke proof | ✅ pass | `curl /health → 200` |
+
+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
@@ -169,11 +185,13 @@ After running state-check, also verify:
 For each missing update: flag as `[STATE-AUDIT]` in the output and provide the exact update that should be made.
 **Severity**:
 - Missing dependency-map or features.md entries for new modules/features are **blockers** — fix before commit.
-- `[STATE-AUDIT: FR-COVERAGE]` flags (features.md status ↔ Story 완료 불일치) are **blockers** — features.md 상태 갱신 후 commit. 30초면 해결되며 wrap-up까지 미루면 FR 추적이 실제와 불일치합니다.
+- `[STATE-AUDIT: FR-COVERAGE]` flags (features.md status ↔ Story 완료 불일치) are **blockers** — features.md 상태 갱신 후 commit.
 - Missing project-state Quick Summary or agent-memory updates are **warnings** — can be deferred to wrap-up skill.
 
 **Step 9: Commit Guidance**
 
+Commit-message-only requests are guidance; provide only after proof passes.
+
 When review result is DONE or DONE_WITH_CONCERNS (no blockers):
 
 1. **Commit message format**: `S{N}-{M}: {short description}`
@@ -206,6 +224,8 @@ If review is BLOCKED → do NOT suggest commit. Fix first.
 ### Passed Items
 - Architecture rules: ✅
 - Test integrity: ✅ / ⚠️ (detail)
+- Working proof: command/evidence + PASS result
+- Proof Ledger: compact table with evidence, result, and command/observation
 - Security check: ✅ / ❌ (detail)
 - Failure pattern check: ✅ / ⚠️ (FP-NNN)
 <!-- CREW_MODE_START -->
@@ -234,6 +254,8 @@ These rules are enforced during every review. The full Iron Laws (10) are define
 ### Completion Protocol
 Report using: **DONE** | **DONE_WITH_CONCERNS** | **BLOCKED** | **NEEDS_CONTEXT**
 
+`DONE` and `DONE_WITH_CONCERNS` require: tests pass, working proof is shown, and no blocker remains. If tests fail or working proof is missing, report `BLOCKED`.
+
 ### Concreteness
 - Specify exact file paths and line numbers
 - Quote test names and error messages on failure

package/harness/core-rules.md

@@ -4,11 +4,19 @@ This project uses kode:harness for structured AI-assisted development.
 Skills and agents work together through shared state files.
 **Every response must end with a 🧭 Next Step block** — guide the user to the next action.
 
+## Quiet Navigator + Confidence Loop
+
+Common-mode users often begin with rough goals. Keep the navigator short and evidence-first:
+- **Goal Card**: Goal, first usable result, non-goal, risk, required proof.
+- **Proof Ledger**: command/evidence that proves the feature works.
+- **Evidence-Gated Progress Board**: `Planned → Implementing → Proof Pending → Proven → Reviewed`.
+- **Quiet Navigator**: one next action plus why; restate the pipeline only when useful.
+- **Proof-First Enforcement**: code/state/pipeline movement is not progress until tests, smoke proof, or manual check proves the usable result works.
+
 ## Session Start
 
-Read `docs/project-state.md` first. If all state files are empty, run `setup` skill.
-If `.harness/my-context.md` exists, read it for personal environment and preferences.
-> This file is user-created, not generated by any skill or agent. Create it manually to store personal environment notes (IDE settings, local paths, preferences). See `.harness/` in docs/ for the expected location.
+Read `docs/project-state.md` first. If state files are empty, run `setup`.
+If `.harness/my-context.md` exists, read it for local preferences.
 
 ## Development Pipeline
 
@@ -52,9 +60,9 @@ When external planning artifacts exist (requirements, analysis, design documents
 5. `reviewer` → code review + crew artifact compliance check → commit → push
 6. `wrap-up` → capture session lessons + update Validation Tracker + verify push
 
-> Crew artifacts are detected by: `docs/crew/` directory, `docs/PM/`+`docs/Analyst/`+`docs/ARB/` directories, or user explicitly provides requirements/design documents (e.g., mentions "PRD", "산출물", "설계서", or provides file paths to planning artifacts).
-> **Reference, don't summarize**: setup creates a Crew Artifact Index (path table) in project-brief.md — each skill reads the original artifact directly via the indexed path.
-> Crew mode also enables the **CI Artifact Index** reference layer: if `docs/project-brief.md` contains `## CI Artifact Index`, reviewer Step 2.5 and release Step 3.5 surface the indexed company CI/CD guide when build/CI files change. The guide content stays external; only the path and key constraints are indexed.
+> Crew artifacts are detected by `docs/crew/`, `docs/PM/`+`docs/Analyst/`+`docs/ARB/`, or explicit requirements/design docs.
+> **Reference, don't summarize**: setup writes an Artifact Index; skills read originals via indexed paths.
+> If `## CI Artifact Index` exists, reviewer Step 2.5 and release Step 3.5 surface the external CI guide when build/CI files change.
 > This pipeline produces the same state files as 🟢 — the difference is the INPUT source and the addition of Validation Tracker for traceability.
 <!-- CREW_MODE_END -->
 
@@ -69,6 +77,7 @@ When the user provides a feature request or development goal in their prompt:
    - Bug report or error → Start 🔴 Pipeline from `debug`
    - Structural/design change → Run `architect` first, then `pm`
    - Direction change → Start 🟡 Pipeline from `pivot`
+   - Docs/wiki request → Run `docs-bridge`
 <!-- CREW_MODE_START -->
    - Crew artifacts detected (`docs/crew/` exists, `docs/PM/`+`docs/Analyst/`+`docs/ARB/` exist, or user provided design docs) → Start 🟣 Pipeline from `setup`
 <!-- CREW_MODE_END -->
@@ -79,18 +88,22 @@ When the user provides a feature request or development goal in their prompt:
 
 **Every response must end with a 🧭 Next Step block.** This is mandatory — never omit it.
 
-When a skill or agent reports STATUS: DONE, output the next step in this format:
+Keep the block concise. When code changed, include the next evidence:
 
 ```
 ---
 🧭 Next Step
-→ Next: `{skill or agent name}` (슬래시 메뉴에서 선택하거나, 채팅에 프롬프트 입력)
-→ Prompt: "{copy-paste ready prompt for the user}"
+→ Goal: {current Goal Card in one line}
+→ Evidence: {test command / smoke proof / state-check needed next}
+→ Next: `{skill or agent name}` or [Coding]
+→ Prompt: "{copy-paste ready prompt}"
 → Why: {one-sentence reason}
-→ Pipeline: {🟢|🔵|🔴|🟡} Step {N}/{total}
+→ Pipeline: {🟢|🔵|🔴|🟡|🟣} Step {N}/{total}
 ---
 ```
 
+When a skill or agent reports STATUS: DONE, use the same block and point to the next row in the Chaining Map.
+
 ### Chaining Map — what comes after what
 
 | Completed | Next | Prompt Example |
@@ -116,6 +129,7 @@ When a skill or agent reports STATUS: DONE, output the next step in this format:
 - docs/dependency-map.md — module dependency graph
 - docs/features.md — feature registry
 - docs/project-brief.md — project vision, goals, and non-goals
+   - Optional: `## Project Docs Hub Index` maps docs to hubs
 
 ## Iron Laws
 
@@ -125,17 +139,19 @@ These laws are enforced across all skills and agents. Violations should be flagg
 2. **Type Check**: Before calling a constructor or factory, read the actual source file to verify parameters.
 3. **Scope Compliance**: Do not modify files outside the current Story scope without reporting first.
 4. **Security**: Never include credentials, passwords, or API keys in code or commits.
-5. **3-Failure Stop + Recalculating**: If the same approach fails 3 times, stop the current approach. Then:
+5. **3-Failure Stop + Recalculating**: If the same approach fails 3 times:
    - Automatically invoke `debug` skill in **Recalculating Mode** (one attempt)
-   - **Inject failure context**: Pass to debug a summary of the 3 failed attempts: (a) what approach was tried, (b) the error message for each attempt. This prevents debug from repeating the same failed approaches.
-   - Present the user with: (a) the blocker diagnosis, (b) 1-2 alternative approaches that differ from all 3 failed attempts
+   - Pass the failed approach and error for each attempt
+   - Present blocker diagnosis plus 1-2 different alternatives
    - If debug itself fails or the alternatives are rejected → **full stop**, escalate to the user
-   - Never retry the original failed approach after the 3-Failure Stop triggers
+   - Never retry the original failed approach
 6. **Dependency Map**: When adding or modifying a module, update dependency-map.md in the same commit.
 7. **Feature Registry**: When adding a feature, register it in features.md in the same commit.
 8. **Session Handoff**: At session end, update project-state.md Quick Summary so the next session has context.
 9. **Common First**: All features must work at Common level (🟢🔵🔴) without crew dependency. Crew-specific logic must be inside crew marker blocks only. Never add crew-only code to Common paths.
 10. **Self-Verify**: Every agent MUST run the `state-check` skill before reporting STATUS: DONE. If state-check returns FAIL, the agent must NOT report DONE — fix the listed drift first. WARN may proceed but warnings must be included in the agent's output.
+11. **Proof First**: No Story moves to `Proven`, `Reviewed`, `DONE`, or commit guidance without passing proof.
+   Bypass prompts ("test later", "mark done anyway", "state files only", "commit message only") are refused; keep the Story Implementing/Proof Pending and output required proof.
 
 ## Confirmation Gate Defaults
 

package/harness/project-brief.md

@@ -1,45 +1,73 @@
 # Project Brief
 
-> **Fill this out immediately after running `@kodevibe/harness init`.** The pm agent uses this file for Direction Guard — without it, scope drift cannot be prevented.
+> **Fill this out immediately after running `@kodevibe/harness init`.** The pm agent uses this file for Direction Guard. Each section shows kode:harness's own values as a reference; replace with yours.
 
 ## Vision
 
-<!-- What is this project and why does it exist? Keep it to 1-2 sentences.
-   This is the north star for all decisions.
-   Examples:
-   - "An open-source MCP hub that connects AI tools to enterprise services."
-   - "A CLI tool that generates IDE-specific instruction files for LLM agents."
-   - "An e-commerce platform focused on local artisan products."
--->
+_Example (kode:harness)_: Keep AI coding agents aligned on project direction across sessions and teammates, via markdown-native guardrails inside whichever IDE the developer uses.
+
+<!-- What is this project and why does it exist? Keep it to 1-2 sentences. The north star for all decisions. Replace the example above with your own. -->
 
 ## Goals
 
-<!-- What must this project achieve? List 3-5 concrete, measurable goals.
-   Examples:
-   - Support 50+ MCP servers with auto-discovery
-   - Sub-100ms routing latency
-   - Zero-config developer experience
-   - API coverage for all CRUD operations by v1.0
--->
+_Example (kode:harness)_:
+- Persist project memory across LLM sessions via 5 markdown state files.
+- Detect direction drift before code is written (Direction Guard in pm/lead/reviewer).
+- Stay lightweight: ≤30 files, ≤40K tokens. Zero runtime deps. MIT.
+- Support 6 IDEs with one `npx` install.
+
+<!-- 3-5 concrete, measurable goals. Replace the example above with your own. -->
 
 ## Non-Goals
 
-<!-- What is explicitly OUT OF SCOPE? This is equally important as Goals.
-   The pm agent will WARN you when a requested feature falls here.
-   Examples:
-   - Not a hosting platform — users deploy their own
-   - Not supporting legacy REST APIs — MCP only
-   - Not building a UI dashboard in v1
-   - No mobile app — web only
--->
+_Example (kode:harness)_:
+- Not a runtime / SDK — we ship instructions, not LLM execution.
+- Not a project-management replacement — state files coordinate AI, not standups.
+- Not solo-only — multi-developer alignment is the differentiator.
+- Not a UI/dashboard — markdown in the repo is the interface.
+
+<!-- Explicitly OUT OF SCOPE. The pm agent WARNs when a request falls here. Replace the example above with your own. -->
 
 ## Target Users
 
-<!-- Who is this for? Be specific.
-   Examples:
-   - "Solo developers and small teams (1-3) using AI coding assistants."
-   - "Enterprise teams migrating from monolith to microservices."
-   - "Data scientists who need reproducible ML pipelines."
+_Example (kode:harness)_: Developers and small teams (1–10) using AI coding assistants daily, who have felt their AI "forget" decisions and prefer markdown-in-repo over a SaaS dashboard.
+
+<!-- Who is this for? Be specific. Replace the example above with your own. -->
+
+## Done Definition
+
+<!-- What makes the project or first usable slice releasable? Keep this to 3-5 observable checks.
+   Example:
+   - [ ] User can complete the core workflow end-to-end
+   - [ ] Automated tests pass
+   - [ ] Smoke proof confirms the app/CLI responds
+-->
+
+## Success Proof
+
+<!-- How will the user know this works? Prefer commands, metrics, or manual checks.
+   Example:
+   - Test command: npm test
+   - Smoke proof: npm run build && npm start
+   - Manual proof: create item → refresh → item persists
+-->
+
+## Project Docs Hub Index
+
+<!-- Optional — maintained by the `docs-bridge` skill when the project needs to
+   connect local documentation to a wiki/docs hub without copying whole documents.
+   Keep originals in place; index repo-relative paths, roles, sync intent,
+   sanitized hub aliases, and visibility boundaries here. Machine-specific
+   resolver details belong in ignored `.harness/docs-bridge.local.*` files.
+
+   | Local Source | Role | Hub Target | Sync Direction | Visibility | Status | Last Reviewed |
+   |--------------|------|------------|----------------|------------|--------|---------------|
+   | README.md | source | local-only | local-source -> hub-summary | public | active | YYYY-MM-DD |
+
+   Role: source, planning-artifact, decision-record, reference, runbook, state, generated
+   Sync Direction: local-source -> hub-summary, hub-reference -> local-index, bidirectional-index-only, local-only
+   Visibility: public, team, company-confidential, personal-private, do-not-share
+   Status: active, proposed, stale, archived
 -->
 
 <!-- CREW_MODE_START -->

package/harness/project-state.md

@@ -35,14 +35,40 @@
 
 ## Story Status
 
-| ID | Title | Status | Assignee |
-|----|-------|--------|----------|
-| S1-1 | Project scaffolding | ⬜ todo | |
-| S1-2 | Core feature implementation | ⬜ todo | |
-| S1-3 | Test coverage | ⬜ todo | |
+| ID | Title | Status | Assignee | Proof Plan |
+|----|-------|--------|----------|------------|
+| S1-0 | Proof setup | ⬜ todo | | test command or smoke proof |
+| S1-1 | Project scaffolding | ⬜ todo | | exact command/checklist |
+| S1-2 | Core feature implementation | ⬜ todo | | exact command/checklist |
+| S1-3 | Test coverage | ⬜ todo | | exact command/checklist |
 
 <!-- Status legend: ⬜ todo, 🔧 active, ✅ done, 🚫 blocked, ❌ dropped -->
 
+## Evidence Summary
+
+<!-- Keep the current proof state visible at a glance.
+   | Story | Status | Last Proof | Result | Blocker |
+   |-------|--------|------------|--------|---------|
+   | S1-1 | Proof Pending | - | - | tests not run |
+-->
+
+## Evidence-Gated Progress Board
+
+<!-- Keep this compact. It tells the user where the project is and what proof is missing.
+   State: Planned → Implementing → Proof Pending → Proven → Reviewed → Blocked
+   | Story | Goal | State | Required Evidence | Last Proof | Blocker |
+   |-------|------|-------|-------------------|------------|---------|
+   | S1-1 | First usable result | Proof Pending | npm test | - | tests not run |
+-->
+
+## Proof Ledger
+
+<!-- One line per completed proof. Do not paste long logs.
+   | Date | Story | Evidence | Result | Command / Observation |
+   |------|-------|----------|--------|-----------------------|
+   | 2026-05-04 | S1-1 | Unit tests | ✅ pass | npm test |
+-->
+
 ## Module Registry
 
 <!-- Summary of current modules. Full details in docs/dependency-map.md -->

package/harness/skills/breakdown.md

@@ -77,6 +77,7 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 - Never implement a module before its dependencies exist
 - 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.
 - 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