[awf] ledger guidance: comment-backed storage missing from agent authoring guide
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
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.mdwith a valid comment-backed example, the requiredtools.comment-memorytarget 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.mdfor 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/gh-aw-firewall
-
code-quality refactoring
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
github/gh-aw-firewall#11797 ·
Maintainers usually reply within 1 day
-
agentic-workflows automated dependencies
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
github/gh-aw-firewall#3837 ·
Maintainers usually reply within 1 day
-
agentic-workflows
Difficulty 3/5 1-2 days Newbie friendliness 48/100
github/gh-aw-firewall#11802 ·
Maintainers usually reply within 1 day
-
automation otel smoke-test tracing
Difficulty 1/5 Under an hour Newbie friendliness 1/100
github/gh-aw-firewall#11801 ·
Maintainers usually reply within 1 day
-
automation otel smoke-test tracing
Difficulty 3/5 1-2 days Newbie friendliness 68/100
github/gh-aw-firewall#11800 ·
Maintainers usually reply within 1 day
All issues in github/gh-aw-firewall
Similar issues
-
bug documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Potential Bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Comfy-Org/ComfyUI_frontend#23773 ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 85/100
lingdojo/kana-dojo#34301 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
code-yeongyu/senpi#7007 ·
Maintainers usually reply within 1 day
-
area/renderer bug plugin/echarts priority/P3
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day