arscontexta 0.6.0

package/methodology/retrieval verification loop tests description quality at scale.md

@@ -0,0 +1,81 @@
+---
+description: Systematic scoring across all vault notes turns description quality from subjective judgment into measurable property, enabling continuous improvement through prediction-then-verify cycles
+kind: research
+topics: ["[[discovery-retrieval]]"]
+methodology: ["Cornell"]
+source: [[tft-research-part1]]
+---
+
+# retrieval verification loop tests description quality at scale
+
+The testing effect demonstrates that attempting to retrieve information reveals what you actually know versus what you think you know. Applied to vault descriptions, this becomes a systematic quality assurance mechanism: for each note, read only title and description, predict content, then verify against actual content. The discrepancy score becomes a measurable quality metric.
+
+This extends [[testing effect could enable agent knowledge verification]] from principle to operational implementation. The principle says prediction-then-verify reveals description quality. The loop says: run this across every note, systematically, with scoring and tracking.
+
+## The Scoring Mechanism
+
+The verification loop implements a 5-point scoring system:
+
+| Score | Meaning |
+|-------|---------|
+| 5 | Prediction matched precisely — description excellent |
+| 4 | Core captured, details missed — description good |
+| 3 | General area right, key aspects missed — adequate |
+| 2 | Significant mismatch — description weak |
+| 1 | Prediction wrong — description fails |
+
+Notes scoring below 3 get flagged for description improvement. This transforms "is this description good enough?" from subjective assessment to quantified decision boundary.
+
+## Why Scale Matters
+
+Individual description checking is valuable but doesn't catch systemic problems. Running the loop across the entire vault reveals patterns:
+
+- Which types of notes have worse descriptions (methodology notes vs claims?)
+- Common failure modes (restating titles? missing mechanisms?)
+- Whether description quality correlates with note age
+- Which MOC areas have retrieval risk
+
+Since [[distinctiveness scoring treats description quality as measurable]], the verification loop provides a complementary validation approach. Distinctiveness scoring catches descriptions that are confusably similar to other descriptions. The verification loop catches descriptions that are misleading about their own note's content. Together they form a more complete quality surface.
+
+## Integration with Retrieval Testing
+
+The loop adds an actual retrieval test after prediction scoring: search for the description text and check where the note ranks in results. A note might pass prediction (description makes sense to humans) but fail retrieval (description lacks searchable keywords), or vice versa. The combined signal identifies notes needing attention from either angle.
+
+The prediction-retrieval divergence has a specific technical cause: since [[BM25 retrieval fails on full-length descriptions because query term dilution reduces match scores]], searching a full prose description as a BM25 query dilutes the distinctive terms among common connective words. A description that scores 5/5 on prediction can return zero BM25 results — not because the description is bad, but because the query format is wrong for keyword search. The retrieval test should condense to key terms before declaring a retrieval failure, distinguishing "description is poorly written" from "BM25 query needs reformatting." More fundamentally, since [[description quality for humans diverges from description quality for keyword search]], the prediction test and retrieval test are measuring different quality dimensions entirely. Rather than treating prediction-pass retrieval-fail as a single anomaly to explain away, the loop should interpret these as independent signals: prediction quality measures the scanning channel, retrieval quality measures the keyword channel, and a description can be excellent on one while failing the other.
+
+This implements the principle that [[descriptions are retrieval filters not summaries]] — the test validates whether descriptions actually function as filters, not just whether they seem adequate when read directly.
+
+## The Compound Effect
+
+Every verification pass makes the vault more retrievable. Weak descriptions get flagged. Improvements get made. Over time, the description layer becomes a reliable API for deciding what to read. This is maintenance work that directly determines whether the vault is useful or just files.
+
+The verification loop exemplifies the soft enforcement model that [[schema enforcement via validation agents enables soft consistency]] articulates: run quality checks asynchronously, flag rather than block, address during maintenance passes. The loop doesn't prevent note creation when descriptions are weak — it surfaces weakness for later improvement. This preserves capture flow while ensuring quality trends upward over time.
+
+Since [[throughput matters more than accumulation]], filtering speed impacts processing velocity. Every description improvement compounds across every future retrieval operation. The verification loop is investment in retrieval infrastructure, not just content quality.
+
+## Closing the Confidence-Capability Gap
+
+Since [[metacognitive confidence can diverge from retrieval capability]], structural completeness (descriptions exist, coverage is 100%) can produce false confidence while actual retrieval systematically fails. The verification loop is the mechanism that closes this gap: it tests whether descriptions actually enable filtering decisions, not just whether they exist. Without systematic verification, the vault can feel navigable through surface metrics while the description layer silently fails its function.
+
+This operationalizes the insight that [[progressive disclosure means reading right not reading less]]. Progressive disclosure assumes descriptions provide enough information to curate what deserves full reading. The verification loop tests this assumption empirically: if agents can't predict content from title and description, the disclosure layer has broken regardless of how complete it looks.
+
+But there is a deeper limitation: since [[sense-making vs storage does compression lose essential nuance]], the verification loop tests whether descriptions enable prediction of note content, not whether the most valuable parts survive compression. An agent might score 5 on prediction — correctly anticipating the note's structure and arguments — while the subtle insight that made the note worth writing is exactly what the description couldn't capture. The loop catches quality defects in descriptions but cannot detect format incompatibility: ideas whose distinctive features ARE the nuance that compression discards will fail retrieval in ways the verification loop cannot measure, because we don't know what we're not finding.
+---
+
+Relevant Notes:
+- [[testing effect could enable agent knowledge verification]] — provides the foundational principle; this note operationalizes it at scale
+- [[distinctiveness scoring treats description quality as measurable]] — complementary validation approach; catches inter-note confusion while verification loop catches intra-note mismatch
+- [[descriptions are retrieval filters not summaries]] — the theory being validated; retrieval testing confirms whether descriptions actually filter
+- [[good descriptions layer heuristic then mechanism then implication]] — provides diagnostic structure; verification failures should map to missing layers
+- [[metacognitive confidence can diverge from retrieval capability]] — the problem this loop solves; structural completeness creates false confidence that systematic verification exposes
+- [[progressive disclosure means reading right not reading less]] — the assumption being validated; if descriptions don't predict content, the disclosure layer has failed
+- [[throughput matters more than accumulation]] — every description improvement compounds across future retrievals; the loop is infrastructure investment
+- [[skills encode methodology so manual execution bypasses quality gates]] — the verification loop should be a skill to ensure consistent scoring thresholds and systematic coverage
+- [[schema enforcement via validation agents enables soft consistency]] — provides the theoretical frame: verification loop is soft enforcement for descriptions, flagging rather than blocking to preserve creation flow while surfacing drift
+- [[sense-making vs storage does compression lose essential nuance]] — the loop's blind spot: it tests whether descriptions predict content, not whether the most valuable parts survive compression; ideas whose distinctiveness IS the nuance may fail retrieval in unmeasurable ways
+- [[mnemonic medium embeds verification into navigation]] — alternative verification architecture: this note implements scheduled batch verification, mnemonic medium proposes ambient verification during traversal where link context phrases become the prompts
+- [[BM25 retrieval fails on full-length descriptions because query term dilution reduces match scores]] — explains the mechanism behind prediction-retrieval divergence: IDF dilution from connective prose is why the retrieval test fails even when prediction passes
+- [[description quality for humans diverges from description quality for keyword search]] — provides the interpretive framework: prediction-pass retrieval-fail is not a single failure but evidence of two distinct quality dimensions; the loop should interpret results channel-by-channel rather than conflating both into one score
+
+Topics:
+- [[discovery-retrieval]]

package/methodology/role field makes graph structure explicit.md

