From dac5b1c3259ed540d9388c45f4f0030baa45cf8d Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Wed, 20 May 2026 15:55:02 -0500 Subject: [PATCH 1/3] docs: align public HACP content lanes and fixture guidance --- README.md | 22 ++++++++++++++++++++++ schemas/README.md | 1 + schemas/examples/README.md | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+) create mode 100644 schemas/examples/README.md diff --git a/README.md b/README.md index c43d116..d7468ab 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, and + decisions; +- 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 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..08ad87d --- /dev/null +++ b/schemas/examples/README.md @@ -0,0 +1,38 @@ +# 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 +``` + +Validation output is evidence for review. It is not approval and does not grant +execution authority. From 213b73c14a21cb0b7d9c0ba7404018c32b55974b Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Wed, 20 May 2026 15:56:43 -0500 Subject: [PATCH 2/3] docs: clarify doctor exit semantics and maturity cross-link --- README.md | 3 +++ schemas/examples/README.md | 6 ++++++ 2 files changed, 9 insertions(+) diff --git a/README.md b/README.md index d7468ab..c5a16e0 100644 --- a/README.md +++ b/README.md @@ -136,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/examples/README.md b/schemas/examples/README.md index 08ad87d..50df7a7 100644 --- a/schemas/examples/README.md +++ b/schemas/examples/README.md @@ -34,5 +34,11 @@ 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. From fa6faa2c408fc54588ccedde7e2e6623aeb70e14 Mon Sep 17 00:00:00 2001 From: Joe Feser Date: Wed, 20 May 2026 15:58:42 -0500 Subject: [PATCH 3/3] docs: include evidence-set and loop-policy in stability lane --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c5a16e0..15564af 100644 --- a/README.md +++ b/README.md @@ -89,8 +89,8 @@ checked. ### Stable Enough To Use Now -- draft artifact vocabulary for packets, reports, stops, findings, and - decisions; +- 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;