Skip to content

feat: two-layer state backend (git-notes + orphan combined) #1013

Description

@tamirdresher

The Two-Layer Architecture (from blog)

PR #1004 implements git-notes and orphan as separate backends. But the blog post describes them working together as a two-layer architecture:

Layer 1: Git Notes (commit-scoped "why" annotations)
  - Per-agent namespaces: refs/notes/squad/{agent}
  - Thin JSON attached to specific commits
  - Invisible in PR diffs
  - Agents write here during sessions

Layer 2: Orphan Branch (permanent state store)  
  - decisions.md, agent histories, logs
  - The "team diary" — full state
  - Ralph promotes important notes here after PR merge

Ralph bridges the layers:
  - After PR merges, scans notes with promote_to_permanent: true
  - Promotes to decisions.md on orphan branch
  - Notes on rejected PRs are silently ignored (desired behavior)

Why this matters

The blog describes 3 scenarios that break naive solutions:

  1. Rejected feature — decision on a rejected PR should NOT be promoted
  2. Universal truth — routing change on a rejected PR SHOULD survive
  3. Valuable failure — research worth keeping even when feature is rejected

The two-layer architecture handles all three via promote_to_permanent and archive_on_close flags on notes. Single-backend approaches can't distinguish these cases.

What to implement

  • Add stateBackend: "two-layer" option in config.json
  • When two-layer: agents write commit-scoped notes (layer 1) AND Scribe commits bulk state to orphan (layer 2)
  • Ralph promotion: after PR merge, scan notes with promote_to_permanent: true, append to orphan branch decisions.md
  • Ralph archival: after PR close (rejected), scan notes with archive_on_close: true, archive to orphan branch
  • Notes on rejected PRs without flags: silently ignored (correct behavior)

Reference

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or improvement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions