@kodevibe/harness 0.11.1 → 0.11.2

package/README.ko.md

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

package/README.md

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

@@ -1,6 +1,6 @@
 {
   "name": "@kodevibe/harness",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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,
+};