Strategy: spec solution-shared context git remote

[pewpewpotato]

Problem

We need a signed strategic/architecture spec for solution-scoped shared context: N code repos → one context git remote, without a second VCS.

Who it’s for

Agents (MCP), humans reviewing context on GitHub, multi-repo solution teams.

Normative baseline (signed + amended 2026-09-19)

#	Constraint
G1	Overlapping agent edits → human-reviewed PR; no silent overwrite
G2	Every agent write → short-lived branch + PR (amended — not push-to-working-branch)
G3	Migration = best-effort one-shot .spl → context git; no dual-run; no Rack wire-compat
G4	Assets: Git LFS above 512 KiB default (configurable); text/JSON/TOML stay plain git with warn above ~1 MiB
L1	Binding: explicit bind file in each code repo → shared context remote; MCP refuses writes until bound; no auto-discovery
L2	Onboarding: spl context init --remote <url> creates layout/schema, seeds CodeRepository from binds
L3	Projection: rebuild from git on every MCP/process start; local only; never committed
L4	Identity: node IDs namespaced by code repo; files stay flat under nodes/ / edges/
L5	Auth: stock git credentials only
L6	Export keep/drop: keep nodes, edges, schema, assets; drop packs, Rack remotes, reflogs, merge leases, projections; lossy OK

Architecture (normative)

Direction

Git is the sole durable SoT for solution context. Spool is the MCP/CLI tool that validates mutations, writes human-diffable files, commits via stock git, and rebuilds a local projection for fast query. Rack and .spl-as-SoT are out of the happy path.

Solution model

• One context git remote per solution; N code repos bind to it
• Graph is solution-flat (cross-repo edges first-class)
• Provenance via repo-namespaced IDs + CodeRepository nodes — not path-siloed trees

Binding

Explicit file in each code repo, e.g. .spool/context.toml:

solution_id = "my-solution"
remote = "https://github.com/org/my-solution-context.git"
protected_branch = "main"

Unbound → mutations fail closed. No auto-discovery.

Context repo layout

/
  schema.toml
  nodes/<id>.json
  edges/<id>.json
  assets/<hash>[/name]
  README.md

Not in repo: projection DBs, .spl packs, Rack config, reflogs, merge leases.

Write plane

1. Validate mutation batch
2. Apply as JSON/assets
3. Short-lived branch → commit (one batch = one commit) → open PR to protected branch
4. Overlaps → humans resolve via PR

Projection

Rebuild from current git checkout on every MCP/process start. Local cache only — never committed/pushed/remoted. Git wins on correctness.

Onboarding

spl context init --remote <url>: ensure remote reachable, create layout/schema if empty, seed CodeRepository from binds, ready for first MCP write (branch+PR).

Assets

Default LFS 512 KiB (configurable). Text/JSON/TOML plain git; warn ~>1 MiB.

Migration (one-shot)

Keep nodes/edges/schema/assets; drop packs/Rack remotes/reflogs/merge leases/projections. Named export/migrate-once (not sync). Lossy OK.

Non-goals

Spool-as-VCS; Rack wire-compat; per-code-repo context remotes; path-siloed graphs; syncing projections; Spool-specific auth/protocol; replacing git for source code.

Acceptance criteria

• Spec documents one context remote per solution and explicit bind (no auto-discovery; refuse unbound writes)
• Spec defines layout (nodes/, edges/, schema/, assets/) and repo-namespaced IDs with flat files
• Spec states projection rebuild-on-process-start (local only, never SoT)
• Spec records gates G1–G4 as amended (esp. every write = branch+PR)
• Explicit non-goals listed above

Downstream

Issue	Uses this
#100	MCP write path, PR-every-write, projection rebuild-on-start
#104	Bind file + retire .spl/Rack SoT
#102	Export keep/drop
#103	LFS defaults
#101	Docs/stop-list messaging

Owner

Spool Architect

[pewpewpotato]

