proof-of-work

Files (3)

• SKILL.md
• SKILL.md.bundle
• SKILL.md.sig

SKILL.md (first lines)

# Proof of Work

> Implements Principle 5 of the DevOPs Constitution.
> Every claim about completed work ships with structured proof.

**Tradeoff:** Per-task output is ~200-500 tokens larger. Worth it: hallucination
on verifiable categories (tests, diffs, scans) drops to near-zero, and the
`claim-validator` checks declared metadata; command execution needs separate evidence.

---

## When to use

Any time you say one of:

- "I've implemented X"
- "Tests pass"
- "Deployed to staging/prod"
- "Security scan clean"
- "Migration applied"
- "Refactored Y without behavior change"
- "Performance improved by Z%"

…you MUST emit a proof artifact.

---

## How to use

1. After completing a verifiable action, write the proof artifact to
   `.workflow/proofs/<claim-id>.yml` using the schema in
   `verification/claim-schema.yml`.

2. The `claim-id` follows the format `claim-YYYY-MM-DD-NNN` where NNN is the
   next available sequence number.

3. The artifact MUST conform to this structure:

```yaml
claim:
  id: claim-2026-05-22-001
  type: implementation | test | scan | deploy | migration | refactor | perf | doc | security-review | threat-model
  spec_ref: "specs/<file>.md#<section-anchor>"
  description: "<one factual sentence, no marketing language>"
  proof:
    git_sha: "<full or short commit hash>"
    files_changed:
      - "src/auth/refresh.ts"
      - "src/auth/refresh.test.ts"
    test_command: "<the exact, runnable command>"
    test_exit_code: 0
    test_output_path: ".workflow/proofs/claim-2026-05-22-001-test.log"
    duration_ms: 4271
  confidence: high | medium | low
  reproducibility_hash: "sha256:<computed as in step 5>"
  caveats: |
    Optional. State any conditions where the proof might not reproduce
    (flaky test, network dependency, time-of-day sensitivity).
```

4. Save the full test output (stdout + stderr) at `test_output_path`.

5. Compute `reproducibility_hash` exactly as the validator does: `"sha256:"`
   followed by the hex SHA-256 of `test_command` + `"\n---\n"` + the
   `proof.environment` entries as `key=value` lines sorted by key and joined
   with `"\n"` (empty when there is no `environment`) + `"\n---\n"` +
   `git_sha`. The code is `recomputeReproducibilityHash` in
   `verification/claim-validator.ts`.

---

## Confidence levels

- **high**: deterministic verification. Tests, type checks, linting, builds
  that produce identical output on re-run. Default.
- **medium**: verification depends on environment but the result is
  reproducible within a controlled environment (Docker container, CI runner).
  Network-dependent tests, time-sensitive code.
- **low**: verification is subjective or non-reproducible. UI screenshots,
  human-judged design quality, A/B test results. **Triggers explicit human
  review.**

If in doubt, downgrade. False high-confidence is worse than acknowledged
low-confidence.

---

## Forbidden patterns

Do NOT emit a claim if:

- Tests did not actually run (compile errors, environment failures)
- The command emitted non-zero exit code (no, "it's basically passing" is not
  acceptable)
- You cannot produce a stable `reproducibility_hash`
- The work is partial — emit only when the unit of work is complete
- You are uncertain whether the work matches the spec — open a blocker instead

---

## Example

After implementing refresh-token rotation per `specs/auth/tokens.md#ac-3`:

```yaml
claim:
  id: claim-2026-05-22-018
  type: implementation
  spec_ref: "specs/auth/tokens.md#ac-3"
  description: "Implemented 7-day expiry on refresh tokens with REFRESH_EXPIRED error code per AC-3"
  proof:
    git_sha: "7c4a9f2"
    files_changed:
      - "src/auth/refresh.ts"
      - "src/auth/refresh.test.ts"
    test_command: "pnpm test auth/token"
    test_exit_code: 0
    test_output_path: ".workflow/proofs/claim-2026-05-22-018-test.log"
    duration_ms: 4271

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs