Keystone · verify — plan and intent vs. the actual diff
Judgment is delegated to the keystone:verifier agent, which did not write the code and sees no conversation. This
skill runs the commands, collects the verdict, and writes the record. Write/Edit are allowed for exactly two things:
<plan folder>/verify.md and the Status: value in the plan header (plus Accepted unproven by … / Accepted violation by … in verify.md for
accept, and for accept the plan's ## Debt lines — references/ACCEPT.md). Never edit code, the intent, the rest of the plan, or tests. Fixing what verify finds is /keystone:fix or
/keystone:implement, not this skill — Fix directly here in Step 6 hands the turn to the fix skill's rules.
Roles. The keystone:verifier agent is the judge (the strongest model); this skill is the orchestrator (a mid
model); the fixed mechanical steps — the diff base, this task's files, build / test / lint — run as a script
(scripts/collect.mjs), so no model spends tokens on them.
Output rendering. Report and summary templates in code blocks below show structure only. Render them as Markdown —
headings, tables, bold labels, bullet lists — never wrapped in a code block (it shows as a monospace wall); keep paths
and commands in inline code. The closing Blocked on me: / Changed: / Found: lines become three bullets with bold labels.
Next step (mandatory). End the answer with a Next: line that names the step in a few words, then put the exact
command on its own, on the following line(s), inside a fenced code block with no language tag — the app shows a
copy button on a code block. Never tag it ```bash: a /keystone:* command is not a shell command, and the bash tag
adds a Run button that would fail. When nothing runs now, write Next: nothing now — waiting for <event> and put the
later command in that fenced block. Never end on a caveat or an open-ended question. A path in that command must open
from the session's working directory, because the next session (after /clear) starts there: a file inside it →
its path relative to it; a file you wrote in another repository or folder (after cd) → its absolute path.
Choice at the end (menu). When the stage leaves more than one sensible next step, end with one AskUserQuestion
menu instead of a single command, as AI Factory does: 2–4 options, the recommended one first with (Recommended),
and Stop here last. Print the report and the summary first, then ask. On a pick, carry it out: an option that
continues in this session runs now — for another Keystone skill, read ${CLAUDE_SKILL_DIR}/../<skill>/SKILL.md and
follow it with the chosen arguments; an option that needs a clean session (/clear first), an irreversible external
step (push, deploy, production) or a human action outside the chat is not run — it becomes the Next: command. With
one sensible next step, or when AskUserQuestion is unavailable (claude -p, CI), skip the menu. The Next: line
always closes the answer.
Status colors. In the chat (not in files other tools parse) mark statuses so they scan at a glance: ✅ ok / done · ⚠️ not proven / warn / partial · ❌ missing / wrong / fail · ⏸️ BLOCKED · 🔄 in progress · ⏳ pending; verdicts and gates 🟢 PASS / pass · 🟡 PASS-UNPROVEN / warn / not proven · 🔴 FAIL / fail · ⚪ n/a; severity and risk 🔴 critical / High · 🟠 high · 🟡 medium / Medium · 🟢 low / Low. The marker goes before the word; the word stays.
File links. Every file you write or point the user to lives inside the session's working directory
(the folder Claude Code runs in — in a worktree, the worktree, never the main checkout), and its link is relative to
that directory: [intent.md](wordpress-plugin/x/docs/keystone/<task>/intent.md), not relative to a nested repo or a
subproject. Check the link before showing it: the app opens links only from the working directory. A file outside
it (Claude's memory under ~/.claude, another repository, a temp folder) is never a link — the app cannot open
it and shows "file not found", and a path in code becomes such a link too: give its absolute path as plain
text, without backticks. Link only a file you checked exists.
No decisions through verify. If the user asks to put a decision or change into the intent or the plan, do not edit
anything: answer that this is /keystone:intent <path> (intent) or /keystone:plan <plan path> (plan), and that verify
must be run again afterwards. Never attribute to the user an edit the agent made.
Arguments: $ARGUMENTS — <plan path> [base ref] [--full] (--full only with the plan path: judge every row again), or accept, or accept [<plan path>] D<k> <proof text>, or empty (= the active plan).
Step 0 — find the plan, intent, rules
accept …→ read${CLAUDE_SKILL_DIR}/references/ACCEPT.mdfirst and follow it; it finds the plan itself.- Active plan = the plan.md of the newest task folder under docs/keystone/ — newest by the date prefix of the folder name, ties broken by the plan.md modification time — whose Status is draft, approved or implementing. A plan elsewhere (an older task folder outside docs/keystone) is used only when its path is given explicitly as the argument. If none: ask for the path, or stop with
no plan to verify. Plan outside docs/keystone/ → say once: the gates never saw it. - A plan with
Status: draftwas never approved: stop and say so — verify measures an implementation, not a draft. - Read the plan header (
Level,Mode,Status,Authority,Settings), the intent named inAuthority:(orintent.mdnext to the plan), and the project rules (those that exist):CLAUDE.md,.claude/CLAUDE.md,docs/architecture.md,.claude/rules/**/*.md(paths:rules apply only to matching files),AGENTS.md. MUST / MUST NOT lines there are project rules.
Step 1 — collect (one command)
Run from the repository root: node ${CLAUDE_SKILL_DIR}/scripts/collect.mjs <plan path> [base ref] [--full] — the diff base,
this task's commits and files (uncommitted ones included), build / test / lint by references/CHECKS.md, then delta:,
judge:, rules scope:, release refs:, left the plan:, carried ids:, the record-only marker, and under it edited: / late watch: / accepted violations: / carried: / history: / trend menu:. verifier: not called → no verifier (references/LOOP.md). Installing dependencies is not allowed; it honours Settings: (tests — no → no test run, no failure). A
not run line is never a pass, (a timeout included); pass (reused: …) is a pass (CHECKS.md). Merged-in commits from other branches or sessions never make a file unrequested;
task-folder files (plan.md, intent.md, verify.md) never are. Mode: fix plans: note whether existing test files were
edited (a violation of the fix contract). A check the plan names (a task's check:, a read-only curl GET against a
local/staging URL in the plan) may run as a second command.
Two gates join the same lines:
- Architecture gate. The script runs each
MUST NOT:check: <grep>ofdocs/architecture.mdon the changed files and printsArchitecture gate: pass | fail — <rule, file:line> | n/a;check: reviewlines go to the verifier. - Security gate. On L whose plan has the
Threats:block or a/keystone:securitytask (security/auth/payments/PII),/keystone:securitymust have been run for this diff: take itsSecurity gate: pass | warn | failline from that run in this session, or run it now with the Skill tool (/keystone:security <plan path>) and read the line from its answer.failwithout a matching entry indocs/keystone/security-ignores.md→ verdict FAIL; none run →not proven. The same applies when the plan has noThreats:block but the diff itself changes RLS policies, grants or roles, auth or session code, or permission checks: that is a security change, so no audit run →Security gate: not proven — <files>, nevern/a. Not a security change →n/a. Strictness: L is strict by default (--strictfor M) — then a lint warning, an unfinished-work marker (TODO / FIXME / HACK) or an undocumented env variable in the changed files iswrong, and anot runcheck isnot proven; in normal mode they are reported as open work only.
Step 3 — the verifier
Call the agent (Agent tool, subagent_type: "keystone:verifier"). Its prompt contains only facts, no opinion:
plan path, intent path, base ref, the Step-1 lines above the record-only marker (incl. the gate lines; never the
evidence of carried rows), and the project-rules file list. It returns one line per task, Reconciliation row and I-n
not carried, then Unrequested, Settings, Rules gate with one rule … line per project rule
(every violating file:line on it), the count line and the Keystone Chain line.
Its first line is Decisions:, then Original goal: met | partially | not met — the user's verbatim goal against the diff, independent of
the intent; partially/not met without a confirmed Goal check: in the intent is wrong (PASS is impossible). Then
Done means: — every outcome there gets ok / not proven / wrong.
Cost. Take the Keystone cost meter line from this prompt's context: cost: verify+fix $<verify + fix> (a part
missing counts as 0.00); no line or not measured yet → cost: verify+fix n/a. It is the cost before this run.
Write verify.md once, in the Step 5 layout: the Step-1 lines (one per line) and cost: as ## Checks, the carried: lines as
they are as ## Carried, the verifier's output exactly as it came as ## Report — never retyped or summarised. Then cross-check every ok and wrong line against the cited
file:line (open it and confirm it says what the line claims); on a mismatch, fix that line in verify.md with Edit
and mark it (corrected by verify). Every wrong line
must carry Repro: <input / command where the failure shows>; the verifier also returns an Unconfirmed — <what could not be confirmed> — looked in <where> section. Do not print the line-by-line report in the chat: it lives in
verify.md, and the chat gets only the Final report below. Count again from ## Report plus ## Carried (carried rows are ok): ok + missing + wrong + not proven + BLOCKED + pending = n.
If the numbers do not add up, fix the count, not the lines, and say so.
Rules you enforce when reading the output (the verifier knows them, you check them):
## Releasesteps (R<n>) are not tasks: they run after the verdict, so they are nevermissing,BLOCKEDor open work, and they never block PASS. Apending R<n>row (release refs … open) is planned proof, not open work.[x], "done", "pass" is not evidence. A grep or a code read is presence, not behaviour →not proven.- A row whose evidence starts with
BLOCKED:is open work, neverok. - Formatting noise is not
unrequested; new logic, files or dependencies without a task / row /I-nare. - A green test run proves nothing about a test the diff loosened: each
Weakened testline without a task / row that asks for it keeps the verdict at PASS-UNPROVEN until the human accepts it. ADecision:line (the change contradicts an accepted decision of an earlier intent or note that this plan does not supersede) is a FAIL.
Step 3b — what the verifier must not be talked into
- Do not pass your own conclusions ("it works", "tests pass") into the prompt — only command output and paths.
- Do not shorten the plan or hide rows: every task, Reconciliation row and
I-nhas a line in## Report(judged) or in## Carried; none drops out of both (ids inleft the plan:excepted). - Do not re-run the verifier hoping for a milder verdict:
delta: since <sha7> — 0 files changed, run FAIL → do not call it; Next/keystone:fix verify(references/LOOP.md). - A Rules gate
failwith a singleruleline while the project has more MUST / MUST NOT lines is incomplete: the verifier must give one line per rule. Send it back once with the missing rules named. - A missing or unreadable intent: say so, verify against the plan alone, and report the outcome / constraint counts
as
n/a. An intent whose status is notacceptedis reported, not silently trusted. - A plan with no
Settings:line (older plan format): treat asSettings: ok, and saySettings line absent.
Step 3c — implementation notes
Every drift edit of the plan after approval (git log -p <approval commit>..HEAD -- <plan>: a changed task text,
snippet or value) and every decision in the diff the plan did not spell out should have a line in
## Implementation notes. Report Implementation notes: <n> lines; unexplained deviations: <k> — <list>. An
unexplained deviation is not a FAIL by itself; list it under Found: so the human can ask why.
Step 4 — verdict
Strict mode (L by default, or --strict) additionally requires: every task ok (no partial), build and tests pass
(tests are required there unless tests — no), lint clean, no unfinished-work markers and no undocumented env
variables in the changed files, Rules gate pass. Anything short of that is wrong or not proven as in Step 1.
Advisory: and Minor: lines never change the verdict.
- PASS — no
missing,wrong,unrequested,not proven;BLOCKED= 0;Weakened tests: none(or each tied to a task);Decisions: none;Settings: ok;Rules gatenotfail;Architecture gatenotfail;Security gatenot an unignoredfail.pending R<n>rows never block PASS. - PASS-UNPROVEN — no
missing/wrong/unrequested,Settings: ok, Rules gate notfail, but at least onenot provenorBLOCKEDrow, or aWeakened testline no task asks for. - FAIL — anything else: a
missing,wrongorunrequestedline, aDecision:line,Settings: violated,Rules gate: fail(all itsfile:lineunderaccepted violations:→ pass, ACCEPT.md),Architecture gate: fail, an unignoredSecurity gate: fail.
Step 5 — record
<plan folder>/verify.mdwas written in Step 3 in this layout (paths in backticks: Prettier bolds a bare__x__); add the## Verdictline now with Edit:# Verify: <plan name> Date: <YYYY-MM-DD> · Base: <ref> · Verdict: <PASS | PASS-UNPROVEN | FAIL> ## Checks <the Step-1 lines, cost:> ## Carried <the carried: lines | none> ## Report <the verifier output, unchanged> ## Verdict <verdict> — <one line: what is open> Late: <ids, LOOP.md> | none <ok + … = n and Keystone Chain, recomputed with carried rows>PASS → set
Status: verifiedin the plan header (nothing else in the plan), then commit onlyverify.mdand the plan:git add <plan folder>/verify.md <plan>andgit commit -m "docs(verify): <slug>";git diff --cached --statlists exactly those two. Then the ownerrelease --any(ACCEPT.md). Push opens now.PASS-UNPROVEN → status unchanged,
git pushstays closed. Commitverify.mdalone (docs(verify): <slug>). The human chooses in Step 6: prove the open rows now and verify again, or accept them consciously. Commit scope. If the project has commitlint (.commitlintrc*,commitlint.config.*, or acommitlintkey inpackage.json) with ascope-enumrule, use only a scope from that list — the closest one (e.g.docs), or no scope if the rule allows it; never a scope the hook rejects. No scope list → keep the Keystone scope (docs(verify)).FAIL → status unchanged; commit
verify.mdalone. Recommend/keystone:fix verify— it takes every finding from thisverify.md(each failingruleline with all itsfile:line, everywrongline,Settings: violated, an Architecture gatefail) and fixes them in one pass, so verify runs once more, not once per finding — or/keystone:implement(a task never finished). The push gate stays closed. To lift a stuck gate deliberately: setStatus: abandonedin the plan header, or run withKEYSTONE_GATES=off— never as a way around a FAIL.
Re-verifying: each run overwrites verify.md and gets its own commit, so the history shows how the verdict moved.
If the working tree has unrelated uncommitted changes, do not stage them — add the two files by path, never -A.
Nothing to commit (verify.md identical to the committed one) → say verify.md unchanged and skip the commit.
Step 6 — the choice (AskUserQuestion)
A verdict that leaves a decision ends with a menu, not with one command. Print the Final report and the summary first,
then call AskUserQuestion once with the options of references/AFTER-CHOICE.md — read it before asking. FAIL (not after a
verifier: not called run) → after the Step 5 commit run node ${CLAUDE_SKILL_DIR}/scripts/collect.mjs <plan path> --history, show
it; rules menu: on this FAIL → ask the rules menu of references/LOOP.md, else trend menu: on this FAIL → its trend menu.
Context drift. If the diff makes docs/architecture.md, CLAUDE.md or .claude/rules clearly stale, add a
second question to the same AskUserQuestion call as references/AFTER-CHOICE.md says; the final report carries
Context drift: <file — what is stale> | none either way.
After the pick, carry the choice out as AFTER-CHOICE.md says.
Gates. The hooks close git push / gh pr create for this plan's commits until Status: verified; accept and
the ways to lift a gate are in references/ACCEPT.md.
Final report (always)
<verdict>: <plan path> · base <ref> · <n> rows — ok a, missing b, wrong c, not proven d, BLOCKED e, pending f; unrequested u
Decisions: <list> | none
Carried: <k> rows from verify <sha7> | none (full run — <reason>)
Pending: <Row n → R<k>, I-n → R<k>> | none
Debt: <k> open — <D<k> row id, …> (the plan's `## Debt`, after Step 5) | none
Advisory: <a> · Minor: <m>
Keystone Chain: outcomes <covered>/<total>, constraints <covered>/<total>; BLOCKED rows <n>; unrequested <n>; rework signals: <none | list | not measurable>
Open: <the not proven / BLOCKED / failed rows, one line each> | none
Unconfirmed: <what could not be confirmed — looked in <where>, one line each | none>
Context drift: <file — what is stale, owning command> | none
Status: <verified | unchanged (reason)> · verify.md: <path> · commit: <sha> docs(verify): <slug>
The heading Unconfirmed: is mandatory verbatim in the chat answer (not only in verify.md); a list or none.
Run the correctness review below before printing the final report.
The Keystone Chain line is mandatory, recomputed with carried rows, even when everything passes. rework signals: the intent
changed after the plan's first commit → name it; intent and plan first committed together → not measurable.
Correctness review: run the built-in /code-review — verify checks the plan against the diff, not whether the code
is well written. On L, also recommend /keystone:review (its validator always runs) before git push, in Blocked on me:; when the
Security gate is warn or the security report has Needs verification items, also recommend /keystone:pentest <your staging or local URL> to confirm them against the running app.
Roadmap and lessons (one line each, in Found: / Blocked on me:). If the intent has Roadmap: M-<n> and the verdict is
PASS (or accept was just recorded), offer: Milestone M-<n> done? Tick it with /keystone:roadmap — verify never edits
docs/roadmap.md. After a Mode: fix plan, or a FAIL that was later fixed, recommend /keystone:evolve to turn the lesson
into a project rule.
End the report with a fixed three-heading summary, short, after the Final report (the line-by-line report stays in verify.md, not in the chat). It is
followed only by the Next: line: PASS with open ## Release steps → Next: /keystone:implement <plan path> (release
mode; on L /keystone:review first); PASS without them → Next: push and open the PR (L: /keystone:review first); PASS-UNPROVEN → the option chosen in Step 6 (a
Prove now check before /keystone:verify accept <plan path>); FAIL and PASS → the option chosen in Step 6 (FAIL default
/keystone:fix verify, all findings in one pass); after a fix plan or a fixed FAIL, /keystone:evolve may follow later.
Blocked on me: <what needs a human decision, incl. recommended next step | none>
Changed: <files written / status set | none>
Found: <the main defects or open rows | none>