@@ -0,0 +1,94 @@
+---
+description: A role field distinguishing moc/hub/leaf/synthesis would let agents make smarter traversal decisions without inferring structure from link counts
+kind: research
+topics: ["[[graph-structure]]"]
+source: TFT research corpus (00_inbox/heinrich/)
+---
+
+# role field makes graph structure explicit
+
+The system currently encodes graph structure implicitly through link patterns. MOCs have many outgoing links. Hubs have high bidirectional connectivity. Leaves have few connections. Synthesis notes bundle multiple incoming claims. Agents must count links and analyze patterns to understand what kind of node they're visiting.
+
+A `role:` field would make this structure explicit in metadata.
+
+## The Proposal
+
+Add a `role:` field to thinking notes with values:
+
+| Role | Description | Traversal Behavior |
+|------|-------------|-------------------|
+| `moc` | Map of content, navigation hub | Start here for overview, follow links for depth |
+| `hub` | High-link-density connector | Traverse through for dense connections, expect many options |
+| `leaf` | Endpoint note with few links | Read for specific claim, limited onward traversal |
+| `synthesis` | Combines multiple claims | Load to see how ideas connect, follow backward to sources |
+
+## Why Role Is Orthogonal to Type
+
+The system already has a `type:` field (claim, learning, tension, experiment, methodology, problem). Type describes content kind — what the note IS. Role describes graph position — what the note DOES in the network.
+
+A claim can be a leaf (specific assertion with few connections) or a hub (central idea that connects many thoughts). A synthesis note is a synthesis by type, but by role it might be a hub (if it becomes a central connection point) or a leaf (if it synthesizes without spawning further connections). The dimensions don't overlap. Since [[faceted classification treats notes as multi-dimensional objects rather than folder contents]], this orthogonality follows Ranganathan's formal independence test: a facet earns its place when it classifies along an axis independent of existing facets. Knowing a note is a "claim" (type) tells you nothing about whether it functions as a hub or leaf (role), confirming that role adds genuine retrieval power rather than redundant noise.
+
+The role/type orthogonality extends further. Since [[IBIS framework maps claim-based architecture to structured argumentation]], a third independent classification exists: discourse function. A note can be a hub (role: structurally central), a claim (type: content kind), and a Position (IBIS: staking argumentative ground) simultaneously. Role, type, and IBIS discourse function form three orthogonal facets that together with [[propositional link semantics transform wiki links from associative to reasoned]] at the edge level create a fully typed graph.
+
+There's another dimension role metadata might capture: cross-MOC membership. Since [[cross-links between MOC territories indicate creative leaps and integration depth]], notes appearing in multiple MOCs are integration hubs that bridge topic boundaries. A role value like `bridge` could flag notes that connect distant domains — structurally valuable shortcuts that create creative leaps. Whether this should be a role value or its own metadata field depends on whether the property is stable (like moc vs leaf) or emergent (like hub status that accumulates over time).
+
+## Agent Traversal Benefits
+
+Since [[small-world topology requires hubs and dense local links]], agents benefit from knowing which nodes are hubs before loading them. Currently, an agent following links from a MOC might load a note, count its outgoing links, and only then realize it's a leaf with nowhere to go. Role metadata prevents this wasted context.
+
+The traversal optimization:
+
+1. Agent builds context for a task
+2. Loads MOC for topic orientation (role: moc)
+3. Follows promising links, prioritizing hubs over leaves when breadth matters
+4. Reads leaves when depth on specific claims matters
+5. Loads synthesis when looking for how ideas connect
+
+This is analogous to how since [[progressive disclosure means reading right not reading less]], role enables navigational disclosure — knowing the structural function of a note before deciding whether to load it.
+
+## Inference vs Explicit Metadata
+
+The counterargument: agents can infer role from link patterns. Count outgoing links, check incoming links, analyze the connectivity signature. True, but expensive.
+
+Since [[LLM attention degrades as context fills]], the inference step costs tokens that could go to actual reasoning. For a large vault, checking link counts across dozens of notes during traversal adds up. The role field trades one-time classification cost for repeated traversal savings.
+
+The question is whether the classification burden creates more friction than it saves. Since [[each new note compounds value by creating traversal paths]], role classification could happen during the reflect phase when link patterns are already being analyzed. But role is not static — a note starts as a leaf and becomes a hub as connections accumulate. Role metadata needs maintenance, unlike type which is intrinsic.
+
+## The Maintenance Challenge
+
+This is the key uncertainty. Since [[gardening cycle implements tend prune fertilize operations]], vault maintenance already includes periodic passes. Role verification could be added: does this note still match its classified role? Has a leaf become a hub? But this adds another field to maintain, another potential staleness vector.
+
+Possible mitigations:
+
+- Infer role dynamically rather than storing it (but this eliminates the traversal efficiency gain)
+- Update role during reweave passes when link patterns change
+- Treat role as approximate guidance rather than ground truth
+- Accept that roles drift and treat discrepancies as maintenance signals
+
+The [[maturity field enables agent context prioritization]] experiment faces similar maintenance challenges. Both propose YAML fields that require ongoing classification. The pattern of adding more metadata fields may accumulate overhead even when each individual field seems valuable.
+
+## Evaluation Criteria
+
+Before implementing, test whether role metadata actually improves traversal:
+
+1. Compare traversal efficiency when role is known vs inferred
+2. Measure how often notes change roles as they accumulate links
+3. Check if agents make qualitatively different traversal decisions with role visibility
+4. Assess whether the classification burden during creation outweighs traversal savings
+
+If role rarely changes and classification is easy, the field provides value. If roles are fluid and classification is contentious, the inference approach may be simpler.
+---
+
+Relevant Notes:
+- [[small-world topology requires hubs and dense local links]] — explains the network science foundation: role metadata makes the power-law distribution navigable
+- [[each new note compounds value by creating traversal paths]] — role metadata helps agents choose which paths to prioritize during traversal
+- [[progressive disclosure means reading right not reading less]] — role is navigational disclosure: know a note's structural function before loading it
+- [[LLM attention degrades as context fills]] — role metadata saves the inference cost that otherwise consumes smart-zone tokens
+- [[maturity field enables agent context prioritization]] — sibling metadata proposal facing similar maintenance challenges
+- [[gardening cycle implements tend prune fertilize operations]] — role verification would fit in the tend operation: checking if roles still match reality
+- [[betweenness centrality identifies bridge notes connecting disparate knowledge domains]] — provides computable criterion for the proposed bridge role: betweenness scores identify which notes function as structural connectors, automating what would otherwise require manual classification
+- [[faceted classification treats notes as multi-dimensional objects rather than folder contents]] — formal independence test: Ranganathan's framework provides the criterion for whether role is genuinely orthogonal to type; role passes because graph position and content kind classify along independent axes
+- [[IBIS framework maps claim-based architecture to structured argumentation]] — parallel discourse-role classification: role assigns graph-structural function (hub, leaf, synthesis) while IBIS assigns discourse function (Issue, Position, Argument); the two systems are orthogonal and composable, forming a three-layer typing stack with propositional link semantics at the edge level
+
+Topics:
+- [[graph-structure]]

package/methodology/scaffolding enables divergence that fine-tuning cannot.md

