Git memory: commit messages as the long-term memory layer for agents

[prineycom]

Context

Every yoke run loses its Decision Shadow — the constraints, rejected alternatives, and reasoning that lived in the agent's head when the code was written. Skills start from scratch, with no awareness of previous decisions.

Lore Protocol proposes git commit messages with native trailers as a structured knowledge channel between agents: long-term memory with zero infrastructure — just git.

Revised 2026-07-13 after a grill session. The original plan on this issue (a lore/ skill, a lore-init/ scaffolder, nine trailers, integration into /task and /plan — both deprecated since) is cut down to a minimal evolution of the existing commit convention. Decision record: .yoke/adr/0012-commit-messages-as-git-memory.md; glossary terms Git memory and Decision trailer in .yoke/context.md. The original plan is preserved in this issue's edit history.

Decision (ADR-0012)

The commit message itself is the memory channel. Named Git memory — the "git layer" in the glossary's memory taxonomy (Journal → Artifacts → Git memory). Lore Protocol is the inspiration, not the spec.

Format — hybrid

The existing subject convention stays: TICKET type(SLUG): description. Beneath it, commits that carry a decision get:

1. a prose body explaining why — written for coding agents as the primary readers, since humans rarely look;
2. optional decision trailers from a fixed vocabulary of four: Constraint:, Rejected:, Directive:, Related:.

#86 feat(86-black-jack-page): add SSE endpoint

Polling was dropped: the kiosk network drops idle HTTP/1.1
connections after 30s, SSE with retry survives it. Score state
lives server-side because the client is untrusted.

Rejected: WebSocket — no proxy support on kiosks
Constraint: client is untrusted, never move score calc there
Related: #84

Rules

• Body is required by content, not by type: the test is "will a reader six months out wonder why". Mechanical chore/style commits stay one-liners.
• Trailers are all optional — written only when there is content; greppable via git log.
• The "no trailers" ban narrows to identity trailers (Co-Authored-By, Signed-off-by) — those stay banned.
• The ticket cascade keeps its current softness: no ticket found → commit without one.
• Enforcement is behavioral, never infrastructural (revised 2026-07-14): agents do the committing, so the convention lives in the instructions the committing agent follows — no git hooks, in yoke or in target projects.
• /merge already produces merge commits (never squash), so per-task bodies survive into the default branch.

Changes

Write side

• skills/gca/reference/commit-convention.md — extend: prose-body rules (the "by content" test), the four decision trailers with examples and anti-patterns, narrow the trailer ban to identity trailers
• Verify /do finish and every committing skill still route to the same convention

Read side

• New skills/gca/reference/history-reading.md — read guide: git log -n 10 -- <path>, git log --grep, git blame + git show, trailer-key greps, the %(trailers) pretty-format; which command when; how to act on Constraint:/Directive:/Rejected: findings. (Note: git log --trailer= from the original plan does not exist — the real tools are --grep and %(trailers).)
• Read step — "read the history of the affected files before working" — in all code skills: /do, /draft, /review, /grill, /grill-docs, /prd, /issues

Distribution (bootstrap)

• Compact section (~10–15 lines) in the generated CLAUDE.md of the target project: how to write commits, when to read history — always-on for any agent, with or without yoke skills
• Dogfood: the yoke repo itself adopts the convention

Success criteria

1. Write: commits produced by /do//gca that carry a decision have a prose body; decision trailers appear only when there is content — no ritual trailers on mechanical commits
2. Read: /do, /draft, /review surface Constraint:/Directive:/Rejected: from the history of affected files before working; a rejected approach found in history is not re-proposed without new evidence
3. Distribution: after /bootstrap, a target project has the CLAUDE.md section; manual sessions outside yoke skills get the same guidance

Rejected (see ADR-0012)

The full Lore Protocol as originally specced here: a lore/ skill, a lore-init/ scaffolder, nine trailers (Confidence:, Scope-risk:, Reversibility:, Tested: degrade into ritual self-assessment noise); trailers-only structure (models read prose better than key-value fragments); prose-only bodies (lose the cheap trailer-key grep); a body required always or by type (manufactures water in trivial commits); a commit-msg git hook in any form (shipped in v3.1.0, removed the same day — per-repo hook infrastructure is noise when agents do the committing, and a hook cannot judge content anyway); markdown files as the memory medium (a parallel artifact tree duplicating what git already versions).

References

• ADR: .yoke/adr/0012-commit-messages-as-git-memory.md
• Glossary: .yoke/context.md (Git memory, Decision trailer)
• Lore Protocol paper: https://arxiv.org/html/2603.15566v1
• Git trailers: https://git-scm.com/docs/git-interpret-trailers
• GCC paper: https://arxiv.org/html/2508.00031v1
• DiffMem: https://github.com/Growth-Kinetics/DiffMem

---

Migrated from projectory-com/sp#36.

[ivan-hilckov]

Implemented in PR #34 — write side (commit-convention body + 4 decision trailers), read side (history-reading guide + read step in do/draft/review/grill/grill-docs/prd/issues), bootstrap distribution (mandatory CLAUDE.md section + commit-msg hook), and dogfood (yoke runs the hook itself; the PR's own commits follow the convention). Decision record: .yoke/adr/0012-commit-messages-as-git-memory.md.