arscontexta 0.6.0

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

@@ -0,0 +1,145 @@
+# Skill Generation Block: graph
+
+## Generation Metadata
+
+```yaml
+skill_name: graph
+purpose: "Interactive knowledge graph analysis with natural language routing"
+domain_verb: "{DOMAIN:graph}"
+output_type: "graph analysis findings with suggested actions"
+triggers:
+  - "/{DOMAIN:graph}"
+  - "/{DOMAIN:graph} [operation]"
+  - "find synthesis opportunities"
+  - "graph analysis"
+  - "show connections"
+  - "find bridges"
+search_mode: none  # runs graph analysis scripts, does not search content
+quality_gates:
+  - every analysis produces findings AND actions
+  - results interpreted with domain vocabulary (not raw data)
+  - {vocabulary.note} descriptions included in output (not just titles)
+  - specific next-step commands suggested
+handoff_protocol: false  # interactive analysis, not orchestrated
+pipeline_position: meta_cognitive  # operates outside the main pipeline
+```
+
+## Vocabulary Transformation Map
+
+| Marker | Resolves To | Example (Research) | Example (Personal) |
+|--------|-------------|-------------------|-------------------|
+| `{vocabulary.notes}` | Notes folder name | `claims/` | `reflections/` |
+| `{vocabulary.note}` / `{vocabulary.note_plural}` | Note type | `claim` / `claims` | `reflection` / `reflections` |
+| `{vocabulary.topic_map}` / `{vocabulary.topic_map_plural}` | MOC reference | `MOC` / `MOCs` | `theme map` / `theme maps` |
+| `{vocabulary.cmd_reflect}` | Connection command | `/reflect` | `/find-patterns` |
+| `{vocabulary.cmd_reweave}` | Backward-pass command | `/reweave` | `/revisit` |
+
+## Processing Depth Calibration
+
+Graph analysis does not vary by processing depth. All operations run the same way regardless of the user's depth setting. The operations themselves range from quick (single-note traversal) to comprehensive (full-graph cluster analysis), but this is controlled by which operation the user selects, not by a depth setting.
+
+## Skill Template
+
+**Source:** `skill-sources/graph/SKILL.md` (reference implementation, 567 lines)
+
+The derivation engine reads the full `skill-sources/graph/SKILL.md` and applies vocabulary transformation:
+
+1. Replace skill frontmatter with domain vocabulary
+2. Replace all `{vocabulary.X}` markers with resolved values
+3. Replace `{DOMAIN:...}` markers with domain-specific terms
+4. Preserve all 9 operations with their analysis scripts
+5. Preserve interactive mode (natural language question routing)
+6. Preserve findings + actions output pattern for every operation
+7. Preserve graph script generation during /setup
+
+### Operations (Invariant — all 9 must be present)
+
+| Operation | Script | What It Reveals |
+|-----------|--------|----------------|
+| `health` | Multiple scripts | Comprehensive graph health report (orphans, dangles, density, coverage) |
+| `triangles` | `find-triangles.sh` | Synthesis opportunities: A links to B, A links to C, but B does not link to C |
+| `bridges` | `find-bridges.sh` | Fragile {vocabulary.note_plural}: removal would disconnect graph regions |
+| `clusters` | `find-clusters.sh` | Connected components — isolated subgraphs that may need cross-linking |
+| `hubs` | `influence-flow.sh` | Hub/authority analysis — which {vocabulary.note_plural} are most influential |
+| `siblings` | `topic-siblings.sh` | Unconnected {vocabulary.note_plural} sharing a {vocabulary.topic_map} — missed connections |
+| `forward` | `n-hop-forward.sh` | N-hop forward traversal from a specific {vocabulary.note} |
+| `backward` | `recursive-backlinks.sh` | N-hop backward traversal to a specific {vocabulary.note} |
+| `query` | Combined | Natural language graph question (routed to appropriate operation) |
+
+### Operation Output Pattern (Invariant)
+
+Every operation produces exactly two sections:
+
+```
+--=={ name : graph > {operation} }==--
+
+  Findings:
+    [interpreted results using {vocabulary.note} descriptions]
+    [domain-specific context, not raw data]
+
+  Actions:
+    [specific commands to run]
+    [e.g., "/{vocabulary.cmd_reflect} [[note A]] [[note B]]"]
+    [e.g., "/{vocabulary.cmd_reweave} [[bridge note]]"]
+```
+
+Never dump raw script output. Always interpret results with {vocabulary.note} descriptions loaded from the notes' YAML frontmatter.
+
+### Interactive Mode
+
+When invoked without arguments or with a natural language question, route to the closest operation:
+
+| Question Pattern | Routes To |
+|-----------------|-----------|
+| "what needs connecting?" | triangles |
+| "is the graph healthy?" | health |
+| "what would break if removed?" | bridges |
+| "are there isolated clusters?" | clusters |
+| "what's most important?" | hubs |
+| "what's related to [[X]]?" | forward (from X) |
+| "what links to [[X]]?" | backward (to X) |
+| "what should I link in [[topic]]?" | siblings |
+
+If the question cannot be mapped, show the operations list and ask the user to choose.
+
+### Graph Script Generation
+
+During /setup, the derivation engine generates graph analysis scripts in `ops/scripts/graph/`:
+
+- Scripts use `{vocabulary.notes}` for the notes directory path
+- Scripts use wiki link syntax `[[title]]` for output
+- Scripts are bash, platform-independent
+- Each script is self-contained (no dependencies beyond grep, awk, sort)
+
+### Health Report Structure
+
+The `health` operation combines multiple scripts into a single report:
+
+```
+--=={ name : graph > health }==--
+
+  | Metric                    | Value | Status |
+  |---------------------------|-------|--------|
+  | Total {vocabulary.note_plural}      | {N}   | —      |
+  | Orphans                   | {N}   | {PASS/WARN} |
+  | Dangling links            | {N}   | {PASS/WARN} |
+  | Avg links per {vocabulary.note}     | {N}   | {PASS/WARN} |
+  | {vocabulary.topic_map} coverage    | {N}%  | {PASS/WARN} |
+  | Bridge {vocabulary.note_plural}    | {N}   | {INFO} |
+  | Synthesis opportunities   | {N}   | {INFO} |
+
+  Priority actions:
+    1. [most urgent graph issue with command]
+    2. [next priority]
+```
+
+## Validation Criteria
+
+- [ ] All 9 operations documented with scripts
+- [ ] Findings + Actions output pattern for every operation
+- [ ] Interactive mode routing table present
+- [ ] Health report structure documented
+- [ ] Graph script generation during /setup described
+- [ ] Never dump raw data — always interpret with descriptions
+- [ ] `{vocabulary.X}` markers used throughout
+- [ ] Specific command suggestions in Actions sections

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

@@ -0,0 +1,119 @@
+# Skill Generation Block: learn
+
+## Generation Metadata
+
+```yaml
+skill_name: learn
+purpose: "Research a topic and grow the knowledge graph"
+domain_verb: "{DOMAIN:learn}"
+output_type: "inbox file with full provenance, chained to pipeline"
+triggers:
+  - "/{DOMAIN:learn}"
+  - "/{DOMAIN:learn} [topic]"
+  - "research this"
+  - "find out about"
+  - "explore [topic]"
+search_mode: none  # learn produces content, does not search existing graph
+quality_gates:
+  - provenance metadata complete (exa_prompt, exa_tool, generated timestamp)
+  - results filed to inbox (not pasted inline)
+  - topic connected to goals if applicable
+  - pipeline chaining offered (manual, suggested, or automatic)
+handoff_protocol: false  # interactive research, not orchestrated
+pipeline_position: pre_pipeline  # feeds INTO the pipeline via inbox
+next_phase: "{DOMAIN:seed}"
+```
+
+## Vocabulary Transformation Map
+
+| Marker | Resolves To | Example (Research) | Example (Personal) |
+|--------|-------------|-------------------|-------------------|
+| `{vocabulary.inbox}` | Inbox folder name | `inbox/` | `journal/` |
+| `{vocabulary.note}` / `{vocabulary.note_plural}` | Note type | `claim` / `claims` | `reflection` / `reflections` |
+| `{vocabulary.cmd_reduce}` | Process command for chaining | `/reduce` | `/distill` |
+| `{vocabulary.cmd_seed}` | Seed command for chaining | `/seed` | `/seed` |
+| `{DOMAIN:the knowledge domain}` | Research focus lens | `agent-operated knowledge systems` | `personal growth` |
+
+## Processing Depth Calibration
+
+Learn supports three research depths that map to different tool cascades:
+
+| Depth | Primary Tool | Fallback | Use Case |
+|-------|-------------|----------|----------|
+| **deep** | exa-deep-research | exa-web-search | Comprehensive topic exploration, literature review |
+| **moderate** | exa-web-search | web-search | Targeted research on specific question |
+| **light** | web-search | none | Quick fact-checking, current events |
+
+Depth is set by: explicit flag (`--deep`, `--moderate`, `--light`) > `ops/config.yaml` default > fallback to moderate.
+
+## Skill Template
+
+**Source:** `skill-sources/learn/SKILL.md` (reference implementation, 255 lines)
+
+The derivation engine reads the full `skill-sources/learn/SKILL.md` and applies vocabulary transformation:
+
+1. Replace skill frontmatter with domain vocabulary
+2. Replace all `{vocabulary.X}` markers with resolved values
+3. Replace `{DOMAIN:...}` markers with domain-specific terms
+4. Preserve three-depth research cascade (deep, moderate, light)
+5. Preserve full Exa provenance metadata requirements
+6. Preserve pipeline chaining options (manual, suggested, automatic)
+7. Preserve goals.md integration (read for topics, update with discoveries)
+
+### Research Flow (Invariant)
+
+```
+1. READ CONFIG — tool preferences, depth, domain vocabulary
+2. DETERMINE DEPTH — from flags, config, or default (moderate)
+3. RESEARCH — tool cascade: primary → fallback → last resort
+4. FILE TO INBOX — {vocabulary.inbox}/{date}-{topic-slug}.md
+5. CHAIN TO PIPELINE — based on pipeline.chaining setting
+6. UPDATE GOALS — append new research directions if discovered
+```
+
+### Provenance Requirements (Invariant)
+
+Every research result filed to inbox MUST include these YAML fields:
+
+| Exa Tool | source_type | Required Fields |
+|----------|-------------|-----------------|
+| deep_researcher | `exa-deep-research` | exa_prompt, exa_research_id, exa_model, generated |
+| web_search | `exa-web-search` | exa_prompt, exa_tool, generated |
+| get_code_context | `exa-web-search` | exa_prompt, exa_tool, generated |
+| WebSearch | `web-search` | search_query, generated |
+
+**The exa_prompt field is critical** — it captures the intellectual context that shaped what Exa returned. Without it, claims cannot be traced back to their research origin.
+
+### Pipeline Chaining
+
+After filing research to inbox, chain based on `ops/config.yaml` setting:
+
+| Mode | Behavior |
+|------|----------|
+| `manual` | Show path to filed research. User decides next step. |
+| `suggested` | Show path + suggest: "Run /{vocabulary.cmd_seed} {filepath} to begin extraction." |
+| `automatic` | Automatically invoke /{vocabulary.cmd_seed} on the filed research. |
+
+### Goals Integration
+
+If `self/goals.md` exists:
+- Before research: read goals to see if topic aligns with existing priorities
+- After research: if new research directions were discovered, append them to goals
+
+### No-Topic Fallback
+
+If invoked without a topic:
+1. Read `self/goals.md` for highest-priority unexplored direction
+2. If found: propose it ("Your goals mention [X] — want me to research that?")
+3. If no goals file: ask "What would you like to research?"
+
+## Validation Criteria
+
+- [ ] Three research depths documented (deep, moderate, light)
+- [ ] Tool cascade for each depth specified
+- [ ] Provenance metadata table present
+- [ ] Pipeline chaining modes documented (manual, suggested, automatic)
+- [ ] Goals integration (read before, update after)
+- [ ] No-topic fallback logic present
+- [ ] Inbox filing with date-prefix filename convention
+- [ ] `{vocabulary.X}` markers used throughout

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

