Semantic Scope

Semantic Scope

One of the most important architectural principles of Weave Skills became:

semantic scope != filesystem scope

This distinction stabilizes:

• bounded semantics
• filesystem authority
• operational locality
• implementation grounding
• and deterministic contextual behavior

inside real engineering repositories.

Core Principle

Semantic participation remains intentionally bounded.

Recommended semantic root:

.context/notes

Only files inside semantic scope:

• participate in symbolic semantics
• support semantic navigation
• participate in contextual reasoning
• and interact with contextual tooling and overlays

Files outside semantic scope remain:

• filesystem artifacts
• implementation context
• operational resources
• and external references

Why Semantic Scope Exists

Without bounded semantic scope, systems tend to drift toward:

• repository semanticization
• ontology escalation
• graph inflation
• semantic ownership
• and repository-global contextual reasoning

The architecture intentionally avoids these failure modes.

Filesystem Scope vs Semantic Scope

The repository intentionally separates:

Scope	Purpose
Filesystem Scope	Real repository structure
Semantic Scope	Contextual surface

This separation became one of the strongest stabilizers of the architecture.

Filesystem Scope

Filesystem scope includes the entire repository.

Examples:

src/
docs/
tests/
fixtures/
scripts/
.context/

The filesystem preserves:

• implementation locality
• operational relationships
• runtime boundaries
• repository organization
• and workflow continuity

The filesystem remains authoritative.

Semantic Scope

Semantic scope defines the contextual surface used for notes and symbolic navigation.

Recommended semantic root:

.context/notes

Only files inside this boundary participate in:

• symbolic semantics
• wikilinks
• semantic navigation
• contextual continuity
• and operational capabilities

Example Repository

repository/
│
├── src/
├── tests/
├── docs/
├── fixtures/
│
└── .context/
    └── notes/
        ├── websocket-debugging.md
        ├── auth-runtime-analysis.md
        └── reconnect-failure.md

Semantic Participation

In this example:

Path	Semantic Participation
.context/notes/*	Yes
src/*	No
tests/*	No
docs/*	No

Implementation files remain operational resources rather than semantic entities.

Symbolic Semantics

Wikilinks operate as:

bounded symbolic contextual references

Example:

[auth-runtime-analysis](auth-runtime-analysis)

Wikilinks intentionally preserve:

• contextual navigation
• operational continuity
• implementation-aware reasoning
• and locality-preserving reasoning

NOT:

• ontology relationships
• graph-authoritative edges
• semantic ownership structures
• or repository-global semantic primitives

Contextual References Outside Scope

Notes MAY reference implementation artifacts outside semantic scope.

Example:

## reconnect-failure

Related implementation:
- src/runtime/socket.ts
- src/runtime/token-refresh.ts

These references preserve:

• implementation grounding
• operational locality
• and contextual continuity

without converting implementation files into semantic entities.

Why Implementation Files Remain Outside Scope

The architecture intentionally avoids semanticizing the entire repository.

Implementation files remain:

• implementation artifacts
• runtime systems
• operational resources
• and filesystem-native structures

This preserves:

• repository clarity
• implementation locality
• deterministic behavior
• and bounded reasoning

Bounded Contextual Reasoning

The architecture intentionally prioritizes:

bounded contextual reasoning

This means:

• contextual reasoning remains scoped
• symbolic semantics remain localized
• and operational overlays remain bounded

The system intentionally avoids:

• repository-global semantic ownership
• graph-centric reasoning
• ontology-wide contextual traversal
• and semantic escalation

Operational Benefits

Bounded semantic scope improves:

• contextual precision
• operational stability
• implementation grounding
• filesystem locality
• and token efficiency

It also reduces:

• activation ambiguity
• ontology drift
• semantic inflation
• and graph complexity

Example Workflow

Contextual Note

## websocket-runtime-investigation

Observed behavior:
- reconnect occasionally races token refresh
- stale auth state survives reconnect

Related implementation:
- src/runtime/socket.ts
- src/runtime/token-refresh.ts

Related investigations:
 - [auth-runtime-analysis](auth-runtime-analysis)

Operational Result

The note participates in symbolic semantics.

The implementation files remain:

• implementation context
• operational resources
• and filesystem artifacts

This preserves the separation between:

semantic scope

and:

filesystem scope

Relationship To Skills

Skills operate primarily inside semantic scope.

This includes:

• contextual reasoning
• symbolic navigation
• continuity preservation
• and operational capabilities

Skills intentionally DO NOT:

• semanticize repositories
• redefine filesystem ownership
• or convert implementation artifacts into graph primitives

Relationship To Runtime

The runtime preserves:

• semantic boundaries
• canonical structures
• deterministic-safe behavior
• and serializer consistency

Skills and agents perform:

• contextual reasoning
• operational interpretation
• and implementation-grounded inference

inside bounded semantic scope.

Long-Running Operational Continuity

The semantic scope model intentionally supports:

long-running implementation-grounded continuity

while preserving:

• filesystem authority
• operational locality
• deterministic structures
• and bounded contextual behavior

This became one of the strongest convergence points of the architecture.

Architectural Philosophy

The architecture intentionally favors:

small
bounded
filesystem-native
implementation-grounded
operational

rather than:

repository-global
graph-authoritative
ontology-driven
semanticized

Related Documents

• Architecture
• Operational Model
• Runtime Boundaries
• Implementation Tracing
• Workflow Examples