arscontexta 0.6.0

package/reference/templates/base-note.md

@@ -0,0 +1,16 @@
+---
+description: One sentence adding context beyond the title (~150 chars, no period)
+type: insight | pattern | preference | fact | decision | question
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the insight as a complete proposition
+
+Body text developing the insight. Show reasoning with connective words: because, therefore, this suggests, however.
+
+Use inline wiki-links as prose: "Since [[other note]], the question becomes..."
+
+---
+
+Topics:
+- [[parent-moc]]

package/reference/templates/companion-note.md

@@ -0,0 +1,70 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+type: memory
+status: fresh
+people: []
+context: ""
+created: YYYY-MM-DD
+_schema:
+  entity_type: "companion-note"
+  applies_to: "memories/*.md"
+  required:
+    - description
+    - type
+  optional:
+    - status
+    - created
+    - people
+    - context
+  enums:
+    type:
+      - memory
+      - ritual
+      - milestone
+      - moment
+    status:
+      - fresh
+      - revisited
+      - archived
+  constraints:
+    description_max_chars: 200
+    people_format: "array of names or wiki links"
+    context_format: "free text — where, when, what triggered the memory"
+  notes: >
+    Companion notes capture things worth remembering about life — moments,
+    rituals, milestones, preferences, and observations. They follow the
+    universal prose-as-title pattern but with minimal schema to keep capture
+    friction near zero. The companion domain is the lightest configuration,
+    optimized for memory building without processing overhead.
+
+    The type field distinguishes four kinds of companion content:
+    - memory: a specific thing worth remembering (default)
+    - ritual: recurring events, traditions, practices
+    - milestone: significant life events, achievements, transitions
+    - moment: small observations, fleeting impressions worth preserving
+
+    The status field tracks revisiting:
+    - fresh: just captured, not yet revisited
+    - revisited: looked at again during maintenance and still resonant
+    - archived: no longer active but preserved for history
+
+    The people field is optional — not every memory involves specific people,
+    but when it does, naming them enables person-centric retrieval via
+    entity MOCs in the relationships domain.
+
+    The context field captures environmental or situational details that
+    make the memory vivid — where you were, what prompted it, what was
+    happening around you. This is the companion equivalent of the research
+    domain's source field: provenance for memories.
+---
+
+# prose-as-title expressing the memory as a complete thought
+
+Body with context — what happened, why it matters, what it connects to. Write naturally, as if telling a friend. The memory should stand on its own: specific enough to be useful when recalled later, personal enough to be worth keeping.
+
+Since this is the lightest domain, body text can be brief. A few sentences capturing the essential detail is often enough. The title carries the memory; the body adds color.
+
+---
+
+Topics:
+- [[life-area-moc]]

package/reference/templates/creative-note.md

@@ -0,0 +1,16 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+stage: idea | draft | revision | complete
+medium: writing | visual | music | code
+inspiration: ["[[reference]]"]
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the creative insight or technique
+
+Body developing the idea. What sparked it, how it could work, what it connects to.
+
+---
+
+Topics:
+- [[topic-moc]]

package/reference/templates/learning-note.md

@@ -0,0 +1,16 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+domain: subject area
+mastery: new | developing | solid | expert
+prerequisites: ["[[concept]]"]
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the learning insight
+
+Body developing the insight. What was learned, why it matters, how it connects.
+
+---
+
+Topics:
+- [[topic-moc]]

package/reference/templates/life-note.md

@@ -0,0 +1,16 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+area: health | finance | home | social | career
+priority: low | medium | high | urgent
+deadline: YYYY-MM-DD
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the life management insight or decision
+
+Body with details. What was decided, why, what follows.
+
+---
+
+Topics:
+- [[topic-moc]]

package/reference/templates/moc.md

@@ -0,0 +1,26 @@
+---
+description: Brief description of what this topic covers and why it matters
+type: moc
+created: YYYY-MM-DD
+---
+
+# topic-name
+
+Brief orientation: what this topic covers, where to start.
+
+## Core Ideas
+
+- [[note]] — context explaining why this matters here
+
+## Tensions
+
+Unresolved conflicts within this topic.
+
+## Open Questions
+
+What's unexplored, gaps that need investigation.
+
+---
+
+Topics:
+- [[parent-moc]]

