@kodevibe/harness 0.9.6 → 0.11.1

package/harness/skills/docs-bridge.md

@@ -0,0 +1,161 @@
+# Docs Bridge
+
+## Purpose
+
+Connect project-local documentation to a wiki, knowledge base, or docs hub through a small, safe index in `docs/project-brief.md`.
+This keeps the repository as the source of truth for project-internal docs while letting a central hub discover, summarize, and link them safely.
+
+## Invoked By
+
+- **User** — "connect this project to my wiki", "문서를 위키처럼 정리해줘", "sync docs to Confluence", "Obsidian docs hub"
+- **setup** — after state files are filled, when the user asked for documentation organization or a central docs hub
+- **wrap-up** — when documentation changed and `docs/project-brief.md` already has a Project Docs Hub Index
+- **state-check** — validates the index shape and local path coverage
+
+## When to Apply
+
+- A project has several documentation surfaces: README, `docs/`, ADRs, runbooks, API specs, planning artifacts, generated reports
+- The user wants a central wiki/docs hub to know which project docs exist without copying every document into the hub
+- The user wants LLMs to manage internal docs, source cards, meeting notes, or project cards across sessions
+- Before promoting a local document into an external wiki, Confluence space, Obsidian vault, or team knowledge base
+
+## Boundaries
+
+- Preserve original documents unless the user explicitly asks to edit them.
+- Do not copy entire READMEs, specs, transcripts, or external pages into the hub. Summarize and link.
+- Treat the hub as a reference layer: path/URL, role, key constraints, status, and visibility are enough.
+- Respect visibility. Private or confidential rows need explicit user confirmation before any external target is written.
+- Do not commit company-private URLs or personal vault paths into OSS templates. Those belong in the user's local project state.
+- Keep tracked index rows sanitized: use `local-only`, `pending`, or a logical hub alias/note title, not machine-specific absolute paths.
+- Store local resolver details such as Obsidian vault paths, personal Wiki names, page IDs, or sync scripts only in ignored local files such as `.harness/docs-bridge.local.json`.
+- Keep uncertain relationships as `proposed`, `needs verification`, or `review required`.
+
+## Procedure
+
+### Phase 1: Discover Documentation Surfaces
+
+Read only enough to classify documents. Prefer headers, tables of contents, and first sections before reading full files.
+
+Common candidates:
+- Root docs: `README*`, `CHANGELOG*`, `CONTRIBUTING*`, `SECURITY*`, `LICENSE`
+- Project docs: `docs/`, `adr/`, `architecture/`, `design/`, `runbooks/`, `playbooks/`, `operations/`
+- API and contract docs: `openapi*`, `swagger*`, `schema*`, `proto/`, `graphql/`
+- AI/planning docs: planning artifact directories, role-based analysis folders, meeting notes, research notes
+- Existing state: `docs/project-brief.md`, `docs/features.md`, `docs/dependency-map.md`, `docs/project-state.md`
+
+Skip generated dependency/build directories: `node_modules/`, `dist/`, `build/`, `.next/`, coverage output, binary archives.
+
+### Phase 2: Classify Each Candidate
+
+Use this vocabulary in the index:
+
+| Role | Meaning |
+|------|---------|
+| `source` | Original project documentation maintained in this repo |
+| `planning-artifact` | PRD, design, architecture, ARB, roadmap, or external planning output |
+| `decision-record` | ADR, Decision Log, meeting decision, or governance note |
+| `reference` | External guide, source card, example, standard, or adoption candidate |
+| `runbook` | Operational procedure, deployment guide, incident response, support playbook |
+| `state` | kode:harness state file used by LLM agents |
+| `generated` | Derived output that should not be treated as an original source |
+
+### Phase 3: Confirm The Docs Hub Contract
+
+Ask at most three questions if the prompt does not already answer them:
+
+1. Hub target: logical hub alias/note title, wiki space/page label, repository path, `pending`, or `local-only`? Do not ask for or write absolute local vault paths into tracked state.
+2. Visibility boundary: `public`, `team`, `company-confidential`, `personal-private`, or `do-not-share`?
+3. Sync intent: summarize local docs into the hub, index hub references locally, or only maintain a bidirectional map?
+
+If the user skips the hub target, create a local map only and set Hub Target to `local-only`. If the user provides a local filesystem path, write only a sanitized alias or `local-only` in the tracked index and put the concrete path in `.harness/docs-bridge.local.json`.
+
+### Phase 4: Update Project Docs Hub Index
+
+Ensure `docs/project-brief.md` contains this section. Add it if missing:
+
+```markdown
+## Project Docs Hub Index
+
+| 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 |
+```
+
+Column rules:
+- **Local Source**: exact repository path, or external URL only when no local file exists.
+- **Role**: use the Phase 2 vocabulary.
+- **Hub Target**: `local-only`, `pending`, a sanitized external page label/URL, an Obsidian note title, a Confluence page label, or a logical hub alias. Never store `/Users/...`, `~/...`, `file://...`, drive-letter paths, personal vault paths, or tokens in this tracked table.
+- **Sync Direction**: one of `local-source -> hub-summary`, `hub-reference -> local-index`, `bidirectional-index-only`, `local-only`.
+- **Visibility**: one of `public`, `team`, `company-confidential`, `personal-private`, `do-not-share`.
+- **Status**: `active`, `proposed`, `stale`, or `archived`.
+- **Last Reviewed**: ISO date, or `pending` for proposed rows.
+
+### Phase 5: Promote Safely (Optional)
+
+Only when the user asks to update the hub:
+
+1. Create or update a short hub summary that links back to the Local Source.
+2. Preserve originals. If a local source needs improvement, ask before editing it.
+3. Record relationships with evidence, for example:
+   - `project -> documents -> Local Source`
+   - `Local Source -> summarized_by -> Hub Target`
+   - `reference -> supports -> project decision`
+4. Put uncertain claims under `needs verification` or `proposed relationship`.
+5. Never expose private/confidential rows into a less-restricted hub target without explicit user confirmation.
+6. For local-only hubs, use `.harness/docs-bridge.local.json` for machine-specific resolver details. Do not write those details into tracked state, README, or OSS templates.
+
+### Phase 6: Verify
+
+1. Run `state-check` after updating `docs/project-brief.md`.
+2. Confirm local paths in the index exist, unless the row is intentionally external.
+3. Report any private/confidential row that has an external Hub Target and ask for confirmation before hub writes.
+4. If documentation files changed, include the proof in the response: paths updated, index rows added/changed, and any hub target touched.
+
+## Output Format
+
+```markdown
+## Docs Bridge Result
+
+### Index Updates
+- Added/updated rows: N
+- Local-only rows: N
+- External hub rows: N
+
+### Visibility Warnings
+- [none] or [row requiring confirmation]
+
+### Verification
+- state-check: PASS | WARN | FAIL
+- Missing local paths: [none or list]
+
+---
+🧭 Next Step
+→ Goal: Keep project docs discoverable without rewriting originals
+→ Evidence: `state-check` plus changed index rows
+→ Next: `wrap-up` or [Hub update]
+→ Prompt: "문서 허브 인덱스를 기준으로 다음 문서를 요약/연결해줘"
+→ Why: The docs map is now explicit enough for future LLM sessions
+→ Pipeline: utility skill (docs bridge)
+---
+```
+
+## Rules
+
+- Use repository-relative paths for Local Source.
+- Prefer summaries and links over copied bodies.
+- Do not modify raw/source docs during discovery.
+- Do not invent hub targets. Use `local-only` or `pending` when unknown.
+- Keep visibility explicit on every row.
+- Keep personal/local Wiki resolver details in ignored `.harness/docs-bridge.local.*` files only.
+- Do not write absolute local paths, personal vault names, private page IDs, tokens, or company-private URLs into tracked templates or public docs.
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Copy every project doc into the central wiki | Index local sources and promote concise summaries only |
+| Treat generated reports as authoritative source | Mark as `generated` and link to the original input when known |
+| Publish private docs to a team/public hub silently | Stop and ask for explicit confirmation |
+| Rewrite READMEs while building the index | Preserve originals; ask before editing source docs |
+| Leave Hub Target blank | Use `local-only` or `pending` with a follow-up |
+| Put `/Users/...`, `~/...`, `file://...`, or personal vault paths in `project-brief.md` | Store only a logical alias in the index and keep resolver details in `.harness/docs-bridge.local.json` |

package/harness/skills/pivot.md

@@ -114,7 +114,9 @@ After pivot completes, always append a 🧭 block:
 | Pivot Result | 🧭 Next Step |
 |---|---|
 | All state files updated | `pm` — "변경된 방향에 맞춰 재계획해줘" |
+<!-- CREW_MODE_START -->
 | Crew artifacts exist for new direction | `setup` (🟣) — "crew 산출물을 기반으로 state를 다시 세팅해줘" |
+<!-- CREW_MODE_END -->
 | User cancelled | 🏁 No action — "기존 방향을 유지합니다" |
 
 Example 🧭 block:

package/harness/skills/setup.md

@@ -13,6 +13,12 @@ One command does everything — no manual editing required.
 - When state files are outdated and need a refresh
 - When any agent reports "state files are empty"
 
+## Re-running on an existing install (Upgrade flow)
+
+On existing installs, default `init` preserves state (`project-state`, `features`, `dependency-map`, `failure-patterns`, `project-brief`, `agent-memory`) and refreshes IDE config (`.github/`, `.claude/`, `.cursor/`, `.codex/`, `.windsurf/`, `.agents/`, `CLAUDE.md`, `AGENTS.md`). Overwritten IDE files are backed up to `.harness/init-backups/<ISO-timestamp>/...`.
+
+Use `--overwrite` only to reset corrupted state after backup; then rerun setup to repopulate files.
+
 ## Procedure
 
 ### Phase 1: Project Discovery (read-only)
