@kodevibe/harness 0.11.2 → 0.11.4

package/harness/skills/wrap-up.md

@@ -20,22 +20,21 @@ This is kode:harness's memory mechanism — without it, the same mistakes repeat
 - After a review revealed a repeated mistake
 - When the user explicitly asks to record a lesson
 
-> **Timing**: Invoke this skill **once at session end**, not after each individual skill. It aggregates the entire session's work into state files.
+> **Timing**: Invoke once at session end; aggregate the whole session into state files.
 
 ## Procedure
 
 ### Step 1: Review Session Activity
 
 1. Scan recent git changes: `git log --oneline -10` and `git diff --stat HEAD~3`
-2. Identify what was accomplished in this session
-3. Identify any errors, failures, or unexpected issues that occurred
+2. Identify accomplishments and unexpected issues
 
 **Edge Case: Zero-Change Session**
 If `git diff --stat` shows no changes and `git log` shows no new commits this session:
 - Report: "📝 Quiet session — status checks only, no code changes."
 - Skip Step 3 (Failure Pattern Detection) — no code changes means no new failure patterns
 - Skip Step 5 (features.md update) and Step 5.5 (dependency-map.md verify) — nothing changed
-- Still execute Step 4 (Quick Summary update) and Step 6 (Agent Memory) if an agent was used
+- Still execute Step 4 and Step 6 if an agent was used
 - Still execute Step 2 (Direction Drift Check) — discussion-only drift is possible
 
 ### Step 2: Direction Drift Check
@@ -49,14 +48,14 @@ Before recording failures, verify that the session's work stayed aligned with pr
    - Did the user explicitly change direction during this session? → Note for pivot recommendation
 3. **If drift detected**:
    - Add a warning to the Step 7 Report: `⚠️ Direction drift: [description of misalignment]`
-   - Recommend: "Consider running `pivot` skill to formally update project direction. You can run it AFTER this wrap-up session completes."
+   - Recommend `pivot` after wrap-up
    - Do NOT block — the wrap-up skill always completes
 4. **If no drift**: Proceed silently (no output for this step)
 
 <!-- CREW_MODE_START -->
 #### Step 2.5: Validation Tracker Update (🟣 Pipeline only) ⚠️ MANDATORY
 
-> **⛔ Completion Gate**: Step 2.5를 완료해야 Step 3 이후를 진행할 수 있습니다. Validation Tracker가 존재하면 반드시 갱신 후 다음 단계로 진행하세요.
+> **⛔ Completion Gate**: Validation Tracker가 있으면 갱신 후 Step 3으로 진행하세요.
 
 If `docs/project-brief.md` contains a `## Validation Tracker` section with data:
 
@@ -70,9 +69,9 @@ If `docs/project-brief.md` contains a `## Validation Tracker` section with data:
    - Did this session produce Stories/code that don't map to any FR or KPI? → warn
    - Are there KPIs/FRs with no Stories after 2+ sprints? → warn as "⚠️ Unplanned KPI/FR risk"
    - Include warnings in Step 7 Report
-5. **Self-check**: Validation Tracker의 KPI/FR/ARB 상태가 이 세션의 완료 Story를 정확히 반영하는지 확인. 미갱신 항목이 있으면 즉시 갱신 후 다음 단계로 진행.
+5. **Self-check**: KPI/FR/ARB 상태가 완료 Story와 일치해야 합니다. 누락 시 즉시 갱신.
 
-> ⛔ Validation Tracker 갱신 없이 Step 3으로 진행하지 마세요. 이 단계를 건너뛰면 FR/KPI Coverage가 실제 진행 상황과 불일치합니다.
+> ⛔ Tracker 갱신 없이 Step 3으로 진행하지 마세요.
 
 If no Validation Tracker → skip this step entirely.
 <!-- CREW_MODE_END -->
@@ -83,7 +82,7 @@ For each issue/error that occurred in this session:
 
 1. Read `docs/failure-patterns.md`
 2. Check if this matches an existing pattern (FP-NNN):