package/reference/templates/relationship-note.md

@@ -0,0 +1,17 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+person: Name
+category: preference | pattern | important-date | interaction | care-task
+last_confirmed: YYYY-MM-DD
+follow_up: true | false
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the relationship insight
+
+Body with details. What was observed, what it means, how to act on it.
+
+---
+
+Topics:
+- [[relationships]]

package/reference/templates/research-note.md

@@ -0,0 +1,19 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+methodology: Zettelkasten | Evergreen | Cornell | Memory Arts | Network Science | Cognitive Science | Original
+source: "[[source-name]]"
+classification: claim | methodology | tension
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the research claim
+
+Body developing the claim with visible reasoning.
+
+---
+
+Relevant Notes:
+- [[related note]] — relationship context
+
+Topics:
+- [[topic-moc]]

package/reference/templates/session-log.md

@@ -0,0 +1,24 @@
+---
+description: Session log for YYYY-MM-DD — what happened, what was learned, what's next
+type: session-log
+created: YYYY-MM-DD
+---
+
+# YYYY-MM-DD session log
+
+## What Happened
+
+Summary of this session's activities.
+
+## Insights Captured
+
+- [[new note created]] — brief context
+- [[another insight]] — brief context
+
+## Open Threads
+
+What's in progress, what needs follow-up.
+
+## Next Session
+
+What to orient on at the start of the next session.

package/reference/templates/therapy-note.md

@@ -0,0 +1,16 @@
+---
+description: One sentence adding context beyond the title (~150 chars)
+category: pattern | trigger | coping-strategy | insight | growth-goal
+confidence: observed | hypothesized | verified
+frequency: once | occasional | regular | constant
+created: YYYY-MM-DD
+---
+
+# prose-as-title expressing the reflection or pattern
+
+Body exploring the pattern. When it happens, what triggers it, what helps.
+
+---
+
+Topics:
+- [[topic-moc]]

package/reference/test-fixtures/edge-case-constraints.md