@@ -62,6 +68,10 @@ One command does everything — no manual editing required.
 
 **Do NOT modify any code files in this phase.**
 
+### Phase 1.4: Project Docs Hub Detection (optional)
+
+If user asked for wiki/docs-hub work, record candidate paths from Phase 1 without reading or rewriting full docs. After Phase 3, invoke `docs-bridge` to fill `## Project Docs Hub Index`. Otherwise skip.
+
 <!-- CREW_MODE_START -->
 ### Phase 1.5: Crew Artifact Detection + Indexing
 
@@ -135,6 +145,17 @@ Ask the user these questions (skip any already answered by Phase 1):
 5. "Are there any type decisions or conventions the AI should know about?"
 6. "What is your test command?" (show detected command if found, e.g., `npm test`, `pytest`, `go test ./...`)
 
+### Phase 2.1: Common Mode Confidence Loop
+
+Before filling state files, collapse the answers into a **Goal Card** and **Proof Profile**:
+- Goal: one sentence from Vision + top goal
+- First usable result: smallest working outcome the user can inspect
+- Non-goal boundary: what will not be built now
+- Required proof: test command, smoke proof, or manual checklist
+- Open question: at most one unresolved ambiguity
+
+If the user's answers are vague, ask at most one follow-up question. If still unclear, record the assumption instead of looping.
+
 ### Phase 3: Fill State Files
 
 Using data from Phase 1 + Phase 2, fill the following files:
@@ -144,6 +165,8 @@ Using data from Phase 1 + Phase 2, fill the following files:
 - Vision → from user answer #1
 - Goals → from user answer #2
 - Non-Goals → from user answer #3
+- Done Definition → from Goal Card / first usable result
+- Success Proof → from Proof Profile (test command, smoke proof, or manual checklist)
 <!-- CREW_MODE_START -->
 - Crew Artifact Index → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
 - Validation Tracker → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
@@ -231,6 +254,11 @@ After setup completes, remind the user that shared files require `git pull` befo
 - [x]docs/project-state.md — Sprint 1 initialized
 - [ ]docs/failure-patterns.md — templates only (no changes)
 
+### Goal Card
+- Goal: [one sentence]
+- First usable result: [observable outcome]
+- Required proof: [test/smoke/manual]
+
 STATUS: DONE
 ```
 
@@ -238,7 +266,7 @@ STATUS: DONE
 
 Bootstrap always leads to `pm`. Append this block after STATUS: DONE:
 
-**If NO crew artifacts** (🟢 pipeline):
+**Default common pipeline**:
 ```
 ---
 🧭 Next Step

package/harness/skills/state-check.md

@@ -46,7 +46,7 @@ For each file:
 1. Read all `✅ done` Stories from `docs/project-state.md` (or `.harness/project-state.md` in Team mode) Story Status table
 2. Read `docs/features.md` Feature Registry
 3. For each `✅ done` Story:
-   - If Story has `[FR-NNN]` prefix → must map to a feature row with that FR reference
+   - If Story has an external reference prefix → must map to a feature row with the same reference
    - Otherwise → must map to at least one feature row whose Key Files overlap with the Story's Scope
 4. Outcomes:
    - Story ✅ done but no matching feature row → FAIL: `[FAIL] Story {S-N-M} done but no feature registered`
@@ -105,6 +105,32 @@ If `docs/project-brief.md` contains a `## Validation Tracker` section:
 If no Validation Tracker → skip.
 <!-- CREW_MODE_END -->
 
