feat: Dorian Claim Warrants for Claude Code (v1.3.0)

CHANGELOG.md

@@ -6,6 +6,43 @@ semantics have been stable since 1.0.0.
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-06-28
+
+The **Dorian Claim Warrants for Claude Code** integration: one command scaffolds a project-local Claude
+Code skill that drafts claim warrants for the checkable facts a coding agent says it changed, which
+`dorian verify` then proves deterministically. **No breaking changes** — purely additive (a new CLI
+subcommand, packaged templates, docs); warrant schema, checker grammar, exit codes, fold policy, and
+security posture are unchanged, the core stays zero-dependency, and **no model is ever added to the
+verification path**.
+
+### Added
+- **`dorian claude-code install-claim-warrants`** (`src/dorian/claude_code.py`) — scaffolds a
+  project-local Claude Code skill at `.claude/skills/dorian-claim-warrants/` (invoked as
+  **`/dorian-claim-warrants`**) that drafts `docs/changes/<slug>.md` + `docs/changes/<slug>.claims.json`
+  for the *checkable* subset of a change summary (config values, signatures/defaults, constants,
+  file/symbol references), then prints `dorian verify … --strength-gate=fail --binding-gate=warn`. The
+  **model only drafts; Dorian verifies**. Writes files only (never runs a checker or executes code),
+  stays inside the target repo, never overwrites without `--force`, and is idempotent. Flags:
+  `--with-hook`, `--no-hook`, `--settings-only`, `--dry-run`, `--force`, `--print-next-steps`,
+  `--target`.
+- **Packaged skill templates** (`src/dorian/templates/claude_code/…`, shipped as wheel package data):
+  `SKILL.md`, a bundle `README.md`, `examples/` (good/bad claims, a final-message walkthrough),
+  `templates/` (change-note + claims.json skeletons), and `reference/` (checker-selection map,
+  safety-boundary).
+- **Opt-in, reminder-only Stop hook** (`hooks/dorian_claim_warrants_stop.py`, stdlib only). It returns a
+  soft `additionalContext` nudge — **never a block**, so it cannot loop — and only when a turn left
+  relevant, un-warranted code/config changes. It never runs `dorian verify` or tests, never writes
+  files, and never executes project code (its only side effect is a read-only `git status`); it fails
+  open. Not enabled by scaffolding — register it under `hooks.Stop` yourself.
+- **Docs** — [`docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md`](docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md)
+  (the integration guide) and [`docs/CLAIM_WARRANTS_VS_AGENT_RECEIPTS.md`](docs/CLAIM_WARRANTS_VS_AGENT_RECEIPTS.md)
+  (how Dorian claim warrants differ from — and complement — the Agent Receipts action-audit protocol).
+
+### Changed
+- README, `docs/CLAUDE_CODE_DORIAN_WORKFLOW.md`, and `docs/POSITIONING_2026_06_27.md` adopt the
+  **"claim warrants"** name (keeping "receipt" only as an explanatory metaphor, to avoid collision with
+  the Agent Receipts project).
+
 ## [1.2.0] — 2026-06-27
 
 C4 import-aware dependency binding, the opt-in truth-axis `--strength-gate`, and the

README.md

@@ -308,6 +308,17 @@ claim, so use the lower-level two-step instead: `dorian capture` to build the re
 
 ## Using dorian with Claude Code
 