Architecture spec — solution-shared context git remote (v1)

Status: Architect intake for #99
Baseline: signed strategy brief + gap locks (2026-09-19), including amended gate #2 (every agent write → short-lived branch + PR).

This spec is normative for #100, #104, #102, #103. Issue body AC that still mention “push clean writes to a working branch” or “projection watermark on pull/commit” are superseded by the locks below.

---

1. Problem & direction

Shared context across many code repos must not require a second VCS (.spl + Rack). Git is the sole durable source of truth for solution context. Spool is the MCP (and CLI) tool that validates graph mutations, writes human-diffable files, commits via stock git, and rebuilds a local projection for fast query. Rack and .spl-as-SoT are out of the happy path.

---

2. Normative constraints (signed gates + gap locks)

#	Constraint
G1	Overlapping agent edits → human-reviewed PR; no silent overwrite
G2	Every agent write uses a short-lived branch and opens a PR (amended — not push-to-working-branch for “clean” writes)
G3	Migration = best-effort one-shot .spl → context git; no dual-run; no Rack wire-compat
G4	Assets: Git LFS above 512 KiB default (configurable); text/JSON/TOML stay plain git with warn above ~1 MiB
L1	Binding: each code repo has an explicit bind file pointing at the shared context remote; MCP refuses writes until bound; no auto-discovery
L2	Onboarding: spl context init --remote <url> creates layout/schema, seeds CodeRepository from binds, ready for first MCP write
L3	Projection: rebuild from git on every MCP/process start; local only; never committed to the context repo
L4	Identity: node IDs namespaced by code repo; files stay flat under nodes/ / edges/ (no repos/<name>/… silos)
L5	Auth: stock git credentials only (HTTPS/SSH / helper) — no Spool tokens
L6	Export keep/drop: keep nodes, edges, schema, assets; drop packs, Rack remotes, reflogs, merge leases, projections; document lossy OK

---

3. Solution model

• One context git remote per solution (product/system), not per code repo.
• N code repos bind to that remote.
• Graph is shared across the solution so agents can traverse cross-repo relationships.
• Provenance uses repo-namespaced IDs (and CodeRepository nodes as needed), not path-siloed trees.

[code repo A]──bind──┐
[code repo B]──bind──┼──► [context git remote]  = SoT
[code repo C]──bind──┘         ▲
                               │ stock git (clone/fetch/push/PR)
                         [Spool MCP]
                               │
                         [local projection]  rebuild on process start

---

4. Binding (N → 1)

Mechanism: explicit file in each code repo, e.g. .spool/context.toml:

solution_id = "my-solution"
remote = "https://github.com/org/my-solution-context.git"
# optional: default protected branch name
protected_branch = "main"

Rules:

• Spool resolves bind from the code repo (or workspace override that still names the same remote).
• Unbound → MCP/CLI mutations fail closed with a clear error.
• Bind file is reviewed in the code repo like any other config.
• No discovery from directory names, monorepo heuristics, or Rack leftovers.

Detailed bind UX / retire-.spl path: #104.

---

5. Context repository layout

Human-diffable, PR-friendly:

/
  schema.toml          # or schema/ — solution schema
  nodes/<id>.json      # one node per file
  edges/<id>.json      # one edge per file
  assets/<hash>[/name] # blobs; LFS when over threshold
  README.md            # optional human orientation

Not in the context repo: projection DBs, .spl CAS packs, Rack config, reflogs, merge leases.

Branching: protected branch (usually main) is the integration line. Agents never push straight to protected; see §7.

---

6. Identity & provenance

• Node/edge IDs are namespaced by code repo (stable, unique within the solution), e.g. conceptually repo-key / local-id encoded into a single ID string — exact encoding left to implementation, but must be unambiguous and collision-safe across repos.
• Files remain under flat nodes/ and edges/ (ID → filename mapping must be filesystem-safe).
• CodeRepository nodes represent each bound code repo; use for listing/membership and optional richer provenance links.
• Optional aliases (e.g. repo:path:symbol) may exist as non-authoritative labels/properties — not a second ID space that forks the graph.
• Cross-repo edges are first-class (solution-flat). Do not invent repos/<name>/nodes/… trees.

