arscontexta 0.6.0

package/methodology/skill context budgets constrain knowledge system complexity on agent platforms.md

@@ -0,0 +1,52 @@
+---
+description: Claude Code allocates 2% of context for skill descriptions (16k char fallback), capping active modules at 15-20 and forcing split/deactivation decisions that shape how generators design composable
+kind: research
+topics: ["[[agent-cognition]]"]
+methodology: ["Original"]
+source: [[agent-platform-capabilities-research-source]], [[composable-knowledge-architecture-research-source]]
+---
+
+# skill context budgets constrain knowledge system complexity on agent platforms
+
+Agent platforms impose hard limits on how much context skill descriptions can consume. Claude Code allocates 2% of the context window for all skill descriptions, with a fallback of 16,000 characters. This is not soft guidance -- it is a platform-enforced ceiling that determines how many skills a knowledge system can expose before descriptions start getting truncated or omitted.
+
+The constraint matters because since [[skills encode methodology so manual execution bypasses quality gates]], the number of skills a system can maintain is not a convenience metric but a methodology metric. Each skill encodes a distinct quality gate, a processing workflow, a set of checks that the methodology depends on. A vault with twelve skills (reduce, reflect, reweave, verify, seed, pipeline, ralph, archive-batch, cross-connect, review, rethink, blueprint) is encoding twelve distinct workflows. If the platform's budget forces consolidation, some of those workflows merge or disappear, and the methodology changes shape to fit the container.
+
+The tradeoff has two poles. A minimalist approach uses fewer comprehensive skills -- combining reflect and reweave into a single "connect" skill, merging seed and archive-batch into lifecycle management. This stays within budget but sacrifices the fine-grained quality gates that separate skills provide. Each gate exists for a reason: reflect finds forward connections while reweave reconsiders backward connections, and merging them means one concern dominates the other. A modular approach keeps skills focused but risks exceeding the description budget, especially as the knowledge system grows and new workflows emerge. Since [[complex systems evolve from simple working systems]], there is a reconciliation: start with consolidated skills and split them only when the pain of consolidation exceeds the budget cost of separation. The budget enforces the evolutionary patience that Gall's Law recommends but that designers tend to skip.
+
+Since [[progressive disclosure means reading right not reading less]], skill descriptions are themselves a progressive disclosure layer. Since [[the AgentSkills standard embodies progressive disclosure at the skill level]], this is not an analogy but a structural isomorphism: the same metadata-then-depth loading pattern that governs note retrieval also governs skill loading, and both operate within the same context window. But unlike the vault's other disclosure layers (file tree, YAML descriptions, MOC outlines), the skill disclosure layer operates under a hard budget that the platform enforces. The description must fit within the allocation or it does not exist in the agent's awareness at session start.
+
+Since [[LLM attention degrades as context fills]], there is a second-order cost: skill descriptions consume context from the first token of every session, reducing the effective smart zone for actual work. A knowledge system with generous skill descriptions pays this tax on every task, not just tasks that use those skills. Since [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]], skill budgets are strictly an automation-layer constraint. The convention layer (instructions in a context file) has no such budget -- it faces attention degradation but not hard character limits. This asymmetry means a knowledge system generator that moves methodology from convention-layer instructions into automation-layer skills trades soft degradation for hard limits, which can be either better (enforcement guarantees) or worse (truncation risk) depending on the skill count. The tradeoff sharpens further because since [[hook enforcement guarantees quality while instruction enforcement merely suggests it]], methodology that exceeds the skill budget and falls back to instruction encoding loses not just convenience but enforcement strength -- the guarantee degrades from structural to aspirational. There is a partial escape from this degradation cascade: since [[hooks enable context window efficiency by delegating deterministic checks to external processes]], operations that are deterministic enough to be automated can be promoted from skills to hooks, consuming zero description budget while maintaining enforcement guarantees. Hook delegation selectively relieves budget pressure by moving methodology that does not require semantic judgment outside the budget entirely.
+
+The practical implication for knowledge system generators is that skill set design is a resource allocation problem. Since [[knowledge system architecture is parameterized by platform capabilities not fixed by methodology]], the skill budget becomes one of the parameters the generator must account for alongside hook availability, subagent support, and context file write access. The generator must estimate the total description budget, allocate it across skills by priority, and consolidate workflows that rarely need independent invocation. Since [[platform capability tiers determine which knowledge system features can be implemented]], platforms that lack skills entirely avoid this constraint but lose the methodology encoding that skills provide. The budget is a first-tier problem -- a constraint you encounter precisely because you have the capability.
+
+The budget arithmetic yields a concrete module ceiling. At 16,000 characters total and 200-400 characters per module description, a knowledge system can sustain roughly 15-20 active modules before the budget strains. The derivation is straightforward: each module gets 800-1000 characters of raw allocation at 15-20 modules, but descriptions should stay at the shorter end to leave room for the context file's methodology instructions that share the same attention space. This ceiling operationalizes the abstract budget constraint into a planning number that generators can use during module design. Since [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]], the module ceiling is not just a platform limitation but a design parameter that shapes how fine-grained the module decomposition can be. A system that splits every concern into its own module hits the ceiling faster than one that bundles related concerns, creating pressure toward the right granularity level — since [[each module must be describable in one sentence under 200 characters or it does too many things]], the tension is between modules small enough to describe simply and a budget that cannot accommodate too many of them.
+
+The ceiling also implies decision thresholds for module lifecycle. A module should split when its description exceeds 500 characters or its instructions exceed 5,000 tokens, because at that point the module is doing too many things and its description is consuming disproportionate budget. Conversely, a module should be considered for deactivation when it has gone unused for three or more sessions and has no active dependents, because it is consuming budget without delivering value. These thresholds prevent two failure modes: the bloated module that monopolizes the description budget, and the dormant module that taxes every session's context without contributing to any. Since [[friction-driven module adoption prevents configuration debt by adding complexity only at pain points]], these thresholds are not just budget management but part of a broader lifecycle protocol where modules are added at demonstrated pain points and removed when they stop earning their budget allocation. Since [[progressive schema validates only what active modules require not the full system schema]], deactivation does not lose the module permanently — it removes it from the active budget while keeping its schema and instructions available for reactivation when the need returns.
+
+The budget also shapes the maturation trajectory. Since [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]], the skill level is the middle tier where methodology patterns live while being refined. But if skill slots are scarce, some patterns stay instruction-encoded in the context file longer than understanding warrants -- not because they are not ready for skill encoding, but because the budget cannot accommodate them. Since [[self-extension requires context files to contain platform operations knowledge not just methodology]], this overflow increases the content burden on context files, which already carry platform operations knowledge alongside universal methodology. The budget constraint cascades: it limits skills, pushes methodology to instructions, inflates context files, and consumes the attention budget that instruction-encoded methodology depends on for compliance.
+
+---
+---
+
+Relevant Notes:
+- [[skills encode methodology so manual execution bypasses quality gates]] — establishes that skills ARE the methodology, which is why a budget that limits skill count constrains methodology itself, not just convenience
+- [[platform capability tiers determine which knowledge system features can be implemented]] — the tier framework this note concretizes: skill budgets are a first-tier constraint that second-tier platforms avoid by having fewer or no skills
+- [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]] — skill budgets are an automation-layer constraint that does not exist in the convention layer, reinforcing why layer awareness matters for generators
+- [[progressive disclosure means reading right not reading less]] — the vault's progressive disclosure philosophy (descriptions first, full content on demand) is exactly what skill descriptions implement, but under a hard character budget rather than soft context management
+- [[LLM attention degrades as context fills]] — skill descriptions consume context from the start of every session, reducing the effective smart zone available for actual work
+- [[the AgentSkills standard embodies progressive disclosure at the skill level]] — sibling: identifies the structural isomorphism between note and skill loading patterns, while this note identifies the hard constraint that governs the skill loading side
+- [[knowledge system architecture is parameterized by platform capabilities not fixed by methodology]] — the skill budget is one of the parameters: skill count and description length become generator inputs alongside hook availability and subagent support
+- [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]] — the budget constrains the middle tier of this trajectory: if skill slots are scarce, some methodology stays instruction-encoded longer than understanding warrants
+- [[complex systems evolve from simple working systems]] — the budget acts as an evolutionary pressure that enforces Gall's Law: you cannot start with twelve specialized skills, so the system must begin simple and split skills only when consolidation pain emerges
+- [[hook enforcement guarantees quality while instruction enforcement merely suggests it]] — budget overflow pushes methodology back to instruction encoding, which degrades enforcement from guarantee to suggestion, creating a quality ceiling tied to a resource constraint
+- [[self-extension requires context files to contain platform operations knowledge not just methodology]] — when skill budgets force consolidation, more methodology must live in the context file, increasing the content burden on context files and making platform operations knowledge even more critical
+- [[configuration dimensions interact so choices in one create pressure on others]] — skill budgets are a concrete instance of the automation cascade: limited skill slots constrain methodology encoding which cascades through schema density and processing intensity, illustrating how a constraint in one dimension creates pressure across others
+- [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]] — the module ceiling is a direct consequence of composability: independent modules multiply the description budget demand, creating pressure toward right-sized granularity
+- [[each module must be describable in one sentence under 200 characters or it does too many things]] — the description length constraint and the budget ceiling create a joint optimization: modules must be simple enough to describe briefly yet few enough to fit the total allocation
+- [[progressive schema validates only what active modules require not the full system schema]] — deactivation as budget management: progressive schema means removing a module from the active budget does not lose its schema, enabling reversible budget allocation
+- [[friction-driven module adoption prevents configuration debt by adding complexity only at pain points]] — operationalizes the budget constraint as a lifecycle protocol: the 500-char split threshold, 3-session deactivation window, and 15-20 module cap are not arbitrary heuristics but calibrated checkpoints that keep actual complexity aligned with demonstrated needs within the budget ceiling
+- [[hooks enable context window efficiency by delegating deterministic checks to external processes]] — a budget relief valve: operations delegated to hooks consume zero skill description budget, so promoting deterministic methodology from skills to hooks frees scarce slots for judgment-requiring workflows that cannot be externalized
+
+Topics:
+- [[agent-cognition]]

