@staix/vault-mem 0.11.0 → 0.12.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/CHANGELOG.md +12 -0
  2. package/README.md +17 -2
  3. package/bin/vmem.js +5 -1
  4. package/package.json +2 -1
  5. package/skills/_shared/vault-adapter.md +131 -0
  6. package/skills/skill-mine/SKILL.md +52 -0
  7. package/skills/skill-mine/vocab/actions.yaml +110 -0
  8. package/skills/skill-mine/vocab/objects.yaml +123 -0
  9. package/skills/vault-connect/SKILL.md +75 -0
  10. package/skills/vault-extract/README.md +20 -0
  11. package/skills/vault-extract/SKILL.md +139 -0
  12. package/skills/vault-graph/SKILL.md +120 -0
  13. package/skills/vault-learn/SKILL.md +111 -0
  14. package/skills/vault-lint/README.md +32 -0
  15. package/skills/vault-lint/SKILL.md +137 -0
  16. package/skills/vault-lint/references/lint-output.md +97 -0
  17. package/skills/vault-lint/references/vault-scope-rules.md +26 -0
  18. package/skills/vault-lint/references/work-scope-checks.md +71 -0
  19. package/skills/vault-refactor/SKILL.md +112 -0
  20. package/skills/vault-remember/SKILL.md +38 -0
  21. package/skills/vault-rethink/README.md +15 -0
  22. package/skills/vault-rethink/SKILL.md +58 -0
  23. package/skills/vault-stats/SKILL.md +49 -0
  24. package/skills/vault-sync/README.md +15 -0
  25. package/skills/vault-sync/SKILL.md +195 -0
  26. package/skills/vault-sync/references/r4-method-evidence.md +12 -0
  27. package/skills/vault-update/SKILL.md +68 -0
  28. package/skills/vmem-status/SKILL.md +30 -0
  29. package/src/amem/host-api.ts +5 -1
  30. package/src/analysis-input.ts +15 -0
  31. package/src/analysis-types.ts +3 -1
  32. package/src/assertion-policy.ts +4 -2
  33. package/src/assertions.ts +48 -8
  34. package/src/cli-output.ts +10 -3
  35. package/src/cli.ts +29 -3
  36. package/src/commands-table.ts +3 -1
  37. package/src/config.ts +21 -7
  38. package/src/enrichment-query.ts +65 -0
  39. package/src/enrichment-search.ts +69 -0
  40. package/src/enrichment-store.ts +197 -0
  41. package/src/enrichment.ts +245 -0
  42. package/src/graph-evidence.ts +2 -2
  43. package/src/index.ts +9 -0
  44. package/src/mcp-vault.ts +46 -8
  45. package/src/proposal-provider.ts +3 -2
  46. package/src/proposals.ts +10 -4
  47. package/src/read-output.ts +1 -1
  48. package/src/registry.ts +57 -2
  49. package/src/setup.ts +12 -3
  50. package/src/skills-install.ts +216 -0
  51. package/src/ui/panel-types.ts +55 -0
  52. package/src/ui/panel.js +76 -0
  53. package/src/ui/plugin.ts +95 -5
  54. package/src/vault-graph.ts +15 -7
  55. package/src/vault-index.ts +17 -0
  56. package/src/vault-lint.ts +12 -4
  57. package/src/write-operations.ts +38 -1
  58. package/src/write-types.ts +1 -0
  59. package/src/write-validation.ts +2 -1
  60. package/src/writer.ts +1 -1
