Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Changelog

## v0.3.0

- Add request-driven planning, contextual decision cards and original-intent mappings.
- Require separate advisory intent/guarantee reviews for generated plans before human approval.
- Add explicit per-assumed-clause acceptance, impact and Given/When/Then checks.
- Add bounded scratch implementation/proof/gap-review loops with optional verified installation.
- Keep public contracts frozen while permitting explicitly enabled provable body hints.
- Add implementation-independent last-return negative mutations, task/coverage views,
offline HTML review and explicitly requested evidence-backed draft PR creation.
- Preserve legacy plans/reviews and document remaining reference/backend differences.
- Validate the repair/install workflow with real Gobra and scripted worker subprocesses;
live model quality is not part of that deterministic qualification.


## v0.2.1

- Prevent `status` from accepting historical success while another project
Expand Down
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ See [authenticated review gates](docs/signed-reviews.md) and
[production qualification](docs/production-readiness.md) for signed authority,
native platform checks and repeatable failure/recovery testing.

Install the tagged CLI with `go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.2.1`,
Install the tagged CLI with `go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.3.0`,
or download checksummed binaries from [Releases](https://github.com/cruskell/pdd-kit-go/releases).

## Quick start
Expand Down Expand Up @@ -80,6 +80,11 @@ pdd --cwd /path/to/repo prove
| `import-approval` | Restore a matching review with `--from PATH`, preserving its assertion |
| `prove` | Run all approved checks and mutations in scratch copies; write JSON/Markdown receipts and logs |
| `status` | Reject unsuccessful, stale or damaged evidence |
| `draft`, `decisions`, `decide` | Generate and settle an unapproved request-driven plan |
| `review` | Separate advisory intent/guarantee reviews or a receipt-bound gap review |
| `build`, `tasks` | Repair/verify/review loop and task/evidence status |
| `report` | Offline HTML review dashboard |
| `pr` | Evidence-backed PR preview; `--create` opens a draft PR |
| `doctor` | Check Go and the pinned Docker image, or Java/local jar prerequisites |

Exit codes: `0` success, `1` unmet verification or operational failure, `2` CLI usage error. `--plan NAME` selects an independent plan and state namespace. `--json` emits a schema-1 result with structured errors. `approve --expect-digest SHA256` binds approval to the snapshot reviewed. See [named plans](docs/named-plans.md) and [JSON protocol](docs/cli-json.md).
Expand Down Expand Up @@ -116,7 +121,7 @@ withdrawals; its plan distinguishes empirical evidence from formal proof.
- Every named empirical Go test actually executes and passes. Missing, skipped, cached-only or empty test runs are not evidence. Checks use `-count=1`.
- Every formal mutation is valid Go, changes only the target function body, preserves the approved contract, and is rejected on the target postcondition. The diagnostic must point to the target source file and its exact postcondition line. A parse failure, timeout, unrelated clause failure or missing tool is inconclusive and fails the run.
- Every trust assumption has an empirical check and was explicitly accepted. Tests support assumptions on exercised cases; they do not prove them.
- Source, plan and approval remain current. A changed file makes an old receipt stale. A changed plan, function signature, proof annotation or its owner, imported declaration or pure specification helper requires review again.
- Source, plan and approval remain current. A changed file makes an old receipt stale. A changed plan, function signature, public proof annotation or its owner, imported declaration or pure specification helper requires review again. Explicitly enabled body proof hints can change but must verify.

There is no automatic fallback from failed formal verification to a green test result. Receipts label formal proof and empirical evidence separately.

Expand All @@ -130,7 +135,7 @@ Default approvals and all receipts are **local attestations**. Optional Ed25519

## Current scope

The end-to-end workflow is implemented. Natural-language intent is reviewed and mapped by a developer or coding agent; the CLI does not contain an LLM or infer contracts automatically. It does not integrate with Chopin, open pull requests, or implement the reference prototype's multiplayer UI.
The CLI now includes request-driven drafting, decision cards, two separate advisory planning reviews, a bounded implementation/proof/gap-review loop, an offline HTML review dashboard and explicit draft-PR creation. Model commands use an external Codex CLI or JSON worker; no model is bundled. Human approval remains separate from machine and model checks. See [the executable workflow](docs/agent-workflow.md) and [comparison with the original PDD Kit](docs/reference-comparison.md). Chopin multiplayer UI and Rust/Verus-specific features remain outside this Go implementation.

The Gobra adapter accepts production `.go` packages, top-level functions and named-receiver methods (for example `Policy.Allows`), single-line `// @` annotations and explicit postconditions. Type declarations can live in separate files. Each proof check lists **all production Go files** in one package.

Expand Down
2 changes: 1 addition & 1 deletion cmd/pdd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ func buildVersion() string {
if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
return info.Main.Version
}
return "0.2.1-dev"
return "0.3.0-dev"
}

func main() { os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr, buildVersion())) }
149 changes: 139 additions & 10 deletions docs/agent-workflow.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,142 @@
# Using the kit with a coding agent
# Executable proof-driven workflow

Give your coding agent the following workflow with the task. The deterministic CLI gates are usable with Codex, Claude Code or another agent; no provider API or credentials are needed.
`pdd draft`, `review` and `build` can use an authenticated Codex CLI or an explicit
JSON worker. Deterministic `lint`, `approve`, `prove` and `status` still work without
a model provider. See the [reference comparison](reference-comparison.md) for scope.

1. Read the relevant Go entry points, implementation and tests. Identify the behavior to prove, both its success and refusal cases, and consequential ambiguities. Ask the developer to settle those ambiguities before changing intended guarantees.
2. Select a plan with `--plan NAME` when the project has multiple independent proof areas. Draft `.pdd/plan.json` or `.pdd/plans/NAME.json`: plain-language intent, requirements, explicit exclusions, proof/empirical classification, named checks, trust assumptions and at least one body mutation per formal clause. Add matching `// @` contracts to production Go files. Use `Type.Method` to map receiver methods. List every production file in each proof package, including separate type declarations. For same-module imports, include a complete check for every transitive callee package. Keep external database, crypto and network behavior behind explicit input assumptions.
3. Run `pdd lint` and `pdd plan`. Present the concrete plan and trusted assumptions to the developer. A plan that rejects all requests can satisfy a rejection-only clause: include the desired acceptance direction when appropriate.
4. The reviewer records acceptance with `pdd [--plan NAME] approve --reviewer NAME --accept-tcb ID,... --expect-digest REVIEWED_SHA256`, taking the digest from the review they inspected. Do not impersonate the developer or automatically approve a plan you drafted. The CLI records an assertion; the organization must supply any real identity or approval policy.
5. Implement the body against the frozen contract. Run `pdd prove`. Fix implementation failures without weakening approved annotations. A contract contradiction or newly discovered trust assumption returns to planning and review.
6. Inspect every gap. Missing tools, skipped tests, surviving mutants and inconclusive verifier failures are unfinished verification. Keep implementation gaps separate from evidence gaps. A test result is empirical evidence, not formal proof.
7. Deliver the receipt, source/plan digests, covered clauses, trust assumptions, mutation results and limitations. Export the complete reviewed approval with `export-approval --to .pdd/reviews/NAME.json`, commit it through review, and use `import-approval --from PATH` before `pdd prove` in CI. CI must not mint an approval of freshly read intent. Re-run after any source change; `pdd status` rejects stale evidence.
## Plan and settle intent

For stronger human/agent separation, use an independent reviewer with read-only access to intent, annotations and receipts. The current CLI does not enforce agent identities or supply a reviewer model.
Start with existing production Go declarations. The planner can add contract
comments, but cannot change implementation code. Save the original request in a
text file, then run:

```sh
pdd --plan checkout draft --request-file /path/to/request.txt --files internal/policy.go --apply
pdd --plan checkout decisions --json
pdd --plan checkout report --out .pdd/checkout-review.html
```

Omit `--apply` to preview a proposal. Replacing an existing draft requires
`--expect-draft HASH`, copied from the inspected `draft_digest`. Generated drafts
record the original request, leave all decision selections empty and require both
planning reviews plus a final gap review. Consequential options include context
and effects; a recommendation never counts as an answer.

```sh
pdd --plan checkout decide --id decision-id --option option-id \
--reason 'The acceptance direction is required' --expect-draft INSPECTED_DRAFT_HASH
pdd --plan checkout lint
pdd --plan checkout review --role both
pdd --plan checkout plan --json
```

The two reviews use separate ephemeral invocations and do not receive each other's
opinions. One examines intent coverage; the other checks vacuity, assumptions and
overclaimed guarantees. They can report `changes-required`, `needs-decision` or
`unsupported`. Their records are embedded in the plan and bound by human approval.
They are advisory model opinions, not proofs or authenticated reviewer identities.

The human reviews the complete plan, formal clauses, original-word mappings,
trust and opinions, then records approval:

```sh
pdd --plan checkout approve --reviewer YOUR_NAME \
--accept-tcb boundary-id,assumed-clause-id --expect-digest INSPECTED_PLAN_DIGEST
```

Accept every trust ID and every assumed clause ID. Each clause states its impact
if false, maps to a named empirical test and has a matching Given/When/Then
scenario. Use `--signing-key` and an independently provisioned `--policy` for an
[authenticated authority gate](signed-reviews.md). An unsigned assertion does not
authenticate a human. Never have the implementation agent impersonate the reviewer.

## Build and check gaps

```sh
pdd --plan checkout build --max-iterations 3 --apply
pdd --plan checkout tasks --json
pdd --plan checkout status --json
pdd --plan checkout report --out .pdd/checkout-review.html
```

The loop clones the bounded input snapshot, runs approved machine checks, asks an
implementation worker for structured Go edits when needed, and retries. A separate
gap reviewer compares the source and actual evidence after successful machine
verification. Contracts, declarations, pure definitions, intent and trust stay
frozen. If those must change, the loop stops with `needs-decision`; revise the plan,
repeat reviews and obtain a new human approval. Missing tools and exhausted repair
limits fail closed. A model's `ready` never overrides a machine failure.

With `workflow.allow_proof_hints`, body `assert`, `invariant`, `decreases`, `fold`
and `unfold` hints may change because the verifier must establish them. Public
contracts, pure definitions and all other annotations remain frozen. Existing
plans without this option continue to freeze every annotation. Prefer mutation
`kind: "last-return"` to keep an approved negative case independent of body text;
its replacement must still fail on the intended clause, not just any error.

Without `--apply`, `build` returns a verified candidate and saved edits without
changing production files. With `--apply`, installation checks that source, plan
and approval have not changed, then runs production verification again. Per-iteration
receipts, responses, final edits and `build.json` remain under the selected plan's
`builds/` state directory. The final gap record binds to the exact final receipt.
A later `prove` creates a new receipt; use `review --role gap` again before PR delivery.

`tasks` lists dependencies, formal versus empirical coverage and remaining gaps.
Its pruning candidates are suggestions for declared `formal-regression` scenarios,
never automatic deletions. Boundary, runtime, integration and trust tests remain.

## Deliver a PR

```sh
pdd --plan checkout pr
# Commit and push the feature branch, then verify that committed revision.
pdd --plan checkout prove
pdd --plan checkout review --role gap
pdd --plan checkout pr --title 'Enforce checkout policy' --create
```

The default command only saves/previews `PR.md`. `--create` uses `gh pr create
--draft`, requires a clean feature branch, an exact HEAD-bound current receipt and
matching remote branch. It does not push or merge. Model review is included as an
opinion alongside formal/empirical results, trust and limits. CI restores an
existing reviewed approval using `import-approval`; it never auto-approves intent.

## Worker protocol

All three model commands accept `--driver codex` (default), `--worker /absolute/path`
for another provider, `--files a.go,b.go` and `--agent-timeout 5m`. A worker is a
trusted executable, launched directly without a shell. It receives one schema-1
JSON request on stdin and must emit exactly one strict JSON response on stdout;
diagnostics belong on stderr. It runs in a scratch copy. Source files in the
request are bounded to 512 KiB; choose a narrower `--files` set for large projects.

The request includes a random invocation ID, `request_digest`, role/instructions,
plan/format guide, source/spec digests, selected Go sources and (when available)
the actual machine receipt plus bounded log excerpts (512 KiB total). Planning critics do not receive prior review records.
The response has these fields, all present for the Codex structured-output driver:

```json
{
"schema": 1,
"request_digest": "COPY_THE_REQUEST_DIGEST",
"status": "ready",
"summary": "Explanation of this result",
"findings": [],
"plan_json": "",
"edits": []
}
```

Findings use `severity` (`blocker`, `warning`, `info`), `kind`, `text` and requirement
IDs in `requirements`. `ready` contradicting a blocker is rejected for reviews.
Planning returns a JSON-encoded plan in `plan_json`; implementation returns complete
Go files in `edits: [{"file":"core.go","content":"..."}]`. Review roles may return
neither plan replacements nor edits. Missing/misbound/malformed output and worker
modifications to its scratch source fail closed. No response creates approval.

The Codex driver uses `exec --ignore-user-config --ephemeral --sandbox read-only`
and structured output. Provider authentication and a compatible installed CLI are
operator prerequisites. This project does not supply a model or attest its quality.
Custom workers and empirical Go tests have host-user privileges; snapshot checking
is integrity checking, not an OS security boundary. Keep signing keys outside the
repository. Use isolated CI hosts for untrusted projects.
12 changes: 12 additions & 0 deletions docs/cli-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,15 @@ real identity and authorization requirements.
Keep generated result files under `.pdd/` (excluded from source snapshots). Redirecting output into a snapshotted source-tree file changes that tree after verification and correctly makes the next status check stale.

With `--policy` or `PDD_REVIEW_POLICY`, prove/status enforce authorized unexpired signatures. Receipts include `approval_policy` (digest, key ID, reviewer). Signed approvals cannot be proved without a policy. `keygen` and `--signing-key` support the workflow described in [signed reviews](signed-reviews.md).

## Proof-driven workflow responses

`draft` returns the proposed analysis, draft view/hash and whether it was applied.
`decisions` returns even unresolved drafts with validation errors and open IDs.
`decide` requires `--expect-draft` and returns the updated unapproved plan.
`review` returns advisory records; any non-ready review exits 1. `tasks` returns
machine freshness/success, check dependencies, remaining gaps, a current gap review
and conservative pruning candidates. `build` returns stage, success, decision-needed
state, applied edits, iterations and artifact paths; success=false exits 1.
`report` returns its written HTML path. `pr` returns the evidence body/path and a URL
only after explicit successful `--create`. All use the same schema-1 envelope.
2 changes: 1 addition & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,4 @@ Plan validation is strict but is not a proof of intention, completeness, satisfi

Go tests and local Java invocations have host permissions. Docker restricts its verifier's mount/network; this is not a full adversarial sandbox for the entire tool. Source hashes do not cover environment variables, network services, dependency caches, or excluded output folders. Receipts record tool identities and commits where available but are not signed or remotely authenticated. Do not treat them as tamper-proof attestations.

The first implementation deliberately leaves LLM generation, independent agent review, Chopin integration and PR automation outside the executable. Developers or agents can follow the accompanying workflow and use machine checks as the gate.
`planning.go` adds decision cards, original-intent mappings, trust clauses and scenarios. `agent.go` provides a strict process/JSON bridge and scratch-only edits. `analysis.go` binds separate advisory reviews to specifications and receipts. `workflow.go` runs bounded repairs with frozen contracts; `dashboard.go` renders offline review and prepares explicit draft PRs. See [workflow](agent-workflow.md) and [reference comparison](reference-comparison.md). Chopin integration remains unsupported.
8 changes: 4 additions & 4 deletions docs/distribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Versioned binaries and checksums are published on [GitHub Releases](https://gith
Go users can install the tagged CLI directly:

```sh
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.2.1
go install github.com/cruskell/pdd-kit-go/cmd/pdd@v0.3.0
pdd --version
```

Expand All @@ -24,10 +24,10 @@ Release builds use the exact Go 1.27.4 toolchain. Fetch it from
From a clean checkout of the release commit, with Python 3 available:

```sh
GO=/path/to/go1.27.4/bin/go python3 scripts/release.py v0.2.1
GO=/path/to/go1.27.4/bin/go python3 scripts/release.py v0.3.0
```

The script produces five archives under `dist/v0.2.1`: Linux amd64/arm64,
The script produces five archives under `dist/v0.3.0`: Linux amd64/arm64,
macOS amd64/arm64 and Windows amd64, plus `BUILD.json` and `SHA256SUMS`.
It disables CGO, VCS stamping and local file paths, embeds the requested CLI
version, records the commit/toolchain/flags, and normalizes archive metadata.
Expand Down Expand Up @@ -67,7 +67,7 @@ example reviews, run actual proofs and HTTP tests, kill mutants and check stale
source handling. It needs Go and Docker with the pinned image already pulled:

```sh
python3 scripts/smoke.py --pdd /absolute/path/to/pdd --version v0.2.1
python3 scripts/smoke.py --pdd /absolute/path/to/pdd --version v0.3.0
```

The [release workflow](../.github/workflows/release.yml) builds and validates
Expand Down
Loading
Loading