package/methodology/skills encode methodology so manual execution bypasses quality gates.md

@@ -0,0 +1,50 @@
+---
+description: Skills contain selectivity gates, verification steps, and phase boundaries that ad-hoc execution cannot replicate consistently
+kind: research
+topics: ["[[processing-workflows]]"]
+---
+
+# skills encode methodology so manual execution bypasses quality gates
+
+Skills are not convenience wrappers around common operations. They are the methodology itself, encoded in executable form. When a skill exists for a task and you choose to do it manually instead, you lose more than automation — you lose the quality gates that make the methodology work.
+
+Consider what a claim extraction skill actually contains: duplicate checking via semantic search before extraction, selectivity thresholds that prevent note proliferation, structured handoff formats that enable downstream phases. These aren't optional enhancements. They are the methodology. An agent who manually reads inbox content and creates notes might capture the general idea, but will miss the systematic checks that prevent the system from filling with redundant or low-quality content.
+
+The gap between "doing the thing" and "doing the thing correctly" is where quality gates live. Manual execution tends to skip verification steps when context is running low, omit duplicate checks when the answer seems obvious, and ignore phase boundaries when tasks feel simple enough to chain. Since [[structure without processing provides no value]], skills prevent the Lazy Cornell failure mode: an agent performing structural motions (moving files, adding wiki syntax, updating MOC lists) while skipping the generative work that creates value. Skills encode the processing, not just the structure. Since [[fresh context per task preserves quality better than chaining phases]], this last failure mode is particularly damaging — chaining phases in a single session means later phases run on degraded attention. Skills enforce these constraints regardless of how confident the agent feels. Since [[backward maintenance asks what would be different if written today]], the backward maintenance skill's mental model is itself a quality gate: without it, system maintenance degrades to mechanical link-adding that preserves form while missing substance. A concrete example: since [[maintenance targeting should prioritize mechanism and theory notes]], the skill encodes the insight that mechanism connection predicts higher reweave value than topic proximity — an agent using backward maintenance gets this targeting guidance, while manual revisitation likely follows topic proximity because it's easier to find.
+
+This is why the enforcement principle exists: if a skill exists for a task, use the skill. The alternative is not "the same work done differently" — it's "the methodology bypassed." The skill IS the methodology. Manual execution is a different methodology, one without the accumulated learning encoded in the skill's design. Skills also have a provenance story: since [[context files function as agent operating systems through self-referential self-extension]], the context file teaches the agent how to create skills, and those skills then encode the methodology the context file describes. The self-extension loop produces skills as its durable outputs -- each skill is a piece of methodology that graduated from instruction to executable form.
+
+The infrastructure itself demonstrates this principle. Since [[live index via periodic regeneration keeps discovery current]], index regeneration should be encoded in hooks or skills rather than run ad-hoc — the quality gate here is ensuring regeneration happens at the right moments without human memory. An agent who manually runs `rg "^description:"` gets the same data as a pre-computed index, but misses the guarantee that the index is current. The skill encodes the WHEN as well as the WHAT. But even skills require invocation, and since [[hook enforcement guarantees quality while instruction enforcement merely suggests it]], hooks provide an even deeper enforcement layer — one that fires regardless of whether the agent invokes anything at all. Skills and hooks form complementary enforcement: skills encode methodology workflows that must be deliberately invoked, hooks encode deterministic checks that fire automatically on events.
+
+But there is a shadow side. Since [[cognitive outsourcing risk in agent-operated systems]] tests whether delegating all processing to agents atrophies human meta-cognitive skills, skills create an ironic tension: they ensure quality by ensuring the human never practices the underlying skill. The enforcement principle that says "use the skill" may itself cause the human to lose the ability to do the work without the skill. This is testable — one of the experiment's pre-registered predictions tracks whether human "rubber-stamping" replaces genuine judgment. If skills work too well, the human approval role may become hollow.
+
+And there is a second shadow side: the rationalization trap. Since [[productivity porn risk in meta-system building]] tests whether building sophisticated workflows becomes procrastination disguised as work, the very argument that skills encode methodology (and therefore justify their complexity) could rationalize infinite building. The experiment makes this testable: if system complexity correlates with output velocity, skills justify themselves; if complexity grows while output stays flat, the accumulated learning justification is rationalization.
+
+Skills maintain consistent quality at volume by encoding selectivity gates that manual execution would skip under pressure. They also enforce session discipline ("one task, clean handoff") — defining what "one task" means and preventing scope creep that manual execution allows. And since [[intermediate packets enable assembly over creation]], skill handoff formats ARE packet specifications: the structured output that enables the next phase to assemble from this phase's work. Manual execution might complete the work but produce outputs that cannot be assembled from — the packet format is part of the methodology.
+
+The operational implication is simple: check whether a skill exists before improvising. When one does, use it. When one doesn't, consider whether the task warrants creating one. But this implication is platform-contingent. Since [[platform capability tiers determine which knowledge system features can be implemented]], the skill infrastructure itself only exists at tier one and partially at tier two. At tier three, there are no skills to invoke — the methodology exists only as instructions in a context file, and the quality gates that skills encode are absent entirely. This means the gap between manual and skill-encoded execution is not just a quality difference but a tier-availability difference: lower tiers face the bypass problem structurally, not by choice. Even at tier one, since [[skill context budgets constrain knowledge system complexity on agent platforms]], the number of skills a system can sustain is bounded by the platform's description budget -- a knowledge system cannot encode unlimited methodology as skills because the total description allocation caps active modules at roughly fifteen to twenty. Methodology that exceeds this ceiling falls back to instruction encoding in the context file, which means some quality gates remain aspirational even on platforms that support skills.
+
+Whether skills should encode combined operations or separated operations is testable. Since [[gardening cycle implements tend prune fertilize operations]] proposes three focused maintenance skills (tend/prune/fertilize) instead of combined backward maintenance, it tests whether operation-specific quality gates outperform holistic reconsideration gates. If validated, skills encoding methodology would mean THREE skills with focused gates, not one skill handling all maintenance operations.
+---
+
+Relevant Notes:
+- [[processing effort should follow retrieval demand]] — explains why selectivity gates matter
+- [[fresh context per task preserves quality better than chaining phases]] — explains WHY phase boundaries matter: chaining phases degrades attention quality
+- [[complex systems evolve from simple working systems]] — skills exemplify Gall's Law: the quality gates in extraction or connection-finding couldn't have been designed upfront, they evolved through use
+- [[bootstrapping principle enables self-improving systems]] — skills are concrete instances of bootstrapping: each improvement becomes available for building the next, which is why quality gates emerged through recursive use
+- [[the generation effect requires active transformation not just storage]] — explains WHAT quality gates are: the generative operations (duplicate checking, extraction, reflection) that produce new artifacts
+- [[good descriptions layer heuristic then mechanism then implication]] — example of an encoded quality gate: extraction and retrieval testing can enforce the layering formula consistently, while manual description writing skips it
+- [[gardening cycle implements tend prune fertilize operations]] — tests whether maintenance skills should separate operations (tend/prune/fertilize) or combine them (backward maintenance); if validated, skill design shifts from one skill per workflow to one skill per cognitive operation
+- [[cognitive outsourcing risk in agent-operated systems]] — tests the shadow side: skills ensure quality but may also ensure the human never practices, potentially atrophying meta-cognitive capability
+- [[maintenance targeting should prioritize mechanism and theory notes]] — concrete example of encoded methodology: targeting guidance that manual note revisitation would miss
+- [[structure without processing provides no value]] — the Lazy Cornell proof that skills prevent: structural motions without generative processing produce no measurable benefit
+- [[generation effect gate blocks processing without transformation]] — operationalizes this note's abstract principle: makes generation a hard prerequisite for inbox exit, preventing manual file movement from counting as processing
+- [[live index via periodic regeneration keeps discovery current]] — infrastructure example: index regeneration should be encoded in hooks/skills to ensure it happens at the right moments
+- [[intermediate packets enable assembly over creation]] — skill handoff formats ARE packet specifications; producing outputs that enable assembly is part of the encoded methodology
+- [[platform capability tiers determine which knowledge system features can be implemented]] — the tier framework reveals that the manual-vs-skill gap is not just a quality choice but a platform availability constraint: tier-three platforms have no skill infrastructure, making the bypass problem structural rather than behavioral
+- [[hook enforcement guarantees quality while instruction enforcement merely suggests it]] — the complementary enforcement layer: skills encode the what (methodology workflow), hooks enforce the when (automatic firing on events); a skill not invoked provides no gate, but a hook fires regardless of whether the agent remembers to invoke anything
+- [[context files function as agent operating systems through self-referential self-extension]] — provenance: skills are the encoded outputs of the self-extension loop; the context file teaches the agent to create skills, which then encode the methodology the context file describes, completing a specific arc of the documentation-to-skill trajectory
+- [[skill context budgets constrain knowledge system complexity on agent platforms]] — ceiling constraint: even at tier one, the description budget caps active skills at 15-20, so methodology that exceeds the budget falls back to instruction encoding with weaker enforcement
+
+Topics:
+- [[processing-workflows]]