@@ -0,0 +1,26 @@
1
+ # vault 스코프 판정 규칙 (L01, L02, L03, L09~L15)
2
+
3
+ `vmem lint`가 구현한 판정 규칙의 요약. finding을 설명하거나 수정 제안을 쓸 때, `note=<path>` 결과를 판정할 때 기준으로 쓴다.
4
+
5
+ - **L01**: 본문 `[[x]]` + frontmatter wiki-link 필드(`topics`·`project`·`projects`·`supersedes`·`superseded_by`; alias `[[name|display]]`는 `name`만)가 `notes/<x>.md`로 해소되지 않으면 error. 각 finding은 존재하는 노트 중 최대 하나를 `suggested <path>`(title 검색 점수)로 제안하므로, 수정 제안은 그 후보를 먼저 검토하고 없을 때만 직접 찾는다. **MOC 정책**: `topics:`는 MOC만 허용, 키워드 wiki-link는 L01 error(동일 가드: vault-extract §Preconditions, vault_adapter §Summary To Vault Fields)
6
+ - **L02**: `type` ∈ `insight | decision | observation | person | project | method | moc | reference`; `topics` 필수(단 `type: moc`는 `topics` 미요구 + `description` 필수); `confidence` ∈ `proven | likely | experimental`, `status` ∈ `active | superseded | archived`, **값이 있을 때만** 검사(없으면 통과). `status`는 노트 생애주기이지 사업 진행 상태가 아니다(작업 상태는 본문에). 정보 줄: `status: superseded` 건수(0이면 supersede 프로토콜 미가동 표시)
7
+ - **L03**: topics 0 AND in-link 0 → orphan. **hub MOC `notes/index.md`는 예외**(3-tier 루트, 설계상 in-link·topics 없음). 도메인 MOC는 예외 아님
8
+ - **L09**: 아래 §L09 참조
9
+ - **L10**: `project:` 값이 `[[x]]`면 `notes/x.md` 실존, plain이면 registry id, 둘 다 아니면 warn
10
+ - **L11**: 최신 `graph-report-YYMMDD.md`가 7일 초과/부재 → warn(`/vault-graph build` 권장)
11
+ - **L13**: 파일명이 소문자 ASCII kebab-case가 아니면 error. 이름 변경은 `vmem move`(legacy 이름 원본 허용)
12
+ - **L14**: frontmatter `source:` 경로가 해소되지 않으면 warn
13
+ - **L15**: `confidence: proven`인데 `source`가 비어 있으면 warn — 근거(memory id·URL·workspace 경로)를 넣거나 confidence를 낮춘다. `--note` 스코프에서도 함께 필터된다
14
+ - **L12**: `vault-graph.json`에서 cross-community edge 0인 커뮤니티 → warn, **멤버 목록(≤10 + N more)으로 보고**. 커뮤니티 번호는 빌드 로컬이라 인용 금지. singleton은 정보 줄
15
+
16
+ ## L09
17
+
18
+ **L09: 로그 포맷** (스코프 정본: 워크스페이스 `ssot.ingest_chain` 규칙)
19
+
20
+ `vault/log`는 append-only라 과거 라인은 소급 수정하지 않는다(제안 조치에도 넣지 않음). warn은 **해결 가능한 신규 위반**에 한정한다:
21
+
22
+ 1. **미등록 TYPE**: 정규 12종(`INGEST ROUTE EXTRACT CONNECT DIGEST LEARN LINT TASK GRAPH SYNC RETHINK SOURCE`)에도, 정규화표(`CREATE UPDATE MIGRATE REFACTOR MERGE MOVE RELOCATE RENAME DRAFT REVIEW RESEARCH REF CLEANUP CLOSE DONE SUPERSEDED DUPLICATE SKIP EDIT CORRECT`)에도 없는 TYPE
23
+ 2. **구조 위반**: `YYYY-MM-DD HH:MM TYPE ...` 형태가 아닌 라인(불릿 접두, 시각 컬럼 누락 등; 경계 위반 라인도 여기서 잡힌다)
24
+ 3. 라인 수 20k 초과 → "수동 아카이브 권장"
25
+
26
+ 정규화표 등재 legacy TYPE은 warn이 아니라 **정보 1줄**(건수 + 최종 사용일 + "신규 발생 없음")로만 표기한다.
@@ -0,0 +1,71 @@
1
+ # work 스코프 검사 (L04, L06, L07, L08)
2
+
3
+ - `work/project-registry.yaml`, `Glob work/**/*-summary.md` (L06), `Glob work/**/*` (L07, L08), `Glob <ideation>/seeds/*.md` (L04)
4
+
5
+ **L04: stale seed**
6
+ 1. `Glob <ideation>/seeds/*.md` + vault 쪽 ideation 노트 (있으면)
7
+ 2. 각 파일 mtime 확인 (work은 Bash stat, vault 노트는 `vmem_list`가 주는 `mtime`, `reports/`·`ops/` 파일은 `vmem_list_files`)
8
+ 3. 현재 - mtime > `scratchpad.ideation_review_days`(기본 90) → 위반
9
+
10
+ **L06: 신 스키마 불일치 (marker-based scope)**
11
+
12
+ inbox summary 스키마 강제는 inbox item에서 만든 파일에만 적용한다. **검사 대상 식별 marker는 frontmatter 존재 여부**.
13
+
14
+ 1. `Glob work/**/*-summary.md`
15
+ 2. 각 파일 Read → 첫 줄 `---` 확인
16
+ 3. **`---` 없음 → 스킵** (inbox-process 출력 아님, 사람 손작업 회고/리뷰/refs 등)
17
+ 4. `---` 있음 → frontmatter 파싱 → 필수 필드 누락 시 → warn
18
+ - 필수: `title`, `received`, `type`, `project`
19
+ - 출처 필수 (택1): `source` (inbox 경유) **또는** `source_url`/`source_detail_url` (웹 직접 참조). 둘 다 없으면 위반.
20
+ 5. 구 포맷 H1 + `- **원본**:` 블록 검사는 폐기 (marker-based scope에서 자연 제외)
21
+
22
+ **L07: 명명 규칙**
23
+ 1. `Glob work/**/*` (서브모듈 제외, 예외 파일/경로 제외, §Legacy Exemptions 참조)
24
+ 2. 파일명이 `YYMMDD-[a-z0-9][a-z0-9-]*\.[a-z]+` 패턴에 맞는지
25
+ 3. 예외: `README.md`, `AGENTS.md`, `CLAUDE.md`, `INDEX.md`, `.git*`, `_guides/*`, `_templates/*`, `templates/*`, 회의록(`YYMMDD-meeting-<slug>.md` 영문 패턴)
26
+ 4. 패턴 위반 → 위반 (단 Legacy Exemptions 경로는 제외)
27
+
28
+ **L08: 한글 파일명**
29
+ 1. `Glob work/**/*` 결과에서 파일명 또는 경로에 `[가-힣]` 포함 여부
30
+ 2. 있으면 → 위반
31
+ 3. 예외 (§Legacy Exemptions 참조): `trips/**`, legacy 계약/MOU/연구 과제 경로
32
+ 4. `meetings/**` 는 **무조건 면제하지 않는다**. 날짜 게이트 적용 (워크스페이스 `ssot.rules`의 naming-and-placement 규칙이 권위):
33
+ legacy 회의록(mtime/파일명 날짜가 2026-05-26 이전, 또는 신규 `YYMMDD-meeting-<slug>.md` 패턴에 맞지 않는 한글 파일)만 면제하고,
34
+ 영문화 대상(2026-05-26 이후 신규 생성 또는 마이그레이션 대상)인 한글 회의록 파일명은 여전히 위반으로 플래그한다.
35
+
36
+ ## Legacy Exemptions (L07, L08 공통)
37
+
38
+ Legacy exemptions are workspace policy, not skill-package policy. Load them from the workspace rules directory when available. If no workspace rule exists, use only generic defaults:
39
+
40
+ - hidden/runtime directories such as `.git`, `.github`, `.obsidian`, `.vscode`, `.cache`, `.venv`, `node_modules`, framework build folders, and secret stores
41
+ - generated inbox/drop or raw-source folders
42
+ - independent submodules or vendored repositories with their own naming conventions
43
+ - legally preserved originals such as contracts, signed documents, travel receipts, and external forms
44
+
45
+ These exemptions are not permission to create new badly named files. They only prevent noisy lint output for historical or tool-owned content.
46
+
47
+ **[G3] 표준 OSS 메타 파일 (filename allowlist, 어디서나 허용)**
48
+
49
+ L07 명명 규칙에서 다음 파일명은 위치 무관하게 통과 (한글 미포함이라 L08 영향 없음):
50
+
51
+ ```
52
+ README.md, README, AGENTS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
53
+ CHANGELOG.md, LICENSE, LICENSE.md, NOTICE, SECURITY.md,
54
+ CLAUDE.md, INDEX.md, _index.md,
55
+ package.json, package-lock.json, pnpm-lock.yaml, yarn.lock,
56
+ tsconfig.json, jsconfig.json, tsconfig.*.json,
57
+ requirements.txt, requirements*.txt, pyproject.toml, poetry.lock, setup.py, setup.cfg,
58
+ uv.lock, Cargo.toml, Cargo.lock, go.mod, go.sum,
59
+ Makefile, Dockerfile, docker-compose.yml, docker-compose.*.yml,
60
+ *.code-workspace,
61
+ .gitignore, .gitmodules, .gitattributes, .editorconfig, .nvmrc, .gitkeep,
62
+ .dockerignore, .npmignore, .eslintrc*, .prettierrc*,
63
+ .pre-commit-config.yaml, .coveragerc, .copier-config.yaml, .copierignore,
64
+ manifest.json, mkdocs.yml, _config.yml,
65
+ dependabot.yml, dependabot.yaml
66
+ ```
67
+
68
+ **신규 파일 규칙은 변함없다**:
69
+ - 위 경로 밖 신규 파일은 L07/L08 error
70
+ - 위 경로 내 신규 파일이라도 에이전트가 생성한 것이라면 리뷰에서 반려
71
+ - Exemption은 과거 누적분 + 도구 상태 영역에 대한 pragmatic 처리
@@ -0,0 +1,112 @@
1
+ ---
2
+ name: vault-refactor
3
+ trigger: /vault-refactor
4
+ description: "Restructure notes: split, merge, rename with vault-wide link rewrite, reorganize MOCs, promote topic MOCs (with mandatory approval gate)"
5
+ ---
6
+
7
+ # /vault-refactor [target]
8
+
9
+ > Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
10
+
11
+ Restructure vault content for better organization. **Never auto-executes** — always presents a structured plan and waits for explicit user approval.
12
+
13
+ ## Operations
14
+
15
+ - **split [note]**: Break a note into multiple atomic notes
16
+ - **merge [note1] [note2]**: Combine related notes into the `keep` note — `vmem_merge` preview then confirm (body, source/topic union, inbound-link repointing, absorbed note superseded)
17
+ - **rename [old] [new]**: Rename a note and update every reference (see §Rename). For a typo, acronym or scope change of the name; content changes use split or merge
18
+ - **moc [domain]**: Reorganize a domain MOC
19
+ - **promote [topic]**: Create topic MOC from tag cluster (20+ notes threshold)
20
+
21
+ ## Process
22
+
23
+ 1. Analyze target for refactoring opportunity
24
+ 2. **Present approval gate** (see format below)
25
+ 3. On explicit accept → execute
26
+ 4. Update all affected wiki links via `vmem_patch` (bidirectional). A merge does not need that pass: `vmem_merge(keep, absorb)` previews the merged body, the source/topic unions, the inbound-link rewrites and a fingerprint without writing, and the confirm (`confirm: true` with that fingerprint) writes the keep note, repoints every inbound link and marks the absorbed note superseded in one mutation-locked write. Use `vmem_supersede(old, next)` only when the two notes stay separate, and the two-step `vmem_delete` to retire a note with no successor. expect: vmem refuses a `vmem_merge` of different types, of a person or MOC note, of an oversized result, and an edit or delete that would newly break an inbound link or MOC topic
27
+ 5. Run `/vault-lint note=<path>` on each affected note; `--note` is CLI-only, so an MCP-only run finishes with one vault-wide `vmem_lint` instead
28
+ 6. `EXTRACT` events in `log` come from the vmem writes themselves, except a rename or merge: `vmem_move` records `ROUTE` and `vmem_merge` / `vmem_supersede` record `RETHINK` (`ingest-chain.md` §비표준 TYPE 처리)
29
+ 7. Commit the vault submodule, then bump the parent pointer
30
+
31
+ ## Approval Gate Format
32
+
33
+ Before any write, present this block to the user:
34
+
35
+ ```
36
+ REFACTOR PROPOSAL
37
+ =================
38
+ operation: split | merge | rename | moc | promote
39
+ target: <path or note name>
40
+
41
+ plan:
42
+ - action 1: <describe — source path → dest path>
43
+ - action 2: <describe>
44
+ - ...
45
+
46
+ affected notes: <count> (<list if ≤10>)
47
+ affected wiki-links: <count>
48
+ broken link risk: <low | medium | high>
49
+ reversibility: <easy | hard — explain why>
50
+
51
+ side effects:
52
+ - <MOC updates>
53
+ - <glossary mentions>
54
+ - <task file impacts>
55
+
56
+ Accept: [y]es, [n]o, [d]etails, [m]odify
57
+ ```
58
+
59
+ **Non-negotiable**: Do not write anything until the user explicitly says `y` or equivalent. `m` opens iteration — re-plan and re-present. `d` shows full affected list.
60
+
61
+ ## Rename
62
+
63
+ Runs inside the approval gate and replaces Process steps 4-6 and §Log Append: its only log line is the ROUTE line `vmem_move` records, and quality is checked by step 6 below. `plan` lists the old and new stem, the referencing notes the move will rewrite, the plain-text mentions left over and any skill sources that name the old stem.
64
+
65
+ 1. **Pre-flight**: `vmem_read` the old stem (must exist) and the new stem (must not; vmem_move also refuses an existing destination). An existing destination with a merge intent is the merge operation.
66
+ 2. **Move**: `vmem_move(from, to)` returns the preview (every wiki, heading, block and embed link and frontmatter reference it rewrites) and a fingerprint; after accept, `vmem_move(from, to, confirm: true, fingerprint)`. vmem rewrites the links in the same write and records one ROUTE line. expect: vmem refuses a stale fingerprint, an existing destination and a non-kebab-case stem. On refusal stop; nothing else runs.
67
+ 3. **Renamed note**: re-read it for a fresh sha256, then change the H1 with `vmem_patch` and a `description` that names the old stem with `vmem_set_frontmatter` (frontmatter is not patchable text).
68
+ 4. **Plain-text mentions**: `vmem_search` the old stem (up to 50 results per call; repeat until a call returns none of the not-yet-handled notes); change the remaining non-link mentions in each note with one `vmem_patch` call using `edits[]`.
69
+ 5. **Outside the vault**: skill sources and work files that name the old stem are listed for the user. Skill text changes go by PR to the skills source repo, never by editing installed skill files. Meeting source filenames stay as they are unless the user decides otherwise.
70
+ 6. **Verify**: `vmem_search` the old stem again. Allowed leftovers: history lines in `log`, graph reports regenerated by the next `/vault-graph build` (recommend that build within 7 days). Report anything else.
71
+ 7. **Failure**: if a step after the move fails, keep what succeeded and report the completed and failed edits; do not roll back automatically (a partial rename is auditable, and `vmem_patch` cannot undo a move). Undoing the whole rename is a second `vmem_move` back, proposed through the approval gate.
72
+
73
+ ## Vault Access
74
+
75
+ **Use vmem tools** through the adapter transport for all reads and writes:
76
+ - `vmem_read` / `vmem_read_many`
77
+ - `vmem_create` for new notes
78
+ - `vmem_patch` for targeted edits (preferred for link updates), `vmem_append` for new section content
79
+ - `vmem_move` for renames (rewrites vault-wide links itself; preview, then `confirm: true` with the fingerprint)
80
+ - `vmem_merge` for merges (preview carries the merged body, source/topic unions, inbound rewrites and the fingerprint; confirm with that fingerprint)
81
+ - `vmem_delete` for deletions (preview lists backlinks; then `confirm: true` with the fingerprint)
82
+
83
+ Filesystem access (Read/Write/Edit/Bash) is forbidden on vault paths.
84
+
85
+ ## Log Append
86
+
87
+ Every vmem write appends its own default `log` line. After the batch, add one summary line with `vmem_log_append(type: "RETHINK", project: "-", source: "refactor:<operation>", note: "<summary> (N notes, M links)")` whose TYPE matches the operation — `RETHINK` for merge, `EXTRACT` for split, moc or promote (no direct log-file append):
88
+
89
+ ```
90
+ YYYY-MM-DD HH:MM RETHINK - refactor:merge — <summary> (N notes, M links)
91
+ ```
92
+
93
+ - `<type>`: `RETHINK` for merge | `EXTRACT` for split, moc, promote
94
+ - `<operation>`: split | merge | moc | promote (a rename adds no summary line: its ROUTE line is the whole record)
95
+ - `<summary>`: one-line describing the change
96
+
97
+ vmem records one default line per write plus this one summary line.
98
+
99
+ ## Guards
100
+
101
+ - **NEVER auto-execute** — approval gate is mandatory
102
+ - All wiki links must be updated (no broken links after)
103
+ - Bidirectional links maintained
104
+ - MOC references updated
105
+ - If any step fails (except rename, see §Rename step 7), attempt rollback via `vmem_patch` reverse edits; if rollback fails, record `failed: <reason>` with `vmem_log_append` and stop
106
+
107
+ ## Output
108
+
109
+ - Proposed changes with reasoning (approval gate block)
110
+ - On accept: execution report (per-note status)
111
+ - `/vault-lint note=` results for all affected notes, or the final vault-wide `vmem_lint` result when only MCP is available
112
+ - log append confirmation
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: vault-remember
3
+ trigger: /vault-remember
4
+ description: Record an operational observation or methodology learning
5
+ ---
6
+
7
+ # /vault-remember [observation]
8
+
9
+ > Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
10
+
11
+ Record an observation about methodology, process, or friction for later review.
12
+
13
+ **Not for**: knowledge — facts, decisions, insights about the world or the user's projects belong in `notes/` via `/vault-learn` (approval gate + LEARN log) or `/vault-extract`. `/vault-remember` only writes `ops/observations/` entries that `/vault-rethink` consumes.
14
+
15
+ ## Input
16
+ - observation: text describing what was observed
17
+
18
+ ## Categories
19
+ - **methodology**: how the vault methodology works (or doesn't)
20
+ - **process**: workflow improvements or issues
21
+ - **friction**: points where the system feels awkward
22
+ - **surprise**: unexpected outcomes (positive or negative)
23
+ - **quality**: note quality patterns
24
+
25
+ ## Process
26
+
27
+ 1. Determine category from observation content
28
+ 2. Create timestamped entry in `ops/observations/` with `vmem_report(path: "ops/observations/<filename>", body)` (vmem screens the text and logs the write). expect: vmem refuses secret-looking text and an unsafe path
29
+ 3. Filename: YYYYMMDD-brief-description.md
30
+ 4. Content: observation text, category, context
31
+ 5. Check the observation count against the rethink threshold: read `maintenance.rethink_observations_threshold` from `ops/config.yaml` (`vmem_read_file`; default 10 when unset) and count the entries with `vmem_list_files(dir: "ops/observations")`
32
+
33
+ ## Rule Zero
34
+ The methodology is the spec. Observations accumulate evidence for methodology changes, but changes require explicit /vault-rethink review.
35
+
36
+ ## Output
37
+ - Confirmation with category and file path
38
+ - Warning if rethink threshold reached
@@ -0,0 +1,15 @@
1
+ SKILL.md is the instruction source for this skill. This file is background for maintainers; it holds no directives.
2
+
3
+ # vault-rethink background
4
+
5
+ ## Retired aging check
6
+
7
+ An earlier review step checked inline task aging and warned at a reminder-file cap. Inline tasks later moved to the workspace task files, so the step had nothing left to measure and was removed.
8
+
9
+ ## Skill list source
10
+
11
+ Drift mode used to carry a hardcoded list of the vault skills to audit. The list now comes from the bundle's `SKILL_INDEX.md` "Vault workflows" line, so adding, merging or removing a skill needs no edit here.
12
+
13
+ ## Rename workflow
14
+
15
+ Note renames moved into `/vault-refactor rename` after a rethink round found manual renames leaving stale references.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: vault-rethink
3
+ trigger: /vault-rethink
4
+ description: Review accumulated observations and tensions for methodology evolution.
5
+ ---
6
+
7
+ # /vault-rethink [mode]
8
+
9
+ > Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
10
+
11
+ Review observations, tensions, and methodology drift.
12
+
13
+ ## Modes
14
+
15
+ - **review**: Process pending observations and tensions + aging check
16
+ - **drift**: Detect configuration drift from derivation
17
+ - **full**: Complete methodology review (review + drift + aging)
18
+
19
+ ## Process
20
+
21
+ ### review mode
22
+
23
+ 1. **Observations 처리**: `ops/observations/` + `ops/tensions/` 파일 읽기 (`vmem_list_files`·`vmem_read_file`). `tensions/`는 첫 긴장 기록 전까지 디렉토리 자체가 없다 — 부재는 드리프트가 아니라 미사용 상태
24
+ 2. **Patterns 식별**: methodology·process·friction·surprise·quality 5 카테고리 그룹핑
25
+ 3. **Methodology changes 제안**: evidence 기반, `M{N}` ID 부여
26
+ 4. **Decisions 기록**: `ops/methodology/YYMMDD-rethink-report.md`를 `vmem_report(path: "ops/methodology/YYMMDD-rethink-report.md", body)`로 생성(vmem이 내용 검사 후 저장하고 기본 EXTRACT log를 남긴다). expect: vmem refuses secret-looking text and an unsafe `ops/` path (frontmatter + state snapshot + observations + tensions + proposed changes + drift check)
27
+
28
+ ### drift mode
29
+
30
+ 1. **Config ↔ Derivation 일치**: `ops/derivation.md` **§Design Dimensions 표** ↔ `ops/config.yaml` `dimensions`(8키) + `domains`(6) 를 키별로 대조. 한쪽에만 있는 키도 mismatch. 출력은 키별 match/mismatch 표 + 최종 판정(예: "8/8 dimensions + 6/6 domains match")
31
+ 2. **AGENTS.md consistency**: vault AGENTS.md·work AGENTS.md 규칙이 최신 methodology와 일치하는지
32
+ 3. **Skill SKILL.md vs 실제 사용**: spec-practice audit. 정식 스킬 목록은 스킬 번들의 `SKILL_INDEX.md` "Vault workflows" 줄에서 읽고, 그중 하나를 순환 선택하여 audit한다
33
+ 4. **Report deviations**: drift table (Check / Status / Action)
34
+
35
+ ### full mode
36
+
37
+ Review + drift 모두 실행.
38
+
39
+ ## Triggers
40
+
41
+ - 10+ unprocessed observations (`ops/config.yaml` `maintenance.rethink_observations_threshold`)
42
+ - 5+ unprocessed tensions
43
+
44
+ ## Output
45
+
46
+ - Pattern analysis from observations
47
+ - Proposed methodology changes (M{N} IDs, never auto-applied)
48
+ - Decision record if changes accepted
49
+ - Drift table (item 1은 키별 verdict 포함)
50
+
51
+ ## Rule Zero
52
+
53
+ Changes require explicit approval. This skill proposes, user decides.
54
+
55
+ ## 관련
56
+
57
+ - `ops/methodology/*-rethink-report.md` — 이전 라운드의 결정 기록 (`vmem_list_files`로 찾는다)
58
+ - `/vault-refactor rename` — note rename 워크플로우
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: vault-stats
3
+ trigger: /vault-stats
4
+ description: Show vault statistics and health, then recommend the highest-value next action
5
+ ---
6
+
7
+ # /vault-stats
8
+
9
+ > Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
10
+
11
+ Without a workspace, skip the work git scan and workspace-dependent source comparisons when unavailable, report them as skipped, and rank the remaining available conditions. Display comprehensive vault statistics, then recommend the most valuable next action from them (§Next action). `/vault-stats next` skips the full report and gives only the recommendation.
12
+
13
+ ## Metrics
14
+
15
+ 1. **Size**: total notes, by type, by domain; bytes and words per group (`vmem_stats` `size`)
16
+ 2. **MOCs**: domain MOC note counts, topic MOC list
17
+ 3. **Connections**: average links per note, orphan count/ratio
18
+ 4. **Sync lag**: days since `ops/sessions/last-sync-timestamp`
19
+ 5. **Activity**: recently created/modified notes
20
+ 6. **Growth**: notes per week/month trend
21
+ 7. **Quality**: schema compliance rate
22
+ 8. **Note-to-source ratio**: note bytes over the bytes of the workspace files the notes cite (`vmem_stats` `ratio`: median, p90, `overOne`, `largest`, and the `skipped` / `emptySourceNotes` / `truncatedNotes` caveats)
23
+
24
+ ## Process
25
+
26
+ Do not recompute what the lint/graph pipeline already produces:
27
+
28
+ 1. Size / ratio / Activity / Growth: `vmem_stats` — `size` (bytes and words, total and by type and domain), `ratio` (median and p90 of note bytes over readable source bytes, `overOne`, `largest` notes, and what the pass left out: `skipped`, `skippedNonFile`, `emptySourceNotes`, `truncatedNotes`), notes by status, notes modified in the last 7 and 30 days, log events by type; `vmem_mocs` for MOC sizes; the recently created/modified notes themselves from `vmem_log_tail`. A ratio question is answered from `ratio`, never from a hand count of source files. Growth beyond those windows: read-only vault git history, or report it as unavailable
29
+ 2. Connections (edges, density, top hubs): read the latest `reports/graph-report-YYMMDD.md` and `reports/graph-trend.md` — report totals only; neighbour or community questions go to `vmem_graph_neighbors`
30
+ 3. Orphan count, broken links, schema compliance and proven-without-source notes: run `vmem lint <vault> --json` (or `vmem_lint`) and take the L03 / L01 / L02 / L15 counts (same numbers `/vault-lint vault` reports)
31
+ 4. Read `ops/sessions/last-sync-timestamp`
32
+ 5. For the next-action conditions: notes whose `mtime` is older than 90 days from a paged `vmem_list`; observation and tension counts from `vmem_list_files` on `ops/observations` and `ops/tensions` (a directory that does not exist yet counts as 0), and their thresholds from `ops/config.yaml` (`vmem_read_file`); work files changed since the sync timestamp from a read-only `git log --since` in the workspace (count only, as `/vault-sync` Step 1B scans)
33
+ 6. Assemble metrics
34
+
35
+ ## Next action
36
+
37
+ Rank maintenance conditions from the metrics above and recommend one action:
38
+
39
+ - Orphan notes or island communities → `/vault-connect`
40
+ - Notes not updated for more than 90 days → `/vault-update`
41
+ - Work sources changed since `ops/sessions/last-sync-timestamp` → `/vault-sync` (or `/vault-sync targets` for a known list)
42
+ - Observation or tension count at or above the `ops/config.yaml` thresholds → `/vault-rethink`
43
+
44
+ Priority: 1. critical (schema violations, broken links); 2. high (unsynced work sources, orphan drift); 3. medium (stale notes, pending observations); 4. low (optimization, MOC refinement).
45
+
46
+ ## Output
47
+ - Formatted statistics report: notes and bytes/words by type and domain, note-to-source ratio (median, p90, `overOne` with its largest offenders, and the skipped/truncated counts next to them so a partial pass never reads as full coverage)
48
+ - Highlight any metrics outside healthy thresholds
49
+ - Recommended next action with reasoning, estimated effort and the command to run
@@ -0,0 +1,15 @@
1
+ SKILL.md is the instruction source for this skill. This file is background for maintainers; it holds no directives.
2
+
3
+ # vault-sync background
4
+
5
+ ## Deduplication history
6
+
7
+ The multi-signal deduplication was revised on 2026-04-16. In that round, `/vault-sync` proposed re-extracting three meetings from 04-14 that were already reflected in vault notes: their `source` fields did not point at the original meeting paths, so the source-field match missed them. Recent update-section detection was added then as a content-level check.
8
+
9
+ ## R4 method evidence update
10
+
11
+ Step 3.5 (introduced 2026-04-24 as M10) came out of the 2026-04-24 Rethink O2 finding: after four rounds of R4 sibling merges, the method note's evidence table had drifted from the real count (recorded N=5, actual N=13). Updating the table in the same round as the merge keeps the two in step.
12
+
13
+ ## Submodule list
14
+
15
+ The submodule list is not copied into SKILL.md. `.gitmodules` is the source, and a copy here would drift from it.
@@ -0,0 +1,195 @@
1
+ ---
2
+ name: vault-sync
3
+ trigger: /vault-sync
4
+ description: Scan work/ for changes, or take an explicit list of work sources, and propose vault extractions with confirmation
5
+ ---
6
+
7
+ # /vault-sync [scope] [path...]
8
+
9
+ > Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
10
+
11
+ Scan work/ for new or changed content and propose vault extractions. Nothing is created without explicit user confirmation. Without a workspace, use `targets` with explicit source paths; skip workspace scans, registry and entity-resolution steps, task-log promotion and timestamp updates, and report the skipped steps. If no targets were supplied, ask for them.
12
+
13
+ ## Input
14
+ - scope (optional): "full" (all work/), "meetings" (meetings only), "projects" (projects only), "diff" (git diff only), "targets" (the work files or directories that follow, no scan)
15
+ - Default: "full"
16
+ - Single work source: call `/vault-extract` directly. A work `inbox/` item is processed by `inbox-process` first and its summary is the target (the vault has no inbox).
17
+ - Without a workspace, a single explicit source follows the same proposal and confirmation steps as a batch; invoke `/vault-extract` only after the user accepts its create proposal.
18
+
19
+ Raw recordings and unreviewed transcripts are not scanned by `/vault-sync`. In a workspace, only refined meeting notes under `work/meetings/YYYY/YYYY-MM/` are considered vault-worthy sources. Any transcript provider output must be processed through `meeting-notes` first. When the workspace or `meeting-notes` skill is unavailable, skip and report that workspace preprocessing step, ask for a reviewed meeting note or summary, and do not process the raw transcript.
20
+
21
+ ## Process
22
+
23
+ ### Step 1: Scan
24
+
25
+ 2-source parallel scan:
26
+
27
+ #### 1A: Meeting Notes (highest priority)
28
+ ```bash
29
+ # List all meeting files in current month (YYYY/YYYY-MM = today)
30
+ ls <workspace-root>/meetings/YYYY/YYYY-MM/
31
+ ```
32
+ - Cross-reference vault notes source fields to find unprocessed meetings
33
+ - Grep vault `notes/` for `source:.*work/meetings/YYYY/YYYY-MM` to identify already-extracted
34
+
35
+ #### 1B: Git Diff (Work Root + Submodules)
36
+ ```bash
37
+ # Work root: changes since last sync timestamp
38
+ cd <workspace-root>
39
+ LAST_SYNC=$(cat <vault.path>/ops/sessions/last-sync-timestamp)
40
+ # Convert YYYYMMDDHHMI to git date format
41
+ SINCE_DATE=$(echo $LAST_SYNC | sed 's/\(....\)\(..\)\(..\)\(..\)\(..\)/\1-\2-\3 \4:\5/')
42
+
43
+ # Root repo changes (exclude system/meetings/tasks — those have dedicated scanners)
44
+ git log --oneline --since="$SINCE_DATE" --name-only -- . \
45
+ ':!.claude' ':!.obsidian' ':!meetings' ':!tasks' \
46
+ | grep -v '^\w\{7\} ' | grep -v '^$' | grep -v '\.json$' \
47
+ | grep -v 'uv.lock' | grep -v 'pyproject.toml' \
48
+ | sort -u
49
+ # The workspace system directory is dropped by the Step 1.5 filter rules
50
+
51
+ # Submodule changes: detect which submodules have new commits
52
+ git submodule status --recursive | grep '^+' | awk '{print $2}'
53
+ ```
54
+
55
+ **Submodule change detection**:
56
+ - `+` prefix in `git submodule status` = submodule HEAD differs from recorded commit
57
+ - For each changed submodule, check its recent commits:
58
+ ```bash
59
+ cd <workspace-root>/$SUBMODULE
60
+ git log --oneline --since="$SINCE_DATE" --name-only -- . ':!.claude' \
61
+ | grep -v '^\w\{7\} ' | grep -v '^$' | sort -u
62
+ ```
63
+
64
+ **Work repo submodules**: 목록은 `.gitmodules`가 정본. `vault`는 스캔 대상이 아니라 목적지이고, 코드 저장소 서브모듈은 명시 요청 시에만 스캔한다. 그 외 work 트리는 일반 디렉토리이므로 루트 git diff 스캔이 덮는다.
65
+
66
+ ### Step 1.5: Filter & Classify
67
+
68
+ **Filter rules** (reduce noise):
69
+ - Skip: the workspace system directory, `.json`, `uv.lock`, `pyproject.toml`, `*.css`, `*.js`, `*.html`
70
+ - Skip: draft versions if final exists (e.g., `drafts/YYMMDD-v2-*` if `final/YYMMDD-v4-*` exists)
71
+ - Skip: personal and code-repository submodules unless explicitly requested
72
+ - Include: `README.md`, `*-plan-*.md`, `*-report-*.md`, `*-summary-*.md`, `*-strategy-*.md`
73
+ - Include: any `.md` under the workspace's configured document roots
74
+
75
+ **Classify** per `references/vault-adapter.md` §Project Registry Pattern (scoring and fallback). A match attaches the project name and `vault_note` to the proposal; ambiguity marks it "project: TBD (user confirm)".
76
+
77
+ > **Entity resolution**: people/orgs/projects 해소는 워크스페이스 context-enrichment 규칙(`ssot.rules`)의 절차 사용 (fast cache → registry → vault MOC, 충돌 시 vault 우선).
78
+
79
+ **Deduplication** (multi-signal):
80
+
81
+ 0. **`vmem_brief` first**: `vmem_brief(intent: "<source title> <key topics>", paths: ["<source work file>"], bytes: 1024)` ranks screened pointer lines by the intent words plus the source file's basename words (`paths` is a word hint, not a citation filter). Run it once per source before the checks below, then confirm a pointer with `vmem_search`; the checks below decide the verdict
82
+ 1. **source field exact match**: `source: work/meetings/...` 경로 직접 일치
83
+ 2. **Title similarity ≥70%**: fuzzy compare against vault note titles
84
+ 3. **Recent update-section detection**: 대상 회의 날짜 헤더(`## Update (YYYY-MM-DD)` 또는 `## YYYY-MM-DD ...`)가 vault 노트에 이미 존재하면 "이미 반영됨"으로 판정
85
+ 4. **Entity overlap** (보조): 회의 제목의 주요 인물·기관 키워드가 vault 노트 본문에 ≥3회 등장 시 후보
86
+
87
+ **판정 로직**:
88
+ - 1, 2, 3 중 **임의 하나 hit** → "already reflected — skip" 제안
89
+ - 1 miss + 2 hit (≥70%) → "update" 제안 (source field 갱신 포함)
90
+ - 모두 miss → "create" 제안
91
+
92
+ Standalone explicit-source precedence: if 1 or 3 hits, propose "already reflected — skip". If 1 and 3 miss but 2 hits, inspect the candidate and propose "update" only when related; show an unclear candidate to the user. This precedence applies only without a workspace.
93
+
94
+ ### Step 2: Propose
95
+
96
+ Present candidates grouped by source and priority:
97
+ ```
98
+ EXTRACTION PROPOSALS
99
+ ====================
100
+ Scanned: meetings 9건, git-diff 5건, submodules 1건
101
+
102
+ ─── MEETINGS (HIGH) ───
103
+
104
+ [1] MEETING: MM-DD partner meeting - example platform
105
+ -> Proposed: update [[example-partner-platform-mou]]
106
+ -> Domain: projects
107
+
108
+ ─── GIT DIFF (MEDIUM-HIGH) ───
109
+
110
+ [2] DIFF: admin/example-unit/YYMMDD-org-restructuring.md (new file)
111
+ -> Proposed: update [[example-org-restructuring-decision]]
112
+ -> Domain: operations
113
+
114
+ [3] DIFF: projects/example-project/planning/YYMMDD-plan-masterplan.md (new file)
115
+ -> Proposed: update [[example-project-masterplan-idea]]
116
+ -> Domain: projects
117
+
118
+ ─── SUBMODULE CHANGES ───
119
+
120
+ [4] SUBMODULE: sites/example-site (+1 commit, requested)
121
+ -> Changed: src/pages/
122
+ -> Proposed: update [[example-site-home]]
123
+ -> Domain: teaching
124
+
125
+ Accept: [a]ll, [1-4] select, [s]kip, [q]uit
126
+ ```
127
+
128
+ ### Step 3: Confirm
129
+ - User selects which proposals to execute
130
+ - Follow `/vault-extract` §Extraction Fidelity and Concurrent Writers on every extraction; its one-writer rule's condition, stated in that rule, decides when it applies
131
+ - For each confirmed proposal:
132
+ 1. Read the source document fully
133
+ 2. **create** proposals: extract insights per `/vault-extract` methodology → create vault note(s) → update relevant MOCs
134
+ 3. **update** proposals: hand off to the `/vault-update` procedure (MCP `vmem_patch`/`vmem_append`/`vmem_set_frontmatter` with the original insight preserved, `## Update YYYY-MM-DD` section, `/vault-lint note=` afterwards when the CLI is available) — this skill does not carry its own update path
135
+ 4. Show created/updated note for review
136
+
137
+ ### Step 3.5: R4 Sibling Merge (Method Evidence 자동 갱신)
138
+
139
+ 이번 라운드에서 **R4 sibling merge**(≥2 meetings → 1 노트 merge)가 1건 이상 실행됐으면, Step 4 전에 `references/r4-method-evidence.md`를 읽고 method 노트의 evidence 테이블을 갱신한다.
140
+
141
+ **Skip 조건**:
142
+ - R4 merge 0건인 세션 → Step 3.5 skip
143
+ - User가 /vault-sync --skip-method-update 플래그 사용 시
144
+
145
+ ### Step 4: Record
146
+ - Update last-sync timestamp in `ops/sessions/last-sync-timestamp` (plain file, fs write)
147
+ - Log sync results in `ops/sessions/YYYYMMDD-sync.md` with `vmem_report(path: "ops/sessions/YYYYMMDD-sync.md", body)` (expect: vmem refuses secret-looking text and an unsafe path)
148
+ - Promote vault-relevant `TASK` events from the work-local `.maru/tasks-log.md`
149
+ to `vault/log` with `vmem_log_append(type: "TASK", ...)` (task-management does not write the
150
+ vault directly)
151
+ - **Graph freshness**: run vault-lint L11 (graph staleness). If `vault-graph.json`
152
+ is > 7 days stale, propose `/vault-graph build`. Suggest only — do not auto-build.
153
+
154
+ ## Scope Details
155
+
156
+ ### /vault-sync meetings
157
+ - Scan work/meetings/YYYY/ (current year) for notes not yet in vault
158
+ - Cross-reference vault notes source fields
159
+ - Extract: decisions, insights, relationship updates
160
+
161
+ ### /vault-sync projects
162
+ - Git diff on work root + project submodules
163
+ - Scan work/projects/ README and key doc changes
164
+ - Compare with existing vault project notes
165
+ - Propose updates to existing notes or new notes
166
+
167
+ ### /vault-sync diff
168
+ - Git diff only (skip meeting scanners)
169
+ - Work root + all submodules
170
+ - Useful for catching project doc changes between meeting-heavy days
171
+
172
+ ### /vault-sync targets <path>...
173
+ - Skip Step 1. Enumerate eligible sources under the given source paths (`.md` with frontmatter, or summary output); at most 20 per run (collector's-fallacy guard: split larger batches)
174
+ - Step 1.5 classification and deduplication run once for the whole batch, and the classification is passed to each extraction (no registry reload per item)
175
+ - The named targets are the user's choice of sources: Step 2 shows the proposal list once and one accept covers the batch (per-item select still works)
176
+ - Step 3 runs the `/vault-extract` method per accepted create proposal and hands accepted update proposals to `/vault-update` as in other scopes, then `/vault-connect` on the notes it created. Check quality once after the batch with one `vmem_lint` call (or the CLI `vmem lint <vault> --note <path>` per note when the CLI is available)
177
+ - Stop on a refusal or a persisted partial write (see `references/vault-adapter.md` §Write results); continue past warnings
178
+ - Output adds: sources skipped by vault-extract preconditions, per-note lint error/warning counts
179
+ - Step 4 writes the session record but does not move `ops/sessions/last-sync-timestamp`: a targets run covers only the named sources, not every change since the last sync
180
+
181
+ ### /vault-sync full
182
+ - All of the above in priority order: meetings → git diff → submodules
183
+ - Limit: max 10 proposals per run (avoid overwhelm)
184
+ - Raw recordings and transcripts must be refined into `work/meetings/` first
185
+
186
+ ## Quality Gates
187
+ - Same as /vault-extract quality gates
188
+ - Additional: deduplication check before creation
189
+ - Confirmation required for every note creation (in `targets`, the one batch accept is that confirmation)
190
+
191
+ ## Output
192
+ - Summary of scan results (per source: meetings, diff, submodules)
193
+ - Numbered proposals with accept/skip interface
194
+ - After execution: list of created/updated notes
195
+ - Updated sync timestamp
@@ -0,0 +1,12 @@
1
+ # R4 Sibling Merge: Method Evidence 갱신
2
+
3
+ 이번 세션에서 **R4 sibling merge**가 1건 이상 실행된 경우 (≥2 meetings → 1 노트 merge), 워크스페이스가 지정한 R4 method 노트(이하 `<r4-method-note>`; 워크스페이스 설정에 없으면 사용자에게 묻는다)의 evidence 테이블을 자동 갱신한다.
4
+
5
+ **절차**:
6
+ 1. 이번 /vault-sync 라운드에서 수행한 R4 merge 노트 목록 수집 (target note + merged sessions count)
7
+ 2. `vmem_read(path: '<r4-method-note>')` 호출 (sha256 보관)
8
+ 3. `## 실증 사례 (3건, YYYY-MM-DD 기준)` 테이블에서 해당 merged 노트 행 찾기
9
+ 4. **누적 N 증가**: `N = 기존 N + 이번 라운드 병합 수`
10
+ 5. **날짜 분포 append**: `기존 분포 + MM-DD(N추가)` 형태로 append
11
+ 6. 표를 한 번의 `vmem_patch`로 갱신한다. 표 전체를 통째로 바꾸면 `vmem_patch(path, oldString: <기존 표 전체>, newString: <갱신 표 전체>, expectedSha: <2단계 sha256>)`, 여러 행·칸만 고칠 때는 `vmem_patch(path, edits: [{oldString, newString}, ...], expectedSha)`로 한 호출에 묶는다 (`edits[]`는 1..32쌍, 원문에서 각각 한 번만 매치해야 하고, 전부 아니면 전무로 적용되며 로그도 1줄만 남는다). 나눠 고쳐야 하면 매 patch 뒤 `vmem_read`로 새 sha256을 받아 다음 patch에 쓴다. expect: vmem refuses a stale `expectedSha` (V09), an `edits[]` pair that matches nowhere or twice, and an overlapping pair
12
+ 7. 신규 merged 노트(케이스 추가)인 경우 **새 행** 추가