Clearing System
The Clearing is Musewoods' semantic context system. It addresses the gap between having excellent canonical artifacts and understanding how those artifacts fit together. Stories, Journals, Viewgraphs, and Groves continue to own editorial work. Clearing sits across those fields and records the typed relationships, provenance, lineage, tensions, evidence, and open questions that make a subject intelligible as a territory rather than merely searchable as a set of documents.
The normative editorial concept lives in The Clearing. This Field Manual page defines where the capability belongs in the platform architecture and how future implementation should preserve existing Musewoods boundaries. At the time of this Guide revision, Clearing is a design contract: the semantic model is specified, but the package must not claim runtime registries, loaders, APIs, or validators until those exist in the codebase.
Do not confuse this system-wide semantic layer with the older Trailhead v1 compatibility feature called Clearings (lib/resonance/trailhead/schema.mjs, dwell: "clearing" in the v1 spine). That bounded feature allows at most two secondary content references a v1 Path can offer as a place to dwell before continuing. It remains valid legacy grammar, but it is neither the v2 dwell semantic role nor the cross-corpus Clearing context system this page describes.
Where Clearing Sits
Clearing is analogous to Resonance in one architectural respect and different in purpose. Both begin from canonical objects rather than becoming a fifth publishing field. Resonance asks how an inquiry travels outward to readers. Clearing asks what a subject means when its canonical artifacts are seen together.
Figure 1
Rendering diagram…
The important rule is that neither system owns the canonical editorial object. A Journal that challenges a thesis remains a Journal. A Viewgraph that illustrates an architecture remains a Viewgraph. A Grove may serve as the durable human-facing projection of a Clearing because it already provides identity, navigation, local assets, Ground, and living structure, but its publishing-field identity remains grove.
The Semantic Contract
| Dimension | Question |
|---|---|
| Meaning | What is this? |
| Question | What made it necessary? |
| Origin | Where did it come from? |
| Actors | Who or what inhabits this territory? |
| Conditions | What must be true for it to work? |
| Tensions | What competing forces shape it? |
| Evidence | What supports, weakens, or exemplifies it? |
| Relations | What does it connect to, and how? |
| Frontier | What remains unresolved? |
These dimensions are semantic responsibilities, not compulsory visual sections. The future renderer should compose from the dimensions a subject genuinely needs. The Context Package should preserve them in a machine-readable form so a Grove projection, Context Map, search surface, or intelligent agent does not need to reconstruct the territory independently.
Typed Relationships
bounded-vocabulary
The first registry should remain small and useful: lineage relations such as originates-from and precedes; explanatory relations such as explains and illustrates; evidence relations such as supports, challenges, and provides-evidence-for; development relations such as extends, refines, and operationalizes; dependency relations such as depends-on, enables, and constrains; and exploration relations such as explores and contrasts-with.
reciprocal-context
If a Journal declares that it challenges a thesis, the Journal owns the explicit declaration and the thesis Clearing can receive the reciprocal view during graph resolution. Authors should not have to maintain the same semantic fact in two places.
provenance
The system should distinguish authored, reciprocal, structural, temporal, and inferred context. An inferred relationship may be useful as a candidate, but it should never render or reason with the same standing as an authored relationship unless an explicit governance step promotes it.
The Context Package
The stable implementation target is a subject-centered Context Package rather than a particular visual graph. It should contain canonical orientation plus resolved origins, actors, conditions, tensions, evidence, typed relations, Frontier, participating artifacts, and edge provenance. Human and machine projections consume that package; they do not each own their own semantic resolver.
{
"subject": "converged-enterprise",
"kind": "thesis",
"status": "developing",
"meaning": "...",
"question": "...",
"origins": [],
"actors": [],
"conditions": [],
"tensions": [],
"evidence": [],
"relations": [],
"frontier": [],
"artifacts": []
}Implementation Boundary
Do not add a fifth field
There should be no Clearing column in the publishing-field capability matrix and no need to move canonical work into a new field root. If implementation begins by copying Story, Journal, Viewgraph, or Grove content into a Clearing directory, the architecture is already drifting.
Build semantics before visualization
Define identifiers, relationship registry, reciprocal rules, provenance, validation, and the Context Package before building a rich Context Map. The map should be one projection of stable semantics rather than the place where semantics accidentally live.
Keep inference subordinate to governance
Similarity and language models may suggest context, but the graph must retain provenance and allow inferred edges to remain candidates. The platform may help discover meaning; it should not silently author it.
Let Grove provide the durable place
When a subject needs a human-facing Clearing, Grove is the natural projection surface. A Clearing-aware Grove may eventually receive assembled context from the semantic layer while preserving the normal Grove shell, navigation, Ground, assets, and field identity.
Validation When Implemented
| Condition | Expected treatment |
|---|---|
| unknown semantic target | source-oriented build error |
| unsupported relationship | build error; never coerce silently to generic related |
| duplicate authored edge | normalize or warn according to provenance |
| reciprocal-rule conflict | registry error |
| genuine authored disagreement | preserve as contested context rather than auto-resolve |
| inferred edge rendered as canonical | validation/projection failure |
| living Clearing with no Frontier | editorial warning |
System Health should begin reporting Clearing capability only after these registries and validators exist in the implementation. Until then, this page and the normative Clearing Grove describe the intended boundary, not a shipped capability count.