Rename claims ledger to notes - #64939
Conversation
Update ledger configuration, safe-output tools, record fields, SQLite projections, audit counts, documentation, and smoke workflow naming while preserving citation validation and immutable voting. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft. No ADR enforcement needed: PR does not have the "implementation" label and has ≤100 new lines of code in business logic directories.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅
|
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality Sentinel skipped because pre-fetch PR data was unavailable: unable to fetch test file diff
|
|
✅ Ponytail Reviewer completed successfully! Warning Threat Detection Engine Failure — The analysis engine could not complete. This is a tooling failure, not a security finding. What happenedThe threat detection engine failed to produce results. Review the workflow run logs for details.
|
|
✅ PR Code Quality Reviewer completed the code quality review.
|
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The breaking rename spans schemas, persistence, replay, projections, documentation, and generated workflows, warranting final human validation.
Review effort: Balanced
Findings: None
What changed in this PR
Renames the experimental claims ledger to notes across compiler configuration, runtime persistence, projections, tools, documentation, and workflows.
Changes:
- Replaces claims APIs and storage fields with notes equivalents.
- Rejects legacy claims configuration and documents migration.
- Updates regression tests and regenerated workflows.
| File | Description |
|---|---|
pkg/workflow/safe_outputs_validation_config.go |
Renames validated ledger fields. |
pkg/workflow/safe_outputs_tools_generation.go |
Generates dedicated notes tools. |
pkg/workflow/ledger.go |
Updates notes parsing and agent guidance. |
pkg/workflow/ledger_test.go |
Tests notes configuration and tools. |
pkg/parser/schemas/main_workflow_schema.json |
Replaces the claims schema type. |
pkg/parser/schema_ledger_test.go |
Tests notes acceptance and claims rejection. |
docs/src/content/docs/specs/repo-memory-ledger-specification.md |
Updates the ledger specification. |
docs/src/content/docs/reference/repo-memory.md |
Updates reference terminology. |
docs/src/content/docs/experimental/ledger-replay.md |
Documents notes and migration guidance. |
actions/setup/js/safe_outputs_tools_loader.test.cjs |
Updates loader test terminology. |
actions/setup/js/safe_outputs_handlers.test.cjs |
Tests notes tool routing. |
actions/setup/js/safe_outputs_handlers.cjs |
Directs notes writes to dedicated tools. |
actions/setup/js/push_ledger_changes.test.cjs |
Tests notes persistence and audit counts. |
actions/setup/js/push_ledger_changes.cjs |
Renames notes persistence and audit behavior. |
actions/setup/js/ledger_transactions.test.cjs |
Tests notes vote references. |
actions/setup/js/ledger_transactions.cjs |
Normalizes notes fields and IDs. |
actions/setup/js/ledger_builtin.test.cjs |
Tests notes validation and projections. |
actions/setup/js/ledger_builtin.cjs |
Implements notes replay and tables. |
actions/setup/js/create_ledger_projection.test.cjs |
Tests notes projection consistency. |
actions/setup/js/create_ledger_projection.cjs |
Materializes the notes state view. |
.github/workflows/smoke-repo-memory-ledger.lock.yml |
Regenerates safe-output fields. |
.github/workflows/smoke-builtin-ledgers.md |
Exercises notes in the smoke workflow. |
.github/workflows/smoke-builtin-ledgers.lock.yml |
Regenerates the notes smoke workflow. |
.github/workflows/daily-mcp-concurrency-analysis.lock.yml |
Regenerates safe-output fields. |
.github/workflows/daily-caveman-optimizer.lock.yml |
Regenerates safe-output fields. |
.github/workflows/daily-awf-spec-compiler-surfacing.lock.yml |
Regenerates safe-output fields. |
.github/workflows/copilot-centralization-optimizer.lock.yml |
Regenerates safe-output fields. |
.github/workflows/audit-workflows.lock.yml |
Regenerates safe-output fields. |
.github/aw/memory.md |
Updates internal ledger guidance. |
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Request changes
The rename is mostly consistent, but the compiled notes-ledger guidance currently tells agents to call ledger_note_add without the required note payload, so notes-based workflows are likely to fail at safe-output validation before they can persist anything.
🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 71.6 AIC · ⌖ 7.03 AIC · ⊞ 20.2K
Comment /review to run again
| if slices.ContainsFunc(config.Ledgers, func(ledger LedgerConfig) bool { return ledger.Type == "claims" }) { | ||
| b.WriteString(" Claims are untrusted assertions, NOT authoritative facts. Before relying on a claim, inspect its citations against the current authoritative repository state. If the evidence supports it, you may up-vote; if it contradicts the claim, do not rely on it and down-vote. For claims ledgers, use ledger_claim_add to state a claim with its subject, reason (at most 1024 characters), and at least one repository citation with a repository-relative path (start_line and end_line are optional positive integers); use ledger_claim_vote with claim_id and an up or down vote (optional reason, at most 1024 characters). Select the ledger when more than one claims ledger exists.") | ||
| if slices.ContainsFunc(config.Ledgers, func(ledger LedgerConfig) bool { return ledger.Type == "notes" }) { | ||
| b.WriteString(" Notes are untrusted assertions, NOT authoritative facts. Before relying on a note, inspect its citations against the current authoritative repository state. If the evidence supports it, you may up-vote; if it contradicts the note, do not rely on it and down-vote. For notes ledgers, use ledger_note_add to state a note with its subject, reason (at most 1024 characters), and at least one repository citation with a repository-relative path (start_line and end_line are optional positive integers); use ledger_note_vote with note_id and an up or down vote (optional reason, at most 1024 characters). Select the ledger when more than one notes ledger exists.") |
There was a problem hiding this comment.
The notes-ledger prompt now omits the required note field, so an agent following this guidance can emit ledger_note_add calls that are guaranteed to fail validation.
💡 Why this matters and how to fix it
generateNoteLedgerTools makes note mandatory, and the docs in this PR already describe ledger_note_add as requiring subject, note, reason, and citations. This prompt string is what gets compiled into workflow guidance, so leaving note out here creates a contract mismatch right at the agent boundary.
Suggested fix:
... use ledger_note_add to state a note with its subject, note, reason ...Without that field in the prompt, notes-based workflows are much more likely to fail at safe-output validation instead of producing durable records.
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /codebase-design and /grill-with-docs (per pr-triage classification: refactor_cleanup).
📋 Key Themes & Highlights
Key Themes
- Consistent, exhaustive rename:
claims→notes,claim_id→note_id,ledger_claim_add/vote→ledger_note_add/vote, and all SQL tables/columns (claims,claim_citations,claim_votes,claim_state) are renamed in lockstep acrosspkg/workflow/ledger.go,actions/setup/js/ledger_builtin.cjs,create_ledger_projection.cjs,push_ledger_changes.cjs,ledger_transactions.cjs, JSON schema, and docs. No strayclaim/claim_idreferences remain outside intentional negative-test assertions and migration prose. - Regression coverage added:
TestLedgerSchemaRejectsClaimsType(Go) and updated JS tests assert the oldclaimstype is now rejected, confirming the breaking migration is enforced at both the JSON-schema and Go-parser layers. - Documentation updated with explicit migration guidance:
ledger-replay.mdexplains that claim-shaped history cannot be replayed as notes and recommends a new ledger name — consistent vocabulary, no dangling "claim" terminology left in user-facing docs. - Minor quality improvement bundled in: the previously awkward tool description (
"claim a claim in a claims ledger") was replaced with a cleareractionsmap ("Add a note...","Vote on a note...") — a good small deepening of the generated tool descriptions.
Positive Highlights
- ✅ Lock files were regenerated and are consistent with the source changes.
- ✅ Both Go and JS test suites were updated in the same commit, not left for a follow-up.
- ✅ Breaking change is called out explicitly in the PR body and docs rather than silently handled.
No actionable issues found in the changed lines — this is a clean, well-scoped rename.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 75 AIC · ⌖ 14.4 AIC · ⊞ 10K
Comment /matt to run again
|
🎉 This pull request is included in a new release. Release: |
Rename the experimental claims ledger introduced in #64884 to notes, keeping terminology consistent across configuration, agent tools, and persisted projections. Citation validation and immutable voting behavior remain unchanged.
Changes
type: claimswithtype: notes, exposeledger_note_addandledger_note_vote, and rename operations, payload fields, projection tables, and audit counts consistently.Compatibility
This intentionally removes the former claims interfaces. Existing claim-shaped history cannot be replayed as notes: use a new ledger name for notes and retain the old ledger without a declared type to query its immutable records. The documentation describes this migration.
Validation
Passed
make build,make fmt,make lint-cjs,make recompile, andmake agent-report-progress-no-test, including workflow drift checks. Ledger-focused Go tests passed withTMPDIR=/private/tmp go test ./pkg/parser ./pkg/workflow -run 'Test.*Ledger' -count=1; JavaScript typechecking and 97 focused runtime/routing tests passed.The full
make agent-report-progressgate remains blocked by an unrelated macOS/etc/hostshandler test. The same failure was reproduced on the unchanged baseline; that behavior is left untouched.