+> **One command: `dorian claude-code install-claim-warrants`.** In a trusted repo this scaffolds a
+> project-local Claude Code skill — invoke **`/dorian-claim-warrants`** after a change — that drafts the
+> change note + `claims.json` for the checkable facts your agent claimed, then prints the verify command:
+> `dorian verify docs/changes/<slug>.md --claims docs/changes/<slug>.claims.json --strength-gate=fail
+> --binding-gate=warn`. The **model only drafts; `dorian verify` proves** it deterministically and
+> token-free. Later, `dorian revalidate --since <base>` REVOKEs a claim the code drifted away from. Add
+> `--with-hook` for an opt-in, reminder-only Stop hook. Not a sandbox — trusted repos only. Guide:
+> [`docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md`](docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md)
+> (and how it differs from Agent Receipts:
+> [`docs/CLAIM_WARRANTS_VS_AGENT_RECEIPTS.md`](docs/CLAIM_WARRANTS_VS_AGENT_RECEIPTS.md)).
+
 The intended loop is an agent-in, checker-out handshake: a coding agent writes the change *and* the
 `claims.json` for what it just did, dorian verifies those claims against the real code, and then
 keeps re-checking them on every later commit. Nothing about dorian is Claude-specific — any agent (or
@@ -395,7 +406,7 @@ jobs:
         with:
           fetch-depth: 0             # revalidate diffs against the PR base sha
           persist-credentials: false # the Action only reads the diff + posts via GITHUB_TOKEN
-      - uses: ajaysurya1221/dorian/action@v1.2.0
+      - uses: ajaysurya1221/dorian/action@v1.3.0
         with:
           fail_on: revoked
           # install defaults to the published PyPI package (dorian-vwp); pin a
@@ -437,6 +448,11 @@ claims.
   `claims.json`, the change note it backs, and a `.github/workflows/dorian.yml` Action workflow.
   Writes files only (never runs a checker or executes code), stays inside the repo, and skips
   existing files unless `--force`. The global `--json` prints a machine-readable plan.
+- `dorian claude-code install-claim-warrants [--with-hook] [--dry-run] [--force]` — scaffold a
+  project-local Claude Code skill (`/dorian-claim-warrants`) that drafts a change note + `claims.json`
+  for the checkable facts your agent claimed, plus review-first settings examples and an opt-in,
+  reminder-only Stop hook. The model only drafts; `dorian verify` proves. Writes files only; idempotent.
+  See [`docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md`](docs/DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md).
 - `dorian verify <artifact> --claims claims.json` — the one-shot agent-claims entry point:
   auto-derive the read-set from each C3/C4/C5 checker, then seal (born-verifiable). C1 span claims
   use `dorian capture` + `dorian seal` instead.
@@ -557,7 +573,7 @@ work perishable, so you find out when it expired.
   **reproducible on those frozen SHAs only** — not a real-world performance claim; the trigger and
   truth layers are reported separately.
 - **PyPI trusted publishing** — `dorian-vwp` is published to PyPI via a Trusted Publisher
-  (latest: **`v1.2.0`**); `pip install dorian-vwp` installs the released package.
+  (latest: **`v1.3.0`**); `pip install dorian-vwp` installs the released package.
 
 Non-goals stay non-goals: no servers, no dashboards, no hosted control plane, no model at check time.
 Local-first is the design center.

action/README.md

@@ -26,7 +26,7 @@ jobs:
           fetch-depth: 0   # REQUIRED: revalidate diffs against the PR base
                            # sha, which a shallow clone does not contain
           persist-credentials: false  # the Action reads the diff + posts via GITHUB_TOKEN
-      - uses: ajaysurya1221/dorian/action@v1.2.0
+      - uses: ajaysurya1221/dorian/action@v1.3.0
         with:
           fail_on: revoked
           # install defaults to the published PyPI package (dorian-vwp);
@@ -78,7 +78,7 @@ self-attested-verdict problem for *non-executable* checkers — that is what
 
 ```yaml
 # untrusted / public-fork posture
-- uses: ajaysurya1221/dorian/action@v1.2.0
+- uses: ajaysurya1221/dorian/action@v1.3.0
   with:
     deny_exec: "true"   # C4/C5 ERROR instead of executing
 ```
@@ -94,7 +94,7 @@ executed). Implemented and proven by the
 
 ```yaml
 # public / forked-PR posture: trusted checker specs + no code execution
-- uses: ajaysurya1221/dorian/action@v1.2.0
+- uses: ajaysurya1221/dorian/action@v1.3.0
   with:
     checker_trust: base   # run only base-approved checker specs
     deny_exec: "true"     # and refuse to execute even those (belt and braces)

docs/BENCHMARK_CURRENT.md

@@ -10,9 +10,9 @@ and are kept as-is for provenance.
 
 | field | value |
 | --- | --- |
-| dorian version | `1.2.0` |
+| dorian version | `1.3.0` |
 | metric commit | `33e9eaf` (the benchmark figures were measured here, during the release audit) |
-| release commit | `81cebbc` (1.0.1) → v1.0.2 announcement hotfix. The 1.0.1 changes (C4 leading-dash nodeid rejection, C5 reconcile per-query timeout, a byte-identical index-once `verify` refactor, the `suggest-claims` / `export --in-toto` commands) plus the v1.0.2 hotfix (export `.warrant` filename disambiguation, `suggest-claims` PEP 263 encoding read, a `symbol_index` non-git `GitError` guard, and CI/SCA/credential/doc hardening) touch no checker numeric behavior; both suites below were **re-run at 1.0.2 and reproduce the metric-commit figures exactly** — binding-lifecycle to the same content-derived `run_id` `168b50d9aa631d52` — so these changes do not move what the suites measure. v1.1.0 added the `dorian init` scaffolder, the PR-comment renderer enhancements (a status line, trust-change counts, sealed-at, and remediation), and build/VCS guards against editor/file-sync `… 2.py` duplicate files (untracked local artifacts — never tracked, never in a CI wheel or on PyPI); v1.1.1 makes the `dorian init` starter claim load-bearing (a scaffold default). All of this is a new command plus output formatting, scaffold defaults, and packaging hygiene only — touching no checker/binding/fold code — so the figures stand unchanged at 1.1.1 (the suites were last executed at 1.0.2, not re-run since). **v1.2.0** adds C4 import-aware binding (a trigger-axis watch widening that affects only C4 `pytest:` claims — not the C1/C3/C5 symbol/regex/string/path/data paths these suites exercise) and the opt-in, default-off `--strength-gate` (advisory; changes no checker verdict or binding). All three suites were **re-run at v1.2.0 and reproduce the metric-commit figures exactly** — binding-lifecycle again landing on the same content-derived `run_id 168b50d9aa631d52` — so 1.2.0 does not move what they measure |
+| release commit | `81cebbc` (1.0.1) → v1.0.2 announcement hotfix. The 1.0.1 changes (C4 leading-dash nodeid rejection, C5 reconcile per-query timeout, a byte-identical index-once `verify` refactor, the `suggest-claims` / `export --in-toto` commands) plus the v1.0.2 hotfix (export `.warrant` filename disambiguation, `suggest-claims` PEP 263 encoding read, a `symbol_index` non-git `GitError` guard, and CI/SCA/credential/doc hardening) touch no checker numeric behavior; both suites below were **re-run at 1.0.2 and reproduce the metric-commit figures exactly** — binding-lifecycle to the same content-derived `run_id` `168b50d9aa631d52` — so these changes do not move what the suites measure. v1.1.0 added the `dorian init` scaffolder, the PR-comment renderer enhancements (a status line, trust-change counts, sealed-at, and remediation), and build/VCS guards against editor/file-sync `… 2.py` duplicate files (untracked local artifacts — never tracked, never in a CI wheel or on PyPI); v1.1.1 makes the `dorian init` starter claim load-bearing (a scaffold default). All of this is a new command plus output formatting, scaffold defaults, and packaging hygiene only — touching no checker/binding/fold code — so the figures stand unchanged at 1.1.1 (the suites were last executed at 1.0.2, not re-run since). **v1.2.0** adds C4 import-aware binding (a trigger-axis watch widening that affects only C4 `pytest:` claims — not the C1/C3/C5 symbol/regex/string/path/data paths these suites exercise) and the opt-in, default-off `--strength-gate` (advisory; changes no checker verdict or binding). All three suites were **re-run at v1.2.0 and reproduce the metric-commit figures exactly** — binding-lifecycle again landing on the same content-derived `run_id 168b50d9aa631d52` — so 1.2.0 does not move what they measure. **v1.3.0** adds the Claude Code claim-warrants scaffolder (`dorian claude-code install-claim-warrants`: a new CLI subcommand, packaged skill/hook/settings templates, an opt-in reminder Stop hook, and docs) — a CLI/packaging/docs addition that touches **no checker, binding, or fold code**, so the figures stand unchanged at 1.3.0 (the suites were last executed at v1.2.0, not re-run since) |
 | Python | 3.12.4 |
 | platform | darwin (CI matrix: 3.11 / 3.12 / 3.13) |
 | reproduce | `dorian bench large-mutation` · `dorian bench binding-lifecycle` · `dorian bench realworld-usecases` |

docs/CLAIM_WARRANTS_VS_AGENT_RECEIPTS.md

@@ -0,0 +1,56 @@
+# Dorian claim warrants vs Agent Receipts
+
+Two projects with adjacent names answer **different questions**. They are
+complementary, not substitutes. This page keeps them distinct so you pick the right
+tool — and so Dorian's "receipt" metaphor is never mistaken for the Agent Receipts
+protocol.
+
+## Two different questions
+
+| | **Agent Receipts** / Obsigna | **Dorian claim warrants** |
+|---|---|---|
+| Core question | *What did the agent do, on whose authority, with what inputs — and was the log tampered with?* | *Is this specific engineering claim true now, and will it revoke when later code makes it false?* |
+| Unit of record | An **action** (a tool call the agent made) | A **claim** (a checkable fact a change asserts) |
+| Mechanism | A daemon records a tamper-evident **receipt for every tool call**, structured as a W3C Verifiable Credential (`type AgentReceipt`), **signed with Ed25519** and **hash-chained** to the previous receipt | A deterministic checker (AST/regex/file-symbol/`pytest`/data) seals a passing claim into a git `.warrant`; later drift folds it to `REVOKED` |
+| Trust property | Integrity of the **action log** (it can't be silently altered) | Truth of the **stated claim** (it can't silently rot as code drifts) |
+| When it runs | Continuously, as the agent acts | At seal time, then on later diffs — **token-free**, no model |
+| Cryptography | Ed25519 signatures, hash-chain | Content-addressed warrant id (SHA-256); **unsigned** today |
+| Surface | Obsigna ecosystem: hook, MCP proxy, SDKs (Go/TS/Python), dashboard | Local-first CLI + GitHub Action; no SaaS, no dashboard |
+
+> Facts about Agent Receipts above are from agentreceipts.ai (verified 2026-06-27):
+> "a tamper-evident receipt for every tool call your agent makes", "structured as a
+> W3C Verifiable Credential with type AgentReceipt", "signed with Ed25519", "hash
+> link to the previous receipt, forming a tamper-evident sequence".
+
+## Why "receipt" here is a metaphor, not a brand
+
+Dorian claim warrants are **receipts for checkable engineering claims, not receipts
+for agent actions.** The word describes the artifact ("proof this stated fact held
+when sealed, and an alarm if it later breaks"). Dorian does **not**:
+
+- record every tool call the agent made,
+- prove *what the agent did* or *who authorized it*,
+- produce a signed, hash-chained action audit trail,
+- replace Agent Receipts, Sigstore, SLSA, in-toto, or audit logs.
+
+So the product name is **claim warrants**, never "agent receipts".
+
+## They are complementary
+
+- **Agent Receipts** can prove the agent actually called `Edit`/`Write`/`Run` — the
+  provenance of the *actions*.
+- **Dorian** can prove the agent's stated engineering *claim* ("the default is still
+  `False`", "`requires-python` is `>=3.11`") was true when sealed, and detect when a
+  later commit silently makes it false.
+
+An action log tells you *that the agent did something*. A claim warrant tells you
+*whether what it said it accomplished is still true*. Used together: Agent Receipts
+for action provenance, Dorian for claim truth over time.
+
+## What Dorian deliberately is not
+
+Dorian is local-first, git-native, deterministic, and token-free at check time. It
+is **not** a sandbox (`C4`/`C5` checkers execute code — trusted repos only), not an
+LLM judge, not a SaaS, not a dashboard, and not a generic agent-action recorder. See
+[`SECURITY_BOUNDARY.md`](SECURITY_BOUNDARY.md) and
+[`VALIDATION_HONESTY.md`](VALIDATION_HONESTY.md).

docs/CLAUDE_CODE_DORIAN_WORKFLOW.md

@@ -1,8 +1,15 @@
-# Claude Code + Dorian — turn your agent's summary into receipts
+# Claude Code + Dorian — turn your agent's summary into claim warrants
 
 > A practical workflow for Claude Code / Codex / Cursor users. When the agent finishes a change, it
 > ends with a summary of specific claims. This is how to make the **checkable** subset into deterministic
-> git receipts that fail later if the code drifts — token-free, in a trusted repo.
+> git **claim warrants** (receipts for checkable claims) that fail later if the code drifts — token-free,
+> in a trusted repo.
+
+> **One-command Claude Code setup.** `dorian claude-code install-claim-warrants` scaffolds a
+> `/dorian-claim-warrants` skill (and an opt-in reminder hook) that drafts the change note + `claims.json`
+> for you, then prints the `dorian verify` command. The model drafts; Dorian proves. See
+> [`DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md`](DORIAN_CLAIM_WARRANTS_CLAUDE_CODE_SKILL.md). The manual
+> loop below is the same thing by hand.
 
 ## The loop
 
@@ -62,7 +69,7 @@ dorian status                              # trust state of every warranted arti
 ## GitHub Action
 
 ```yaml
-- uses: ajaysurya1221/dorian/action@v1.2.0
+- uses: ajaysurya1221/dorian/action@v1.3.0
   with:
     fail_on: revoked        # block the PR when a sealed claim breaks
     # for semi-trusted contributors, also: checker_source: base  + deny_exec: true