@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.
- package/CHANGELOG.md +12 -0
- package/README.md +17 -2
- package/bin/vmem.js +5 -1
- package/package.json +2 -1
- package/skills/_shared/vault-adapter.md +131 -0
- package/skills/skill-mine/SKILL.md +52 -0
- package/skills/skill-mine/vocab/actions.yaml +110 -0
- package/skills/skill-mine/vocab/objects.yaml +123 -0
- package/skills/vault-connect/SKILL.md +75 -0
- package/skills/vault-extract/README.md +20 -0
- package/skills/vault-extract/SKILL.md +139 -0
- package/skills/vault-graph/SKILL.md +120 -0
- package/skills/vault-learn/SKILL.md +111 -0
- package/skills/vault-lint/README.md +32 -0
- package/skills/vault-lint/SKILL.md +137 -0
- package/skills/vault-lint/references/lint-output.md +97 -0
- package/skills/vault-lint/references/vault-scope-rules.md +26 -0
- package/skills/vault-lint/references/work-scope-checks.md +71 -0
- package/skills/vault-refactor/SKILL.md +112 -0
- package/skills/vault-remember/SKILL.md +38 -0
- package/skills/vault-rethink/README.md +15 -0
- package/skills/vault-rethink/SKILL.md +58 -0
- package/skills/vault-stats/SKILL.md +49 -0
- package/skills/vault-sync/README.md +15 -0
- package/skills/vault-sync/SKILL.md +195 -0
- package/skills/vault-sync/references/r4-method-evidence.md +12 -0
- package/skills/vault-update/SKILL.md +68 -0
- package/skills/vmem-status/SKILL.md +30 -0
- package/src/amem/host-api.ts +5 -1
- package/src/analysis-input.ts +15 -0
- package/src/analysis-types.ts +3 -1
- package/src/assertion-policy.ts +4 -2
- package/src/assertions.ts +48 -8
- package/src/cli-output.ts +10 -3
- package/src/cli.ts +29 -3
- package/src/commands-table.ts +3 -1
- package/src/config.ts +21 -7
- package/src/enrichment-query.ts +65 -0
- package/src/enrichment-search.ts +69 -0
- package/src/enrichment-store.ts +197 -0
- package/src/enrichment.ts +245 -0
- package/src/graph-evidence.ts +2 -2
- package/src/index.ts +9 -0
- package/src/mcp-vault.ts +46 -8
- package/src/proposal-provider.ts +3 -2
- package/src/proposals.ts +10 -4
- package/src/read-output.ts +1 -1
- package/src/registry.ts +57 -2
- package/src/setup.ts +12 -3
- package/src/skills-install.ts +216 -0
- package/src/ui/panel-types.ts +55 -0
- package/src/ui/panel.js +76 -0
- package/src/ui/plugin.ts +95 -5
- package/src/vault-graph.ts +15 -7
- package/src/vault-index.ts +17 -0
- package/src/vault-lint.ts +12 -4
- package/src/write-operations.ts +38 -1
- package/src/write-types.ts +1 -0
- package/src/write-validation.ts +2 -1
- package/src/writer.ts +1 -1
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-extract
|
|
3
|
+
trigger: /vault-extract
|
|
4
|
+
description: Extract insights from a source document into vault notes
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# /vault-extract [source]
|
|
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
|
+
Extract insights, decisions, observations from a source document and create vault notes.
|
|
12
|
+
|
|
13
|
+
## Input
|
|
14
|
+
- source: path to a source file or a URL
|
|
15
|
+
|
|
16
|
+
## Preconditions (MANDATORY — enforce before any vault write)
|
|
17
|
+
|
|
18
|
+
Before writing ANY vault note, verify the source frontmatter (summary or canonical meeting note) has **all three required fields with non-empty values**:
|
|
19
|
+
|
|
20
|
+
1. **`description`** — string, ≥10 chars, not equal to title
|
|
21
|
+
2. **`domain`** — ∈ `{research | projects | teaching | operations | people | ai-practice}`
|
|
22
|
+
3. **`topics`** — array containing ≥1 `[[wiki-link]]` **AND every `[[target]]` must be an existing MOC in the bound vault** (MOC enforcement — topics carry hub navigation only, not keyword tags)
|
|
23
|
+
- vmem checks this at write time; `vmem_mocs` lists the existing MOCs when you need to choose one. expect: vmem refuses (V02) a `topics` entry that is not an existing MOC
|
|
24
|
+
- If any `[[target]]` is missing: **ABORT** (do NOT auto-create the MOC) — the caller (or user) must either fix the summary's topics or create the MOC note first
|
|
25
|
+
- Concept/keyword tags (e.g., `credit-recognition`, `partnership-mapping`) belong in body text, NOT in `topics`. Schema is "topics = MOC only" per `vault/AGENTS.md §Schema`.
|
|
26
|
+
|
|
27
|
+
**Read the supplied summary's frontmatter with a YAML parse BEFORE building the vault note body, regardless of its location.** expect: vmem refuses (V01) a missing `description`, `type` or `domain` and an enum value outside the vocabulary.
|
|
28
|
+
|
|
29
|
+
If any check fails:
|
|
30
|
+
- **ABORT** the extract for this summary
|
|
31
|
+
- Emit failed event with `vmem_log_append(type: "EXTRACT", project: <proj>, source: <summary>, note: "failed: <reason>")` (reasons include: `missing required fields: <field list>`, `dead topic: [[<target>]] not in vault/notes/`)
|
|
32
|
+
- Return error to caller (`inbox-process`, /vault-sync) — caller decides whether to continue with other items
|
|
33
|
+
- **Do NOT synthesize empty values. Do NOT guess. Do NOT proceed to write.**
|
|
34
|
+
- User must fix summary.md and re-run. `inbox-process` must re-emit summary with correct fields when the summary came from an inbox item.
|
|
35
|
+
|
|
36
|
+
## Extraction Fidelity and Concurrent Writers
|
|
37
|
+
|
|
38
|
+
These rules govern every extraction:
|
|
39
|
+
|
|
40
|
+
1. **Key facts stay verbatim.** Quote numbers, dates, amounts, contract terms and named obligations exactly as the source states them, with the source path on the same line. Keep analysis in a separate `## Synthesis` section, required whenever the note quotes key facts.
|
|
41
|
+
2. **Conflicts stay conflicts.** When two sources disagree on a value, record both values with their sources; `## Synthesis` may say which source is later or more authoritative, and both attributed values remain.
|
|
42
|
+
3. **One writer per entity page**, when more than one agent or session writes vault notes in one pass: assign each entity (person, organization, project, document, contract) to one writer, and every other writer links to that page from the notes it owns and writes only the pages it owns. Owners create, or confirm the existence of, their entity pages at the start of the pass, and another writer adds its link only after that create succeeded; vmem refuses a new unresolved wiki link (V03), so until then it records the pending link as plain text in the run output (never as a `[[link]]` in a note), adds it once the target resolves, and reports it as unresolved if the owner's create never succeeds. A non-owner links into an owned page only from its own notes (with `vmem_link(..., bidirectional: false)` or a body link), because the default bidirectional call would write into a page the non-owner does not own; once the other writers finish, each owner (or the session coordinating the pass, if that owner has ended) runs `/vault-connect` on each of its pages another writer linked into, to add the back-links.
|
|
43
|
+
|
|
44
|
+
## Process
|
|
45
|
+
|
|
46
|
+
1. Read the source document completely
|
|
47
|
+
2. If workspace registry is available, classify the source document's project per `references/vault-adapter.md` §Project Registry Pattern (scoring and fallback); otherwise skip registry classification, report it, and use content-based classification or project `-`.
|
|
48
|
+
3. Identify extractable items by domain:
|
|
49
|
+
- research: claims, methods, contradictions, open-questions, tech-trends
|
|
50
|
+
- projects: decisions, rationale, lessons-learned, risks, milestones
|
|
51
|
+
- teaching: pedagogy-insights, curriculum-patterns, student-feedback, course-design
|
|
52
|
+
- operations: policies, process-improvements, resource-decisions, institutional-strategy
|
|
53
|
+
- people: collaboration-patterns, preferences, expertise, relationship-dynamics
|
|
54
|
+
- ai-practice: gap-patterns, effective-prompts, tool-comparisons, workflow-optimizations
|
|
55
|
+
4. **Run Preconditions** (see §Preconditions above). ABORT on failure before any write.
|
|
56
|
+
5. For each item, create a note in vault/notes/:
|
|
57
|
+
- Filename: prose-as-title (lowercase, hyphens, .md)
|
|
58
|
+
- YAML frontmatter with required fields (`description`, `type`, `domain`, `topics`)
|
|
59
|
+
- **Copy source-derived fields verbatim**: `description`, `domain`, `topics` are copied directly from summary.md frontmatter (verified in preconditions above). See `references/vault-adapter.md` §Summary To Vault Fields.
|
|
60
|
+
- **type remapping**: summary `type` (regulation|report|plan|...) maps to vault `type` (insight|decision|observation|person|project|method|moc|reference) based on semantic intent. Common mappings: report→observation, plan→decision, memo→insight, proposal→decision, regulation→observation, meeting→decision for actual decisions or observation for other meeting insights; `meeting_kind` is descriptive metadata, not a vault type.
|
|
61
|
+
- If registry matched in step 2, follow `references/vault-adapter.md` §Project Registry Pattern for MOC validation; an ordinary `vault_note` never becomes a topic.
|
|
62
|
+
- Set `source` to a real workspace-relative path, URL, or `mem:` id accepted by vmem. For a standalone local file outside a configured workspace, do not invent a workspace path or use an absolute path: use a real stable URL or `mem:` id when supplied; otherwise omit source metadata, use `-` for the log source, and report that provenance is unavailable. Follow the adapter log-field rules. If the source carries backref
|
|
63
|
+
frontmatter (`source_doc`, `meetingSourcePath`, `relatedMeetings`,
|
|
64
|
+
`relatedTasks`), preserve workspace
|
|
65
|
+
origins as plain paths, including body links; retain vault links only
|
|
66
|
+
after resolving them in the bound vault. The same stem in both namespaces
|
|
67
|
+
does not make a workspace link a vault link.
|
|
68
|
+
- Body: the insight with context, with quoted facts and `## Synthesis` placed per §Extraction Fidelity and Concurrent Writers
|
|
69
|
+
- Relevant Notes section with wiki links
|
|
70
|
+
- Topics section with MOC wiki links
|
|
71
|
+
6. **Pre-validate, write, and read the receipt** (MANDATORY):
|
|
72
|
+
a. `vmem_check(path: "notes/<stem>.md", text: <the full note text>)` validates the prospective note without writing, so an invalid frontmatter (V01), a `topics` entry that is not an existing MOC (V02), a new unresolved wiki link (V03) and secret-looking text (V06) cost no write. It does not see a stem collision; only the create does.
|
|
73
|
+
b. Duplicate check: `vmem_brief(intent: "<title> <description>", paths: ["<source work file>"], bytes: 1024)`. `paths` only adds the file's basename words to the ranked terms (a hint, not a citation filter), so also confirm a pointer with `vmem_search`. A pointer that is already this insight is a merge, not a second note: run `vmem_merge(keep, absorb)` as a preview, then confirm it with the fingerprint.
|
|
74
|
+
c. Create with `vmem_create(stem, type, domain, topics, description, source, body, log: {type: "EXTRACT", project, source, dest: "notes/<stem>.md", note: "<type>"})`. Omit the note `source` argument when no valid reference exists; set `log.source` to `-` in that case. vmem validates the full frontmatter before it saves, so a stripped or invalid note is never written.
|
|
75
|
+
d. Read the whole receipt. `possibleDuplicates` is a warning, not a refusal: the note was written, and vmem lists the notes whose indexed title terms match it (V08 at warning severity). Surface that list with the merge option (keep the existing note, absorb the new one) or keep both and link them — never write a second copy of the same insight. The hard V08 (`same stem or normalized H1 already exists`) is the refusing form and stops before anything is written. `ok: false` with `applied: false` wrote nothing: record `failed: <issue codes>` with `vmem_log_append` and return the issues. `ok` false with `applied: true` persisted: reconcile per `references/vault-adapter.md` §Write results.
|
|
76
|
+
e. expect: vmem refuses the V01/V02/V03/V06 issues `vmem_check` reports, V08 on a duplicate stem or normalized H1, and V09 on a note over 256 KiB; `vmem_merge` refuses two notes of different types, a person or MOC note, and a merged result over the size bound. Report the named issues; never retry with guessed values.
|
|
77
|
+
7. After creating notes, invoke /vault-connect with entities hint (from summary.md):
|
|
78
|
+
- Read `entities` field from source summary.md (if present — list of 인물/기관 names)
|
|
79
|
+
- Pass entities list to `/vault-connect` as wiki-link candidate seeds (`entities_hint` parameter)
|
|
80
|
+
- `/vault-connect` uses entities to prioritize wiki-link discovery in its first pass
|
|
81
|
+
- **Note**: `keywords` field is NOT carried forward to vault notes — it exists only for route scoring reproducibility
|
|
82
|
+
8. **EXTRACT event in vault/log** (ingest chain audit trail) comes from the step 6 `log` argument
|
|
83
|
+
|
|
84
|
+
## Log Append (Step 8 — REQUIRED)
|
|
85
|
+
|
|
86
|
+
Every note created or updated by /vault-extract must produce one `log` line. `vmem_create` writes it from its `log` argument. An update (`vmem_patch` / `vmem_append`) records a default EXTRACT line; when the contract needs the `updated: <type>` note text, pass it as that write's `log` argument. Failures use `vmem_log_append`. Never append to the log file directly.
|
|
87
|
+
|
|
88
|
+
**Format** (`references/vault-adapter.md` §Log Append):
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
YYYY-MM-DD HH:MM EXTRACT <project> <source> → <vault/notes/x.md> — <type>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- `<source>`: real workspace-relative source path, URL or `mem:` id as described above; use `-` when no valid reference is available, never invent a workspace path
|
|
95
|
+
- `<vault/notes/x.md>`: newly created note path (use `notes/x.md` form)
|
|
96
|
+
- `<type>`: note type (`insight | decision | observation | person | project | method | moc | reference`)
|
|
97
|
+
|
|
98
|
+
**Multiple notes from single source**: one log line per note created.
|
|
99
|
+
|
|
100
|
+
**Update vs create**: for updates, use `— updated: <type>` to distinguish.
|
|
101
|
+
|
|
102
|
+
**Failure**: `references/vault-adapter.md` §Log failure handling.
|
|
103
|
+
|
|
104
|
+
**Vault access**: use vmem through the transport in the adapter; no direct vault writes. No filesystem Write/Edit on vault paths.
|
|
105
|
+
|
|
106
|
+
## Sibling Meeting Merge Rule
|
|
107
|
+
|
|
108
|
+
복수 회의 소스(같은 프로젝트·같은 날·보완적 관점)를 **단일 vault 노트**로 merge할지, **분리**할지 결정:
|
|
109
|
+
|
|
110
|
+
**Merge 조건 (모두 충족 시)**:
|
|
111
|
+
1. 같은 이니셔티브/프로젝트 (registry score 동일 결과)
|
|
112
|
+
2. 같은 날 또는 ±1일 이내
|
|
113
|
+
3. 보완적 관점 (한쪽이 다른 쪽의 전제·후속·다른 stakeholder view)
|
|
114
|
+
4. 각 회의만으로는 독립된 vault 노트로 composability 성립 안 함
|
|
115
|
+
|
|
116
|
+
**분리 조건 (하나라도 해당)**:
|
|
117
|
+
- 서로 다른 프로젝트/도메인
|
|
118
|
+
- 동일 주제의 **독립 의사결정** 또는 시간 간격 ≥7일
|
|
119
|
+
- 각 회의 독립 composability 성립 (각자 "This note argues that ..." 문장 성립)
|
|
120
|
+
|
|
121
|
+
**Merge 시 구조**:
|
|
122
|
+
- 단일 frontmatter `source`는 **주도 회의** 하나 경유
|
|
123
|
+
- 본문에 `## Update (YYYY-MM-DD, AM/PM): 출처: ...` 형태로 **각 회의 출처 명시**
|
|
124
|
+
- EXTRACT 로그는 **노트당 1줄** + 회의 각각 별도 `SOURCE`로 기록
|
|
125
|
+
|
|
126
|
+
**Purpose**: prevent fragmented notes when two source documents describe the same initiative from complementary perspectives.
|
|
127
|
+
|
|
128
|
+
## Quality Gates
|
|
129
|
+
|
|
130
|
+
- description must add information beyond the title (max 200 chars)
|
|
131
|
+
- Composability test: "This note argues that [title]" must make sense
|
|
132
|
+
- Each note must link to at least 1 domain MOC
|
|
133
|
+
- source field must be set when a valid reference is available; otherwise report the missing provenance
|
|
134
|
+
- **EXTRACT event appended to log for every created/updated note**
|
|
135
|
+
|
|
136
|
+
## Output
|
|
137
|
+
- List of created notes with descriptions
|
|
138
|
+
- Count of log lines appended
|
|
139
|
+
- Suggestion to run /vault-connect on new notes
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-graph
|
|
3
|
+
trigger: /vault-graph
|
|
4
|
+
description: >
|
|
5
|
+
지식그래프 빌드·분석·질의 스킬. vault 그래프와 workspace 레이어를 `vmem graph build`로 빌드한다.
|
|
6
|
+
커뮤니티 탐지, god node 분석, surprising connections를 제공한다.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# /vault-graph [command]
|
|
10
|
+
|
|
11
|
+
> 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.
|
|
12
|
+
>
|
|
13
|
+
> Graph builds and queries require vmem >= 0.8.0. Check the version as described in the adapter; if the MCP host does not expose it, report it as unknown and check tool availability.
|
|
14
|
+
|
|
15
|
+
Knowledge graph build, query, and report for vault notes and the workspace layer. Run workspace builds and workspace weekly-job steps only when a workspace exists; otherwise skip and report them, and use the vault-only build. No code graph and no graph MCP server.
|
|
16
|
+
|
|
17
|
+
`vault-graph` owns the graph workflow.
|
|
18
|
+
|
|
19
|
+
## Shared Runtime
|
|
20
|
+
|
|
21
|
+
| Item | Path |
|
|
22
|
+
|------|------|
|
|
23
|
+
| Vault/workspace builder | `vmem graph build <vault> [--workspace]` (MCP `vmem_graph_build`) |
|
|
24
|
+
|
|
25
|
+
## Commands
|
|
26
|
+
|
|
27
|
+
### Query Commands (vmem reads, always available)
|
|
28
|
+
- **orphans**: notes with no incoming links (`vmem_lint` L03 — an in-link-0, topics-0 finding, so the count matches `/vault-lint`)
|
|
29
|
+
- **hubs**: notes with most connections (`vmem_graph_neighbors` `hops: 1` returns `degree` per node; a hub sweep uses the graph report's god-node table)
|
|
30
|
+
- **domain [name]**: all notes in a domain (`vmem_search` with `domain`)
|
|
31
|
+
- **cross [domain1] [domain2]**: notes linking across domains (`vmem_graph_neighbors` per note with `hops: 1`, comparing the two neighbours' domains)
|
|
32
|
+
- **backlinks [note]**: all notes linking to a specific note (`vmem_links` with `direction: "in"`)
|
|
33
|
+
- **density**: connection density metrics (graph report totals: nodes, edges, communities, isolates, density)
|
|
34
|
+
- **stale [days]**: notes not modified in N days (`vmem_list` `mtime`)
|
|
35
|
+
|
|
36
|
+
### Build Commands
|
|
37
|
+
- **build**: Run community detection + analysis pipeline. Outputs:
|
|
38
|
+
- `vault/reports/vault-graph.json` (node-link JSON)
|
|
39
|
+
- `vault/reports/graph-report-YYMMDD.md` (audit report; 구 리포트는 보존되고 `graph-trend.md`에 빌드마다 행 1개가 추가된다)
|
|
40
|
+
- **build --workspace**: Add the work operational layer → `vault/reports/workspace-graph.json` (vault-graph.json untouched; no report written). **On demand only**; the weekly ritual does not build it. See below.
|
|
41
|
+
- **neighbors [note]**: 1-hop neighborhood + community of a note through `vmem_graph_neighbors` (no build, no report or `vault-graph.json` read).
|
|
42
|
+
- **path [note-a] [note-b]**: shortest link path between two notes through `vmem_graph_path` (no build, no report or `vault-graph.json` read)
|
|
43
|
+
- **report**: Read the latest graph report (if < 7 days old)
|
|
44
|
+
- **communities**: List detected communities from latest build
|
|
45
|
+
- **surprises**: List cross-community surprising connections
|
|
46
|
+
- **god-nodes**: Show most-connected non-MOC nodes
|
|
47
|
+
|
|
48
|
+
## Build Process (`/vault-graph build`)
|
|
49
|
+
|
|
50
|
+
Options:
|
|
51
|
+
- `--vault`: build the vault graph
|
|
52
|
+
- `--workspace`: build the vault layer **plus** the work operational layer → `workspace-graph.json`
|
|
53
|
+
|
|
54
|
+
1. Execute:
|
|
55
|
+
```bash
|
|
56
|
+
vmem graph build <vault> # --vault (MCP: vmem_graph_build)
|
|
57
|
+
vmem graph build <vault> --workspace # --workspace (MCP: vmem_graph_build workspace: true)
|
|
58
|
+
```
|
|
59
|
+
2. Pipeline: read notes → extract graph → deterministic Leiden community detection → god node analysis → surprising connections → report. vmem's graph block carries `partitioner: "leiden"` and its report prints the same name, so use Leiden everywhere (MOCs and business-unit hubs excluded). 커뮤니티 제목은 **anchor 노트**(degree 최대 멤버)로 붙고 정수 id는 "do not cite" 줄에만 남는다(빌드마다 재배정되므로 인용 금지).
|
|
60
|
+
3. Outputs:
|
|
61
|
+
- vault: `<vault.path>/reports/vault-graph.json`, `<vault.path>/reports/graph-report-YYMMDD.md` (+ `graph-trend.md` 행 추가, 구 리포트 보존)
|
|
62
|
+
- workspace: `<vault.path>/reports/workspace-graph.json` only (no report or trend row; the result lists the work counters)
|
|
63
|
+
4. vmem writes the vault and workspace outputs and records the GRAPH event itself; add no log line. A build whose receipt is `ok: false` names the rule that stopped it; stop and report it.
|
|
64
|
+
The weekly ritual is a **single** vault build, run by the workspace's weekly job (`--workspace` is on-demand only). Order: build → lint → vault push → work pointer bump.
|
|
65
|
+
|
|
66
|
+
## Neighbors Process (`/vault-graph neighbors <note>`)
|
|
67
|
+
|
|
68
|
+
1-hop neighborhood + community of a note, read through `vmem_graph_neighbors`, which builds the graph from the current index on each call (no report read, no `jq`, no rebuild). Used by the workspace's context-enrichment graph-neighborhood step.
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
vmem_graph_neighbors(path: "<stem>", hops: 1, limit: 50) # MCP
|
|
72
|
+
vmem graph neighbors <vault> <stem> --hops 1 --limit 50 # CLI
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- The result carries `nodes` (each with `community` and `degree`), the `edges` among them and `truncated`; `hops: 2` widens the walk and `relation` (`wiki_link` or one typed relation) narrows the edge set.
|
|
76
|
+
- Report the node's `community`, its degree-ranked neighbors (≤10), and same-community co-members.
|
|
77
|
+
- Backlinks, orphans and staleness come from vmem too: `vmem_links(path, direction: "in")`, `vmem_lint` L03, and `vmem_list` `mtime` — never a ripgrep pass over `notes/`.
|
|
78
|
+
- expect: vmem refuses `hops` outside 1–2, a `limit` outside 1–500, an unknown `relation` and an unknown note.
|
|
79
|
+
|
|
80
|
+
## Path Process (`/vault-graph path <note-a> <note-b>`)
|
|
81
|
+
|
|
82
|
+
Shortest link path between two notes, read through `vmem_graph_path`, which builds the graph from the current index on each call (no report read, no `jq`, no rebuild).
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
vmem_graph_path(from: "<stem-a>", to: "<stem-b>", maxHops: 6) # MCP
|
|
86
|
+
vmem graph path <vault> <stem-a> <stem-b> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json] # CLI
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- The walk is undirected BFS with neighbours visited in code-point order, so the same pair and options always return the same path. The result carries `found`, `length` in hops, the ordered `nodes` and the `edges` between them (each edge keeping its `relation`).
|
|
90
|
+
- `maxHops` is 1–6 and defaults to 6: a pair farther apart than that comes back `found: false`, not as an error.
|
|
91
|
+
- `viaHubs` is off by default, so `moc` and `bu` hubs are not intermediate steps; set it when the only route runs through a MOC. `relation` (`wiki_link` or one typed relation) narrows the edge set.
|
|
92
|
+
- expect: vmem refuses `maxHops` outside 1–6, an unknown `relation` (`use wiki_link or supports, contradicts, extends, applies-to, context-for`), and an unknown `from` or `to` note. `from` equal to `to` returns `found: true, length: 0`; a pair with no route within `maxHops` returns `found: false` with `length: 0` and empty `nodes`/`edges`, a result and not a refusal.
|
|
93
|
+
|
|
94
|
+
## Report Process (`/vault-graph report [target]`)
|
|
95
|
+
|
|
96
|
+
1. Resolve report directory: `<vault.path>/reports/graph-report-*.md`.
|
|
97
|
+
2. Select newest report and warn if older than 7 days.
|
|
98
|
+
3. Read it with `vmem_read_file`.
|
|
99
|
+
4. Summarize overview, god nodes, top communities, surprising connections, and isolate count.
|
|
100
|
+
|
|
101
|
+
## Query Process (`/vault-graph query "<question>" [options]`)
|
|
102
|
+
|
|
103
|
+
An ad-hoc graph question is a vmem read, never a pass over `graph.json`. Pick the read that matches the question:
|
|
104
|
+
|
|
105
|
+
| Question | Read |
|
|
106
|
+
|---|---|
|
|
107
|
+
| open question about a topic | `vmem_brief` with the question as `intent` |
|
|
108
|
+
| words that must appear in a note | `vmem_search` |
|
|
109
|
+
| what surrounds one note | `vmem_graph_neighbors` (`hops: 2`, optional `relation`) |
|
|
110
|
+
| what links to one note | `vmem_links` with `direction: "in"` |
|
|
111
|
+
| how two notes are connected | `vmem_graph_path` (`from`/`to` stems; `maxHops` 1–6, `relation`, `viaHubs`) |
|
|
112
|
+
| vault-wide shape (hubs, communities, cross-community links) | latest graph report, after `/vault-graph build` when it is stale |
|
|
113
|
+
|
|
114
|
+
## Integration
|
|
115
|
+
|
|
116
|
+
- `/vault-connect` Step 0 discovers candidates with `vmem_brief` and `vmem_graph_neighbors`, never by reading this report
|
|
117
|
+
- `/vault-sync` duplicates come from `vmem_brief` with the source path; the graph report is not a dedup signal
|
|
118
|
+
- `/vault-lint` checks L11 (graph staleness > 7 days), L12 (island communities, reported by member list)
|
|
119
|
+
- `skill-mine` mines skill candidates with `vmem skills mine`, which uses the same deterministic Leiden communities
|
|
120
|
+
- The workspace agent guide may point T2/T3 operations at the graph report before a full vault search
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-learn
|
|
3
|
+
trigger: /vault-learn
|
|
4
|
+
description: Query→Wiki 환원 — research a topic (or promote a conversation answer) into vault with user approval gate and LEARN event logging
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# /vault-learn [topic]
|
|
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
|
+
Promote a research finding or conversation answer into the vault graph **only after explicit user approval**. Implements the Query→Wiki 환원 루프 defined in `vault/AGENTS.md` §"Query → Wiki 환원 루프".
|
|
12
|
+
|
|
13
|
+
**Not for**: observations about how the vault/methodology itself is working (friction, surprises, process notes) — those go to `ops/observations/` via `/vault-remember` (no approval gate, no LEARN line; they feed `/vault-rethink`). `/vault-learn` writes knowledge into `notes/`.
|
|
14
|
+
|
|
15
|
+
## When to invoke
|
|
16
|
+
|
|
17
|
+
1. **Automatic trigger**: user question required cross-referencing 2+ work/ files and synthesizing a conclusion
|
|
18
|
+
2. **Manual trigger**: user says `/vault-learn` or `$learn` to promote the current conversation
|
|
19
|
+
3. **Research trigger**: user says `/vault-learn <topic>` to initiate web research + vault promotion
|
|
20
|
+
|
|
21
|
+
## Input
|
|
22
|
+
- topic: subject to research or promote (optional if current conversation context is the source)
|
|
23
|
+
|
|
24
|
+
## Process
|
|
25
|
+
|
|
26
|
+
### Step 1: Source gather
|
|
27
|
+
- If research mode: WebSearch / WebFetch the topic, collect primary sources
|
|
28
|
+
- If conversation mode: collect the question, the files cross-referenced, and the synthesized answer
|
|
29
|
+
|
|
30
|
+
### Step 2: Vault duplicate check
|
|
31
|
+
- `vmem_brief(intent: "<topic> <key terms>", paths: ["<work file or the source of the answer>"], bytes: 1024)` — screened pointer lines over titles, descriptions and types; `paths` adds the file's basename words to the ranked terms (a hint, not a citation filter)
|
|
32
|
+
- `vmem_search(query: "...")` on the topic + key terms to confirm a pointer, and `vmem_read(path: "glossary", section: "<term>")` for a term collision
|
|
33
|
+
- A pointer that already carries this insight makes the proposal an UPDATE (Option B) or a `vmem_merge`, not a new note
|
|
34
|
+
|
|
35
|
+
### Step 3: Propose (user approval gate — MANDATORY)
|
|
36
|
+
Present a proposal block:
|
|
37
|
+
```
|
|
38
|
+
LEARN PROPOSAL
|
|
39
|
+
==============
|
|
40
|
+
topic: <topic>
|
|
41
|
+
type: insight | observation | decision
|
|
42
|
+
domain: research | projects | teaching | operations | people | ai-practice
|
|
43
|
+
confidence: experimental (new research, default) | likely (consensus) | proven (verified sources) — schema values only (vault/AGENTS.md §Schema)
|
|
44
|
+
|
|
45
|
+
Option A (NEW note):
|
|
46
|
+
- path: notes/<kebab-case-stem>.md (lowercase letters, digits, hyphens)
|
|
47
|
+
- description: <one-line>
|
|
48
|
+
- topics: [[<moc>]]
|
|
49
|
+
- source: <url | work/ path | conversation:<date>>
|
|
50
|
+
|
|
51
|
+
Option B (UPDATE existing):
|
|
52
|
+
- path: notes/<existing-note>.md
|
|
53
|
+
- change: <add wiki-link to [[new-term]] + 1 paragraph>
|
|
54
|
+
|
|
55
|
+
Option C (PROMOTE an agent-mem entry):
|
|
56
|
+
- candidate: mem:<id> — <title> (kind, project), from `amem_vault_candidates`
|
|
57
|
+
- path: notes/<kebab-case-stem>.md (prefilled from the entry: title → H1 and stem, text → body)
|
|
58
|
+
- source: mem:<id> (the confirm writes `promoted_from: mem:<id>` and the back-link itself)
|
|
59
|
+
|
|
60
|
+
Accept: [a] new, [b] update, [c] promote, [s] skip, [q] quit
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Do NOT write to vault without explicit accept.** If user skips, append `— proposed, skipped` LEARN line anyway (see Step 6).
|
|
64
|
+
|
|
65
|
+
### Step 4: Execute (on accept)
|
|
66
|
+
- New note: `vmem_create(stem, type, domain, topics, description, confidence, source, body, log: {type: "LEARN", project, source, note: "promoted: <type>"})`
|
|
67
|
+
- Update: `vmem_patch(path, oldString, newString, expectedSha, log)` or `vmem_append(path, section, markdown, log)` with `log: {type: "LEARN", project, source, dest, note: "updated: <title>"}`
|
|
68
|
+
- Promote an agent-mem entry (Option C): list candidates with `amem_vault_candidates` (CLI `amem vault-candidates`), then call `vmem_promote_from_amem(id: "mem:<id>", stem, type, domain, topics, description, body, project)` for the preview — full note text, the possible duplicates and a fingerprint — and confirm with `vmem_promote_from_amem(..., confirm: true, fingerprint)`. A listed duplicate is not a refusal: the preview carries `choices` (`create` or `link-existing <path>`), so pick one before confirming, or pass `linkTo` to link an existing note instead of creating one. That confirm creates the note, writes `promoted_from` and its back-link, and records the `LEARN <project> mem:<id> → notes/<stem>.md — promoted: <kind>` line itself; pass no `log`, and add none afterwards. expect: vmem refuses a stale fingerprint, and a `stem`, `type` or `domain` outside the schema; an existing stem or the same normalized H1 (hard V08) makes the preview `ok: false`, so change the stem or H1 before confirming
|
|
69
|
+
- Body: atomic insight, context, relevant notes section
|
|
70
|
+
- expect: vmem refuses a missing or duplicated note field, a `confidence` outside the schema, a `topics` entry that is not an existing MOC, a new unresolved wiki link and secret-looking text; report the named issues instead of retrying with guessed values
|
|
71
|
+
|
|
72
|
+
### Step 5: Connect
|
|
73
|
+
- Call `/vault-connect note=<new-note>` to wire wiki-links (delegates log append to /vault-connect for CONNECT event)
|
|
74
|
+
|
|
75
|
+
### Step 6: LEARN event in vault/log
|
|
76
|
+
|
|
77
|
+
Always record one LEARN line — even when user skips — so the query history is preserved. A Step 4 create or update records it through its `log` argument, and an Option C promotion records its own `LEARN mem:<id> → notes/<stem>.md` line on confirm, so add none for either; for `proposed, skipped` and `failed: <reason>` call `vmem_log_append(type: "LEARN", project, source, dest, note)`. Never append to the log file directly.
|
|
78
|
+
|
|
79
|
+
**Format**:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
YYYY-MM-DD HH:MM LEARN <project> <source> → <vault/notes/x.md> — <note>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
- `<source>`: `query` (conversation origin), `url:<hash>` (web research), or `work/<path>` (file cross-ref)
|
|
86
|
+
- `<note>`: one of
|
|
87
|
+
- `promoted: <type>` (new note created)
|
|
88
|
+
- `updated: <title>` (existing note updated)
|
|
89
|
+
- `proposed, skipped` (user declined the proposal)
|
|
90
|
+
- `failed: <reason>` (write error)
|
|
91
|
+
|
|
92
|
+
**Vault access**: use vmem through the transport in the adapter; no direct vault writes.
|
|
93
|
+
|
|
94
|
+
## Quality Gates
|
|
95
|
+
- Each promoted note must be a single atomic insight (composability test: "This note argues that [title]")
|
|
96
|
+
- Source must be recorded (`source:` frontmatter for notes; `— <source>` column in log)
|
|
97
|
+
- Confidence field required; default `experimental` for new research
|
|
98
|
+
- Must link to at least 1 existing note or MOC
|
|
99
|
+
- **User approval is non-negotiable** — never auto-promote
|
|
100
|
+
|
|
101
|
+
## Output
|
|
102
|
+
- Research/conversation summary
|
|
103
|
+
- Proposal block (Step 3)
|
|
104
|
+
- On accept: created/updated note path + /vault-connect result
|
|
105
|
+
- LEARN event confirmation (log append status)
|
|
106
|
+
|
|
107
|
+
## Related
|
|
108
|
+
|
|
109
|
+
- `vault/AGENTS.md` §"Query → Wiki 환원 루프" — the policy
|
|
110
|
+
- `references/vault-adapter.md` §Log Append — log line format
|
|
111
|
+
- `/vault-extract`, `/vault-connect` — downstream skills invoked in steps 4-5
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
SKILL.md is the instruction source for this skill. This file is background for maintainers; it holds no directives.
|
|
2
|
+
|
|
3
|
+
# vault-lint background
|
|
4
|
+
|
|
5
|
+
## Origin
|
|
6
|
+
|
|
7
|
+
The skill implements the lint stage of Karpathy's "LLM Wiki Method": a periodic consistency check over the workspace and the vault that reports problems and leaves fixes to other skills.
|
|
8
|
+
|
|
9
|
+
## Retired checks
|
|
10
|
+
|
|
11
|
+
- **L05** was retired on 2026-08-19. Its input, `inbox/INDEX.md`, was replaced by `inbox/_state/index.jsonl` (the intake receipt log), and routing-receipt consistency moved to inbox-intake and inbox-process.
|
|
12
|
+
- **L11b** (workspace-graph freshness) was retired on 2026-08-19 because nothing queried that output (the workspace rules directory, `ssot.rules`). The `--work-root` graph build remains available on demand.
|
|
13
|
+
|
|
14
|
+
## Script history
|
|
15
|
+
|
|
16
|
+
- On 2026-10-31 `scripts/lint.py` was removed and the vault scope moved to `vmem lint` (STAIxBWLB/skills#88). On the live personal vault both reported the same findings (0 errors, 0 warnings), and vault-mem's parity checks had already compared their finding sets twice on the private corpus. vmem adds L13 (filename), L14 (source paths) and L15 (`confidence: proven` without a `source`). The entries below describe the retired script.
|
|
17
|
+
- `scripts/lint.py` parses frontmatter with PyYAML (block sequences, flow arrays, folded scalars). The switch on 2026-08-19 removed the cause of L02 false positives.
|
|
18
|
+
- The MOC-only rule for `topics:` (checked by L01) dates from 2026-05-22.
|
|
19
|
+
- The script's TYPE lists for L09 carry a keep-aligned comment pointing at the workspace ingest-chain rule, so the rule table and the constants in `scripts/lint.py` change together.
|
|
20
|
+
- Measured cost: one script run covered 456 notes in under a second, so the work-scope globbing (L07, L08) dominates run time.
|
|
21
|
+
|
|
22
|
+
## Why L06 uses a frontmatter marker
|
|
23
|
+
|
|
24
|
+
`*-summary.md` names are used by inbox-process output and also by human-written retrospectives, reviews, and reference notes (`99-review/`, `06-refs/`, `drafts/`). Treating frontmatter presence as the marker catches real regressions (frontmatter present, required field missing) and leaves hand-written, non-chain summaries out of scope without a path list.
|
|
25
|
+
|
|
26
|
+
## Why L09 warns only on new violations
|
|
27
|
+
|
|
28
|
+
`vault/log` is append-only, so past lines cannot be corrected after the fact. Warnings are limited to violations that can still be resolved; legacy TYPEs listed in the normalization table appear as a single information line instead.
|
|
29
|
+
|
|
30
|
+
## Run cadence
|
|
31
|
+
|
|
32
|
+
The skill was designed for one `/vault-lint full` run per week and a `/vault-lint vault` run after a large ingest. CI registration is ruled out (see SKILL.md 가드레일) because every run needs local vault access.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-lint
|
|
3
|
+
trigger: /vault-lint
|
|
4
|
+
description: >
|
|
5
|
+
work/ + vault/ 정합성 검증 리포트 생성. dead wiki-link, orphan note,
|
|
6
|
+
스키마 위반, 명명규칙 위반, 스테일 seed, 로그 포맷 위반, 그래프 신선도 등 체크셋을
|
|
7
|
+
실행하여 vault/reports/lint-report-YYMMDD.md로 리포트. vault 스코프는 `vmem lint`가
|
|
8
|
+
판정하고 work 스코프는 에이전트가 검사. 자동 수정 하지 않음(제안만).
|
|
9
|
+
트리거: vault-lint, /vault-lint, lint, 정합성 검사, 건강검진, vault lint, work lint,
|
|
10
|
+
스키마 검사, 명명 검사, orphan 검사, 교차참조 검사, 린트
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# /vault-lint 스킬
|
|
14
|
+
|
|
15
|
+
> 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.
|
|
16
|
+
|
|
17
|
+
work/ + vault/ 정합성 검증 리포트 생성기. workspace가 없으면 기본 `full`은 vault 범위만 검사하고 work 검사와 workspace 설정 의존 검사를 건너뛰었다고 보고한다. 명시적인 work 전용 범위는 workspace가 없으면 건너뛰고 보고한다.
|
|
18
|
+
|
|
19
|
+
## 기본 원칙
|
|
20
|
+
|
|
21
|
+
- **읽기 전용**: 자동 수정 하지 않는다. 제안만 한다.
|
|
22
|
+
- **리포트 출력 1곳**: `vault/reports/lint-report-YYMMDD.md`
|
|
23
|
+
- **log append**: `vault/log`에 `LINT` 이벤트 1줄 추가
|
|
24
|
+
- **vault 스코프 판정은 vmem**: `vmem lint`(=`vmem_lint`)가 vmem 인덱스로 L01·L02·L03·L09·L10·L11·L12·L13·L14·L15를 판정한다.
|
|
25
|
+
vault 쓰기(리포트)도 vmem만 사용.
|
|
26
|
+
- **work/ 접근**: Read / Grep / Glob (서브모듈 내부 깊이 검사는 위임)
|
|
27
|
+
|
|
28
|
+
## 호출 형식
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
/vault-lint [scope]
|
|
32
|
+
/vault-lint note=<notes/path.md>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
| scope | 대상 |
|
|
36
|
+
|-------|------|
|
|
37
|
+
| `full` (기본) | vault + work 전체 |
|
|
38
|
+
| `vault` | vault/notes/ + vault/log |
|
|
39
|
+
| `work` | work/ 전체 (서브모듈 루트까지) |
|
|
40
|
+
| `inbox` | inbox summary 스키마 (L06) |
|
|
41
|
+
| `names` | 파일명 규칙만 (work/ + vault/) |
|
|
42
|
+
| `note=<path>` | 단일 vault note 품질·스키마 검증 |
|
|
43
|
+
|
|
44
|
+
## 체크셋 (L01-L15)
|
|
45
|
+
|
|
46
|
+
`<ideation>` = `<paths.scratchpad>/<scratchpad.ideation_subdir>` (기본
|
|
47
|
+
`work/scratchpad/ideation`). workspace 설정에서 경로를 해석한다. 설정이 없으면 해당 scratchpad 검사를 건너뛰고 보고한다.
|
|
48
|
+
임계값도 설정에서 읽는다 (`scratchpad.ideation_review_days`,
|
|
49
|
+
`scratchpad.temp_stale_days`).
|
|
50
|
+
|
|
51
|
+
| ID | 대상 | 내용 | 심각도 |
|
|
52
|
+
|----|------|------|--------|
|
|
53
|
+
| L01 | `vault/notes/` 본문 + frontmatter `topics:` | dead wiki-link (`[[x]]` 대상 부재). frontmatter는 `topics`/`project`/`projects` 등 wiki-link 값 필드 모두 포함 | **error** |
|
|
54
|
+
| L02 | `vault/notes/` | 필수 frontmatter 누락 (`type`, `topics`) + 허용값 이탈 (`type`, `confidence`, `status`) | **error** |
|
|
55
|
+
| L03 | `vault/notes/` | orphan (in-link 0, topics 0) | warn |
|
|
56
|
+
| L04 | `<ideation>/seeds/`, `vault/` ideation | `scratchpad.ideation_review_days` 초과 미갱신 seed | warn |
|
|
57
|
+
| L05 | - | **폐지**. 라우팅 영수증 정합성은 inbox-intake/inbox-process 소관 | - |
|
|
58
|
+
| L06 | `work/**/*-summary.md` (frontmatter 보유분) | 신 스키마 필수 필드 누락 (marker-based scope) | warn |
|
|
59
|
+
| L07 | `work/**/*` | `YYMMDD-type-desc.ext` 명명 위반 | warn |
|
|
60
|
+
| L08 | `work/**/*` | 한글 파일명 (macOS NFD) | **error** |
|
|
61
|
+
| L09 | `vault/log` | **미등록 TYPE**(정규 12종·정규화표 모두 없음)·구조 위반·라인 수 20k 초과만 warn. 정규화표 등재 legacy TYPE은 정보 1줄 | warn |
|
|
62
|
+
| L10 | `vault/notes/*` | `project:` frontmatter 값이 vault 노트(wiki-link)도, `project-registry.yaml` id도 아님 | warn |
|
|
63
|
+
| L11 | `vault/reports/` | graph report 7일 초과 stale (`graph-report-YYMMDD.md`) | warn |
|
|
64
|
+
| L12 | `vault/reports/vault-graph.json` | island community (cross-community edge 0개인 커뮤니티) — 멤버 목록으로 보고, 번호 인용 금지 | warn |
|
|
65
|
+
| L13 | `vault/notes/` | 파일명이 소문자 ASCII kebab-case가 아님 (`vmem move`로 수정) | **error** |
|
|
66
|
+
| L14 | `vault/notes/` | frontmatter `source:` 경로가 해소되지 않음 | warn |
|
|
67
|
+
| L15 | `vault/notes/` | `confidence: proven`인데 `source`가 비어 있음 — 근거(memory id·URL·workspace 경로)를 넣거나 confidence를 낮춘다 | warn |
|
|
68
|
+
|
|
69
|
+
## 실행 절차
|
|
70
|
+
|
|
71
|
+
### 1단계: scope 해석
|
|
72
|
+
|
|
73
|
+
| scope | 활성 체크 |
|
|
74
|
+
|-------|----------|
|
|
75
|
+
| `full` | L01~L15 (L05 제외) |
|
|
76
|
+
| `vault` | L01, L02, L03, L09~L15 — 전부 `vmem lint` |
|
|
77
|
+
| `work` | L06, L07, L08 |
|
|
78
|
+
| `inbox` | L06 |
|
|
79
|
+
| `names` | L07, L08 |
|
|
80
|
+
| `note=<path>` | L01·L02·L03·L10·L13·L14·L15 (CLI `--note` 전용) + 단일 note quality gates |
|
|
81
|
+
|
|
82
|
+
### 2단계: vault 스코프 — `vmem lint` (L01, L02, L03, L09~L15)
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
vmem lint <vault> --json
|
|
86
|
+
# 단일 노트(CLI 전용): vmem lint <vault> --note notes/<x>.md --json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- 결과 JSON: `findings`(코드별 목록), `errors`, `warnings`, `markdown`(리포트 본문, 체크별 섹션), `summary`(`SUMMARY errors=N warnings=M`). `findings`는 vmem이 만든 판정이고, 스킬이 다시 계산하지 않는다
|
|
90
|
+
- 읽기 전용. project id는 vault에 등록된 `registry`로 검사한다
|
|
91
|
+
- finding을 설명하거나 수정 제안을 쓰기 전, `note=<path>` 결과를 판정하기 전에 `references/vault-scope-rules.md`를 읽는다.
|
|
92
|
+
- L01 finding은 해결 후보를 함께 준다: vmem이 제안한 `suggested` 타깃(존재하는 노트, 점수 포함)을 먼저 검토하고, 없거나 틀렸을 때만 직접 후보를 찾는다. 한 노트만 볼 때는 `vmem_links(path)`가 같은 제안을 dead link마다 하나씩 준다
|
|
93
|
+
- `note=<path>` 스코프: `--note`로 L01/L02/L03/L10/L13/L14/L15를 해당 노트로 제한한 뒤, 에이전트가 note quality gates(description test·composability·source)를 추가 검토
|
|
94
|
+
- MCP `vmem_lint` 인자는 `{vault, write, dryRun}`뿐이라 note를 좁힐 수 없다: `note=<path>`는 CLI 전용이고, MCP만 쓰는 경로는 vault 전체 lint 결과를 요청한 노트로 필터해 보고하고 범위 제한을 명시한다.
|
|
95
|
+
|
|
96
|
+
### 3단계: work 스코프 — 에이전트 검사 (L04, L06, L07, L08)
|
|
97
|
+
|
|
98
|
+
scope가 `full`·`work`·`inbox`·`names`이면 검사 전에 `references/work-scope-checks.md`를 읽고 활성 체크의 절차, Legacy Exemptions, 표준 OSS 메타 파일 allowlist를 따른다.
|
|
99
|
+
|
|
100
|
+
### 4단계: 리포트 생성
|
|
101
|
+
|
|
102
|
+
`vault/reports/lint-report-YYMMDD.md`를 생성한다. 두 경로 중 하나만 쓴다: (a) work 스코프 포함 리포트는 `vmem_report(path: "reports/lint-report-YYMMDD.md", body, log)`(5단계 LINT 1줄 기록), (b) vault 스코프만이면 `vmem_lint(write: true)`가 같은 파일에 쓴다(LINT 1줄 기록). expect: vmem refuses secret-looking text and an unsafe report path. vault 스코프 섹션은 2단계 `markdown`을 그대로 붙이고, work 스코프 섹션(L04·L06·L07·L08)을 에이전트가 채운다. 작성 전에 `references/lint-output.md`를 읽고 그 구조(frontmatter, 요약, 체크별 섹션, 제안 조치)를 따른다.
|
|
103
|
+
|
|
104
|
+
### 5단계: log append
|
|
105
|
+
|
|
106
|
+
(a) 경로는 4단계 `vmem_report`에 `log: {type: "LINT", project: "-", source: "vault/ + work/", note: "E errors, W warnings"}`를 넘겨 LINT 1줄을 기록한다((b)는 `vmem_lint`가 이미 LINT를 기록한다). 별도 `vmem_log_append`는 하지 않는다:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
YYYY-MM-DD HH:MM LINT - vault/ + work/ — E errors, W warnings
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
log 파일 직접 append(`>>`) 금지.
|
|
113
|
+
|
|
114
|
+
## 가드레일
|
|
115
|
+
|
|
116
|
+
- **자동 수정 금지**: 리포트만 생성. 수정은 사용자가 별도 스킬(`/vault-extract`, `/vault-connect`, `inbox-process`)로 실행.
|
|
117
|
+
- **vault 쓰기는 vmem만**: 리포트는 `vmem_report`(또는 CLI `vmem report`), 노트 수정은 `vmem_*` 쓰기 도구. 파일시스템 `Write`/`Edit` 금지.
|
|
118
|
+
- **서브모듈 내부 깊이 검사 안 함**: 서브모듈은 해당 저장소의 자체 lint로 위임.
|
|
119
|
+
- **CI 등록 금지**: 로컬 vault 접근이 필요하므로 CI 파이프라인에 등록하지 않는다. 권장 주기는 주간 `full` 1회, 대규모 ingest 후 `vault`.
|
|
120
|
+
- **성능**: vault 스코프는 `vmem lint` 1회 실행. work 스코프(L07/L08 `Glob work/**/*`)가 비용의 대부분이므로 필요 시 `/vault-lint vault`로 분리.
|
|
121
|
+
- **대용량 log**: L09가 라인 수 20k 초과 감지 시 "수동 아카이브 권장" warn만 추가 (자동 롤오버 안 함).
|
|
122
|
+
- **중복 리포트**: 같은 날 여러 번 실행 시 `vault/reports/lint-report-YYMMDD.md`를 덮어쓴다 (최신 상태 유지). 이력은 `vault/log`의 `LINT` 이벤트로 추적.
|
|
123
|
+
|
|
124
|
+
## 응답 원칙
|
|
125
|
+
|
|
126
|
+
1. **한국어 소통**
|
|
127
|
+
2. **실행 전 scope 확인**: 사용자에게 scope 선택 제시 (기본 full)
|
|
128
|
+
3. **진행 상황**: 각 체크 완료 시 한 줄 요약 (`L01: 0 error`)
|
|
129
|
+
4. **최종 요약**: error/warn 건수 + 리포트 경로 + log append 확인
|
|
130
|
+
|
|
131
|
+
## 관련 문서
|
|
132
|
+
|
|
133
|
+
- `references/vault-adapter.md` §Log Append — log 포맷 (체인 전체 그림은 워크스페이스 `ssot.ingest_chain`)
|
|
134
|
+
- `references/vault-adapter.md` — vault 접근·스키마 정책
|
|
135
|
+
- workspace 설정이 있을 때만 scratchpad 경로·임계값을 읽는다
|
|
136
|
+
- `inbox-process` 스킬 — inbox 처리와 요약 스키마
|
|
137
|
+
- `ssot.project_registry` — 프로젝트 id 단일 소스
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Lint 출력 노트 구조
|
|
2
|
+
|
|
3
|
+
`vault/reports/lint-report-YYMMDD.md` 구조. vault 스코프 섹션(L01·L02·L03·L09·L10·L11·L12·L13·L14·L15)은 `vmem lint`의 `markdown`과 `findings`를 그대로 옮기고, work 스코프 섹션(L04·L06·L07·L08)은 에이전트가 채운다.
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
---
|
|
7
|
+
type: report
|
|
8
|
+
generated: YYYY-MM-DDTHH:MM
|
|
9
|
+
scope: full
|
|
10
|
+
summary:
|
|
11
|
+
errors: N
|
|
12
|
+
warnings: N
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Lint Report YYYY-MM-DD
|
|
16
|
+
|
|
17
|
+
## 요약
|
|
18
|
+
|
|
19
|
+
- error: N건
|
|
20
|
+
- warn: N건
|
|
21
|
+
- scope: full
|
|
22
|
+
|
|
23
|
+
## L01 — dead wiki-link (error, N건)
|
|
24
|
+
|
|
25
|
+
- `notes/foo.md`: `[[missing-target]]` → 대상 노트 없음 — suggested `notes/foo-bar.md` (score 0.812)
|
|
26
|
+
- ...
|
|
27
|
+
|
|
28
|
+
## L02 — 필수 frontmatter 누락 (error, N건)
|
|
29
|
+
|
|
30
|
+
- `notes/bar.md`: `type` 필드 없음
|
|
31
|
+
- ...
|
|
32
|
+
|
|
33
|
+
## L03 — orphan (warn, N건)
|
|
34
|
+
|
|
35
|
+
- `notes/baz.md`: in-link 0, topics 0
|
|
36
|
+
|
|
37
|
+
## L04 — stale seed (warn, N건)
|
|
38
|
+
|
|
39
|
+
- `work/scratchpad/ideation/seeds/YYYY-MM-DD-foo.md`: 146일 미갱신
|
|
40
|
+
|
|
41
|
+
## L06 — 신 스키마 불일치 (warn, N건)
|
|
42
|
+
|
|
43
|
+
- `work/projects/example/admin/YYMMDD-report-summary.md`: frontmatter 없음 (구 포맷)
|
|
44
|
+
|
|
45
|
+
## L07 — 명명 규칙 (warn, N건)
|
|
46
|
+
|
|
47
|
+
- `work/projects/foo/Report Draft.md`: 공백 포함, 소문자 아님
|
|
48
|
+
|
|
49
|
+
## L08 — 한글 파일명 (error, N건)
|
|
50
|
+
|
|
51
|
+
- `work/projects/bar/보고서.pdf`
|
|
52
|
+
|
|
53
|
+
## L09 — 로그 포맷 (warn, N건)
|
|
54
|
+
|
|
55
|
+
- `log:42`: TYPE `FOO` 미등록 (정규 12종·정규화표 모두 없음)
|
|
56
|
+
- `log:1798`: 구조 위반 (불릿 접두, 시각 컬럼 누락)
|
|
57
|
+
|
|
58
|
+
정보: legacy TYPE 45건 (정규화표 등재), 최종 사용 YYYY-MM-DD, 신규 발생 없음
|
|
59
|
+
|
|
60
|
+
## L10 — project 미등록 (warn, N건)
|
|
61
|
+
|
|
62
|
+
- `notes/xyz.md`: `project: unknown-project` (registry 없음)
|
|
63
|
+
|
|
64
|
+
## L11 — graph report staleness (warn, N건)
|
|
65
|
+
|
|
66
|
+
- `vault/reports/graph-report-YYMMDD.md`: 7일 초과 (최신: YYMMDD, 현재: YYMMDD). `/vault-graph build` 재실행 권장
|
|
67
|
+
|
|
68
|
+
## L12 — island community (warn, N건)
|
|
69
|
+
|
|
70
|
+
- island community (2 notes): `person-a`, `person-b` — `/vault-connect` 필요
|
|
71
|
+
|
|
72
|
+
nodes 446 / edges 2457 / communities 9; singleton 6개: `concept-a`, `person-c`, ...
|
|
73
|
+
|
|
74
|
+
## L13 — 명명 규칙 (vault note, error, N건)
|
|
75
|
+
|
|
76
|
+
- `notes/Project Brief.md`: 소문자 ASCII kebab-case 아님 → `vmem_move`로 `notes/project-brief.md`
|
|
77
|
+
|
|
78
|
+
## L14 — source 미해소 (warn, N건)
|
|
79
|
+
|
|
80
|
+
- `notes/abc.md`: `source: work/projects/gone/file.md` 경로 없음
|
|
81
|
+
|
|
82
|
+
## L15 — proven confidence의 source (warn, N건)
|
|
83
|
+
|
|
84
|
+
- `notes/def.md`: `confidence: proven`인데 `source` 없음
|
|
85
|
+
|
|
86
|
+
## 제안 조치
|
|
87
|
+
|
|
88
|
+
- L01: finding이 제안한 `suggested` 타깃을 먼저 검토 — 맞으면 wiki-link 수정, 없으면 대상 노트 생성 (`/vault-extract`); 한 노트만 볼 때는 `vmem_links(path)`가 같은 제안을 dead link마다 하나씩 준다
|
|
89
|
+
- L02: `vault-adapter.md` 정책에 맞춰 frontmatter 보강
|
|
90
|
+
- L03: `/vault-connect` 재실행 또는 topics 추가
|
|
91
|
+
- L11: `/vault-graph build` 재실행으로 graph report 갱신
|
|
92
|
+
- L12: `/vault-connect` 재실행으로 island community 노트에 cross-community wiki-link 추가
|
|
93
|
+
- L13: `vmem_move`로 kebab-case stem으로 rename (링크 재작성 포함)
|
|
94
|
+
- L15: 근거(memory id·URL·workspace 경로)를 `source`에 넣거나 confidence를 낮춘다
|
|
95
|
+
- L06: 신 스키마로 점진 마이그레이션 (수동)
|
|
96
|
+
- L08: 파일명 영문화 (즉시 수정 권장)
|
|
97
|
+
```
|