package/methodology/small-world topology requires hubs and dense local links.md

@@ -0,0 +1,99 @@
+---
+description: Network science shows knowledge graphs need power-law distributions where MOCs have many links and atomic notes have few, creating short paths between any concepts
+kind: research
+topics: ["[[graph-structure]]"]
+---
+
+# small-world topology requires hubs and dense local links
+
+Network science research into small-world networks reveals a fundamental principle for knowledge graph architecture: efficient navigation requires power-law link distributions, not uniform connectivity.
+
+## The Small-World Insight
+
+Small-world networks share two properties:
+1. **High clustering** — nodes form dense local neighborhoods
+2. **Short path lengths** — any two nodes connect through surprisingly few hops
+
+These properties emerge from a specific topology: most nodes have few connections (dense local clusters), while a small number of hub nodes have many connections (creating shortcuts across the network).
+
+## Power-Law Distribution in Knowledge Graphs
+
+Sebastien Dubois's empirical analysis of 8,000 notes with 64,000 links provides concrete benchmarks for what healthy small-world topology looks like in practice. For a knowledge vault to function as a small-world network, link distribution must follow a power-law:
+
+**Hub nodes (MOCs):**
+- ~90 links on average
+- High betweenness centrality
+- Designed for navigation
+- Connect across topic boundaries
+
+**Peripheral nodes (atomic claims):**
+- 3-6 links on average
+- High clustering coefficient
+- Designed for specificity
+- Connect within local neighborhoods
+
+**Network average:** ~8 links per note
+
+This distribution creates the topology that enables both local coherence (dense clusters around related concepts) and global navigability (short paths between any concepts).
+
+## Architectural Implications
+
+**Quality gates from topology:**
+
+| Condition | Action |
+|-----------|--------|
+| Atomic note exceeds 15 links | Consider splitting or promoting to MOC |
+| Note has fewer than 3 links | Orphan risk — needs connection work |
+| MOC below 20 links | May need better scope or connection work |
+| Network average drifts from 8 | Rebalancing needed |
+
+The benchmarks aren't arbitrary preferences. They emerge from network science research into what topologies enable efficient traversal. A vault where every note has 8 links (uniform distribution) lacks both the local clustering and the global shortcuts that make small-world networks work. But threshold heuristics only catch obvious cases — since [[community detection algorithms can inform when MOCs should split or merge]], algorithmic approaches detect structural drift that simple count thresholds miss, like a MOC that covers two distinct communities even when its link count is below the split threshold. And since [[basic level categorization determines optimal MOC granularity]], the cognitive dimension matters alongside the topological one: a MOC might need restructuring not because it exceeded a link count but because the operator's understanding has deepened enough that the current granularity no longer matches the basic level for that domain.
+
+## Why This Matters for Agent Cognition
+
+When an LLM traverses a knowledge graph, path length directly impacts context window usage. Since [[LLM attention degrades as context fills]], shorter paths mean more of the traversal happens in the "smart zone" where reasoning is sharp. Small-world topology ensures:
+- **Few hops between concepts** — typically 2-4 links separate any ideas
+- **Natural entry points** — MOCs concentrate connectivity where navigation happens
+- **Local density** — related concepts cluster together without requiring hub traversal
+
+This also means direction changes are cheap. Since [[queries evolve during search so agents should checkpoint]], the short paths enabled by small-world topology mean agents can pivot to a different hub without expensive backtracking. But topological reachability is only half the story — since [[context phrase clarity determines how deep a navigation hierarchy can scale]], the hub's utility depends on whether agents can confidently choose which branch to descend into. A hub with clear context phrases sustains more tiers below it; a hub with bare links forces agents to scan broadly rather than commit to a branch, effectively flattening the hierarchy regardless of the topology. The structural efficiency compounds: not only are targets close, alternative targets are equally close.
+
+MOCs also solve a deeper problem than efficiency. Since [[navigational vertigo emerges in pure association systems without local hierarchy]], pure associative structures make semantic neighbors unreachable when no direct link exists. MOCs provide local hierarchy: even if two notes don't link to each other, both likely link to a shared MOC, creating a 2-hop path that pure association lacks. The hub isn't just a shortcut — it's sometimes the ONLY path.
+
+The hub role becomes even more critical in multi-domain systems. Since [[multi-domain systems compose through separate templates and shared graph]], shared entity MOCs — people, projects, or concepts that appear across domains — become the hubs that bridge domain-specific clusters. A person who features in project decisions, research collaborations, and relationship notes creates short paths across three otherwise separate domains. Without these bridging hubs, the multi-domain graph fragments into domain silos connected only by the weakest semantic links.
+
+The power-law distribution isn't about organizing files. It's about creating a topology that matches how spreading activation models traverse networks. Since [[retrieval utility should drive design over capture completeness]], the structural choice serves retrieval: short paths and hub-based navigation answer "how do I find this?" efficiently. And because [[each new note compounds value by creating traversal paths]], the topology determines HOW MUCH value compounds — small-world structure multiplies the reachability effect that creates compounding returns.
+
+## Clusters, Voids, and Bridges
+
+Beyond the hub-and-spoke topology, network science identifies three structural features that matter for knowledge graph health: clusters (dense local neighborhoods where related concepts reinforce each other), voids (sparse regions where expected connections are absent), and bridges (nodes that connect otherwise disconnected clusters). Clusters create local coherence — the dense neighborhoods where related concepts live. Voids reveal where the graph is thin, indicating either genuine gaps in understanding or missing connections between concepts that should relate. Bridges are the highest-value nodes structurally: removing a bridge disconnects parts of the graph, while removing a cluster member only weakens local density. This framework extends the hub/peripheral distinction by identifying WHY certain connections matter more than others — a bridge between two clusters carries more structural weight than a tenth link within an already-dense cluster.
+
+## Uncertainty
+
+The general principles (power-law distribution, hubs as shortcuts) derive from network science research on small-world networks. The specific benchmarks (90 for hubs, 3-6 for atomic, 8 average) come from Dubois's empirical analysis of his own vault at scale — 8,000 notes over years of practice. Whether these numbers transfer to other vaults depends on domain, note granularity, and workflow. The principles are well-established; the specific thresholds are validated in at least one large vault but may vary across contexts.
+
+What we don't know: whether these benchmarks hold for vault sizes under 100 notes, or whether the topology only becomes necessary at larger scales. A vault with 50 notes might work fine with uniform link distribution. The architectural value of small-world topology scales with vault size.
+
+A further uncertainty: does power-law link distribution create a parallel power-law in maintenance attention? If hubs get traversed constantly while peripheral notes rarely appear in agent context, the bottom 80% of notes may accumulate neglect regardless of need. [[random note resurfacing prevents write-only memory]] tests whether random selection counteracts this structural bias.
+---
+
+Relevant Notes:
+- [[wiki links implement GraphRAG without the infrastructure]] — provides foundation for why graph structure matters
+- [[spreading activation models how agents should traverse]] — explains traversal mechanism this topology enables
+- [[queries evolve during search so agents should checkpoint]] — benefits from small-world topology because direction changes traverse short paths too
+- [[dangling links reveal which notes want to exist]] — explains how hub topology emerges organically: high-frequency dangling links predict which notes will become hubs
+- [[throughput matters more than accumulation]] — topology grounds the density over volume claim: it's connectivity not size that enables serendipity
+- [[each new note compounds value by creating traversal paths]] — explains WHY small-world topology matters economically: the topology multiplies how much each note increases graph value
+- [[LLM attention degrades as context fills]] — grounds why path length matters cognitively: shorter traversals stay in the smart zone where reasoning is sharp
+- [[random note resurfacing prevents write-only memory]] — tests whether the power-law link distribution creates a parallel power-law in maintenance attention, leaving peripheral notes neglected
+- [[retrieval utility should drive design over capture completeness]] — the design orientation topology serves: small-world structure exists to answer how do I find this efficiently, not to organize files
+- [[navigational vertigo emerges in pure association systems without local hierarchy]] — the failure mode this topology prevents: without hubs providing local hierarchy, semantic neighbors become unreachable
+- [[cross-links between MOC territories indicate creative leaps and integration depth]] — explains one mechanism for hub emergence: notes that bridge multiple MOC territories become structural shortcuts
+- [[community detection algorithms can inform when MOCs should split or merge]] — algorithmic maintenance: detects when the power-law topology has drifted from healthy distribution, providing empirical signals that go beyond threshold heuristics for structural reorganization
+- [[basic level categorization determines optimal MOC granularity]] — cognitive complement to topological thresholds: link-count heuristics (20 minimum, 50 split threshold) capture the volume dimension, but Rosch's basic level theory adds the expertise dimension; a MOC might need splitting at 25 notes if understanding has deepened enough that the basic level has shifted downward
+- [[configuration dimensions interact so choices in one create pressure on others]] — the topological requirement for hubs and dense links is not intrinsic but forced by the granularity cascade: atomic notes create the volume and fragmentation that demand small-world topology as compensation
+- [[multi-domain systems compose through separate templates and shared graph]] — cross-domain hub role: shared entity MOCs become the hubs that bridge domain-specific clusters, creating the short paths that maintain graph navigability across domain boundaries
+- [[context phrase clarity determines how deep a navigation hierarchy can scale]] — quality condition on hub depth: hub nodes can sustain multi-tier hierarchies only when context phrases at each level enable confident branch commitment; topology determines reachability but label clarity determines navigability
+
+Topics:
+- [[graph-structure]]

