arscontexta 0.6.0

package/generators/features/graph-analysis.md

@@ -0,0 +1,188 @@
+# Feature: Graph Analysis
+
+## Context File Block
+
+```markdown
+## Graph Analysis — Your Vault as a Queryable Database
+
+Your wiki-linked vault is not just a folder of markdown files. It is a graph database:
+
+- **Nodes** are markdown files (your {DOMAIN:notes})
+- **Edges** are wiki links (`[[connections]]` between {DOMAIN:notes})
+- **Properties** are YAML frontmatter fields (structured metadata on every node)
+- **Query engine** is ripgrep (`rg`) operating over structured text
+
+This means every question you can ask about a graph database — "what connects to what?", "where are the clusters?", "what is isolated?" — you can answer with standard command-line tools. No external database required. The filesystem IS the database.
+
+### Three Query Levels
+
+Graph queries operate at three levels of increasing sophistication:
+
+#### Level 1: Field-Level Queries (Property Inspection)
+
+Query individual YAML fields across {DOMAIN:notes}:
+
+```bash
+# Find all {DOMAIN:notes} of a specific type
+rg '^type: pattern' {DOMAIN:notes}/
+
+# Scan descriptions for a concept
+rg '^description:.*friction' {DOMAIN:notes}/
+
+# Find {DOMAIN:notes} missing required fields
+rg -L '^description:' {DOMAIN:notes}/*.md
+
+# Find {DOMAIN:notes} by {DOMAIN:topic map}
+rg '^topics:.*\[\[methodology\]\]' {DOMAIN:notes}/
+
+# Cross-field queries (combine with xargs)
+rg -l '^type: tension' {DOMAIN:notes}/ | xargs rg '^status: pending'
+```
+
+Field-level queries answer: "What properties do my {DOMAIN:notes} have?" They are fast, precise, and require no external tools.
+
+#### Level 2: Node-Level Queries (Neighborhood Inspection)
+
+Query a specific {DOMAIN:note}'s relationships — what it links to, what links to it:
+
+```bash
+# Find all outgoing links from a {DOMAIN:note}
+./ops/scripts/graph/extract-links.sh "{DOMAIN:note} title"
+
+# Find all incoming links (backlinks) to a {DOMAIN:note}
+./ops/scripts/backlinks.sh "{DOMAIN:note} title"
+
+# Count connections
+./ops/scripts/backlinks.sh "{DOMAIN:note} title" --count
+```
+
+Node-level queries answer: "What is this {DOMAIN:note}'s neighborhood?" They reveal a single node's context within the larger graph.
+
+#### Level 3: Graph-Level Queries (Structural Analysis)
+
+Query the graph's topology — clusters, bridges, synthesis opportunities, influence patterns:
+
+```bash
+# Find synthesis opportunities (open triangles)
+./ops/scripts/graph/find-triangles.sh
+
+# Detect isolated clusters
+./ops/scripts/graph/find-clusters.sh
+
+# Find structurally critical {DOMAIN:notes}
+./ops/scripts/graph/find-bridges.sh
+
+# Measure overall graph health
+./ops/scripts/link-density.sh
+```
+
+Graph-level queries answer: "What does the structure of my knowledge look like?" They reveal patterns invisible from any single {DOMAIN:note}.
+
+### Available Graph Operations
+
+#### Traversal Operations
+
+Navigate the graph from any starting point:
+
+| Operation | Script | What It Does |
+|-----------|--------|-------------|
+| Forward N-hop | `graph/n-hop-forward.sh "{DOMAIN:note}" [depth]` | Find everything reachable within N links from a starting {DOMAIN:note}. Depth 1 shows direct connections; depth 2 shows connections-of-connections. Useful for understanding a concept's reach. |
+| Backward N-hop | `graph/recursive-backlinks.sh "{DOMAIN:note}" [depth]` | Find everything that leads TO a {DOMAIN:note} within N hops. Reveals what lines of thought converge on a concept. |
+| Link extraction | `graph/extract-links.sh "{DOMAIN:note}"` | List all wiki links in a specific {DOMAIN:note}. The raw edge list from a single node. |
+
+#### Synthesis Operations
+
+Detect opportunities for new connections and insights:
+
+| Operation | Script | What It Does |
+|-----------|--------|-------------|
+| Triangle detection | `graph/find-triangles.sh` | Find open triadic closures: {DOMAIN:note} A links to B, A links to C, but B and C do not link to each other. These are synthesis opportunities — two concepts connected through a shared parent but not yet directly related. |
+| Topic siblings | `graph/topic-siblings.sh "{DOMAIN:topic map}"` | Find {DOMAIN:notes} in the same {DOMAIN:topic map} that do not link to each other. Notes that share a topic but lack direct connections often reveal unexplored relationships. |
+
+Triangle detection is particularly powerful because it finds structural gaps that browsing cannot detect. When A links to B and A links to C, there is often a genuine relationship between B and C that was simply not captured. The script surfaces these candidates for human judgment — not every open triangle should close, but many reveal real connections.
+
+#### Structural Operations
+
+Understand the architecture of your knowledge graph:
+
+| Operation | Script | What It Does |
+|-----------|--------|-------------|
+| Cluster detection | `graph/find-clusters.sh` | Find connected components — groups of {DOMAIN:notes} that link to each other but not to other groups. Reveals topic boundaries and isolated knowledge islands. |
+| Bridge detection | `graph/find-bridges.sh` | Find bridge {DOMAIN:notes} — nodes whose removal would disconnect parts of the graph. These are structurally critical and may need splitting to reduce fragility. |
+| Connected components | `graph/find-clusters.sh --components` | Count the number of separate connected subgraphs. A healthy vault is one large connected component. Multiple components suggest domain silos. |
+
+#### Density Operations
+
+Measure the health of your graph's connectivity:
+
+| Operation | Script | What It Does |
+|-----------|--------|-------------|
+| Link density | `link-density.sh` | Average outgoing links per {DOMAIN:note}. Target: 3+ links per {DOMAIN:note}. Below this, the graph is sparse and traversal is unreliable. |
+| Orphan detection | `orphan-notes.sh` | {DOMAIN:Notes} with zero incoming links. Invisible to traversal — they exist but no path leads to them. |
+| Dangling links | `dangling-links.sh` | Wiki links pointing to {DOMAIN:notes} that do not exist. Demand signals for what should be created. |
+
+#### Centrality Operations
+
+Identify the most important and influential {DOMAIN:notes}:
+
+| Operation | Script | What It Does |
+|-----------|--------|-------------|
+| Hub/authority ranking | `graph/influence-flow.sh` | Ranks {DOMAIN:notes} by link patterns. Hubs are {DOMAIN:notes} with many outgoing links (they point to lots of things). Authorities are {DOMAIN:notes} with many incoming links (lots of things point to them). Synthesizers have both high incoming and high outgoing — they integrate knowledge. |
+
+#### Schema Queries
+
+Use YAML frontmatter as a queryable property layer:
+
+```bash
+# All {DOMAIN:notes} by methodology tradition
+rg '^methodology:.*Zettelkasten' {DOMAIN:notes}/
+
+# Unresolved tensions
+rg -l '^type: tension' {DOMAIN:notes}/ | xargs rg '^status: pending'
+
+# {DOMAIN:Notes} adapted from human patterns
+rg '^adapted_from: ' {DOMAIN:notes}/ | grep -v 'null'
+
+# Combined methodology synthesis {DOMAIN:notes}
+rg '^methodology: \[' {DOMAIN:notes}/ | grep -E '\[.*,.*\]'
+
+# {DOMAIN:Notes} without source attribution
+rg -L '^source:' {DOMAIN:notes}/*.md
+```
+
+Schema queries are domain-adapted: the specific fields and enum values come from your templates. Every schema field becomes a query dimension. Combining dimensions surfaces cross-cutting insights that browsing alone cannot find.
+
+### The /graph Command
+
+Use /{DOMAIN:analyze} for interactive graph analysis. Ask questions in natural language or use explicit operation names:
+
+```
+/{DOMAIN:analyze} "What connects to [[{DOMAIN:note} title]]?"
+/{DOMAIN:analyze} triangles
+/{DOMAIN:analyze} "Where are synthesis opportunities?"
+/{DOMAIN:analyze} orphans
+/{DOMAIN:analyze} "What are the most influential {DOMAIN:notes}?"
+/{DOMAIN:analyze} density
+```
+
+The command routes to the appropriate script(s), interprets results in domain vocabulary, and suggests concrete actions. Results always include context (descriptions, relationship types), not bare file lists. Large result sets are summarized with top findings rather than dumped in full.
+
+### When to Use Each Operation Type
+
+| Situation | Operation | Why |
+|-----------|-----------|-----|
+| Just created new {DOMAIN:notes} | Triangle detection + topic siblings | Find connections you missed during creation |
+| Graph feels disconnected | Cluster detection + bridge analysis | Understand the structure and find linking opportunities |
+| Preparing for a synthesis session | Forward N-hop from key {DOMAIN:notes} | Map the neighborhood before writing |
+| Health check | Orphan detection + dangling links + density | Standard diagnostic pass |
+| Prioritizing maintenance | Influence flow + bridge detection | Focus on structurally important {DOMAIN:notes} first |
+| Exploring a new topic | Backward N-hop to the {DOMAIN:topic map} | See what converges on this topic |
+| Schema audit | Field-level queries across all {DOMAIN:notes} | Verify consistency and completeness |
+
+### Limitations
+
+Graph analysis scripts find structural patterns — they cannot assess whether a connection is intellectually warranted. Triangle detection reveals that B and C share a parent but are not linked; it cannot tell you whether B and C SHOULD be linked. That judgment is yours. Use structural analysis to find candidates, then apply intellectual judgment to evaluate them.
+```
+
+## Dependencies
+Requires: wiki-links (graph edges depend on wiki link infrastructure), schema (property queries depend on structured YAML)

package/generators/features/helper-functions.md

@@ -0,0 +1,92 @@
+# Feature: Helper Functions
+
+## Context File Block
+
+```markdown
+## Helper Functions — Essential Graph Infrastructure
+
+Your vault ships with utility scripts for safe graph maintenance. These are not afterthoughts — they are essential infrastructure that prevents common failure modes when working with a wiki-linked knowledge graph.
+
+### Safe Rename
+
+Never rename a {DOMAIN:note} manually. Manual renames break every wiki link that references the old title, silently degrading the graph. Use the rename script:
+
+```bash
+./ops/scripts/rename-note.sh "old title" "new title"
+```
+
+The script:
+1. Finds the file by name (searches the entire vault)
+2. Renames with `git mv` (preserves history)
+3. Updates ALL wiki links across every file in the vault
+4. Verifies no broken links remain after the rename
+
+This is the only safe way to rename. Wiki links resolve by filename — when a filename changes, every `[[old title]]` in the vault becomes a dangling link unless updated. The script handles this atomically.
+
+### Graph Maintenance Utilities
+
+Scripts for detecting and resolving common graph health issues:
+
+**Orphan detection** — Find {DOMAIN:notes} with no incoming links. Orphaned {DOMAIN:notes} are invisible to traversal — they exist but nobody can reach them:
+```bash
+./ops/scripts/orphan-notes.sh
+```
+Every orphan is either a gap (needs connections) or stale (needs archiving). Neither is acceptable as a permanent state.
+
+**Dangling link detection** — Find wiki links that point to non-existent {DOMAIN:notes}:
+```bash
+./ops/scripts/dangling-links.sh
+```
+Dangling links are demand signals — they tell you what {DOMAIN:notes} should exist but do not. Either create the missing {DOMAIN:note} or fix the link.
+
+**Backlink count** — Count incoming links to a specific {DOMAIN:note}:
+```bash
+./ops/scripts/backlinks.sh "note title"
+```
+High backlink counts identify hub {DOMAIN:notes} — central concepts that many other {DOMAIN:notes} reference. Low counts on important {DOMAIN:notes} suggest connection-finding opportunities.
+
+**Link density** — Measure the average number of links per {DOMAIN:note}:
+```bash
+./ops/scripts/link-density.sh
+```
+Healthy graphs maintain an average of 3+ outgoing links per {DOMAIN:note}. Below that threshold, the graph is sparse and traversal becomes unreliable.
+
+**Schema validation** — Validate all {DOMAIN:notes} against their template schemas:
+```bash
+./ops/scripts/validate-schema.sh
+```
+Checks required fields, enum values, and constraints. Reports violations by severity (PASS, WARN, FAIL).
+
+### Batch Operations
+
+When processing multiple {DOMAIN:notes}, batch utilities streamline common operations:
+
+- **Queue status** — View pending tasks, phase distribution, archivable batches, and stalled batches:
+  ```bash
+  ./ops/scripts/queue-status.sh
+  ```
+
+- **Workboard reconciliation** — Run condition-based invariant checks, surface violated conditions as tasks, and auto-close satisfied conditions:
+  ```bash
+  ./ops/scripts/reconcile.sh
+  ```
+  This is idempotent — safe to run any number of times. It only reads state, never modifies your {DOMAIN:notes} or graph.
+
+### Domain-Specific Helpers
+
+As your vault grows, you may create additional utility scripts for domain-specific operations. Place them in `ops/scripts/` and document their usage here. Common extensions include:
+
+- Export scripts for sharing subsets of the graph
+- Import scripts for bulk ingestion from external sources
+- Report generators for domain-specific analytics
+- Migration scripts for schema evolution across existing {DOMAIN:notes}
+
+The pattern: if you find yourself running the same sequence of commands repeatedly, extract it into a script. Scripts encode methodology the same way skills do — they make repeatable operations reliable and consistent.
+
+### When to Use Helpers vs Skills
+
+Helpers are lightweight, stateless utilities — they inspect or modify the graph without pipeline state. Skills are pipeline-aware workflows with quality gates, handoff protocols, and queue integration. Use helpers for quick checks and mechanical operations. Use skills for knowledge work that requires judgment and quality verification.
+```
+
+## Dependencies
+None — helper functions are standalone utilities.

package/generators/features/maintenance.md

@@ -0,0 +1,164 @@
+# Feature: Maintenance
+
+## Context File Block
+
+```markdown
+## Maintenance — Keeping the Graph Healthy
+
+A knowledge graph degrades without maintenance. Notes written last month don't know about notes written today. Links break when titles change. {DOMAIN:topic maps} grow stale as topics evolve. Maintenance is not optional — it's what keeps the system useful.
+
+### Health Check Categories
+
+Run these checks when conditions warrant — orphans detected, links broken, schema violations accumulated:
+
+**1. Orphan Detection**
+{DOMAIN:Notes} with no incoming links are invisible to traversal. Find them:
+```bash
+# Find notes not linked from anywhere
+rg -l '.' {DOMAIN:notes/}*.md | while read f; do
+  title=$(basename "$f" .md)
+  rg -q "\[\[$title\]\]" {DOMAIN:notes/} || echo "Orphan: $f"
+done
+```
+Every orphan is either a gap (needs connections) or stale (needs archiving).
+
+**2. Dangling Links**
+Wiki links pointing to non-existent {DOMAIN:notes} create confusion:
+```bash
+# Find [[links]] to files that don't exist
+rg -o '\[\[([^\]]+)\]\]' {DOMAIN:notes/} -r '$1' --no-filename | sort -u | while read title; do
+  find . -name "$title.md" -not -path "./.git/*" | grep -q . || echo "Dangling: [[$title]]"
+done
+```
+Either create the missing {DOMAIN:note} or fix the link.
+
+**3. Schema Validation**
+Check that {DOMAIN:notes} have required YAML fields:
+```bash
+rg -L '^description:' {DOMAIN:notes/}*.md    # missing descriptions
+```
+Missing descriptions mean the {DOMAIN:note} can't be filtered during search.
+
+**4. {DOMAIN:Topic Map} Coherence**
+{DOMAIN:Topic maps} should accurately reflect the notes they organize:
+- Do all listed {DOMAIN:notes} still exist?
+- Are there {DOMAIN:notes} on this topic NOT listed in the {DOMAIN:topic map}?
+- Has the topic grown large enough to warrant splitting?
+
+**5. Stale Content**
+{DOMAIN:Notes} that haven't been touched in a long time may contain outdated claims. Check modification dates and review oldest notes first.
+
+### Reweaving — The Backward Pass
+
+New {DOMAIN:notes} create connections going forward. But older {DOMAIN:notes} don't automatically know about newer ones. Reweaving is the practice of revisiting old {DOMAIN:notes} and asking: "If I wrote this today, what would be different?"
+
+**Reweaving can:**
+- Add connections to newer {DOMAIN:notes} that didn't exist when the original was written
+- Sharpen a claim that's become clearer with more context
+- Split a {DOMAIN:note} that actually contains multiple ideas
+- Challenge a claim that new evidence contradicts
+- Rewrite prose to incorporate new links inline
+
+**When to reweave:**
+- After creating a batch of new {DOMAIN:notes} — check what older {DOMAIN:notes} should link to them
+- When a health check flags sparse {DOMAIN:notes} with few connections
+- When {DOMAIN:notes} have not been touched since N new notes were added to the graph
+- When a {DOMAIN:note} feels disconnected from the rest of the graph
+
+### Condition-Based Maintenance
+
+Maintenance triggers are condition-based, not time-based. Time-based triggers (weekly, monthly, quarterly) assume uniform activity — a vault that scales fast would overwhelm a monthly check, while a vault used rarely would run empty checks on schedule. Condition-based triggers respond to actual state, firing exactly when the system needs attention.
+
+| Condition | Threshold | Action When True |
+|-----------|-----------|-----------------|
+| Orphan {DOMAIN:notes} | Any detected | Surface for connection-finding |
+| Dangling links | Any detected | Surface for resolution |
+| {DOMAIN:Topic map} size | >40 {DOMAIN:notes} | Suggest sub-{DOMAIN:topic map} split |
+| Pending observations | >=10 | Suggest /{DOMAIN:rethink} |
+| Pending tensions | >=5 | Suggest /{DOMAIN:rethink} |
+| Inbox pressure | Items older than 3 days | Suggest processing |
+| Stale pipeline batch | >2 sessions without progress | Surface as blocked |
+| Schema violations | Any detected | Surface for correction |
+
+These conditions are evaluated by /next via queue reconciliation. When a condition fires, it materializes as a `type: "maintenance"` entry in the queue — not a calendar reminder.
+
+### Session Maintenance Checklist
+
+Before ending a work session:
+- [ ] New {DOMAIN:notes} are linked from at least one {DOMAIN:topic map}
+- [ ] Wiki links in new {DOMAIN:notes} point to real files
+- [ ] Descriptions add information beyond the title
+- [ ] Changes are committed
+
+### The Maintenance Mindset
+
+Maintenance is not cleanup — it's cultivation. Each pass through old {DOMAIN:notes} is an opportunity to deepen the graph. Reweaving discovers connections that weren't visible when the {DOMAIN:notes} were first written. Health checks reveal structural gaps that point toward missing insights.
+
+The graph doesn't just get maintained. It gets better.
+
+### Unified Queue Reconciliation
+
+Maintenance work lives alongside pipeline work in the same queue. Instead of a separate tracking file, /next evaluates conditions and materializes maintenance tasks directly in the queue.
+
+The reconciliation pattern:
+1. **Declare conditions** — the system defines what "healthy" looks like (desired state) via `maintenance_conditions` in the queue
+2. **Measure actual state** — /next compares reality against each condition on every invocation
+3. **Auto-create tasks** — when a condition is violated, a `type: "maintenance"` entry appears in the queue
+4. **Auto-close tasks** — when the condition is satisfied again, the entry is marked done
+
+This is idempotent: running /next any number of times produces the same queue state (no duplicates). Each `condition_key` has at most one pending maintenance task.
+
+The key insight: you don't manage task status manually. Fix the underlying problem and the task goes away on its own.
+
+### Invariant-Based Task Creation
+
+The reconciliation checks 12 invariants that together define a healthy system:
+
+| Invariant | What It Checks |
+|-----------|---------------|
+| Inbox pressure (per subdir) | Are {DOMAIN:inbox/} subdirectories accumulating unprocessed material? |
+| Orphan {DOMAIN:notes} | Are there {DOMAIN:notes} with no incoming links? |
+| Dangling links | Do wiki links point to non-existent {DOMAIN:notes}? |
+| Observation accumulation | Have pending observations exceeded the threshold (10+)? |
+| Tension accumulation | Have pending tensions exceeded the threshold (5+)? |
+| {DOMAIN:Topic map} size | Has any {DOMAIN:topic map} grown beyond its healthy range? |
+| Stale batches | Are there processing batches that have been sitting unfinished? |
+| Infrastructure ideas | Are there improvement ideas waiting for review? |
+| Pipeline pressure | Is the processing queue backing up? |
+| Schema compliance | Do all {DOMAIN:notes} pass schema validation? |
+| Experiment staleness | Are there experiments or trials that need evaluation? |
+
+Each invariant is self-healing: fix the underlying issue (process the inbox, connect the orphan, resolve the tension) and the task disappears at next reconciliation. No manual status updates needed.
+
+### Consequence-Speed Priority
+
+Maintenance tasks are prioritized by how fast their consequences compound, not by manual importance labels:
+
+| Consequence Speed | Priority | Examples | Why This Priority |
+|-------------------|----------|----------|-------------------|
+| `session` | Highest | Orphan {DOMAIN:notes}, dangling links, inbox pressure | These degrade your work quality right now — orphans are invisible, dangling links confuse traversal, inbox pressure means lost ideas |
+| `multi_session` | Medium | Pipeline batch completion, stale batches | These compound over days — unfinished batches block downstream work |
+| `slow` | Lower | {DOMAIN:Topic map} oversizing, rethink thresholds, infrastructure ideas | These compound over weeks — annoying but not blocking |
+
+The principle: a task that causes problems THIS session matters more than one that compounds slowly. Priority is derived from the invariant's consequence speed, not assigned by you. This means you don't waste time triaging priority — the system knows.
+
+### Integration with /{DOMAIN:next} and /{DOMAIN:rethink}
+
+The unified queue connects to two key workflows:
+
+**/{DOMAIN:next}** reconciles maintenance conditions and recommends the highest-priority action from the unified queue. It considers:
+- Consequence speed (session-priority maintenance tasks first)
+- Current pipeline state (are there claims waiting to be processed?)
+- Accumulated signals (are observations or tensions piling up?)
+
+This means you can start any session by asking "what should I work on?" and get a prioritized answer based on actual system state, not a stale to-do list.
+
+**/{DOMAIN:rethink}** is surfaced automatically when /next detects signal accumulation:
+- 10+ pending observations → /next creates a maintenance task suggesting /{DOMAIN:rethink}
+- 5+ pending tensions → /next creates a maintenance task suggesting /{DOMAIN:rethink}
+
+This closes the loop: maintenance detects that your system has accumulated enough operational evidence to warrant a meta-cognitive pass. You review the evidence, promote insights, implement changes, and the system evolves. Maintenance feeds evolution, evolution improves maintenance.
+```
+
+## Dependencies
+Requires: wiki-links (link health checks depend on wiki link infrastructure), mocs (MOC coherence checks require MOC awareness)

package/generators/features/methodology-knowledge.md

@@ -0,0 +1,70 @@
+# Feature: Methodology Knowledge
+
+## Context File Block
+
+```markdown
+## Your System's Self-Knowledge (ops/methodology/)
+
+Your vault knows why it was built the way it was. The `ops/methodology/` folder contains linked notes explaining configuration rationale, learned behavioral patterns, and operational evolution. This is not documentation *about* your system — it IS your system's self-model.
+
+### What Lives Here
+
+| Content | Created By | Purpose |
+|---------|-----------|---------|
+| Derivation rationale | /setup | Why each dimension was configured this way |
+| Behavioral patterns | /{DOMAIN:remember} | Learned corrections and operational guidance |
+| Configuration state | /{DOMAIN:rethink}, /architect | Active features, threshold adjustments |
+| Evolution history | /{DOMAIN:rethink}, /architect, /reseed | What changed and why |
+
+### How to Query Your Methodology
+
+Your methodology notes are plain markdown with YAML frontmatter. Query them directly — no special tools needed.
+
+```bash
+# List all methodology notes
+ls ops/methodology/*.md
+
+# Search by category
+rg '^category:' ops/methodology/
+
+# Find active directives (not archived)
+rg '^status: active' ops/methodology/
+
+# Keyword search across methodology
+rg -i 'duplicate' ops/methodology/
+
+# Read a specific note
+cat ops/methodology/derivation-rationale.md
+```
+
+### When to Consult Methodology
+
+| Task | Grep Pattern | What You'll Find |
+|------|-------------|-----------------|
+| Processing a source | `rg -i 'pipeline\|processing\|extract' ops/methodology/` | Pipeline preferences, extraction categories |
+| Finding connections | `rg -i 'connect\|link\|reflect' ops/methodology/` | Linking philosophy, connection standards |
+| Maintaining the graph | `rg -i 'maintenance\|health\|reweave' ops/methodology/` | Maintenance thresholds, condition triggers |
+| Writing for the domain | `rg -i 'voice\|tone\|vocabulary' ops/methodology/` | Domain vocabulary, personality guidance |
+| Quality checking | `rg -i 'quality\|schema\|validate' ops/methodology/` | Schema expectations, validation rules |
+
+**Key rule:** When methodology notes contradict the context file on behavioral specifics, methodology notes are the more current authority. The context file defines the architecture; methodology notes capture operational learnings that refine it.
+
+### The Research Foundation
+
+Your system's design choices are backed by a knowledge base of 249 interconnected methodology notes — research claims, guidance documents, and domain examples — covering knowledge systems, cognitive science, and agent cognition. Access it through:
+
+```
+/ask "why does my system use atomic notes?"
+/ask "what are the trade-offs of condition-based maintenance?"
+/ask "how should I handle sources that span multiple domains?"
+```
+
+The /ask command consults two knowledge layers:
+- **Local methodology** (ops/methodology/) — "How does MY system work?" questions
+- **Research graph** (249 bundled methodology notes) — "Why is this a good idea in general?" questions
+
+When you need to understand a design choice: check ops/methodology/ for the specific rationale, then /ask for the theoretical backing.
+```
+
+## Dependencies
+Requires: self-evolution (methodology-knowledge teaches querying; self-evolution teaches capturing and Rule Zero)

package/generators/features/mocs.md

@@ -0,0 +1,144 @@
+# Feature: MOCs (Maps of Content)
+
+## Context File Block
+
+```markdown
+## {DOMAIN:Topic Maps} — Attention Management
+
+{DOMAIN:Topic maps} organize {DOMAIN:notes} by topic. They are not folders — they are navigation hubs that reduce context-switching cost. When you switch to a topic, you need to know: what is known, what is in tension, what is unexplored. Without a {DOMAIN:topic map}, you search blindly. With a {DOMAIN:topic map}, you see the landscape immediately.
+
+### Why {DOMAIN:Topic Maps}
+
+A flat collection of {DOMAIN:notes} becomes unnavigable as it grows. At 20 {DOMAIN:notes}, you can load everything into context. At 100, you cannot. {DOMAIN:Topic maps} solve this by providing curated entry points into topic areas. They tell you what exists and WHY each {DOMAIN:note} matters in context — not just a list of titles, but a map with reasoning about relationships.
+
+### {DOMAIN:Topic Map} Taxonomy
+
+The system supports several types of navigation structures, each serving a different purpose:
+
+**Hub {DOMAIN:topic map}** — Entry point for the entire workspace. Pure navigation linking to domain {DOMAIN:topic maps}. One per workspace. Answers: "What topics exist?"
+
+**Domain {DOMAIN:topic map}** — Entry point for a research or knowledge area. Contains synthesis across the domain and links to topic-level {DOMAIN:topic maps}. Answers: "What are the big themes here?"
+
+**Topic {DOMAIN:topic map}** — Active workspace for a specific topic. Core ideas, tensions, gaps. This is where you start when you know which topic you are working in. Answers: "What do we know about this topic?"
+
+**Self {DOMAIN:topic map}** — Agent identity and operational memory (self/identity.md, self/methodology.md, etc.). Flat peer structure — these {DOMAIN:topic maps} are equals, not hierarchically related.
+
+**Operational {DOMAIN:topic map}** — Procedure tracking with atomic entries. Categories of observations, tensions, operational learnings. Answers: "What has the system noticed?"
+
+Not every type applies to every workspace. A simple system may have only topic {DOMAIN:topic maps}. A complex system may use the full taxonomy. Create the types you need, not the ones that theoretically could exist.
+
+### Your Starting {DOMAIN:Topic Maps}
+
+```
+self/
+├── identity.md      — {DOMAIN:topic map}: who you are
+├── methodology.md   — {DOMAIN:topic map}: how you work
+├── goals.md         — {DOMAIN:topic map}: current threads
+└── relationships.md — {DOMAIN:topic map}: key people (if relevant)
+```
+
+These are your foundation. As your {DOMAIN:notes}/ grows, you will create topic {DOMAIN:topic maps} there as well. Start with what you need and let the structure emerge from your content.
+
+### {DOMAIN:Topic Map} Structure
+
+```markdown
+# topic-name
+
+Brief orientation — 2-3 sentences explaining what this topic covers and how to use this {DOMAIN:topic map}.
+
+## Core Ideas
+- [[{DOMAIN:note}]] — context explaining why this matters here
+- [[{DOMAIN:note}]] — what this adds to the topic
+
+## Tensions
+Unresolved conflicts — intellectual work, not bugs. What questions remain open? Where do ideas clash?
+
+## Open Questions
+What is unexplored. Research directions, gaps in understanding, areas that need attention.
+```
+
+**The critical rule:** Core Ideas entries MUST have context phrases. A bare link list (`- [[{DOMAIN:note}]]` without explanation) is an address book, not a map. The context phrase explains WHY this {DOMAIN:note} belongs here and what it contributes to the topic. This is what makes {DOMAIN:topic maps} navigable — you can scan the context phrases to find the entry point you need without reading every linked {DOMAIN:note}.
+
+### Lifecycle
+
+**Create** when:
+- 5+ related {DOMAIN:notes} accumulate without navigation structure
+- You can not navigate a topic without loading everything into context
+- You find yourself repeatedly loading the same set of {DOMAIN:notes} across sessions
+- A topic appears in multiple existing {DOMAIN:topic maps}' Open Questions sections
+
+**Do NOT create** when fewer than 5 related {DOMAIN:notes} exist, the topic fits as a section in an existing {DOMAIN:topic map}, or "just in case." Premature creation adds maintenance burden without navigation value.
+
+**Split** when:
+- A {DOMAIN:topic map} exceeds 40 {DOMAIN:notes} and distinct sub-communities form
+- Sections have different update frequencies (one part is active, another is stable)
+- Navigation friction emerges — you can not quickly find what you need
+
+How to split: create sub-{DOMAIN:topic map}(s) named `parent-subtopic.md`. Move Core Ideas for the subtopic. Parent becomes domain-style ({DOMAIN:topic map} of {DOMAIN:topic maps}). Update all affected {DOMAIN:notes}' Topics footers.
+
+**Merge** when: Both {DOMAIN:topic maps} are small (under 30 combined {DOMAIN:notes}), significant content overlap exists, and they update at the same frequency.
+
+**Archive** when: fewer than 5 {DOMAIN:notes} remain and the topic has been stagnant for 6+ months, the {DOMAIN:topic map} has been superseded, or all {DOMAIN:notes} have been absorbed elsewhere. Move to archive, do not delete.
+
+### Maintenance Protocol
+
+**Continuous (every {DOMAIN:note} creation):**
+1. Add the new {DOMAIN:note} to relevant {DOMAIN:topic map}(s) Core Ideas with a context phrase
+2. If the {DOMAIN:note} spans multiple topics, add to all relevant {DOMAIN:topic maps}
+3. Update the {DOMAIN:note}'s Topics footer to list its {DOMAIN:topic maps}
+
+This is handled by /{DOMAIN:connect} in the pipeline. When creating {DOMAIN:notes} manually (not through the pipeline), you must do this yourself.
+
+**Condition-based checks:**
+
+| Condition | Action When True |
+|-----------|-----------------|
+| {DOMAIN:Topic map} exceeds 40 {DOMAIN:notes} | Consider splitting into sub-{DOMAIN:topic maps} |
+| Orphan {DOMAIN:notes} detected | Add to appropriate {DOMAIN:topic map} |
+| Dangling links in {DOMAIN:topic map} | Fix or remove broken links |
+| {DOMAIN:Topic map} not updated in 90+ days | Review and refresh |
+
+### Health Metrics
+
+| Metric | Healthy | Warning | Action |
+|--------|---------|---------|--------|
+| {DOMAIN:Notes} per topic {DOMAIN:topic map} | 10-40 | >50 | Split into sub-{DOMAIN:topic maps} |
+| Orphan {DOMAIN:notes} | 0 | Any | Add to appropriate {DOMAIN:topic map} |
+| Dangling links in {DOMAIN:topic map} | 0 | Any | Fix or remove |
+| {DOMAIN:Topic map} last updated | Recent | >90 days | Review and refresh |
+
+### Multi-{DOMAIN:Topic Map} Membership
+
+Some {DOMAIN:notes} genuinely span multiple topics. This is valuable — it reveals synthesis opportunities and cross-cutting insights. List ALL relevant {DOMAIN:topic maps} in the {DOMAIN:note}'s Topics footer:
+
+```markdown
+Topics:
+- [[methodology]]
+- [[relationships]]
+```
+
+Cross-{DOMAIN:topic map} membership is a signal, not a problem. When a {DOMAIN:note} appears in multiple {DOMAIN:topic maps}, it often serves as a bridge between topic areas. The /{DOMAIN:connect} phase identifies these naturally.
+
+### Growing {DOMAIN:Topic Maps}
+
+- Start with the self/ {DOMAIN:topic maps} — they are your foundation
+- Create new {DOMAIN:topic maps} when a topic accumulates enough {DOMAIN:notes} to warrant navigation
+- Split {DOMAIN:topic maps} when they exceed their healthy range and sub-communities form
+- Every {DOMAIN:note} links back to its {DOMAIN:topic map}(s) via the Topics footer
+- The hierarchy emerges from your content, not from planning — let {DOMAIN:topic maps} form around natural clusters
+
+### Anti-Patterns
+
+**Bare link lists** — `- [[{DOMAIN:note}]]` without context phrases. These are address books, not maps. Always explain WHY each {DOMAIN:note} belongs.
+
+**{DOMAIN:Topic maps} as content** — Developed thinking belongs in {DOMAIN:notes}, not {DOMAIN:topic maps}. Synthesis that makes claims should become a synthesis {DOMAIN:note} linked FROM the {DOMAIN:topic map}, not prose within the {DOMAIN:topic map}.
+
+**Too many {DOMAIN:topic maps}** — If you can not decide which to update, merge small ones. A {DOMAIN:topic map} for 3 {DOMAIN:notes} is overhead without value.
+
+**Stale navigation** — Creating {DOMAIN:notes} without updating {DOMAIN:topic maps}. The pipeline handles this automatically; manual creation requires discipline.
+
+**Deep hierarchy** — Keep the {DOMAIN:topic map} depth manageable. Beyond 3-4 levels, reconsider your decomposition. Navigation should get you to the right {DOMAIN:note} in 2-3 hops, not 6.
+```
+
+## Dependencies
+Requires: wiki-links (MOCs use wiki-links to reference notes)