-   - **If match found AND already incremented by `debug` in this session**: Skip — do not double-count. Check `docs/project-state.md` Recent Changes for debug entries from this session to determine if a pattern was already recorded.
+   - **If match found AND already incremented by `debug` in this session**: Skip. Check Recent Changes to avoid double-count.
    - **If match found AND NOT already incremented this session**: Increment the Frequency counter, add the Sprint/Story to "Occurred"
    - **If new pattern**: Assign next FP-NNN number, create a new entry using this format:
 
@@ -100,7 +99,7 @@ For each issue/error that occurred in this session:
 
 3. If the failure relates to a specific skill or agent, note it for that skill's checklist
 
-> **Self-check**: Step 3 완료 시 `docs/failure-patterns.md`에 최소 하나의 FP 항목이 있어야 합니다 (이 세션에서 실패가 없었으면 기존 항목 확인만).
+> **Self-check**: `docs/failure-patterns.md` has at least one FP entry; if no new failure, existing entries are enough.
 
 ### Step 4: Update docs/project-state.md ⚠️ MANDATORY
 
@@ -116,6 +115,9 @@ For each issue/error that occurred in this session:
    ```
    - [YYYY-MM-DD] S{N}-{M}: {what was done} (STATUS: DONE)
    ```
+   - Append compact changelog rows only. If creating the section, place it before `## Session Handoff Protocol` or EOF.
+   - Never insert it inside proof/evidence sections (`Proof Ledger`, durable UI evidence, smoke/manual proof).
+   - Self-check: no nested headings or UI/proof checklist bullets under `## Recent Changes`.
 
 ### Step 5: Update docs/features.md (if applicable)
 
@@ -136,7 +138,23 @@ For each issue/error that occurred in this session:
    - WARN → include warnings in the final wrap-up report, then proceed
    - FAIL → fix the listed drift (update affected state files), then re-run state-check until PASS or WARN
 
-> **Self-check**: `docs/dependency-map.md`에 이 세션에서 새로 추가한 모듈이 모두 등록되었는지 확인. 누락 시 즉시 추가. state-check가 PASS 또는 WARN을 반환해야 다음 단계로 진행합니다.
+> **Self-check**: New modules are registered in `docs/dependency-map.md`; state-check is PASS/WARN.
+
+#### Step 5.5b: Guard Evidence (R16) ⚠️ MANDATORY
+
+Before saying `state-check PASS`, `0 FAIL`, `0 WARN`, `STATUS: DONE`, or `Session Learn Complete`, run and quote one guard summary:
+
+```bash
+HARNESS_GUARD_ROOT="$PWD" node /path/to/k-harness/scripts/harness-guard.js docs/project-state.md
+```
+
+or installed script:
+
+```bash
+npm run harness:guard:wrap-up
+```
+
+Rules: paste the exact guard summary. Errors block `STATUS: DONE`; warnings must be listed. Never write `0 FAIL, 0 WARN` unless guard says no issues.
 
 ### Step 5.55: Refresh Project Docs Hub Index (if applicable)
 
@@ -145,7 +163,7 @@ Run only if user used/requested `docs-bridge`, or Project Docs Hub Index has rea
 1. For changed docs (`README*`, `docs/`, ADR/design/runbook/API specs), refresh indexed review/status.
 2. For new docs, add `proposed` rows or recommend `docs-bridge`.
 3. Never write external hubs, invent targets, change visibility, or convert `local-only` / `pending` without explicit request.
-4. Keep filesystem paths, vault names, page IDs, and resolver details out of tracked state; use `.harness/docs-bridge.local.*`.
+4. Keep private paths/IDs/resolvers out of tracked state; use `.harness/docs-bridge.local.*`.
 
 ### Step 5.6: Resolve STATE-AUDIT Flags (if applicable)
 