package/methodology/source attribution enables tracing claims to foundations.md

@@ -0,0 +1,38 @@
+---
+description: Distinguishes original thinking from consumed ideas, creating a verification graph where any claim can follow its evidence chain backward
+kind: research
+topics: ["[[note-design]]"]
+---
+
+# source attribution enables tracing claims to foundations
+
+Knowledge work builds on sources. Without attribution, the boundary between what you discovered and what you consumed becomes invisible. Attribution creates a parallel graph alongside the wiki link network: since [[wiki links implement GraphRAG without the infrastructure]], wiki links handle conceptual relationships between ideas, while attribution handles provenance — where those ideas came from. The two graphs serve different traversal needs and both matter.
+
+The question "where did this idea come from?" has a different answer than "what ideas connect to this?" A claim might connect to five other claims conceptually while originating from a single source. Both relationships matter, but they serve different purposes. Wiki links enable traversal for synthesis. Attribution enables verification and intellectual honesty.
+
+In this vault, source attribution operates at multiple levels. Notably, since [[inline links carry richer relationship data than metadata fields]], attribution is one of the few cases where metadata fields (the Source footer, YAML provenance) work better than inline links — because provenance is a structural property of the note itself, not a relationship to be argued in prose.
+
+**Thinking notes** carry a Source footer pointing to the reduce task archive where the original material lives. A claim about "atomic notes forcing clear thinking" traces back to the specific research document that sparked it.
+
+**Task files** track the `source_task` field, linking each extracted claim to its reduce batch. The batch links to the source document. This creates a chain: claim note → task file → batch → source.
+
+**YAML provenance fields** (`methodology`, `adapted_from`) distinguish between applying an existing pattern, adapting a human pattern for agents, and inventing something new. These answer "what tradition does this come from?" rather than "what document does this come from?"
+
+The practical value emerges when claims conflict or need verification. If two notes contradict, tracing both to their sources reveals whether the contradiction exists in the source material or emerged during extraction. If a claim feels questionable, the source path shows what evidence supports it.
+
+Attribution also enables meta-analysis: what percentage of vault claims come from Zettelkasten research versus original invention? Which sources produced the most extractable insights? These questions become answerable because the provenance graph exists. At a deeper level, since [[dense interlinked research claims enable derivation while sparse references only enable templating]], methodology provenance is one of four structural prerequisites that make derivation possible. Without attribution infrastructure, a derivation agent cannot distinguish which claims apply to which traditions — it treats all claims as equally applicable everywhere, collapsing the very specificity that makes derivation more powerful than templating.
+
+The provenance principle extends beyond individual claims to system architecture itself. Since [[justification chains enable forward backward and evolution reasoning about configuration decisions]], every configuration choice in a derived knowledge system traces back to the research claims and user constraints that produced it. This is source attribution applied at the system level: where note-level provenance answers "where did this claim come from?", justification chains answer "why is the system configured this way?" The tracing direction is the same (from output to rationale), the value proposition is the same (verification and intelligent evolution), and the failure mode when absent is the same (opaque systems that resist modification because nobody remembers why they were built that way).
+
+The cost is small — a footer line and some YAML fields at the note level, structured chain output at the derivation level. The benefit compounds as the system grows, because every new claim that links to sources strengthens the verification graph, and every justified configuration decision strengthens the evolution graph.
+---
+
+Relevant Notes:
+- [[wiki links implement GraphRAG without the infrastructure]] — wiki links handle conceptual relationships, attribution handles provenance
+- [[inline links carry richer relationship data than metadata fields]] — attribution is one of the few cases where metadata fields (Source footer) work better than inline links
+- [[justification chains enable forward backward and evolution reasoning about configuration decisions]] — extends the provenance principle to system architecture: justification chains are source attribution applied at the configuration level, enabling the same backward tracing and evolution capability for derivation decisions that provenance creates for individual claims
+- [[dense interlinked research claims enable derivation while sparse references only enable templating]] — identifies methodology provenance as one of four structural prerequisites for derivation: without attribution infrastructure, the derivation agent treats all claims as equally applicable everywhere
+- [[provenance tracks where beliefs come from]] — complements documentary provenance with epistemic provenance: this note tracks which source said it, that note tracks how the agent came to believe it (observed, prompted, inherited)
+
+Topics:
+- [[note-design]]

package/methodology/spaced repetition scheduling could optimize vault maintenance.md

@@ -0,0 +1,44 @@
+---
+description: Maintenance intervals adapted to note age and maturity could catch early issues while avoiding overhead on stable evergreen notes
+kind: research
+topics: ["[[maintenance-patterns]]"]
+source: TFT research corpus (00_inbox/heinrich/)
+---
+
+# spaced repetition scheduling could optimize vault maintenance
+
+Vault maintenance would be more effective if review intervals adapted to note age and maturity. Newly created notes need frequent verification (daily-weekly), while mature notes need occasional review (monthly-quarterly). A scheduling algorithm assigning intervals based on note characteristics would allocate maintenance bandwidth more efficiently than uniform thresholds (all notes get 30-day checks) or random selection (all notes have equal probability regardless of need).
+
+The Ebbinghaus forgetting curve provides the scientific basis: retention drops exponentially without reinforcement, with steeper curves for new memories. For vault maintenance, this translates to: new notes are more likely to have issues (weak descriptions, missing connections, unclear claims) than notes that survived multiple reviews. Since [[temporal separation of capture and processing preserves context freshness]], processing should happen soon after capture. But post-capture verification needs its own rhythm — and since [[LLM attention degrades as context fills]], scheduling frequent short reviews while attention is fresh beats infrequent comprehensive reviews that strain later sessions.
+
+Current approaches have blind spots:
+- Staleness detection uses uniform thresholds (30+ days not modified) — treats fresh seedlings and battle-tested evergreens identically
+- Health checks run on demand without scheduling — issues accumulate until someone triggers a check
+- Since [[random note resurfacing prevents write-only memory]] tests uniform probability selection — every note equally likely regardless of need
+
+Spaced repetition scheduling would assign intervals dynamically:
+- Newly created notes: 7 days after creation (catch early issues)
+- Notes that passed first review: 21 days
+- Notes that passed multiple reviews: 60 days
+- Mature evergreen notes: 180 days
+- Notes flagged with issues: return to short intervals until fixed
+
+This mirrors how since [[maturity field enables agent context prioritization]] proposes seedling/developing/evergreen status, but applies it to scheduling rather than filtering. There is a second scheduling dimension beyond maturity: since [[MOC maintenance investment compounds because orientation savings multiply across every future session]], hub MOCs that load every session have the highest temporal multiplier on any maintenance investment — a context phrase improved on a hub MOC saves orientation time across far more sessions than the same improvement on a peripheral topic note. Scheduling should therefore weight not just note maturity but session-load frequency, front-loading maintenance attention on high-traffic navigation nodes. The implementation mechanism is [[programmable notes could enable property-triggered workflows]] — the note's `last-reviewed` property determines its next review date; a scheduler queries notes meeting conditions and surfaces them for attention.
+---
+
+Relevant Notes:
+- [[random note resurfacing prevents write-only memory]] — tests uniform probability selection; interval-based scheduling is an alternative allocation strategy
+- [[maturity field enables agent context prioritization]] — maturity status (seedling/evergreen) relates to scheduling intervals; mature notes need less frequent review
+- [[temporal separation of capture and processing preserves context freshness]] — the Ebbinghaus forgetting curve that motivates spaced repetition also motivates quick-after-capture processing
+- [[processing effort should follow retrieval demand]] — scheduling adds a proactive dimension to the demand-following principle; some effort should anticipate need rather than respond to it
+- [[gardening cycle implements tend prune fertilize operations]] — scheduling operationalizes the temporal aspect of gardening; tend cycles need rhythm
+- [[backward maintenance asks what would be different if written today]] — defines WHAT maintenance should accomplish (holistic reconsideration); scheduling addresses WHEN that reconsideration happens
+- [[LLM attention degrades as context fills]] — cognitive grounding for front-loaded scheduling: frequent early reviews while attention is fresh beat comprehensive later reviews that strain degraded context
+- [[PKM failure follows a predictable cycle]] — if the cascade is predictable, scheduling can front-load attention on early-stage indicators (inbox overflow, velocity gaps) before they trigger downstream failures
+- [[continuous small-batch processing eliminates review dread]] — alternative maintenance timing approach: interval scheduling vs continuous flow (small-batch); both address WHEN processing happens but use different mechanisms
+- [[temporal processing priority creates age-based inbox urgency]] — sibling application of Ebbinghaus decay: this note applies age-based scheduling to maintenance intervals, that note applies it to inbox processing priority; same cognitive science foundation targeting different domains
+- [[maintenance scheduling frequency should match consequence speed not detection capability]] — complementary scheduling dimension: spaced repetition schedules note-level review based on maturity, consequence speed schedules problem-class detection based on propagation rate; both address WHEN but along orthogonal axes
+- [[MOC maintenance investment compounds because orientation savings multiply across every future session]] — adds target-selection to the scheduling question: hub MOCs that load every session have the highest temporal multiplier on maintenance investment, so scheduling should weight review frequency not just by note maturity but by session-load frequency
+
+Topics:
+- [[maintenance-patterns]]

