Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

docs: Add Working Model and Local Guidance Convention #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davidfsol5 wants to merge 1 commit into main
base: main
Choose a base branch
Loading
from working-model-guidance
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/
76 changes: 76 additions & 0 deletions CLAUDE.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

AltStyle によって変換されたページ (->オリジナル) /