arscontexta 0.6.0

package/platforms/shared/skill-blocks/verify.md

@@ -0,0 +1,562 @@
+---
+# GENERATION TEMPLATE — Do not edit directly
+# This template is transformed by the derivation engine during /setup.
+# All {vocabulary.*} markers resolve from the preset's vocabulary.yaml.
+# All {config.*} markers resolve from the preset's preset.yaml.
+# All {DOMAIN:*} markers resolve from conversation-derived domain context.
+# All {if ...}{endif} blocks are conditionally included based on config.
+source_skill: verify
+min_processing_depth: standard
+platform: shared
+---
+
+---
+name: {vocabulary.verify}
+description: Combined verification — description quality (cold-read prediction) + schema compliance + health checks. Use as a quality gate after creating {vocabulary.note_plural} or as periodic maintenance. Triggers on "/{vocabulary.verify}", "/{vocabulary.verify} [{vocabulary.note}]", "verify {vocabulary.note} quality", "check {vocabulary.note} health".
+user-invocable: true
+allowed-tools: Read, Write, Edit, Grep, Glob, mcp__qmd__vsearch
+context: fork
+model: opus
+generated_from: "arscontexta-{plugin_version}"
+---
+
+## Runtime Configuration (Step 0 — before any processing)
+
+Read these files to configure domain-specific behavior:
+
+1. **`{config.ops_dir}/derivation-manifest.md`** — vocabulary mapping, platform hints
+   - Use `vocabulary.notes` for the notes folder name
+   - Use `vocabulary.note` / `vocabulary.note_plural` for note type references
+   - Use `vocabulary.verify` for the process verb in output
+   - Use `vocabulary.topic_map` for {DOMAIN:topic map} references
+   - Use `vocabulary.templates` for the templates folder path
+   - Use `vocabulary.cmd_reflect` for redirect when missing connections found
+
+2. **`{config.ops_dir}/config.yaml`** — processing depth, verification settings
+   - `processing.depth`: deep | standard | quick
+   - `processing.verification.description_test`: true | false
+   - `processing.verification.schema_check`: true | false
+   - `processing.verification.link_check`: true | false
+
+If these files don't exist, use universal defaults.
+
+**Processing depth adaptation:**
+
+| Depth | Verification Behavior |
+|-------|-----------------------|
+| deep | Full verification: cold-read prediction, complete schema check, exhaustive link verification, {DOMAIN:topic map} coverage, orphan risk analysis, content staleness detection, bundling analysis |
+| standard | Balanced: cold-read prediction, schema check, link verification, {DOMAIN:topic map} coverage |
+| quick | Basic: schema check, link verification only. Skip cold-read prediction and health analysis |
+
+## EXECUTE NOW
+
+**Target: $ARGUMENTS**
+
+Parse immediately:
+- If target contains a {vocabulary.note} name: verify that specific {vocabulary.note}
+- If target contains `--handoff`: output RALPH HANDOFF block at end
+- If target is "all" or "recent": verify recently created/modified {vocabulary.note_plural}
+- If target is empty: ask which {vocabulary.note} to verify
+
+## Anti-Shortcut Warning
+
+Before marking verification as passed, you MUST complete ALL four categories:
+
+1. COMPLETE description quality test — cold-read the title + description,
+   predict what the {vocabulary.note} contains, compare against actual content.
+   A description that merely restates the title FAILS.
+
+2. COMPLETE schema validation — check ALL required fields from the
+   template schema, verify ALL enum values are valid, confirm ALL
+   constraints are met. A single missing required field FAILS.
+
+3. COMPLETE link verification — confirm ALL wiki links in the {vocabulary.note}
+   resolve to existing files. A single dangling link FAILS.
+
+4. COMPLETE {DOMAIN:topic map} integration — verify the {vocabulary.note} appears in at least
+   one {DOMAIN:topic map}'s Core Ideas section with a context phrase.
+   A {vocabulary.note} with no {DOMAIN:topic map} mention FAILS.
+
+Do NOT declare success after checking only one or two categories.
+ALL FOUR must pass.
+
+**Execute these steps IN ORDER:**
+
+### Step 0: INDEX FRESHNESS CHECK
+
+Before any retrieval tests, verify the semantic search index is current:
+
+{if config.semantic_search}
+1. Try `mcp__qmd__vsearch` with a simple test query to confirm MCP availability
+2. If MCP is available, proceed to Step 1
+3. If MCP is unavailable (tool fails or returns error): note "retrieval test will be deferred" and proceed — do NOT let index issues block verification
+{endif}
+
+{if !config.semantic_search}
+1. Semantic search is not configured — retrieval test will use grep-based findability check instead
+2. Proceed to Step 1
+{endif}
+
+The index freshness check prevents false retrieval failures on recently created {vocabulary.note_plural}. If the index is stale, retrieval test results should be interpreted with that context.
+
+### Step 1: RECITE (cold-read prediction test)
+
+**CRITICAL: Do NOT read the full {vocabulary.note} yet. Only read frontmatter.**
+
+This step tests whether the title + description alone enable an agent to predict the {vocabulary.note}'s content. The cold-read constraint is the entire point — reading the {vocabulary.note} first contaminates the prediction.
+
+**1. Read ONLY title + description**
+
+Use Read with a line limit to get just the first few lines of frontmatter. Extract:
+- Title (the filename without .md)
+- Description (the description field)
+
+Do NOT scroll past the frontmatter closing `---`.
+
+**2. Form prediction**
+
+Before reading further, write out what you expect:
+- Core argument: what claim does this {vocabulary.note} make?
+- Mechanism: what reasoning or evidence does it use?
+- Scope: what boundaries does the argument have?
+- Likely connections: what other {vocabulary.note_plural} would it reference?
+
+Write this prediction explicitly in your output. It must be specific enough to be wrong.
+
+**3. Read full {vocabulary.note} content**
+
+NOW read the complete {vocabulary.note}. Compare against your prediction.
+
+**4. Score prediction accuracy (1-5)**
+
+| Score | Meaning | Threshold |
+|-------|---------|-----------|
+| **5** | Perfect — description fully captured the argument | Pass |
+| **4** | Strong — minor details missed, core predicted | Pass |
+| **3** | Adequate — general area right, missed key aspects | Pass (minimum) |
+| **2** | Weak — significant mismatch between prediction and content | FAIL |
+| **1** | Failed — {vocabulary.note} argued something different than expected | FAIL |
+
+**Passing threshold: 3 or above.**
+
+**5. Run semantic retrieval test**
+
+Test whether the description enables semantic retrieval:
+
+{if config.semantic_search}
+- Try `mcp__qmd__vsearch` with query = "[the {vocabulary.note}'s description text]", collection = "{vocabulary.notes_collection}", limit = 10
+- If MCP unavailable: report "retrieval test deferred (semantic search unavailable)" — do NOT skip silently
+
+Check where the {vocabulary.note} appears in results:
+- Top 3: description works well for semantic retrieval
+- Position 4-10: adequate but could improve
+- Not in top 10: flag — description may not convey the {vocabulary.note}'s meaning
+{endif}
+
+{if !config.semantic_search}
+- Run grep-based findability test: search for key terms from the description across {config.notes_dir}/
+- Check if the {vocabulary.note} would be discoverable via keyword search using its description terms
+- Report "semantic retrieval test not available — grep findability check used instead"
+{endif}
+
+**Why vsearch specifically:** Agents find {vocabulary.note_plural} via semantic search during /{vocabulary.reflect} and /{vocabulary.reweave}. Testing with keyword search tests the wrong retrieval method. Full hybrid search with LLM reranking compensates for weak descriptions — too lenient. vsearch tests real semantic findability without hiding bad descriptions behind reranking.
+
+**6. Draft improved description if needed**
+
+If prediction score < 3:
+- Diagnose the failure: too vague? missing mechanism? wrong emphasis? restates title?
+- Draft an improved description that would score higher
+- If you have Edit tool access: apply the improvement
+
+**7. Combined scoring**
+
+| Prediction Score | Retrieval Rank | Suggested Action |
+|------------------|----------------|------------------|
+| 4-5 | top 3 | Description works — no changes needed |
+| 3-4 | top 5 | Adequate — minor improvements possible |
+| 3+ | 6-10 | Investigate — passes prediction but weak retrieval |
+| any | not in top 10 | Flag for review — description may not enable retrieval |
+| < 3 | any | FAIL — description needs rewriting |
+
+### Step 2: VALIDATE (schema check)
+
+Read the template that applies to this {vocabulary.note} type. Determine the template by checking:
+- {vocabulary.note} location (e.g., {config.notes_dir}/ uses the standard {vocabulary.note} template)
+- Type field in frontmatter (if present, may indicate a specialized template)
+
+If the vault has templates with `_schema` blocks, read the `_schema` from the relevant template for authoritative field requirements. If no `_schema` exists, use the checks below as defaults.
+
+**Required fields (FAIL if missing):**
+
+| Field | Requirement | Severity |
+|-------|-------------|----------|
+| `description` | Must exist and be non-empty | FAIL |
+| Topics footer or `topics` field | Must reference at least one {DOMAIN:topic map} | FAIL |
+
+**Description constraints (WARN if violated):**
+
+| Constraint | Check | Severity |
+|------------|-------|----------|
+| Length | Should be ~50-200 characters | WARN |
+| Format | Single sentence, no trailing period | WARN |
+| Content | MUST add NEW information beyond title | WARN |
+| Semantic value | Should capture mechanism, not just topic | WARN |
+
+**How to check "adds new info":** Read the title, read the description. If the description says the same thing in different words, it fails this check. A good description adds: mechanism (how/why), scope (boundaries), implication (what follows), or context (where it applies).
+
+**YAML validity (FAIL if broken):**
+
+| Check | Rule | Severity |
+|-------|------|----------|
+| Frontmatter delimiters | Must start with `---` and close with `---` | FAIL |
+| Valid YAML | Must parse without errors | FAIL |
+| No unknown fields | Fields not in the template | WARN |
+
+**Domain-specific field enums (WARN if invalid):**
+
+If the {vocabulary.note} has fields with enumerated values (type, category, status, etc.), check them against the template's `_schema.enums` block. Each invalid enum value produces a WARN.
+
+**Relevant notes format (WARN if incorrect):**
+
+| Constraint | Check | Severity |
+|------------|-------|----------|
+| Format | Array with context: `["[[{vocabulary.note}]] -- relationship"]` | WARN |
+| Relationship type | Should use standard types: extends, foundation, contradicts, enables, example | INFO |
+| Links exist | Each referenced {vocabulary.note} must exist as a file | WARN |
+
+**Topics format (FAIL if invalid):**
+
+| Constraint | Check | Severity |
+|------------|-------|----------|
+| Format | Array of wiki links: `["[[{vocabulary.topic_map}]]"]` | FAIL |
+| Links exist | Each {DOMAIN:topic map} must exist as a file | WARN |
+
+**Composability (WARN if fails):**
+
+| Check | Rule | Severity |
+|-------|------|----------|
+| Title test | Can you complete "This {vocabulary.note} argues that [title]"? | WARN |
+| Specificity | Is the claim specific enough to disagree with? | WARN |
+
+### Step 3: REVIEW (per-note health checks)
+
+Run these 5 checks on the {vocabulary.note}:
+
+**1. YAML frontmatter integrity**
+- File starts with `---`, has closing `---`
+- YAML parses without errors
+- No duplicate keys
+
+**2. Description quality (independent of recite)**
+- Description is present and non-empty
+- Description adds information beyond the title
+- Description is not just the title rephrased
+
+**3. {DOMAIN:topic map} connection**
+- {vocabulary.note} appears in at least one {DOMAIN:topic map}'s Core Ideas section
+- How to check: grep for `[[{vocabulary.note} title]]` in files that serve as {DOMAIN:topic map}s
+- The {vocabulary.note}'s Topics footer references a valid {DOMAIN:topic map}
+- A {vocabulary.note} with no {DOMAIN:topic map} mention is orphaned — FAIL
+
+**4. Wiki link density**
+- Count outgoing wiki links in the {vocabulary.note} body (not just frontmatter)
+- Expected minimum: 2 outgoing links
+- If < 2: flag as sparse — the {vocabulary.note} is not participating in the graph
+- Sparse {vocabulary.note_plural} should be routed to /{vocabulary.reflect} for connection finding
+
+**5. Link resolution**
+- Scan ALL wiki links in the {vocabulary.note} — body, frontmatter `relevant_notes`, and Topics
+- For each `[[link]]`, confirm a matching file exists in the vault
+- **Exclude** wiki links inside backtick-wrapped code blocks (single backtick or triple backtick) — these are syntax examples, not real links
+- A single dangling link = FAIL with the specific broken link identified
+
+**Deep-only checks (when processing.depth = deep):**
+
+**6. Orphan risk assessment**
+- Count incoming links: grep for `[[{vocabulary.note} title]]` across all .md files
+- If 0 incoming links: AT RISK — {vocabulary.note} exists but nothing references it
+- If 1 incoming link: LOW RISK — single point of connection
+- If 2+ incoming links: OK
+
+**7. Content staleness detection**
+- Read the {vocabulary.note}'s content and assess whether claims still seem current
+- Check if referenced concepts/tools/approaches have changed
+- Flag anything that reads as potentially outdated
+
+**8. Bundling analysis**
+- Does the {vocabulary.note} make multiple distinct claims that could be separate {vocabulary.note_plural}?
+- Check: could you link to part of this {vocabulary.note} without dragging unrelated context?
+- If yes: flag for potential splitting
+
+### Step 4: APPLY FIXES
+
+If you have Edit tool access, apply fixes for clear-cut issues:
+
+**Auto-fix (safe to apply):**
+- Improved description if recite score < 3
+- Missing `---` frontmatter delimiters
+- Trailing period on description
+- Missing Topics footer (if obvious which {DOMAIN:topic map} applies)
+
+**Do NOT auto-fix (requires judgment):**
+- Bundled {vocabulary.note_plural} (splitting requires understanding the claims)
+- Content staleness (needs human review of factual accuracy)
+- Missing connections (use /{vocabulary.reflect} instead — connection finding is its own phase)
+- Ambiguous {DOMAIN:topic map} assignment (when {vocabulary.note} could fit multiple)
+
+### Step 5: Compile Results
+
+Combine all checks into a unified report:
+
+```
+=== VERIFY: [{vocabulary.note} title] ===
+
+RECITE:
+  Prediction score: N/5
+  Retrieval rank: #N (or "not in top 10" or "deferred")
+  Description: [pass/improved/needs work]
+
+VALIDATE:
+  Required fields: [PASS/FAIL — detail]
+  Description constraints: [PASS/WARN — detail]
+  Topics format: [PASS/FAIL — detail]
+  Optional fields: [PASS/WARN/N/A]
+  Relevant notes: [PASS/WARN/N/A]
+  Composability: [PASS/WARN]
+
+REVIEW:
+  Frontmatter: [PASS/FAIL]
+  Description quality: [PASS/WARN]
+  {DOMAIN:topic map} connection: [PASS/FAIL — which {DOMAIN:topic map}]
+  Wiki links: N outgoing [PASS/WARN if < 2]
+  Link resolution: [PASS/FAIL — broken links listed]
+
+Overall: [PASS / WARN (N warnings) / FAIL (N failures)]
+
+Actions Taken:
+- [List of fixes applied, or "none"]
+
+Recommended Actions:
+- [List of suggested next steps, or "none"]
+===
+```
+
+### Step 6: Update task file and capture observations
+
+- If a task file is in context (pipeline execution): update the `## {vocabulary.verify_title}` section with results
+- Reflect on the process: friction? surprises? methodology insights? process gaps?
+- If any observations worth capturing: create atomic note in the observations directory per the observation capture pattern
+- If `--handoff` in target: output RALPH HANDOFF block (see below)
+
+**START NOW.** The reference material below explains philosophy and methodology — use to guide reasoning, not as output to repeat.
+
+---
+
+# {vocabulary.verify_title}
+
+Combined verification: recite (description quality) + validate (schema compliance) + review (health checks). Three lightweight checks in one context window.
+
+## philosophy
+
+**verification is one concern, not three.**
+
+recite tests whether the description enables retrieval. validate checks schema compliance. review checks graph health. all three operate on the same {vocabulary.note}, read the same frontmatter, and together answer one question: is this {vocabulary.note} ready?
+
+running them separately meant three context windows, three subagent spawns, three rounds of reading the same file. the checks are lightweight enough (combined context ~15-25% of window) that they fit comfortably in one session while staying in the smart zone.
+
+> "the unit of verification is the {vocabulary.note}, not the check type."
+
+## execution order matters
+
+**Recite MUST run first.** The cold-read prediction test requires forming an honest prediction from title + description BEFORE reading the full {vocabulary.note}. If validate or review ran first (both read the full {vocabulary.note}), the prediction would be contaminated. Recite's constraint: predict first, read second.
+
+**Index freshness runs before everything.** The retrieval test in recite depends on semantic search having current data. Without a freshness check, recently created {vocabulary.note_plural} produce false retrieval failures that obscure actual description quality issues.
+
+After recite reads the full {vocabulary.note}, validate and review can run in any order since they both need the full content.
+
+## recite: description quality
+
+the testing effect applied to vault quality. read only title + description, predict what the {vocabulary.note} argues, then check. if your prediction fails, the description fails.
+
+**why this matters:** descriptions are the API of the vault. agents decide whether to load a {vocabulary.note} based on title + description. a misleading description causes two failure modes:
+- **false positive:** agent reads the {vocabulary.note} expecting X, wastes context on Y
+- **false negative:** agent skips the {vocabulary.note} because description doesn't signal relevance
+
+both degrade the vault's value as a knowledge tool.
+
+{if config.semantic_search}
+**retrieval test rationale:** agents find {vocabulary.note_plural} via semantic search during /{vocabulary.reflect} and /{vocabulary.reweave}. testing with BM25 keyword matching tests the wrong retrieval method. full hybrid search with LLM reranking compensates for weak descriptions — too lenient. vsearch tests real semantic findability without hiding bad descriptions.
+{endif}
+
+## validate: schema compliance
+
+checks against the relevant template schema:
+
+| Check | Requirement | Severity |
+|-------|-------------|----------|
+| `description` | Must exist, non-empty | FAIL |
+| `topics` | Must exist, array of wiki links | FAIL |
+| description length | < 200 chars | WARN |
+| description content | Adds info beyond title | WARN |
+| description format | No trailing period | WARN |
+| domain enum fields | Valid values per template `_schema.enums` | WARN |
+| `relevant_notes` format | Array with context phrases | WARN |
+| YAML integrity | Well-formed, `---` delimiters | FAIL |
+| Composability | Title passes "This {vocabulary.note} argues that [title]" test | WARN |
+
+**FAIL means fix needed. WARN is informational but worth addressing.**
+
+**template discovery:** The skill reads the template for the {vocabulary.note} type to get its `_schema` block. If no template exists or no `_schema` block is found, fall back to the default checks above.
+
+## review: per-note health
+
+5 focused checks per {vocabulary.note} (not a full vault-wide audit):
+
+1. **YAML frontmatter** — well-formed, has `---` delimiters, valid parsing
+2. **Description quality** — present, adds info beyond title, not a restatement
+3. **{DOMAIN:topic map} connection** — appears in at least one {DOMAIN:topic map}
+4. **Wiki link count** — >= 2 outgoing links (graph participation threshold)
+5. **Link resolution** — all wiki links point to existing files (full body scan, excluding backtick-wrapped examples)
+
+plus 3 deep-only checks for comprehensive audits:
+6. **Orphan risk** — incoming link count (is anything pointing here?)
+7. **Content staleness** — does the content still seem accurate?
+8. **Bundling** — does the {vocabulary.note} make multiple distinct claims?
+
+## common failure patterns
+
+| Pattern | Symptom | Fix |
+|---------|---------|-----|
+| Title restated as description | Recite score 1-2, prediction trivially correct but content is richer | Rewrite description to add mechanism/scope |
+| Missing {DOMAIN:topic map} | Review fails {DOMAIN:topic map} check | Add to appropriate {DOMAIN:topic map} or create Topics footer |
+| Dangling links | Review fails link resolution | Remove link, create the target {vocabulary.note}, or fix the spelling |
+| Sparse {vocabulary.note} | < 2 outgoing links | Route to /{vocabulary.reflect} for connection finding |
+| Schema drift | Enum values not in template | Update {vocabulary.note} to use valid values, or propose enum addition |
+
+## batch mode (--all)
+
+When verifying all {vocabulary.note_plural}:
+
+1. Discover all {vocabulary.note_plural} in {config.notes_dir}/ directory
+2. For each {vocabulary.note}, run the full verification pipeline
+3. Produce summary report:
+   - Total {vocabulary.note_plural} checked
+   - PASS / WARN / FAIL counts per category
+   - Top issues grouped by check type
+   - {vocabulary.note_plural} needing immediate attention (FAIL items)
+   - Pattern analysis across failures
+
+**Performance note:** In batch mode, the recite cold-read test runs honestly for each {vocabulary.note}. Do not "warm up" by reading multiple {vocabulary.note_plural} first — each prediction must be genuinely cold.
+
+## standalone invocation
+
+### /{vocabulary.verify} [{vocabulary.note}]
+
+Run all three checks on a specific {vocabulary.note}. Full detailed report.
+
+### /{vocabulary.verify} --all
+
+Comprehensive audit of all {vocabulary.note_plural} in {config.notes_dir}/. Summary table + flagged failures.
+
+### /{vocabulary.verify} --handoff [{vocabulary.note}]
+
+Pipeline mode for orchestrator. Runs full workflow, outputs RALPH HANDOFF block.
+
+## handoff mode (--handoff flag)
+
+When invoked with `--handoff`, output this structured format at the END of the session:
+
+```
+=== RALPH HANDOFF: {vocabulary.verify} ===
+Target: [[{vocabulary.note} name]]
+
+Work Done:
+- Recite: prediction N/5, retrieval #N, [pass/fail]
+- Validate: [PASS/WARN/FAIL] (N checks, M warnings, K failures)
+- Review: [PASS/WARN/FAIL] (N checks, M issues)
+- Description improved: [yes/no]
+
+Files Modified:
+- {config.notes_dir}/[{vocabulary.note}].md (description improved, if applicable)
+- [task file path] ({vocabulary.verify_title} section updated, if applicable)
+
+Learnings:
+- [Friction]: [description] | NONE
+- [Surprise]: [description] | NONE
+- [Methodology]: [description] | NONE
+- [Process gap]: [description] | NONE
+
+Queue Updates:
+- Mark: {vocabulary.verify} done for this task
+=== END HANDOFF ===
+```
+
+## task file update
+
+When a task file is in context (pipeline execution), update the `## {vocabulary.verify_title}` section:
+
+```markdown
+## {vocabulary.verify_title}
+**Verified:** [UTC timestamp]
+
+Recite:
+- Prediction: N/5 — [brief reason]
+- Retrieval: #N via vsearch (or "deferred")
+- Description: [kept/improved — brief note]
+
+Validate:
+- Required fields: PASS
+- Description constraints: PASS (147 chars, adds mechanism)
+- Topics: PASS (["[[{vocabulary.topic_map}]]"])
+- Optional: [status]
+
+Review:
+- Frontmatter: PASS
+- {DOMAIN:topic map} connection: PASS ([[{vocabulary.topic_map}]])
+- Wiki links: N outgoing
+- Link resolution: PASS (all resolve)
+
+Overall: [PASS/WARN/FAIL]
+```
+
+## Pipeline Chaining
+
+/{vocabulary.verify} is the **final pipeline phase**. After verification completes:
+
+- **manual:** Output "Verified. Pipeline complete." — no next step
+- **suggested:** Output completion summary AND suggest marking task done in queue
+- **automatic:** Task marked done, summary logged to task file
+
+If verification FAILS (recite score < 3 or any FAIL-level issue), do NOT mark done. Instead:
+- Output what failed and what needs fixing
+- Keep task at `current_phase: "{vocabulary.verify}"` for re-run after fixes
+
+The chaining output uses domain-native vocabulary from the derivation manifest.
+
+## queue.json update (interactive execution)
+
+When running interactively (NOT via orchestrator), YOU must execute queue updates:
+
+```bash
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+jq '(.tasks[] | select(.id=="TASK_ID")).status = "done" | (.tasks[] | select(.id=="TASK_ID")).completed = "'"$TIMESTAMP"'"' {config.ops_dir}/queue/queue.json > tmp.json && mv tmp.json {config.ops_dir}/queue/queue.json
+```
+
+The queue path uses the domain-native operations folder. Check `{config.ops_dir}/` or equivalent.
+
+## critical constraints
+
+**never:**
+- read the {vocabulary.note} before forming the recite prediction (cold-read is the whole point)
+- auto-fix FAIL-level issues without flagging them in the report
+- skip the semantic retrieval test without reporting "deferred"
+- leave failures without suggested improvements
+- declare PASS after checking only some categories
+
+**always:**
+- run recite FIRST (before validate/review — execution order is load-bearing)
+- be honest about prediction accuracy (inflated scores defeat the purpose)
+- suggest specific improved descriptions for score < 3
+- report all severity levels clearly (PASS/WARN/FAIL)
+- update task file if one is in context
+- capture observations for friction, surprises, or methodology insights

package/platforms/shared/templates/README.md

@@ -0,0 +1,35 @@
+# shared/templates/ -- Note Type Templates
+
+Note type templates live at `reference/templates/`. They define the YAML frontmatter schema and structural patterns for each note type a generated vault can contain.
+
+This directory does not duplicate those files. It exists to document the shared template layer from a distribution perspective.
+
+## Canonical Source
+
+All template files: `reference/templates/`
+
+## The 10 Note Type Templates
+
+| # | Template | Purpose |
+|---|----------|---------|
+| 1 | `base-note.md` | Foundation template -- minimal fields shared by all note types |
+| 2 | `research-note.md` | Research claims, methodology citations, adapted_from tracking |
+| 3 | `therapy-note.md` | Therapeutic journaling with mood, themes, and safety-aware structure |
+| 4 | `learning-note.md` | Learning captures with confidence tracking and spaced review signals |
+| 5 | `creative-note.md` | Creative work fragments with stage tracking and revision history |
+| 6 | `relationship-note.md` | Relationship observations with interaction logging and patterns |
+| 7 | `life-note.md` | Life management notes for goals, decisions, and personal systems |
+| 8 | `companion-note.md` | Companion/conversational captures with emotional context |
+| 9 | `moc.md` | Map of Content structure with synthesis, core ideas, tensions, gaps |
+| 10 | `session-log.md` | Session boundary logging with orientation, work done, and handoff |
+
+## How Templates Are Used
+
+During generation (/setup), the derivation engine selects which templates to include based on the derived configuration:
+
+- **Domain determines primary template.** A therapy system gets `therapy-note.md` as its primary note template. A research system gets `research-note.md`.
+- **Base template is always inherited.** Every note type builds on `base-note.md` fields.
+- **MOC and session-log are always included.** These are structural templates needed by every system.
+- **Multi-domain systems get multiple note templates.** A system with both research and creative domains gets both `research-note.md` and `creative-note.md`.
+
+Templates are platform-agnostic. The same `therapy-note.md` template works whether the vault is operated by a Claude Code agent or an OpenClaw bot.

