@kodevibe/harness 0.11.1 → 0.11.3

package/harness/skills/wrap-up.md

@@ -20,7 +20,7 @@ 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
 
@@ -35,7 +35,7 @@ If `git diff --stat` shows no changes and `git log` shows no new commits this se
 - 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 +49,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 +70,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 +83,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 +100,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 +116,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 +139,7 @@ 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.55: Refresh Project Docs Hub Index (if applicable)
 
@@ -145,7 +148,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 +163,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,7 +178,7 @@ 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 파일이 없어야 합니다.
 
@@ -179,16 +186,16 @@ State file 변경사항을 커밋합니다. Learn 실행 결과가 커밋되지
 
 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 +206,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 +282,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 +309,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 +326,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 +334,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.1",
+  "version": "0.11.3",
   "description": "kode:harness — harness engineering for keeping every developer's AI aligned on one project direction.",
   "keywords": [
     "llm",
@@ -46,8 +46,17 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.js",
+    "harness:check-pack": "node scripts/check-public-pack.js",
     "harness:check-drift": "node scripts/check-harness-drift.js",
-    "harness:sync": "node bin/cli.js init --ide vscode --batch --dir . --overwrite"
+    "harness:dependency-scan": "node scripts/check-dependency-map.js",
+    "harness:guard": "node scripts/harness-guard.js",
+    "harness:guard:all": "node scripts/harness-guard.js --all",
+    "harness:guard:wrap-up": "node scripts/harness-guard.js --wrap-up",
+    "harness:llm-bench": "node scripts/llm-bench.js",
+    "harness:llm-bench:export": "node scripts/llm-bench.js --export-prompts --scenarios docs/llm-bench-scenarios.json --out bench/r10",
+    "harness:llm-bench:smoke": "node scripts/llm-bench.js docs/llm-bench-results.example.json",
+    "harness:llm-bench:real": "node scripts/llm-bench.js docs/llm-bench-results.json --require-real",
+    "harness:state-sync": "node scripts/harness-guard.js --state-sync"
   },
   "publishConfig": {
     "access": "public"

package/src/dependency-scan.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const DEFAULT_ROOTS = ['src', 'app', 'lib', 'packages', 'services'];
+const SKIP_DIRS = new Set(['.git', '.harness', 'node_modules', 'dist', 'build', 'coverage', '.next', '.turbo']);
+
+function toPosix(file) {
+  return String(file || '').replace(/\\/g, '/');
+}
+
+function stripCodeComments(content) {
+  return String(content || '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+function isSourceFile(file) {
+  return SOURCE_EXTENSIONS.has(path.extname(file));
+}
+
+function walkSourceFiles(cwd, roots = DEFAULT_ROOTS) {
+  const files = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const name of fs.readdirSync(dir)) {
+      if (SKIP_DIRS.has(name)) continue;
+      const full = path.join(dir, name);
+      const st = fs.statSync(full);
+      if (st.isDirectory()) walk(full);
+      else if (st.isFile() && isSourceFile(full)) files.push(toPosix(path.relative(cwd, full)));
+    }
+  }
+
+  for (const root of roots) walk(path.join(cwd, root));
+  return files.sort();
+}
+
+function moduleKeyForFile(file) {
+  const parts = toPosix(file).split('/').filter(Boolean);
+  if (parts.length === 0) return '';
+  if (parts[0] === 'packages' || parts[0] === 'services') {
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+  }
+  if (DEFAULT_ROOTS.includes(parts[0])) {
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+  }
+  return parts[0];
+}
+
+function extractLocalSpecifiers(content) {
+  const clean = stripCodeComments(content);
+  const specs = [];
+  const patterns = [
+    /\bimport\s+(?:[^'"]+\s+from\s+)?['"]([^'"]+)['"]/g,
+    /\bexport\s+[^'"]+\s+from\s+['"]([^'"]+)['"]/g,
+    /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+  for (const re of patterns) {
+    for (const match of clean.matchAll(re)) {
+      const spec = match[1];
+      if (spec.startsWith('.')) specs.push(spec);
+    }
+  }
+  return specs;
+}
+
+function normalizeRelativeTarget(fromFile, specifier) {
+  const fromDir = path.posix.dirname(toPosix(fromFile));
+  return path.posix.normalize(path.posix.join(fromDir, specifier));
+}
+
+function scanDependencyGraph({ cwd = process.cwd(), files = null, roots = DEFAULT_ROOTS } = {}) {
+  const sourceFiles = files ? files.filter(isSourceFile).map(toPosix).sort() : walkSourceFiles(cwd, roots);
+  const modules = new Map();
+
+  for (const file of sourceFiles) {
+    const module = moduleKeyForFile(file);
+    if (!module) continue;
+    if (!modules.has(module)) modules.set(module, { module, files: new Set(), dependsOn: new Set() });
+    modules.get(module).files.add(file);
+
+    const abs = path.join(cwd, file);
+    if (!fs.existsSync(abs)) continue;
+    const content = fs.readFileSync(abs, 'utf8');
+    for (const spec of extractLocalSpecifiers(content)) {
+      const target = normalizeRelativeTarget(file, spec);
+      const dep = moduleKeyForFile(target);
+      if (dep && dep !== module) modules.get(module).dependsOn.add(dep);
+    }
+  }
+
+  return [...modules.values()]
+    .map((entry) => ({
+      module: entry.module,
+      files: [...entry.files].sort(),
+      dependsOn: [...entry.dependsOn].sort(),
+    }))
+    .sort((a, b) => a.module.localeCompare(b.module));
+}
+
+function markdownTableRows(section) {
+  const lines = String(section || '').split('\n').map((line) => line.trim()).filter((line) => line.startsWith('|'));
+  if (lines.length < 2) return [];
+  const headers = lines[0].replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
+  return lines.slice(2)
+    .filter((line) => !/^\|\s*[-:|\s]+\|?$/.test(line))
+    .map((line) => {
+      const cells = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
+      const row = {};
+      headers.forEach((header, i) => { row[header] = cells[i] || ''; });
+      row.__raw = line;
+      return row;
+    });
+}
+
+function section(content, header) {
+  const re = new RegExp(`^##\\s+${header}\\s*$`, 'm');
+  const match = re.exec(content);
+  if (!match) return '';
+  const rest = content.slice(match.index + match[0].length);
+  const next = /^##\s+/m.exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+}
+
+function splitDepends(value) {
+  return String(value || '')
+    .replace(/`/g, '')
+    .split(/(?:<br\s*\/?>|[,;]|\s{2,})/i)
+    .map((item) => item.trim())
+    .filter((item) => item && !/^[-–—]$/.test(item) && !/^n\/a$/i.test(item) && !/^none$/i.test(item));
+}
+
+function parseDependencyMap(content) {
+  const body = section(content, 'Module Registry')
+    || section(content, 'Module Dependency Map')
+    || section(content, 'Module Map')
+    || content;
+  return markdownTableRows(body)
+    .map((row) => ({
+      module: row.Module || row.module || '',
+      dependsOn: splitDepends(row['Depends On'] || row.Depends || row.Dependencies || ''),
+      raw: row.__raw,
+    }))
+    .filter((row) => row.module);
+}
+
+function checkDependencyMapCoverage({ graph = [], dependencyMap = '' } = {}) {
+  const violations = [];
+  const rows = parseDependencyMap(dependencyMap);
+  const rowByModule = new Map(rows.map((row) => [row.module, row]));
+
+  for (const item of graph) {
+    const row = rowByModule.get(item.module);
+    if (!row) {
+      violations.push({
+        check: 'dependency-scan',
+        severity: 'error',
+        line: 0,
+        message: `Module ${item.module} exists in source files but is missing from dependency-map.md (R7 source dependency scan).`,
+      });
+      continue;
+    }
+    const mapped = row.dependsOn.join(' ');
+    for (const dep of item.dependsOn) {
+      if (!mapped.includes(dep)) {
+        violations.push({
+          check: 'dependency-scan',
+          severity: 'error',
+          line: 0,
+          message: `Module ${item.module} imports ${dep}, but dependency-map.md does not list it in Depends On (R7 source dependency scan).`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+module.exports = {
+  DEFAULT_ROOTS,
+  isSourceFile,
+  walkSourceFiles,
+  moduleKeyForFile,
+  extractLocalSpecifiers,
+  normalizeRelativeTarget,
+  scanDependencyGraph,
+  parseDependencyMap,
+  checkDependencyMapCoverage,
+};