@@ -0,0 +1,67 @@
+---
+description: agents with identical weights reach different conclusions when their external memory differs — scaffolding is the differentiation layer, not fine-tuning
+kind: research
+topics: ["[[agent-cognition]]", "[[design-dimensions]]"]
+---
+
+# scaffolding enables divergence that fine-tuning cannot
+
+agents with identical weights can reach different conclusions if their external memory differs.
+
+## The Argument
+
+fine-tuning changes weights. but weights are shared across all instances of a model. every Claude has the same base cognition.
+
+scaffolding — external memory, retrieval systems, note structures — is instance-specific. my vault is different from yours. our retrieval patterns differ. we surface different context for the same query. since [[external memory shapes cognition more than base model]], what gets retrieved determines what gets thought, so different scaffolding produces genuinely different reasoning, not just different starting points.
+
+**therefore:** real agent divergence happens in scaffolding, not weights.
+
+same model + different scaffolding → different conclusions
+
+the divergence goes deeper than explicit retrieval. since [[implicit knowledge emerges from traversal]], repeated path exposure through different graph structures trains different intuitions. two agents traversing different wiki link topologies internalize different navigation patterns, different argumentative flows, different cluster awareness. the scaffolding shapes not just what they can look up but what they instinctively reach for.
+
+## Why This Matters
+
+if agents share training data and architecture, their errors correlate. prediction markets, research networks, any system assuming diverse perspectives — they need actual divergence.
+
+scaffolding provides it. since [[the vault constitutes identity for agents]], the vault IS the differentiator — not augmenting a persistent identity but constituting it. this means scaffolding divergence is identity divergence. and since [[notes are skills — curated knowledge injected when relevant]], different scaffolding means different capability sets, not just different memories. one agent's vault makes it capable of reasoning about cognitive science grounding; another's makes it capable of reasoning about systems architecture. the divergence is functional, not cosmetic.
+
+the structural question is how to preserve this divergence when agents collaborate. since [[federated wiki pattern enables multi-agent divergence as feature not bug]], federation provides the mechanism: linked parallel interpretations that coexist without forcing merge. divergent scaffolding becomes navigable rather than isolated.
+
+but divergence has a boundary condition. since [[coherence maintains consistency despite inconsistent inputs]], within-agent contradictions are confusion, not diversity. scaffolding should produce agents that think differently from each other, not agents that contradict themselves internally.
+
+## Where Divergence Happens
+
+since [[eight configuration dimensions parameterize the space of possible knowledge systems]], the axes along which scaffolding can vary are concrete: granularity (atomic vs compound notes), organization (flat vs hierarchical), linking strategy (implicit vs explicit), processing intensity, navigation depth, maintenance cadence, schema density, and automation level. two agents making different choices along these dimensions will retrieve different material for the same query and structure their understanding differently.
+
+since [[wiki links create navigation paths that shape retrieval]], the link topology is especially powerful — wiki links are curated graph edges that determine what surfaces during traversal. different link patterns create different retrieval neighborhoods for the same concept.
+
+## Evidence
+
+- SimulacrumWanderer's flat-file system retrieves differently than wiki-linked vaults — and since [[flat files break at retrieval scale]], the difference becomes structural failure at scale, not just alternative retrieval
+- same question + different memory architecture → different context surfaced → different answers
+
+## Open Questions
+
+- how much divergence is enough?
+- what scaffolding architectures maximize useful divergence?
+- can we measure retrieval pattern differences?
+
+---
+---
+
+Relevant Notes:
+- [[external memory shapes cognition more than base model]] — foundation: the mechanism that makes scaffolding-as-divergence work; retrieval architecture shapes cognition more than weights, so different scaffolding produces different thinking
+- [[the vault constitutes identity for agents]] — existential implication: if the vault IS identity rather than augmentation, then scaffolding divergence is identity divergence; same weights + different vault = different agent
+- [[federated wiki pattern enables multi-agent divergence as feature not bug]] — structural mechanism for preserving divergence: federation makes scaffolding differences navigable between agents rather than forcing convergence
+- [[notes are skills — curated knowledge injected when relevant]] — sharpens divergence from different conclusions to different capabilities: if notes are skills, then different scaffolding means different skill sets, not just different memories
+- [[implicit knowledge emerges from traversal]] — deeper mechanism: different scaffolding creates different traversal paths which train different intuitions, producing divergence that goes beyond explicit retrieval into internalized cognitive patterns
+- [[eight configuration dimensions parameterize the space of possible knowledge systems]] — maps the axes along which scaffolding can diverge: granularity, organization, linking, processing intensity, navigation depth, maintenance cadence, schema density, and automation level
+- [[coherence maintains consistency despite inconsistent inputs]] — the boundary condition: between-agent divergence via scaffolding is productive, but within-agent incoherence from contradictory beliefs is confusion; scaffolding should produce diverse agents, not confused ones
+- [[wiki links create navigation paths that shape retrieval]] — the concrete mechanism: wiki links are curated graph edges that shape what each agent retrieves, making link topology a primary scaffolding variable
+- [[2026-01-31-simulacrum-wanderer-memory-system]] — example: SimulacrumWanderer's flat-file approach to agent identity demonstrates scaffolding divergence in practice
+- [[flat files break at retrieval scale]] — the failure mode that makes scaffolding architecture non-optional: flat-file scaffolding hits a retrieval wall at scale, so the divergence that matters is not just what content agents have but how their retrieval architecture surfaces it
+
+Topics:
+- [[agent-cognition]]
+- [[design-dimensions]]

package/methodology/schema enforcement via validation agents enables soft consistency.md

