Repository navigation
Description
Decision (owner, 2026-11-12)
Slice 2 of 3 of the formal-verification plugin. The whole design, the directory layout, the decided names and the design rules are on slice 1: Add the formal-verification plugin's chart skill, setup and consumer contract, proven on the loop-lane claim protocol.
Source: her create-formal-verification-skill (cursor/plugins pstack/skills/, MIT), text kept as far as possible.
Depends on
- Add the formal-verification plugin's chart skill, setup and consumer contract, proven on the loop-lane claim protocol #15648: the consumer contract,
chartandsetupthis slice builds on.
This item
/formal-verification:specify with its bare, create and check forms.
- Bare: propose the promise worth proving (promise, harm, tool, and the folder
createwould write); write nothing. create: pick the target from the code ("A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify"); let the question choose the tool (a model checker for bad orderings, a code-level verifier for every-input properties, a proof when a bound is not enough, generated-input tests through/testing:writewhen no verifier exists for the language); generate the model and the consumer'sformal-<area>skill with itssync.yaml; then break the code on a scratch change and confirm the check catches it before hand-off.createtakes a promise as its argument:/formal-verification:specify create "<promise>".- Tool choice: with no tool recorded,
createresearches and recommends one, asks, and records the choice only in that area'sformal-<area>skill ("Tool and why"). A latercreatereads the existingformal-*skills first. specifynever installs a verification tool. For a toolsetupdoes not declare, it names the tool, the reason and the tool's official install page, and stops; unattended it reports "blocked: tool missing".- Attended, with no target named,
createshows the bare form's proposal (promise, harm, tool, folder) and waits for a yes before writing.create --unattendedis a dry run that writes nothing and lists its open questions. - The seeded break is made in a throwaway git worktree, never the person's working tree, and recorded in the
formal-<area>skill. A reused recorded break is still followed by a full rerun. The discarded worktree is outside the unattended write boundary. - When no verifier runs on the language,
createhands off to/testing:write's property guidance, writes noformal-<area>skill, and reports that the area has property tests, not formal verification.
check: a deterministic script and a pass or fail gate on whether a consumer'sformal-<area>skill meets the contract. It edits nothing. It fails on: missing or wrong frontmatter, a missing required section, a missing or invalidsync.yaml, a sync commit that is not an ancestor ofHEAD, a covered path missing atHEAD, no run command. It warns on covered code changed since the sync commit and on verification skills outside the contract. A per-check settingon_stale(warn or fail, default warn) can make stale coverage fail.- This repository runs
checkas a step insideCI Statusover.claude/skills/formal-*once aformal-<area>skill exists; it adds no new required check to a ruleset. - Her quality bar is kept: true to the code, able to fail, findings stay findings (never weaken a property, never change product code unless asked), honest about scope, readable without the tool, cheap to rerun, kept in step with the code.
specifynames no tool. Her TLA+ writing rules stay inchart;specifygets no TLA+ reference file, and keeps a tool-neutralchoose-a-tool.md. Her sentence "TLA+ is the default" is replaced, recorded as a change (ADR 0101).specifyis model-invocable (disable-model-invocation: false), because/corrections:codifychains to it.- This slice does not wait for Route codify findings by capability and hand the build to implement. The enforcement ladder's
formal-verificationrung is opt-in, so this slice adds the line to this repository'sAGENTS.md: "This repository opts in to formal verification:/corrections:codifymay place a rule on the enforcement ladder'sformal-verificationrung."
Before build
The interview ran and the owner confirmed it on 2026-11-14 ("Go with recommendations, whatever the research says, and whatever is the best fit in our repo", then "Confirmed."). The contract's required sections are decided on #15648; what check treats as a failure and how a model invokes the skill are stated above.
Left to planning: how the dogfood's /app-control:drive run is wired (the control skill's feature row, what happens if the drive does not resolve, how many candidates it tries).
Dogfood
A second promise in this repository, chosen by the skill's own bare run, taken through create with the seeded-break proof. The bare form's proposal is taken only if it is a promise other than the claim protocol; if its tool does not resolve or is not installed, the run records that and takes the next candidate.
Owner step
The dogfood's attended create waits for a person's yes on the bare form's proposal before it writes.
Done when
- Bare
/formal-verification:specifyproposes a promise, its harm, its tool and the foldercreatewould write, and changes no file. -
/formal-verification:specify create "<promise>"takes a promise as its argument. -
/formal-verification:specifyskill and reference text name no verification tool, andspecifyhas no TLA+ reference file. -
/formal-verification:specifyno longer carries her sentence "TLA+ is the default", and the change is recorded with ADR 0101 as its reason. - With no tool recorded for an area,
/formal-verification:specify createresearches and recommends a tool, asks, and records the choice only in that area'sformal-<area>skill under "Tool and why". -
/formal-verification:specify createreads the existingformal-*skills before it chooses a tool. -
/formal-verification:specifyinstalls no verification tool. - For a tool
setupdoes not declare,/formal-verification:specifynames the tool, the reason and the tool's official install page, and stops. - Unattended, with its tool missing,
/formal-verification:specifyreports "blocked: tool missing". - Attended
/formal-verification:specify createwith no target named shows the bare form's proposal and writes nothing until a yes. -
/formal-verification:specify create --unattendedwrites nothing and lists its open questions. -
/formal-verification:specify createmakes its seeded break in a throwaway git worktree, never the person's working tree, and the generated check catches it before hand-off. - The
formal-<area>skill/formal-verification:specify creategenerates records its seeded break and meets the formal-verification consumer contract. - When
/formal-verification:specifyreuses a recorded seeded break, a full rerun of the check follows. - When no verifier runs on the language,
/formal-verification:specify createhands off to/testing:write, writes noformal-<area>skill, and reports property tests, not formal verification. -
/formal-verification:specifykeeps her quality bar: true to the code, able to fail, findings stay findings, honest about scope, readable without the tool, cheap to rerun, kept in step with the code. -
/formal-verification:specifyreaches other skills only by slash reference with an "if installed" fallback and copies none ofchart's commands. -
/formal-verification:specifyis model-invocable (disable-model-invocation: false). - The formal-verification
checkscript is deterministic and edits no file. - The formal-verification
checkscript exits non-zero on missing or wrong frontmatter, a missing required section, a missing or invalidsync.yaml, or no run command. - The formal-verification
checkscript exits non-zero on a sync commit that is not an ancestor ofHEADand on a covered path missing atHEAD. - The formal-verification
checkscript warns on covered code changed since the sync commit and on verification skills outside the contract. - The formal-verification
checkscript reads a per-checkon_stalesetting (warn or fail, default warn), andfailmakes stale coverage fail. - The formal-verification
checkscript runs as a step insideCI Statusover.claude/skills/formal-*once aformal-<area>skill exists. - This repository's
AGENTS.mdcarries the line "This repository opts in to formal verification:/corrections:codifymay place a rule on the enforcement ladder'sformal-verificationrung." - The formal-verification dogfood takes a promise other than the claim protocol from the bare form's proposal through
create, and its seeded break is caught. - If the formal-verification dogfood's proposed tool does not resolve or is not installed, the run records that and takes the next candidate.
Out of scope
- The
/corrections:codifyside of the hand-off (Route codify findings by capability and hand the build to implement #15728). - A tool interface for a second checker: not until a second tool exists.
- A CI job that runs the model checker.
Metadata
Metadata
Assignees
Labels
Type
Fields
Work status
Priority
Activity
github-actions commentedon Nov 13, 2026
Size: Medium
Complexity: Medium
Uncertainty: Knowable
Flags: none
Blocked by: #15648
I read this as slice 2 of 3 of the formal-verification plugin. It asks for
/formal-verification:specifywith three forms. The bare form proposes a target and writes nothing.createpicks a target, chooses a tool, generates the model and the consumer'sformal-<area>skill, and proves a seeded break is caught.checkis a read-only pass/fail gate on the contract. It also moves the TLA+ writing rules intoreference/tools/.The design and contract live on slice 1 (#15648), so this depends on it. The codify hand-off also needs the ladder rung from #15708. The issue says to run
/planning:interviewbefore build to lock the contract's required sections, whatchecktreats as a failure, and how a model invokes the skill. Those three points are still open.Related, not duplicates: #15775 (refresh action) and #15728 (codify routing). No merged pull request already covers this.
Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 13, 2026
The triage verdict left this issue at
needs-owner-decision:Reason:
intentkyle-sexton commentedon Nov 14, 2026
Decision recorded. Interview complete, owner-confirmed 2026-11-14 ("Go with recommendations, whatever the research says, and whatever is the best fit in our repo", then "Confirmed."). The shared decisions are on issue #15648. Decisions for this slice:
chart;specifygets noreference/tools/tla-plus.md(correction to the body, per ADR 0101).createresearches and recommends one, asks, and records the choice only in that area'sformal-<area>skill ("Tool and why"). A latercreatereads the existingformal-*skills first.specifynever installs a verification tool. For a toolsetupdoes not declare, it names the tool, the reason and the tool's official install page, and stops; unattended it reports "blocked: tool missing".createshows the bare form's proposal (promise, harm, tool, folder) and waits for a yes before writing.create --unattendedis a dry run that writes nothing and lists its open questions.formal-<area>skill. A reused recorded break is still followed by a full rerun. The discarded worktree is outside the unattended write boundary.checkis a deterministic script. It fails on: missing or wrong frontmatter, a missing required section, a missing or invalidsync.yaml, a sync commit that is not an ancestor ofHEAD, a covered path missing atHEAD, no run command. It warns on covered code changed since the sync commit and on verification skills outside the contract. A per-check settingon_stale(warn or fail, default warn) can make stale coverage fail.checkin CI over.claude/skills/formal-*, required once aformal-<area>skill exists.createhands off to/testing:write's property guidance, writes noformal-<area>skill, and reports that the area has property tests, not formal verification./formal-verification:specify create "<promise>"). The enforcement ladder'sformal-verificationrung is opt-in, so this slice adds the line to this repository'sAGENTS.md: "This repository opts in to formal verification:/corrections:codifymay place a rule on the enforcement ladder'sformal-verificationrung."specifyis model-invocable (disable-model-invocation: false), because/corrections:codifychains to it.Left to planning: how the dogfood's
/app-control:driverun is wired (the control skill's feature row, what happens if the drive does not resolve, how many candidates it tries).