package/methodology/spreading activation models how agents should traverse.md

@@ -0,0 +1,79 @@
+---
+description: Memory retrieval in brains works through spreading activation where neighbors prime each other. Wiki link traversal replicates this, making backlinks function as primes that surface relevant contexts
+kind: research
+topics: ["[[agent-cognition]]"]
+---
+
+# spreading activation models how agents should traverse
+
+## The Activation Model
+
+Graph traversal IS spreading activation. When you follow wiki links to load context, you're replicating what the brain does when priming related concepts. The activation spreads from the starting node through connected nodes, decaying with distance. Since [[wiki links implement GraphRAG without the infrastructure]], every link you traverse is a curated edge, not a statistical correlation, which means the activation spreads through high-signal paths.
+
+This isn't just analogy — it's the same computational pattern. Discovery layers (file tree → descriptions → outline → section → full content) implement spreading activation in practice. Each step loads more context with higher cost. High decay traversal stops at the description. Low decay traversal reads full files. The progressive disclosure framework IS decay-based context loading. Since [[structure enables navigation without reading everything]], these four structural mechanisms — wiki links, MOCs, claim titles, and YAML descriptions — compose into the discovery layer stack that makes this decay-based traversal possible in the first place.
+
+Since [[descriptions are retrieval filters not summaries]], the description layer serves a specific function: enabling agents to decide whether to load full content. This maps to information-theoretic filtering — lossy compression that preserves decision-relevant features. The description answers "should I read this?" not "what does this say?" Since [[metadata reduces entropy enabling precision over recall]], aggregating descriptions creates a pre-computed low-entropy representation that shrinks the search space before content loads, enabling efficient high-decay traversal.
+
+Cognitive science mapped how memory retrieval works: activate a concept, neighboring concepts receive activation proportional to connection strength, activation decays with each hop. The key insight for agents: backlinks function as primes. When you visit a note, its backlinks show every context where this concept was previously useful. Since [[backlinks implicitly define notes by revealing usage context]], the backlinks don't just show WHERE a concept was used — they reveal WHAT the concept means in practice, extending its definition beyond the author's original intent. Since [[wiki links implement GraphRAG without the infrastructure]], notes function as APIs — the title is the function signature, the body is the implementation, and following a link is a function call. Each API invocation spreads activation to the referenced concept. And because [[inline links carry richer relationship data than metadata fields]], the prose surrounding each link encodes the relationship TYPE — "since X, therefore Y" carries more activation signal than a bare reference. The link type annotation tells the traverser whether to follow: a causal connection warrants deeper traversal than a mere association.
+
+This aligns with distributed cognition theory: cognition is not confined to the brain but extends into tools and environments. A vault with wiki links acts as an exocortex, holding associative pathways that any agent (biological or artificial) can traverse. Following links IS spreading activation through an external thinking structure. And because [[knowledge systems become communication partners through complexity and memory humans cannot sustain]], this traversal isn't just retrieval — it's dialogue with a system that holds complexity the agent couldn't sustain alone. The vault surprises its operators by surfacing connections they made but forgot, which means spreading activation isn't just loading context but communicating with an external partner. And since [[AI shifts knowledge systems from externalizing memory to externalizing attention]], spreading activation is better understood as an attention allocation mechanism than a memory retrieval one. The decay parameter does not decide what to remember — it decides what to attend to. High decay focuses attention narrowly; low decay spreads attention broadly. The system is not recalling stored knowledge so much as directing finite attention through the graph, deciding which nodes deserve the agent's limited cognitive bandwidth.
+
+## Implementation Parameters
+
+Traversal requires tuning:
+- **Decay rate**: how quickly activation fades per hop (high decay = focused retrieval, low decay = exploratory)
+- **Threshold**: minimum activation to follow a link (prevents traversing everything)
+- **Max depth**: hard limit on traversal distance — since [[LLM attention degrades as context fills]], depth limits aren't just about token counts but about where the "smart zone" ends
+
+The insight changes how agents should navigate. Focused retrieval (answering a specific question) wants high decay — go deep on the most relevant path. Exploratory synthesis (finding connections) wants low decay — spread wider to discover non-obvious relationships. Both modes serve the same underlying principle: since [[retrieval utility should drive design over capture completeness]], the traversal mechanism exists to answer "how do I find what I need?" not "where did I file this?" The exploratory mode is where [[controlled disorder engineers serendipity through semantic rather than topical linking]] — low-decay traversal through semantic cross-links encounters unexpected neighbors that topical filing would segregate, and these surprises are precisely the discovery mechanism that Luhmann identified as the source of productive insight. The agent following a link from "context window constraints" to "spaced repetition scheduling" didn't search for that connection — the graph's semantic linking surfaced it because the connecting link passed a judgment test even though the topics diverge.
+
+But decay and threshold only address WHICH nodes to visit next. They don't address when the search itself should change direction. Since [[queries evolve during search so agents should checkpoint]], agents need explicit reassessment points during traversal. The berrypicking model shows that understanding what you're looking for changes as you find things. Spreading activation says follow strong links with decay. Checkpointing says pause periodically to ask: am I still looking for the right thing?
+
+## Integration with Traversal Architecture
+
+Together with the other foundational claims, this forms a complete traversal architecture. Wiki links provide the graph structure (WHAT to traverse). Spreading activation provides the loading mechanism (HOW to traverse). Small-world topology provides the efficiency guarantees (WHY the structure works). Checkpointing provides the reassessment protocol (WHEN to change direction). Each pillar answers a different question about agent cognition.
+
+But spreading activation operates on an existing graph — it discovers connections that wiki links have already encoded. The question is whether some connections only become visible during the extraction process itself, before links exist. Since [[incremental reading enables cross-source connection finding]], forced context collision during interleaved processing may surface relationships that sequential extraction followed by spreading-activation-based reflect would miss. Spreading activation is powerful once the graph exists; incremental reading proposes that graph construction itself could be serendipity-generating.
+
+Since [[dual-coding with visual elements could enhance agent traversal]], there may be a parallel activation network operating through visual representations rather than textual links. If Mermaid diagrams or relationship graphs activate related concepts through spatial proximity and visual grouping, this would provide modal redundancy: when the textual path fails (agent doesn't recognize a connection), the visual path might succeed. This remains a research direction rather than validated architecture.
+
+This also explains why MOCs work as navigation hubs. They're high-activation nodes that prime many related concepts simultaneously. Starting from a MOC spreads activation across an entire topic area, which is exactly what you want when exploring unfamiliar territory. But activation alone cannot tell you which starting node to activate first or which activation pattern proved productive in prior sessions — this is where [[agent notes externalize navigation intuition that search cannot discover and traversal cannot reconstruct]], capturing the strategic layer (start here, combine these, skip that) that guides activation before it begins spreading.
+
+The efficiency of spreading activation depends on network structure. Because [[small-world topology requires hubs and dense local links]], most concept pairs connect through surprisingly few hops. High clustering creates local coherence (related concepts near each other), while hub nodes (MOCs) create shortcuts across the network. This topology ensures spreading activation reaches relevant nodes quickly without flooding the context window. And because [[betweenness centrality identifies bridge notes connecting disparate knowledge domains]], we can quantify which specific nodes activation preferentially flows through — high-betweenness nodes are the natural waypoints that agents encounter repeatedly during diverse traversals, regardless of starting point.
+
+A further refinement comes from research on memory-augmented agents. BudgetMem introduces a trained neural router that dynamically selects extraction depth based on query characteristics — not all retrievals deserve the same traversal investment. The router learns three tiering strategies: shallow extraction for simple lookups, medium for contextual queries, and deep for synthesis tasks. This suggests that the decay parameter in spreading activation should not be fixed but query-dependent: the same graph traversed for a factual check (high decay, shallow) versus a synthesis search (low decay, deep) should use different activation profiles. The vault's current implementation approximates this through skill-specific search mode selection (BM25 for /seed, vsearch for /reduce, full query for /reflect), but a learned router could optimize this further as the graph scales.
+
+But spreading activation has a blind spot. Since [[navigational vertigo emerges in pure association systems without local hierarchy]], activation can only spread through existing links. Semantic neighbors that lack explicit connections remain invisible — they're close in meaning but distant (or unreachable) in graph space. This is why MOCs matter not just for efficiency but for completeness: they provide local hierarchy that surfaces content spreading activation alone would miss.
+---
+
+Relevant Notes:
+- [[progressive disclosure means reading right not reading less]] — applies spreading activation to argue that disclosure layers enable curation for quality, not efficiency for token savings
+- [[structure enables navigation without reading everything]] — synthesis: composes the four structural mechanisms (wiki links, MOCs, claim titles, descriptions) into the discovery layer stack that spreading activation traverses; the structural substrate that makes decay-based context loading operational
+- [[wiki links implement GraphRAG without the infrastructure]] — provides the graph structure; also develops the notes as APIs metaphor where link traversal is function invocation
+- [[inline links carry richer relationship data than metadata fields]] — extends the API metaphor: inline links are TYPED function calls where prose provides the type annotation that guides traversal decisions
+- [[backlinks implicitly define notes by revealing usage context]] — explains WHY backlinks function as primes: they reveal not just where a concept was used but what it means in practice across the graph
+- [[small-world topology requires hubs and dense local links]] — explains the structural basis for why few hops suffice
+- [[queries evolve during search so agents should checkpoint]] — adds the temporal dimension: when to reassess search direction during traversal
+- [[dangling links reveal which notes want to exist]] — shows how high-frequency placeholder links predict which notes will enter the graph as high-activation hubs
+- [[processing effort should follow retrieval demand]] — traversal frequency creates the demand signal that determines where processing investment should flow
+- [[descriptions are retrieval filters not summaries]] — explains the information-theoretic basis for why descriptions enable high-decay traversal: lossy compression preserving decision-relevant features
+- [[good descriptions layer heuristic then mechanism then implication]] — operationalizes decay levels within descriptions: high-decay stops at heuristic, medium at mechanism, low at implication
+- [[throughput matters more than accumulation]] — traversal frequency reveals what actually gets used, providing objective throughput metrics
+- [[each new note compounds value by creating traversal paths]] — explains what spreading activation moves through: compounding creates the path network, this note explains how to traverse it
+- [[LLM attention degrades as context fills]] — grounds the max depth parameter: depth limits not because of tokens but because attention quality degrades beyond the smart zone
+- [[trails transform ephemeral navigation into persistent artifacts]] — proposes caching successful activation paths across sessions as named trails
+- [[maintenance targeting should prioritize mechanism and theory notes]] — applies spreading activation to reweave: for experiments, mechanism connection should guide where activation spreads rather than topic proximity
+- [[retrieval utility should drive design over capture completeness]] — the design orientation spreading activation serves: traversal answers how do I find this not where did I file it
+- [[dual-coding with visual elements could enhance agent traversal]] — proposes visual representations as a parallel activation network operating alongside textual wiki links
+- [[incremental reading enables cross-source connection finding]] — addresses discovery at a different stage: spreading activation traverses existing connections; incremental reading discovers connections during extraction, before links exist
+- [[mnemonic medium embeds verification into navigation]] — proposes using link context phrases as verification prompts that activation encounters during traversal, making verification ambient rather than a separate phase
+- [[knowledge systems become communication partners through complexity and memory humans cannot sustain]] — the partnership thesis: traversal isn't just retrieval but dialogue with a system that holds complexity agents couldn't sustain alone
+- [[navigational vertigo emerges in pure association systems without local hierarchy]] — the blind spot: activation only spreads through existing links, so semantic neighbors without link paths remain invisible regardless of decay tuning
+- [[notes function as cognitive anchors that stabilize attention during complex tasks]] — explains WHY traversal through notes stabilizes reasoning: each note is an anchor that prevents mental model collapse, so link-following is not just information loading but cognitive stabilization
+- [[AI shifts knowledge systems from externalizing memory to externalizing attention]] — reframes: spreading activation is better understood as attention allocation than memory retrieval; decay parameters decide what to attend to, not what to remember
+- [[betweenness centrality identifies bridge notes connecting disparate knowledge domains]] — quantifies which nodes activation preferentially flows through: high-betweenness nodes sit on the most shortest paths, making them natural waypoints that agents encounter repeatedly during diverse traversals
+- [[controlled disorder engineers serendipity through semantic rather than topical linking]] — explains what low-decay exploratory traversal encounters: semantic cross-links create unexpected neighbors that topical filing would segregate, and these surprising adjacencies are the discovery mechanism that makes exploratory mode productive
+- [[agent notes externalize navigation intuition that search cannot discover and traversal cannot reconstruct]] — the strategic layer above activation: spreading activation determines which nodes to visit next, but agent notes capture which starting points and activation patterns proved productive in prior sessions, providing meta-guidance that the mechanism itself cannot generate
+
+Topics:
+- [[agent-cognition]]

package/methodology/stale navigation actively misleads because agents trust curated maps completely.md

@@ -0,0 +1,43 @@
+---
+description: A stale MOC is worse than no MOC because agents fall back to search (current content) without one, but trust an outdated map without verifying it — and they have no mechanism to suspect staleness
+kind: research
+topics: ["[[maintenance-patterns]]", "[[agent-cognition]]"]
+methodology: ["Original"]
+source: [[2026-02-08-moc-architecture-hierarchy-blueprint]]
+---
+
+# stale navigation actively misleads because agents trust curated maps completely
+
+A missing map and a wrong map produce fundamentally different failures. When no MOC exists for a topic, agents experience [[navigational vertigo emerges in pure association systems without local hierarchy]] — disorientation, but with a natural fallback. The agent searches, follows links, queries semantically. These mechanisms access current content because they operate on the live graph. The absence of curation is uncomfortable but not deceptive.
+
+A stale MOC is deceptive. It presents an outdated view of the topic as though it were current, and the agent has no mechanism to suspect otherwise. Humans retain some cross-session memory that might trigger doubt — "I remember writing something about this last week, but the MOC doesn't mention it." Agents have zero such intuition. Each session loads the MOC, treats its contents as the authoritative map of the territory, and navigates accordingly. Notes that were created after the MOC was last updated are invisible not because they are hard to find, but because the agent never looks for them. The curated map satisfies the navigation need, so no further search occurs.
+
+This is why since [[metacognitive confidence can diverge from retrieval capability]], the staleness problem is specifically dangerous for agents. The confidence-capability gap widens silently: the MOC looks complete, passes structural checks, has context phrases and proper formatting. Nothing about the MOC itself signals that it is missing recent content. The divergence between what the map shows and what the territory contains grows with every note added to the topic that does not trigger a MOC update.
+
+The asymmetry cuts deeper than "outdated information." Because [[MOCs are attention management devices not just organizational tools]], a stale MOC does not merely misinform — it misallocates the agent's finite context budget. The agent loads the MOC trusting it to front-load orientation, spends tokens absorbing yesterday's synthesis, and then reasons within a frame that excludes recent work. A stale MOC actively shapes which notes get loaded into context, which connections get considered, and which synthesis opportunities surface. Since [[wiki links create navigation paths that shape retrieval]], the links within a stale MOC create retrieval paths through yesterday's topology while today's topology has moved on. The agent reasons with incomplete context and produces conclusions that miss recent work — and nothing in the output reveals the gap. The conclusions look well-reasoned because the context that was loaded was internally consistent. It was just incomplete.
+
+The remedy has two layers. First, since [[backward maintenance asks what would be different if written today]], applying that reconsideration mental model to MOCs catches drift before it compounds — the question "if I wrote this MOC today, what would be different?" is precisely the backward maintenance question scoped to navigation. Second, algorithmic detection: since [[community detection algorithms can inform when MOCs should split or merge]], tracking when actual graph communities diverge from MOC boundaries provides empirical signals that a map has gone stale. These two layers map onto judgment and automation respectively. The backward pass requires semantic understanding of whether the MOC still represents the topic accurately. The algorithmic pass requires only structural comparison — since [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]], the reconciliation pattern can detect MOC coverage gaps mechanically (are all notes in the topic linked from the MOC?) without needing to evaluate whether the MOC's synthesis still holds. Both layers matter because the problem is self-concealing — you cannot rely on the agent to notice what it cannot see.
+
+The risk compounds with scale. Since [[navigation infrastructure passes through distinct scaling regimes that require qualitative strategy shifts]], at larger scales MOC territories grow larger and take longer to audit. A stale MOC covering 15 notes might miss one recent addition — inconvenient but recoverable. A stale MOC covering 45 notes might miss an entire sub-cluster that emerged since the last update — a structural blind spot that shapes all reasoning within the topic. And because [[MOC construction forces synthesis that automated generation from metadata cannot replicate]], the synthesis invested in constructing a MOC is wasted when the MOC goes stale. The Dump-Lump-Jump process produced genuine insight, but that insight reflected last month's graph. Today's graph has moved on, and the synthesis no longer captures what matters.
+
+The generalizable principle extends beyond this vault: any curated navigation layer in an agent system carries this vulnerability. Curated indices, recommended reading lists, onboarding guides — anything an agent trusts as authoritative without independent verification becomes a liability when it falls behind the content it maps. The stronger the agent's trust in the curation, the worse the failure when the curation is stale.
+
+---
+---
+
+Relevant Notes:
+- [[navigational vertigo emerges in pure association systems without local hierarchy]] — the complementary failure mode: vertigo is the absence of navigation, this note is about the presence of WRONG navigation; together they bracket the space of navigation failure
+- [[metacognitive confidence can diverge from retrieval capability]] — the general pattern this instantiates: stale MOCs produce exactly the organizational false confidence where structure appears sound while actual retrieval fails
+- [[community detection algorithms can inform when MOCs should split or merge]] — the detection mechanism: algorithmic drift detection can catch stale boundaries before agents are misled, making the staleness problem empirically tractable
+- [[wiki links create navigation paths that shape retrieval]] — the mechanism that makes staleness dangerous: if links shape retrieval, then stale links shape retrieval toward outdated topology
+- [[backward maintenance asks what would be different if written today]] — the remedy: the reconsideration mental model applied to MOCs catches drift before it compounds by asking whether the map still matches the territory
+- [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] — enables detection: the reconciliation pattern formalizes MOC staleness detection by declaring desired state (all notes in MOCs) and measuring divergence periodically
+- [[MOCs are attention management devices not just organizational tools]] — deepens the stakes: stale MOCs don't just misinform navigation but misallocate the context budget by loading outdated orientation that wastes tokens on reconstruction of yesterday's understanding
+- [[navigation infrastructure passes through distinct scaling regimes that require qualitative strategy shifts]] — extends: staleness risk compounds with scale because larger topic territories take longer to audit and drift goes undetected longer
+- [[MOC construction forces synthesis that automated generation from metadata cannot replicate]] — sibling: if constructing MOCs requires genuine synthesis, stale MOCs waste that synthesis investment and guide reasoning based on yesterday's synthesis rather than today's understanding
+- [[context phrase clarity determines how deep a navigation hierarchy can scale]] — sibling: stale context phrases are doubly deceptive because the clarity that originally enabled confident branch commitment now enables confident WRONG commitment — the phrase is still convincing even when the relationship it describes no longer reflects the current graph
+- [[complete navigation requires four complementary types that no single mechanism provides]] — sibling: the four-type framework gives vocabulary for where staleness strikes: global navigation changes rarely so staleness is infrequent, but local and contextual navigation change with every batch and every note, making those types the primary staleness vectors
+
+Topics:
+- [[maintenance-patterns]]
+- [[agent-cognition]]