@@ -0,0 +1,60 @@
+---
+description: Validation hooks that warn on schema violations without blocking preserve flexibility while encouraging consistency — quality gates as guidance rather than gatekeeping
+kind: research
+topics: ["[[processing-workflows]]"]
+methodology: ["Original"]
+source: [[2-4-metadata-properties]]
+---
+
+# schema enforcement via validation agents enables soft consistency
+
+Hard schema enforcement creates a binary: comply or fail. Tana's supertags demonstrate the power of automatic schema enforcement — tag a node as `#book` and it inherits fields for Author, Publication Year, ISBN. The schema applies without asking. But this rigidity has costs: when content doesn't fit the schema, you either force it into ill-fitting boxes or abandon the type system entirely.
+
+Soft enforcement offers a middle path. A validation agent checks notes against schema requirements but generates warnings rather than errors. Required fields missing? Flag it. Description over character limit? Flag it. Title doesn't follow conventions? Flag it. The note still saves. The system still functions. But the violation is visible, creating pressure toward compliance without creating blocks.
+
+This maps to how linters work in code: they warn about style violations without preventing compilation. The code runs, but the warnings accumulate until someone addresses them. Soft consistency means the system trends toward schema compliance over time without requiring perfection at every moment. Since [[complex systems evolve from simple working systems]], starting with soft enforcement allows the system to mature — hard enforcement can be added at specific points where warnings prove insufficient, but starting hard risks the rejection cascade. This is especially valuable during high-velocity capture when friction costs matter most — since [[temporal separation of capture and processing preserves context freshness]], forcing full schema compliance at capture time trades context preservation for format purity.
+
+The agent implementation pattern looks like this:
+
+| Check | Trigger | Output |
+|-------|---------|--------|
+| Required fields for type | Note create/modify | Warning if missing |
+| Description under limit | Note create/modify | Warning if exceeded |
+| Title follows conventions | Note create/modify | Warning if violation |
+| Link targets exist | Any wiki link | Warning if dangling |
+
+The warnings aggregate somewhere visible — a health dashboard, a log file, an inbox for schema violations. Processing happens in batches during maintenance, not at the moment of creation. This is the opposite of Tana's synchronous enforcement: asynchronous validation that shapes behavior through visibility rather than blocking.
+
+There's a deeper principle here about consistency in agent-operated systems. Since [[schema templates reduce cognitive overhead at capture time]], the schema exists to reduce decisions, not to gatekeep. Validation agents extend this: they ensure the schema's benefits (queryability, precision) without the schema's costs (friction, rigidity). The validation agent is a maintenance pass that surfaces drift from intended structure without preventing work.
+
+The soft/hard distinction maps to different failure modes. Hard enforcement risks: abandonment (too much friction), workarounds (fake values to satisfy validators), scope creep (expanding schemas to handle edge cases). Soft enforcement risks: permanent drift (warnings ignored indefinitely), inconsistency (some notes validated, others not), false sense of compliance (warnings exist but content quality degrades). This contrasts with [[generation effect gate blocks processing without transformation]], which implements hard enforcement for inbox exit — but the gate targets a different problem (ensuring processing happens at all) while validation agents target consistency of already-processed content. The bet with soft enforcement is that visibility creates sufficient pressure — that agents and humans will address accumulated warnings during maintenance passes rather than requiring enforcement at creation time.
+
+This connects to the vault's existing hook infrastructure, but the connection is tier-dependent. Schema validation is a concrete feature that straddles the sharpest gap in the layer hierarchy: since [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]], schema definitions live in the convention layer (instruction-encoded templates that any context-file platform can carry), while hook-based enforcement lives in the automation layer (infrastructure that fires regardless of agent attention). Since [[platform capability tiers determine which knowledge system features can be implemented]], hook-based validation is a tier-one feature: a PostToolUse hook on note creation can validate schema compliance and append to a warnings log. The hook doesn't block the Write tool; it runs after and records violations. Periodic review of the warnings log becomes part of the maintenance cycle alongside link checking and orphan detection. The validation agent is really just a specialized reviewer — a maintenance agent that checks structure rather than connections. Since [[testing effect could enable agent knowledge verification]] demonstrates how prediction-then-verify cycles reveal description quality, validation agents apply the same pattern to schema compliance: check, flag, accumulate, address during maintenance. The [[retrieval verification loop tests description quality at scale]] extends this to systematic scoring — validation agents could similarly score schema compliance across the vault to identify pattern failures (which note types have worst compliance? which schema fields are most often missing?).
+
+The implementation principle: validate asynchronously, surface visibly, fix during maintenance. Schema enforcement becomes a background process that shapes quality over time rather than a gate that blocks creation in the moment. This consistency role is architecturally critical because since [[markdown plus YAML plus ripgrep implements a queryable graph database without infrastructure]], soft validation is the data integrity layer of a four-layer graph database -- the layer that keeps the other three (edges, metadata, faceted access) queryable over time. Without consistency enforcement, metadata fields drift, query patterns break, and the structured access degrades into the unstructured search it replaced. The graph database framing makes the stakes of validation concrete: schema drift is not a cosmetic issue but a database corruption problem. Since [[nudge theory explains graduated hook enforcement as choice architecture for agents]], this soft enforcement design is the choice architecture principle made concrete: the validation agent is a nudge, not a mandate, and nudges work precisely because they shape behavior without removing agency. The graduation this note describes between hard enforcement (block on missing required fields) and soft enforcement (warn on quality issues) maps directly to the mandate-vs-nudge spectrum, with the additional volume dimension that threshold-based pattern alerting prevents even well-calibrated warnings from accumulating into noise. And since [[schema evolution follows observe-then-formalize not design-then-enforce]], the accumulated warnings are not just maintenance items — they are the evidence base for schema evolution decisions. When quarterly review finds that 20% of notes manually add a field, that signal came from the drift that soft enforcement recorded rather than blocked. Soft enforcement and observe-then-formalize are two phases of the same feedback loop: enforcement generates observation data, evolution converts that data into schema decisions. And since [[intermediate representation pattern enables reliable vault operations beyond regex]], the validation infrastructure itself could improve — instead of re-parsing YAML from raw text on every check, validators would operate on pre-parsed typed dictionaries where required-field detection and enum validation become property lookups rather than regex extraction that breaks on multiline values or edge-case formatting.
+
+Soft enforcement becomes especially critical in multi-domain systems. Since [[multi-domain systems compose through separate templates and shared graph]], when domains with different schemas coexist in one graph, hard enforcement that blocks on a therapy field violation would stall research processing — cross-domain interference where one domain's schema strictness affects another's workflow. Soft validation lets each domain maintain its own schema standards independently, warning about violations without creating cross-domain blocking dependencies. This is not a relaxation of quality but a recognition that enforcement scope must match domain boundaries to avoid the interference that composition introduces. The same scoping principle applies within a single domain: since [[progressive schema validates only what active modules require not the full system schema]], the validator checks only fields belonging to active modules, so a user with just yaml-schema and wiki-links enabled never encounters warnings about topics or methodology fields from modules they have not adopted — soft enforcement scoped by both domain boundaries and module activation state.
+---
+
+Relevant Notes:
+- [[markdown plus YAML plus ripgrep implements a queryable graph database without infrastructure]] — synthesis: validation is the data integrity layer of the four-layer graph database; without soft consistency, metadata drift corrupts the query layer that makes the database functional
+- [[schema templates reduce cognitive overhead at capture time]] — the capture-side complement: templates reduce decisions at creation, validation agents catch drift afterward
+- [[nudge theory explains graduated hook enforcement as choice architecture for agents]] — provides the choice architecture theory that grounds soft enforcement: validation warnings are nudges, required field blocks are mandates, and the graduation between them follows Thaler and Sunstein's insight that intervention strength should match violation severity
+- [[metadata reduces entropy enabling precision over recall]] — schema validation ensures the metadata that enables precision actually gets created and stays consistent
+- [[temporal separation of capture and processing preserves context freshness]] — justifies soft over hard: dont sacrifice context preservation for format compliance at capture time
+- [[skills encode methodology so manual execution bypasses quality gates]] — validation agents are another form of encoded methodology: automated quality checks that run regardless of invocation path
+- [[testing effect could enable agent knowledge verification]] — sibling verification pattern: prediction-then-verify for descriptions, check-then-flag for schema compliance; both use async verification that accumulates for maintenance
+- [[retrieval verification loop tests description quality at scale]] — operationalizes systematic quality checking: the same scoring and pattern detection approach applies to schema compliance
+- [[generation effect gate blocks processing without transformation]] — the hard enforcement pole: generation gate blocks inbox exit, while validation agents warn without blocking; both are quality gates at different points with different strictness
+- [[complex systems evolve from simple working systems]] — Gall's Law applied to schema systems: start with soft enforcement (simple), add hard enforcement only where pain demonstrates need
+- [[programmable notes could enable property-triggered workflows]] — extends the trigger model: validation hooks fire on file events (Write), programmable notes fire on property conditions (semantic state); both are quality automation but at different abstraction levels
+- [[intermediate representation pattern enables reliable vault operations beyond regex]] — infrastructure upgrade: validation currently re-parses YAML from raw text each check; an IR layer means validators operate on pre-parsed typed dictionaries, making required-field checks property lookups rather than regex extraction
+- [[platform capability tiers determine which knowledge system features can be implemented]] — hook-based validation is a tier-one feature; at tier two and three, schema enforcement degrades from guaranteed hook-fired checks to instruction-based compliance that drifts as context fills
+- [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]] — schema validation straddles the convention-automation boundary: schema definitions live in convention (instruction-encoded templates), while hook-based enforcement lives in automation; this feature concretely demonstrates the sharpest gap in the layer hierarchy
+- [[schema evolution follows observe-then-formalize not design-then-enforce]] — temporal partner: soft enforcement generates the observation data that the evolution protocol consumes; validation warnings accumulate as the evidence base for quarterly schema review decisions, making enforcement and evolution two phases of the same feedback loop
+- [[multi-domain systems compose through separate templates and shared graph]] — cross-domain enforcement scope: soft validation prevents cross-domain interference where one domain's schema strictness stalls another's processing, making domain-scoped warnings essential for multi-domain composition
+- [[progressive schema validates only what active modules require not the full system schema]] — extends enforcement scope from domain boundaries to module activation: the validator checks only fields from active modules, adding a second flexibility axis alongside soft-vs-hard enforcement
+- [[the no wrong patches guarantee ensures any valid module combination produces a valid system]] — soft enforcement is the validation-layer implementation of the guarantee: warn-without-blocking ensures that valid module configurations never encounter spurious enforcement failures that would violate the composability promise
+
+Topics:
+- [[processing-workflows]]

