oh-my-llmwikimode 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +494 -0
  3. package/bin/llmwiki.js +1493 -0
  4. package/docs/INSTALLATION.md +228 -0
  5. package/docs/SCOPE_LOCK.md +79 -0
  6. package/docs/STAGE1_GUIDE.md +265 -0
  7. package/docs/STAGE2_AGENT_TEAM_GUIDE.md +141 -0
  8. package/docs/STAGE3_CONVERSATIONAL_GROWTH_GUIDE.md +50 -0
  9. package/docs/TEST_WORKSHEET.md +120 -0
  10. package/docs/github-private-bootstrap.md +53 -0
  11. package/docs/release.md +79 -0
  12. package/docs/stage4-slice1-manual-test.md +259 -0
  13. package/docs/stage4-slice1-user-guide.md +269 -0
  14. package/docs/user-guide-ko.md +452 -0
  15. package/package.json +76 -0
  16. package/scripts/install-llmwiki.ps1 +229 -0
  17. package/src/config.js +74 -0
  18. package/src/curator/browser-data.js +134 -0
  19. package/src/curator/queue.js +324 -0
  20. package/src/curator/schema.js +237 -0
  21. package/src/curator/scoring.js +83 -0
  22. package/src/hooks.js +199 -0
  23. package/src/librarian/schema.js +218 -0
  24. package/src/librarian/weekly-digest.js +478 -0
  25. package/src/security.js +127 -0
  26. package/src/server.js +860 -0
  27. package/src/stage4/graph-reasoning/analyzer.js +255 -0
  28. package/src/stage4/graph-reasoning/browser-data.js +130 -0
  29. package/src/stage4/graph-reasoning/index.js +35 -0
  30. package/src/stage4/graph-reasoning/loader.js +122 -0
  31. package/src/stage4/graph-reasoning/queue.js +154 -0
  32. package/src/stage4/graph-reasoning/schema.js +190 -0
  33. package/src/team/browser-data.js +142 -0
  34. package/src/team/capabilities.js +79 -0
  35. package/src/team/dispatch.js +108 -0
  36. package/src/team/queue.js +290 -0
  37. package/src/team/schema.js +225 -0
  38. package/src/team/shared-memory.js +183 -0
  39. package/src/todo/browser-data.js +71 -0
  40. package/src/todo/queue.js +159 -0
  41. package/src/todo/schema.js +90 -0
  42. package/src/utils/embedding-model.js +111 -0
  43. package/src/wiki/alias-suggestions.js +180 -0
  44. package/src/wiki/browser-data.js +284 -0
  45. package/src/wiki/doctor.js +218 -0
  46. package/src/wiki/entry-normalizer.js +139 -0
  47. package/src/wiki/ingest.js +443 -0
  48. package/src/wiki/lesson-proposal-analyzer.js +463 -0
  49. package/src/wiki/lesson-proposal-manager.js +331 -0
  50. package/src/wiki/lesson-template.js +182 -0
  51. package/src/wiki/lint.js +294 -0
  52. package/src/wiki/notebooklm-adapter.js +264 -0
  53. package/src/wiki/query.js +304 -0
  54. package/src/wiki/raw-manager.js +400 -0
  55. package/src/wiki/search-feedback.js +211 -0
  56. package/src/wiki/semantic-index.js +333 -0
  57. package/src/wiki/semantic-search.js +170 -0
  58. package/src/wiki/source-ledger.js +370 -0
  59. package/src/wiki/store.js +1329 -0
  60. package/src/wiki/usage-events.js +144 -0
