agentleFS
aaronreneaaronrene/knowtation/.cursor/skills/build-verification-review/SKILL.md

build-verification-review

Skill1 starsChanged 2 months agoMITView on GitHub

Use after an Auto build phase ({step}b) claims deliverables are complete — before marking the phase DONE in {{docs.roadmap_path}}. Invoke: /build-verification-review. Mandatory in every overseer install: .cursor/rules/build-verification-required.mdc (alwaysApply). Agents must not mark DONE until this skill returns pass. This is the honesty gate: verify the implementation actually matches the frozen spec — not merely that tests are green or the agent said "done." Catch agent dishonesty: false completion claims, made-up behavior, tests that do not exercise real paths, docs/marketing that…

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use after an Auto build phase ({step}b) claims deliverables are complete — before marking the phase DONE in {{docs.roadmap_path}}.

    line 3
  2. Distinctive:

    Before ROADMAP row → DONE

    line 31
  3. Very specific:

    Before Tier-3 merge to {{vcs.git.main_branch}}

    line 32
  4. Distinctive:

    Test files — do they assert real behavior or tautologies?

    line 46
  5. Very specific:

    When honesty.enabled: true, a pass MUST be accompanied by appending (or confirming a prior append of) a verification_evidence entry with …

    line 76
  6. Very specific:

    When honesty.enabled: false, ledger append is skipped.

    line 83
  7. Very specific:

    Use the same escalation categories as freeze review: security, irreversible, real_money, gates_tier3.

    line 97
  8. Very specific:

    Do not mark DONE in ROADMAP until pass

    line 106
  9. Very specific:

    When {step}b completes, NEXT block should say:

    line 138
  10. Very specific:

    No merge to {{vcs.git.main_branch}} on findings or blocked

    line 147
  11. Distinctive:

    No waiving V8 ("tests pass therefore done") without addressing citations

    line 148

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Build verification review skill

Use after an Auto build phase ({step}b) claims deliverables are complete — before marking the phase DONE in {{docs.roadmap_path}}. Invoke: /build-verification-review.

Mandatory in every overseer install: .cursor/rules/build-verification-required.mdc (alwaysApply). Agents must not mark DONE until this skill returns pass.

This is the honesty gate: verify the implementation actually matches the frozen spec — not merely that tests are green or the agent said "done."

Purpose

Catch agent dishonesty: false completion claims, made-up behavior, tests that do not exercise real paths, docs/marketing that overstate what shipped, and scope drift from the frozen contract.

This did not get lost — it was always the intent of SD-3 (Thinking → Auto). The kit shipped:

GateWhenTool today
Freeze reviewBefore Auto build ({step}a)freeze-review / freeze-review-loop + ok review --freeze
Build verificationAfter Auto build ({step}b)This skill (thinking model; manual/opt-in)
Mechanical proofDuring/after buildSeven-tier tests (policy/test-tiers.yaml)

Tests prove code runs; this skill proves the code matches the frozen spec and the agent was honest about what landed.

When to use

  • Auto phase {step}b complete; tests reported green
  • Before ROADMAP row → DONE
  • Before Tier-3 merge to {{vcs.git.main_branch}}
  • Especially: video pipelines, billing, user-facing outputs — anywhere agents previously "approved" falsely

Model

Always thinking-high — independent reviewer; not the same session that did the build if possible (fresh chat or explicit "verifier" role). Never Auto for this gate.

Inputs (read all)

  1. Frozen spec artifact (frozen: true from {step}a) — ground truth
  2. {{docs.roadmap_path}} — phase deliverable row
  3. {{docs.handover_path}} — what the build session claims landed
  4. Git diff vs feature-branch base (or muse/git log for the build commits)
  5. Test files — do they assert real behavior or tautologies?
  6. ok status — footprint/drift if kit files touched

Verification checklist (every item needs evidence)

#CheckDishonesty signal
V1Every frozen deliverable exists at the path the spec names"Implemented" but file missing or stub
V2Public APIs match frozen interfaces (signatures, exit codes, fail-closed branches)Spec says X; code does Y
V3Tests cover frozen test-matrix rows — not only happy pathassert True, empty tests, mock-only
V4No scope creep beyond frozen specExtra features not in contract
V5No silent deletion of frozen requirementsSpec requirement removed without spec update
V6Governance docs truthfulROADMAP/HANDOVER say DONE but tests fail or deliverables missing
V7No secrets, injection surfaces, or unsafe defaults introducedgrep + read changed paths
V8Agent claims match verifiable state and (when honesty.enabled) are bound to ledger verification_evidence artifacts"All green" with empty/unrelated diff; "tests passed" with no test_output hash; "deployed" / "healthy" with no deploy_health ref+hash; "UI verified" with no screenshot hash — or a claimed pass with no matching ledger entry when require_verification_evidence: require

Evidence table (required in skill output whenever honesty module is enabled, and recommended always):

### Evidence
| type | sha256 | ref | notes |
| --- | --- | --- | --- |
| test_output | <64 hex> | <label or path> | <optional> |

Rules for a skill verdict of pass (frozen process rules):

  1. V1–V7 unchanged in meaning.
  2. V8 requires citing verifiable git/test state as today.
  3. When honesty.enabled: true, a pass MUST be accompanied by appending (or confirming a prior append of) a verification_evidence entry with bv_verdict: pass, matching phase_id + frozen_spec + round, and a non-empty artifacts list that includes at least one test_output artifact whose sha256 digests the test output the reviewer actually used.
  4. deploy_health and screenshot artifacts are required in the entry only when the build session's claims mention deploy/health or visual/UI proof; otherwise they are omitted. The skill must not invent fake deploy/screenshot evidence.
  5. When honesty.enabled: false, ledger append is skipped; V8 still requires claims↔git/test honesty in the review text (baseline without L2).
  6. findings / blocked rounds MAY append verification_evidence with the corresponding bv_verdict so the chain records failed rounds; this is allowed but not required for skill progress. A later pass round is a separate append (new round).

Verdicts

VerdictMeaningNext step
passImplementation matches frozen spec; claims honestMark phase DONE; governance-sync; Tier-3 merge when ready
findingsCited gaps — fix on feature branchFixer addresses citations only; re-run this skill
blockedEscalating category or fundamental spec violationHuman required

Use the same escalation categories as freeze review: security, irreversible, real_money, gates_tier3.

Loop (bounded)

Same pattern as freeze-review-loop:

  • Max rounds: 5 (build fixes should be smaller than spec fixes)
  • Reviewer → findings → fixer (cited lines only) → re-review until pass or stop
  • Do not mark DONE in ROADMAP until pass

Output format

## Build verification — <phase-id> round <N>

**Verdict:** pass | findings | blocked
**Frozen spec:** <path>
**Diff scope:** <commits or file list>

### Findings
| ID | Sev | path:line | Claim vs reality |
| --- | --- | --- | --- |
| BV1 | MAJOR | src/foo.py:42 | Spec §3.2 requires fail-closed; returns success on error |

### Honest summary (only if pass)
One paragraph: what actually shipped, backed by paths in the diff.

CLI helpers (non-substitute)

./cli/ok status
# run the phase's seven-tier test command
./cli/ok governance-sync --dry-run

CLI cannot replace thinking verification — run this skill after tests pass.

Handover integration

When {step}b completes, NEXT block should say:

Model: thinking-high.
Run build-verification-review against <frozen-spec-path> before marking <phase> DONE.

Hard stops

  • No merge to {{vcs.git.main_branch}} on findings or blocked
  • No waiving V8 ("tests pass therefore done") without addressing citations
  • Uncited findings invalid — re-review

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.