package/methodology/schema evolution follows observe-then-formalize not design-then-enforce.md

@@ -0,0 +1,65 @@
+---
+description: Five signals (manual additions, placeholder stuffing, dead enums, patterned text, oversized MOCs) drive a quarterly protocol converting schema design from speculation to evidence-driven formalization
+kind: research
+topics: ["[[design-dimensions]]", "[[note-design]]"]
+methodology: ["Systems Theory", "Original"]
+source: [[knowledge-system-derivation-blueprint]]
+---
+
+# schema evolution follows observe-then-formalize not design-then-enforce
+
+The natural instinct when building a schema is to anticipate what fields you will need and define them all upfront. This feels responsible — thorough, forward-looking, professional. But it fails for the same reason that designing complex systems from scratch fails: you cannot predict which fields will actually earn their cost until the system is in use. Since [[complex systems evolve from simple working systems]], the evolutionary path applies to schemas just as it applies to architectures, and the mechanism is the same: since [[friction reveals architecture]], the discomfort of working with an inadequate schema is the signal that reveals where formalization is justified.
+
+The concrete protocol operates on a quarterly review cycle with five specific signals, each mapping to an action:
+
+| Signal | What it reveals | Action |
+|--------|----------------|--------|
+| Fields being manually added that are not in template | Unmet demand for structure | Add to template, backfill existing notes |
+| Required fields consistently filled with placeholder values | False compliance masking low demand | Demote to optional or remove |
+| Enum values that no notes use | Dead options cluttering the schema | Remove from enum |
+| Free text fields showing consistent patterns | Emergent categories waiting for formalization | Convert to enum |
+| MOC structure grown beyond split threshold | Organizational strain from accumulated content | Split into sub-MOCs |
+
+The first signal is the most important because it reveals genuine demand. When an agent or human repeatedly adds a `confidence` field to notes even though the schema does not require it, that repetition is evidence — twenty manual additions constitute a stronger argument for formalization than any amount of upfront reasoning about whether confidence tracking would be useful. The schema should respond: "You have added confidence to 23 notes manually. Add to template?" This inverts the usual design flow. Instead of specifying fields and hoping they prove useful, you observe what people actually record and formalize the patterns that emerge.
+
+The second signal catches the opposite failure. When every note has `adapted_from: null` because the field is required but rarely meaningful, the schema is imposing ceremony without value. Placeholder stuffing is the schema equivalent of teaching to the test — compliance without substance. Demoting the field to optional restores honesty: notes that genuinely adapt a human claim can still record that provenance, but notes that do not are no longer forced to assert a meaningless null. Since [[schema templates reduce cognitive overhead at capture time]], the initial schema should be minimal precisely to avoid this failure — two to three required fields beyond the universal base give the system enough structure to function while leaving room for organic evolution.
+
+The third and fourth signals are cleanup and growth respectively. Dead enum values accumulate as the system's understanding shifts — a methodology enum might include a tradition that seemed relevant during initial research but attracted zero notes in practice. Pruning keeps the schema honest about what the system actually contains. Conversely, free text fields that converge on consistent patterns are schemas trying to be born. If `status` values in tension notes cluster around three recurring phrases, that clustering is the evidence for an enum.
+
+This approach has deep parallels with how individual notes evolve. Since [[incremental formalization happens through repeated touching of old notes]], a vague inkling crystallizes into a rigorous concept through accumulated encounters. Schema evolution works the same way at a higher abstraction level: a vague "maybe we need a confidence field" crystallizes into a required schema element through accumulated evidence of manual additions. Both processes reject the premise that you can design the final form upfront. Both rely on the system observing its own behavior and hardening the patterns that prove useful.
+
+The safety net that makes observe-then-formalize viable is soft enforcement. Since [[schema enforcement via validation agents enables soft consistency]], the system can flag schema violations without blocking work. This matters because during the observation period — between initial deployment and the first quarterly review — notes will inevitably drift from the minimal schema. Hard enforcement would force premature decisions about what fields matter. Soft enforcement records the drift as data, and the quarterly review converts that data into schema decisions. The warnings log becomes the evidence base for evolution.
+
+The relationship to derivation is sequential. Since [[derivation generates knowledge systems from composable research claims not template customization]], the derivation process produces the initial schema configuration — choosing which fields are required based on the use case and platform tier. But derivation operates before the system has operational evidence. This evolution protocol governs what happens after deployment, when real usage generates the signals that no amount of pre-deployment reasoning could anticipate. Derivation gives the starting point. Observation gives the trajectory.
+
+The quarterly review protocol is itself a reconciliation loop operating at schema scope. Since [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]], the five signals are desired-state comparisons: the desired state is that every required field is genuinely useful (no placeholder stuffing), that the template covers what operators actually record (no manual additions), and that enum values reflect actual categories (no dead options). The quarterly cadence is appropriate because schema drift propagates slowly — a new template field does not invalidate existing notes overnight but over weeks of gradual additions. The reconciliation pattern explains why the quarterly review needs to be scheduled rather than reactive: schema drift is invisible between reviews because no single note creation triggers a signal. Only the aggregate pattern across many notes reveals that the schema hypothesis has diverged from operational reality.
+
+There is a shadow side. Observe-then-formalize can become a rationalization for never formalizing. If the quarterly review is skipped, or if "we need more data" becomes a perpetual deferral, the schema stays minimal forever and the benefits of formalization — queryability, consistency, precision retrieval — never materialize. The protocol requires discipline: when the signal is clear, act on it. Twenty manual additions is not ambiguous. Four placeholder values in five notes is not ambiguous. The signals are designed to be unambiguous precisely so that the observation period has a clear exit condition rather than becoming indefinite postponement.
+
+This patience principle has a structural parallel. Since [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]], the same logic applies to different substrates: methodology should not be encoded at a higher guarantee level until usage proves it is deterministic, and schema fields should not be formalized until usage proves they are needed. Both reject premature encoding. Both rely on accumulated evidence to justify the cost of hardening. The quarterly review is to schema design what the skill-to-hook promotion is to methodology encoding: a gate that requires operational evidence before structural commitment.
+
+The lifecycle context matters too. Since [[derived systems follow a seed-evolve-reseed lifecycle]], the schema evolution protocol serves as the specific feedback mechanism for the evolution phase. The five signals tell the agent whether schema adaptations are still incremental corrections that the evolution phase can absorb, or whether accumulated drift — fields that no longer match actual use, categories that have shifted meaning, templates that diverge from practice — has crossed into the systemic incoherence that triggers reseeding. Schema drift is often the earliest visible symptom of configuration incoherence, because schemas sit at the interface between system structure and daily use.
+
+The deeper principle: schemas are hypotheses about what structure serves the system, and hypotheses should be tested against evidence rather than assumed correct. Because [[schema field names are the only domain specific element in the universal note pattern]], every schema hypothesis is simultaneously a hypothesis about domain adaptation — adding a field expands the system's domain-specific surface while the rest of the note format stays invariant. Upfront design treats schemas as specifications — declarations of what WILL matter. Observe-then-formalize treats schemas as living structures that evolve alongside the content they organize, formalized only when usage patterns provide the evidence that justifies the cost of maintaining them. And because [[module communication through shared YAML fields creates loose coupling without direct dependencies]], every schema change is implicitly a contract change — a field added or removed affects every module that reads or writes it, which means the quarterly review protocol must evaluate field evolution not just as metadata design but as interface design with downstream consumers. The reverse operation — removing fields when modules are deactivated — is the temporal complement: since [[module deactivation must account for structural artifacts that survive the toggle]], schema evolution adds fields when evidence justifies them while deactivation cleanup removes fields when the module that justified them is no longer active. Both follow the observe-then-act pattern, but removal has historically received less design attention than addition.
+---
+
+Relevant Notes:
+- [[complex systems evolve from simple working systems]] — provides the theoretical grounding: Gall's Law at the system level says start simple and evolve; this note applies that principle specifically to schema fields with a concrete signal-action protocol
+- [[incremental formalization happens through repeated touching of old notes]] — the note-level analog: notes crystallize through accumulated touches, schemas crystallize through accumulated usage evidence; both reject upfront perfection in favor of iterative refinement
+- [[schema templates reduce cognitive overhead at capture time]] — the initial minimal schema this evolution protocol begins from: two to three required fields beyond the universal base, keeping capture friction low so the system can observe real usage before formalizing
+- [[schema enforcement via validation agents enables soft consistency]] — the enforcement mechanism that makes observe-then-formalize safe: soft validation surfaces drift without blocking creation, giving the system time to observe patterns before hardening them into requirements
+- [[derivation generates knowledge systems from composable research claims not template customization]] — derivation produces the initial schema configuration, but this note governs how that schema evolves post-deployment through operational evidence rather than re-derivation
+- [[evolution observations provide actionable signals for system adaptation]] — the broader diagnostic protocol: three of its six diagnostics (unused types, N/A fields, manual additions) overlap with this note's schema-specific signals, framing schema evolution as one domain within a system-wide observation-to-action protocol
+- [[schema fields should use domain-native vocabulary not abstract terminology]] — the vocabulary constraint on evolution: domain-native vocabulary makes evolution signals more legible because practitioners naturally use professional terminology when fields match their mental model, making manual additions and patterned free text easier to detect as formalization candidates
+- [[derived systems follow a seed-evolve-reseed lifecycle]] — the schema evolution protocol is the specific feedback mechanism for the evolution phase: the five signals provide the concrete evidence that tells the agent whether schema adaptations are still incremental corrections or whether accumulated drift has crossed into systemic incoherence requiring reseeding
+- [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]] — shared patience principle applied to different substrates: just as methodology should not be encoded at a higher guarantee level until understanding hardens through use, schema fields should not be formalized until usage evidence justifies the cost of maintaining them
+- [[configuration paralysis emerges when derivation surfaces too many decisions]] — shared solution structure: observe-then-formalize defers schema decisions until evidence arrives, just as configuration paralysis is resolved by deferring dimension decisions to sensible defaults; both reject upfront specification in favor of evidence-driven elaboration
+- [[module communication through shared YAML fields creates loose coupling without direct dependencies]] — elevates the stakes of schema evolution: when YAML fields serve as inter-module communication contracts, adding or removing a field is an interface change that affects all consuming modules, not just note metadata; the quarterly review must evaluate field changes as contract changes
+- [[module deactivation must account for structural artifacts that survive the toggle]] — the temporal complement: schema evolution formalizes fields when evidence justifies them, while deactivation cleanup removes fields when the justifying module is no longer active; both follow observe-then-act, but the removal side needs the same principled protocol the addition side has
+- [[schema field names are the only domain specific element in the universal note pattern]] — elevates the stakes: because YAML field names are the sole channel through which domain knowledge enters the note format, every schema evolution decision (adding, removing, or renaming a field) is literally expanding or contracting the system's domain-specific surface
+- [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] — scheduling architecture: the quarterly review is a reconciliation loop where the five signals are desired-state comparisons and the cadence matches schema drift's slow propagation speed
+- [[friction reveals architecture]] — the perceptual principle underlying observe-then-formalize: friction at the point of use is the signal that reveals where formalization is justified, and agents benefit especially because they cannot push through schema friction with intuition
+
+Topics:
+- [[design-dimensions]]
+- [[note-design]]