@@ -160,8 +178,12 @@ Before session end, record the working proof that justified completion:
 1. Read reviewer output or recent terminal evidence for passing tests/smoke proof.
 2. Add one compact row to `docs/project-state.md` → `## Proof Ledger` for each completed Story.
 3. Cross-check completed Stories against `## Evidence Summary` / `## Proof Ledger`.
-4. If no proof exists, write `[PROOF-GAP] Proof missing` in the wrap-up report and recommend returning to `reviewer`; do not claim the Story is complete.
-5. If `[PROOF-GAP]` exists, STOP before Step 5.65. Do not auto-commit state files that mark a Story done/reviewed without passing proof. Revert the Story to Proof Pending or return to `reviewer`.
+4. Check `## Story Contracts`: completed Story rows must be `✅ pass`/`proven`; otherwise `[CONTRACT-GAP]`.
+5. UI/manual/smoke proof needs artifact/checklist or URL + exact counts/elements.
+6. Keep durable UI evidence in its own section, never under `## Recent Changes`.
+7. Split FR/KPI/ARB mappings need `Scope split approved: <reason>`.
+8. If proof is missing, write `[PROOF-GAP]` and return to `reviewer`.
+9. If `[PROOF-GAP]` or `[CONTRACT-GAP]` exists, STOP before Step 5.65.
 
 Proof rows must stay short: Date, Story, Evidence, Result, Command / Observation. Do not paste long logs.
 
@@ -171,24 +193,34 @@ State file 변경사항을 커밋합니다. Learn 실행 결과가 커밋되지
 
 1. Stage state files: `git add docs/project-state.md docs/failure-patterns.md docs/features.md docs/dependency-map.md docs/agent-memory/`
 2. Commit: `git commit -m "wrap-up: session lessons captured"`
-3. If commit fails (nothing to commit), skip — state files were already committed
+3. If nothing to commit, skip.
 
 > **Self-check**: `git status`에 docs/ 아래 unstaged 파일이 없어야 합니다.
 
+#### Step 5.65b: Dirty Worktree Truth (R16) ⚠️ MANDATORY
+
+Run:
+
+```bash
+git status --short
+```
+
+Rules: paste exact `git status --short` or `clean`. Dirty `src/`, `test/`, `public/`, or app files mean work is not fully committed. If they remain by policy, report `Session End: DIRTY WORKTREE`.
+
 ### Step 5.7: Git Push Check (session end)
 
 Before ending the session, check for unpushed commits:
 
-1. Run `git log --oneline @{u}..HEAD 2>/dev/null || echo "no upstream"` to find unpushed commits
+1. Run `git log --oneline @{u}..HEAD 2>/dev/null || echo "no upstream"`
 2. **If unpushed commits exist**:
    - List the commits: `git log --oneline @{u}..HEAD`
    - Solo mode: Recommend push — `git push origin {branch}`
-   - Team mode: **Strongly recommend** push — unpushed work is invisible to teammates
+   - Team mode: **Strongly recommend** push
    - Warn: "⚠️ {N}개의 커밋이 push되지 않았습니다. 작업물을 원격에 백업하세요."
 3. **If no upstream configured** (`no upstream`):
    - Check if remote exists: `git remote -v`
    - If remote exists: Suggest `git push -u origin {branch}` (first push)
-   - If no remote: Note "원격 저장소가 설정되지 않았습니다. 팀 협업 시 remote 설정이 필요합니다."
+   - If no remote: Note "원격 저장소가 설정되지 않았습니다."
 4. **If all commits are pushed**: Skip (no output)
 
 ### Step 6: Update Agent Memory (if applicable)
@@ -199,15 +231,15 @@ If an agent (reviewer, pm, lead, architect) was used in this session, update its
 2. **Auto-initialize if needed**: If the file only contains `<!-- Example entries` placeholder comments and no real data:
    - Replace the placeholder block with actual entries from this session
    - Initialize statistics counters with real values
-   - If real entries already exist alongside placeholders, APPEND new entries and remove only the placeholder comments. Do not overwrite existing real data.
-   - **When does initialization happen?**: On the FIRST session where the agent is used AND wrap-up is invoked. If an agent is never used, its memory stays as a placeholder indefinitely — this is expected.
+   - If real entries exist, APPEND and remove only placeholder comments.
+   - Initialize on the first wrap-up session where the agent was used.
    - Example transformation:
      ```
      Before: <!-- Example entries (replace with real findings after first review):
      After:  - [S1-1] Mock sync missed for UserService interface change
      ```
 3. **Append session learnings** to the appropriate section:
-   - **reviewer.md**: Add review patterns found, update statistics (total reviews +1, auto-fixes, escalations)
+   - **reviewer.md**: Add review patterns and update statistics
    - **pm.md**: Record estimation accuracy (planned vs actual), note architecture discoveries
    - **lead.md**: Update velocity (stories done/planned), record any scope drift incidents
    - **architect.md**: Record design decisions made, module boundary insights, anti-patterns observed
@@ -275,11 +307,11 @@ If crew artifacts were used this session (🟣 pipeline), also append:
 - Keep failure pattern descriptions concise (1-2 sentences for Cause and Prevention)
 - If no failures occurred, skip Step 2 and just update state files
 - Do not modify source code — this skill only updates state files
-- Quick Summary must be exactly 3 lines — concise enough for the next session to scan instantly
+- Quick Summary must be exactly 3 lines
 
 ## Enforced Rules
 
-- **Session Handoff**: Before ending a session, docs/project-state.md Quick Summary MUST be updated. Never leave the project in an undocumented state.
+- **Session Handoff**: Before ending, update docs/project-state.md Quick Summary.
 - **State File Size Limits**: Keep state files compact for LLM context windows:
   - docs/project-brief.md: Max 200 lines
   - docs/project-state.md: Max 300 lines (archive completed sprints)
@@ -302,7 +334,7 @@ If crew artifacts were used this session (🟣 pipeline), also append:
 ## Team Mode: Session Wrap-up
 
 ### Pre-Pull (mandatory before any shared file edit)
-1. Run `git pull` on the default branch before updating docs/features.md or docs/dependency-map.md (per project-brief.md → Key Technical Decisions; default: main)
+1. Run `git pull` on the default branch before updating docs/features.md or docs/dependency-map.md (default: main)
 2. If merge conflicts occur, follow the **Merge Conflict SOP** below
 
 ### Merge Conflict SOP
@@ -319,7 +351,7 @@ When `git pull` causes merge conflicts in shared state files:
    | `docs/failure-patterns.md` | Keep BOTH entries, deduplicate by FP-NNN number |
 3. **After resolving**: `git add <resolved-files> && git commit`
 4. **Verify**: Re-read the resolved file and confirm no data was lost
-5. **If unsure**: Do NOT force-resolve. Ask the designated authority (per project-brief.md; default: team lead) or the Owner of the conflicting rows.
+5. **If unsure**: Do NOT force-resolve. Ask the designated authority or row Owner.
 
 ### Owner-Scoped Updates
 - **docs/features.md**: only update rows where Owner = you
@@ -327,7 +359,7 @@ When `git pull` causes merge conflicts in shared state files:
 - **Personal files** (.harness/project-state.md, .harness/failure-patterns.md, .harness/agent-memory/): update freely — no coordination needed
 
 ### Failure Pattern Promotion
-If a personal failure pattern (FP-NNN in .harness/failure-patterns.md) is likely to affect other developers:
+If a personal FP in `.harness/failure-patterns.md` may affect others:
 1. Discuss with the team (Slack, PR comment, etc.)
-2. If agreed, add it to a shared location (team wiki, PR description) so others can add it to their personal .harness/failure-patterns.md
+2. If agreed, add it to a shared location so others can copy it.
 <!-- TEAM_MODE_END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodevibe/harness",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "kode:harness — harness engineering for keeping every developer's AI aligned on one project direction.",
   "keywords": [
     "llm",