---
id: SHARD-WP-0012
type: workplan
title: "second adapter — git-IS-store shard (contract validation on a new substrate)"
domain: whynot
repo: shard-wiki
status: done
owner: tegwick
topic_slug: whynot
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - SHARD-WP-0007
  - SHARD-WP-0008
state_hub_workstream_id: "9e24eeb0-c0f0-41e6-a1ca-88d71e4139ea"
---

# SHARD-WP-0012 — git-IS-store shard adapter

## Goal

Add a **second adapter on a different substrate** to validate the contract beyond the plain
folder: a **git-IS-store** shard (`FederationArchitecture` T17 / TSD §A.3 — the home case where
git is the store *and* the journal). It exercises git-native history (TSD §A.5 *adopt*),
commit-as-write, `current_rev`=commit-sha drift detection, and the implication rules
(attachment=git-IS-store ⟹ substrate=git ∧ history=git-native). Proves "writing an adapter +
declaring a verified profile" is all it takes — no core changes.

**Non-goal:** remote push/pull federation (VCS-replication+ping is a federation workplan);
merge beyond fast-forward (apply-under-drift refuse is enough, as in SHARD-WP-0008).

## Context

- Contract: `TechnicalSpecificationDocument.md` §A; binding taxonomy §A.3; history §A.5.
- Reuses the existing contract/conformance/overlay machinery unchanged.

---

## GitShardAdapter — read over a git working tree/repo

```task
id: SHARD-WP-0012-T1
status: done
priority: high
state_hub_task_id: "8a1c7c80-a0cc-4e02-a611-1f1fd7dec57b"
```

A `GitShardAdapter` reading Markdown from a git repo: keys = tracked `*.md` paths; `read`
returns a `Page` whose `source_rev` is the **commit sha** (HEAD or blob commit); profile =
git-IS-store / substrate=git / history=git-native / addressing=path, validated against the
implication rules. Tests: read tracked files; profile validates; conformance read path passes.

## Write = commit; current_rev = sha (drift)

```task
id: SHARD-WP-0012-T2
status: done
priority: high
state_hub_task_id: "b47dfb86-46c1-4e97-a62f-377719499ff2"
```

`write(key, body)` stages + **commits** (author/message), returning the updated `Page` at the
new sha; `current_rev(key)` returns the current commit sha for drift detection. Declare `WRITE`
+ `version`. Tests: write commits; conformance positive-write probe passes; `current_rev`
changes after an external commit.

## History adopt + integration with union/overlay

```task
id: SHARD-WP-0012-T3
status: done
priority: medium
state_hub_task_id: "4c895f42-671d-4948-8bdf-941fd85644bb"
```

Adopt git-native history (TSD §A.5 *adopt*): expose a minimal page history (commit list for a
path) behind a `version`-gated method. Integration: attach a `GitShardAdapter` to an
`InformationSpace` alongside a `FolderAdapter` → resolve/chorus/edit/overlay/apply all work
across substrates (apply-under-drift uses sha rev). Update SCOPE; `pytest` + pyflakes green.

---

## Acceptance criteria

- `GitShardAdapter` passes the conformance suite (read + positive write) with a profile whose
  implication rules hold (git-IS-store ⟹ git substrate + git-native history).
- Write = commit; `current_rev` = sha drives apply-under-drift correctly.
- The union/overlay/edit machinery works unchanged across folder + git shards (no core change —
  capability-as-data proven on a second substrate).
- `pytest` + pyflakes green; each task committed; state-hub synced.

## Notes

If `git` plumbing via subprocess proves heavy for tests, a thin in-repo git helper (or
`tmp_path` repos created in tests) is acceptable; no new runtime dependency — use stdlib +
`git` CLI already present.

## Suggested task order

T1 read adapter + profile → T2 write=commit + current_rev → T3 history adopt + integration.