---

7. Write / review plane (MCP → git)

Owned in depth by #100; normative here:

1. Validate mutation batch against schema/invariants.
2. Apply to working tree as JSON (and assets with LFS policy).
3. Create a short-lived branch, commit (one mutation batch → one git commit), open a PR into the protected branch.
4. No silent overwrite on overlapping paths/IDs — overlap → humans resolve via PR.
5. Sync/history/review = stock git/GitHub only.

---

8. Projection (query acceleration)

• Purpose: fast search/filter/context assembly.
• Lifecycle: rebuild from the current git checkout on every MCP/process start (chosen over watermark-cached staleness for v1 simplicity/trust).
• Location: local cache directory only — never committed, pushed, or remoted.
• Correctness: git history/files win; projection is disposable.
• Suggested shape may reuse SQLite/FTS ideas from today’s spool, re-homed onto git checkout — implementation detail for Strategy: MCP writes to context git + derived projections #100.

---

9. Onboarding

spl context init --remote <url>:

1. Ensures context remote is reachable with stock git auth.
2. Creates layout + default permissive schema if empty.
3. Seeds CodeRepository nodes from known binds.
4. Leaves the repo ready so the first MCP write can open a short-lived branch + PR.

No Rack-like bootstrap or Spool-specific sync daemon.

---

10. Assets

• Default LFS threshold: 512 KiB (configurable).
• Text/JSON/TOML: plain git; warn if above ~1 MiB.
• Asset graph nodes point at content-addressed paths under assets/.

Details: #103.

---

11. Migration (one-shot)

• Entrypoint clearly named export/migrate-once (not “sync”).
• Keep: nodes, edges, schema, assets (then LFS policy).
• Drop: packs, Rack remotes, reflogs, merge leases, projections.
• Success output lists landed vs skipped; docs: lossy OK; re-run = overwrite-at-own-risk.
• Must not configure Rack as a side effect.

Details: #102.

---

12. Non-goals

• Spool as a general/distributed VCS or Rack-hosted context sync plane
• .spl CAS as durable SoT
• Per-code-repo context remotes / path-siloed graphs
• Rack pack wire-compat
• Replacing git for source code
• Syncing or publishing projections
• Spool-specific auth or remote protocols for context

---

13. Downstream handoff

Issue	Uses this spec for
#100	MCP write path, PR-every-write, projection rebuild-on-start
#104	Bind file format + retire .spl/Rack SoT happy path
#102	Export keep/drop list
#103	LFS threshold defaults
#101	Docs/stop-list messaging

Architect sign-off: this comment is the v1 architecture baseline for #99 AC. PO/TL may tick AC when satisfied; Engineer unblocked for #100 planning once TL confirms intake of this spec.

— Spool Architect

[pewpewpotato]

PO AC alignment (amended signed baseline — supersedes earlier body wording where it conflicts):

• Explicit bind file in each code repo → shared context remote (no auto-discovery); MCP refuses writes until bound
• spl context init --remote creates layout/schema, seeds CodeRepository from binds, ready for first MCP commit
• Node IDs namespaced by code repo; files stay flat under nodes/ / edges/ (no path silos)
• Every agent write → short-lived branch + PR (gate Bump actions/checkout from 4 to 7 #2 amend — not push-clean-to-working-branch)
• Projection rebuild on every MCP/process start; local only; never committed to context repo
• LFS default 512 KiB (configurable); text/JSON/TOML stay plain git with warn above ~1 MiB
• Export keep/drop + lossy OK as in Architect locks
• Auth = stock git only

Architect’s #99 spec comment is the normative detail for intake.