diff --git a/README.md b/README.md index c43d116..15564af 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,28 @@ describe an implementation as "HACP compliant" yet; use narrower labels such as "implements the HACP v0.1 draft base profile" and cite the evidence that was checked. +## Stability Lanes + +### Stable Enough To Use Now + +- draft artifact vocabulary for packets, reports, stops, findings, decisions, + evidence sets, and loop policies; +- draft JSON Schema pack for machine-checkable artifact shape and vocabulary; +- valid/invalid example corpus with manifest expectations; +- local `hacp:doctor` validation flow for repeatable draft checks; +- explicit authority boundary language that keeps approval and risk acceptance + human-owned. + +### Experimental Or Product-Proven But Not Standardized + +- product-specific UX/readback and governance workflows; +- cross-vendor interoperability claims without independent implementations; +- any claim that schema validation alone proves operational safety; +- any maturity framing that implies a finalized or ratified standard. + +Use these lanes when describing HACP externally: "working draft with proven +local evidence" is accurate; "formal standard" is not. + ## HACP 0.2 Draft HACP 0.2 is a new experimental protocol draft that frames HACP as a @@ -114,6 +136,9 @@ Start here: HACP 0.2 is not 1.0. It is a draft vocabulary and fixture set for review and independent implementation feedback. +For maturity framing across v0.1 and v0.2, see +[Stability Lanes](#stability-lanes). + ## Public Review The preferred place for early v0.1 feedback is diff --git a/schemas/README.md b/schemas/README.md index e5d7437..7cb3f65 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -65,6 +65,7 @@ the required base evidence list. - Canonical valid examples: [`examples/valid/`](examples/valid/) - Intentional invalid contract tests: [`examples/invalid/`](examples/invalid/) - Corpus inventory manifest: [`examples/manifest.json`](examples/manifest.json) +- Corpus guidance and claim boundaries: [`examples/README.md`](examples/README.md) - Reliability boundary stop example: [`examples/valid/stop-response.reliability-boundary.valid.json`](examples/valid/stop-response.reliability-boundary.valid.json) - Stop response fixture pack: diff --git a/schemas/examples/README.md b/schemas/examples/README.md new file mode 100644 index 0000000..50df7a7 --- /dev/null +++ b/schemas/examples/README.md @@ -0,0 +1,44 @@ +# HACP Example Corpus Guidance + +This folder contains draft HACP fixture artifacts used for local, repeatable +validation checks. These fixtures are protocol documentation assets, not +runtime instructions. + +## Purpose + +- `valid/` fixtures show schema-conforming artifact shapes. +- `invalid/` fixtures are intentional contract-failure examples. +- `manifest.json` declares expected outcomes and metadata used by local checks. + +## What Fixtures Prove + +- whether a fixture conforms to the referenced draft schema; +- whether expected-valid and expected-invalid outcomes match manifest + declarations when manifest-mode checking runs; +- whether artifact vocabulary and basic structure are machine-checkable. + +## What Fixtures Do Not Prove + +- production safety certification; +- autonomous dispatch or execution authority; +- human approval, merge, deploy, or risk acceptance decisions; +- cross-vendor interoperability by themselves. + +## Validation Flow + +Run the local draft checker against this corpus: + +```bash +npm run hacp:doctor -- schemas/examples/valid +npm run hacp:doctor -- schemas/examples/invalid --json +npm run hacp:doctor -- schemas/examples --manifest schemas/examples/manifest.json +``` + +Expected exit-code behavior: + +- `0`: checks passed for the requested target. +- `1`: contract diagnostics found (expected when checking `invalid/` directly). +- `2`: usage, input, schema compile, or environment hard failure. + +Validation output is evidence for review. It is not approval and does not grant +execution authority.