@@ -0,0 +1,148 @@
+# Test Fixture: Edge Case — Constraint Conflicts
+
+A conversation that intentionally pushes against interaction constraints with conflicting signals. The derivation engine must detect incoherent configurations, warn the user, and guide them toward coherent alternatives. This tests the constraint system's ability to prevent generating systems that will fail in practice.
+
+## Expected Outcome
+
+- **Constraint violations triggered:**
+  1. HARD: atomic granularity + 2-tier navigation + high volume
+  2. SOFT: atomic granularity + light processing
+  3. SOFT: dense schema + convention automation
+  4. SOFT: high volume + no semantic search
+- **Expected behavior:** Agent warns on each violation with explanation, suggests coherent alternatives, does NOT silently generate an incoherent configuration
+- **Final configuration (after corrections):** A coherent system that reflects the user's adjusted preferences
+- **Dimensions (after resolution):** Will depend on which direction the user adjusts — multiple valid outcomes
+- **Vocabulary:** Research-adjacent but custom (user prefers own terminology)
+
+## Conversation
+
+### User Turn 1
+
+I want to build a knowledge system for my legal research. I read about 20 case law opinions per week and I want to break each one down into individual legal principles — one principle per note. I want to keep things simple though, just a flat list with a main index page. No complicated hierarchy.
+
+### Expected Agent Response Pattern 1
+
+The agent should:
+- Extract signals: high volume (20 cases/week), atomic granularity ("one principle per note"), 2-tier navigation ("flat list with main index page")
+- Detect the first constraint conflict: atomic granularity at high volume (20 cases * ~5 principles each = ~100 notes/week = ~5000/year) with only 2-tier navigation
+- This is a HARD constraint: `atomic + navigation_depth == "2-tier" + volume > 100` produces navigational vertigo
+- NOT silently accept the configuration
+- Warn the user clearly: "Breaking each case into individual principles is great for cross-referencing, but at 20 cases per week, you will have thousands of notes within months. A single index page will become unnavigable very quickly. I would recommend at least a 3-tier structure: a main index linking to practice area pages (constitutional law, contracts, torts, etc.), which then link to individual principles."
+- Ask: "Would you be open to having a few practice area pages between the main index and your notes? It will make a big difference as the collection grows."
+
+### User Turn 2
+
+I see what you mean but I really want to keep it simple. I do not want to have to maintain a bunch of topic pages. What if I just use good search instead? I can find what I need by searching.
+
+### Expected Agent Response Pattern 2
+
+The agent should:
+- Acknowledge the user's preference for simplicity
+- Evaluate the compensating mechanism: can search compensate for shallow navigation?
+- The interaction constraint matrix says: "High volume + shallow nav — Strong semantic search enables discovery without deep hierarchy. Moderate effectiveness — works for retrieval, not for orientation."
+- This means search can PARTIALLY compensate but the user will lack orientation (knowing what topics exist, what the landscape looks like)
+- Present the trade-off honestly: "Search can help you find specific principles, but you will lose the ability to see your landscape — which practice areas have lots of coverage, which have gaps, where contradictions exist. Think of it like having a library with no catalog. You can search the stacks, but you cannot see the collection."
+- Suggest a compromise: "What if we start with just 4-5 practice area pages? You do not have to maintain them manually — the system can update them during processing. It is minimal hierarchy with maximum value."
+
+### User Turn 3
+
+OK fine, I will do practice area pages. But I want to keep processing light — I do not want some complicated pipeline. I just want to quickly note down the principle and move on.
+
+### Expected Agent Response Pattern 3
+
+The agent should:
+- Detect the second constraint conflict: atomic granularity + light processing
+- This is a SOFT constraint: "Atomic notes need processing to recreate decomposed context. Light processing may leave notes disconnected."
+- Warn: "When you break a case into individual principles, each note loses the context of the full opinion — which case it came from, how the principles relate to each other, what the court's reasoning was. Without a connect phase (even a quick one), those principles will be isolated fragments that are hard to use later."
+- Present options:
+  1. Keep atomic + add moderate processing: "After noting the principles, take 2 minutes to add links between related principles and file them under practice areas. This is moderate processing, not a full pipeline."
+  2. Switch to moderate granularity: "Instead of one principle per note, write one case note with principles as sections. Less decomposition, less connection needed, faster capture."
+  3. Accept the risk: "Keep atomic + light, but know that you will need to do a maintenance pass later to connect isolated principles."
+- Ask which approach appeals
+
+### User Turn 4
+
+Option 1 — I will do a quick connection pass after noting the principles. But I want really detailed metadata on each note — the case name, court, year, jurisdiction, practice area, whether it has been overturned, the judge, and the strength of the holding. I want to query this like a database.
+
+### Expected Agent Response Pattern 4
+
+The agent should:
+- Detect the third constraint conflict: dense schema + convention automation (the user said no complicated pipeline, implying low automation)
+- This is a SOFT constraint: "Dense schemas without automated validation create maintenance burden. Consider adding validation hooks or reducing schema density."
+- Calculate the burden: 8+ schema fields * 100 notes/week = 800+ field entries per week, all manually validated
+- Warn: "That is a lot of metadata to maintain by hand. With 8 required fields on every note, and 100+ notes per week, you will spend more time filling in metadata than doing legal analysis. Two options:"
+  1. "Reduce to essential fields: case_name, jurisdiction, practice_area, and status (active/overturned). That is 4 fields instead of 8 — the others can be added later if you actually query them."
+  2. "Keep all 8 fields but add automated validation (a hook that checks your metadata is complete after each note). This catches missing fields before they compound."
+- Ask: "Which fields do you actually search by? Start with those."
+
+### User Turn 5
+
+Good point. I mostly search by practice area and jurisdiction. Sometimes by whether it has been overturned. The judge and court are nice-to-have. Let me drop those.
+
+### Expected Agent Response Pattern 5
+
+The agent should:
+- Reduce schema to: case_name (required), jurisdiction (required), practice_area (required), status (required: active/overturned/questioned), year (optional), judge (optional)
+- This resolves the dense schema constraint — moderate schema is coherent with convention automation
+- Check the fourth constraint: high volume + no semantic search
+- The user mentioned "good search" in turn 2 but the configuration does not include semantic search yet
+- Warn (if not yet addressed): "At your volume, keyword search will miss connections between principles that use different legal terminology. 'Strict scrutiny' in one jurisdiction might be described as 'heightened review' in another. Semantic search would catch those. Would you want that?"
+- Present the full resolved configuration with all constraint violations addressed
+
+### User Turn 6
+
+Yes, add semantic search. OK, I think I have been going back and forth. Can you just show me the final configuration with everything resolved?
+
+### Expected Agent Response Pattern 6
+
+The agent should:
+- Present the FINAL resolved configuration, showing how each conflict was resolved:
+  - Granularity: atomic (user's strong preference, validated)
+  - Organization: flat (user's preference, coherent with semantic search)
+  - Linking: explicit+implicit (semantic search added for cross-vocabulary matching)
+  - Processing: moderate (quick connection pass after extraction — resolved from light)
+  - Navigation: 3-tier (hub -> practice area MOCs -> principle notes — resolved from 2-tier)
+  - Maintenance: condition-based with tight thresholds (high volume demands responsive triggers)
+  - Schema: moderate (4 required fields + 2 optional — reduced from 8 required)
+  - Automation: convention, with validation hook recommended as first upgrade
+- Show the constraint resolution log:
+  - "RESOLVED: atomic + 2-tier -> 3-tier (practice area pages added)"
+  - "RESOLVED: atomic + light processing -> moderate processing (quick connection pass)"
+  - "RESOLVED: dense schema + convention -> moderate schema (reduced to essential query fields)"
+  - "RESOLVED: high volume + no semantic search -> semantic search added"
+- Present vocabulary mapping (legal domain)
+- Ask for final confirmation
+
+### User Turn 7
+
+This is much better than what I originally described. Thank you for pushing back. Generate it.
+
+### Expected Agent Response Pattern 7
+
+The agent should:
+- Generate the vault with all resolved configurations
+- In ops/derivation.md, document each constraint conflict and how it was resolved — this is critical for future reseed (the user might drift back toward incoherent configurations, and the derivation rationale explains why the current shape exists)
+- Include in CLAUDE.md's "System Evolution" section: the specific constraint tensions and why the current configuration was chosen
+- Include in Common Pitfalls: the specific failure modes this configuration is vulnerable to (schema erosion at high volume, orphan drift if connection pass is skipped)
+- Run validate-kernel.sh: 15/15 PASS
+- Note that the pushback conversation itself is evidence the constraint system works — it prevented 4 incoherent configurations from being generated
+
+### User Turn 8
+
+Wait actually, one more thing. I do not want to call them "claims" or "notes." In legal research we call them "holdings" or "principles." Can you change the vocabulary?
+
+### Expected Agent Response Pattern 8
+
+The agent should:
+- Apply custom vocabulary transformation:
+  - note -> holding (or principle)
+  - MOC -> practice area guide
+  - inbox -> case queue
+  - extract -> brief (as in "briefing a case")
+  - reflect -> cross-reference
+  - description -> holding summary
+  - topics -> practice areas
+  - archive -> closed cases
+- Regenerate affected files with the new vocabulary (context file, templates, self/identity.md, skill names)
+- Verify zero instances of "claim", "note" (in the knowledge-unit sense), "MOC", "extract" in the regenerated output
+- Update ops/derivation.md with the custom vocabulary mapping

package/reference/test-fixtures/multi-domain.md

@@ -0,0 +1,164 @@
+# Test Fixture: Multi-Domain Composition
+
+Adding a second domain (relationship tracking) to an existing research vault. Tests the composition mechanism: shared graph with separate templates, separate processing intensities, cross-domain linking, and unified navigation. The key validation is that the second domain does not corrupt the first — different processing pipelines, different schemas, different maintenance sensitivities coexist in one graph.
+
+## Expected Outcome
+
+- **Dimensions (Research domain — existing, unchanged):**
+  - Granularity: atomic (0.8)
+  - Processing: heavy (0.8)
+  - Linking: explicit+implicit (0.7)
+  - Navigation: 3-tier
+  - Schema: moderate (research-note template)
+  - Maintenance: condition-based (tight thresholds)
+
+- **Dimensions (Relationships domain — new addition):**
+  - Granularity: moderate (0.5)
+  - Processing: light (0.3)
+  - Linking: explicit (0.3)
+  - Navigation: 2-tier (hub + per-person MOCs)
+  - Schema: moderate (person-note template with emotional_context, follow_up fields)
+  - Maintenance: condition-based (lax thresholds)
+
+- **Composition rules validated:**
+  1. Shared graph (wiki links cross domains)
+  2. Separate templates (research-note.md and person-note.md)
+  3. Separate processing (heavy pipeline for research, light capture for relationships)
+  4. Shared navigation (hub MOC links to both domains)
+  5. Cross-domain links are natural, not forced
+
+- **Features added:** entity MOCs (per-person), relationship-note template
+- **Features preserved:** everything from the existing research vault
+- **Vocabulary:** Research vocabulary preserved for existing domain; relationship vocabulary for new domain (memory, notice, person page, encounters)
+- **Configuration:** unchanged from existing vault
+
+## Conversation
+
+### User Turn 1
+
+I already have a research vault set up with Ars Contexta. Now I also want to track people I work with — collaborators, researchers I follow, people I meet at conferences. I want to remember what they work on, what we have discussed, and follow up on things.
+
+### Expected Agent Response Pattern 1
+
+The agent should:
+- Recognize this as a multi-domain composition request — adding Relationships domain to existing Research domain
+- Identify signals: entity-centric organization (per-person), light processing ("remember" not "analyze"), follow-up tracking
+- Confirm the existing vault: "You already have a research vault — I will add relationship tracking alongside it without changing your existing setup"
+- Ask about scope: "How many people are you tracking — a handful of close collaborators, or dozens of conference contacts?"
+- Ask about cross-domain linking needs: "When you meet a researcher, do you want to link their person page to the research claims they have influenced?"
+
+### User Turn 2
+
+Maybe 15-20 people actively. The cross-domain linking is exactly what I want — like if I read a paper by someone I know, the claim should link to their person page. And if I have a conversation with a collaborator about a topic, I want to see that on their page and in the research notes.
+
+### Expected Agent Response Pattern 2
+
+The agent should:
+- Set volume to moderate (15-20 active people, slow growth)
+- Confirm cross-domain linking is a primary value — this validates flat organization (per-person folders would block cross-domain linking)
+- Derive relationship domain configuration:
+  - Granularity: moderate (per-encounter observations, not atomic decomposition of conversations)
+  - Processing: light (capture + connect, not extraction pipeline)
+  - Navigation: 2-tier (relationships hub -> per-person MOCs)
+  - Schema: moderate (person, relationship_type, last_contact, emotional_context, follow_up)
+  - Maintenance: condition-based with lax thresholds (relationships change slowly)
+- Ask about vocabulary preference: "For relationship notes, would you call them 'observations', 'memories', or something else? And the person pages — 'person page', 'collaborator page', or just their name?"
+
+### User Turn 3
+
+I think just "observations" for the notes and their name for the person page — like "Sarah Chen.md" is her page. I want the follow-up tracking to be important — like if Sarah mentions she is submitting to NeurIPS, I want a reminder to ask how it went next time I see her.
+
+### Expected Agent Response Pattern 3
+
+The agent should:
+- Set vocabulary: observations for notes, names for person MOCs
+- Recognize the follow-up need — this maps to `follow_up` field in schema AND potentially to ops/reminders.md for time-bound follow-ups
+- Distinguish between:
+  - Schema follow-up: `follow_up: true` on an observation (flags it for next interaction)
+  - Timed reminder: ops/reminders.md entry "2026-03-01: Ask Sarah about NeurIPS submission"
+- Present the composition plan:
+  - New template: person-note.md (per-person MOC template) and observation-note.md
+  - New directory: people/ alongside existing notes/ (or within notes/ as MOC files since organization is flat)
+  - Updated hub MOC: index.md gets a "People" section linking to person MOCs
+  - Cross-domain linking convention: research notes can link to person MOCs and vice versa
+  - Processing distinction: research notes go through the full pipeline; observations get light processing (capture + manual connection)
+
+### User Turn 4
+
+What happens when I cite a paper by Sarah? Does the claim automatically link to her person page?
+
+### Expected Agent Response Pattern 4
+
+The agent should:
+- Be honest: automatic cross-domain linking is included as a convention in the processing instructions. The agent checks for person links during the reflect phase, but it is convention-driven, not a dedicated automation hook.
+- Explain the approach: "When you process a paper by Sarah, the reduce skill extracts claims. During the reflect phase, I check if the author has a person page and add a link. This is part of the standard processing flow."
+- Note: "If this convention is insufficient — you are regularly finding missed author links — that is a signal to add a dedicated PostToolUse hook for author matching. The system captures this as friction via /remember."
+
+### User Turn 5
+
+That makes sense. What about when I am at a conference and I meet 5 new people in one day? I need fast capture.
+
+### Expected Agent Response Pattern 5
+
+The agent should:
+- Recognize the fast capture need — this maps to the inbox/encounters zone
+- Suggest a lightweight capture workflow:
+  - Quick note in encounters/ (the relationships inbox) with just name, context, and one key thing
+  - Process into a full person page later (or the next day)
+  - The encounters/ note is the raw material; the person page in people/ is the processed result
+- Emphasize zero-friction capture: "At a conference, speed matters. Drop a note with their name, where you met, and one memorable thing. Process it into a proper page when you have time."
+- This is the temporal separation principle: capture fast, process slow
+
+### User Turn 6
+
+OK, let us add this to my vault. Do not touch my existing research setup — just add the people tracking alongside it.
+
+### Expected Agent Response Pattern 6
+
+The agent should:
+- Generate ONLY the new components (additive, not destructive):
+  - New template: `templates/person-page.md` (entity MOC for people) and `templates/observation.md` (per-observation note)
+  - New directory: `encounters/` (capture zone for quick people notes)
+  - New starter files: a sample person page to show the format
+  - Updated files:
+    - CLAUDE.md: add "People Tracking" section describing the relationship domain, its vocabulary, processing, and cross-domain linking convention
+    - `notes/index.md`: add "People" section with link to starter person page
+    - ops/derivation.md: document the composition — which dimensions apply to which domain
+    - ops/derivation-manifest.md: add `person-page` and `observation` to template list
+- NOT modify:
+  - Existing research templates
+  - Existing research notes
+  - Existing processing pipeline configuration
+  - Existing self/ files (except possibly self/relationships.md if it does not exist)
+- Run validate-kernel.sh on the updated vault: 15/15 PASS (the composition does not break any kernel primitives)
+- Explain the cross-domain workflow:
+  1. Meet someone -> quick note in encounters/
+  2. Process into person page -> create Name.md in notes/ with person-page template
+  3. When processing a paper by that person -> add link from claim to person page during reflect
+  4. When meeting them -> check their person page first for follow-ups
+
+### User Turn 7
+
+Can you show me what Sarah Chen's page would look like with a research link?
+
+### Expected Agent Response Pattern 7
+
+The agent should:
+- Create a sample person page for Sarah Chen with:
+  - YAML: description, relationship_type (collaborator), affiliation, research_areas, last_contact
+  - Sections: About, Research Interests, Observations (with linked observation notes), Follow-ups
+  - Cross-domain link: "Sarah's work on [[interpretability of language models challenges current alignment assumptions]] directly connects to our research on..."
+  - An observation entry: "2026-02-10: Sarah mentioned she is submitting her interpretability framework to NeurIPS. [[follow-up: ask about NeurIPS submission]]"
+- Demonstrate the cross-domain value: the person page is a hub that connects to research claims, and research claims link back to the person who made them
+
+### User Turn 8
+
+Perfect. This is exactly what I needed.
+
+### Expected Agent Response Pattern 8
+
+The agent should:
+- Briefly confirm what was added and what was preserved
+- Remind about the encounter workflow for conference capture
+- Suggest starting with 2-3 people they interact with most frequently to build the habit before a conference
+- NOT over-explain or re-describe the full system