docs(spec): add glossary and format ADRs#3
Conversation
|
Warning Review limit reached
More reviews will be available in 48 minutes and 57 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThis pull request adds foundational specification documentation for the Agent Trail format. It introduces a shared glossary, establishes schema.json as the canonical contract, defines file envelope and multi-segment session structures, and specifies reconciliation semantics and extensibility policies through eight architecture decision records. ChangesAgent Trail Specification Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Ready to review this PR? Stage has broken it down into 3 individual chapters for you:
Chapters generated by Stage for commit 1d3b235 on Jun 12, 2026 6:40pm UTC. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0002-trail-envelope-and-two-tier-identity.md`:
- Around line 9-10: The term "file label" is undefined and ambiguous in the
trail envelope description (the `type:"trail"` record); either add a concise
definition for "file label" in this ADR clarifying whether it is a human-facing
display name, a unique envelope identifier, or a schema/key field, or replace
every occurrence of "file label" with the existing, precise term used elsewhere
in the spec (e.g., "envelope id" or "display name") and update the
`type:"trail"` record description accordingly so implementers know its purpose
and format.
In `@docs/adr/0005-session-bundles-and-child-sessions.md`:
- Around line 11-19: The field name fork_from.session_id is ambiguous vs the
per-artifact "session id" (session_uid); rename or explicitly define it as a
durable parent-session reference (e.g., parent_session_id or parent_header_id)
and update the JSON example and glossary text to state that this identifier is
an Agent Trail durable header id (not the runtime session_uid), while runtime
IDs remain in metadata/source.raw; ensure you also mention entry_id and
content_hash are optional and that this parent_session_id represents the durable
parent session identifier family to avoid implementer confusion.
In `@docs/adr/0008-enum-extensibility-policy.md`:
- Around line 13-15: Update the ADR wording for the extensible vocabulary list
to clarify that the `agent.name` slot accepts either a canonical registry value
or a vendor-namespaced extension of the form `x-<vendor>/<name>`; explicitly
state the two-part contract (registered canonical names vs. opaque passthrough
for `x-...` extensions) and mirror the same grammar/reader behavior language
used for other slots like `scope` and `system_event.kind` so readers treat
unknown `x-<vendor>/<name>` `agent.name` values as opaque strings that are
passed through.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 6895c990-70f3-4c6f-84ed-1e56c3efaa21
📒 Files selected for processing (10)
README.mddocs/GLOSSARY.mddocs/adr/0001-schema-json-is-the-format-contract.mddocs/adr/0002-trail-envelope-and-two-tier-identity.mddocs/adr/0003-multi-segment-session-primitives.mddocs/adr/0004-segment-reconciliation-and-event-id-policy.mddocs/adr/0005-session-bundles-and-child-sessions.mddocs/adr/0006-context-compact-replaced-message-provenance.mddocs/adr/0007-v0.1-draft-hardening-decisions.mddocs/adr/0008-enum-extensibility-policy.md
1 participant
Pull Request
Summary
docs/GLOSSARY.md.docs/adr/.Related Issue
Public Impact
Impact description:
Verification
rg -n "GitHub issue|github issue|#[0-9]+|Closes|Tracks|issue|issues|PR" docs/adr- no matches.rg -n "Parser Source Matrix|Local store|Finalized object|Index|redaction-patterns" docs/GLOSSARY.md- no matches.rg -n "ADR-000[1-8]" docs/adr docs/GLOSSARY.md README.md- confirms compact ADR references.mise run check- passed.Reviewer Notes