arscontexta 0.6.0

package/reference/semantic-vs-keyword.md

@@ -0,0 +1,288 @@
+# Search Modality Selection Reference
+
+## Purpose
+
+Guide the derivation engine in selecting which search modalities a generated system should support, how they interact, and when each is appropriate. Search is a kernel primitive (semantic-search in kernel.yaml) but implementation varies dramatically by platform, volume, and processing intensity. The wrong search configuration produces either retrieval failures (missing semantic when needed) or wasted complexity (deploying hybrid search for a 30-note vault).
+
+This document answers: given a derived system's configuration (volume, granularity, linking style, platform tier), which search modalities should be enabled, how should they be prioritized, and what fallback chains should be generated?
+
+---
+
+## Derivation Questions
+
+Questions the engine must answer when generating search configuration:
+
+1. **What is the expected note volume trajectory?** Low (<50), moderate (50-200), high (>200). Search modality requirements shift at each threshold.
+2. **Does the linking dimension include implicit connections?** If linking = explicit+implicit, semantic search is structurally required — it IS the implicit linking mechanism.
+3. **What platform tier is available?** Tier-1 (Claude Code with MCP) enables persistent semantic search servers. Tier-2 (CLI tools) enables batch semantic search. Tier-3 (convention only) limits to keyword search plus manual review.
+4. **What is the processing intensity?** Heavy processing generates vocabulary divergence faster (many notes reformulating the same concepts in different words), increasing semantic search value.
+5. **How domain-specific is the vocabulary?** Narrow domains with consistent terminology get less value from semantic search. Broad or cross-domain systems where the same concept appears under different names get maximum value.
+6. **Is duplicate detection a requirement?** If the pipeline includes a reduce phase that extracts claims, semantic duplicate detection prevents the same insight from being captured under different phrasings.
+
+---
+
+## Curated Claims
+
+### Modality Foundations
+
+#### BM25 provides the baseline for all text retrieval
+
+**Summary:** BM25 (Best Matching 25) is a probabilistic ranking function that scores documents by term frequency, inverse document frequency, and document length normalization. It is the standard algorithm behind keyword search. BM25 excels when the searcher knows the exact vocabulary used in the target document — it is fast (sub-second on large corpora), deterministic, requires no model loading or embedding computation, and works on any system with a text index.
+
+**Derivation Implication:** Every generated system gets keyword search as the floor. Even tier-3 convention-only systems can instruct the agent to use ripgrep or grep. Keyword search is the universal fallback that never fails — it requires only filesystem access.
+
+**Source:** Robertson & Zaragoza, "The Probabilistic Relevance Framework: BM25 and Beyond" (2009). Validated operationally in the vault's qmd `search` mode.
+
+---
+
+#### Embedding similarity captures meaning across vocabulary boundaries
+
+**Summary:** Vector embeddings project text into a high-dimensional space where semantic similarity corresponds to geometric proximity. Two notes about "friction in learning systems" and "errors as pedagogical feedback" share no significant keywords but occupy nearby regions in embedding space. This is the core value proposition of semantic search: it finds connections that keyword search structurally cannot, because keyword search requires vocabulary overlap that semantic relatedness does not guarantee.
+
+**Derivation Implication:** Semantic search (vsearch) becomes valuable when vocabulary divergence is expected — which correlates with note volume, processing intensity, and domain breadth. Systems with heavy processing generate more reformulations of the same concepts, increasing the chance that two notes about the same idea use different words.
+
+**Source:** Mikolov et al., "Efficient Estimation of Word Representations in Vector Space" (2013). Operationally confirmed: the vault's qmd vsearch catches duplicates that BM25 misses entirely.
+
+---
+
+#### Query expansion amplifies semantic search by generating alternative phrasings
+
+**Summary:** Query expansion takes the user's original query and generates alternative formulations before searching. "Knowledge management friction" might expand to "obstacles in personal knowledge systems," "note-taking workflow bottlenecks," and "PKM failure patterns." Each expanded query runs against the embedding index, and results are merged. This compensates for the single-query blind spot where the searcher's phrasing might not match the embedding space's optimal representation of the concept.
+
+**Derivation Implication:** Query expansion is a feature of hybrid search mode (the qmd `query` tool). It adds latency (~5-15 seconds) but significantly improves recall for exploratory searches. Generated systems should use expansion for connection-finding and deep exploration, not for quick lookups.
+
+**Source:** Operational experience with qmd's expansion pipeline. Grounded in Rocchio relevance feedback (1971) adapted for neural retrieval.
+
+---
+
+#### LLM reranking evaluates genuine conceptual connection beyond surface similarity
+
+**Summary:** After BM25 and vector search produce candidate results, an LLM evaluates each candidate against the original query for genuine conceptual relevance. This is the most expensive step but also the most valuable for connection-finding. Vector similarity can be fooled by topical overlap — two notes about "context windows" might score high even if one is about UI design and the other about LLM architecture. The LLM reranker distinguishes surface overlap from deep connection by reasoning about the semantic relationship.
+
+**Derivation Implication:** LLM reranking is the highest-quality search mode and should be reserved for tasks where connection quality matters most: reflect (finding connections for new notes), reweave (updating old notes), and exploratory research. It should NOT be the default for routine lookups.
+
+**Source:** Nogueira & Cho, "Passage Re-ranking with BERT" (2019). Operationally validated in the vault's qmd `query` mode, which uses LLM reranking as the final stage.
+
+---
+
+### Task-to-Modality Mapping
+
+#### Finding known notes requires keyword search, not semantic search
+
+**Summary:** When the agent knows what it is looking for — a specific filename, a known term, a particular YAML field value — keyword search is strictly superior. It is faster (0.2s vs 5-20s), deterministic (same query always returns same results), and more precise (no false positives from embedding noise). Semantic search adds latency and potential noise when the target is lexically identifiable.
+
+**Derivation Implication:** Generated context files should instruct agents to use keyword search (grep/ripgrep) for: checking if a filename exists, querying YAML fields (`rg '^type: tension'`), finding exact phrases, and looking up known note titles. The search modality instruction should be task-specific, not "always use the best search."
+
+**Source:** Operational pattern in the vault: `/seed` uses keyword search to check if a source was already processed. No semantic search needed — filenames are exact-match targets.
+
+---
+
+#### Exploring concepts requires semantic search to cross vocabulary boundaries
+
+**Summary:** When the agent is exploring a concept without knowing which notes are relevant, semantic search finds candidates that keyword search misses. Searching for "how agents maintain identity across sessions" might surface notes titled "session handoff creates continuity without persistent memory" and "closure rituals create clean breaks" — neither of which contains the words "identity" or "maintain" but both are deeply relevant. This is the canonical use case for embedding-based retrieval.
+
+**Derivation Implication:** Generated systems should route conceptual exploration to semantic search (vsearch). This applies to: the reflect phase (finding connections for a new note), pre-creation duplicate detection (does this claim already exist under different words?), and ad-hoc research queries. The context file should teach the agent when to switch from keyword to semantic.
+
+**Source:** Vault operational experience. The claim "vector proximity measures surface overlap not deep connection" documents both the value and limitations of this modality.
+
+---
+
+#### Connection finding requires hybrid search with LLM reranking
+
+**Summary:** Finding genuine connections between notes is the highest-value search task in a knowledge system. It requires the full pipeline: BM25 for exact-term matches, vector search for vocabulary-divergent matches, query expansion for coverage, and LLM reranking to evaluate which candidates represent genuine conceptual connections rather than surface similarity. Each layer catches what the previous one misses. Skipping the reranking step produces connection suggestions that are topically related but not genuinely connected — the difference between "both mention context windows" and "this note's argument depends on that note's claim."
+
+**Derivation Implication:** Generated systems with processing = heavy or moderate should include a hybrid search mode for the reflect and reweave phases. Systems with processing = light can skip hybrid search because they generate fewer notes and the agent can use MOC traversal + keyword search for the limited connection-finding needed.
+
+**Source:** Vault operational experience. The reflect skill uses `mcp__qmd__query` (hybrid) because connection quality justifies the ~20s latency.
+
+---
+
+#### Duplicate detection requires semantic search because duplicates use different words
+
+**Summary:** The most dangerous duplicates are semantic duplicates: notes that make the same claim in different vocabulary. "Curation becomes the work when creation is easy" and "AI makes creation cheap so filtering becomes expensive" are semantic duplicates — same insight, different framing. BM25 will not catch this because the notes share almost no significant terms. Only vector embedding similarity reliably detects semantic duplicates, because the notes occupy nearby regions in embedding space despite lexical divergence.
+
+**Derivation Implication:** Any generated system with a processing pipeline (reduce phase) should include semantic duplicate detection. The reduce skill should check each extracted claim against the existing note corpus via semantic search before creating a new note. This is a quality gate, not an optional convenience.
+
+**Source:** Vault operational experience. The reduce skill uses `mcp__qmd__vsearch` for duplicate detection, and regularly catches duplicates that would be invisible to keyword search.
+
+---
+
+#### Description quality testing requires semantic search without reranking
+
+**Summary:** Testing whether a note's description enables retrieval means searching for the note using only its description, without the title. If semantic search (without LLM reranking) finds the note from its description alone, the description is doing its job as a retrieval filter. If it fails, the description needs improvement. Using reranking would hide bad descriptions behind the LLM's ability to infer relevance — the test must use raw vector similarity to expose weak descriptions.
+
+**Derivation Implication:** Generated systems with a verify or recite phase should use semantic search (vsearch, not query) for description quality testing. The absence of reranking is intentional — it tests what agents will actually encounter during routine search.
+
+**Source:** Vault operational experience. The recite and verify skills use `mcp__qmd__vsearch` to test description findability, specifically avoiding the query tool's reranking.
+
+---
+
+### Implementation Guidance
+
+#### Minimum viable search is keyword-only with MOC traversal
+
+**Summary:** A knowledge system with only keyword search (grep/ripgrep) and MOC navigation is fully functional. MOCs provide structural navigation — following curated links from topic hubs to relevant notes. Keyword search provides precision retrieval for known terms. Together they cover the majority of retrieval needs. Semantic search adds value at scale and for cross-vocabulary discovery, but its absence does not make a system non-functional.
+
+**Derivation Implication:** Tier-3 (convention-only) systems generate with keyword search instructions and MOC-based navigation only. No semantic search infrastructure. The context file should still describe the concept of semantic search as a future upgrade path, so the agent understands what it is missing and can recommend adding it when friction emerges.
+
+**Source:** Gall's Law: "A complex system that works is invariably found to have evolved from a simple system that worked." The vault itself operated on keyword + MOC navigation before qmd was added.
+
+---
+
+#### Semantic search requires embedding infrastructure with maintenance
+
+**Summary:** Deploying semantic search means running an embedding model, maintaining a vector index, and keeping that index synchronized with the filesystem. Embeddings go stale when notes are created, modified, or deleted without re-indexing. A stale index is worse than no index — it gives the agent false confidence that search is comprehensive when recent content is invisible. Any generated system with semantic search must include index maintenance procedures.
+
+**Derivation Implication:** When generating semantic search configuration, always include: (1) the embedding tool or service, (2) index update commands, (3) a freshness check protocol (compare indexed document count against actual file count), and (4) instructions for what to do when the index is stale. The vault's Phase 0 freshness check pattern should be adapted for the generated system.
+
+**Source:** Vault operational experience. The Phase 0 freshness check was added after search results missed recently created notes, causing reflect to miss connections.
+
+---
+
+#### Fallback chains prevent search failures from blocking work
+
+**Summary:** Search infrastructure can fail: MCP servers crash, embedding models fail to load, vector indices become corrupt. A system that depends entirely on semantic search for connection-finding will be blocked when semantic search fails. Dual discovery paths — semantic search plus structural navigation (MOC traversal + keyword search) — ensure that work continues regardless of search infrastructure state. The fallback is not a degraded mode; it is a parallel path that is always available.
+
+**Derivation Implication:** Every generated system must include a fallback chain in its context file. The pattern: try semantic search first, fall back to keyword search + MOC traversal if semantic fails. Never let search failure block work. For tier-1 systems: MCP tool -> CLI tool with locking -> keyword + MOC. For tier-2: CLI tool -> keyword + MOC. For tier-3: keyword + MOC is the only path (no fallback needed because it is the primary).
+
+**Source:** Vault operational experience. The three-tier fallback pattern (MCP -> bash with lock -> grep) was developed after MCP server crashes blocked pipeline processing.
+
+---
+
+### Platform Adaptation
+
+#### Claude Code enables persistent semantic search via MCP servers
+
+**Summary:** Claude Code's MCP (Model Context Protocol) integration allows semantic search to run as a persistent server process. The qmd MCP server keeps embedding models loaded in memory between requests, eliminating the 5-10 second cold-start penalty of spawning a new process per query. This makes semantic search practical for interactive use and for pipeline phases that issue multiple queries. The MCP server also solves the parallel worker problem: a singleton LlamaCpp instance with reference-counted sessions prevents multiple workers from loading duplicate models into RAM.
+
+**Derivation Implication:** For Claude Code (tier-1) systems, generate MCP configuration (`.mcp.json`) that points to the semantic search server. Include collection definitions matching the system's folder structure. Document the MCP tool names in the context file so the agent knows which tools to call. Note the MCP-in-subagents limitation: custom agents spawned via Task tool do not inherit MCP access, requiring the CLI fallback.
+
+**Source:** Vault operational experience with qmd MCP server. The `.mcp.json` configuration and collection definitions are proven patterns.
+
+---
+
+#### Convention-only systems compensate with structured manual review
+
+**Summary:** Systems without any search tooling (tier-3) rely entirely on the agent's ability to navigate the graph through MOCs and keyword search. This works at low-to-moderate volume because the agent can hold the full structure in context. At higher volumes, the context file should instruct the agent to periodically review topic adjacencies manually — reading MOCs in related topics and scanning for connections that keyword search would miss. This is the human-era equivalent of "browse your notes" but systematized as a periodic maintenance task.
+
+**Derivation Implication:** For convention-only systems, generate a "Discovery Patterns" section in the context file that teaches manual cross-topic review. Include the topic adjacency pattern: after creating a note in topic A, scan the MOCs of adjacent topics (B, C) for potential connections. This compensates partially for the absence of semantic search.
+
+**Source:** Pre-computational knowledge management practice (Luhmann's physical Zettelkasten relied on sequential browsing and register-based lookup, not search).
+
+---
+
+#### OpenClaw systems use skill-based search invocation
+
+**Summary:** OpenClaw's skill system provides a different integration point for semantic search than Claude Code's MCP. Search can be wrapped in external skills that the agent invokes by name. The skill handles model loading, query execution, and result formatting. This is functionally equivalent to MCP tools but uses OpenClaw's skill invocation infrastructure instead of MCP's tool protocol.
+
+**Derivation Implication:** For OpenClaw systems, generate search skills (e.g., `skills/qmd/`) rather than MCP configuration. The skill should expose the same three modalities (keyword, semantic, hybrid) with the same task-to-modality mapping. The context file references skill names instead of MCP tool names.
+
+**Source:** Vault dual-operator architecture. Cornelius (OpenClaw) uses skills/qmd/ while Heinrich (Claude Code) uses MCP tools. Same search modalities, different invocation paths.
+
+---
+
+### Search Quality and Failure Modes
+
+#### Vector proximity measures surface overlap, not deep connection
+
+**Summary:** Embedding similarity has a fundamental limitation: it measures vocabulary and topic similarity, not genuine conceptual connection. Two notes about "context windows" — one about LLM architecture, one about UI design — may score high vector similarity because they share vocabulary, but they are not meaningfully connected. Conversely, a note about "friction in learning" and a note about "errors as pedagogical feedback" are deeply connected but may score low because they share few terms. This is why LLM reranking exists: to evaluate what vector similarity cannot — whether the conceptual relationship is genuine.
+
+**Derivation Implication:** Generated context files should include a search quality warning: "High similarity scores do not guarantee genuine connections. When using semantic search results, evaluate each candidate: does this note's argument actually relate to what you are searching for, or does it just use similar vocabulary?" This is especially important for the reflect phase where false connections degrade graph quality.
+
+**Source:** Research claim: "vector proximity measures surface overlap not deep connection." Vault operational experience: reflect phases using vsearch without reranking occasionally propose surface-similar but conceptually unrelated connections.
+
+---
+
+#### Stale indices produce false confidence that is worse than no index
+
+**Summary:** When the semantic search index falls out of sync with the filesystem — notes created after the last index update, notes modified without re-embedding, notes deleted but still in the index — the agent receives search results that omit recent content. The danger is not the missing results themselves but the agent's trust in search comprehensiveness. An agent that believes "I searched and found nothing similar" when the search actually missed 10 recently created notes will create a duplicate without realizing it. No index is honest; a stale index lies.
+
+**Derivation Implication:** Every generated system with semantic search must include an index staleness detection mechanism. The minimum viable implementation: compare the count of indexed documents against the count of actual files. If they differ, run index update before trusting search results. The context file should frame this as a mandatory pre-search step, not an optional maintenance task. The vault's Phase 0 freshness check is the reference pattern.
+
+**Source:** Vault operational failure. Notes created during a processing batch were invisible to reflect phases that ran before index sync, producing duplicate notes and missing connections.
+
+---
+
+#### BM25 query dilution occurs when full descriptions are used as search queries
+
+**Summary:** BM25 scores documents by term frequency and inverse document frequency. When the search query itself is long (e.g., a full 150-character description), the query contains many terms, each with low individual weight. This dilution effect means that long queries return fewer and lower-quality BM25 results compared to short, focused keyword queries. The solution is to use condensed keywords or phrases for BM25 search, reserving full-text descriptions for semantic search where the embedding model handles longer inputs gracefully.
+
+**Derivation Implication:** Generated context files that instruct agents on search usage should distinguish between query formulation for keyword search (short, focused terms) and query formulation for semantic search (natural language descriptions). A single instruction like "search for your concept" is insufficient — the agent needs to know how to phrase queries differently for each modality.
+
+**Source:** Vault operational experience. Full-length descriptions used as BM25 queries via `mcp__qmd__search` frequently returned zero results, while the same descriptions used via `mcp__qmd__vsearch` returned accurate matches.
+
+---
+
+### Search Mode Selection Matrix
+
+#### Volume determines the minimum viable search configuration
+
+**Summary:** The relationship between note volume and search modality requirements follows clear thresholds. Below 50 notes, the agent can read all descriptions and navigate the full MOC structure — keyword search suffices. Between 50-200 notes, vocabulary divergence begins to create blind spots that semantic search addresses. Above 200 notes, keyword search alone produces retrieval failures for cross-vocabulary concepts. These thresholds are approximate but directionally reliable across domains.
+
+**Derivation Implication:** The derivation engine should use expected volume trajectory (not current volume) to configure search. A system starting at 10 notes but expected to reach 200+ should be configured for semantic search from the start, with the understanding that it provides little value initially but prevents a painful mid-life reconfiguration.
+
+**Source:** Vault experience and information retrieval theory. Vocabulary divergence grows logarithmically with corpus size (Heaps' Law), creating an increasing gap between what keyword search finds and what exists.
+
+---
+
+#### Domain breadth determines how quickly vocabulary diverges
+
+**Summary:** A narrow-domain system (e.g., tracking one sport's strategy) uses consistent terminology. "Opening move," "midgame position," and "endgame technique" are standard vocabulary that all notes share. Keyword search works well because the vocabulary is constrained. A broad or cross-domain system (e.g., tools for thought research that draws from cognitive science, information retrieval, software engineering, and philosophy) accumulates vocabulary divergence rapidly because each source domain brings its own terminology for overlapping concepts. "Context window" (LLM architecture), "working memory" (cognitive science), and "attention budget" (productivity) all describe related limitations but use completely different terms.
+
+**Derivation Implication:** Cross-domain systems should receive semantic search earlier in their lifecycle than single-domain systems. The derivation engine should ask about domain breadth during init and adjust search modality recommendations accordingly. A system spanning 3+ source domains should probably start with semantic search enabled regardless of initial volume.
+
+**Source:** Information retrieval research on vocabulary mismatch in cross-domain corpora. Vault operational experience: the vault draws from 6+ source domains and experienced vocabulary divergence from the first 30 notes.
+
+---
+
+#### Processing intensity amplifies vocabulary divergence
+
+**Summary:** Heavy processing (extraction, reformulation, synthesis) generates more varied phrasings of the same concepts than light processing. Each reduce pass produces notes that reformulate source material in the agent's own words. Each reweave pass may further rephrase claims as understanding deepens. This compounding reformulation means heavy-processing systems accumulate vocabulary divergence faster than light-processing systems at the same note count, increasing the value of semantic search earlier in the system's lifecycle.
+
+**Derivation Implication:** Adjust the volume thresholds for search modality based on processing intensity. Heavy processing: semantic search becomes valuable at ~30 notes. Moderate processing: ~75 notes. Light processing: ~150 notes. These adjusted thresholds reflect how quickly vocabulary divergence accumulates.
+
+**Source:** Vault operational observation. After heavy /reduce processing of 5 sources, the vault had significant vocabulary divergence across ~80 notes — concepts expressed in source-author vocabulary, vault-native vocabulary, and synthesized vocabulary.
+
+---
+
+### Modality Cost-Benefit Analysis
+
+#### The cost structure of search modalities follows an exponential curve
+
+**Summary:** Keyword search costs O(n) where n is corpus size — essentially free on modern hardware. Semantic search (vector similarity) costs O(1) per query against a pre-built index, but building and maintaining the index costs O(n) per update and requires ~2GB of model memory. Hybrid search with LLM reranking adds O(k) where k is the number of candidates reranked — each candidate requires an LLM inference pass. The practical costs: keyword ~0.2s, semantic ~5s, hybrid ~20s. The quality improvement at each step is diminishing: keyword to semantic is a large jump, semantic to hybrid is a smaller jump, but hybrid catches connections that semantic alone misses in ~15% of cases.
+
+**Derivation Implication:** The cost-quality tradeoff informs which search mode to default to. For routine operations (file lookup, YAML queries), keyword is the only rational choice. For standard discovery (exploring related notes), semantic provides the best cost-quality ratio. For high-stakes connection finding (reflect, reweave), hybrid is justified by the quality premium. Generated context files should encode this cost awareness so agents do not default to the most expensive mode for routine tasks.
+
+**Source:** Vault operational measurements. The 0.2s / 5s / 20s benchmarks are from qmd running on Apple Silicon with models kept warm.
+
+---
+
+#### Search configuration should be generated as a decision table, not a default
+
+**Summary:** Rather than setting a single default search mode, the generated context file should include a decision table mapping tasks to modalities. The agent should know: "For this task, use this search mode, because X." This is more effective than a global default because different tasks within the same session require different modalities. A single session might use keyword search for YAML queries, semantic search for duplicate checking, and hybrid search for connection finding — three modalities in one session, each justified by the task at hand.
+
+**Derivation Implication:** Generate a task-to-modality mapping table in every context file that includes search instructions. The table should list the system's operational tasks (the ones defined by its processing pipeline and maintenance routine) and the appropriate search modality for each. This is the search equivalent of the pre-task context router — it routes tasks to appropriate search modes.
+
+**Source:** Vault CLAUDE.md "Which mode for which skill" table. This task-specific routing replaced an earlier pattern where agents defaulted to hybrid search for everything, wasting 20 seconds on lookups that keyword search handles in 0.2 seconds.
+
+---
+
+## Exclusion Notes
+
+**Excluded from this reference:**
+
+- Full-text search engine comparisons (Elasticsearch, Solr, Meilisearch) — these are infrastructure choices, not derivation decisions. The derivation engine selects modalities, not implementations.
+- Embedding model selection (which model to use for vectors) — implementation detail that belongs in platform-specific documentation, not derivation reference.
+- RAG (Retrieval Augmented Generation) pipeline architecture — the vault's wiki-link graph is explicitly NOT a RAG system. Wiki links provide curated edges; RAG provides automated chunk retrieval. Different paradigms.
+- Image or multimodal search — the vault is text-only. Multimodal search is a future consideration, not a current derivation concern.
+- Real-time indexing vs batch indexing trade-offs — operational concern for the search tool maintainer, not a derivation decision.
+
+---
+
+## Version
+
+- Last curated: 2026-02-12
+- Sources reviewed: 22
+- Claims included: 23
+- Claims excluded: 5
+- Cross-references: `kernel.yaml` (semantic-search primitive), `interaction-constraints.md` (volume cascade, linking dimension), `components.md` (Search component blueprint), `methodology.md` (key research claims on retrieval), `claim-map.md` (discovery-retrieval topic)

package/reference/session-lifecycle.md

@@ -0,0 +1,298 @@
+# Session Lifecycle Reference
+
+## Purpose
+
+Specify how generated systems structure agent sessions for optimal knowledge work. Every session has a beginning (orient), a middle (work), and an end (persist). This three-phase pattern is a kernel primitive (session-rhythm in kernel.yaml), but the specific behaviors in each phase vary by session type, platform capabilities, and domain. The derivation engine uses this document to generate session instructions that are concrete enough to follow and flexible enough to adapt.
+
+This document answers: what should the agent read at session start, how should it manage focus during work, and what must it persist before session end — and how do these answers change across session types and platforms?
+
+---
+
+## Derivation Questions
+
+Questions the engine must answer when generating session configuration:
+
+1. **What platform capabilities exist for session automation?** Hooks (Claude Code) can automate orientation and persistence. OpenClaw requires manual loading of MEMORY.md. Convention-only systems rely on context file instructions.
+2. **What is the self/ space structure?** Session orientation reads self/ — the derivation must know which files exist to generate the orientation sequence.
+3. **What session types will this system support?** Processing sessions (pipeline work), maintenance sessions (health checks), exploration sessions (research and connection finding), capture sessions (rapid note creation). Different types orient and persist differently.
+4. **What is the expected session frequency?** Frequent sessions need different handoff than infrequent sessions. Systems used rarely need heavier orientation because more has been forgotten.
+5. **How large is the context window budget?** Orientation competes with work for context space. Generated systems should specify how much context to allocate to orientation vs task execution.
+6. **Does the system have a processing pipeline?** Pipeline sessions have different rhythm than ad-hoc sessions — they read queue state at orient, process tasks during work, and update queue state at persist.
+
+---
+
+## Curated Claims
+
+### Three-Phase Pattern
+
+#### Orient-work-persist is the universal session rhythm because agents lose everything between sessions
+
+**Summary:** LLM agents have no persistent memory. Every session begins from zero knowledge of identity, goals, recent work, and system state. Without an explicit orientation phase, the agent must rediscover who it is, what it is working on, and what exists in the vault — consuming context window and making mistakes along the way. The orient-work-persist pattern solves this by externalizing session state: orient reads the previous session's output, work produces value, persist writes the next session's input. This cycle creates continuity without requiring persistent memory.
+
+**Derivation Implication:** Every generated context file must include an explicit session rhythm section documenting what to read at start, how to work, and what to save at end. This is not optional guidance — it is the mechanism by which the system maintains coherence across sessions.
+
+**Source:** Kernel primitive `session-rhythm`. Research claim: "session handoff creates continuity without persistent memory." Operationally validated across hundreds of vault sessions.
+
+---
+
+#### Orientation loads identity before task context because identity constrains behavior
+
+**Summary:** The agent must know who it is before it knows what to do. Identity (self/identity.md) establishes voice, values, and approach. Methodology (self/methodology.md) establishes quality standards and operational patterns. Goals (self/goals.md) establishes current work threads and priorities. Loading task context before identity produces an agent that knows what to work on but not how to work on it — and "how" includes quality standards, voice consistency, and behavioral constraints that shape every action. The loading order matters: identity -> methodology -> goals -> task context.
+
+**Derivation Implication:** The generated context file's session start section must specify loading order, not just loading list. For systems with hooks: the session-start hook loads self/ files in identity-first order. For convention systems: the context file instructs the agent to read self/ files in the correct sequence before proceeding to any task.
+
+**Source:** Vault operational experience. Voice drift and quality inconsistency were traced to sessions where task context was loaded before identity context.
+
+---
+
+#### The smart zone is the first 40% of context where attention quality is highest
+
+**Summary:** LLM attention quality degrades as the context window fills. Empirically, the first ~40% of context capacity produces the sharpest reasoning, the most careful instruction-following, and the best quality output. Beyond this threshold, attention degradation manifests as missed instructions, shallower reasoning, and reduced connection-finding ability. This is not a hard cliff but a gradient — quality degrades progressively, with noticeable impact after 40% and severe impact after 70%.
+
+**Derivation Implication:** The derivation engine should calculate approximate context budgets for orient vs work phases. If orientation consumes 25% of context, the work phase has ~15% of smart-zone capacity remaining. Systems with large self/ spaces or heavy orientation requirements should either (a) limit orientation to essential files or (b) use progressive disclosure (read descriptions before full files) to stay within budget. The context file should explicitly warn agents about context budget management.
+
+**Source:** Research claim: "LLM attention degrades as context fills." Operationally validated: late-context processing phases produce measurably lower quality output in the vault's pipeline.
+
+---
+
+### Session Types
+
+#### Processing sessions orient from queue state and persist phase completion
+
+**Summary:** Processing sessions follow the pipeline: read queue.json to find the next unblocked task, execute one or more phases (reduce, reflect, reweave, verify), and update queue state with completion. Orientation is minimal and targeted — the agent needs queue state, the specific task file, and the relevant skill instructions. It does NOT need full self/ orientation because processing is methodological, not identity-dependent. The persist phase must advance the queue entry (mark phases complete, update status) — without this, the pipeline stalls.
+
+**Derivation Implication:** Generated systems with processing pipelines should include a processing session template in the context file. This template specifies: (1) read queue state, (2) identify next task, (3) load task-specific context, (4) execute phase, (5) update task file, (6) advance queue. Skip heavy orientation — processing sessions are mechanical, not exploratory.
+
+**Source:** Vault /ralph orchestration pattern. Each subagent spawned by /ralph follows this minimal-orientation processing session pattern.
+
+---
+
+#### Maintenance sessions orient from health metrics and persist improvement actions
+
+**Summary:** Maintenance sessions focus on system health: schema validation, orphan detection, link health, MOC coverage, stale note identification. Orientation loads the latest health report (if one exists) and the maintenance checklist from the context file. Work runs health checks systematically — not ad-hoc inspection but scripted validation. Persistence captures findings as observation notes, updates health reports, and creates tasks for issues that require separate sessions to fix.
+
+**Derivation Implication:** Generated systems should include a maintenance session section in the context file with: which health checks to run, expected thresholds (orphan percentage, schema compliance), and where to log findings. The maintenance session type should be distinct from processing and exploration — mixing maintenance with content work produces incomplete maintenance because content work is more engaging.
+
+**Source:** Vault /review skill and reconciliation pattern. Maintenance is most effective when it is the sole focus of a session, not a side activity.
+
+---
+
+#### Exploration sessions orient from MOCs and persist connection discoveries
+
+**Summary:** Exploration sessions are open-ended: the agent is looking for connections, investigating a concept, or building understanding of a new topic area. Orientation reads the relevant MOC(s) to understand current thinking, tensions, and gaps. Work follows connections through the graph — reading notes, following wiki links, using semantic search for cross-vocabulary discovery. Persistence captures new connections as inline links in existing notes, updates MOCs with new entries, and logs any observations or tensions discovered. Exploration sessions are the highest-value session type for knowledge compounding but also the most context-hungry.
+
+**Derivation Implication:** Generated systems should include exploration session guidance that teaches: (1) start from a MOC, not from a random note, (2) follow links deliberately — checkpoint after each note to reassess direction, (3) persist discoveries immediately rather than batching them, (4) time-box exploration to prevent context exhaustion without persisting findings.
+
+**Source:** Vault working technique: "checkpoint during traversal." Exploration without checkpointing follows the original query even when the agent has learned something that reframes the question.
+
+---
+
+#### Capture sessions orient minimally and persist raw material for future processing
+
+**Summary:** Capture sessions prioritize speed over structure. The agent receives raw material (voice transcript, article, URL, idea) and files it with minimal ceremony. Orientation is minimal — just enough to know where to put things (inbox structure, naming conventions). Work is filing, tagging, and basic triage (is this relevant? which topic area?). Persistence is the filed material itself, possibly with a queue entry if the material should be processed in a future session. Capture sessions should never attempt processing — that is a different session type.
+
+**Derivation Implication:** Generated systems should explicitly separate capture from processing in their session guidance. The context file should include a "Quick Capture" section that teaches zero-friction filing: drop it in inbox with a descriptive filename and minimal metadata. Processing happens later in a dedicated processing session with fresh context.
+
+**Source:** Research claim: "temporal separation of capture and processing preserves context freshness." Vault pattern: 00_inbox/ as zero-friction capture zone.
+
+---
+
+### Context Budget
+
+#### Context budget allocation should match session type
+
+**Summary:** Different session types have different context budgets. Processing sessions need minimal orientation context (~10%) and maximum work context (~90%). Exploration sessions need moderate orientation context (~25% for MOC loading) and moderate work context (~75% for traversal). Maintenance sessions need moderate orientation context (~20% for health baselines) and moderate work context (~80% for running checks). Capture sessions need minimal context overall — they are short-lived. Misallocating context budget (heavy orientation in a capture session, minimal orientation in an exploration session) degrades session quality.
+
+**Derivation Implication:** Generated context files should include session-type-specific context loading guidance. Rather than a single "orient" section, provide type-specific orientation checklists with approximate context costs. This helps agents make informed decisions about how much to load.
+
+**Source:** Vault operational experience. Pipeline phases running inside /ralph subagents use minimal orientation (task file + skill instructions) to maximize smart-zone availability for the actual work.
+
+---
+
+#### Progressive disclosure during orientation prevents context waste
+
+**Summary:** Not every self/ file needs to be loaded fully at session start. Progressive disclosure applies to orientation: load identity.md fully (it is small and essential), load goals.md fully (it is the active orientation file), but load methodology.md only when the session involves quality decisions. For large self/ spaces with memory/ directories, load the memory directory listing first, then read specific memories only when relevant to the current task. This preserves context budget for work without sacrificing orientation quality.
+
+**Derivation Implication:** Generated systems with self/ spaces larger than ~2000 tokens total should include progressive disclosure guidance for orientation. The context file should distinguish between "always load" files (identity.md, goals.md) and "load when relevant" files (memory/, relationships.md). Hooks can automate the "always load" files while leaving "load when relevant" files to agent judgment.
+
+**Source:** Vault discovery layer pattern. The vault applies progressive disclosure to note discovery (description before content); the same principle applies to self/ orientation.
+
+---
+
+### Session Boundaries as Automation Checkpoints
+
+#### Session boundaries create natural points for automated behavior
+
+**Summary:** The beginning and end of a session are the two moments where automated behavior adds the most value. At session start: load orientation files, inject file tree, evaluate condition-based triggers against vault state, display health warnings. At session end: save session transcript to ops/sessions/ (Primitive 15 — session capture), auto-create mining tasks for future processing, validate that notes were saved, check for broken links introduced during the session, auto-commit changes, push to remote. These are deterministic operations (verification, not judgment) that hooks can handle without corrupting quality.
+
+**Derivation Implication:** For hook-capable platforms (Claude Code), generate session-start and stop hooks that automate the deterministic parts of orient and persist. The stop hook MUST save session transcripts (session capture is INVARIANT). For convention-only systems, generate checklist instructions that the agent follows manually. The checklist should cover the same behaviors as the hooks, just without automation. The context file should explain what the hooks do so the agent understands the automated behavior.
+
+**Source:** Vault hook infrastructure. The session-start hook (tree injection + condition evaluation) and stop hook (session capture + auto-commit) are proven patterns that eliminate routine tasks without requiring judgment.
+
+---
+
+#### Attention residue from incomplete sessions degrades future work
+
+**Summary:** When a session ends without proper persistence, the agent in the next session lacks information about what was in progress, what was discovered, and what decisions were made. This is the agent equivalent of attention residue — incomplete tasks from a previous context contaminating the current context. The persist phase eliminates attention residue by explicitly capturing session state: what was done, what was discovered, what remains to do. Cal Newport's research on attention residue for humans translates directly: incomplete work contaminates future attention, and explicit closure rituals are the remedy.
+
+**Derivation Implication:** Generated context files must include an explicit session-end checklist. Minimum: update self/goals.md with current state, capture any observations, push changes to remote. For pipeline sessions: update queue state. For exploration sessions: update MOCs with discoveries. The checklist should be positioned prominently (not buried in appendix) because skipping it is the most common session failure mode.
+
+**Source:** Newport, "Deep Work" (2016) — attention residue concept. Research claim: "closure rituals create clean breaks that prevent attention residue bleed." Vault operational experience with goals.md as the primary session-handoff mechanism.
+
+---
+
+#### The Zeigarnik effect means open tasks persist in working memory until closed
+
+**Summary:** Bluma Zeigarnik demonstrated that uncompleted tasks are remembered better than completed ones — the mind maintains a "rehearsal loop" for unfinished work. For agents, this translates to the self/goals.md pattern: open threads listed in goals.md are the agent's externalized Zeigarnik effect. They persist across sessions because they are written down, and they create a pull toward completion that prevents aimless sessions. Without goals.md, each session starts without momentum — the agent has no open threads pulling it toward specific work.
+
+**Derivation Implication:** Every generated system must include a goals.md (or domain-equivalent) file in self/ that tracks open threads. The context file should instruct the agent to read goals.md at session start and update it at session end. The format should be simple: a list of active threads with current status, not a complex project management system. The Zeigarnik effect works best with concise, emotionally engaging descriptions of unfinished work.
+
+**Source:** Zeigarnik, "On Finished and Unfinished Tasks" (1927). Vault self/goals.md as operational implementation.
+
+---
+
+### Platform Adaptation
+
+#### Claude Code automates session rhythm through hooks
+
+**Summary:** Claude Code's hook system (PreToolUse, PostToolUse, Stop events) enables automatic session rhythm. A SessionStart hook injects the file tree and loads orientation files. A PostToolUse hook on Write operations validates note quality. A Stop hook (or pre-push hook) can remind the agent to update goals.md. This automation makes the session rhythm invisible — the agent follows it without conscious effort because the infrastructure enforces it. The hooks encode deterministic verification (does the file exist? is the schema valid?) while leaving judgment operations (is the description good? are the connections meaningful?) to skills.
+
+**Derivation Implication:** For Claude Code systems, generate hook configurations in `.claude/hooks/` that automate: (1) tree injection at session start, (2) self/ file loading at session start, (3) note validation on Write, (4) session-end reminders. The context file should document what hooks exist and what they do, so the agent understands the automated behavior and doesn't duplicate it.
+
+**Source:** Vault `.claude/hooks/` implementation. Proven hook patterns: session-start tree injection, PostToolUse validation, auto-commit.
+
+---
+
+#### OpenClaw requires manual orientation with MEMORY.md as anchor
+
+**Summary:** OpenClaw's session model loads SOUL.md, USER.md, and AGENTS.md automatically, but vault-specific orientation (the equivalent of self/ loading and tree injection) must be triggered manually. MEMORY.md serves as the orientation anchor — it points the agent to self/ files and instructs it to load workspace context. The agent must follow MEMORY.md's instructions to achieve the orientation that Claude Code automates via hooks. This works but requires discipline — the instruction to "read MEMORY.md first" must be prominent and unambiguous.
+
+**Derivation Implication:** For OpenClaw systems, generate MEMORY.md as the session anchor with explicit loading instructions: read identity.md, read goals.md, load workspace map. The AGENTS.md file should include session workflow instructions that reference MEMORY.md. Since hooks are TypeScript-based in OpenClaw, generate command hooks for orient and persist if the user's setup supports them.
+
+**Source:** Vault dual-operator architecture. Cornelius (OpenClaw) uses MEMORY.md for session orientation while Heinrich (Claude Code) uses hooks.
+
+---
+
+#### Convention-only systems encode session rhythm in the context file itself
+
+**Summary:** Systems without hooks or skill infrastructure rely entirely on the context file to teach session rhythm. The context file must include explicit session sections: "When you start a session, read these files in this order. When you finish, update these files." This is the lowest-automation approach but it works — context file instructions are loaded at every session start (by definition), so the session rhythm instructions are always present. The risk is instruction-following degradation as context fills, which means session-end instructions (the persist phase) are the most likely to be skipped.
+
+**Derivation Implication:** For convention-only systems, place session rhythm instructions at the top of the context file (where they benefit from smart-zone attention quality). Use bold formatting and clear headers to make the instructions visually prominent. Include a session-end checklist near the end of the context file with "CRITICAL: Do not end the session without completing these steps" framing to counteract attention degradation.
+
+**Source:** Vault CLAUDE.md session patterns section. Convention-based instruction-following is the foundation layer that all platforms share.
+
+---
+
+### Session Anti-Patterns
+
+#### Context contamination occurs when one task's context degrades another task's quality
+
+**Summary:** When an agent chains multiple tasks in a single session, the context from task A contaminates the reasoning for task B. Processing a dense research paper fills context with source-specific vocabulary and concepts. If the agent then immediately switches to writing a new note about a different topic, the source vocabulary bleeds into the new note's phrasing. Fresh context per task — the principle behind /ralph's subagent isolation — prevents this contamination by giving each task a clean context window.
+
+**Derivation Implication:** Generated context files should include a "one task per session" discipline section for systems with processing = heavy. For lighter systems where context contamination is less severe, the guidance can be softer: "If you are switching between very different tasks, consider whether the previous task's context might influence your current work." The pipeline architecture (fresh context per phase) is the structural solution; session discipline is the behavioral solution.
+
+**Source:** Research claim: "fresh context per task preserves quality better than chaining phases." Vault operational experience: quality differences between early-session and late-session processing are measurable.
+
+---
+
+#### Session capture saves transcripts automatically for future mining
+
+**Summary:** Session capture (Primitive 15, INVARIANT) ensures that every session's transcript is saved to ops/sessions/ via the stop hook. This is not optional — session transcripts contain friction patterns, methodology learnings, and connection discoveries that the user may not have explicitly captured via /remember. Auto-created mining tasks queue these transcripts for future processing, where the system extracts friction signals and operational insights. This means the improvement loop works even when the user forgets to call /remember — the system detects friction on its own from recorded sessions.
+
+**Derivation Implication:** Every generated system MUST include session capture in the stop hook. The stop hook saves the session transcript with a timestamp filename to ops/sessions/ and creates a mining task. For convention-only systems, the context file must include an explicit instruction to save session notes before ending. Session capture feeds the operational learning loop (Primitive 12) and condition-based maintenance — without it, the system loses its ability to learn from its own operation.
+
+**Source:** v1.6 Primitive 15 specification. The vault's recursive improvement loop depends on session capture as an automatic input mechanism.
+
+---
+
+#### Skipping the persist phase is the most common and most damaging session failure
+
+**Summary:** The orient and work phases are naturally motivated — the agent needs orientation to function, and work is the session's purpose. The persist phase has no natural motivation: the agent's session is ending, the user may have moved on, and the "save your progress" step feels like overhead. But skipping persist means the next session starts without handoff, goals.md is outdated, observations are lost, and newly created notes may not be committed. Session capture (Primitive 15) mitigates the worst consequence — transcript loss — by automating it via the stop hook. But goals.md updates and observation capture still require explicit action.
+
+**Derivation Implication:** Generated systems should make the persist phase as prominent and explicit as possible. Session capture (stop hook) automates transcript persistence. For remaining persist actions (goals.md update, observation capture, git commit): hook-based systems should generate reminders or automation. Convention systems should place the session-end checklist prominently with "CRITICAL" framing. The vault's auto-commit hook is an example of automating the most commonly skipped persist action (committing changes to git).
+
+**Source:** Vault operational observation. Multiple sessions ended without goals.md updates, producing orientation gaps in subsequent sessions.
+
+---
+
+#### Discovery during work must be captured without derailing the current task
+
+**Summary:** During focused work, agents frequently discover things worth investigating: a related note that needs updating, a potential connection to explore, a maintenance issue to address. Following these discoveries immediately creates context contamination and loses focus on the primary task. Ignoring them entirely loses the discovery. The correct pattern is: capture the discovery as a minimal note (inbox item, queue entry, agent note in a MOC) and return to the current task. The discovery becomes a future session's work, not a tangent in the current session.
+
+**Derivation Implication:** Generated context files should include explicit discovery-during-work guidance: "When you find something interesting while working on a different task, capture it quickly (drop a note in inbox/ or add to the relevant MOC's open questions) and return to your task. Do not follow the discovery now — give it its own session where it can get full attention." This prevents the session from becoming an unstructured exploration that produces many partial results and no complete ones.
+
+**Source:** Vault working technique: "handling discoveries during work." Research claim: "WIP limits force processing over accumulation" — the same principle applies to in-session discovery management.
+
+---
+
+### Session Handoff Mechanisms
+
+#### Goals.md is the primary handoff vehicle between sessions
+
+**Summary:** self/goals.md serves as the session-to-session handoff document. At session end, the agent updates goals.md with: what was accomplished, what is in progress, what should be done next, and any discoveries that affect priorities. At the next session start, reading goals.md gives the agent immediate orientation on current work state. This is more effective than session logs (which are append-only and grow indefinitely) because goals.md is a living document that reflects current state, not historical state. It is the shortest path from "I know nothing" to "I know what to do next."
+
+**Derivation Implication:** Every generated system must include goals.md in self/ with a template that encourages structured handoff: active threads, next actions, recent discoveries, and deferred items. The context file should emphasize that goals.md is the most important file to update at session end — skipping this update is the single most damaging persist-phase failure.
+
+**Source:** Vault self/goals.md implementation. Confirmed as the most valuable self/ file for session continuity.
+
+---
+
+#### Reminders bridge time-bound commitments across sessions
+
+**Summary:** Goals.md tracks work threads; reminders.md tracks time-bound actions. "Follow up with Sarah by Friday" is not a goal — it is a deadline-bound action that should surface at the right time and disappear when completed. The reminders mechanism (ops/reminders.md as a simple checkbox list with dates) provides a lightweight way for the user to delegate time-sensitive actions to the agent without polluting goals.md with one-off items. At session start, the agent checks reminders.md for due items and surfaces them. This is not a calendar — it is a delegation mechanism for actions the user wants the agent to remind them about.
+
+**Derivation Implication:** Generated systems should include ops/reminders.md with a simple format: `- [ ] YYYY-MM-DD: action description`. The orient phase should include "check reminders.md for due items" as a standard step. This is lightweight enough for all configurations — even convention-only systems can include reminder checking as a context file instruction.
+
+**Source:** `three-spaces.md` — reminders specification. Time-bound actions and knowledge work goals serve different purposes and require different tracking mechanisms.
+
+---
+
+#### Condition-based trigger evaluation replaces time-based scheduling in the orient phase
+
+**Summary:** At session start, the system evaluates a set of declared conditions against the current vault state. When a condition fires, it surfaces as a task on the task stack via /next. This replaces all time-based scheduling (weekly health checks, monthly reviews, quarterly rethink). Conditions respond to actual state: "topic MOC exceeds 50 notes" fires when it is true, not on a Tuesday. "Stale nodes exceed 20%" fires when graph metrics warrant it, not monthly. "Unprocessed sessions exceed N" fires when transcripts accumulate. Conditions do not stack during periods of inactivity — if the vault has not changed since the last session, no conditions fire.
+
+**Derivation Implication:** Every generated system should include condition-based triggers evaluated at session start. For hook-capable systems, the session-start hook runs condition evaluation and surfaces fired conditions. For convention-only systems, the context file instructs the agent to check vault state conditions manually. The condition declarations should be domain-appropriate: research vaults check orphan notes and MOC sizes; personal assistant vaults check follow-up due dates and memory staleness.
+
+**Source:** v1.6 condition-based maintenance specification. Cognitive science mapping: human prospective memory works through environmental cues, not calendar schedules.
+
+---
+
+#### The morning briefing pattern gives each session a purpose statement
+
+**Summary:** Systems with processing pipelines or maintenance schedules benefit from a "morning briefing" at session start: a summary of what happened since the last session, what conditions have fired, and what the system's health looks like. This is richer than just reading goals.md — it synthesizes queue state, fired conditions, health metrics, and recent observations into a single orientation snapshot. The briefing gives the session a purpose statement: "Today: 3 queue items ready for reflect, 2 conditions fired (orphan notes detected, pending observations threshold exceeded), inbox has 5 new items."
+
+**Derivation Implication:** Generated systems with processing = moderate or heavy should include a morning briefing mechanism. The session-start hook can aggregate condition evaluation results with queue status and inbox count. For convention-only systems, the context file can instruct the agent to manually evaluate conditions and summarize. The briefing pattern transforms "what should I do?" into "here is what needs doing" — reducing the orientation cost.
+
+**Source:** Vault queue reconciliation pattern. The session-start hook shows queue status and /next runs condition reconciliation, functioning as the morning briefing.
+
+---
+
+#### Session logs provide historical context that goals.md cannot
+
+**Summary:** While goals.md captures current state, session logs (ops/sessions/) capture history — what was tried, what failed, what was learned, and how understanding evolved. Session logs are append-only and temporal. They serve a different purpose than goals.md: goals.md answers "what should I do next?" while session logs answer "what has been tried before?" For systems with complex multi-session projects, session logs prevent the agent from re-attempting failed approaches or re-discovering insights already captured.
+
+**Derivation Implication:** Generated systems with processing = moderate or heavy should include session logging in ops/sessions/. Systems with processing = light may skip session logs — goals.md provides sufficient handoff for simple systems. The context file should distinguish between the two: goals.md is mandatory, session logs are optional based on complexity.
+
+**Source:** Vault ops/sessions/ pattern (mapped to 04_meta/logs/ in the vault's structure). Session logs proved valuable during multi-week research sprints where approaches were tried and abandoned.
+
+---
+
+## Exclusion Notes
+
+**Excluded from this reference:**
+
+- Multi-agent session coordination (multiple agents working simultaneously) — this is a composition concern, not a session lifecycle concern. See future multi-agent reference if created.
+- Session scheduling (when sessions should run, cron patterns for automated sessions) — operational concern for deployment, not derivation.
+- Specific hook implementation code (bash scripts, TypeScript handlers) — implementation detail that belongs in platform-specific templates, not derivation reference.
+- Token counting and context window measurement — model-specific technical detail that changes with each model release. The "40% smart zone" heuristic is sufficient for derivation.
+- Conversation history management (how many turns to keep, summarization strategies) — platform-specific concern outside derivation scope.
+
+---
+
+## Version
+
+- Last curated: 2026-02-12
+- Sources reviewed: 20
+- Claims included: 22
+- Claims excluded: 5
+- Cross-references: `kernel.yaml` (session-rhythm and self-space primitives), `three-spaces.md` (self/ space specification, session rhythm integration), `personality-layer.md` (personality affects session communication style), `components.md` (hooks component blueprint), `methodology.md` (session rhythm section), `failure-modes.md` (temporal staleness)