+### Check 7: Proof Ledger Coverage
+
+1. Read `docs/project-state.md` (or `.harness/project-state.md` in Team mode).
+2. For each Story marked `✅ done`, verify at least one Proof Ledger or Evidence Summary row exists with a passing result.
+3. Outcomes:
+   - Done Story with passing proof → PASS
+   - Done Story with no proof → FAIL: `[FAIL] Story {S-N-M} is done but has no passing Proof Ledger/Evidence Summary entry — revert to Proof Pending or run reviewer proof before DONE/commit guidance`
+   - Done Story with failing proof → FAIL: `[FAIL] Story {S-N-M} proof shows failure but status is done`
+   - In-progress Story without proof → PASS; proof pending is normal
+
+### Check 8: Project Docs Hub Index (optional)
+
+If `docs/project-brief.md` contains `## Project Docs Hub Index` with non-comment table rows:
+
+1. For each row, verify `Local Source`, `Sync Direction`, `Visibility`, `Status`, and `Last Reviewed` are not blank or `TBD`.
+2. If `Local Source` is a repository path, verify the file or directory exists. Skip existence checks for URLs and explicitly external rows.
+3. Verify `Sync Direction` is one of: `local-source -> hub-summary`, `hub-reference -> local-index`, `bidirectional-index-only`, `local-only`.
+4. Verify `Visibility` is one of: `public`, `team`, `company-confidential`, `personal-private`, `do-not-share`.
+5. If `Hub Target` contains an absolute/local machine path (`/Users/`, `~/`, `file://`, drive-letter paths, or backslash user paths), WARN: `[WARN] docs hub row contains local machine path — move resolver details to .harness/docs-bridge.local.*`.
+6. If Visibility is `company-confidential`, `personal-private`, or `do-not-share` and Hub Target is not `local-only` or `pending`, WARN: `[WARN] restricted docs row has external Hub Target — confirm disclosure boundary before hub writes`.
+
+Outcomes:
+- Complete rows with existing local paths → PASS
+- 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
+
 ## Output Format
 
 ```
@@ -126,6 +152,12 @@ If no Validation Tracker → skip.
 ### Check 4: Agent Memory Legacy Names
 - No legacy names found (or list of legacy files to rename)
 
+### Check 7: Proof Ledger Coverage
+- {N} done Stories checked / {M} missing proof / {K} failing proof
+
+### Check 8: Project Docs Hub Index
+- {N} rows checked / {M} missing paths / {K} visibility warnings / skipped if unused
+
 <!-- CREW_MODE_START -->
 ### Check 6: Validation Tracker (🟣)
 - {N} FR references checked / {M} drifted
@@ -142,7 +174,7 @@ STATUS: PASS | WARN | FAIL
 ### Result Interpretation
 
 - **PASS** — all checks passed; calling agent may proceed with STATUS: DONE
-- **WARN** — non-blocking issues; calling agent should include warnings in its output but may proceed
+- **WARN** — non-blocking issues; calling agent should include warnings in its output but may proceed. Exception: proof coverage gaps are FAIL.
 - **FAIL** — blocking; calling agent must NOT report STATUS: DONE until failures are resolved
 
 ### 🧭 Navigation — After State Check

package/harness/skills/wrap-up.md

@@ -138,6 +138,15 @@ For each issue/error that occurred in this session:
 
 > **Self-check**: `docs/dependency-map.md`에 이 세션에서 새로 추가한 모듈이 모두 등록되었는지 확인. 누락 시 즉시 추가. state-check가 PASS 또는 WARN을 반환해야 다음 단계로 진행합니다.
 
+### Step 5.55: Refresh Project Docs Hub Index (if applicable)
+
+Run only if user used/requested `docs-bridge`, or Project Docs Hub Index has real rows.
+
+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.*`.
+
 ### Step 5.6: Resolve STATE-AUDIT Flags (if applicable)
 
 If the `reviewer` agent was run in this session and produced `[STATE-AUDIT]` flags:
@@ -145,6 +154,17 @@ If the `reviewer` agent was run in this session and produced `[STATE-AUDIT]` fla
 2. Apply the recommended state file update
 3. If the flag was already resolved during the session, skip it
 
+### Step 5.6a: Finalize Proof Ledger ⚠️ MANDATORY
+
+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`.
+
+Proof rows must stay short: Date, Story, Evidence, Result, Command / Observation. Do not paste long logs.
+
 ### Step 5.65: Auto-Commit State Files ⚠️ MANDATORY
 
 State file 변경사항을 커밋합니다. Learn 실행 결과가 커밋되지 않으면 다음 세션에서 유실됩니다.
@@ -209,6 +229,7 @@ Present a summary of all updates made.
 
 ### State Files Updated:
 - [x] docs/project-state.md — Quick Summary refreshed
+- [x] docs/project-state.md — Proof Ledger updated (if any Story completed)
 - [x] docs/failure-patterns.md — [N] patterns added/updated
 - [x] docs/features.md — [N] features updated (if applicable)
 - [x] docs/dependency-map.md — [N] modules verified/added (if applicable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodevibe/harness",
-  "version": "0.9.6",
+  "version": "0.11.1",
   "description": "kode:harness — harness engineering for keeping every developer's AI aligned on one project direction.",
   "keywords": [
     "llm",
@@ -45,7 +45,9 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "harness:check-drift": "node scripts/check-harness-drift.js",
+    "harness:sync": "node bin/cli.js init --ide vscode --batch --dir . --overwrite"
   },
   "publishConfig": {
     "access": "public"