[awf] ledger guidance: comment-backed storage missing from agent authoring guide

Open Beginner friendly
#11,612 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, yaml
Domain
documentation

Research direction

Start by reading .github/aw/ledger.md and note every Git-specific claim (branch, commits, clone/push, compaction, 1024-file limit), then compare against the comment-backed schema in pkg/parser/schemas/main_workflow_schema.json (see the tools.ledger.<name>.storage: comment-memory and tools.comment-memory entries) and the trust/queue/capacity section of docs/src/content/docs/specs/repo-memory-ledger-specification.md. Scope the Git statements, add a working comment-backed example with its required target configuration and per-backend limits, and note that switching storage does not migrate history. Done when the guide compiles as documented config and the added guidance check rejects claims that all ledgers use a Git branch.

Written by the indexing model from the issue text.

Description

awf-triage

Problem

The agent authoring guide .github/aw/ledger.md presents Git branch storage (ledgers/<name> branch, commits, clone/push, compaction, 1024-file limit) as universal. Since tools.ledger.<name>.storage: comment-memory was added (commit 910cd8c), agents may choose or describe the wrong backend.

Context

Original issue: github/gh-aw#77571 (feature ID ledger.storage-comment-memory).

Root Cause

The guide was written before the comment backend existed and was not updated. Its Git-specific statements are not scoped to Git-backed ledgers. The schema (pkg/parser/schemas/main_workflow_schema.json) and human docs already cover comment storage, so the gap is limited to agent-facing guidance.

Proposed Solution

  • P1: Update .github/aw/ledger.md with a valid comment-backed example, the required tools.comment-memory target configuration, deferred persistence, and per-backend limits (no compaction, smaller history).
  • P2: Explain the Git vs. comment choice. State that changing storage does not migrate existing ledger history. Link docs/src/content/docs/specs/repo-memory-ledger-specification.md for trust, queue, and capacity limits.
  • P2: Add a guidance check that compiles the documented comment-backed configuration and fails on claims that all ledgers use a Git branch.

Generated by Firewall Issue Dispatcher · copilot · routed: haiku55 xhigh · ~2 AIC · ⊞ 3K · ◷

Dominant language
TypeScript
Stars
165
Forks
84
Avg merge
5h 57m
Merged PRs (30d)
390

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/gh-aw-firewall

All issues in github/gh-aw-firewall

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.