From 246ad92ef2dda153e0f32a1f3d665318d7205ae3 Mon Sep 17 00:00:00 2001 From: davidfsol5 Date: Thu, 4 Jun 2026 13:12:06 -0400 Subject: [PATCH] docs: Add Working Model and Local Guidance Convention to CLAUDE.md Captures the evolving conceptual model of polycentric knowledge processing refined through Experiments 1-3: Working Model: - Polycentricity vs Distribution distinction - The Seam: shared referent IRIs enabling join without collapse - Sharing as Projection: 4-field model (include_types, stub_types, edge_predicates, exclude_nodes) - Non-Collapse Invariant: perspectives must remain distinct - Operational principles: immutable input, reproducible experiments, heterogeneous deployment, "just enough" sharing Local Guidance Convention: - Two-tier system: version-controlled CLAUDE.md + local .claude/CLAUDE.md - Semantics: scope, inheritance, precedence rules - Coherence checks on commit/PR with promotion path - Purpose: engineering room for working models before team consumption Also updates .gitignore to use **/.claude/ pattern for nested directories. Co-Authored-By: Claude Opus 4.5 --- .gitignore | 3 ++- CLAUDE.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index db71a12..973ddd6 100644 --- a/.gitignore +++ b/.gitignore @@ -62,7 +62,8 @@ Thumbs.db # Claude Code tmpclaude-* -.claude/ +# Local guidance directories (at any level per Local Guidance Convention in CLAUDE.md) +**/.claude/ # Design working files designs/tmp/ diff --git a/CLAUDE.md b/CLAUDE.md index 875e625..0d8645b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -195,3 +195,79 @@ docker-compose -f instances/instance-b/docker-compose.yml down - Each instance has isolated data (changes in A don't appear in B) - Authentication works independently on each instance - API calls to each instance return independent results + +## Working Model + +This section captures the evolving conceptual model of polycentric knowledge processing as refined through experimentation. It supplements the Project Overview with operational insights. + +### Core Concepts + +#### Polycentricity vs Distribution +- **Polycentric:** Orchestration over heterogeneous instances, each maintaining its own "center" (autonomy, authority, perspective) +- **Distributed:** Orchestration over homogeneous instances with merged/blurred centers +- The system must accommodate genuinely heterogeneous infrastructure (cloud + local, different auth mechanisms, different operators) + +#### The Seam +A *seam* is a set of shared referent IRIs that allow join across perspectives without collapsing them: +- **Common referents** (e.g., actant IRIs) are shared across instances unchanged +- **Divergent readings** live in *perspective-scoped* structures (e.g., characterizations grouped by `ant:withinNetwork`) +- No `owl:sameAs`, no alignment predicates, no new terms required — the existing data patterns support "common referents, distinct readings" + +When designing polycentric scenarios, ask: *"What are the common referents (the seam) and what are the perspective-scoped structures that carry the divergent readings?"* + +#### Sharing as Projection +Sharing is a *projection mechanism* operating over any RDF vocabulary, not a transfer of complete graphs: +- **4-field projection model:** `include_types`, `stub_types`, `edge_predicates`, `exclude_nodes` +- **Named profiles** (e.g., `DISCOURSE_EVIDENCE_PROFILE`, `ANT_COMPARISON_PROFILE`) are configurations of this mechanism +- **Stub types** enable "identity without payload" — share that something exists and what it's called, without leaking prose/detail + +#### Non-Collapse Invariant +When two perspectives share referent IRIs, they must remain distinct after merge/comparison: +- Exactly N perspectives, N networks (no unintended merged entity) +- Shared referents may be characterized in multiple perspectives (distinguishable by scope) +- Comparisons are *views*, not new canonical artifacts — no merged perspective is written back + +### Operational Principles + +1. **Ontology/data as immutable input:** The system adapts to existing data patterns rather than requiring data to be reshaped. Observations about data shape are recorded as *findings*, not patches. + +2. **Experiments as reproducible artifacts:** Each experiment includes a README (repro guide), captured run logs, and findings (including operational issues). This supports knowledge accumulation. + +3. **Heterogeneous deployment is first-class:** Configuration must accommodate diverse auth mechanisms (bearer token, LDAP), multi-tenant services (`FLEXO_ORG_NAME`), and mixed local/cloud topologies. + +4. **"Just enough" sharing:** Policies express minimal sufficient projection — full export, stub (identity only), or excluded — enabling trust boundaries between collaborating centers. + +### Model Evolution + +This working model is refined through experimentation. Key sources: +- **Experiments 1-3** (PR #1, `polycentric-experiments` branch): Validated ontology-agnostic sharing, the seam pattern, and non-collapse verification +- **Design specs:** `docs/superpowers/specs/` contains detailed reasoning behind model decisions + +## Local Guidance Convention + +This project uses a two-tier guidance system for Claude Code: + +### Version-Controlled Guidance +- `CLAUDE.md` — Authoritative, team-shared guidance +- Applies to the file's directory and all descendants +- Takes precedence on conflict with local guidance + +### Local Guidance +- `.claude/CLAUDE.md` — Local working notes, not version-controlled +- `.claude/` directories are gitignored +- Supplements (does not override) version-controlled guidance +- May exist at any directory level for scope-specific notes + +### Semantics +- **Scope:** Guidance applies to the directory containing the file and all subdirectories +- **Inheritance:** Nested guidance accumulates (child adds to parent) +- **Precedence:** On conflict, version-controlled wins; within tier, more specific (closer to leaf) wins + +### Coherence Checks +Local guidance should be checked for coherence with team guidance: +- **On commit:** Review local guidance against changed scope for incompatibilities +- **On PR:** Review for drift between local and team-wide guidance +- **Promotion:** When local insights prove coherent and valuable, promote to version-controlled `CLAUDE.md` + +### Purpose +Local guidance provides engineering room for working models before they're ready for team consumption. Knowledge processing is inherently lossy — local guidance stays local until it demonstrates coherence, avoiding noise in the team view.