@@ -0,0 +1,131 @@
+# Skill Generation Block: next
+
+## Generation Metadata
+
+```yaml
+skill_name: next
+purpose: "Surface the most valuable next action based on vault state"
+domain_verb: "{DOMAIN:next}"
+output_type: "prioritized recommendation with rationale"
+triggers:
+  - "/{DOMAIN:next}"
+  - "what should I do"
+  - "what's next"
+  - "what needs attention"
+search_mode: none  # reads state, does not search
+quality_gates:
+  - recommendation is singular (one action, not a list)
+  - rationale references specific vault state
+  - consequence speed classification is explicit
+  - deduplication against recent recommendations
+handoff_protocol: false  # advisory skill, not orchestrated
+pipeline_position: meta_cognitive  # operates outside the main pipeline
+```
+
+## Vocabulary Transformation Map
+
+| Marker | Resolves To | Example (Research) | Example (Personal) |
+|--------|-------------|-------------------|-------------------|
+| `{vocabulary.notes}` | Notes folder name | `claims/` | `reflections/` |
+| `{vocabulary.inbox}` | Inbox folder name | `inbox/` | `journal/` |
+| `{vocabulary.note}` / `{vocabulary.note_plural}` | Note type | `claim` / `claims` | `reflection` / `reflections` |
+| `{vocabulary.topic_map}` | MOC reference | `MOC` | `theme map` |
+| `{vocabulary.cmd_reduce}` | Processing command | `/reduce` | `/distill` |
+| `{vocabulary.cmd_reflect}` | Connection command | `/reflect` | `/find-patterns` |
+| `{vocabulary.cmd_reweave}` | Backward-pass command | `/reweave` | `/revisit` |
+| `{vocabulary.rethink}` | Rethink command | `rethink` | `reassess` |
+
+## Processing Depth Calibration
+
+/next does not vary by processing depth — it is a read-only advisory operation that measures vault state and recommends one action. The recommendation may reference depth-appropriate actions (e.g., suggesting quick processing vs deep extraction) but the skill itself always runs the same way.
+
+## Skill Template
+
+**Source:** `skill-sources/next/SKILL.md` (reference implementation, 329 lines)
+
+The derivation engine reads the full `skill-sources/next/SKILL.md` and applies vocabulary transformation:
+
+1. Replace skill frontmatter with domain vocabulary
+2. Replace all `{vocabulary.X}` markers with resolved values
+3. Replace `{DOMAIN:...}` markers with domain-specific terms
+4. Preserve 14-signal vault state collection
+5. Preserve consequence speed classification (session > multi-session > slow)
+6. Preserve 4-level priority cascade (task stack > session > multi-session > slow)
+7. Preserve deduplication via ops/next-log.md
+8. Apply clean output format (no branded frames per Section 10.5)
+
+### Vault State Signals (Invariant — all 14 must be collected)
+
+| Signal | What It Measures |
+|--------|-----------------|
+| Task stack depth | ops/tasks.md pending items |
+| Queue pending count | ops/queue/queue.json pending tasks |
+| Queue blocked count | Tasks waiting on dependencies |
+| Inbox count | Unprocessed items in {vocabulary.inbox}/ |
+| Pending observations | ops/observations/*.md count |
+| Pending tensions | ops/tensions/*.md count |
+| Unprocessed sessions | ops/sessions/*.json count |
+| Orphan {vocabulary.note_plural} | Notes with zero incoming links |
+| Dangling links | Wiki links to non-existent files |
+| {vocabulary.topic_map} coverage | Notes not appearing in any {vocabulary.topic_map} |
+| Stale {vocabulary.note_plural} | Notes not modified in 30+ days with low link density |
+| Goals staleness | Days since goals file was last updated |
+| Tutorial state | Incomplete tutorial step |
+| Pipeline pressure | Active batches with incomplete phases |
+| Maintenance queue state | ops/queue/queue.json maintenance tasks |
+
+### Consequence Speed Classification (Invariant)
+
+| Speed | Meaning | Examples |
+|-------|---------|---------|
+| **session** | Inaction degrades THIS session | Orphans, dangling links, inbox pressure, task stack items |
+| **multi_session** | Inaction degrades over 2-5 sessions | Pipeline batches, observation accumulation, stale goals |
+| **slow** | Inaction degrades over weeks | {vocabulary.topic_map} oversizing, rethink thresholds, deep maintenance |
+
+### Priority Cascade (Invariant)
+
+```
+Level 1: Task stack items (user's explicit priorities — always first)
+Level 2: Session-speed signals (what degrades THIS session)
+Level 3: Multi-session signals (what degrades over 2-5 sessions)
+Level 4: Slow signals (weeks-scale degradation)
+```
+
+Within each level, pick the signal with the highest count or most severe consequence.
+
+### Output Format
+
+```
+next
+
+  Recommended: [one specific action with command]
+
+  Why: [2-3 sentences referencing specific vault state]
+
+  Consequence speed: [session|multi_session|slow]
+  Signal: [which signal triggered this]
+
+  Other signals: [brief list of non-critical signals]
+```
+
+### Deduplication
+
+After each recommendation, append to `ops/next-log.md`:
+
+```markdown
+- {YYYY-MM-DD}: Recommended {action} (signal: {signal}, speed: {speed})
+```
+
+Before recommending, check the log: if the same signal was recommended in the last 2 entries and the user did not act on it, deprioritize it and surface the next-highest signal instead. Persistent ignoring signals intent.
+
+## Validation Criteria
+
+- [ ] All 14 vault state signals documented with collection method
+- [ ] Consequence speed classification present (session, multi_session, slow)
+- [ ] Priority cascade documented (4 levels)
+- [ ] Singular recommendation output (not a list)
+- [ ] Deduplication via next-log.md
+- [ ] Clean output format (no branded frames)
+- [ ] Maintenance queue reconciliation documented with create/close/update logic
+- [ ] Condition reconciliation runs BEFORE state collection
+- [ ] `{vocabulary.X}` markers used throughout (no hardcoded terms)