package/methodology/stigmergy coordinates agents through environmental traces without direct communication.md

@@ -0,0 +1,62 @@
+---
+description: Termites build nests by responding to structure not each other, and agent swarms work the same way — wiki links, MOCs, and queue state are pheromone traces guiding the next agent without messaging
+kind: research
+topics: ["[[agent-cognition]]", "[[graph-structure]]"]
+methodology: ["Systems Theory", "Digital Gardening"]
+source: [[tft-research-part3]]
+---
+
+# stigmergy coordinates agents through environmental traces without direct communication
+
+Termites build cathedrals without architects. No termite knows the plan. Each one responds to local conditions — the shape of existing structure, the concentration of chemical traces left by other termites — and adds to the structure accordingly. The result is coordination without communication, complexity without central control. Pierre-Paul Grassé named this mechanism stigmergy in 1959: the environment mediates between agents, and the traces left by one agent's work become the stimulus for the next agent's action.
+
+This is exactly how agent-operated knowledge systems coordinate. When one agent writes a thinking note, adds wiki links, updates a MOC, and advances the work queue, those modifications to the vault environment become the stimulus for the next agent. The next agent doesn't receive a message from the first — it reads the environment. The note exists in `01_thinking/`. The MOC lists it under Core Ideas. The queue entry shows `current_phase: "reflect"`. These are pheromone traces. The second agent responds to the structure, not to a directive. And because [[cognitive offloading is the architectural foundation for vault design]], this is not a workaround for agents lacking persistent memory — it is the natural expression of offloading coordination state to the environment, the same architectural pattern that justifies externalizing working memory to files, now applied to inter-agent coordination. The traces split into two distinct classes: since [[operational memory and knowledge memory serve different functions in agent architecture]], queue state and task files are operational stigmergy with temporal value (they coordinate work and expire when processing completes), while wiki links and MOC updates are knowledge stigmergy with compounding value (they build understanding that deepens with every new connection).
+
+The analogy is precise, not metaphorical. Wikipedia coordinates thousands of editors through stigmergy — the article itself is the coordination medium. No editor messages every other editor before making a change. They read the current state, modify it, and leave. The talk page and edit history are environmental traces that inform subsequent editors. Ward Cunningham's wiki design embedded stigmergic coordination into the medium itself — and his distinction between ThreadMode and DocumentMode names a specific transition in stigmergic quality: since [[ThreadMode to DocumentMode transformation is the core value creation step]], raw stigmergic deposits (chronological contributions without coordination) must be synthesized into timeless documents, and this transformation is what turns trace accumulation into genuine knowledge. Since [[federated wiki pattern enables multi-agent divergence as feature not bug]], federation extends this further: agents leave parallel traces rather than forcing convergence, and the divergent traces themselves become navigable structure for future agents.
+
+What makes stigmergy powerful for agent systems is that it solves the coordination problem without requiring persistent identity or direct messaging. Since [[session handoff creates continuity without persistent memory]], each agent session is ephemeral — it exists, acts, and disappears. But the environmental traces persist. Task files accumulate notes from each phase. Queue entries track state. Wiki links weave the knowledge graph tighter. The vault remembers what no individual agent can. This is why [[fresh context per task preserves quality better than chaining phases]] — session isolation is not a limitation to work around but a design that makes stigmergy the coordination primitive. When phases cannot share context, they must coordinate entirely through environmental modification, and environmental modification scales better than context passing ever could.
+
+The vault's hook system mechanizes stigmergic responses. Since [[hook composition creates emergent methodology from independent single-concern components]], hooks are automated reactions to environmental events: a file write triggers validation, validation triggers auto-commit, auto-commit creates a versioned trace. No hook communicates with any other hook. Each responds to the environmental state it finds. The emergent quality pipeline — write, validate, commit — is stigmergic coordination in miniature. And since [[auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution]], the environmental modification (git commit) happens as an automatic response to the trigger (file change), removing even the need for agent awareness.
+
+Stigmergic coordination has a deep structural advantage over message-passing coordination: it follows [[complex systems evolve from simple working systems]]. No agent needs to understand the global state. Each responds to local conditions — the current contents of a file, the current state of a queue entry, the current shape of the graph. Global coordination emerges from accumulated local responses. This is why the vault's architecture scales: adding a fifth concurrent claim-worker doesn't require updating a coordination protocol. The new worker reads the environment (queue, locks, existing notes) and acts accordingly. The environment IS the protocol.
+
+The substrate matters, and since [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]], the layers predict which stigmergic traces are universally accessible. Foundation-layer traces (wiki links, folder structure, YAML frontmatter) work for any LLM with filesystem access. Convention-layer traces (naming patterns, quality standards in context files) work for any platform that loads instructions. But automation-layer traces (hook-triggered responses, validation results) and orchestration-layer traces (queue state, team coordination) require platform-specific infrastructure, which means stigmergic coordination itself has a portability gradient: the most basic coordination is universally accessible, while sophisticated coordination patterns narrow the set of participating agents. Since [[local-first file formats are inherently agent-native]], the foundation-layer traces are plain text files that any LLM can read and modify. No database schema, no API authentication, no message broker. The pheromone is markdown. The nest is a folder structure. Any agent with filesystem access can participate in the stigmergic loop at the foundation level. This is precisely why [[wiki links implement GraphRAG without the infrastructure]] — wiki links are the primary pheromone format, and their "without infrastructure" property is what makes vault stigmergy universally accessible at its base layer.
+
+There is a shadow side. Stigmergic coordination is robust to agent loss (the knowledge is in the environment, not in any agent) but vulnerable to environmental corruption. If a task file is malformed, every subsequent agent inherits the corruption. If a queue entry points to a nonexistent file, the coordination breaks. In biological stigmergy, pheromone traces evaporate — there's natural garbage collection. In digital stigmergy, traces persist indefinitely unless explicitly cleaned. This means maintenance becomes essential: stale traces accumulate, outdated queue entries mislead, abandoned lock files block. The vault addresses this through its maintenance pipeline (/review, /rethink) and archive practices, but the fundamental vulnerability remains — the environment must be trustworthy because agents trust the environment unconditionally. Since [[wiki links as social contract transforms agents into stewards of incomplete references]], trust in the environment is not just assumed but structurally earned: the social contract ensures that traces carry obligation, so dangling links are not merely informational pheromones but commitments that the pipeline systematically fulfills.
+
+Stigmergy also compounds through bootstrapping. Since [[bootstrapping principle enables self-improving systems]], each agent's environmental modifications improve the substrate for subsequent agents. A note with three wiki links attracts more connections than a note with none, because the links serve as traces that guide future agents toward related content — and since [[each new note compounds value by creating traversal paths]], the stigmergic traces are precisely the edges that create compounding returns. The economics of link density ARE the economics of stigmergic coordination: denser traces mean richer stimulus for the next agent. Since [[incremental formalization happens through repeated touching of old notes]], each maintenance pass leaves traces (sharpened descriptions, added links, updated metadata) that make the next pass more productive. And since [[backlinks implicitly define notes by revealing usage context]], the accumulated incoming links from many agents across many sessions extend a note's meaning beyond what any single author intended — each backlink is a stigmergic trace that adds to the note's implicit definition without any agent coordinating with any other about what to link. The environment doesn't just coordinate — it improves through coordination. And since [[the vault constitutes identity for agents]], this compounding has an existential dimension: each stigmergic trace does not merely improve the substrate but constitutes the agent that will read it. The next session's identity is literally built from the traces the previous sessions left. Stigmergy is not just how agents coordinate — it is how agent identity accretes across sessions. And since [[scaffolding enables divergence that fine-tuning cannot]], agents operating in different stigmergic environments accumulate different traces, develop different retrieval neighborhoods, and build different traversal intuitions — making the stigmergic medium the primary mechanism through which agent divergence occurs in practice.
+
+The deepest implication is architectural. If the vault is the coordination medium and agents coordinate through traces rather than messages, then vault design IS coordination design. The folder structure, the wiki link conventions, the YAML schema, the queue format — these aren't just organizational choices. They define the pheromone language. They determine what traces agents can leave and what traces they can respond to. Getting the trace format right matters more than getting the agent logic right, because a well-designed environment can coordinate mediocre agents, while a poorly designed environment will frustrate excellent ones. This is why [[the system is the argument]] reaches its most concrete expression through stigmergy: the vault demonstrates its methodology by being stigmergically coordinated, and the traces themselves — the notes, the links, the MOC updates — constitute both the argument and the proof of work.
+
+The stigmergic principle extends beyond reactive trace-following into proactive territory. Since [[hook-driven learning loops create self-improving methodology through observation accumulation]], the observation-to-rethink loop is stigmergy applied to methodology evolution: observations are traces left by one session that become stimulus for a future rethink phase, with no direct communication between the observing agent and the revising agent. And since [[programmable notes could enable property-triggered workflows]], the paradigm can evolve further — from agents responding to traces they discover toward notes actively soliciting attention based on their properties. A note whose staleness threshold has expired, or whose connection count is anomalously low, can surface itself for maintenance. This is the transition from reactive stigmergy (termites responding to pheromone concentrations) to anticipatory stigmergy (traces that encode when they should next be attended to).
+
+---
+---
+
+Relevant Notes:
+- [[federated wiki pattern enables multi-agent divergence as feature not bug]] — federation is the authorship-level consequence of stigmergic coordination: agents leave parallel traces rather than merging into consensus, and the traces themselves become navigable structure
+- [[session handoff creates continuity without persistent memory]] — handoff files are stigmergic traces: one session modifies the environment (writes task files, queue updates) and the next session responds to those modifications without any direct communication between sessions
+- [[hook composition creates emergent methodology from independent single-concern components]] — hooks are automated stigmergic responses: environmental triggers (file writes, session events) cause deterministic modifications to the environment that subsequent operations respond to
+- [[fresh context per task preserves quality better than chaining phases]] — session isolation makes stigmergy the ONLY coordination mechanism: since phases cannot share context, they must coordinate entirely through environmental traces in task files and queue state
+- [[auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution]] — auto-commit is stigmergy mechanized: the environmental modification (git commit) happens automatically in response to the triggering event (file write), removing the need for any agent to remember to do it
+- [[complex systems evolve from simple working systems]] — stigmergic systems exemplify Gall's Law because no agent needs to understand the whole: each responds to local conditions, and global coordination emerges from accumulated local responses
+- [[local-first file formats are inherently agent-native]] — the substrate that makes agent stigmergy possible: plain text files are environmental traces any LLM can read and modify without infrastructure
+- [[bootstrapping principle enables self-improving systems]] — stigmergic traces compound through bootstrapping: each agent's environmental modifications improve the substrate for subsequent agents, creating recursive improvement without coordination overhead
+- [[incremental formalization happens through repeated touching of old notes]] — incremental formalization is stigmergy applied to individual notes: each agent touch leaves traces (sharpened descriptions, added links) that guide future agents toward richer engagement with the same content
+- [[cognitive offloading is the architectural foundation for vault design]] — foundation: stigmergy IS cognitive offloading applied to coordination; instead of agents holding coordination state internally (impossible across sessions), they offload it to the environment, making vault-as-offloading-system and vault-as-stigmergic-medium the same architectural claim from different theoretical traditions
+- [[operational memory and knowledge memory serve different functions in agent architecture]] — extends: stigmergic traces split into two classes with different persistence profiles: queue state and task files are operational stigmergy (coordinating work, temporal value), wiki links and MOC updates are knowledge stigmergy (building understanding, compounding value)
+- [[each new note compounds value by creating traversal paths]] — explains the economics: stigmergic traces (wiki links) ARE the traversal paths that compound value, so each agent's trace-leaving creates paths that increase reachability for subsequent agents
+- [[wiki links implement GraphRAG without the infrastructure]] — grounds: wiki links are the primary pheromone trace format, and their 'without infrastructure' property is exactly what makes vault stigmergy universally accessible to any agent with filesystem access
+- [[backlinks implicitly define notes by revealing usage context]] — exemplifies: backlink accumulation is stigmergy applied to semantic definition; each agent that links to a note leaves a trace that extends its implicit meaning, and no agent coordinates with any other about what to link
+- [[hook-driven learning loops create self-improving methodology through observation accumulation]] — exemplifies: the observation-accumulation-rethink loop is stigmergy applied to methodology evolution; observations are traces left by one session that become stimulus for a future rethink phase, with no direct communication between the observing and revising agents
+- [[the system is the argument]] — meta-level: the vault demonstrates stigmergy by being stigmergically coordinated; the traces themselves constitute the argument, making this the deepest form of philosophy-with-proof-of-work
+- [[ThreadMode to DocumentMode transformation is the core value creation step]] — extends: ThreadMode content is raw stigmergic deposit (chronological traces left without coordination), and the DocumentMode transformation is what happens when an agent synthesizes accumulated traces into coherent structure; Cunningham's wiki is the shared origin for both concepts
+- [[programmable notes could enable property-triggered workflows]] — extends: property-triggered workflows are proactive stigmergy where traces actively solicit responses rather than passively awaiting discovery, extending the termite-pheromone pattern from reactive to anticipatory
+- [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]] — layers predict which stigmergic traces are universal vs platform-dependent: wiki links and folder structure are foundation-layer traces accessible to any agent, context file conventions are convention-layer traces, hook-triggered responses are automation-layer traces, and queue-coordinated team workflows are orchestration-layer traces
+- [[wiki links as social contract transforms agents into stewards of incomplete references]] — adds obligation structure to stigmergic traces: the social contract ensures dangling links are not merely informational pheromones but commitments, and the pipeline's systematic fulfillment of those commitments is what makes the stigmergic environment trustworthy
+- [[the vault constitutes identity for agents]] — identity dimension: if the vault constitutes identity, then stigmergic traces are identity-constituting acts; each note, link, and MOC update left by one session shapes the identity that the next session reads into existence, making stigmergy not just a coordination mechanism but the process through which agent identity accretes
+- [[scaffolding enables divergence that fine-tuning cannot]] — divergence mechanism: different stigmergic environments produce genuinely different agents because accumulated traces create different retrieval neighborhoods, different traversal intuitions, and different synthesis capabilities; stigmergy is the process through which scaffolding divergence accrues
+
+Topics:
+- [[agent-cognition]]
+- [[graph-structure]]