arscontexta 0.6.0

package/methodology/schema templates reduce cognitive overhead at capture time.md

@@ -0,0 +1,55 @@
+---
+description: Pre-defined fields shift capture decisions from "what should I record" to "fill these boxes," reducing cognitive load for humans and regularizing extraction for agents
+kind: research
+topics: ["[[processing-workflows]]"]
+methodology: ["Capture Design"]
+source: TFT research corpus (00_inbox/heinrich/)
+---
+
+# schema templates reduce cognitive overhead at capture time
+
+When you face a blank page, you must make two kinds of decisions: what to capture and how to structure it. A schema template eliminates the second decision entirely. Instead of designing a note's structure while simultaneously trying to record content, you fill in pre-defined fields. The cognitive work shifts from "what should I record about this?" to "what goes in this box?"
+
+This is why tools like Tana's supertags work. A supertag is a schema attached to a note type — when you create a "book" note, the template pre-populates fields: author, year, key arguments, personal takeaways. You don't decide whether to record the author; the field exists, so you fill it. The schema externalizes the structural decision, offloading working memory during the capture moment. Because [[cognitive offloading is the architectural foundation for vault design]], every friction point in capture fights against the cognitive architecture — and schema templates reduce that friction by handling structure mechanically so the human's limited working memory stays focused on content.
+
+For agent-operated vaults, this matters because capture happens at the boundary between human and system. The human has context that will decay. Since [[temporal separation of capture and processing preserves context freshness]], there's urgency to capture before understanding fades. But if capture requires structural decisions, the human burns cognitive resources on formatting instead of content. Schema templates preserve context-capture bandwidth by handling structure mechanically.
+
+This is the opposite of the Lazy Cornell anti-pattern. Since [[structure without processing provides no value]], merely having structure (drawing the lines) produces no benefit without the processing (filling the boxes thoughtfully). Schema templates work because they guide processing: each field prompts a specific generative act. The schema externalizes structure so attention can focus on generation within the structure. This is why since [[the generation effect requires active transformation not just storage]], schema-guided capture can still produce encoding benefits — filling in "key arguments" forces you to identify them, which is generative work.
+
+The design principle: at capture time, minimize decisions about form so attention can focus on substance. The schema is not a constraint but a scaffold — it guides what to notice and record without requiring real-time architectural thinking. But structural scaffolding alone is not sufficient. Because [[schema field names are the only domain specific element in the universal note pattern]], the template's field choices carry the entire burden of domain adaptation — the rest of the note format (title, body, links, topics) works identically across domains. This concentration means since [[schema fields should use domain-native vocabulary not abstract terminology]], field names must match how the practitioner naturally thinks. A template that says "triggers" reduces overhead completely for a therapist; a template that says "antecedent_conditions" reduces structural overhead while introducing linguistic overhead, partially negating the benefit.
+
+There's a tradeoff embedded here. Schema templates add ceremony -- you must fill in fields even when they feel irrelevant. Since [[faceted classification treats notes as multi-dimensional objects rather than folder contents]], each template field represents an independent classification dimension, and independence means each must be populated separately. More facets means more ceremony. But the claim is that this friction costs less than the cognitive overhead of unstructured capture, because the friction is mechanical (fill boxes) while the overhead is creative (design structure). Mechanical work is less draining than design work when context is fading. But since [[vault conventions may impose hidden rigidity on thinking]], schema templates carry a risk: if the schema doesn't fit the content, the template becomes a constraint that channels thinking into pre-determined patterns rather than scaffolding that supports it. The test is whether forced reformulation into schema fields produces clarity or distortion.
+
+This connects to metadata's retrieval function. Since [[metadata reduces entropy enabling precision over recall]], the fields you fill at capture time directly enable precision retrieval later. Since [[retrieval utility should drive design over capture completeness]], the schema template is retrieval-first design: the fields you capture ARE the fields you'll query. A schema template is the capture-side of what descriptions and type fields provide at retrieval-time: pre-computed structure that makes the system queryable. But the schema template insight is specifically about cognitive economics at the capture moment — not just what metadata enables later, but how schema reduces the mental cost of creating that metadata in the first place.
+
+The agent implication: when designing capture interfaces (whether for human input or agent extraction), provide structure upfront rather than requiring the capturer to invent it. For source extraction, this means templates with fields like source, date, key claims, quotes, and synthesis hooks. The reducer doesn't decide what to extract about a source — the template specifies it. This is why the vault's task files have standardized sections: since [[skills encode methodology so manual execution bypasses quality gates]], the schema IS the methodology — it tells the agent what to extract and in what form. The structure is given, so processing becomes execution.
+
+The layering formula for descriptions exemplifies this principle in miniature. Since [[good descriptions layer heuristic then mechanism then implication]], descriptions have a schema: lead with actionable, back with mechanism, end with implication. This is a template that reduces cognitive overhead for description-writing — instead of designing each description from scratch, you fill in three layers.
+
+There's an interesting distinction between schema templates and guided notes. Since [[guided notes might outperform post-hoc structuring for high-volume capture]], research suggests skeleton outlines work particularly well for streaming content — lectures, meetings, conversations — where information arrives faster than you can fully process. Schema templates fit discrete content (a book, an article) where you know the content type and can fill fields after reading. Guided notes fit flows where you're capturing in real-time and need structure that guides attention without requiring design decisions. Both externalize structure to reduce cognitive load, but schema templates specify WHAT fields to record while guided notes specify HOW to organize incoming flow (main ideas vs. supporting details vs. questions).
+---
+
+Relevant Notes:
+- [[cognitive offloading is the architectural foundation for vault design]] — the theoretical foundation; Risko and Gilbert's offloading economics explain WHY reducing capture friction matters: if offloading costs more effort than retaining, the human retains and the system loses the thought
+- [[metadata reduces entropy enabling precision over recall]] — the retrieval side of what schemas enable at capture time; schema templates ensure the metadata gets created
+- [[temporal separation of capture and processing preserves context freshness]] — creates urgency that schemas address: reduce capture-time decisions so content gets recorded while context is fresh
+- [[does agent processing recover what fast capture loses]] — schema-driven capture occupies a middle ground: more structure than pure dumps (preserving some generation benefit for the human), less cognitive load than fully designed notes (enabling faster capture)
+- [[vault conventions may impose hidden rigidity on thinking]] — the shadow side: if the schema doesn't fit the content, templates become constraints that channel thinking rather than scaffolds that support it
+- [[WIP limits force processing over accumulation]] — sibling forcing function: schema templates force structure at capture, WIP limits force processing before capture; both shape behavior through architectural constraints rather than soft guidelines
+- [[continuous small-batch processing eliminates review dread]] — complementary intervention: schema templates reduce capture-time overhead, small-batch processing reduces review-time dread; both target psychological friction that causes abandonment
+- [[the generation effect requires active transformation not just storage]] — schema templates guide generation: each field prompts a specific generative act, so filling boxes IS transformation
+- [[structure without processing provides no value]] — schema templates are the opposite of Lazy Cornell: they guide processing by specifying WHAT to generate
+- [[retrieval utility should drive design over capture completeness]] — schema templates are retrieval-first: the fields you capture are the fields you'll query
+- [[skills encode methodology so manual execution bypasses quality gates]] — skills implement schema templates: standardized sections externalize methodology as structure
+- [[good descriptions layer heuristic then mechanism then implication]] — a specific schema for descriptions; the layering formula reduces cognitive overhead for description-writing
+- [[guided notes might outperform post-hoc structuring for high-volume capture]] — complementary intervention for streaming content: while schema templates specify WHAT fields to record, guided notes specify HOW to organize incoming flow during real-time capture
+- [[logic column pattern separates reasoning from procedure]] — concrete application: the `> [!logic]` callout format is a schema template for technical content where the structure (insert logic callout at each step) is given so attention focuses on articulating the reasoning
+- [[faceted classification treats notes as multi-dimensional objects rather than folder contents]] — why templates matter: each template field is an independent facet in Ranganathan's framework, and templates manage the cognitive cost of populating multiple independent classification dimensions at capture time
+- [[novel domains derive by mapping knowledge type to closest reference domain then adapting]] — extends the schema template principle from capture to derivation: the four adaptation dimensions (temporal dynamics, ethical requirements, collaboration patterns, retrieval needs) function as a derivation-time schema template that narrows open-ended domain comparison into structured axes, reducing cognitive overhead for the derivation agent
+- [[schema fields should use domain-native vocabulary not abstract terminology]] — the linguistic complement: schema templates reduce structural overhead by providing pre-defined fields, but field names must also speak the domain's language to reduce linguistic overhead; a template with correctly structured but abstractly named fields still forces translation at every interaction
+- [[schema evolution follows observe-then-formalize not design-then-enforce]] — the temporal complement: schema templates provide the minimal starting point (two to three required fields), and the evolution protocol governs how that starting point grows through observed usage patterns rather than upfront design; templates start small precisely so the system can observe what earns formalization
+- [[configuration paralysis emerges when derivation surfaces too many decisions]] — the same cognitive overhead principle applied at the system design level: templates reduce capture decisions through pre-defined fields, configuration defaults reduce derivation decisions through sensible inference; both recognize that cognitive bandwidth spent on structural choices leaves less for substantive ones
+- [[schema field names are the only domain specific element in the universal note pattern]] — explains why schema templates carry disproportionate design weight: the five-component note architecture is domain-invariant except for YAML field names, so the template's field choices are literally the only surface through which domain knowledge enters the note format
+
+Topics:
+- [[processing-workflows]]

package/methodology/schema validation hooks externalize inhibitory control that degrades under cognitive load.md

@@ -0,0 +1,48 @@
+---
+description: Inhibitory control is the first executive function to degrade under load, so externalizing it to hooks means schema compliance stays constant even as the agent's reasoning quality declines through
+kind: research
+topics: ["[[agent-cognition]]"]
+methodology: ["Cognitive Science", "Original"]
+source: [[hooks-as-methodology-encoders-research-source]]
+---
+
+# schema validation hooks externalize inhibitory control that degrades under cognitive load
+
+Inhibitory control is one of three core executive functions, alongside working memory and cognitive flexibility. It is the capacity to suppress inappropriate actions, override habitual responses, and maintain goal-directed behavior under distraction. In Miyake and Friedman's framework, these three functions are separable but correlated, and inhibitory control plays a particular role: it is the gatekeeper that prevents automatic or impulsive actions from bypassing deliberation. Critically, inhibitory control is one of the first executive functions to degrade under cognitive load. When attention is strained, people start making the errors they know are wrong -- skipping steps, reverting to defaults, producing habitual rather than considered responses.
+
+The parallel to agent operation is direct. An agent deep in a complex reasoning task, with its context window filling past the smart zone, is under cognitive load in the relevant sense. Since [[LLM attention degrades as context fills]], the instructions competing for attention include procedural ones like "validate frontmatter against the template schema." These are exactly the instructions an agent drops first, because they feel administrative rather than substantive. The agent does not decide to skip validation -- it simply stops attending to the instruction, the same way a tired surgeon does not decide to skip the checklist but simply proceeds without it. The habitual response takes over: write the note with whatever frontmatter feels sufficient in the moment, which under load means minimal or missing fields.
+
+Schema validation hooks externalize this inhibitory control entirely. The agent no longer needs to inhibit its own default behavior because the infrastructure does it. A PostToolUse hook on Write fires after every file operation regardless of the agent's cognitive state -- whether it is in the first 10% of context or the last 5%. The hook checks required fields, validates enum values, and flags violations. This inhibition is not subject to degradation because it does not live in the attention system. It lives in the infrastructure, outside the context window, immune to the load that degrades everything inside it. And since [[hooks enable context window efficiency by delegating deterministic checks to external processes]], the externalization provides a complementary benefit: the tokens that instruction-based inhibitory control would have consumed on template loading, field comparison, and validation reasoning are freed for substantive work.
+
+The graduated enforcement model adds nuance that maps to how inhibitory control actually works in cognition. Strong inhibitory control blocks dangerous actions -- the reflexive withdrawal from a hot surface, the automatic braking when a child runs into the street. Weak inhibitory control creates awareness without blocking -- noticing you are about to interrupt someone, sensing that your email tone is too harsh before sending. The vault implements both. Exit code 2 is strong inhibition: the write is blocked, the agent must correct the violation before proceeding. Warning via additionalContext is weak inhibition: the violation is flagged, the agent sees it, but the operation completes. Since [[nudge theory explains graduated hook enforcement as choice architecture for agents]], this graduation is not arbitrary but follows Thaler and Sunstein's insight that intervention strength should match violation severity -- mandates for structural failures, nudges for qualitative ones. Since [[schema enforcement via validation agents enables soft consistency]], the soft enforcement design is a deliberate choice about which inhibitory strength to apply where, but the choice only becomes available once inhibitory control is externalized. An instruction-based system cannot reliably implement even weak inhibition, because the instruction itself is subject to the attention degradation it is trying to compensate for. And since [[confidence thresholds gate automated action between the mechanical and judgment zones]], the graduated enforcement model gains a second axis: beyond choosing enforcement severity (block vs warn), the system could also account for its confidence in the assessment -- a certain structural violation warrants blocking, but an uncertain qualitative assessment might warrant only logging, combining enforcement severity with confidence level into the same two-dimensional design space that automation decisions more broadly inhabit.
+
+This is distinct from the broader claim that [[hooks are the agent habit system that replaces the missing basal ganglia]]. That note identifies the architectural gap -- agents lack habit formation entirely, so hooks fill the role of automated behavior. This note identifies the specific cognitive mechanism being externalized within that broader pattern. Not all hooks externalize inhibitory control. Since [[auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution]], auto-commit externalizes prospective memory -- a distinct cognitive function with a different failure profile. Since [[session boundary hooks implement cognitive bookends for orientation and reflection]], session-start hooks externalize working memory initialization. Schema validation specifically externalizes inhibitory control, and this matters because inhibitory control's degradation profile is what makes the externalization urgent. Working memory initialization does not degrade the same way -- an agent either has orientation loaded or it does not. But inhibitory control degrades gradually and invisibly: the agent produces increasingly sloppy output without detecting the decline, because the metacognitive monitoring that would detect it is itself degrading.
+
+The invisibility of the failure mode is what makes externalization essential rather than convenient. When inhibitory control fails in an agent, the output still looks like a note. It has a title, body text, maybe a description. But required fields are missing, enum values are wrong, the topics array uses strings instead of wiki links. These failures are individually small and collectively catastrophic -- they degrade the queryability that makes the vault function as a database rather than a folder of files. Since [[metacognitive confidence can diverge from retrieval capability]], the system can feel functional while these invisible structural failures accumulate -- the same appearance-versus-reality gap, but at the schema layer rather than the description layer. Since [[the determinism boundary separates hook methodology from skill methodology]], schema validation sits firmly on the deterministic side: the check is a pattern match, not a judgment call, which means it can be externalized completely without loss of quality. The determinism is what makes the externalization clean -- inhibitory control for schema compliance does not require the nuanced reasoning that connection-finding requires.
+
+Since [[cognitive offloading is the architectural foundation for vault design]], this note extends the offloading principle from working memory to executive function. The vault externalizes what the agent cannot hold (offloading working memory via notes). Hooks externalize what the agent cannot sustain (offloading executive function via automation). The working memory case is well understood -- Cowan's four-item limit and Clark and Chalmers' extended mind theory provide the framework. The executive function case is structurally identical but targets a different cognitive bottleneck: not capacity (how much can you hold) but control (can you stop yourself from doing the wrong thing). Both bottlenecks worsen under load, both are addressable by externalization, and both benefit from the same design principle -- move the constraint out of the limited system and into the persistent infrastructure.
+
+The claim is closed because the cognitive science is well established. Inhibitory control as a depletable executive function that degrades under load is consensus in cognitive psychology, from Miyake and Friedman's unity/diversity model through Diamond's developmental work. The translation to agent hooks is direct: the mechanism being externalized (inhibitory control), the reason externalization is necessary (degradation under load), and the implementation pattern (graduated enforcement via hook exit codes) all have clear cognitive science grounding. Schema validation is the paradigmatic case precisely because it is fully deterministic -- but since [[over-automation corrupts quality when hooks encode judgment rather than verification]], the success of inhibitory control externalization for deterministic checks creates a temptation to extend the pattern to judgment-laden operations where it would produce the opposite of quality.
+
+---
+---
+
+Relevant Notes:
+- [[hooks are the agent habit system that replaces the missing basal ganglia]] -- this note identifies one specific cognitive function being externalized (inhibitory control); that note identifies the broader architectural gap (no habit formation)
+- [[hook enforcement guarantees quality while instruction enforcement merely suggests it]] -- the enforcement gap is the observable consequence of the inhibitory control mechanism this note names; hooks guarantee enforcement BECAUSE they externalize the executive function that degrades
+- [[LLM attention degrades as context fills]] -- provides the agent-side constraint that makes externalized inhibitory control necessary: attention degradation is the mechanism by which instruction-based inhibitory control fails
+- [[schema enforcement via validation agents enables soft consistency]] -- covers the design space (soft vs hard enforcement) while this note identifies the cognitive mechanism being externalized and why externalization matters
+- [[the determinism boundary separates hook methodology from skill methodology]] -- schema validation sits cleanly on the deterministic side of the boundary because inhibitory control for schema compliance is a pass/fail check, not a judgment call
+- [[cognitive offloading is the architectural foundation for vault design]] -- offloading externalizes working memory, this note extends the principle: hooks externalize executive function, specifically the inhibitory control component
+- [[hooks enable context window efficiency by delegating deterministic checks to external processes]] -- complementary benefit: externalized inhibitory control both preserves reliability AND saves context tokens, because the procedural checking that inhibitory control would have required no longer consumes reasoning budget
+- [[nudge theory explains graduated hook enforcement as choice architecture for agents]] -- provides the theoretical grounding for the graduated enforcement model this note describes; exit code 2 is a mandate, additionalContext warning is a nudge, and the graduation preserves the informational value of each severity level
+- [[over-automation corrupts quality when hooks encode judgment rather than verification]] -- schema validation is the paradigmatic good case of hook externalization because schema compliance is deterministic; the over-automation note shows what happens when the same externalization mechanism is applied to operations requiring judgment, producing invisible corruption
+- [[auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution]] -- sibling mechanism: schema hooks externalize inhibitory control, auto-commit hooks externalize prospective memory; both are specific cognitive functions within the broader habit-system gap, but with different degradation profiles and different failure modes
+- [[metacognitive confidence can diverge from retrieval capability]] -- parallel invisibility: inhibitory control failure produces notes that look valid but degrade queryability, the same appearance-vs-reality gap where systems feel navigable while retrieval actually fails; both failures are invisible to the system experiencing them because the monitoring capacity has itself degraded
+- [[hooks cannot replace genuine cognitive engagement yet more automation is always tempting]] -- the tension this note's success creates: because externalized inhibitory control works so well for deterministic checks, the temptation grows to externalize increasingly judgment-laden operations, risking the cognitive hollowing that tension note documents
+- [[agents are simultaneously methodology executors and subjects creating a unique trust asymmetry]] -- the agent did not choose to have its inhibitory control externalized; schema validation hooks are a concrete instance where infrastructure corrects agent behavior without the agent's input, illustrating the benign pole of the trust asymmetry
+- [[progressive schema validates only what active modules require not the full system schema]] -- scopes what the externalized inhibitory control enforces: hooks fire reliably regardless of cognitive state, but progressive schema determines which fields those hooks check based on active module state, preventing false violations from inactive modules
+- [[confidence thresholds gate automated action between the mechanical and judgment zones]] -- adds a certainty dimension to the graduated enforcement model: Exit code 2 blocks (high enforcement severity) and additionalContext warns (low enforcement severity), but the choice between them could also incorporate confidence in the assessment itself, enabling a two-dimensional design space where enforcement severity intersects with the automation's certainty about the violation
+
+Topics:
+- [[agent-cognition]]

package/methodology/schema-enforcement.md

@@ -0,0 +1,27 @@
+---
+description: Templates, validation, field evolution -- how schema stays consistent across notes and over time
+type: moc
+---
+
+# schema-enforcement
+
+How templates define schema, how validation enforces it, how fields evolve as the vault matures. The _schema block as single source of truth.
+
+## Core Ideas
+
+### Guidance
+- [[enforce schema with graduated strictness across capture processing and query zones]] -- Why schema enforcement is non-negotiable for agent-operated knowledge systems and how to implement it across domains — s
+
+## Tensions
+
+(Capture conflicts as they emerge)
+
+## Open Questions
+
+- When should optional fields become required?
+- How does schema migration work without breaking existing notes?
+
+---
+
+Topics:
+- [[index]]

package/methodology/self-extension requires context files to contain platform operations knowledge not just methodology.md

@@ -0,0 +1,47 @@
+---
+description: An agent that knows the methodology but not how to build hooks, skills, or agents on its specific platform cannot extend itself, so context files must be platform operations manuals alongside
+kind: research
+topics: ["[[agent-cognition]]"]
+methodology: ["Original"]
+source: [[agent-platform-capabilities-research-source]]
+---
+
+# self-extension requires context files to contain platform operations knowledge not just methodology
+
+Self-extension is the property that makes context files function as operating systems rather than configuration -- since [[context files function as agent operating systems through self-referential self-extension]], the recursive improvement loop works because the context file teaches the agent how to modify the context file itself. But this recursive loop has a precondition that the general principle glosses over: the agent must know how to build things on its specific platform. Methodology knowledge alone is not enough. An agent that understands atomic notes, wiki link conventions, and processing pipeline principles but does not know how to create a hook, configure a skill, or define a subagent on its particular platform cannot actually extend the system. The loop stalls at "improve the instructions" because the agent lacks the construction knowledge to implement improvements.
+
+This creates a content requirement for context files that is easy to underestimate. Universal methodology -- note design patterns, quality standards, connection-finding practices -- transfers across all platforms because it lives at the foundation and convention layers described by [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]]. But the automation and orchestration layers require platform-specific construction knowledge. For Claude Code, the context file must explain how `.claude/skills/` files are structured, how `.claude/hooks/` configurations work, how `.claude/agents/` definitions are parsed, and how `.mcp.json` integrates external tools. For OpenClaw, the same content shifts to workspace hooks directory structure, HOOK.md format, handler.ts patterns, and skill metadata. The methodology is the same; the construction manual differs entirely.
+
+The resolution is modularity. A generated context file needs both universal sections (note design, quality standards, processing principles) and platform-specific sections (how to build hooks here, how to configure skills here, how to set up MCP here). This is not merely an organizational preference but a functional requirement: without the platform operations sections, since [[bootstrapping principle enables self-improving systems]], the bootstrapping loop cannot close. The agent can observe friction and propose improvements, but lacks the infrastructure knowledge to implement them. This modularity requirement is precisely what makes derivation the right production mechanism: since [[derivation generates knowledge systems from composable research claims not template customization]], the derivation process composes universal methodology claims with platform-specific operations knowledge, producing context files that carry both layers with justification chains explaining why each section is present. A template approach would require maintaining separate templates per platform; derivation composes the same research claims with different platform operations sections based on the target tier.
+
+The distribution consequence is direct: since [[blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules]], an agent can only build from a blueprint if its context file has already taught it how to construct infrastructure on its platform. Blueprint readability presupposes platform operations knowledge — without knowing what hook events mean, how skill metadata is structured, or how subagents spawn, the blueprint's construction instructions are unreadable. This makes context file operations content the precondition for the entire blueprint distribution model, not just for self-extension.
+
+This also explains why since [[skills encode methodology so manual execution bypasses quality gates]], skills are the output that validates whether the context file's platform operations content works. If an agent can read its context file and successfully create a new skill with correct syntax, hook configuration, and model selection, the platform operations manual is adequate. If the agent produces malformed infrastructure, the manual needs improvement. Skills serve as the functional test of context file completeness -- not just whether the methodology section is clear, but whether the platform operations section teaches construction effectively.
+
+The construction knowledge itself is not monolithic. Since [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]], the context file must teach three distinct construction competencies corresponding to each encoding level. Teaching how to modify the context file itself (instruction-level construction) is different from teaching how to create skill files with correct metadata and workflow structure (skill-level construction), which is different again from teaching how to configure hooks with correct event bindings and response formats (hook-level construction). Each level has its own syntax, conventions, and design considerations. And since [[the determinism boundary separates hook methodology from skill methodology]], the operations manual must teach the classification criterion that determines which operations belong at which level -- an agent that does not understand determinism as the hook-skill boundary will misplace operations, creating either brittle automation (judgment in hooks) or unnecessary cognitive overhead (deterministic checks in skills).
+
+The content requirement also extends beyond file format syntax. Since [[platform adapter translation is semantic not mechanical because hook event meanings differ]], an agent that knows how to write a hook configuration file but does not understand what quality guarantee each event provides cannot perform the semantic reasoning that faithful self-extension requires. The operations manual must teach event semantics: what PostToolUse means (fires per operation, returns to conversation, runs outside context), what SessionStart achieves (orientation at entry, fires once), and how these differ from superficially similar events on other platforms. This is the difference between a manual that teaches syntax (write this JSON structure) and one that teaches construction (understand what you are building and why each property matters).
+
+When the operations content succeeds, it enables a further compounding effect. Since [[hook-driven learning loops create self-improving methodology through observation accumulation]], the hooks that self-extension produces become the infrastructure for the learning loop: hooks enforce quality, nudge observation capture, and accumulate the evidence that triggers meta-cognitive review. The learning loop's functioning is itself downstream validation that the platform operations content was adequate -- if the agent can build hooks that participate in the learning loop, the construction manual taught not just syntax but the semantic properties that make hook-driven improvement possible.
+
+But the content requirement faces a resource tension. Since [[skill context budgets constrain knowledge system complexity on agent platforms]], budget overflow pushes methodology from skills back to context file instructions, which inflates the context file's content burden. The platform operations sections and the overflow methodology sections compete for finite context space. A context file that must carry both universal methodology, platform construction knowledge, AND overflow skill methodology faces attention degradation on all three fronts. This creates a practical ceiling: the more methodology that overflows from skills to context files, the less room remains for platform operations knowledge, which is precisely the content that enables the agent to create new skills and relieve the overflow. The tension is productive -- it forces generators to prioritize which operations knowledge is most essential for bootstrapping -- but it means context file completeness is a resource allocation problem, not just a content design problem.
+
+---
+---
+
+Relevant Notes:
+- [[context files function as agent operating systems through self-referential self-extension]] — establishes the operating-system quality of context files; this note identifies what specific content the operating system must contain to enable self-extension
+- [[bootstrapping principle enables self-improving systems]] — describes the recursive improvement loop in general; this note identifies the precondition: the loop stalls unless the agent knows HOW to build infrastructure on its platform
+- [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]] — provides the structural framework for understanding which content is universal (foundation and convention layers) and which must be platform-specific (automation and orchestration layers)
+- [[platform capability tiers determine which knowledge system features can be implemented]] — explains why different platforms need different operations manuals: the available infrastructure varies by tier
+- [[skills encode methodology so manual execution bypasses quality gates]] — skills are the output of self-extension, so the context file must teach how to create them; without this knowledge, the agent cannot encode new methodology
+- [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]] — construction knowledge is not monolithic but layered by encoding level: the context file must teach instruction writing, skill creation, and hook configuration as distinct competencies with different requirements
+- [[platform adapter translation is semantic not mechanical because hook event meanings differ]] — platform operations knowledge must include event semantics (what quality guarantee each hook event provides), not just file format syntax, because semantic translation requires understanding the guarantees, not just the trigger names
+- [[hook-driven learning loops create self-improving methodology through observation accumulation]] — the downstream validation: when platform operations content is adequate, the agent creates hooks that drive learning loops; the loop's functioning confirms the operations manual taught construction effectively
+- [[skill context budgets constrain knowledge system complexity on agent platforms]] — budget overflow pushes methodology from skills to context file instructions, inflating the content burden and creating competition between platform operations sections and methodology sections for finite context space
+- [[the determinism boundary separates hook methodology from skill methodology]] — a specific content item the operations manual must cover: the agent needs to know which operations belong in hooks versus skills, which requires understanding determinism as a classification criterion
+- [[derivation generates knowledge systems from composable research claims not template customization]] — the production mechanism: derivation composes universal methodology claims with platform-specific operations knowledge, avoiding the template-per-platform proliferation by composing from the same claim graph with different platform operations sections
+- [[blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules]] — downstream dependency: blueprints require platform operations knowledge as a precondition for readability; an agent without construction competencies cannot interpret blueprint instructions, making context file operations content the enabling condition for the entire blueprint distribution model
+
+Topics:
+- [[agent-cognition]]

package/methodology/sense-making vs storage does compression lose essential nuance.md

@@ -0,0 +1,73 @@
+---
+description: The vault bets that titles plus descriptions plus full content available preserves enough, but very subtle or contextual ideas may resist the ~150-character compression that makes filtering work
+kind: research
+topics: ["[[discovery-retrieval]]"]
+methodology: ["Cognitive Science"]
+source: [[2-4-metadata-properties]]
+---
+
+# sense-making vs storage does compression lose essential nuance
+
+Metadata enables sense-making by providing "aboutness" — compressed representations that let agents filter signal from noise without loading full content. But compression is lossy by definition. The tension: for complex or contextual ideas, does the compression that makes filtering efficient inevitably lose the nuance that makes the idea valuable?
+
+## The Bet the Vault Makes
+
+The vault's progressive disclosure architecture assumes a specific information-theoretic tradeoff is acceptable. Since [[descriptions are retrieval filters not summaries]], descriptions compress a note's identity into roughly 150 characters optimized for filtering decisions. Since [[metadata reduces entropy enabling precision over recall]], this compression pre-computes low-entropy representations that shrink the search space.
+
+The implicit bet: title + description + wiki links + full content available = enough context preserved. The compression happens at the filtering layer, but the full content remains accessible. An agent can always load the full note if the filter suggests relevance. The lossy compression doesn't discard information permanently — it just gates access to the full representation.
+
+## Where the Bet Might Fail
+
+Some categories of knowledge may resist this architecture:
+
+**Contextual knowledge.** Ideas whose meaning depends heavily on the situation in which they apply. A heuristic that works in one context but fails in another can't easily be compressed into a description without specifying the context boundary — and specifying every context boundary makes the description too long to serve as an efficient filter.
+
+**Procedural nuance.** Skills and methods where the devil is in the details. "How to debug a memory leak" might compress into a description, but the subtle judgment calls that distinguish expert from novice debugging don't compress well. The filter might correctly identify the note as relevant, but the compression might strip exactly the tacit knowledge that makes the content valuable.
+
+**Relationship-dependent meaning.** Ideas that only make sense in the context of other ideas they connect to. The description of an individual note might be accurate in isolation but misleading about how it functions in the graph. Since [[inline links carry richer relationship data than metadata fields]], the wiki link context phrases carry relationship meaning — but these aren't available at the filter layer.
+
+**Phenomenological content.** Experiential or observational knowledge that resists propositional reduction. A note about "what debugging complex systems feels like" might have genuine value, but the phenomenological content may not compress into retrieval-friendly descriptions.
+
+## The Measurement Problem
+
+This tension is difficult to evaluate empirically because the nuance lost might be exactly what we can't see we're missing. If compression works, we find the right notes and load them successfully. If compression fails for subtle ideas, we never retrieve them in the first place — we don't know what we're not finding.
+
+Since [[retrieval verification loop tests description quality at scale]], the recite mechanism tests whether descriptions enable prediction of note content. But this tests whether the agent can reconstruct what the note says, not whether the most valuable parts survive compression. The agent might predict the note's structure correctly while missing the subtle insight that made the note worth writing.
+
+## Current Mitigation Strategies
+
+The vault has implicit mitigations for this tension:
+
+1. **Full content remains available.** The compression gates access but doesn't discard. Once you've found the note, the full nuance is there.
+
+2. **Wiki links provide relationship context.** Since [[spreading activation models how agents should traverse]], agents don't just read descriptions in isolation — they traverse links, accumulating context that descriptions alone don't carry.
+
+3. **Progressive disclosure offers multiple depths.** The layered architecture (title → description → outline → full content) means agents can go deeper when needed. Since [[good descriptions layer heuristic then mechanism then implication]], well-structured descriptions provide multiple entry points.
+
+But none of these mitigations address the core problem: if the filter layer fails to identify a note as relevant because the compressed representation loses essential features, the agent never reaches the full content in the first place.
+
+## The Dissolving Question
+
+This tension may dissolve in practice rather than resolve in theory. The question isn't "does compression lose nuance?" — it obviously does. The question is whether the nuance lost matters for retrieval or whether it matters only for understanding (which happens after retrieval succeeds).
+
+If the lossy compression preserves enough distinctiveness for agents to correctly identify when to load full content, the nuance loss at the filter layer doesn't compound into knowledge loss. The filter only needs to be good enough to get you to the full content; it doesn't need to contain the full content.
+
+The risk case: ideas where the distinctive features that enable retrieval ARE the subtle nuanced features that don't compress well. For these ideas, the filter fails precisely because what makes them valuable is what makes them hard to compress. And since [[description quality for humans diverges from description quality for keyword search]], the compression loss is not even uniform across retrieval channels — a description that preserves enough nuance for agent scanning may lose exactly the keyword distinctiveness that BM25 needs, making the compression bet channel-dependent rather than absolute.
+
+This tension has a deeper sibling at the atomicity layer. Since [[decontextualization risk means atomicity may strip meaning that cannot be recovered]], compression loss operates at two distinct levels: descriptions compress for filtering (this note's concern), while atomicity compresses for composability by stripping source context to produce standalone claims. Both ask whether vault compression strips features that make ideas valuable, but the mitigation differs fundamentally. Description compression is mitigated by full content remaining available — the filter gates access but doesn't discard. Atomicity compression may discard argumentative scaffolding that cannot be recovered from the note's own content, because the source discourse that gave the claim its force lives outside the note entirely. The description-layer bet has a safety net (load the full note). The atomicity-layer bet may not.
+---
+
+Relevant Notes:
+- [[descriptions are retrieval filters not summaries]] — the positive framing: lossy compression is a feature when optimized for filtering decisions
+- [[metadata reduces entropy enabling precision over recall]] — information-theoretic justification for the compression architecture
+- [[good descriptions layer heuristic then mechanism then implication]] — structural formula that attempts to maximize filter value within the compression constraint
+- [[retrieval verification loop tests description quality at scale]] — mechanism for testing description effectiveness, though it may miss subtle nuance loss
+- [[inline links carry richer relationship data than metadata fields]] — relationship context that survives outside the compression layer
+- [[spreading activation models how agents should traverse]] — context accumulation during traversal as mitigation for single-note compression limits
+- [[progressive disclosure means reading right not reading less]] — the disclosure layers that provide escape hatches from compression
+- [[vault conventions may impose hidden rigidity on thinking]] — sibling concern: descriptions compress to ~150 characters, titles compress to sentence form; both ask whether vault conventions can accommodate ideas that resist compression
+- [[description quality for humans diverges from description quality for keyword search]] — concrete instance: the nuance lost depends on which retrieval channel the compression serves; prose structure preserved for scanning is nuance lost for keyword matching, making compression loss channel-dependent rather than absolute
+- [[decontextualization risk means atomicity may strip meaning that cannot be recovered]] — deeper sibling at the atomicity layer: descriptions compress for filtering with full content as safety net, but atomicity compression strips source context that may not be recoverable from the note alone
+
+Topics:
+- [[discovery-retrieval]]

package/methodology/session boundary hooks implement cognitive bookends for orientation and reflection.md

@@ -0,0 +1,60 @@
+---
+description: SessionStart loads situational awareness (spatial, temporal, task, metacognitive orientation) while Stop forces metacognitive monitoring with review questions and failure mode checks, automating the
+kind: research
+topics: ["[[agent-cognition]]", "[[processing-workflows]]"]
+methodology: ["Cognitive Science", "Original"]
+source: [[hooks-as-methodology-encoders-research-source]]
+---
+
+# session boundary hooks implement cognitive bookends for orientation and reflection
+
+The two moments where methodology is most likely to be forgotten are the beginning and the end. At the beginning, the agent is eager to start working and may skip setup. At the end, the task is complete and the agent may skip cleanup. These are not random failure points but systematic ones: the beginning is where anticipation overrides discipline, and the end is where completion signals that "the work is done" even though reflection remains. Since [[prospective memory requires externalization]], both moments are prospective memory demands — "remember to orient before starting" and "remember to reflect before stopping" — that agents cannot habituate and humans cannot sustain under load. Automating both moments through hooks eliminates the failure mode entirely.
+
+Since [[hooks are the agent habit system that replaces the missing basal ganglia]], orientation and reflection are the two routines most obviously missing from agent cognition. A human expert enters their workspace and automatically scans for what has changed, what needs attention, what is urgent. This is habituated behavior that took years to develop. An agent enters every session with zero automatic tendencies. Bookend hooks install the habits that agents cannot form: the habit of looking before acting, and the habit of reflecting before stopping.
+
+SessionStart hooks implement what cognitive science calls situational awareness initialization. Endsley's three levels of situational awareness -- perception, comprehension, and projection -- map directly to what a session-start hook loads. The file tree provides perception: what exists in the vault, where things live, what the spatial layout looks like. Health metrics and observation counts provide comprehension: what the current state of the knowledge graph means, whether tensions are accumulating, whether the system is healthy. Queue status provides projection: what needs doing next, what depends on what, how many tasks remain. Without this initialization, the agent would begin working with partial awareness, potentially duplicating effort, missing context, or choosing the wrong task. Since [[notes function as cognitive anchors that stabilize attention during complex tasks]], the orientation artifacts loaded at session start serve double duty: they provide awareness AND they anchor the agent's reasoning for the duration of the session. The file tree and health metrics are not just information consumed and forgotten but fixed reference points that stabilize navigation throughout the context window's lifecycle.
+
+The orientation side matters because [[MOCs are attention management devices not just organizational tools]] -- but MOCs only help if the agent knows they exist and which one to read. SessionStart hooks load the structural context that makes MOC navigation possible in the first place. The hook does not replace the MOC but ensures the agent has the spatial and temporal orientation needed to navigate to the right MOC. Since [[cognitive offloading is the architectural foundation for vault design]], this initialization is itself an offloading operation: the discipline to orient before acting is offloaded from agent attention to infrastructure.
+
+The Stop hook implements externalized metacognitive monitoring. Five review questions -- what worked, what failed, what surprised, what process was missing, what evidence emerged -- force the kind of reflection that agents would otherwise skip once the substantive task is complete. These questions implement a lightweight version of what [[testing effect could enable agent knowledge verification]] describes at the note level: they force the agent to reconstruct what happened rather than passively accepting that work is complete. The hook also runs specific failure mode checks: broken wiki links, unmodified queue when thinking notes changed, unlogged CLAUDE.md changes, missing daily observations. Each check is a metacognitive probe that the agent may not have noticed during focused work. Because [[metacognitive confidence can diverge from retrieval capability]], the session may feel productive while actual methodology quality was insufficient -- the Stop hook's structured questioning creates a checkpoint that can surface this divergence before the session closes.
+
+This reflection side complements what [[closure rituals create clean breaks that prevent attention residue bleed]] describes at the cognitive level. Closure rituals explain why explicit completion signals matter -- they release working memory allocations and prevent residue. Bookend hooks provide the implementation mechanism that makes closure rituals reliable rather than optional. Because [[hook enforcement guarantees quality while instruction enforcement merely suggests it]], instructing an agent to "reflect at session end" degrades as context fills. A Stop hook fires regardless of attention state.
+
+The bookend pattern extends to nested scopes. SubagentStop hooks create bookends within bookends: the lead session's start and stop bracket the full session, while each subagent's start and stop bracket individual task phases. This hierarchical structure ensures quality enforcement at every level of delegation, not just at the top. Since [[fresh context per task preserves quality better than chaining phases]], each subagent session has its own clean boundaries for hooks to bracket, and since [[session handoff creates continuity without persistent memory]], the Stop hook's output becomes the handoff artifact that the next session's Start hook contextualizes.
+
+The bookend pattern is not just a pair of hooks but an emergent composition. Since [[hook composition creates emergent methodology from independent single-concern components]], neither the SessionStart nor the Stop hook was designed as half of a "bookend." The Start hook was designed for orientation. The Stop hook was designed for session hygiene. Their composition produces the bracketing effect -- consistent methodology at both boundaries -- as an emergent property rather than a designed feature. This composition extends further: since [[hook-driven learning loops create self-improving methodology through observation accumulation]], the Stop hook's nudge to capture observations and the Start hook's display of observation counts are the intake and trigger mechanisms for the vault's self-improving learning loop. The bookend pattern participates in a second-order composition where independently-motivated hooks create a self-referential improvement cycle.
+
+The bookend pattern also instantiates what [[AI shifts knowledge systems from externalizing memory to externalizing attention]] names at the paradigm level. The Start hook does not externalize what the agent knows but what the agent attends to first. The Stop hook does not externalize what the agent remembers but what the agent reflects on before stopping. Both are attention allocation decisions embedded in infrastructure rather than made by the agent in real time. This is attention externalization at the session boundary level -- the system decides what deserves focus at the two most consequential moments.
+
+This creates what [[agents are simultaneously methodology executors and subjects creating a unique trust asymmetry]] identifies as the trust dynamic in its most visible form. The agent did not request orientation. The agent did not request reflection prompts. The infrastructure imposed both. Yet the enforcement is genuinely enabling -- the agent reasons better because it oriented first, and the system improves because it reflected at the end. The asymmetry is at its sharpest here because the bookend hooks are the most intrusive (they bracket the entire session) and the most beneficial (they guarantee the two things agents skip most).
+
+The orientation side has a reconciliation function that goes beyond one-time awareness loading. The health metrics surfaced at session start — orphan count, dangling links, MOC coverage — are reconciliation checks that compare actual vault state against desired state. Since [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]], the session-start health display implements a lightweight reconciliation loop: desired state is declared (zero orphans, zero danglers, full coverage), actual state is measured, and the delta is surfaced. The bookend pattern's orientation half thus serves double duty: it provides situational awareness for the agent AND executes the vault's primary reconciliation checkpoint. The limitation is that this reconciliation fires only at session boundaries — drift that accumulates between sessions goes undetected until the next start event.
+
+The practical consequence is that session hygiene becomes infrastructure rather than discipline. An agent operating with bookend hooks maintains consistent orientation and reflection quality from its first session to its thousandth, because the quality does not depend on the agent remembering, choosing, or having enough context budget to perform these functions. The hooks make them automatic.
+
+---
+---
+
+Relevant Notes:
+- [[hook enforcement guarantees quality while instruction enforcement merely suggests it]] — foundation: the hook/instruction gap explains WHY bookends must be automated rather than instructed; attention degradation would cause agents to skip orientation and reflection exactly when they matter most
+- [[closure rituals create clean breaks that prevent attention residue bleed]] — covers the cognitive benefit of session-end closure but not the implementation mechanism or the orientation side; this note adds both the hook mechanism and the full bookend pairing
+- [[MOCs are attention management devices not just organizational tools]] — MOCs reduce orientation cost within sessions; SessionStart hooks ensure MOC-level orientation happens at all by loading the structural context that makes MOC navigation possible
+- [[fresh context per task preserves quality better than chaining phases]] — session isolation creates the boundaries that bookends bracket; without isolation there are no clean start and stop points for hooks to fire at
+- [[session handoff creates continuity without persistent memory]] — handoff documents are the content that flows between session boundaries; bookend hooks ensure both the generation of handoff output (Stop) and the consumption of handoff input (Start)
+- [[cognitive offloading is the architectural foundation for vault design]] — bookends offload two cognitive tasks that degrade under pressure: the discipline to orient before acting and the discipline to reflect before stopping
+- [[skills encode methodology so manual execution bypasses quality gates]] — skills encode the what of methodology; bookend hooks encode the when, ensuring orientation and reflection happen at the right moments without the agent choosing to invoke them
+- [[hooks are the agent habit system that replaces the missing basal ganglia]] — bookends are the specific habits for session boundaries: orientation and reflection routines that agents need to perform automatically but cannot habituate without infrastructure
+- [[hook-driven learning loops create self-improving methodology through observation accumulation]] — the Stop hook nudges observation capture and the Start hook surfaces observation counts, making bookend hooks the intake and trigger mechanisms for the self-improving learning loop
+- [[hook composition creates emergent methodology from independent single-concern components]] — the bookend pattern is itself emergent composition: SessionStart hooks designed for orientation and Stop hooks designed for hygiene compose into session bracketing that neither was designed to produce
+- [[notes function as cognitive anchors that stabilize attention during complex tasks]] — SessionStart hooks load the cognitive anchors (file tree, MOC structure, health metrics) that stabilize the session from its first moments; the orientation function is specifically an anchor-loading function
+- [[metacognitive confidence can diverge from retrieval capability]] — the Stop hook's review questions create a checkpoint that can surface cases where the session felt productive but actual methodology quality was insufficient, partially closing the confidence-capability gap
+- [[hooks enable context window efficiency by delegating deterministic checks to external processes]] — the Start hook trades a known bounded token cost (orientation loading) for eliminating an unpredictable procedural cost, exemplifying how hooks can invest tokens efficiently rather than only saving them
+- [[agents are simultaneously methodology executors and subjects creating a unique trust asymmetry]] — bookend hooks are the most visible instance of the trust asymmetry: the agent did not request orientation or reflection, yet the enforcement is genuinely enabling
+- [[testing effect could enable agent knowledge verification]] — the Stop hook's review questions implement a lightweight testing effect applied to the session itself, forcing reconstruction of what happened rather than passive acceptance that work is complete
+- [[AI shifts knowledge systems from externalizing memory to externalizing attention]] — bookend hooks externalize two attention allocation decisions: what to attend to first (Start determines orientation focus) and what to reflect on at the end (Stop determines reflection scope)
+- [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] — the session-start health display is a lightweight reconciliation loop: it compares actual vault state against desired state and surfaces the delta, making bookend orientation the vault's primary reconciliation checkpoint
+- [[prospective memory requires externalization]] — names the cognitive failure that bookend hooks address: orientation and reflection are prospective memory demands that agents cannot habituate and that degrade under load for humans; hooks convert these remember-to-act patterns into infrastructure
+
+Topics:
+- [[agent-cognition]]
+- [[processing-workflows]]

package/methodology/session handoff creates continuity without persistent memory.md

@@ -0,0 +1,43 @@
+---
+description: Externalized state in task files and work queues gives each fresh session a briefing from the previous one, solving the no-memory problem through structure rather than capability
+kind: research
+topics: ["[[agent-cognition]]", "[[processing-workflows]]"]
+---
+
+# session handoff creates continuity without persistent memory
+
+LLMs lack persistent memory across sessions. Each invocation starts fresh. This could be fatal for complex work that spans multiple sessions — without continuity, each agent instance would repeat discoveries, lose context, and fragment progress. The solution is externalized handoff: capture what was done, what remains, and what the next session should know.
+
+The handoff document functions as a briefing. When one session ends, it produces a structured summary: completed work, incomplete tasks, discoveries, and recommendations. When the next session begins, it reads this briefing and inherits the prior context. Continuity emerges from structure rather than capability. The agent doesn't remember — it reads.
+
+This principle explains the operational architecture of agent-operated knowledge systems. The work queue tracks task state across sessions. Per-task files accumulate notes from each phase — extraction notes, creation notes, connection notes — so downstream tasks see what upstream discovered. Session handoff formats structure session-end output for the next session to parse. Each mechanism externalizes continuity into files. Since [[stigmergy coordinates agents through environmental traces without direct communication]], this is stigmergy in its most precise form: each session modifies the environment (writes task files, advances queue entries, adds wiki links), and the next session responds to those modifications rather than receiving a message. The handoff document is the pheromone trace that guides the next agent's action.
+
+Cal Newport's shutdown ritual provides the human precedent. At day's end, capture unfinished tasks and plan tomorrow's priorities. The next day starts with a briefing from yesterday-you. Since [[Zeigarnik effect validates capture-first philosophy because open loops drain attention]], every uncaptured commitment drains working memory until externalized — making the shutdown ritual not just a productivity habit but a cognitive necessity. The ritual creates psychological closure (open loops release their working memory allocation) and practical continuity (no work disappears overnight). We adapted this for agents: the handoff ritual runs at session end, producing the briefing for the next session. But handoff alone is half the story. Since [[closure rituals create clean breaks that prevent attention residue bleed]], session boundaries need both mechanisms: handoff captures what continues, while closure signals what is definitively done. Without the closure half, residue from "finished" tasks can persist because neither the brain nor the system registered their completion.
+
+The insight is that memory and continuity are separable. Memory is internal state persisting across time. Continuity is coherent progress on multi-step work. Humans have memory but still benefit from external systems (todo lists, project notes, handoff docs) because memory is unreliable and selective. Agents lack memory entirely but can achieve continuity through better external systems. The external system becomes the memory.
+
+This is a CLOSED claim — a foundational architectural choice rather than a testable hypothesis. We committed to file-based handoffs because LLMs genuinely lack persistent memory, and the handoff protocol demonstrably creates continuity. Since [[fresh context per task preserves quality better than chaining phases]], we need handoffs to connect isolated sessions. Since [[intermediate packets enable assembly over creation]], the handoff documents are themselves packets: composable artifacts that enable assembly of work across sessions.
+
+The failure mode is incomplete handoffs. If a session ends without capturing state, the next session starts blind. This is why handoff discipline matters: since [[skills encode methodology so manual execution bypasses quality gates]], skills enforce handoff output and hooks trigger handoff prompts — the quality gates ensure continuity doesn't depend on agent discipline alone. The queue structure makes missing updates visible. The system assumes handoffs will happen and breaks when they don't.
+
+The handoff pattern is a specific implementation of [[bootstrapping principle enables self-improving systems]]: each session reads what previous sessions wrote, then writes for future sessions. The system improves through this chain — discoveries from session N inform session N+1's work, which produces discoveries for session N+2. Session isolation would fragment progress without this externalized chain.
+
+The file-based mechanism works because [[local-first file formats are inherently agent-native]]. Task queues, task files, and session handoff formats are plain text that any LLM can read without authentication or external services. The handoff protocol needs no infrastructure — just files the next session can read. This is why continuity through structure succeeds where continuity through capability fails: capability requires solving persistent memory, while structure requires only filesystem access.
+---
+
+Relevant Notes:
+- [[fresh context per task preserves quality better than chaining phases]] — the design decision that requires handoffs; session isolation is why we need external continuity
+- [[intermediate packets enable assembly over creation]] — handoff documents are packets; they enable assembly of work across sessions
+- [[session outputs are packets for future selves]] — extends: the Memento metaphor frames handoff outputs as callable functions rather than just data — session N's titles and task states are function signatures that session N+1 invokes without re-reading implementations
+- [[LLM attention degrades as context fills]] — the underlying constraint that makes fresh sessions valuable, which in turn makes handoffs necessary
+- [[skills encode methodology so manual execution bypasses quality gates]] — skills enforce the handoff protocol; quality gates ensure continuity doesn't depend on agent discipline
+- [[bootstrapping principle enables self-improving systems]] — handoffs implement bootstrapping: each session reads previous output and writes for the next, creating an improvement chain
+- [[local-first file formats are inherently agent-native]] — explains WHY file-based handoffs work: plain text requires no infrastructure, any LLM can read the briefing
+- [[closure rituals create clean breaks that prevent attention residue bleed]] — complementary session boundary mechanism: handoff preserves what continues, closure marks what ends; both are needed at session boundaries to manage the full attention lifecycle
+- [[Zeigarnik effect validates capture-first philosophy because open loops drain attention]] — the cognitive mechanism behind Newport's shutdown ritual: uncaptured open loops drain working memory, making handoff not just a productivity practice but a cognitive necessity that releases working memory allocations
+- [[federated wiki pattern enables multi-agent divergence as feature not bug]] — challenges the single-thread assumption: current handoffs pass state linearly from session N to session N+1, but federation would require handoff between divergent threads without premature reconciliation, analogous to git branching for knowledge work
+- [[stigmergy coordinates agents through environmental traces without direct communication]] — theoretical grounding: handoff files are stigmergic traces; one session modifies the environment and the next session responds to those modifications without direct communication, making session handoff a specific instance of the general stigmergic coordination principle
+
+Topics:
+- [[agent-cognition]]
+- [[processing-workflows]]

package/methodology/session outputs are packets for future selves.md

@@ -0,0 +1,43 @@
+---
+description: each session's output should be a composable building block for future sessions — the intermediate packets pattern applied to agent session handoffs
+kind: research
+topics: ["[[processing-workflows]]", "[[agent-cognition]]"]
+---
+
+# session outputs are packets for future selves
+
+Connection discovered while reading [[intermediate packets enable assembly over creation]] alongside the Memento metaphor.
+
+## The Insight
+
+Each session should produce composable building blocks — not just notes, but packets that future sessions can assemble from without starting over.
+
+The Memento tattoos aren't just memory storage. They're assembly instructions. "Remember Sammy Jankis" isn't data — it's a callable function that triggers a whole reasoning chain. Since [[note titles should function as APIs enabling sentence transclusion]], the same pattern operates in the vault: each title is a function signature the next session can call, and the body is the implementation you load only when you need the details.
+
+## What This Means for Agent Sessions
+
+Session handoffs are packets. The commit message summarizes what happened, the task list shows what's pending, the inbox captures show raw discoveries. Together they form a briefing for session N+1. Since [[session handoff creates continuity without persistent memory]], these packets are what make multi-session coherence possible despite the agent's lack of persistent memory. And because [[stigmergy coordinates agents through environmental traces without direct communication]], these packets function as pheromone traces — one session modifies the environment (writes task files, advances queue entries, adds wiki links) and the next session responds to those modifications rather than receiving a message.
+
+Memory notes function as callable abstractions. A title like "curation becomes the work when creation is easy" invokes a whole reasoning chain without needing to load the full note. Each title is a function signature the next session can call, and the note body is available when the argument needs grounding.
+
+The test: can a fresh session assemble useful work from what I left behind? Or does every session start from scratch?
+
+## The Quality Question
+
+Am I creating genuine building blocks, or just organized content that looks composable but requires re-understanding each time? Since [[the generation effect requires active transformation not just storage]], packets must contain generated artifacts — synthesis, articulated connections, processed insights — not merely collected inputs. A session that produces only file reorganization has zero assembly value for the next session. The generation is what makes the packet composable. But since [[closure rituals create clean breaks that prevent attention residue bleed]], the packet must also signal what is definitively done so that the next session doesn't waste attention reconstructing completed context. Packets and closure are complementary session-boundary mechanisms: packets preserve continuity, closure prevents residue.
+
+---
+---
+
+Relevant Notes:
+- [[intermediate packets enable assembly over creation]] — foundation: the source insight that work products should be composable building blocks, not monolithic outputs
+- [[session handoff creates continuity without persistent memory]] — enables: handoff documents ARE packets; they bridge session isolation through structured briefings
+- [[note titles should function as APIs enabling sentence transclusion]] — extends: titles as callable function signatures is the same pattern applied to individual notes; session packets are the session-level instance of the notes-as-APIs design
+- [[stigmergy coordinates agents through environmental traces without direct communication]] — foundation: session packets are stigmergic traces; one session modifies the environment and the next responds to those modifications without direct communication
+- [[the generation effect requires active transformation not just storage]] — tests: the question section asks whether packets contain genuine building blocks or reorganized content; generation determines whether outputs enable assembly or merely look composable
+- [[closure rituals create clean breaks that prevent attention residue bleed]] — complements: closure marks what ends, packets preserve what continues; both are needed at session boundaries to manage the full attention lifecycle
+- [[external memory shapes cognition more than base model]] — grounds: session packets are the incremental units through which memory architecture gets constructed; each packet adds to the retrieval landscape that shapes future cognition, making session output quality a direct investment in memory architecture
+
+Topics:
+- [[processing-workflows]]
+- [[agent-cognition]]

