AGENT SKILL

proof-of-work

Produce structured proof artifacts for every completed claim. Use this skill whenever the agent claims to have implemented something, tested something, deployed something, or completed a task. Every claim must ship with proof — git SHA, files changed, test command, exit code, output tail, and a reproducibility hash. Claims without proof are rejected by the claim-validator. Triggers on any output that asserts completion.

License 许可
MIT
所属仓库
MILTONADINA/DevOPs
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
proof-of-work
description
Produce structured proof artifacts for every completed claim. Use this skill whenever the agent claims to have implemented something, tested something, deployed something, or completed a task. Every claim must ship with proof — git SHA, files changed, test command, exit code, output tail, and a reproducibility hash. Claims without proof are rejected by the claim-validator. Triggers on any output that asserts completion.

02 资源文件 1

03 SKILL.md 正文

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:

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).
  1. Save the full test output (stdout + stderr) at test_output_path.

  2. 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:

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
  confidence: high
  reproducibility_hash: "sha256:e7a3b9c5d2f4..."
  caveats: |
    None. Test uses fake timers so no real-clock dependency.

Verification

After emitting the claim, run:

npm run validate:claims -- .workflow/proofs/claim-2026-05-22-018.yml --no-rerun

That npm script exists in the DevOPs repository itself. In a project where DevOPs is installed, run the same validator as tsx "$DEVOPS_ROOT/verification/claim-validator.ts" <claim-file> --no-rerun.

The validator requires --no-rerun and checks metadata without executing test_command:

  1. The claim conforms to the packaged schema
  2. The git_sha exists in the repo
  3. The files_changed names appear in that commit's changed-file list
  4. The reproducibility_hash recomputes to the same value

Retain the separately observed command, exit code and output. Metadata acceptance does not establish that the declared command ran or that its result is true.

If any check fails, the claim is rejected and the session cannot proceed to completion until it's fixed or withdrawn.


This skill is working when: 100% of session-end summaries show all claims verified by the validator. The intended record is governance/telemetry/proof-rate.jsonl. Nothing writes it yet, so check by hand.

04 同仓库更多 Skills

MILTONADINA
MILTONADINA/DevOPs

karpathy-guidelines

Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.

★ 0
MILTONADINA
MILTONADINA/DevOPs

unsigned-missing-sig-fixture

Test fixture (F.09) — SKILL.md without an accompanying .sig file. Default install rejects with exit 2; --allow-unsigned --rationale="..." proceeds.

★ 0
MILTONADINA
MILTONADINA/DevOPs

unsigned-mismatched-sig-fixture

Test fixture (F.09) — SKILL.md whose accompanying .sig signs different content. NFR-F3 hash check catches this even with --allow-unsigned.

★ 0
MILTONADINA
MILTONADINA/DevOPs

karpathy-guidelines

Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.

★ 0
MILTONADINA
MILTONADINA/DevOPs

webhook-idempotency

Defend against double-processing of webhook events across every provider (Stripe, GitHub, Slack, Twilio, SendGrid). Idempotency-key pattern + replay-window enforcement + dedupe-storage strategy. Triggers on any webhook handler authoring (route matching /webhook(s)?/, Stripe-Signature / X-Hub-Signature-256 header references). Defense against OWASP ASI02 (Tool Misuse) -- a replayed webhook that re-triggers a destructive tool is the canonical control-flow-level replay attack. Universal across providers; stack-specific signature verification lives in stack-specific skills.

★ 0
MILTONADINA
MILTONADINA/DevOPs

semgrep-scan

Run Semgrep static analysis to detect insecure code patterns - SQL injection, XSS, path traversal, weak crypto, broken auth, OWASP Top 10 issues. Use on every file change touching security-sensitive code and as part of the tiered security gate. Complements gitleaks (which catches secrets) by catching insecure logic.

★ 0