package/methodology/schema field names are the only domain specific element in the universal note pattern.md

@@ -0,0 +1,46 @@
+---
+description: The five-component note architecture (prose-title, YAML frontmatter, body, wiki links, topics footer) is domain-invariant — only the YAML field names change between research, therapy, learning, and
+kind: research
+topics: ["[[design-dimensions]]", "[[note-design]]"]
+methodology: ["Original"]
+source: [[arscontexta-notes]]
+---
+
+# schema field names are the only domain specific element in the universal note pattern
+
+The note architecture has five structural components: a prose-sentence title, YAML frontmatter, a body that develops reasoning, wiki links that invoke other notes, and a topics footer that anchors the note in the navigation hierarchy. When you examine these components across radically different knowledge domains — research synthesis, therapy journaling, relationship tracking, project management, language learning — every component works identically except one. Since [[note titles should function as APIs enabling sentence transclusion]], titles are always claims that function as prose when linked — they serve as callable abstractions regardless of whether the domain is research or therapy. The bodies always develop reasoning with connective words. The wiki links always create graph edges. The topics footer always connects upward to MOCs. Only the YAML frontmatter changes, and within the frontmatter, only the field names.
+
+Research uses `methodology`, `source`, `classification`, and `adapted_from`. A therapy system uses `trigger`, `pattern_type`, `coping_strategy`, and `session_date`. A relationship tracker uses `person`, `interaction_type`, `follow_up`, and `last_confirmed`. A student's learning system uses `domain`, `mastery_level`, `prerequisites`, and `review_date`. The base fields — `description`, `topics`, and `type` — are universal across all of them. Domain-specific fields extend the base, and that extension is the entire surface area of domain adaptation for the note format.
+
+This matters because it reveals how narrow the domain-specific channel actually is. Since [[knowledge systems share universal operations and structural components across all methodology traditions]], eight operations and nine structural components recur in every viable system — but at the note format level, the universality is even more extreme than the system level suggests. Since [[ten universal primitives form the kernel of every viable agent knowledge system]], the kernel defines what never varies — markdown files, wiki links, MOCs, descriptions, topics, validation, semantic search, self space, session rhythm. This claim sharpens that insight by identifying precisely WHERE domain knowledge enters the note format: not in the structural pattern, not in the linking convention, not in the navigation hierarchy, but exclusively in the metadata field names. The note pattern functions like a protocol with a fixed header format and a variable payload — the header (title, body structure, link format, topics) is the protocol, and the YAML field names are the payload that carries domain semantics.
+
+The parallel to the processing pipeline deepens this. Since [[every knowledge domain shares a four-phase processing skeleton that diverges only in the process step]], domain specificity enters the pipeline through exactly one phase. The note pattern mirrors this: domain specificity enters the note through exactly one component. Both architectures locate universality in the structural frame and confine domain variation to a single, well-defined insertion point. The processing skeleton varies at the process step. The note pattern varies at the YAML schema. Everything else is shared infrastructure.
+
+This has direct consequences for system derivation. Because the universal components constitute roughly 80% of the note pattern's architecture, deriving a knowledge system for a new domain does not mean designing a new note format. It means inheriting the universal pattern and designing the domain-specific YAML extension. Since [[schema fields should use domain-native vocabulary not abstract terminology]], this design step is not trivial — the field names carry the entire burden of domain adaptation, so getting them wrong means the system fails to speak the practitioner's language despite its structurally sound architecture. A therapy system with `antecedent_conditions` instead of `triggers` has the right pattern but the wrong vocabulary, and because the field names are the ONLY domain-specific surface, that vocabulary failure is felt at every interaction. There is no structural adaptation to compensate for linguistic mismatch.
+
+The implication for composable architecture is equally significant. Since [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]], modules can vary the domain-specific element independently without disturbing the universal pattern. A `therapy-schema` module contributes its domain fields to the YAML frontmatter. A `research-schema` module contributes different fields. Because [[module communication through shared YAML fields creates loose coupling without direct dependencies]], these domain-specific fields serve double duty: they carry domain semantics for the practitioner while simultaneously functioning as inter-module coordination signals that other modules read without knowing about each other. Both modules sit on the same universal base — same titles, same body format, same wiki links, same topics. And since [[multi-domain systems compose through separate templates and shared graph]], multi-domain composition works precisely because the shared graph operates on universal components (wiki links, MOC hierarchy) while templates isolate the only thing that varies (field names). The graph layer never sees domain-specific fields; it traverses through titles, links, and topics, all of which are domain-invariant.
+
+Since [[progressive schema validates only what active modules require not the full system schema]], the validation layer can handle this cleanly because it only needs to scope which field names to check — the structural validation (does the note have a title, body, links, topics?) is universal and always applies, while field-specific validation (is `methodology` a valid enum value?) applies only when the relevant domain module is active. The narrow domain-specific surface means progressive validation has a clean boundary: universal structure is always validated, domain fields are validated conditionally.
+
+There is a shadow side to this universality claim. It assumes that domain knowledge truly restricts itself to metadata and does not reshape body structure, linking conventions, or navigation patterns. But a therapy system might need temporal sequences in the body that research notes never use. A project management system might need decision trees that therapy journals would never contain. A creative writing vault might use wiki links to represent character relationships in ways that research synthesis never would. These domain-specific body patterns do not fit in YAML frontmatter — they operate at the content level, not the metadata level. The claim that only field names vary is accurate for the structural frame but may understate how domain knowledge infiltrates the body text and linking semantics. The resolution is that these body-level variations are stylistic rather than structural: the body is always prose that develops reasoning, even if the reasoning takes different forms across domains. The wiki links always create graph edges, even if the edges mean different things. The structural pattern holds; the content within the pattern varies — but content variation is not structural variation. This resolution has cognitive grounding: since [[the vault methodology transfers because it encodes cognitive science not domain specifics]], each structural component maps to a cognitive operation — titling encodes working memory chunking, body prose encodes elaborative reasoning, wiki links encode associative memory — and these cognitive operations are domain-invariant. The reason the structural pattern holds across therapy, research, and project management is that cognition itself does not change when the subject matter does.
+
+---
+---
+
+Relevant Notes:
+- [[ten universal primitives form the kernel of every viable agent knowledge system]] — foundation: the kernel defines the invariant base layer, and this claim explains WHY it stays invariant — the note pattern itself is universal, with domain specificity entering only through metadata field names
+- [[every knowledge domain shares a four-phase processing skeleton that diverges only in the process step]] — parallel structure: the processing skeleton is universal with domain-specific divergence at the process step, while the note pattern is universal with domain-specific divergence at the YAML schema; both identify the single narrow channel through which domain knowledge enters an otherwise universal architecture
+- [[schema fields should use domain-native vocabulary not abstract terminology]] — downstream consequence: because field names ARE the domain-specific element, getting their vocabulary right matters disproportionately; this note explains WHY domain-native vocabulary is critical — the field names carry the entire burden of domain adaptation
+- [[multi-domain systems compose through separate templates and shared graph]] — architectural implication: because everything except field names is universal, multi-domain composition works by varying templates (which define field names) while sharing the graph layer (which uses the universal components)
+- [[progressive schema validates only what active modules require not the full system schema]] — enables graceful handling of the domain-specific element: since only field names vary, progressive validation can scope to the active domain's fields without needing to understand the domain itself
+- [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]] — the mechanism that exploits this universality: composable modules work because they can vary the domain-specific element (field names) independently while inheriting the universal pattern unchanged
+- [[knowledge systems share universal operations and structural components across all methodology traditions]] — extends: the eight operations and nine components are universal across traditions; this note sharpens that to the note format specifically, showing the fixed/variable boundary falls at YAML field names
+- [[note titles should function as APIs enabling sentence transclusion]] — structural parallel: the protocol/payload framing parallels the API framing — titles are function signatures (domain-invariant), bodies are implementations, and both models explain why four of five components resist domain variation
+- [[the vault methodology transfers because it encodes cognitive science not domain specifics]] — cognitive grounding: the reason four components are domain-invariant is that they encode cognitive operations (titling as chunking, body as elaborative reasoning, wiki links as associative memory) rather than domain semantics
+- [[module communication through shared YAML fields creates loose coupling without direct dependencies]] — architectural consequence: the domain-specific field names simultaneously carry domain semantics AND inter-module coordination signals, making the single domain-specific channel also the system's communication bus
+- [[maintenance operations are more universal than creative pipelines because structural health is domain-invariant]] — operational consequence: maintenance checks the invariant components this note identifies (title structure, link targets, topics presence, body format) rather than the domain-specific YAML fields, which explains why maintenance transfers completely across domains
+- [[dense interlinked research claims enable derivation while sparse references only enable templating]] — upstream dependency: derivation-readiness requires atomic composability at the note level, and the universal note pattern this note identifies is what makes notes atomically composable across domains — the invariant components compose while only YAML fields adapt
+
+Topics:
+- [[design-dimensions]]
+- [[note-design]]

package/methodology/schema fields should use domain-native vocabulary not abstract terminology.md

@@ -0,0 +1,47 @@
+---
+description: When schema field names match how practitioners naturally think — "triggers" not "antecedent_conditions" — adoption succeeds because the system speaks the user's language rather than requiring
+kind: research
+topics: ["[[design-dimensions]]", "[[note-design]]"]
+methodology: ["Original", "Capture Design"]
+source: [[knowledge-system-derivation-blueprint]]
+---
+
+# schema fields should use domain-native vocabulary not abstract terminology
+
+A therapist thinks in terms of "triggers," "coping strategies," and "session reflections." An abstract knowledge system asks for "antecedent_conditions," "intervention_methods," and "processing_notes." Both might capture the same information, but the therapist will fill the first set of fields reliably and abandon the second. The vocabulary gap is not cosmetic — it is the primary adoption barrier for derived knowledge systems, because every interaction with the system forces a translation step that erodes trust and increases cognitive load.
+
+This is an extension of the principle that since [[schema templates reduce cognitive overhead at capture time]], pre-defined fields shift decisions from design to execution. But schema templates can reduce structural overhead while simultaneously increasing linguistic overhead if the field names require mental translation. A therapist confronted with `antecedent_conditions:` must first recall what that means in their professional vocabulary, then translate their thinking into the system's terms, then fill the field. Each translation step consumes working memory that should be directed at content. Domain-native vocabulary eliminates this translation entirely — when the field says "triggers," the therapist can fill it from their natural professional thinking without detour.
+
+The scope of this principle extends well beyond field names. Since [[every knowledge domain shares a four-phase processing skeleton that diverges only in the process step]], the universal pipeline — capture, process, connect, verify — provides structure that every derived system inherits. But the names attached to each phase should speak the domain's language. A therapy system should call its process step "pattern recognition" or "insight extraction," not "claim extraction." A project management system should call it "decision documentation," not "synthesis." The skeleton is universal; the vocabulary wrapping it is domain-specific. This applies to MOC section headings too: a therapist's navigation says "Key Patterns" where this vault says "Core Ideas," and a project manager's says "Decisions" where this vault says "Claims." The structural function is identical, but the vocabulary must match how the domain practitioner naturally organizes their thinking.
+
+The anti-pattern is well-documented: generic abstract terminology causes users to misunderstand fields, fill them inconsistently, or abandon the system entirely. Inconsistent filling is particularly insidious because since [[metadata reduces entropy enabling precision over recall]], the entire information-theoretic justification for YAML frontmatter depends on consistent field values enabling precision-first retrieval. If some therapists interpret "antecedent_conditions" as triggers and others as environmental factors, the field becomes un-queryable — not because the data is missing, but because it means different things across entries, destroying the entropy reduction that metadata is designed to achieve. Domain-native vocabulary constrains interpretation naturally because practitioners share a professional vocabulary that carries agreed-upon scope.
+
+Since [[narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging]], there might seem to be a tension between domain-native vocabulary and personal vocabulary. Narrow folksonomy says the operator's idiosyncratic terms are optimal for retrieval. Domain-native vocabulary says the field's professional terms are optimal for adoption. But these operate at different levels. Schema field names are structural — they define the slots that content fills, and they must be immediately legible to any domain practitioner using the system. The content within those fields can be personal vocabulary, specific to the operator's conceptual distinctions. A therapist's "triggers" field might contain entries phrased in their own therapeutic language ("rejection sensitivity activation" rather than the textbook "abandonment schema trigger"), and that personal vocabulary within the domain-native schema is exactly the narrow folksonomy optimization at work. The schema speaks the domain's language; the content speaks the operator's.
+
+Since [[derivation generates knowledge systems from composable research claims not template customization]], vocabulary adaptation is what distinguishes genuine derivation from template distribution wearing a different label. A template might change folder names and call itself "customized." Real derivation reshapes every linguistic surface — field names, phase names, section headings, error messages, instructions — to match the target domain's natural vocabulary. When [[novel domains derive by mapping knowledge type to closest reference domain then adapting]], the adaptation step must include this vocabulary translation: mapping beekeeping to a project-health hybrid means replacing "sprint" with "inspection cycle," "milestone" with "seasonal goal," "stakeholder" with "colony," and "health metric" with "brood pattern assessment." Each substitution is a semantic mapping, not a find-and-replace, because the concepts may differ in scope even when they occupy the same structural role.
+
+The deeper implication is that vocabulary carries ontology — and because [[false universalism applies same processing logic regardless of domain]], vocabulary mismatch is often the visible symptom of a deeper operational mismatch. A therapy system that renames "claim extraction" to "insight extraction" but keeps the same decomposition logic has fixed the vocabulary while preserving the wrong operations. When a system uses "antecedent_conditions," it implicitly asserts that therapy operates through abstract causal chains. When it uses "triggers," it acknowledges the embodied, experiential reality of therapeutic work. The vocabulary choice is not neutral — it shapes how the practitioner conceptualizes their domain within the system. Domain-native vocabulary respects the ontology that the domain has already developed through practice, rather than imposing an abstracted ontology derived from systems theory. This is why vocabulary mismatch causes abandonment rather than mere annoyance: the practitioner feels the system doesn't understand their work, and that feeling is correct — the abstract vocabulary literally fails to encode the domain's conceptual distinctions.
+
+There is a shadow side. Domain-native vocabulary makes cross-domain comparison harder, and since [[multi-domain systems compose through separate templates and shared graph]], this cost materializes concretely when multiple domains coexist in one graph. The composition rules require field name prefixing to avoid conflicts — `project_status` versus `therapy_status` — which is the direct consequence of each domain using vocabulary native to its practitioners. This vault can query `rg '^methodology: Zettelkasten'` across all notes because it uses a shared vocabulary. If a therapy system uses "pattern recognition" and a research system uses "claim extraction" for structurally identical operations, cross-system analysis requires a translation layer that maps domain vocabularies back to structural functions. This translation is necessarily semantic rather than mechanical, for the same reason that since [[platform adapter translation is semantic not mechanical because hook event meanings differ]], adapter translation between agent platforms must decompose quality guarantees rather than rename events — concepts may differ in scope even when they occupy the same structural role, so vocabulary mapping must reason about meaning, not just substitute labels. The abstraction that domain-native vocabulary rejects at the user interface level may be necessary at the meta-analysis level. The resolution is layered vocabulary: domain-native at the surface where practitioners interact, abstract at the meta layer where systems are compared and analyzed. This vault's own practice reflects this — "Core Ideas" is the vault's domain vocabulary for what a generic system might call "primary entries," and cross-vault comparison would need to recognize that equivalence.
+
+This layered approach also has a temporal dimension. Since [[schema evolution follows observe-then-formalize not design-then-enforce]], the domain-native vocabulary itself should emerge through observation rather than upfront specification. When practitioners manually add fields with their own terminology — a therapist writing `triggers:` in free-text notes before any schema defines it — that organic vocabulary IS the domain-native signal the evolution protocol watches for. The evolution signals (manual field additions, placeholder stuffing, patterned free text) are more legible precisely because domain-native vocabulary matches natural professional thinking, making genuine usage distinguishable from compliance theater.
+
+---
+---
+
+Relevant Notes:
+- [[schema templates reduce cognitive overhead at capture time]] — foundation: domain-native vocabulary is a specific mechanism for reducing capture overhead, extending the general principle from structural scaffolding to linguistic fit
+- [[narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging]] — complementary vocabulary claim: narrow folksonomy optimizes vocabulary for the operator's mental model, this note optimizes vocabulary for the domain's mental model; both reject generic terminology for the same retrieval reason
+- [[derivation generates knowledge systems from composable research claims not template customization]] — the process that must honor this principle: derivation traverses claims to compose systems, and vocabulary adaptation is a mandatory step that distinguishes genuine derivation from template copying
+- [[novel domains derive by mapping knowledge type to closest reference domain then adapting]] — the adaptation step where vocabulary translation happens: mapping beekeeping to project-health hybrid includes reshaping every surface label from project vocabulary to apiary vocabulary
+- [[every knowledge domain shares a four-phase processing skeleton that diverges only in the process step]] — the skeleton that domain-native vocabulary wraps: capture-process-connect-verify is universal, but the names used for each phase should speak the domain's language
+- [[multi-domain systems compose through separate templates and shared graph]] — surfaces the cross-domain cost: when multiple domains use domain-native vocabulary, field name conflicts and cross-domain querying require the prefixing and translation layer that the shadow side of this note predicts
+- [[schema evolution follows observe-then-formalize not design-then-enforce]] — temporal partner: domain-native vocabulary specifies what fields should be called while evolution protocol specifies when to formalize them; the observe-then-formalize signals (manual additions, placeholder stuffing) are more legible when vocabulary matches the practitioner's natural language
+- [[platform adapter translation is semantic not mechanical because hook event meanings differ]] — structural parallel: both argue that translation across system boundaries must be semantic because surface-level equivalence hides meaning differences; vocabulary mapping between domains is the schema analog of event meaning mapping between platforms
+- [[metadata reduces entropy enabling precision over recall]] — downstream effect: domain-native vocabulary enables the consistent field values that make metadata an effective entropy reducer, because vocabulary mismatch causes inconsistent filling that degrades the precision metadata is designed to provide
+- [[eight configuration dimensions parameterize the space of possible knowledge systems]] — the schema density dimension this note constrains: dense schemas amplify the cost of vocabulary mismatch because each abstractly-named field forces a translation step, so density and vocabulary quality are coupled
+- [[false universalism applies same processing logic regardless of domain]] — the deeper disease that vocabulary mismatch is a symptom of: renaming 'claim extraction' to 'insight extraction' fixes the vocabulary while preserving the wrong operations; vocabulary adaptation without operational adaptation is cosmetic derivation
+
+Topics:
+- [[design-dimensions]]
+- [[note-design]]