package/presets/experimental/categories.yaml

@@ -0,0 +1 @@
+extraction_categories: []  # user-defined during init, guided by examples from research + personal presets

package/presets/experimental/preset.yaml

@@ -0,0 +1,38 @@
+name: experimental
+display_name: "Experimental / Build Your Own"
+description: "In-depth onboarding with thinking notes surfaced for every design decision. The user co-designs the system."
+dimensions:
+  atomicity: null  # user-chosen
+  organization: null
+  linking: null
+  processing: null
+  session: null
+  maintenance: null
+  search: null
+  automation: null
+blocks:
+  always:
+    - wiki-links
+    - processing-pipeline
+    - schema
+    - maintenance
+    - self-evolution
+    - session-rhythm
+    - templates
+    - ethical-guardrails
+    - helper-functions
+    - graph-analysis
+  conditional:
+    - atomic-notes
+    - mocs
+    - semantic-search
+    - personality
+    - self-space
+    - multi-domain
+  optional: []
+  disabled: []
+self_space: "user_choice"
+qmd: "user_choice"
+personality: "derived_from_conversation"
+processing_depth: "full quality gates by default, user can opt down"
+starter_mocs: []  # user-chosen

package/presets/experimental/starter/README.md

@@ -0,0 +1,7 @@
+# Experimental Preset Starter
+
+This preset uses conversation-driven derivation. No starter MOCs are pre-defined.
+
+During initialization, the onboarding conversation guides the user through design decisions for each dimension, surfacing relevant thinking notes to inform choices. The resulting configuration determines which starter MOCs to create, what vocabulary to use, and which blocks to activate.
+
+The starter directory is intentionally empty. MOCs are generated based on the conversation outcome, not pre-built templates.

package/presets/experimental/vocabulary.yaml

@@ -0,0 +1,7 @@
+# Derived from conversation during init
+domain_verb_process: null
+domain_verb_connect: null
+domain_verb_maintain: null
+domain_verb_verify: null
+domain_notes: null
+domain_topic_map: null

package/presets/personal/categories.yaml

@@ -0,0 +1,7 @@
+extraction_categories:
+  - reflections
+  - relationship-dynamics
+  - goals
+  - habits
+  - gratitude
+  - lessons