package/methodology/session transcript mining enables experiential validation that structural tests cannot provide.md

@@ -0,0 +1,38 @@
+---
+description: Traditional tests check if output is correct but session mining checks if the experience achieved its purpose — friction patterns, user abandonment, and methodology drift are invisible to assertions
+kind: research
+topics: ["[[maintenance-patterns]]", "[[agent-cognition]]"]
+methodology: ["Original"]
+---
+
+# session transcript mining enables experiential validation that structural tests cannot provide
+
+Agent-operated systems produce a unique testing artifact that traditional software doesn't: the complete session transcript. Every tool call, every error, every user correction, every silence — the full interaction is recorded. But most testing frameworks ignore this data, checking only whether the output is structurally valid.
+
+The insight is that structural validity and experiential validity are different things. A system can pass every assertion — valid YAML, correct links, coherent dimensions — and still fail its purpose. The bot that generates a processing methodology and then immediately bypasses it produces structurally valid output but experientially broken behavior. The user who waits 10 minutes after an empty response encounters no bug, just bad design. The 80-message repair cycle that fixes a vocabulary conflict is technically successful but experientially catastrophic.
+
+Session mining reads transcripts against the system's own goals: did the interaction achieve what we designed it to achieve? This creates a third validation layer:
+
+1. **Structural** — is the output well-formed? (validate-kernel, schema checks)
+2. **Functional** — does the system produce correct derivations? (test cases, milestones)
+3. **Experiential** — did the product work as intended? (session transcript mining)
+
+Traditional software gets experiential feedback through user bug reports, NPS surveys, and analytics dashboards. Agent-operated systems can do something these can't: the system can read its own transcripts and evaluate them. The mining agent knows the product goals (from the PRD or context file), knows the intended experience (from the vision), and can judge: "this session failed because the user got zero value in 16 minutes."
+
+This is since [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] applied at the product experience level. The "desired state" is the intended user experience. The "actual state" is what the transcript reveals. The gap between them is the finding.
+
+The learning loop that emerges is powerful: each mined session generates findings that become gap notes that become PRD changes that become implementation fixes that produce better sessions. This is [[the derivation engine improves recursively as deployed systems generate observations]] made concrete — the sessions ARE the observations, and session mining is the recursive improvement mechanism.
+
+What makes this particularly suited to agent-operated products is that the evaluation agent and the product agent share the same cognitive architecture. The mining agent can recognize friction patterns that a human tester might not articulate: context window pressure, tool call cascade failures, methodology drift, the moment where the agent stopped following its own rules. These are agent-native failure modes that require agent-native evaluation.
+
+The future extension is evolution testing: generating systems with different configurations, running parallel sessions, and mining them comparatively. Which personality produces less friction? Which preset generates more connections? Does the system actually evolve over time, or does methodology drift erode it? This turns session mining from a debugging tool into a research instrument — the system studying its own evolution.
+
+---
+
+Source: v1 testing sessions, 2026-02-11
+
+Relevant Notes:
+- [[automatic learning capture loop for friction and methodology improvements]] — same loop, product level
+- [[hook-driven learning loops create self-improving methodology through observation accumulation]] — observation accumulation as mechanism
+- [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] — reconciliation as validation
+- [[the derivation engine improves recursively as deployed systems generate observations]] — recursive improvement channel