mandel-macaque/memento/git-memento-workflow

Git Memento Workflow

Run this workflow whenever work must be committed with an AI session note.

1. Preflight

• Confirm repository status with git status --short and branch with git branch --show-current.
• Confirm git memento is available: git memento help.
• If unavailable, install git-memento into a directory on PATH and re-check.

2. Initialize Once Per Repository

• Check configuration: git config --local --get memento.provider.
• If missing, run git memento init codex or git memento init claude.
• If provider CLI shape differs from expected sessions get/list --json, configure adapter command in local git config:
• git config --local memento.<provider>.bin <adapter-or-cli-path>
• git config --local memento.<provider>.getArgs '<args with {id} placeholder>'
• git config --local memento.<provider>.listArgs '<list args>'
• For summary mode, configure provider summary execution if defaults do not match your environment:
• git config --local memento.<provider>.summary.bin <adapter-or-cli-path>
• git config --local memento.<provider>.summary.args '<args with {prompt}, optionally {skill} and {sessionId}>'

3. Resolve Session ID

• Prefer explicit session id from the user.
• For Codex in this environment, default to CODEX_THREAD_ID when present.
• Validate retrieval before commit by running provider command manually if needed.

4. Create Memento Commit or Amend

• Stage files as needed (git add ...).
• Run commit through memento so note attachment happens in the same flow:
• git memento commit <session-id> -m "<subject>"
• Optional summary mode: git memento commit <session-id> --summary-skill <skill|default> -m "<subject>"
• For amend flows:
• git memento amend -m "<amended-subject>" to carry forward existing note(s) onto the amended commit.
• git memento amend <session-id> -m "<amended-subject>" to carry forward existing note(s) and append a new session.
• Optional summary mode: git memento amend <session-id> --summary-skill <skill|default> -m "<amended-subject>"
• Summary mode behavior:
• The CLI generates a markdown summary using the configured provider command.
• It prints the generated summary and requires explicit confirmation.
• If rejected, it asks for a user prompt and regenerates.
• It writes the summary into refs/notes/commits and stores the full session in refs/notes/memento-full-audit.
• Backward compatibility:
• Legacy single-session notes are preserved.
• When append is needed, legacy notes are upgraded into the versioned multi-session envelope so no prior session content is lost.
• For longer body, use embedded newlines in -m or omit -m to use editor.

5. Verify Note Attachment

• Read latest commit: git log -1 --pretty=fuller.
• Show note on that commit: git notes show <commit-hash>.
• For multi-session notes, expect envelope/version headers and separators:
• <!-- git-memento-sessions:v1 -->
• <!-- git-memento-note-version:1 -->
• <!-- git-memento-session:start -->
• <!-- git-memento-session:end -->
• Summary mode stores summary entries in refs/notes/commits and full sessions in refs/notes/memento-full-audit.
• In summary mode, verify both refs:
• git notes show <commit-hash> (summary note)
• git notes --ref refs/notes/memento-full-audit show <commit-hash> (full session)
• If note is missing, inspect provider command config and rerun commit flow after fixing.

6. Push Code and Sync Notes

• Push commit branch and sync notes in one step: git memento push <remote>.
• For default remote, run git memento push.
• Optional fallback: git push <remote> <branch> then git memento share-notes <remote>.
• Verify notes exist remotely: git ls-remote <remote> 'refs/notes/*'.
• notes-sync, notes-rewrite-setup, and notes-carry preserve both refs/notes/commits and refs/notes/memento-full-audit.

7. Failure Handling Checklist

• git-memento is not configured: run git memento init ....
• Provider command fails: verify memento.<provider>.* git config and executable permissions.
• Session not found: list sessions using provider list command and retry with exact id.
• Note push missing on remote: rerun git memento push <remote> (or git memento share-notes <remote>) and confirm remote ref output.