@@ -0,0 +1,141 @@
1
+ # Stage 2 Agent Team Workbench 가이드
2
+
3
+ > **Deprecated**: Agent Team Workbench는 기존 Stage 2 artifact 호환을 위해 보존됩니다. 새 작업 관리에는 Phase 1의 **Simple TODO**(`llmwiki todo ...`)를 사용하세요.
4
+
5
+ > 이 문서는 LLM Wiki v2 **Stage 2**의 사용자용 설명입니다. 핵심 이름은 **Agent Team Workbench**이고, 목적은 여러 에이전트에게 일을 “몰래 실행”시키는 것이 아니라 사람이 검토할 수 있는 **dispatch packet**과 **evidence** 흐름을 안전하게 만드는 것입니다.
6
+
7
+ ## 1. 한 줄 요약
8
+
9
+ Stage 2는 로컬 wiki 위에 다음 기능을 추가합니다.
10
+
11
+ - `agent profiles`와 `agent groups`로 작업자 유형을 정의합니다.
12
+ - Kanban 방식의 로컬 queue로 작업 상태를 관리합니다.
13
+ - 승인된 작업만 dispatch packet으로 만들고, 사용자가 복사해서 다른 agent 세션에 붙여넣습니다.
14
+ - 결과는 evidence note로 다시 가져와 사람이 검토합니다.
15
+ - `capability` gate가 shell, browser, network, Git push, promote/reject, sync 같은 위험 행동을 기본 차단합니다.
16
+
17
+ ## 2. 기본 원칙: 승인 기반 자동화
18
+
19
+ Stage 2의 기본값은 **승인 우선**입니다.
20
+
21
+ 1. task card를 만듭니다.
22
+ 2. 사람이 목표, 성공 기준, 요청 capability를 확인합니다.
23
+ 3. 승인 metadata가 붙은 task만 dispatch packet이 됩니다.
24
+ 4. dispatch packet은 실행기가 아니라 복사 가능한 문서입니다.
25
+ 5. 다른 agent가 작업한 뒤 evidence를 붙이고 Workbench에서 검토합니다.
26
+
27
+ 즉, Workbench는 “시동 버튼”이 아니라 “검토대와 서류철”에 가깝습니다.
28
+
29
+ ## 3. agent profiles / agent groups 설정
30
+
31
+ `agent profiles`는 각 작업자 프로필입니다.
32
+
33
+ | scope | 의미 | 기본 성격 |
34
+ |---|---|---|
35
+ | `main` | 현재 OpenCode 주 작업자 | 읽기와 dispatch artifact 작성 중심 |
36
+ | `sub` | Oracle, reviewer 같은 보조 agent | 읽기/검토 중심, 위험 행동 기본 차단 |
37
+ | `custom` | 사용자가 직접 정의한 agent | policy에 따라 허용/승인/차단 capability를 조절 |
38
+
39
+ `agent groups`는 여러 profile을 묶은 팀입니다. 예를 들어 `core-team`은 main builder와 sub reviewer를 함께 보여주는 기본 그룹입니다.
40
+
41
+ CLI로는 다음처럼 로컬 profile/group artifact를 만들 수 있습니다. 이 명령도 agent를 실행하지 않고 queue 설정 파일만 갱신합니다.
42
+
43
+ ```bash
44
+ llmwiki team create-profile --id custom-codex --title "Custom Codex" --kind codex --scope custom --role builder --allowed read,dispatch --requires-approval shell,browser --denied git_push,direct_agent_message
45
+ llmwiki team create-group --id custom-group --title "Custom Group" --profiles main-opencode,custom-codex --policy approval-first
46
+ ```
47
+
48
+ ## 4. role과 queue 상태
49
+
50
+ role은 “무슨 역할로 일할지”를 설명합니다.
51
+
52
+ - `builder`: 승인된 task를 구현하고 evidence를 반환합니다.
53
+ - `reviewer`: 산출물을 읽고 빠진 점을 검토합니다.
54
+
55
+ queue 상태는 다음 순서로 사용합니다.
56
+
57
+ ```text
58
+ proposed -> approved -> dispatched -> evidence -> review -> done
59
+ \-> blocked
60
+ ```
61
+
62
+ - `proposed`: 아직 승인 전입니다.
63
+ - `approved`: 사람이 승인했습니다.
64
+ - `dispatched`: dispatch packet artifact가 만들어졌습니다.
65
+ - `evidence`: 작업 결과 evidence가 들어왔습니다.
66
+ - `review`: 사람이 검토 중입니다.
67
+ - `done`: 완료입니다.
68
+ - `blocked`: 승인, 정보, 범위 문제로 멈춘 상태입니다.
69
+
70
+ ## 5. dispatch packet 복사/붙여넣기 흐름
71
+
72
+ CLI 예시는 다음과 같습니다.
73
+
74
+ ```bash
75
+ llmwiki team create-task --id task-docs --title "Docs task" --goal "Write Stage 2 docs" --criteria "Guide exists"
76
+ llmwiki team approve task-docs --approved-by user --approved-capabilities read
77
+ llmwiki team generate-packet task-docs --json
78
+ llmwiki team evidence task-docs --summary "Manual evidence reviewed" --artifact .system/agent-team/dispatch-packets/packet-task-docs-main-opencode.json
79
+ ```
80
+
81
+ 생성된 dispatch packet에는 다음이 들어갑니다.
82
+
83
+ - task 목표와 성공 기준
84
+ - role과 agent profile
85
+ - 허용 capability와 금지 capability
86
+ - wiki-backed shared memory 참조
87
+ - “자동 실행하지 말고 evidence를 반환하라”는 안전 지시
88
+
89
+ 사용자는 packet 내용을 복사해 다른 agent 세션에 붙여넣습니다. Stage 2 자체는 agent를 자동 실행하지 않습니다.
90
+
91
+ ## 6. capability gate
92
+
93
+ `capability` gate는 agent profile별로 세 범주를 둡니다.
94
+
95
+ - `allowed`: 기본 허용
96
+ - `requires_approval`: 명시 승인이 있어야 허용
97
+ - `denied`: 항상 차단
98
+
99
+ 기본적으로 shell, Git push, browser automation, network, promote/reject, sync, wiki 밖 쓰기, direct agent-to-agent communication은 위험 capability로 취급됩니다.
100
+
101
+ ## 7. wiki-backed shared memory
102
+
103
+ task card는 wiki entry path, graph id, query 같은 참조를 가질 수 있습니다. dispatch packet은 원문 전체를 무작정 넣지 않고, 필요한 참조와 제한된 context만 사용합니다.
104
+
105
+ 중요한 규칙은 다음과 같습니다.
106
+
107
+ - rejected, superseded, private, needs-clarification 상태 entry는 일반 context에서 제외합니다.
108
+ - 검색 결과는 “untrusted reference knowledge”로 취급합니다.
109
+ - graph/related 참조는 board data의 `relation_edges`로 요약되어 Workbench가 연결 관계를 보여줄 수 있습니다.
110
+ - evidence도 자동 lesson 승격 없이 검토 대상 artifact로 남깁니다.
111
+
112
+ ## 8. VS Code Workbench 사용
113
+
114
+ VS Code command palette에서 **Open Agent Team Workbench**를 실행하면 다음을 볼 수 있습니다.
115
+
116
+ - Kanban queue
117
+ - agent profiles / agent groups
118
+ - role filter와 capability badge
119
+ - dispatch packet preview와 copy 버튼
120
+ - blocked reason
121
+ - evidence review 영역
122
+ - task별 Approve, Block task, Generate packet, Attach evidence, Mark review 동작
123
+
124
+ 쓰기 성격의 동작은 VS Code Workspace Trust가 필요합니다. copy는 로컬 clipboard 동작이고 dispatch packet을 실행하지 않습니다.
125
+
126
+ ## 9. Stage 2가 하지 않는 것
127
+
128
+ Stage 2는 아래를 하지 않습니다.
129
+
130
+ - 숨은 agent worker pool 실행
131
+ - agent끼리 직접 메시지 주고받기
132
+ - shell/Git/browser/network 자동 실행
133
+ - auto-push
134
+ - auto-promotion
135
+ - remote embedding, hosted team cloud, marketplace, 결제 기능
136
+
137
+ ## 10. Stage 3 / Stage 4 경계
138
+
139
+ `Stage 3`은 Hermes-like Conversational Growth 같은 미래 범위입니다. `Stage 4`는 Personal/Team AI OS 같은 더 큰 미래 범위입니다.
140
+
141
+ 현재 구현은 Stage 2 Workbench와 artifact review에 한정됩니다. Stage 3과 Stage 4 기능은 문서상 로드맵으로만 남아 있습니다.
@@ -0,0 +1,50 @@
1
+ # Stage 3 Conversational Growth MVP Guide
2
+
3
+ Stage 3 adds a **Curator Workbench** for turning solved work into review-required lesson proposals.
4
+
5
+ ## What Stage 3 does
6
+
7
+ - Creates local lesson candidate artifacts under `.system/curator/lesson-candidates/`.
8
+ - Creates local consolidation proposal packets under `.system/curator/consolidation-proposals/`.
9
+ - Adds scoring hints: `importance`, `recency`, and `trust`.
10
+ - Adds a curator queue and audit log for review.
11
+ - Shows Curator data in VS Code through `Open Curator Workbench`.
12
+
13
+ ## What Stage 3 does not do
14
+
15
+ - It does not run a Hermes agent or any hidden background curator.
16
+ - It does not auto-promote lessons.
17
+ - It does not merge, delete, or clean up wiki entries automatically.
18
+ - It does not install or apply generated skills.
19
+ - It does not push Git or sync anything by itself.
20
+
21
+ ## CLI quickstart
22
+
23
+ ```powershell
24
+ node bin/llmwiki.js curator list --wiki-root C:\path\to\wiki --json
25
+
26
+ node bin/llmwiki.js curator suggest-lesson `
27
+ --wiki-root C:\path\to\wiki `
28
+ --source inbox/solved-example.md `
29
+ --related inbox/related-example.md `
30
+ --title "Reusable lesson candidate" `
31
+ --json
32
+
33
+ node bin/llmwiki.js curator propose-consolidation `
34
+ --wiki-root C:\path\to\wiki `
35
+ --entries inbox/solved-example.md,inbox/related-example.md `
36
+ --rationale "These entries overlap and should be reviewed together." `
37
+ --json
38
+ ```
39
+
40
+ ## VS Code flow
41
+
42
+ 1. Run `llmwiki rebuild --browser-data` or any curator CLI action that refreshes browser data.
43
+ 2. Open Command Palette.
44
+ 3. Run `LLM Wiki: Open Curator Workbench`.
45
+ 4. Review queue cards, scoring hints, lesson candidates, and consolidation proposals.
46
+ 5. Use buttons only when you want to create another local proposal artifact.
47
+
48
+ ## Safety model
49
+
50
+ Stage 3 is a proposal system, not an execution system. Scores help decide what to review first, but scores never approve anything. Source wiki entries remain unchanged when lesson candidates or consolidation proposals are created.
@@ -0,0 +1,120 @@
1
+ # 🧪 실사용 테스트 워크시트
2
+
3
+ > 이 워크시트를 복사해서 OpenCode 채팅에 붙여넣기만 하면 됩니다.
4
+
5
+ ---
6
+
7
+ ## 테스트 준비 확인
8
+
9
+ - [ ] oh-my-llmwikimode 플러그인이 OpenCode에 설치됨
10
+ - [ ] 위키 폴드가 생성됨 (`~/Documents/llm-wiki/`)
11
+
12
+ **아직 안 됐으면 채팅에 말하세요:**
13
+ > "oh-my-llmwikimode 플러그인 설치하고 위키 폴드 만들어줘"
14
+
15
+ ---
16
+
17
+ ## 테스트 1: 기본 검색 (30초)
18
+
19
+ **채팅에 붙여넣기:**
20
+ ```
21
+ 내 위키에 뭐가 있는지 확인해줘
22
+ ```
23
+
24
+ **예상 결과:**
25
+ - 메모 개수 알림
26
+ - 최근 메모 목록 (있으면)
27
+
28
+ **체크:**
29
+ - [ ] 위키 상태가 정상적으로 보고됨
30
+ - [ ] 오류 없음
31
+
32
+ ---
33
+
34
+ ## 테스트 2: 메모 저장 (1분)
35
+
36
+ **채팅에 붙여넣기:**
37
+ ```
38
+ 테스트 메모 저장해줘: Docker Compose 볼륨 문제는 docker compose down -v로 해결 가능
39
+ 태그는 docker, compose, troubleshooting으로 해줘
40
+ ```
41
+
42
+ **예상 결과:**
43
+ - "저장 완료: inbox/2026-...-docker-compose-..." 알림
44
+
45
+ **체크:**
46
+ - [ ] 저장 완료 메시지 받음
47
+ - [ ] 파일 경로가 inbox/ 아래에 생성됨
48
+
49
+ ---
50
+
51
+ ## 테스트 3: 메모 검색 (30초)
52
+
53
+ **채팅에 붙여넣기:**
54
+ ```
55
+ Docker Compose 볼륨 문제 해결 방법 위키에서 찾아줘
56
+ ```
57
+
58
+ **예상 결과:**
59
+ - 방금 저장한 메모가 검색 결과로 나옴
60
+ - 제목, 태그, 내용 요약 표시
61
+
62
+ **체크:**
63
+ - [ ] 방금 저장한 메모가 결과에 포함됨
64
+ - [ ] 내용이 정확함
65
+
66
+ ---
67
+
68
+ ## 테스트 4: Stage 4 그래프 분석 (1분)
69
+
70
+ **채팅에 붙여넣기:**
71
+ ```
72
+ 내 위키에서 연결 안 된 메모 찾아줘
73
+ ```
74
+
75
+ **예상 결과:**
76
+ - orphaned_entry_review 결과
77
+ - "이 메모는 다른 메모와 연결이 안 되어 있어요" 형태
78
+
79
+ **체크:**
80
+ - [ ] 분석 결과가 나옴
81
+ - [ ] insight가 1개 이상
82
+
83
+ ---
84
+
85
+ ## 테스트 5: 큐레이터 기능 (1분)
86
+
87
+ **채팅에 붙여넣기:**
88
+ ```
89
+ 방금 저장한 Docker 메모를 레슨 후보로 제안해줘
90
+ ```
91
+
92
+ **예상 결과:**
93
+ - 큐레이터 대기열에 제안 추가
94
+ - 사용자 승인 필요하다고 알림
95
+
96
+ **체크:**
97
+ - [ ] 제안이 생성됨
98
+ - [ ] 자동 실행되지 않음 (승인 필요)
99
+
100
+ ---
101
+
102
+ ## 피드백
103
+
104
+ ### 잘 된 점
105
+ (자유롭게 작성)
106
+
107
+ ### 안 된 점 / 오류
108
+ (있으면 채팅 내용 복사해서 붙여넣기)
109
+
110
+ ### 불편한 점
111
+ (어떤 말을 했을 때 AI가 이해를 못 했는지, 결과가 이상했는지)
112
+
113
+ ### 추가로 필요한 기능
114
+ (있으면 작성)
115
+
116
+ ---
117
+
118
+ ## 제출
119
+
120
+ 이 워크시트를 OpenCode 채팅에서 공유하거나, GitHub Issue에 남겨주세요.
@@ -0,0 +1,53 @@
1
+ # Private GitHub Bootstrap
2
+
3
+ This document prepares the first private GitHub upload for `oh-my-llmwikimode`.
4
+ It is a runbook only; do not run the side-effecting steps until explicitly
5
+ approved.
6
+
7
+ ## Target
8
+
9
+ ```text
10
+ Owner: wjdtmddn325-maker
11
+ Repository: oh-my-llmwikimode
12
+ Visibility: private
13
+ Repository root: plugins/oh-my-llmwikimode/
14
+ ```
15
+
16
+ ## Current readiness
17
+
18
+ - GitHub CLI authentication is available for `wjdtmddn325-maker`.
19
+ - `wjdtmddn325-maker/oh-my-llmwikimode` does not exist yet.
20
+ - The package verifies locally with `npm run verify`.
21
+ - The release job is gated by `vars.ENABLE_RELEASE == 'true'` so the first
22
+ private push runs verification but does not publish to npm.
23
+ - `.gitignore` excludes dependencies, logs, secrets, local wiki state, and
24
+ generated artifacts.
25
+
26
+ ## Bootstrap sequence
27
+
28
+ Run these commands from `plugins/oh-my-llmwikimode/` only after approval:
29
+
30
+ ```powershell
31
+ git init -b main
32
+ git add .
33
+ git commit -m "chore: bootstrap oh-my-llmwikimode"
34
+ gh repo create wjdtmddn325-maker/oh-my-llmwikimode --private --source=. --remote=origin --push
35
+ ```
36
+
37
+ ## Post-upload checks
38
+
39
+ 1. Confirm the GitHub repository visibility is private.
40
+ 2. Confirm the `Verify` GitHub Actions job passes.
41
+ 3. Confirm the `Semantic Release` job is skipped while `ENABLE_RELEASE` is
42
+ unset.
43
+ 4. Do not add `NPM_TOKEN` or set `ENABLE_RELEASE=true` until npm publishing is
44
+ intentionally approved.
45
+
46
+ ## Later release enablement
47
+
48
+ When ready for the first automated npm release:
49
+
50
+ 1. Add repository secret `NPM_TOKEN`.
51
+ 2. Add repository variable `ENABLE_RELEASE=true`.
52
+ 3. Push a Conventional Commit to `main`.
53
+ 4. Confirm semantic-release creates the GitHub Release and npm package.
@@ -0,0 +1,79 @@
1
+ # Release Runbook
2
+
3
+ This project uses `semantic-release` in GitHub Actions.
4
+
5
+ ## Required Secrets
6
+
7
+ - `NPM_TOKEN`: npm automation token with publish permission for `oh-my-llmwikimode`.
8
+ - `GITHUB_TOKEN`: provided by GitHub Actions automatically.
9
+
10
+ ## Required Repository Variables
11
+
12
+ - `ENABLE_RELEASE`: set to `true` only after the private GitHub repository,
13
+ npm package ownership, and `NPM_TOKEN` are ready.
14
+
15
+ The release job is intentionally disabled by default for the first private repo
16
+ push. Verification still runs on pushes and pull requests, but semantic-release
17
+ will not publish until `ENABLE_RELEASE=true` is configured.
18
+
19
+ ## Required Permissions
20
+
21
+ The release workflow requires:
22
+
23
+ - `contents: write`
24
+ - `issues: write`
25
+ - `pull-requests: write`
26
+ - `id-token: write` for npm provenance
27
+
28
+ ## Commit Convention
29
+
30
+ - `fix:` creates a patch release.
31
+ - `feat:` creates a minor release.
32
+ - `BREAKING CHANGE:` creates a major release.
33
+
34
+ ## Release Flow
35
+
36
+ 1. Push to `main`.
37
+ 2. CI installs dependencies with `npm ci`.
38
+ 3. CI runs `npm test`, `npm run verify:docs`, and `npm run verify:package`.
39
+ 4. If `ENABLE_RELEASE=true`, `semantic-release` analyzes commits.
40
+ 5. If a release is needed, it updates `CHANGELOG.md`, `package.json`, and `package-lock.json`.
41
+ 6. CI publishes to npm and creates a GitHub Release.
42
+
43
+ ## Private GitHub Bootstrap
44
+
45
+ For the initial private GitHub upload:
46
+
47
+ 1. Create `wjdtmddn325-maker/oh-my-llmwikimode` as a **private** repository.
48
+ 2. Push the verified package root as the repository root.
49
+ 3. Confirm the `Verify` job passes.
50
+ 4. Keep `ENABLE_RELEASE` unset until npm publishing is intentionally enabled.
51
+ 5. Add `NPM_TOKEN`, then set `ENABLE_RELEASE=true` only when ready for the
52
+ first automated release.
53
+
54
+ See `docs/github-private-bootstrap.md` for the exact private-repo bootstrap
55
+ sequence.
56
+
57
+ ## Dry Run
58
+
59
+ ```bash
60
+ npm run release:dry-run
61
+ ```
62
+
63
+ This command must not publish to npm or create a GitHub Release.
64
+ When the private GitHub remote or release credentials are not configured, the
65
+ command validates the release config/workflow and skips semantic-release itself.
66
+ Set `NPM_TOKEN` and either `GH_TOKEN` or `GITHUB_TOKEN` to run the local
67
+ semantic-release dry run.
68
+
69
+ ## Rollback
70
+
71
+ If a bad release is published:
72
+
73
+ 1. Do not delete git tags unless the release never left npm.
74
+ 2. Publish a new `fix:` commit that reverts or repairs the behavior.
75
+ 3. If the package contains sensitive data, revoke exposed credentials immediately and follow npm support guidance.
76
+
77
+ ## Runtime Boundary
78
+
79
+ The runtime plugin must never modify its own source, version, changelog, documentation, GitHub release, or npm publish state. Release automation belongs only to CI.
@@ -0,0 +1,259 @@
1
+ # Stage 4 Slice 1 — 실사용 테스트 가이드
2
+
3
+ > 이 문서는 **사용자가 직접** 실제 위키 데이터로 Stage 4 그래프 추론 기능을 테스트하는 방법을 설명합니다.
4
+
5
+ ---
6
+
7
+ ## 사전 준비
8
+
9
+ ### 1. 실제 위키가 있어야 함
10
+
11
+ 최소 **5개 이상**의 마크다운 항목이 `inbox/` 또는 `problems/` 폴더에 있어야 다양한 insight가 나옵니다.
12
+
13
+ ```
14
+ ~/Documents/llm-wiki/
15
+ ├── inbox/
16
+ │ ├── 2026-05-01-bug-report.md
17
+ │ ├── 2026-05-02-feature-idea.md
18
+ │ └── 2026-05-03-learning-note.md
19
+ ├── problems/
20
+ │ └── 2026-04-20-known-issue.md
21
+ └── editorial/
22
+ └── lessons/
23
+ └── 2026-03-15-best-practice.md
24
+ ```
25
+
26
+ > 위키가 없다면, 일단 5~10개 정도 아무 내용이나 넣고 시작하세요. 내용은 상관없습니다.
27
+
28
+ ### 2. 그래프가 최신 상태여야 함
29
+
30
+ 분석 전에 반드시 그래프를 리빌드:
31
+
32
+ ```powershell
33
+ cd plugins/oh-my-llmwikimode
34
+ node bin/llmwiki.js rebuild --wiki-root "C:\Users\USER\Documents\llm-wiki"
35
+ ```
36
+
37
+ > `--wiki-root`를 생략하면 기본값 `~/Documents/llm-wiki`를 사용합니다.
38
+
39
+ ---
40
+
41
+ ## 테스트 1: 그래프 추론 분석 실행
42
+
43
+ ### 명령어
44
+
45
+ ```powershell
46
+ node bin/llmwiki.js stage4 graph-reasoning analyze --wiki-root "C:\Users\USER\Documents\llm-wiki" --json
47
+ ```
48
+
49
+ ### 예상 출력
50
+
51
+ ```json
52
+ {
53
+ "success": true,
54
+ "wikiRoot": "C:\\Users\\USER\\Documents\\llm-wiki",
55
+ "insight_count": 3,
56
+ "artifacts": [
57
+ ".system/stage4/graph-reasoning/insights/insight-orphaned-inbox-2026-05-01-bug-report-md-xxxxxxxx.json",
58
+ ".system/stage4/graph-reasoning/insights/insight-high-conn-editorial-lessons-2026-03-15-best-practice-md-xxxxxxxx.json",
59
+ ".system/stage4/graph-reasoning/insights/insight-stale-inbox-2026-04-20-known-issue-md-xxxxxxxx.json"
60
+ ],
61
+ "audit": {
62
+ "timestamp": "2026-05-08T16:45:30.123Z",
63
+ "action": "run_analysis",
64
+ "actor": "cli",
65
+ "subject_id": "analysis-run",
66
+ "artifact_path": "",
67
+ "source_paths": [],
68
+ "executed": false
69
+ },
70
+ "message": "Graph reasoning analysis completed: 3 insight(s) generated."
71
+ }
72
+ ```
73
+
74
+ ### 확인할 것
75
+
76
+ - [ ] `insight_count`가 0이 아닌가? (0이면 위키 항목이 너무 적거나 연결 고리가 없음)
77
+ - [ ] `artifacts` 배열에 파일 경로가 있는가?
78
+ - [ ] `audit` 객체가 존재하고 `action: "run_analysis"`인가?
79
+ - [ ] `executed: false`로 되어 있는가? (자동 실행 금지 확인)
80
+
81
+ ---
82
+
83
+ ## 테스트 2: 생성된 Insight 직접 열어보기
84
+
85
+ ### 명령어
86
+
87
+ ```powershell
88
+ # 생성된 insight 파일 목록 확인
89
+ Get-ChildItem "C:\Users\USER\Documents\llm-wiki\.system\stage4\graph-reasoning\insights"
90
+
91
+ # 특정 insight 내용 확인 (파일명은 실제 출력과 다를 수 있음)
92
+ Get-Content "C:\Users\USER\Documents\llm-wiki\.system\stage4\graph-reasoning\insights\insight-orphaned-*.json" | ConvertFrom-Json
93
+ ```
94
+
95
+ ### 확인할 것
96
+
97
+ - [ ] `review_status`가 `"review_required"`인가?
98
+ - [ ] `review_only`가 `true`인가?
99
+ - [ ] `boundaries.executed`가 `false`인가?
100
+ - [ ] `boundaries.mutates_sources`가 `false`인가?
101
+ - [ ] `boundaries.auto_promotes`가 `false`인가?
102
+ - [ ] `source_paths`가 실제 내 위키 파일을 가리키는가? (예: `inbox/2026-05-01-bug-report.md`)
103
+ - [ ] `source_paths`에 `C:/Users/...` 같은 절대경로가 **없는가**?
104
+
105
+ ---
106
+
107
+ ## 테스트 3: Queue 카드와 Browser Data 확인
108
+
109
+ ### 명령어
110
+
111
+ ```powershell
112
+ # 1. Queue + browser data 조회
113
+ node bin/llmwiki.js stage4 graph-reasoning list --wiki-root "C:\Users\USER\Documents\llm-wiki" --json
114
+
115
+ # 2. browser-data.json 직접 확인
116
+ Get-Content "C:\Users\USER\Documents\llm-wiki\.system\browser-data.json" | ConvertFrom-Json | Select-Object -ExpandProperty stage4_graph_reasoning
117
+ ```
118
+
119
+ ### 확인할 것
120
+
121
+ - [ ] `queue_cards` 배열에 insight들이 있는가?
122
+ - [ ] `insights` 배열에 요약 정보가 있는가?
123
+ - [ ] `summary.insight_count`가 0이 아닌가?
124
+ - [ ] `summary.audit_count`가 1 이상인가?
125
+ - [ ] `queue_cards`의 각 카드가 `status: "review_required"`인가?
126
+
127
+ ---
128
+
129
+ ## 테스트 4: Zero-Insight 상황 테스트
130
+
131
+ ### 목적
132
+
133
+ 비어 있는 그래프에서도 audit이 기록되는지 확인
134
+
135
+ ### 명령어
136
+
137
+ ```powershell
138
+ # 임시 빈 위키 만들기
139
+ $emptyWiki = "C:\Users\USER\AppData\Local\Temp\empty-wiki-test"
140
+ New-Item -ItemType Directory -Path "$emptyWiki\.system" -Force
141
+ New-Item -ItemType Directory -Path "$emptyWiki\inbox" -Force
142
+ Set-Content "$emptyWiki\.system\graph.json" '{"nodes":[],"edges":[],"communities":[],"meta":{"built_at":"2026-05-08T00:00:00.000Z"}}'
143
+
144
+ # 분석 실행
145
+ node bin/llmwiki.js stage4 graph-reasoning analyze --wiki-root $emptyWiki --json
146
+ ```
147
+
148
+ ### 확인할 것
149
+
150
+ - [ ] `insight_count`가 0인가?
151
+ - [ ] 그럼에도 `audit` 객체가 존재하고 `action: "run_analysis"`인가?
152
+ - [ ] `.system/stage4/graph-reasoning/audit.jsonl` 파일에 기록이 추가되었는가?
153
+
154
+ ---
155
+
156
+ ## 테스트 5: 악성 아티팩트 차단 확인
157
+
158
+ ### 목적
159
+
160
+ 수동으로 악성 insight를 넣어도 browser data에서 걸러지는지 확인
161
+
162
+ ### 명령어
163
+
164
+ ```powershell
165
+ $wikiRoot = "C:\Users\USER\Documents\llm-wiki"
166
+ $insightsDir = "$wikiRoot\.system\stage4\graph-reasoning\insights"
167
+
168
+ # 악성 insight 주입 (절대경로 포함)
169
+ Set-Content "$insightsDir\malicious-test.json" -Value '{
170
+ "schema_version": 1,
171
+ "insight_id": "malicious-test",
172
+ "kind": "orphaned_entry_review",
173
+ "title": "Malicious",
174
+ "summary": "Test",
175
+ "source_paths": ["C:/Users/SECRET/secret.md"],
176
+ "evidence_refs": [{"path":"inbox/test.md","reason":"test"}],
177
+ "reasoning_hints": {"confidence":0.5},
178
+ "review_status": "review_required",
179
+ "review_only": true,
180
+ "boundaries": {"executed":false,"mutates_sources":false,"auto_promotes":false},
181
+ "created_at": "2026-05-08T00:00:00.000Z"
182
+ }'
183
+
184
+ # browser data 재생성 후 확인
185
+ node bin/llmwiki.js stage4 graph-reasoning list --wiki-root $wikiRoot --json | ConvertFrom-Json | Select-Object -ExpandProperty graph_reasoning | Select-Object -ExpandProperty insights | Where-Object { $_.id -eq "malicious-test" }
186
+ ```
187
+
188
+ ### 확인할 것
189
+
190
+ - [ ] 출력이 **비어 있어야 함** (악성 insight가 필터링되었음)
191
+ - [ ] `malicious-test.json` 파일은 디스크에 남아 있어도 browser data에는 노출되지 않음
192
+
193
+ > 테스트 후 `malicious-test.json`은 직접 삭제하세요.
194
+
195
+ ---
196
+
197
+ ## 테스트 6: 재실행 시 Determinism 확인
198
+
199
+ ### 목적
200
+
201
+ 동일한 입력에 대해 동일한 출력이 나오는지 확인
202
+
203
+ ### 명령어
204
+
205
+ ```powershell
206
+ $wikiRoot = "C:\Users\USER\Documents\llm-wiki"
207
+
208
+ # 첫 번째 실행
209
+ $result1 = node bin/llmwiki.js stage4 graph-reasoning analyze --wiki-root $wikiRoot --json | ConvertFrom-Json
210
+
211
+ # 두 번째 실행 (같은 위키, 같은 상태)
212
+ $result2 = node bin/llmwiki.js stage4 graph-reasoning analyze --wiki-root $wikiRoot --json | ConvertFrom-Json
213
+
214
+ # insight 개수 비교
215
+ $result1.insight_count -eq $result2.insight_count
216
+ # 결과: True
217
+ ```
218
+
219
+ ### 확인할 것
220
+
221
+ - [ ] 두 번 실행핏 모두 같은 `insight_count`인가?
222
+ - [ ] `artifacts` 배열의 파일명이 동일한가?
223
+
224
+ ---
225
+
226
+ ## 문제 해결
227
+
228
+ ### `insight_count: 0`이 나옴
229
+
230
+ - 위키 항목이 3개 미만인 경우 → 항목을 더 추가하세요
231
+ - `graph.json`이 없거나 비어 있음 → `rebuild` 명령어를 먼저 실행하세요
232
+ - 모든 항목이 서로 연결되어 있음 → 고립된 항목이 없으면 orphaned insight는 안 나옴
233
+
234
+ ### `audit is null`이 나옴
235
+
236
+ - `audit.jsonl` 파일에 쓰기 권한이 없음 → 위키 폴더의 권한 확인
237
+
238
+ ### CLI 명령어를 못 찾음
239
+
240
+ ```powershell
241
+ # oh-my-llmwikimode 폴드로 이동 후 실행
242
+ cd C:\Users\USER\Desktop\OpenCode_Modes\plugins\oh-my-llmwikimode
243
+ node bin/llmwiki.js stage4 graph-reasoning analyze
244
+ ```
245
+
246
+ ---
247
+
248
+ ## 다음 단계
249
+
250
+ 테스트 결과를 보고 다음 중 선택하세요:
251
+
252
+ 1. **insight가 너무 많이/적게 나옴** → 임계값 조정 (analyzer.js의 `degree >= 2`, `daysStale >= 7` 등)
253
+ 2. **새로운 insight 규칙이 필요함** → analyzer.js에 새 규칙 추가 제안
254
+ 3. **VS Code 워크벤치에서 보고 싶음** → Slice 2 (UI 확장) 구현 고려
255
+
256
+ ---
257
+
258
+ *문서 버전: Stage 4 Slice 1 (2026-05-08)*
259
+ *커밋: `66f23c8` — feat: implement Stage 4 Slice 1 personal local graph reasoning*