docs: rewrite README for evidence-first positioning

[kaizencycle]

Mobius PR — Cycle

• Cycle: C-367
• Type: Docs
• Primary Area(s): docs
• Pulse Attached: ⬜

---

1. Summary

Rewrites the README from a spec-heavy catalog into a product narrative: one honest "what works today" table, Quick Start with fail-closed error output, counterfactuals rationale, proposer-independence / deny-by-default design notes, and a tiered roadmap. Holds the README to the same standard the Guard holds PRs — no claim without evidence.

---

2. Details

• Motivation / Problem: Prior README read like internal canon documentation. New positioning leads with the merge gate story, AI-agent risk framing, and verifiable claims only.
• Solution / Approach: Drop-in README rewrite. Intent example uses canonical structured justification (passes validator). DEMO_LINK_PLACEHOLDER replaced with honest roadmap deferral — demo repo is listed under Roadmap → Next, not shipped.
• Architecture Impact: None — documentation only.
• Breaking Changes: No

---

3. Tests

• node test/classify.test.mjs — 11/11 pass
• npm test — 3 packages pass

---

Intent Publication

epicon_id: EPICON_C-367_DOCS_readme-v2-rewrite_v1
ledger_id: kaizencycle
scope: docs
mode: normal
issued_at: 2026-07-15T00:00:00Z
expires_at: 2026-10-13T00:00:00Z
justification:
  VALUES INVOKED: integrity, transparency, accountability
  REASONING: README must not sell futures. New copy leads with what ships
    (the GitHub Action), explains counterfactuals and gate honesty, and
    defers unshipped items to a tiered roadmap.
  ANCHORS:
    - packages/guard-core/src/index.mjs (validator invariants I1-I6)
    - README prior revision (C-367 evidence-first standard)
  BOUNDARIES: README.md only; no validator or runtime changes
  COUNTERFACTUAL: If the intent example fails the Guard, patch README immediately
counterfactuals:
  - If intent example fails validator, revert example block
  - If demo repo ships, restore live demo link in Quick Start

---

"We heal as we walk." — Mobius Substrate

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c9e704694

ℹ️ 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".

[chatgpt-codex-connector]

Document the EP-1 fail-open path

When changed-file analysis succeeds and all changed paths classify as EP-1 (for example a docs-only PR touching README.md), validatePullRequest returns PASS_WITH_BACKFILL and shouldFailCheck exits 0 even with mode: enforce. This fail-closed statement teaches admins a stricter guarantee than the Action actually enforces, so users can configure branch protection expecting missing intent to block every PR when EP-1 changes still pass.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Correct the README license claim

The README now advertises AGPL-3.0, but the linked LICENSE file is still CC0-1.0 and package.json also declares "license": "CC0-1.0". Consumers checking the README before reusing the Action will see conflicting license terms, so this should either keep the README on CC0 or update the actual license file and package metadata in the same change.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Keep the Action-specific test command

npm test invokes turbo test, which only runs workspace package scripts and does not run the root Action tests such as node test/classify.test.mjs or node test/policy-ref.test.mjs. Since this replaces the explicit classifier test command, contributors can follow the README and believe they verified the shipped GitHub Action while the validator/policy tests were skipped.

Useful? React with 👍 / 👎.