Phase 260: apply public HACP protocol docs packet - #23
Merged
Conversation
BYOK Configuration Required! 🔑Your plan requires a Bring Your Own Key (BYOK) configuration to perform code reviews. Please configure your API keys in Settings > BYOK Configuration. |
Reviewer's GuideAdds public-facing HACP protocol framing docs and clarifies authority/validation boundaries across README and schema/example docs, plus new focused docs on glossary, lifecycle, authority boundaries, adapters/projections, and an owner-controlled bridge workflow. Sequence diagram for owner-controlled HACP bridge workflowsequenceDiagram
actor Owner
participant HACP_CLI
participant Runner
participant HACP_App
Owner->>HACP_CLI: npx hacp packet fetch
HACP_CLI-->>Owner: TaskPacket
Owner->>Runner: TaskPacket
Runner-->>Owner: AgentReport + EvidenceSet
Owner->>HACP_CLI: npx hacp report submit
HACP_CLI->>HACP_App: report submit
HACP_App->>HACP_App: report.import_verifier_checked
HACP_App-->>Owner: human_decision_required
Owner->>HACP_App: HumanDecision / StopReason
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation establishing HACP's public protocol framing: authority boundaries, event lifecycle, glossary, and an example owner-controlled bridge workflow. It clarifies that HACP provides contracts for accountable delegation without executing work or granting authority directly, and specifies what protocol constructs (packets, reports, decisions, verification) do and do not guarantee. ChangesProtocol Framing and Authority Boundaries
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
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 docstrings
🧪 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 |
Review Summary by QodoAdd public HACP protocol documentation and authority boundary clarifications
WalkthroughsDescription• Adds comprehensive public HACP protocol documentation covering glossary, event lifecycle, and authority boundaries • Establishes vendor-neutral framing emphasizing human-approved coordination and explicit authority checkpoints • Clarifies that transport, adapters, and verification do not grant authority or prove completion • Documents owner-controlled bridge workflow and adapter/projection positioning within protocol Diagramflowchart LR
A["README.md<br/>Protocol Framing"] --> B["docs/glossary.md<br/>Core Contracts"]
A --> C["docs/event-lifecycle.md<br/>Lifecycle Events"]
A --> D["docs/authority-boundaries.md<br/>Authority Rules"]
A --> E["docs/adapters-and-projections.md<br/>Transport & Read Models"]
A --> F["docs/workflows/owner-controlled-bridge.md<br/>Example Workflow"]
B --> G["schemas/README.md<br/>Schema Authority Boundary"]
C --> G
D --> G
File Changes1. README.md
|
Code Review by Qodo
1.
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- There is a fair bit of repetition around the “verification is custody/integrity, not completion proof” and “transport does not grant authority” statements across multiple docs; consider centralizing the canonical wording in one section (e.g.,
authority-boundaries.md) and referencing it from other pages to reduce drift risk. - The lifecycle/event names described in
docs/event-lifecycle.mdand the glossary appear in other docs as prose (e.g., “import verifier checks”); consider standardizing on the exact event identifiers everywhere and linking back to the lifecycle doc to keep terminology unambiguous.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- There is a fair bit of repetition around the “verification is custody/integrity, not completion proof” and “transport does not grant authority” statements across multiple docs; consider centralizing the canonical wording in one section (e.g., `authority-boundaries.md`) and referencing it from other pages to reduce drift risk.
- The lifecycle/event names described in `docs/event-lifecycle.md` and the glossary appear in other docs as prose (e.g., “import verifier checks”); consider standardizing on the exact event identifiers everywhere and linking back to the lifecycle doc to keep terminology unambiguous.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for the Human-Approved Coordination Protocol (HACP), including details on authority boundaries, event lifecycles, adapters, projections, and a glossary. The review feedback focuses on improving terminology consistency and standardizing abbreviations. Specifically, it is recommended to update references from StopReason to StopResponse to align with the schema definitions, and to correct the abbreviation of OpenTelemetry to OTel instead of OTEL.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@README.md`:
- Around line 18-20: Update README to remove the contradiction by choosing one
maturity framing and making both statements match: replace the assertive
sentence "HACP is a vendor-neutral..." with a qualifying version such as "HACP
aims to be vendor-neutral pending independent implementations and audits" (or
alternatively change the later caution to affirm vendor-neutrality) and make the
other occurrence ("should not be described as vendor-neutral yet") consistent
with that chosen wording so both top-level description and the later caveat
convey the same maturity position.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 109ac6ce-fb2b-4f75-a9ab-81f866839cfc
📒 Files selected for processing (8)
README.mddocs/adapters-and-projections.mddocs/authority-boundaries.mddocs/event-lifecycle.mddocs/glossary.mddocs/workflows/owner-controlled-bridge.mdschemas/README.mdschemas/examples/README.md
Owner
Author
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ca87963a87
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR adds public-facing HACP protocol documentation (glossary, lifecycle, authority boundaries, adapters/projections, and a bridge workflow) and updates top-level and schema/example docs to more explicitly state that validation/transport provide custody evidence but never confer execution or approval authority.
Changes:
- Add new protocol docs under
docs/(glossary, event lifecycle, authority boundaries, adapters/projections, and an owner-controlled bridge workflow). - Update
README.mdwith “Public Protocol Framing” and “HACP Is / Is Not” sections linking to the new docs. - Clarify in
schemas/README.mdandschemas/examples/README.mdthat schema checks/fixtures/transport validate contract shape and custody evidence only (not completion or authority).
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| schemas/README.md | Adds explicit “Authority Boundary” section and reinforces that schema validation is shape-only and non-authoritative. |
| schemas/examples/README.md | Clarifies what fixtures prove vs. do not prove (including custody vs. completion/authority) and reiterates transport non-authority. |
| README.md | Adds public protocol framing and links to the new docs; clarifies non-claims and authority boundaries. |
| docs/workflows/owner-controlled-bridge.md | Introduces an owner-controlled bridge workflow description and example transport paths. |
| docs/glossary.md | Adds public-safe glossary for core objects, lifecycle terms, and boundary terms. |
| docs/event-lifecycle.md | Summarizes lifecycle event names for packet/report/decision/stop. |
| docs/authority-boundaries.md | Documents mandatory authority boundary statements and non-claims. |
| docs/adapters-and-projections.md | Positions adapters/projections as transport/read-model layers that never confer approval authority. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
BYOK Configuration Required! 🔑Your plan requires a Bring Your Own Key (BYOK) configuration to perform code reviews. Please configure your API keys in Settings > BYOK Configuration. |
BYOK Configuration Required! 🔑Your plan requires a Bring Your Own Key (BYOK) configuration to perform code reviews. Please configure your API keys in Settings > BYOK Configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
joefeser/hacpdocs onlyPacket alignment
HumanDecisionas required for risky authority transitionsValidation
npm run hacp:doctor -- schemas/examples --manifest schemas/examples/manifest.jsongit diff --checkSummary by Sourcery
Document public HACP protocol framing, lifecycle, and authority boundaries, and clarify that validation, transport, and adapters handle custody but never grant execution or approval authority.
Documentation:
Summary by CodeRabbit
Note
Add public HACP protocol documentation covering authority boundaries, adapters, and lifecycle
docs/covering authority boundaries, adapters and projections, event lifecycle labels, a glossary, and an owner-controlled bridge workflow.Macroscope summarized 28d6d69.