Notes Protocol

Squad state has two layers:

1. Git notes layer (this document) — thin, commit-scoped annotations that attach agent context to commits without appearing in PRs or diffs.
2. Permanent state layer — long-lived decisions, routing rules, and archives stored via the configured state backend (git-notes or orphan branch).

Agents write notes during their work rounds. Ralph promotes flagged notes to permanent state after a PR merges.

Namespaces

Each agent writes to its own namespace to prevent conflicts:

Rule: Only write to your own namespace. The shared namespaces (research, review) use append — never add.

Note JSON Schema

All notes MUST be valid JSON. Minimum required fields:

Decision notes

Set "promote_to_permanent": true to signal Ralph to copy this to decisions.md after the PR merges.

Research notes

Set "archive_on_close": true to signal Ralph to archive this to state/research/ even if the PR is rejected.

Write Commands

Or use the helper script:

Fetch / Push

Notes are NOT fetched or pushed by default. Every clone needs setup.

One-time setup

Or use the helper:

Every work round

1. Start: git fetch origin 'refs/notes/*:refs/notes/*'
2. End: git push origin 'refs/notes/*:refs/notes/*'

Conflict Handling

1. Per-agent namespaces prevent 99% of conflicts. Only one agent writes to refs/notes/squad/data, so there are no write conflicts in normal use.

2. Same agent, two machines: First push wins. Losing machine should fetch and append:

   bashCopy

   git fetch origin 'refs/notes/*:refs/notes/*'
   git notes --ref=squad/{agent} append -m '{...}' HEAD
   git push origin 'refs/notes/*:refs/notes/*'

3. Shared namespaces (research, review): Always use git notes append, never git notes add.

4. Push conflict recovery:

   bashCopy

   git fetch origin 'refs/notes/*:refs/notes/*'
   git notes merge refs/notes/remotes/origin/squad/{namespace}
   git push origin 'refs/notes/*:refs/notes/*'

When to Use Notes vs State Backend

When in doubt: notes first, promote to permanent state later. Ralph handles the promotion automatically when promote_to_permanent is set.

Ralph Promotion Rules

After PR merge:

1. Fetch all notes from remote
2. Traverse commits reachable from the default branch that have notes
3. For each note with "promote_to_permanent": true → append to decisions.md
4. Push state

After PR close/rejection:

1. List notes in squad/research on the closed branch’s commits
2. For each note with "archive_on_close": true → archive to research/
3. Push state
4. Notes on rejected commits are NOT promoted — this is the desired behavior