Skip to content

Commit fd98c24

Browse files
KeyCode17claude
andcommitted
docs(acceptance): wire soak harness + sign-off into AC + phase 04
docs/008-sow-acceptance.md now lists the operator commands to produce each AC's evidence. docs/phase/04-cli-canary-docs.md gains an "Producing the evidence" subsection that points at xtask soak, the code-side verification doc, and the AC-7 template. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 82fe868 commit fd98c24

2 files changed

Lines changed: 46 additions & 0 deletions

File tree

docs/008-sow-acceptance.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,31 @@ Each deliverable's acceptance criteria are stated under [`003-sow-deliverables.m
99
- **MVP-AC-5:** No clippy warnings, no `cargo audit` advisories at severity ≥ medium.
1010
- **MVP-AC-6:** Audit log contains exactly one entry per solve attempt with no cookie payload present (verified by `grep -E 'px3|pxhd' audit.log` returning zero matches).
1111
- **MVP-AC-7:** Threat model and dual-use policy documents signed off by the owner.
12+
13+
## How to produce evidence
14+
15+
MVP-AC-1..4 are collected by a single soak run (operator-side, runs from a
16+
clean residential IP):
17+
18+
```bash
19+
# Terminal 1: start the server
20+
PX_KEYS=config/keys.yaml PX_ALLOWLIST=config/allowlist.yaml \
21+
cargo run -p px-server
22+
23+
# Terminal 2: run the soak (writes evidence to docs/verification/<date>-soak.md)
24+
PX_SOAK_KEY=<key-id>:<secret> cargo xtask soak --duration 24h --rps 1
25+
```
26+
27+
`scripts/soak.sh` (invoked by the xtask subcommand) records per-request
28+
timings, samples `/v1/metrics` every minute, runs a `pgrep` zombie check
29+
on exit, and emits a markdown evidence file with PASS/FAIL verdicts for
30+
AC-1 through AC-4.
31+
32+
MVP-AC-5 + AC-6 are code-side; see
33+
[`docs/verification/2026-05-16-mvp-ac-codeside.md`](verification/2026-05-16-mvp-ac-codeside.md).
34+
35+
MVP-AC-7 is owner-side; see
36+
[`docs/verification/owner-signoff-template.md`](verification/owner-signoff-template.md).
37+
38+
After all seven items hold, run `cargo xtask phase 04` per
39+
[ADR-0017](adr/0017-phase-aligned-versioning.md).

docs/phase/04-cli-canary-docs.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,24 @@ All of [`docs/008-sow-acceptance.md`](../008-sow-acceptance.md) MVP-AC-1..7 hold
4444
6. Audit log: one record/solve, zero cookie payloads (`grep -E '_px3|_pxhd' audit.log` = 0).
4545
7. Threat model + dual-use policy signed off by owner.
4646

47+
### Producing the evidence
48+
49+
Items 1–4 (the soak block) are gathered with one command:
50+
51+
```bash
52+
PX_SOAK_KEY=<key-id>:<secret> cargo xtask soak --duration 24h --rps 1
53+
```
54+
55+
That writes `docs/verification/<date>-soak.md` with PASS/FAIL per AC.
56+
57+
Item 5 is replayed by `cargo clippy ... && cargo audit` (see
58+
[`docs/verification/2026-05-16-mvp-ac-codeside.md`](../verification/2026-05-16-mvp-ac-codeside.md)).
59+
Item 6 is structurally guaranteed by `AuditEvent` having no cookie fields,
60+
documented in the same file.
61+
62+
Item 7: copy `docs/verification/owner-signoff-template.md`, fill in name +
63+
date + the two doc commit SHAs, commit.
64+
4765
After all 7 MVP-AC items are confirmed, run `cargo xtask phase 04` → version becomes `1.0.0` (major bump from `0.4.0`) per [ADR-0017](../adr/0017-phase-aligned-versioning.md). `xtask` does **not** verify the MVP acceptance checklist; that verification is the operator's responsibility before invoking the phase bump.
4866

4967
## Risks

0 commit comments

Comments
 (0)