docs: align public HACP docs to Phase 166 readiness packet - #21
Conversation
Reviewer's GuideThis PR updates public HACP documentation to align with the Phase 166 readiness packet by clarifying stability lanes, tightening claims about what the schema examples and fixtures do/do not prove, and wiring the examples corpus guidance into the schemas docs, without introducing any runtime, product-specific, or formal-standard claims. Flow diagram for local hacp:doctor validation against the example corpusflowchart LR
Dev[Developer] -->|npm run hacp:doctor -- schemas/examples/valid| Doctor[hacp:doctor]
Dev -->|npm run hacp:doctor -- schemas/examples/invalid --json| Doctor
Dev -->|npm run hacp:doctor -- schemas/examples --manifest schemas/examples/manifest.json| Doctor
Doctor --> ValidDir[schemas/examples/valid]
Doctor --> InvalidDir[schemas/examples/invalid]
Doctor --> Manifest[schemas/examples/manifest.json]
Doctor --> Output[Validation_output]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughThis PR adds documentation for project maturity guidance and example fixtures. The main README introduces "Stability Lanes" to categorize which project materials are ready to use versus experimental. A new examples/README.md provides comprehensive guidance on the local fixture corpus, including directory structure, manifest usage, what validation proves and does not prove, and exact commands to run validation checks. ChangesDocumentation for Stability Lanes and Example Corpus
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 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 QodoDocument HACP stability lanes and fixture validation boundaries
WalkthroughsDescription• Added explicit stability lanes distinguishing production-ready vs experimental features • Created comprehensive fixture corpus guidance with validation boundaries • Clarified what HACP examples prove and do not prove • Added cross-references between documentation layers Diagramflowchart LR
A["README.md"] -- "adds stability lanes" --> B["Stable vs Experimental"]
C["schemas/README.md"] -- "links to" --> D["schemas/examples/README.md"]
D -- "defines" --> E["Fixture Purpose & Boundaries"]
E -- "clarifies" --> F["What Fixtures Prove/Not Prove"]
File Changes1. README.md
|
Code Review by Qodo
1.
|
Kody Review CompleteGreat news! 🎉 Keep up the excellent work! 🚀 Kody Guide: Usage and ConfigurationInteracting with Kody
Current Kody ConfigurationReview OptionsThe following review options are enabled or disabled:
|
![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:
- In
schemas/examples/README.md, consider briefly documenting the expectedhacp:doctorexit codes (especially for runs overinvalid/and manifest mode) so users know how to interpret success vs expected failure when they follow the commands. - In the top-level
README.md, you might link the new "Stability Lanes" section from the HACP 0.2 draft section (or vice versa) so readers jumping into the draft protocol context are explicitly guided to the stability framing you just introduced.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `schemas/examples/README.md`, consider briefly documenting the expected `hacp:doctor` exit codes (especially for runs over `invalid/` and manifest mode) so users know how to interpret success vs expected failure when they follow the commands.
- In the top-level `README.md`, you might link the new "Stability Lanes" section from the HACP 0.2 draft section (or vice versa) so readers jumping into the draft protocol context are explicitly guided to the stability framing you just introduced.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 a "Stability Lanes" section to the main README to clarify the maturity and intended use of various HACP components. It also adds a new guidance document for the example corpus, detailing its purpose, limitations, and the validation flow using the hacp:doctor tool. A review comment suggests expanding the draft artifact vocabulary list in the README to include missing items like evidence sets and loop policies to ensure the documentation accurately reflects the current draft schema.
|
@copilot review |
|
@codex review |
Reviewed the latest docs commits at |
|
Codex Review: Didn't find any major issues. Keep them coming! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
docs: Align public HACP documentation with Phase 166 readiness guidelines.
This update introduces new documentation to clarify the scope, stability, and limitations of the HACP project and its artifacts:
README.md: Categorizes HACP components into "Stable Enough To Use Now" and "Experimental Or Product-Proven But Not Standardized" to guide external communication and manage expectations regarding the project's maturity.schemas/examples/README.mdprovides detailed explanations for the example fixtures, clarifying their purpose (e.g., schema conformance, contract testing) and explicitly stating what they do not prove (e.g., production safety, autonomous execution, human approval, cross-vendor interoperability).schemas/README.md: References the new example corpus guidance to improve discoverability and provide a comprehensive overview of the schema examples.