diff --git a/.changes/formal-verification/feat-formal-verification-chart-setup-2f19b369.md b/.changes/formal-verification/feat-formal-verification-chart-setup-2f19b369.md new file mode 100644 index 00000000000..1f2b8583bc1 --- /dev/null +++ b/.changes/formal-verification/feat-formal-verification-chart-setup-2f19b369.md @@ -0,0 +1,11 @@ +--- +bump: minor +--- + +### Added + +- The `formal-verification` plugin, off by default. +- `/formal-verification:chart` model-checks a TLA+ spec with TLC and writes a Mermaid chart of its states and a report with the shortest path to each broken rule. Its scripts take the jar, Java and bounds as arguments and install nothing. +- `/formal-verification:setup` checks the script runtime, Java, the model checker and the renderer, and on a typed `apply install-model-checker` or `apply install-renderer` downloads the pinned file into the plugin data directory, keeping it only when its checksum matches. +- `reference/formal-skill.md`, the contract for a consumer's `formal-` skill: its sections, one `sync.yaml` entry per check, the view file the chart reads, and where model files and unattended writes may go. +- Version pins and default bounds as keys of the consumer's `docs/conventions/formal-verification.yaml`, and the jar, Java and script-runtime paths as plugin options. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index efaf09ff813..fe07b3a2db1 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -611,6 +611,21 @@ "skill" ] }, + { + "name": "formal-verification", + "source": "./plugins/formal-verification", + "category": "testing", + "tags": [ + "formal-verification", + "tla-plus", + "tlc", + "model-checking", + "statechart", + "mermaid", + "skill" + ], + "defaultEnabled": false + }, { "name": "code-tidying", "source": "./plugins/code-tidying", diff --git a/.claude/skills/formal-claim-protocol/SKILL.md b/.claude/skills/formal-claim-protocol/SKILL.md new file mode 100644 index 00000000000..0ad74a77056 --- /dev/null +++ b/.claude/skills/formal-claim-protocol/SKILL.md @@ -0,0 +1,162 @@ +--- +name: formal-claim-protocol +description: "TLA+ model of the work-item tracker's GitHub claim protocol: one issue claimed at once by a local session's default claim, the issue lane's lease-only claim and a triage claim, each able to renew once and release, with lease expiry, the 300 s skew margin, the completed-run rule and the assignee hand-back. Use when a change touches the GitHub adapter's claim.sh, renew-lease.sh, release.sh, common.sh, lib/lease.sh or the tracker contract's Lease protocol, or to ask whether two claimants can both work one item." +disable-model-invocation: true +--- + +# Formal check: the claim protocol + +## Property + +Each rule is an INVARIANT in `model/ClaimProtocol.tla`; the quoted line is the source it encodes. +Paths are under `plugins/work-items/tools/work-item-tracker/`. + +| Rule | Plain sentence | Source | +|---|---|---| +| `OneHolder` | At most one claimant works the item while its own lease is live. | `CONTRACT.md` "Lease protocol" step 4: "If an earlier live lease exists that is not our own comment, the foreign lease wins → supersede own comment, exit `7`."; `adapters/github/claim.sh`: "# Earliest LIVE lease wins." | +| `LaneAssignsNoOne` | The issue lane's lease-only claim never assigns anyone. | CONTRACT.md: "**Lease-only (`--lease-only`):** the claim posts the lease comment and assigns no one." | +| `HolderAssigned` | A default claimant that holds the item is assigned to it. | CONTRACT.md: "Claim = **assignee (authenticated human user) + lease record**." | +| `NoStrandedAssignee` | Every assigned login belongs to a claim still in flight. | `adapters/github/claim.sh`: "any failure before a successful lease-comment write (step 3) would otherwise strand the issue assigned with no lease record" | +| `LoserSupersedesOwn` | A claimant that lost arbitration has superseded its own lease. | CONTRACT.md step 4: "the foreign lease wins → supersede own comment, exit `7`." | +| `CompletedRunHoldsNothing` | No claimant backs off from a lease whose run had completed. | CONTRACT.md step 4: "A run whose `status` is `completed`, whatever its conclusion, holds nothing, so its lease is superseded in place" | +| `ReleaseFreesItem` | A claimant that released no longer holds a live lease. | CONTRACT.md, Release: "a session that has finished with an item hands it back at once instead of blocking every later claim" | + +How each rule reads the model's states: + +- "Works the item" (`Holding`): the claim returned success, no release returned success, no renew + told the session it lost or is still re-checking after a late renew, and its own lease is live. +- `HolderAssigned` is checked in quiescent states only (every claimant holds, has finished, or has + not started): the hand-back removes and restores a same-login holder's assignee two calls apart. +- "In flight" (`NoStrandedAssignee`): a default claimant of that login has started and not + returned: it is claiming, holds the item, or is renewing, releasing or handing back. +- `LoserSupersedesOwn` covers a claimant that lost, failed or died; it assumes writes succeed, + since the supersede is best-effort. +- `CompletedRunHoldsNothing` records the moment a claimant's decision goes against the lane's + lease while the lane's run has completed. + +`TypeOK` checks the variables' types. `EndStateReclaimable` is an extra rule, outside the seven the owner approved +(`adapters/github/claim.sh`: "reclaim ignores items with no lease"): once every claimant +has finished and no lease is live, any assignee left is the holder of the active lease, which +reclaim unassigns. + +## Harm + +Two sessions work the same issue at once and push conflicting changes, or an issue stays assigned +with nobody working it and drops off the frontier. + +## Tool and why + +TLA+ with TLC, read through `/formal-verification:chart`. The question is whether the GitHub calls +of three sessions can interleave into a bad order; a model checker tries every order of a small +model, and the races live between comment, assignee and clock reads that no unit test sequences. + +## Bounds and assumptions + +- One issue; three claimants: `local` (login `human`), the lane (holder `bot`, `--lease-only`, + `session_id` `run-`) and `triage` (login `human` or `other`; both are explored). The cfg's + `Starters` names the claimants that start a claim. +- Each claimant claims once, renews at most once (`WithRenew`) and releases at most once; at most + three lease comments; one renewal generation per lease. +- Every GitHub read and write is its own step. A lease list retried once is one step. +- One clock for every claimant: entering the 300 s margin and expiring are global events per lease. + With `BoundedStall`, a body read more than 300 s before its expiry is judged before it expires, + and a renew that judged its lease outside the margin PATCHes before it expires. +- Lease comment ids grow in posting order. +- The lane's run can end at any point after its lease is posted, without releasing. +- Failures are off unless a cfg turns them on: `WritesMayFail` (each best-effort write may fail), + `ReadsMayFail` (the reads whose failure does not exit may fail), `MayDie` (a claimant may die + between any two steps; a checked call's failure exits the same way). `RenewDeathKeepsHolding` + is `FALSE`: a renew that dies after its PATCH ends the session. +- The cfg uses `VIEW View`, which drops script-local values a claimant never reads again. Under + it TLC's distinct-state count depends on exploration order; the chart command runs one worker, + so its count is stable. +- The model is finite, so no bound limits the first pass; the run commands pass + `--rerun-states` to cover it after a break. +- The seeded break in `sync.yaml` was run against this model: with the winner taken as the latest + live lease, `OneHolder` breaks in `LocalLane.cfg` after 1,415 distinct states (`caught: true`). + +## Not covered + +- Reclaim, the local-markdown and other adapters, the role-label flip, a second renew, and an + assignee a person adds by hand. +- A comment from an author the adapter does not count, a cross-issue or foreign handle, and + `gh api user` reads. +- Time passing between renew's PATCH and its clock read after it: the model takes both in one + step, so it never shows a renew that landed in time but reads its clock inside the margin or + past the old expiry (the code then re-lists or backs off). +- A PATCH that GitHub applies but reports as failed (renew's or release's), a lease + `renewed_at` more than 300 s in the future, a TTL over the cap, and the pause between writes. +- Three sessions on one login: the model has at most two. With three, a hand-back's last removal + can land after a third session's claim won, leaving that holder unassigned (issue 16505). +- `WithRenew = TRUE` with all three claimants: that space is over 100 million states. The shipped + checks run two claimants each. All three without renew (`Starters = {"local", "lane", "triage"}`, + `WithRenew = FALSE`) hold every rule at a548b3aaab8c: 202,568,284 states, 25 minutes on 20 + workers, so it is a hand run and not a shipped check. +- The tracker contract's documented limits are reported as known limits, never as defects: + clock skew ("Liveness compares provider timestamps (`renewed_at` in the marker) to the local + clock"), ttl-0 ("A claim with `ttl_hours: 0` and `ttl_minutes: 0` is born expired"), + comment-id monotonicity ("adapters MUST emit ordered unique numeric `lease_comment_id` + handles"), the ambiguous lease post ("A lease comment POST that GitHub applies but reports as + failed (a timeout) returns no comment id"), and no compare-and-swap ("GitHub's comment PATCH + has no If-Match/CAS, so a concurrent writer can still interleave"). + +## Run + +One command per cfg; each takes two to three minutes: + +```text +/formal-verification:chart .claude/skills/formal-claim-protocol/model/ClaimProtocol.tla --config .claude/skills/formal-claim-protocol/model/LocalLane.cfg --view .claude/skills/formal-claim-protocol/model/view.mjs --rerun-states 2000000 +/formal-verification:chart .claude/skills/formal-claim-protocol/model/ClaimProtocol.tla --config .claude/skills/formal-claim-protocol/model/LocalTriage.cfg --view .claude/skills/formal-claim-protocol/model/view.mjs --rerun-states 2000000 +``` + +`LocalLane.cfg` runs the local session against the issue lane, `LocalTriage.cfg` the local session +against a triage claim; both with renew, every failure off and `BoundedStall`. `--rerun-states` +must cover the whole space (1,686,588 and 1,356,633 states): after a rule breaks, the command rechecks +the others under that bound, and a smaller bound leaves them not checked. + +Pass a new `--out` folder each run. + +## Reading a result + +Replay each counterexample step by step against the scripts on a scratch issue, one call per +action. The actions are named for the calls they model: `Assign`, `CheckRead`, `ReAssign`, +`PostLease`, `ReadLeases`, `ArbJudge`, `ArbRunRead`, `ArbRunSup`, `LossSup`, `WinRead` and +`WinAdd` are `claim.sh`; `RenewStart`, `RenewPatch`, `Ren2Leases`, `Ren2Judge` and `RenSup` are +`renew-lease.sh`; `ReleaseStart`, `RelJudgeOwn` and `RelPatch` are `release.sh`; `GLeases` to +`GRm3` are the hand-back, `wit_hand_back_assignee` in `common.sh`; `TrapSup` is claim's abort +trap; `Die` is a death or an exiting failure; `RunCompletes`, `Approach` (300 s before expiry) and +`Expire` are the world. Each action's comment in the model cites its lines. If a bug does not +occur, think that the model is wrong until you show that it is not. A path that reproduces is a +bug: write it up with `/bugs:write`. A path that needs a documented limit to fail is reported as +that limit. + +Known results at the sync commit (a run that shows only these has found nothing new): + +- Both shipped cfgs hold every rule. +- With `WritesMayFail = TRUE`, `NoStrandedAssignee` and `EndStateReclaimable` break in both + starter sets: a release's PATCH fails, the release exits with no hand-back, and its login stays + assigned beside its live lease; once a later lease is the active one, reclaim no longer removes + that login. In `{"local","triage"}` `HolderAssigned` breaks: a same-login hand-back removed the + login and the winner's re-add fails. A known limit: these writes are best-effort or exit on + failure. +- With `ReadsMayFail = TRUE`, `OneHolder` breaks: renew's re-list after a PATCH inside the margin + fails twice and the renewed lease is kept while a newer claimant holds. By design: "a list it + still cannot read keeps the renewed lease (exit `0`, with a warning)". `CompletedRunHoldsNothing` + breaks in `{"local","lane"}`: "A run in any other status, or a read that fails, keeps the lease + winning." In `{"local","triage"}` `HolderAssigned`, `NoStrandedAssignee` and + `EndStateReclaimable` break: a hand-back whose lease list fails twice counts it as empty or + stops at the re-list, so it removes a same-login holder's login or leaves a login no lease + holds. By design: "a failed list counts as empty". +- With `MayDie = TRUE`, `NoStrandedAssignee` and `EndStateReclaimable` break (a claim killed + during its own rollback leaves its assignee with no lease, which reclaim ignores), and in + `{"local","triage"}` `HolderAssigned` breaks (a same-login hand-back killed between its removal + and its re-list). A known limit: a killed process cannot finish its exit trap. + +## Updating + +When a covered file in `sync.yaml` changes, read the change against the model: a call split in +two, a new branch, a retry, or a moved check means the model changes; a promise changed on purpose +means a rule changes, and only with the owner's yes. Never weaken a rule to make it hold. Move +`commit` forward only after confirming the model describes the code at the new commit, re-cite +the changed line numbers in the model's comments, rerun every shipped cfg and the seeded break, +and update the known results above. diff --git a/.claude/skills/formal-claim-protocol/model/ClaimProtocol.tla b/.claude/skills/formal-claim-protocol/model/ClaimProtocol.tla new file mode 100644 index 00000000000..98931ec4cd1 --- /dev/null +++ b/.claude/skills/formal-claim-protocol/model/ClaimProtocol.tla @@ -0,0 +1,715 @@ +---------------------------- MODULE ClaimProtocol ---------------------------- +\* One GitHub issue claimed by three claimants of the work-item tracker's +\* GitHub adapter (CONTRACT.md "Lease protocol"): +\* local - a default claim from a local session, login "human" +\* lane - the issue lane's --lease-only claim, session_id run-, +\* holder "bot", inside a workflow run that can complete +\* triage - a default claim, login "human" or "other" +\* A holder may renew once (renew-lease.sh) and release once (release.sh). +\* Every GitHub read and write is its own step. Line numbers are at commit +\* a548b3aaab8c; paths are under plugins/work-items/tools/work-item-tracker/, +\* the scripts under adapters/github/. + +EXTENDS Naturals, Sequences, FiniteSets + +CONSTANTS + Starters, \* the claimants that may start a claim + WithRenew, \* a holder runs renew-lease at most once + WritesMayFail, \* each best-effort write may fail + ReadsMayFail, \* the reads whose failure does not exit may fail + MayDie, \* a claimant may die between any two of its steps + BoundedStall, \* a renew that judged its lease outside the margin PATCHes before it expires + RenewDeathKeepsHolding \* a renew killed after its PATCH leaves the session working + +Claimants == {"local", "lane", "triage"} +DefaultClaims == {"local", "triage"} +Logins == {"human", "other", "bot"} + +VARIABLES + pc, ctx, leases, assignees, runDone, triageLogin, + mine, \* own lease comment id, 0 before the post + snap, \* last lease list read: [sup, gen, near] per comment + live, cand, win, + bodyGen, \* generation of the own body as release/renew read it + renewed, + nearSeen, \* renew: the margin test at its clock sample + after, \* where the hand-back ends + backedOffDone \* the claimant's decision went against a run lease whose run had completed + +vars == <> + +LoginOf(c) == CASE c = "local" -> "human" + [] c = "lane" -> "bot" + [] OTHER -> triageLogin + +\* gen = renewals so far; generations below expN have expired; near = the +\* current generation is within the 300 s skew margin (lib/lease.sh:12) of +\* its expiry. +LeaseRec == [by : Claimants, holder : Logins, run : BOOLEAN, + sup : BOOLEAN, gen : 0..1, expN : 0..2, near : BOOLEAN] +SnapRec == [sup : BOOLEAN, gen : 0..1, near : BOOLEAN, exp : 0..2] + +WriteOutcomes == IF WritesMayFail THEN BOOLEAN ELSE {TRUE} +ReadOutcomes == IF ReadsMayFail THEN BOOLEAN ELSE {TRUE} + +Min(S) == CHOOSE i \in S : \A j \in S : i <= j +Max(S) == CHOOSE i \in S : \A j \in S : i >= j + +Final == {"lost", "failed", "dead", "released", "relFail", "relDead", "gone", + "renLost"} +RenewPre == {"renLeases", "arbJudge", "arbRunRead", "arbRunSup", "renPatch"} + +\* The margin matters only while the lease's owner can still renew it. +NeedsNear(i) == + LET c == leases[i].by + IN WithRenew /\ \/ ~renewed[c] /\ pc[c] \notin Final + \/ ctx[c] = "renew" /\ pc[c] \in RenewPre + +\* lib/lease.sh:128-136 wit_lease_is_live. +LiveNow(i) == ~leases[i].sup /\ leases[i].expN <= leases[i].gen +\* A body read outside the margin of its expiry is judged before it expires +\* when stalls are bounded. +SnapLive(s, i) == ~s[i].sup /\ (leases[i].expN <= s[i].gen + \/ (BoundedStall /\ ~s[i].near)) +Snapshot == [i \in 1..Len(leases) |-> + [sup |-> leases[i].sup, gen |-> leases[i].gen, + near |-> leases[i].near \/ ~NeedsNear(i), exp |-> 0]] +\* The hand-back reads its clock before each lease list: exp is each lease's +\* expired generations at that clock read, kept beside the bodies listed after. +ClockSnap == [i \in 1..Len(leases) |-> + [sup |-> FALSE, gen |-> 0, near |-> FALSE, + exp |-> leases[i].expN]] +ListSnap(c) == [i \in 1..Len(leases) |-> + [sup |-> leases[i].sup, gen |-> leases[i].gen, near |-> FALSE, + exp |-> IF i \in DOMAIN snap[c] THEN snap[c][i].exp ELSE 0]] +\* lib/lease.sh:44-58 wit_select_active_lease: the newest non-superseded lease. +ActiveIn(s) == LET open == {i \in DOMAIN s : ~s[i].sup} + IN IF open = {} THEN 0 ELSE Max(open) +ActiveNow == ActiveIn(Snapshot) + +\* adapters/github/common.sh:534-543 _wit_login_holds_other on the list in +\* snap[c], judged at the clock read before the list. The code also counts a +\* lease live at a later read (:540), which differs only for a renewed_at +\* ahead of the reader's clock; the model has one clock. +HoldsOther(c) == \E i \in DOMAIN snap[c] : + /\ i # mine[c] + /\ leases[i].holder = LoginOf(c) + /\ ~snap[c][i].sup + /\ snap[c][i].exp <= snap[c][i].gen + +Alive(c) == c = "lane" => ~runDone + +Guarded == {"gLeases", "gList", "gJudge", "gARead", "gRm", "gRead2", "gList2", + "gJudge2", "gAdd", "gRead3", "gList3", "gJudge3", "gRm3"} +ClaimRollback == {"assigned", "reAssign", "checked2", "checked"} +ClaimAbort == {"posted", "arbJudge", "arbRunRead", "arbRunSup", "lossSup", + "winRead", "winAdd"} +RenewPost == {"ren2Leases", "ren2Judge", "renSup"} +ReleaseMid == {"relLeases", "relJudgeOwn", "arbJudge", "arbRunRead", + "arbRunSup", "relPatch", "relSup"} +Pcs == {"idle", "held", "tSup"} \cup Final \cup Guarded \cup ClaimRollback + \cup ClaimAbort \cup RenewPre \cup RenewPost \cup ReleaseMid + +SupersedeWrite(i, g, ok) == + leases' = IF ok THEN [leases EXCEPT ![i].sup = TRUE, ![i].gen = g] + ELSE leases +AddLogin(c, ok) == + assignees' = IF ok THEN assignees \cup {LoginOf(c)} ELSE assignees +RemoveLogin(c, ok) == + assignees' = IF ok THEN assignees \ {LoginOf(c)} ELSE assignees + +Init == + /\ pc = [c \in Claimants |-> "idle"] + /\ ctx = [c \in Claimants |-> "claim"] + /\ leases = <<>> + /\ assignees = {} + /\ runDone = FALSE + /\ triageLogin \in {"human", "other"} + /\ mine = [c \in Claimants |-> 0] + /\ snap = [c \in Claimants |-> <<>>] + /\ live = [c \in Claimants |-> {}] + /\ cand = [c \in Claimants |-> 0] + /\ win = [c \in Claimants |-> 0] + /\ bodyGen = [c \in Claimants |-> 0] + /\ renewed = [c \in Claimants |-> FALSE] + /\ nearSeen = [c \in Claimants |-> FALSE] + /\ after = [c \in Claimants |-> "failed"] + /\ backedOffDone = [c \in Claimants |-> FALSE] + +----------------------------------------------------------------------------- +\* claim.sh + +\* :93 assign (REST may drop the login silently, common.sh:217-220); the +\* rollback trap of :85-88 is armed. +Assign(c) == + /\ c \in DefaultClaims \cap Starters /\ pc[c] = "idle" + /\ \E ok \in WriteOutcomes : AddLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = "assigned"] + /\ UNCHANGED <> + +\* :96-118 read the assignees. Own login missing: one re-assign and re-read +\* (:104-108), then exit 4 (:109-113). Another login: exit 7 (:114-118). Both +\* exits run the rollback trap: the hand-back. +CheckRead(c) == + /\ pc[c] \in {"assigned", "checked2"} + /\ pc' = [pc EXCEPT ![c] = + IF LoginOf(c) \notin assignees + THEN (IF pc[c] = "assigned" THEN "reAssign" ELSE "gLeases") + ELSE IF \E l \in assignees : l # LoginOf(c) + THEN "gLeases" + ELSE "checked"] + /\ UNCHANGED <> + +\* :105 the one re-assign; :106 re-reads (CheckRead from "checked2"). +ReAssign(c) == + /\ pc[c] = "reAssign" + /\ \E ok \in WriteOutcomes : AddLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = "checked2"] + /\ UNCHANGED <> + +\* :121-132 post the lease; the abort trap of :137-141 is armed. The lane +\* (lease-only, :75-76) starts here. +PostLease(c) == + /\ \/ c \in DefaultClaims /\ pc[c] = "checked" + \/ c = "lane" /\ c \in Starters /\ pc[c] = "idle" /\ ~runDone + /\ leases' = Append(leases, [by |-> c, holder |-> LoginOf(c), + run |-> (c = "lane"), sup |-> FALSE, + gen |-> 0, expN |-> 0, near |-> FALSE]) + /\ mine' = [mine EXCEPT ![c] = Len(leases) + 1] + /\ pc' = [pc EXCEPT ![c] = "posted"] + /\ UNCHANGED <> + +\* Every checked read of the lease list (a failure exits: Die): claim.sh:150, +\* renew-lease.sh:63, release.sh:94. +ReadLeases(c) == + /\ Alive(c) + /\ pc[c] \in {"posted", "renLeases", "relLeases"} + /\ snap' = [snap EXCEPT ![c] = Snapshot] + /\ pc' = [pc EXCEPT ![c] = + IF pc[c] = "relLeases" THEN "relJudgeOwn" ELSE "arbJudge"] + /\ UNCHANGED <> + +\* What each script does with the winner. Claim, claim.sh:160-164: another +\* winner backs off. Renew, renew-lease.sh:66-83: another winner refuses; +\* inside the margin (as sampled with the winner's clock) the lease must also +\* be the newest non-superseded one. Release, release.sh:113-125: another +\* winner refuses with exit 7 after superseding its own lease (RelSup). +Decide(c, w) == + /\ win' = [win EXCEPT ![c] = w] + /\ pc' = [pc EXCEPT ![c] = + CASE ctx[c] = "claim" -> + (IF w = 0 \/ w = mine[c] + THEN (IF c \in DefaultClaims THEN "winRead" ELSE "held") + ELSE "lossSup") + [] ctx[c] = "renew" -> + (IF w = mine[c] + /\ (nearSeen'[c] => ActiveIn(snap[c]) = mine[c]) + THEN "renPatch" ELSE "held") + [] OTHER -> (IF w = mine[c] THEN "relPatch" ELSE "relSup")] + +\* lib/lease.sh:68-86 wit_lease_winner with one clock sample: the earliest +\* live lease; a run lease that is not ours costs a run-status read. +Judge(c) == + LET S == {i \in DOMAIN snap[c] : SnapLive(snap[c], i)} + w0 == IF S = {} THEN 0 ELSE Min(S) + IN /\ live' = [live EXCEPT ![c] = S] + /\ cand' = [cand EXCEPT ![c] = w0] + /\ nearSeen' = [nearSeen EXCEPT ![c] = + ctx[c] = "renew" /\ leases[mine[c]].near] + /\ IF w0 # 0 /\ w0 # mine[c] /\ leases[w0].run + THEN /\ pc' = [pc EXCEPT ![c] = "arbRunRead"] + /\ UNCHANGED win + ELSE Decide(c, w0) + +\* claim.sh:151, renew-lease.sh:64-65. +ArbJudge(c) == + /\ Alive(c) /\ pc[c] = "arbJudge" + /\ Judge(c) + /\ UNCHANGED <> + +\* common.sh:478-492 wit_lease_released_by_run: the run-status read (:484). A +\* failed read keeps the lease winning (:484-487). +ArbRunRead(c) == + /\ Alive(c) /\ pc[c] = "arbRunRead" + /\ UNCHANGED nearSeen + /\ \E ok \in ReadOutcomes : + /\ backedOffDone' = [backedOffDone EXCEPT ![c] = @ \/ (~ok /\ runDone)] + /\ IF ok /\ runDone + THEN /\ pc' = [pc EXCEPT ![c] = "arbRunSup"] + /\ UNCHANGED win + ELSE Decide(c, cand[c]) + /\ UNCHANGED <> + +\* common.sh:489 the completed run's lease is superseded, best-effort; the +\* winner is the next live lease. +ArbRunSup(c) == + /\ Alive(c) /\ pc[c] = "arbRunSup" + /\ UNCHANGED nearSeen + /\ \E ok \in WriteOutcomes : + SupersedeWrite(cand[c], snap[c][cand[c]].gen, ok) + /\ LET rest == live[c] \ {cand[c]} + IN Decide(c, IF rest = {} THEN 0 ELSE Min(rest)) + /\ UNCHANGED <> + +\* :163 exit 7 runs the abort trap (:137-140): supersede own lease +\* (common.sh:465-470), then a default claim's hand-back (:85-87). +LossSup(c) == + /\ Alive(c) /\ pc[c] = "lossSup" + /\ \E ok \in WriteOutcomes : SupersedeWrite(mine[c], 0, ok) + /\ after' = [after EXCEPT ![c] = "lost"] + /\ pc' = [pc EXCEPT ![c] = IF c \notin DefaultClaims THEN "lost" ELSE "gLeases"] + /\ UNCHANGED <> + +\* common.sh:506-521 wit_hand_back_assignee, run by a claim's failure paths +\* and back-off, by release, and by renew's back-off. Each lease list retries +\* once (one step here; a failed read means both attempts failed). +\* :508-509 list (a failed list counts as empty); stop on another live lease +\* of the login. +GLeases(c) == + /\ Alive(c) /\ pc[c] = "gLeases" + /\ snap' = [snap EXCEPT ![c] = ClockSnap] + /\ pc' = [pc EXCEPT ![c] = "gList"] + /\ UNCHANGED <> + +GList(c) == + /\ Alive(c) /\ pc[c] = "gList" + /\ \E ok \in ReadOutcomes : + snap' = [snap EXCEPT ![c] = IF ok THEN ListSnap(c) ELSE <<>>] + /\ pc' = [pc EXCEPT ![c] = "gJudge"] + /\ UNCHANGED <> + +GJudge(c) == + /\ Alive(c) /\ pc[c] = "gJudge" + /\ pc' = [pc EXCEPT ![c] = IF HoldsOther(c) THEN after[c] ELSE "gARead"] + /\ UNCHANGED <> + +\* :510-512 a successful assignee read without the login ends it. +GARead(c) == + /\ Alive(c) /\ pc[c] = "gARead" + /\ \E ok \in ReadOutcomes : + pc' = [pc EXCEPT ![c] = + IF ok /\ LoginOf(c) \notin assignees THEN after[c] ELSE "gRm"] + /\ UNCHANGED <> + +\* :513 best-effort removal. +GRm(c) == + /\ Alive(c) /\ pc[c] = "gRm" + /\ \E ok \in WriteOutcomes : RemoveLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = "gRead2"] + /\ UNCHANGED <> + +\* :514-515 re-list (a failed list ends it). +GRead2(c) == + /\ Alive(c) /\ pc[c] = "gRead2" + /\ snap' = [snap EXCEPT ![c] = ClockSnap] + /\ pc' = [pc EXCEPT ![c] = "gList2"] + /\ UNCHANGED <> + +GList2(c) == + /\ Alive(c) /\ pc[c] = "gList2" + /\ \E ok \in ReadOutcomes : + IF ok THEN /\ snap' = [snap EXCEPT ![c] = ListSnap(c)] + /\ pc' = [pc EXCEPT ![c] = "gJudge2"] + ELSE /\ UNCHANGED snap + /\ pc' = [pc EXCEPT ![c] = after[c]] + /\ UNCHANGED <> + +GJudge2(c) == + /\ Alive(c) /\ pc[c] = "gJudge2" + /\ pc' = [pc EXCEPT ![c] = IF HoldsOther(c) THEN "gAdd" ELSE after[c]] + /\ UNCHANGED <> + +\* :516 best-effort re-add. +GAdd(c) == + /\ Alive(c) /\ pc[c] = "gAdd" + /\ \E ok \in WriteOutcomes : AddLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = "gRead3"] + /\ UNCHANGED <> + +\* :519-520 after a re-add the leases are listed once more; the login comes +\* off again when the lease it was put back for is gone (a failed list keeps it). +GRead3(c) == + /\ Alive(c) /\ pc[c] = "gRead3" + /\ snap' = [snap EXCEPT ![c] = ClockSnap] + /\ pc' = [pc EXCEPT ![c] = "gList3"] + /\ UNCHANGED <> + +GList3(c) == + /\ Alive(c) /\ pc[c] = "gList3" + /\ \E ok \in ReadOutcomes : + IF ok THEN /\ snap' = [snap EXCEPT ![c] = ListSnap(c)] + /\ pc' = [pc EXCEPT ![c] = "gJudge3"] + ELSE /\ UNCHANGED snap + /\ pc' = [pc EXCEPT ![c] = after[c]] + /\ UNCHANGED <> + +GJudge3(c) == + /\ Alive(c) /\ pc[c] = "gJudge3" + /\ pc' = [pc EXCEPT ![c] = IF HoldsOther(c) THEN after[c] ELSE "gRm3"] + /\ UNCHANGED <> + +GRm3(c) == + /\ Alive(c) /\ pc[c] = "gRm3" + /\ \E ok \in WriteOutcomes : RemoveLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = after[c]] + /\ UNCHANGED <> + +\* claim.sh:169-174 on a win, re-read the assignees and put the login back. +WinRead(c) == + /\ pc[c] = "winRead" + /\ pc' = [pc EXCEPT ![c] = + IF LoginOf(c) \in assignees THEN "held" ELSE "winAdd"] + /\ UNCHANGED <> + +WinAdd(c) == + /\ pc[c] = "winAdd" + /\ \E ok \in WriteOutcomes : AddLogin(c, ok) + /\ pc' = [pc EXCEPT ![c] = "held"] + /\ UNCHANGED <> + +\* claim.sh:137-140 the abort trap after a failure: best-effort supersede, +\* then a default claim's hand-back. +TrapSup(c) == + /\ Alive(c) /\ pc[c] = "tSup" + /\ \E ok \in WriteOutcomes : SupersedeWrite(mine[c], 0, ok) + /\ pc' = [pc EXCEPT ![c] = IF c \in DefaultClaims THEN "gLeases" ELSE "failed"] + /\ UNCHANGED <> + +----------------------------------------------------------------------------- +\* renew-lease.sh + +\* :34-59 read our comment; refuse a superseded (:47-50) or expired (:55-59) +\* lease. +RenewStart(c) == + /\ WithRenew /\ Alive(c) /\ pc[c] = "held" /\ ~renewed[c] + /\ renewed' = [renewed EXCEPT ![c] = TRUE] + /\ ctx' = [ctx EXCEPT ![c] = "renew"] + /\ IF LiveNow(mine[c]) + THEN /\ pc' = [pc EXCEPT ![c] = "renLeases"] + /\ bodyGen' = [bodyGen EXCEPT ![c] = leases[mine[c]].gen] + ELSE UNCHANGED <> + /\ UNCHANGED <> + +\* :85-86, :103 rewrite the whole body as read with a fresh renewed_at; +\* :117-120 sample the clock after the PATCH (in this same step): at or past +\* the old expiry, back off (:118-119); inside the margin before it, re-list +\* (:120). +\* A failed PATCH at or near the old expiry backs off (:105-106); any other +\* failed PATCH exits (:107). +RenewPatch(c) == + /\ Alive(c) /\ pc[c] = "renPatch" + /\ \E ok \in WriteOutcomes : + IF ok + THEN /\ leases' = [leases EXCEPT ![mine[c]].sup = FALSE, + ![mine[c]].gen = bodyGen[c] + 1, + ![mine[c]].near = FALSE] + /\ pc' = [pc EXCEPT ![c] = + IF leases[mine[c]].expN > bodyGen[c] THEN "renSup" + ELSE IF leases[mine[c]].near THEN "ren2Leases" + ELSE "held"] + ELSE /\ UNCHANGED leases + /\ pc' = [pc EXCEPT ![c] = + IF leases[mine[c]].expN > bodyGen[c] \/ leases[mine[c]].near + THEN "renSup" ELSE "held"] + /\ UNCHANGED <> + +\* :121-122 re-list, one retry; a list still unread keeps the lease (:125-126). +Ren2Leases(c) == + /\ Alive(c) /\ pc[c] = "ren2Leases" + /\ \E ok \in ReadOutcomes : + IF ok THEN /\ snap' = [snap EXCEPT ![c] = Snapshot] + /\ pc' = [pc EXCEPT ![c] = "ren2Judge"] + ELSE /\ UNCHANGED snap + /\ pc' = [pc EXCEPT ![c] = "held"] + /\ UNCHANGED <> + +\* :123-124 a newer live lease (lib/lease.sh:90-97 wit_newer_live_lease) +\* makes it back off. +Ren2Judge(c) == + /\ Alive(c) /\ pc[c] = "ren2Judge" + /\ pc' = [pc EXCEPT ![c] = + IF \E i \in DOMAIN snap[c] : i > mine[c] /\ SnapLive(snap[c], i) + THEN "renSup" ELSE "held"] + /\ UNCHANGED <> + +\* :90-99 back_off: supersede the renewed lease, two tries (:91-92); the +\* hand-back (:93) only when one succeeded; exit 7: the session stops. +RenSup(c) == + /\ Alive(c) /\ pc[c] = "renSup" + /\ \E ok \in WriteOutcomes : + /\ SupersedeWrite(mine[c], bodyGen[c] + 1, ok) + /\ pc' = [pc EXCEPT ![c] = IF ok THEN "gLeases" ELSE "renLost"] + /\ after' = [after EXCEPT ![c] = "renLost"] + /\ UNCHANGED <> + +----------------------------------------------------------------------------- +\* release.sh + +\* :47-59 read our comment. Already superseded (:80-86): hand back, exit 0. +ReleaseStart(c) == + /\ Alive(c) /\ pc[c] = "held" + /\ ctx' = [ctx EXCEPT ![c] = "release"] + /\ bodyGen' = [bodyGen EXCEPT ![c] = leases[mine[c]].gen] + /\ pc' = [pc EXCEPT ![c] = + IF ~leases[mine[c]].sup THEN "relLeases" ELSE "gLeases"] + /\ after' = [after EXCEPT ![c] = "released"] + /\ UNCHANGED <> + +\* :95 one clock sample judges our body and the winner. Expired (:100-109): +\* hand back, then exit 0 when we are the newest non-superseded lease, else +\* exit 7. Live: judge the winner (:113-125). +RelJudgeOwn(c) == + /\ Alive(c) /\ pc[c] = "relJudgeOwn" + /\ IF leases[mine[c]].expN <= bodyGen[c] + THEN Judge(c) /\ UNCHANGED after + ELSE /\ UNCHANGED <> + /\ pc' = [pc EXCEPT ![c] = "gLeases"] + /\ after' = [after EXCEPT ![c] = + IF ActiveIn(snap[c]) = mine[c] THEN @ ELSE "relFail"] + /\ UNCHANGED <> + +\* :127-129 PATCH superseded_at (a failure exits, no hand-back), then the +\* hand-back (:74-78). +RelPatch(c) == + /\ Alive(c) /\ pc[c] = "relPatch" + /\ \E ok \in WriteOutcomes : + IF ok + THEN /\ leases' = [leases EXCEPT ![mine[c]].sup = TRUE, + ![mine[c]].gen = bodyGen[c]] + /\ pc' = [pc EXCEPT ![c] = "gLeases"] + ELSE /\ UNCHANGED leases + /\ pc' = [pc EXCEPT ![c] = "relFail"] + /\ UNCHANGED <> + +\* An outranked live handle: supersede the own lease (two tries, one step +\* here), the hand-back only after a supersede succeeded, exit 7. +RelSup(c) == + /\ Alive(c) /\ pc[c] = "relSup" + /\ \E ok \in WriteOutcomes : + /\ SupersedeWrite(mine[c], bodyGen[c], ok) + /\ pc' = [pc EXCEPT ![c] = IF ok THEN "gLeases" ELSE "relFail"] + /\ after' = [after EXCEPT ![c] = "relFail"] + /\ UNCHANGED <> + +----------------------------------------------------------------------------- +\* Failures and the environment + +\* A death (or a checked call's failure, which exits the same way through +\* wit_run_gh, common.sh:164-170) runs the trap armed at that point: claim's +\* rollback (claim.sh:85-88) or abort (:137-141). A death inside the +\* hand-back equals its remaining best-effort writes failing. +Die(c) == + /\ MayDie /\ Alive(c) + /\ \/ /\ ctx[c] = "claim" /\ pc[c] \in ClaimRollback + /\ pc' = [pc EXCEPT ![c] = "gLeases"] + \/ /\ ctx[c] = "claim" /\ pc[c] \in ClaimAbort + /\ pc' = [pc EXCEPT ![c] = "tSup"] + \/ /\ pc[c] \in Guarded + /\ pc' = [pc EXCEPT ![c] = CASE after[c] = "lost" -> "dead" + [] after[c] = "renLost" -> "renLost" + [] after[c] \in {"released", "relFail"} -> "relDead" + [] OTHER -> "failed"] + \/ /\ ctx[c] = "renew" /\ pc[c] \in RenewPre + /\ pc' = [pc EXCEPT ![c] = "held"] + \/ /\ ctx[c] = "renew" /\ pc[c] \in RenewPost + /\ pc' = [pc EXCEPT ![c] = + IF RenewDeathKeepsHolding THEN "held" ELSE "renLost"] + \/ /\ ctx[c] = "release" /\ pc[c] \in ReleaseMid + /\ pc' = [pc EXCEPT ![c] = "relDead"] + /\ UNCHANGED <> + +\* The lane's workflow run ends (completed, cancelled or timed out) after its +\* lease is posted, without releasing. +RunCompletes == + /\ mine["lane"] # 0 /\ ~runDone + /\ runDone' = TRUE + /\ pc' = [pc EXCEPT !["lane"] = IF @ \in Final THEN @ ELSE "gone"] + /\ UNCHANGED <> + +\* Time enters the skew margin of lease i's current generation. +Approach(i) == + /\ i \in DOMAIN leases + /\ NeedsNear(i) + /\ ~leases[i].near /\ leases[i].expN <= leases[i].gen + /\ leases' = [leases EXCEPT ![i].near = TRUE] + /\ UNCHANGED <> + +\* Time passes the current generation's expiry. +Expire(i) == + /\ i \in DOMAIN leases + /\ (leases[i].near \/ ~NeedsNear(i)) /\ leases[i].expN <= leases[i].gen + /\ BoundedStall => + LET c == leases[i].by + IN ~(ctx[c] = "renew" /\ ~nearSeen[c] + /\ pc[c] \in {"arbRunRead", "arbRunSup", "renPatch"}) + /\ leases' = [leases EXCEPT ![i].expN = @ + 1] + /\ UNCHANGED <> + +Done == + /\ \A c \in Claimants : pc[c] \in Final \cup {"idle"} + /\ UNCHANGED vars + +Next == + \/ \E c \in Claimants : + \/ Assign(c) \/ CheckRead(c) \/ ReAssign(c) \/ PostLease(c) + \/ ReadLeases(c) \/ ArbJudge(c) \/ ArbRunRead(c) \/ ArbRunSup(c) + \/ LossSup(c) \/ GLeases(c) \/ GList(c) \/ GJudge(c) \/ GARead(c) + \/ GRm(c) \/ GRead2(c) \/ GList2(c) \/ GJudge2(c) \/ GAdd(c) + \/ GRead3(c) \/ GList3(c) \/ GJudge3(c) \/ RelSup(c) + \/ GRm3(c) \/ WinRead(c) \/ WinAdd(c) \/ TrapSup(c) + \/ RenewStart(c) \/ RenewPatch(c) \/ Ren2Leases(c) \/ Ren2Judge(c) + \/ RenSup(c) \/ ReleaseStart(c) \/ RelJudgeOwn(c) \/ RelPatch(c) + \/ Die(c) + \/ RunCompletes + \/ \E i \in 1..3 : Approach(i) \/ Expire(i) + \/ Done + +Spec == Init /\ [][Next]_vars + +\* A claimant between scripts never reads its script-local values again +\* before the next script overwrites them, so states differing only there +\* are one state. +View == < + IF pc[c] \in Final \cup {"idle", "held"} THEN <<>> + ELSE <>]>> + +----------------------------------------------------------------------------- +\* Invariants + +\* The claim returned success, no release returned success, and no renew told +\* the session it lost. +ClaimHeld(c) == pc[c] = "held" + \/ (ctx[c] \in {"renew", "release"} + /\ pc[c] \notin {"released", "gone", "renLost"} + \cup RenewPost \cup Guarded) + +Holding(c) == /\ ClaimHeld(c) + /\ mine[c] # 0 + /\ LiveNow(mine[c]) + /\ (c = "lane" => ~runDone) + +\* A claim, renew or release has started and not yet returned. +InFlight(c) == pc[c] \notin Final \cup {"idle"} + +Quiescent == \A c \in Claimants : pc[c] \in Final \cup {"idle", "held"} +AllFinished == \A c \in Claimants : pc[c] \in Final \cup {"idle"} + +TypeOK == + /\ pc \in [Claimants -> Pcs] + /\ ctx \in [Claimants -> {"claim", "renew", "release"}] + /\ Len(leases) <= 3 + /\ \A i \in DOMAIN leases : leases[i] \in LeaseRec + /\ assignees \subseteq Logins + /\ runDone \in BOOLEAN + /\ triageLogin \in {"human", "other"} + /\ mine \in [Claimants -> 0..3] + /\ \A c \in Claimants : /\ Len(snap[c]) <= 3 + /\ \A i \in DOMAIN snap[c] : snap[c][i] \in SnapRec + /\ live \in [Claimants -> SUBSET (1..3)] + /\ cand \in [Claimants -> 0..3] + /\ win \in [Claimants -> 0..3] + /\ bodyGen \in [Claimants -> 0..1] + /\ renewed \in [Claimants -> BOOLEAN] + /\ nearSeen \in [Claimants -> BOOLEAN] + /\ after \in [Claimants -> {"failed", "lost", "renLost", "released", "relFail"}] + /\ backedOffDone \in [Claimants -> BOOLEAN] + +\* CONTRACT.md "Lease protocol" step 4: "If an earlier live lease exists that +\* is not our own comment, the foreign lease wins"; claim.sh:156 "Earliest +\* LIVE lease wins." +OneHolder == Cardinality({c \in Claimants : Holding(c)}) <= 1 + +\* CONTRACT.md: "Lease-only (`--lease-only`): the claim posts the lease +\* comment and assigns no one." +LaneAssignsNoOne == "bot" \notin assignees + +\* CONTRACT.md: "Claim = assignee (authenticated human user) + lease record." +\* Quiescent states only: the hand-back removes and restores a same-login +\* holder's assignee two calls apart. +HolderAssigned == + Quiescent => + \A c \in DefaultClaims : + (pc[c] = "held" /\ Holding(c)) => LoginOf(c) \in assignees + +\* claim.sh:78-79: "any failure before a successful lease-comment write +\* (step 3) would otherwise strand the issue assigned with no lease record". +\* Every assigned login belongs to a default claimant whose claim, renew or +\* release is still in flight, or that holds the item. +NoStrandedAssignee == + \A l \in assignees : \E c \in DefaultClaims : LoginOf(c) = l /\ InFlight(c) + +\* CONTRACT.md step 4: "the foreign lease wins → supersede own comment, exit +\* `7`." The supersede is best-effort, so the rule assumes writes succeed. +LoserSupersedesOwn == + ~WritesMayFail => + \A c \in Claimants : + (pc[c] \in {"lost", "failed", "dead"} /\ mine[c] # 0) + => leases[mine[c]].sup + +\* CONTRACT.md step 4: "A run whose `status` is `completed`, whatever its +\* conclusion, holds nothing". +CompletedRunHoldsNothing == \A c \in Claimants : ~backedOffDone[c] + +\* CONTRACT.md, Release: "a session that has finished with an item hands it +\* back at once instead of blocking every later claim". +ReleaseFreesItem == + \A c \in Claimants : pc[c] = "released" => ~LiveNow(mine[c]) + +\* With every claimant finished and no lease live, any assignee left is the +\* holder of the active lease, which reclaim unassigns. claim.sh:80: +\* "reclaim ignores items with no lease". +EndStateReclaimable == + (AllFinished /\ \A i \in DOMAIN leases : ~LiveNow(i)) => + \A l \in assignees : ActiveNow # 0 /\ leases[ActiveNow].holder = l + +============================================================================= diff --git a/.claude/skills/formal-claim-protocol/model/LocalLane.cfg b/.claude/skills/formal-claim-protocol/model/LocalLane.cfg new file mode 100644 index 00000000000..7783eb4686c --- /dev/null +++ b/.claude/skills/formal-claim-protocol/model/LocalLane.cfg @@ -0,0 +1,20 @@ +SPECIFICATION Spec +CONSTANTS + Starters = {"local", "lane"} + WithRenew = TRUE + WritesMayFail = FALSE + ReadsMayFail = FALSE + MayDie = FALSE + BoundedStall = TRUE + RenewDeathKeepsHolding = FALSE +VIEW View +INVARIANT TypeOK +INVARIANT OneHolder +INVARIANT LaneAssignsNoOne +INVARIANT HolderAssigned +INVARIANT NoStrandedAssignee +INVARIANT LoserSupersedesOwn +INVARIANT CompletedRunHoldsNothing +INVARIANT ReleaseFreesItem +INVARIANT EndStateReclaimable +CHECK_DEADLOCK TRUE diff --git a/.claude/skills/formal-claim-protocol/model/LocalTriage.cfg b/.claude/skills/formal-claim-protocol/model/LocalTriage.cfg new file mode 100644 index 00000000000..6726931c43f --- /dev/null +++ b/.claude/skills/formal-claim-protocol/model/LocalTriage.cfg @@ -0,0 +1,20 @@ +SPECIFICATION Spec +CONSTANTS + Starters = {"local", "triage"} + WithRenew = TRUE + WritesMayFail = FALSE + ReadsMayFail = FALSE + MayDie = FALSE + BoundedStall = TRUE + RenewDeathKeepsHolding = FALSE +VIEW View +INVARIANT TypeOK +INVARIANT OneHolder +INVARIANT LaneAssignsNoOne +INVARIANT HolderAssigned +INVARIANT NoStrandedAssignee +INVARIANT LoserSupersedesOwn +INVARIANT CompletedRunHoldsNothing +INVARIANT ReleaseFreesItem +INVARIANT EndStateReclaimable +CHECK_DEADLOCK TRUE diff --git a/.claude/skills/formal-claim-protocol/model/view.mjs b/.claude/skills/formal-claim-protocol/model/view.mjs new file mode 100644 index 00000000000..afb9e7c0d7a --- /dev/null +++ b/.claude/skills/formal-claim-protocol/model/view.mjs @@ -0,0 +1,116 @@ +const fixed = { + idle: "Not started", + assigned: "Assigning itself", + reAssign: "Assigning itself", + checked2: "Assigning itself", + checked: "Assigned, no one else", + posted: "Lease posted", + lossSup: "Lost, backing off", + winRead: "Won, checking its assignee", + winAdd: "Won, checking its assignee", + held: "Holds the item", + tSup: "Failed, backing off", + gLeases: "Handing back its assignee", + gList: "Handing back its assignee", + gJudge: "Handing back its assignee", + gARead: "Handing back its assignee", + gRm: "Handing back its assignee", + gRead2: "Handing back its assignee", + gList2: "Handing back its assignee", + gJudge2: "Handing back its assignee", + gAdd: "Handing back its assignee", + gRead3: "Handing back its assignee", + gList3: "Handing back its assignee", + gJudge3: "Handing back its assignee", + gRm3: "Handing back its assignee", + renLeases: "Renewing", + renPatch: "Renewing", + ren2Leases: "Renewed near expiry, re-checking", + ren2Judge: "Renewed near expiry, re-checking", + renSup: "Renew backing off", + relLeases: "Releasing", + relJudgeOwn: "Releasing", + relPatch: "Releasing", + relSup: "Release outranked, backing off", + lost: "Backed off", + failed: "Claim failed", + dead: "Died backing off", + released: "Released", + relFail: "Release refused or failed", + relDead: "Died releasing", + gone: "Run ended", + renLost: "Lost the item on renew", +}; + +const judging = { claim: "Lease posted", renew: "Renewing", release: "Releasing" }; + +const word = (v, c) => { + const pc = v.pc[c]; + if (pc === "arbJudge" || pc === "arbRunRead" || pc === "arbRunSup") return judging[v.ctx[c]]; + return fixed[pc]; +}; + +export const title = "One issue claimed by a local session, the issue lane and triage"; + +export const state = (v) => ({ + "Local session": word(v, "local"), + "Issue lane": word(v, "lane"), + Triage: word(v, "triage"), +}); + +const who = { local: "the local session", lane: "the issue lane", triage: "triage" }; + +const steps = { + Assign: "assigns itself", + CheckRead: "reads the assignees", + ReAssign: "assigns itself again", + PostLease: "posts its lease", + ReadLeases: "lists the leases", + ArbJudge: "picks the earliest live lease", + ArbRunRead: "reads the lane run's status", + ArbRunSup: "supersedes the completed run's lease", + LossSup: "supersedes its own lease", + GLeases: "reads its clock", + GList: "lists the leases", + GJudge: "looks for another live lease of its login", + GARead: "reads the assignees", + GRm: "removes its assignee", + GRead2: "reads its clock", + GList2: "lists the leases", + GJudge2: "looks for another live lease of its login", + GAdd: "assigns itself again", + GRead3: "reads its clock", + GList3: "lists the leases", + GJudge3: "looks for another live lease of its login", + GRm3: "removes its assignee", + WinRead: "reads the assignees", + WinAdd: "assigns itself again", + TrapSup: "supersedes its own lease", + RenewStart: "starts a renew", + RenewPatch: "renews its lease", + Ren2Leases: "lists the leases", + Ren2Judge: "looks for a newer live lease", + RenSup: "supersedes its renewed lease", + ReleaseStart: "starts a release", + RelJudgeOwn: "judges its own lease", + RelPatch: "supersedes its lease", + RelSup: "supersedes its outranked lease", + Die: "dies, or a call fails", +}; + +const world = { + RunCompletes: "the lane's run ends", + Approach: "a lease comes within 300 s of expiry", + Expire: "a lease expires", + Done: null, +}; + +const actor = (from, to) => + Object.keys(who).find((c) => from.pc[c] !== to.pc[c] || from.ctx[c] !== to.ctx[c]); + +export const step = (action, from, to) => { + if (action in world) return world[action]; + const c = actor(from, to); + const what = steps[action] ?? action; + return c ? `${who[c]} ${what}` : what; +}; diff --git a/.claude/skills/formal-claim-protocol/sync.yaml b/.claude/skills/formal-claim-protocol/sync.yaml new file mode 100644 index 00000000000..7540dfe1b60 --- /dev/null +++ b/.claude/skills/formal-claim-protocol/sync.yaml @@ -0,0 +1,30 @@ +checks: + - id: claim-local-lane + covers: + - plugins/work-items/tools/work-item-tracker/CONTRACT.md + - plugins/work-items/tools/work-item-tracker/adapters/github/claim.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/release.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/renew-lease.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/common.sh + - plugins/work-items/tools/work-item-tracker/lib/lease.sh + commit: a548b3aaab8ca0923b387b7f020f4b5af1c59e99 + command: /formal-verification:chart .claude/skills/formal-claim-protocol/model/ClaimProtocol.tla --config .claude/skills/formal-claim-protocol/model/LocalLane.cfg --view .claude/skills/formal-claim-protocol/model/view.mjs --rerun-states 2000000 + seeded_break: + change: claim step 4 (lib/lease.sh wit_lease_winner) takes the latest live lease as the winner instead of the earliest; OneHolder breaks after 1,415 distinct states + caught: true + commit: a548b3aaab8ca0923b387b7f020f4b5af1c59e99 + - id: claim-local-triage + covers: + - plugins/work-items/tools/work-item-tracker/CONTRACT.md + - plugins/work-items/tools/work-item-tracker/adapters/github/claim.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/release.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/renew-lease.sh + - plugins/work-items/tools/work-item-tracker/adapters/github/common.sh + - plugins/work-items/tools/work-item-tracker/lib/lease.sh + commit: a548b3aaab8ca0923b387b7f020f4b5af1c59e99 + command: /formal-verification:chart .claude/skills/formal-claim-protocol/model/ClaimProtocol.tla --config .claude/skills/formal-claim-protocol/model/LocalTriage.cfg --view .claude/skills/formal-claim-protocol/model/view.mjs --rerun-states 2000000 + seeded_break: + change: claim step 4 (lib/lease.sh wit_lease_winner) takes the latest live lease as the winner instead of the earliest; OneHolder breaks after 1,888 distinct states + caught: true + commit: a548b3aaab8ca0923b387b7f020f4b5af1c59e99 +outside_model: [] diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml index 4c17369195b..0f2a3b9d63b 100644 --- a/.github/workflows/pr-require-checks.yml +++ b/.github/workflows/pr-require-checks.yml @@ -1826,7 +1826,9 @@ jobs: # The Node.js release keyring: binary, a byte-exact upstream copy. # The review revert cases' fixtures: byte copies of this repository's # history. - exclude: (^|/)\.github/actions/setup-pinned-node/pubring\.kbx$|(^|/)plugins/review/evals/revert-[^/]+/fixtures/ + # The chart corpus graph files: TLC writes them with no final newline + # and the corpus tests compare them byte for byte. + exclude: (^|/)\.github/actions/setup-pinned-node/pubring\.kbx$|(^|/)plugins/review/evals/revert-[^/]+/fixtures/|(^|/)plugins/formal-verification/skills/chart/scripts/test/corpus/[^/]+/graph\.dot$ # The path-scoped readers gate on the filter group of what they read: # actionlint and the dependabot and workflow schemas on `run_workflows` diff --git a/docs/adr/0093-record-plugin-acceptance-security-reviews.md b/docs/adr/0093-record-plugin-acceptance-security-reviews.md index f738cb105e2..cd970eab2fb 100644 --- a/docs/adr/0093-record-plugin-acceptance-security-reviews.md +++ b/docs/adr/0093-record-plugin-acceptance-security-reviews.md @@ -536,3 +536,71 @@ upstream. **Conditions shipped, and this ACCEPT depends on all of them:** the hu the agent-never-executes instruction, the TTY-only fail-closed library, https-only `open_url`, and the hardened `.env`/gh write path. Removing or weakening any of them re-opens this review, as does any move to have the agent execute a generated wizard. + +### Review record: `formal-verification` (ACCEPT, 2026-11-15) + +Reviewed at `0.0.0`; a version bump adding a new trust surface re-triggers this review. The +`chart` scripts are copied from cursor/plugins `pstack/skills/statechart` at +`ec569379616a4826b98f0f0a205dd3411b573611` (MIT); provenance is `docs/upstream/cursor-pstack.md`. +Four fresh-context reviewers read every line of the copied scripts at `43fba2c9189`, one per +group (core, backends, frontends, passes and tests); their 16 findings are below. + +- **Code execution (1).** No hooks, no `bin/`. `/formal-verification:chart` runs the copied + TypeScript, which runs TLC (Java) on the spec, and runs the consumer's view file as JavaScript in a + worker. The command stages only regular `.tla` files into a fresh folder, refuses `.class` and + `.jar` files beside the spec, standard-module shadowing, generated names, and EXTENDS or INSTANCE + of modules outside the `allowed_modules` setting (such as Json, which reads and writes files), + all before any JVM starts. TLC and the worker get an environment allowlist (PATH, LANG, LC_ALL, + a temp HOME and TMPDIR, and the `STATECHART_*` variables only the test harness reads), a heap cap, + a timeout and an output cap. `/formal-verification:setup` is `disable-model-invocation: true`. +- **MCP servers (2).** None. +- **Consumer config (3).** Three `userConfig` file paths (`model_checker_jar`, `java`, + `script_runtime`), none sensitive. Version pins, bounds and limits are keys in the consumer's + `docs/conventions/formal-verification.yaml`; a convention file that sets a download URL or a + checksum is refused, and versions and package names are pattern-checked. +- **Cache isolation (4).** Installs land only under `${CLAUDE_PLUGIN_DATA}`, each target asserted + inside it. The chart writes only to a new or empty `--out` folder and refuses one reached through + a symbolic link. +- **Data egress (5).** Only `setup apply install-model-checker` and `apply install-renderer`, + typed by the user, fetch the URLs in the shipped `releases.json` (the TLC jar from the tlaplus + GitHub release, Pele from the npm registry), over https with a size cap and a timeout, kept only + on a SHA-256 or integrity match. An unattended run installs nothing and reports + `blocked: toolchain missing`. No telemetry; the chart makes no network call. +- **Provenance & third-party trust (6).** First-party plugin over an MIT upstream whose copied + scripts diverge as ours and are re-taken only through the pstack record's drift re-audit. The + third-party binaries are pinned by checksum. +- **Main-thread / PATH (7).** None; no `settings.json` `agent`, no `bin/`. + +**Review history.** Each finding was fixed on the pull request branch: + +| # | Finding | Commit | +|---|---|---| +| 1 | TLC loaded Java from the spec folder | `146c03d13c2` | +| 2 | Whole environment forwarded to the JVM and the worker | `146c03d13c2` | +| 3 | No timeout, heap or output cap; unbounded collection; open descriptors | `146c03d13c2`, `d6a259c21af` | +| 4 | Modules that touch the machine | `146c03d13c2` | +| 5 | View file runs as JavaScript | `93f6a07ac30` | +| 6 | Repository could set the download URL and checksums; path traversal | `d6a259c21af` | +| 7 | Output folder through a symlink | `146c03d13c2` | +| 8 | Unescaped spec text and fixed fences in the report | `b369b064acb`, `93f6a07ac30` | +| 9 | Test could SIGKILL pid 0 | `d851e211f22` | +| 10 | Interval expansion | `146c03d13c2` | +| 11 | Default labels containing `undefined`/`NaN` refused | `86427e41b1c` | +| 12 | Region condition dropped after a bracketed label | `86427e41b1c` | +| 13 | Spec extension and list separator | `146c03d13c2` | +| 14 | Legend classes undefined; quadratic colon scan | `b369b064acb` | +| 15 | Generated module and operator name collisions | `146c03d13c2` | +| 16 | Fixture rewrite in the test run; temp folders; fast-check; lockfile | `db59e0fff71` | + +**Residual: specs from untrusted pull requests.** A view file is JavaScript the command runs, and +TLC is a large Java program run on the spec, so the controls above do not make an attacker-written +spec safe outside a sandbox. Decision (owner, 2026-11-15): this is not a threat in this estate, +whose only actors are the owner, his bots, agents and GitHub Apps, and no sandbox work is done. No +lane or CI job runs the model checker. + +**Verdict: ACCEPT.** Surfaces 2/7 absent; 1 bounded by staging, module refusal, a scrubbed +environment and resource caps; 3 non-sensitive paths with download sources fixed in the plugin; 4 +confined to the plugin data directory and a fresh output folder; 5 two typed, checksummed +downloads; 6 an MIT upstream taken at a pin. **Recheck trigger:** a lane or CI job that runs the +model checker, a new actor class that can open pull requests here, or a release that adds a +download source. diff --git a/docs/catalog.md b/docs/catalog.md index 2f95294de36..64fef323905 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -48,6 +48,7 @@ plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabu - [`playwright`](../plugins/playwright): Live E2E browser automation via Microsoft's @playwright/cli: named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context, plus produced pull-request demo videos with frame-measured quality control, a vendored upstream baseline and maintainer drift-check update flow. - [`app-control`](../plugins/app-control): Runs the project's app and records evidence without judging it. /app-control:drive finds the project's control skill (or falls back to the bundled run skill or a project-type recipe), reports what is reachable, captures one artifact, stops only what it started, and writes report.md and report.json. /app-control:map writes and maintains that control skill: discovery first, questions only for what is left, and a driver CLI that enforces the safety floors. +- [`formal-verification`](../plugins/formal-verification): Formal verification for the part of a codebase where a bug costs most. /formal-verification:chart model-checks a TLA+ spec with TLC and draws its states as a Mermaid chart, with the shortest path to each broken rule for a person to judge. /formal-verification:setup checks the toolchain and installs the pinned, checksummed model checker only on a typed yes. A consumer's formal- skill follows reference/formal-skill.md. - [`tdd`](../plugins/tdd): A TDD knowledge base distilled from cover-to-cover readings of Kent Beck's Test-Driven Development: By Example and Vladimir Khorikov's Unit Testing: Principles, Practices, and Patterns. Fourteen author-attributed reference files behind a routing table, plus a no-load quick decision guide, answer the WHY behind test design decisions. - [`evals`](../plugins/evals): LLM evaluation methodology and eval-suite design, based on Anthropic's evaluation guidance. /evals:methodology answers questions on success criteria, eval design, and grading. /evals:design interviews for measurable success criteria and scaffolds a graded eval suite for an LLM app or Claude Code skill. /evals:plugin-eval preflights the CLI and target, prices a suite before running, and reads the with-versus-without delta. /evals:validate checks case files with no model call. - [`testing`](../plugins/testing): Test-stage discipline: /testing:plan (coverage gaps, test plans), /testing:write (TDD authoring), /testing:run-e2e (live E2E and smoke checks), /testing:diagnose (failing-test root cause, with a fix-until-green workflow across files), /testing:audit (can't-fail test audit with a fail-closed gate), /testing:cleanup (rewrite, quarantine, or delete low-value tests behind a mutation gate), /testing:setup, and an opt-in hook that flags edits that weaken tests. diff --git a/docs/skill-cheat-sheet.md b/docs/skill-cheat-sheet.md index 3b7f67d8a2d..0e8e5d56e64 100644 --- a/docs/skill-cheat-sheet.md +++ b/docs/skill-cheat-sheet.md @@ -213,6 +213,7 @@ From the stage definitions: A conditional stage runs only when its trigger holds | Skill | Plugin | What it does | Actions | Arguments | Upstream | Next | | --- | --- | --- | --- | --- | --- | --- | +| [`/formal-verification:chart`](../plugins/formal-verification/skills/chart/SKILL.md) | `formal-verification` | Check a TLA+ spec with TLC, chart its states, path each broken rule | | ` [--view FILE] [--out DIR] [--chart-states N] [--rerun-states N] [--image…]` | [pstack `statechart`](upstream/cursor-pstack.md#attribution-table) | `/bugs:write`, `/verification:confirm` | | [`/performance:protect`](../plugins/performance/skills/protect/SKILL.md) | `performance` | Hold a verified counter win with a CI ceiling a human merges | | `[]` | | `/toolchain:ratchet`, `/source-control:pull-request` | | [`/performance:snapshot`](../plugins/performance/skills/snapshot/SKILL.md) | `performance` | Capture a snapshot only from a host proven measurable | `baseline`, `post` | `[baseline\|post] []` | [pstack `hillclimb`](upstream/cursor-pstack.md#attribution-table) | `/implementation:implement`, `/performance:snapshot`, `/performance:climb`, `/performance:verify` | | [`/performance:verify`](../plugins/performance/skills/verify/SKILL.md) | `performance` | Re-derive the result in fresh context and report it honestly | | `[]` | [pstack `principle-explain-the-number`](upstream/cursor-pstack.md#attribution-table), [pstack `benchmark-checklist`](upstream/cursor-pstack.md#attribution-table) | `/performance:protect`, `/source-control:pull-request`, `/performance:target`, `/debugging:debug` | diff --git a/docs/upstream/cursor-pstack.md b/docs/upstream/cursor-pstack.md index 876e54fe09a..58041306eb9 100644 --- a/docs/upstream/cursor-pstack.md +++ b/docs/upstream/cursor-pstack.md @@ -23,10 +23,10 @@ and deleted all its reference files, cut `how` to one subagent and deleted both every other skill's call to `how` with an inline trace, changed the default models and the `setup-pstack` migration of old defaults, reworded `sharpen`'s last sentence, and fixed `statechart`'s Mermaid renderer with new tests. Each row that commit touched says what was re-checked -at `bf0c7cd80a`. The `statechart` and `benny` changes touch no row; `benny` only drops `how` from -its dependency list, and `statechart`'s renderer and tests were listed, not read, because its -adoption ([#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648)) reads the -skill at its then-current head. A row whose latest stamp is older covers paths that did not change +at `bf0c7cd80a`. The `benny` change touches no row: it only drops `how` from its dependency list. +`statechart`'s renderer fix and tests are not in our copy, which +[#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648) took at +`ec56937961`; its row says so. A row whose latest stamp is older covers paths that did not change since that stamp's commit, so that check stands at this pin. **Recheck trigger:** a change, between the pinned commit and upstream HEAD, to a path a row we took @@ -35,10 +35,12 @@ rows. Row links point at whole skill directories where a verdict rests on more t the trigger reaches `references/`, playbooks and `scripts/`. `scripts/check-upstream-drift.sh` computes the changed paths. -**Adaptation posture.** Every entry is a reauthor, not a fork and not a vendored copy. We keep the -substance where it earns its place, fit it to this marketplace's conventions, and write the prose -ourselves. The `playbooks` plugin's boris pack is the deliberate contrast: it keeps an upstream copy -so drift can be detected against it. +**Adaptation posture.** Every entry is a reauthor, not a fork and not a vendored copy, except the +three formal-verification rows marked `Adopted (copied)`: there the owner decided to keep as much of +her text and scripts as possible, so they are copied once and then diverge as ours. Elsewhere we +keep the substance where it earns its place, fit it to this marketplace's conventions, and write +the prose ourselves. The `playbooks` plugin's boris pack is the deliberate contrast: it keeps an +upstream copy so drift can be detected against it. Upstream targets Cursor, so three kinds of machinery are dropped from every row without a note: hard-coded model identifiers and model-role tables, Cursor's MCP discovery, and Cursor transcript @@ -92,7 +94,7 @@ is adopted by this record. | [`how`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/how), [`investigation`](https://github.com/cursor/plugins/blob/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/poteto-mode/playbooks/investigation.md) | [`discovery:explore`](../../plugins/discovery/skills/explore/SKILL.md) and its [`explore_output` setting](../../plugins/discovery/reference/config.md) | Options | No `how` skill. Taken: `explore_output` in `discovery` (`auto` by default, `change-prep`, `explain`) chooses the shape of the final reply, and `explain` walks through how the scope works with a `path:line` cite at each step (`plugins/discovery/reference/config.md:34`). Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds. Upstream renumbered its steps and cut the explorer prompt's step list; the walkthrough output we took does not depend on the cut text, and `investigation` is unchanged. Re-checked at 88d47514b8: holds; the only change to `how` is the subagent model-rule line, and `investigation` is unchanged. Re-checked at bf0c7cd80a: changed. `how` lost its simple-or-complex split, its parallel explorers and both prompt files: one read-only subagent now explores and explains in a single pass from a one-paragraph brief, and its named output sections are gone. `investigation` traces the code inline and keeps the Overview to Gotchas sections. Already have: `discovery:explore` runs in one fresh-context subagent, and the `explore_output` walkthrough we took does not depend on the removed text. | none | | [`interrogate`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/interrogate) | [`review:fanout`](../../plugins/review/skills/fanout/SKILL.md), [`review:code-reviewer`](../../plugins/review/agents/code-reviewer.md), `review:quality-gate` with [`code-metrics:audit size`](../../plugins/code-metrics/skills/audit/actions/size.md) | Partial | Landed in `review:fanout`: a short intent paragraph the orchestrator writes in its own words and passes, labeled as the author's claim, to every surface it dispatches, as a description to test and never evidence (`plugins/review/skills/fanout/SKILL.md:95-99`), and a `## Dismissed` report section listing each demotion with its reason (`:145-149`). Landed in `review:code-reviewer`: the reviewer rubric's repeat-run and dual-path item, flagging an old and a new path for one behavior both left callable with nothing saying which callers use which (`plugins/review/agents/code-reviewer.md:71`). Review's `fanout_diversity` setting, values `lens` (default, one reviewer agent per concern) and `model` (one review prompt per distinct fan-out model tier) (`plugins/review/skills/fanout/SKILL.md:64-76`, `plugins/review/workflows/fanout-sweep.js:32`, `plugins/review/reference/config.md:13`, `plugins/review/.claude-plugin/plugin.json:37`). The same rubric line holds the second rubric item, state-changing code that may run a second time after a retry or a resume (`plugins/review/agents/code-reviewer.md:71`), and the large-file flag is the reviewer's size-crossing note: an advisory finding for a file that went from below the consumer's `size.file_lines` reference at the base to at or above it at the head, counted through `code-metrics:audit size` (`plugins/review/agents/code-reviewer.md`, "Before reviewing" step 1, "Size crossings"). Re-checked at 23e4138: holds; unchanged at `e43c7ee26e`. Re-checked at 118e73b0e1: holds. Upstream shortened its scope, intent and synthesis steps and cut its default reviewers from three models to two; the intent paragraph, the Dismissed bucket, the agreement section and the rubric's idempotency item remain. Re-checked at 88d47514b8 ([cursor/plugins#634](https://github.com/cursor/plugins/pull/634)): changed: the lead-judgment reference lost its opening, which said why the lead filters rather than aggregates, and its Verdict Calibration section, which capped the Act On list at about five items and called the Dismissed list a trust mechanism; `SKILL.md` gained the subagent model-rule line and a family fallback for `cursor-grok-*` and `composer-*` slugs. The Dismissed section stays in the skill's report shape, so our `## Dismissed` take stands and its reason is now ours alone; we never took the five-item cap. Re-checked at ae5650febf: changed. The skill was rewritten: adversaries on the configured models must prove each finding with a run, the lead's four buckets are gone, and all four reference files were deleted. Our intent paragraph still matches its framing step. `## Dismissed` (`plugins/review/skills/fanout/SKILL.md:145`) is now ours alone beside upstream's per-adversary dropped count; so are the repeat-run and dual-path rubric item (`plugins/review/agents/code-reviewer.md:71`) and the size-crossing note ("Size crossings"). `fanout_diversity` stands as a setting. New candidate, not taken: keeping only findings a rerun proves; owner to decide in `review`. Decided 2026-11-12: taken, reshaped. A plain filter would break the fan-out's recall contract and its rule that it runs no builds or tests (`plugins/review/skills/fanout/SKILL.md:93-97`, `:200`). Instead, the rule for running reviewed code moves out of `/bugs:scan`'s verification gate into one contract both cite, and a setting on the fan-out's normalization step labels or requires run-proven findings (off by default), with unproven findings still listed as dismissed (pending adoption: `review:fanout`, [#15833](https://github.com/melodic-software/claude-code-plugins/issues/15833), after its interview). | none | | [`no-comments`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/no-comments), [`comment-sicko`](https://github.com/cursor/plugins/blob/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/agents/comment-sicko.md) | [`code-tidying:remove-comments`](../../plugins/code-tidying/skills/remove-comments/SKILL.md), [`code-metrics:audit-suppressions`](../../plugins/code-metrics/skills/audit-suppressions/SKILL.md) | Partial | Taken: `code-tidying:remove-comments` keeps a suppression's justification beside its waiver ([`dissolve-comments/SKILL.md:102`](https://github.com/melodic-software/claude-code-plugins/blob/4a3213c937a770e9bb6ce882d7d2e62a2f4ce7b4/plugins/code-tidying/skills/dissolve-comments/SKILL.md#L102), the file the line cites in this row refer to) and proposes a regression test or a lint rule for a comment that states a constraint the code could enforce (`:168-172`); the run's mode settles a doubtful comment, kept under the cautious modes and kept under `aggressive` and `strip` only when it is a listed survivor kind (`:130-139`); and `code-metrics:audit-suppressions` is the suppression inventory. Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; the agent's id is now `comment-sicko`, and `no-comments` spawns it by that id. Re-checked at 88d47514b8: holds; the only change to `no-comments` is the subagent model-rule line, and `comment-sicko` is unchanged. Decided 2026-11-12: fixing the flagged code inside the same run is declined; comment removal stays comment-only. Taken instead is the hand-off: `code-tidying:remove-comments` writes its reshape flags and root-cause rows to a findings file in every mode, so `/review:fanout fix`, `/implementation:implement` or `/architecture:improve` can act on them (pending adoption: `code-tidying:remove-comments`, [#15841](https://github.com/melodic-software/claude-code-plugins/issues/15841)). Decided 2026-11-14: her policy is the shipped default posture, `necessary`. Our floor differs from `comment-sicko` in three places: a suppression of a correctness rule is kept and listed as root-cause work, a `TODO(#issue)` marker is kept, and a comment paired with a regression test is kept. New comments are stopped by a lint on the lines a change adds (`comment_lint` in `code-tidying`, off by default) and by the review rule, not by a comment count. Re-checked at bf0c7cd80a: holds; `no-comments` and `comment-sicko` now trace a thin `IMPORTANT` or `do not remove` symbol inline instead of running `/how` (`/why` stays). Our posture and floor are unchanged. | none | -| [`setup-pstack`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/setup-pstack) | `multi-agent:route` | Partial | We keep alias tiers and per-plugin configuration; an effort budget lives in multi-agent configuration. Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; upstream changed its budget labels and model defaults, which we do not take. Re-checked at 88d47514b8: holds; a new last step offers once to generate a formal verification skill through `create-formal-verification-skill`, which is not adopted (see [below](#sharpen-and-the-formal-verification-pair-not-now)); the alias tiers and per-plugin configuration we keep are unchanged. Re-checked at ae5650febf: holds; one sentence on how the judge pool is ordered, model-role machinery we drop. Re-checked at bf0c7cd80a: holds. New defaults, budget steps measured from each role's default, retired `how` and `why` role lines, and a `# defaults: 2` marker so a rerun replaces old defaults a full-file rule had pinned while keeping the user's choices. Already have: `/multi-agent:setup apply` writes only the keys the user asks to change and keeps the rest (`plugins/multi-agent/skills/setup/SKILL.md:60-62`), so a bundled default never goes stale in a consumer layer. | none | +| [`setup-pstack`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/setup-pstack) | `multi-agent:route` | Partial | We keep alias tiers and per-plugin configuration; an effort budget lives in multi-agent configuration. Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; upstream changed its budget labels and model defaults, which we do not take. Re-checked at 88d47514b8: holds; a new last step offers once to generate a formal verification skill through `create-formal-verification-skill`, adopted since by the `formal-verification` plugin (see its row), with no setup-time offer; the alias tiers and per-plugin configuration we keep are unchanged. Re-checked at ae5650febf: holds; one sentence on how the judge pool is ordered, model-role machinery we drop. Re-checked at bf0c7cd80a: holds. New defaults, budget steps measured from each role's default, retired `how` and `why` role lines, and a `# defaults: 2` marker so a rerun replaces old defaults a full-file rule had pinned while keeping the user's choices. Already have: `/multi-agent:setup apply` writes only the keys the user asks to change and keeps the rest (`plugins/multi-agent/skills/setup/SKILL.md:60-62`), so a bundled default never goes stale in a consumer layer. | none | | [`principle-attack-the-premise`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-attack-the-premise), [`principle-fix-root-causes`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-fix-root-causes) | [`debugging:debug`](../../plugins/debugging/skills/debug/SKILL.md), [`code-tidying:remove-comments audit`](../../plugins/code-tidying/skills/remove-comments/actions/audit.md) | Partial | Taken in `debugging:debug`: after a second failed fix, reduce what the failed fixes share to one claim a test can check, running the per-actor tally first when the symptom is uneven (`plugins/debugging/skills/debug/SKILL.md:383`); a failure that began after a restart with no code change ranks what the old process left on disk first in the hypothesis table (`:200`); and a shipped workaround needs a tracking link or a removal condition in its comment, which `code-tidying:remove-comments audit` reports as `unjustified-workaround` when both are missing (`:369`). Re-checked at 23e4138: holds. Re-checked at 88d47514b8 ([cursor/plugins#633](https://github.com/cursor/plugins/pull/633), landed by `99743e9c15`): changed; both principles are restated as reasoning. `principle-attack-the-premise` dropped its census of which actors hold an imbalance and its rotate-or-randomize remedies; it now asks for one check whose result would differ were the premise wrong, judged from the pattern of where failures fall as well as how big they are. That is the one checkable claim `debugging:debug` already takes (`:383`); running the per-actor tally before that test is now ours alone, kept as one way to read the distribution. `principle-fix-root-causes` now defines the root cause as the earliest point where behavior departs from what was intended, keeps suspecting persisted state after a restart (`:200`) and fixing the code rather than a paragraph-long comment (`:369`), and replaces its flat ban on guards with a test: handling a state is the fix when the system may legitimately be in it, and a guard masks the defect when that state is one the system must never reach. Taken in `debugging:debug` under the principle placement of [#7589](https://github.com/melodic-software/claude-code-plugins/issues/7589): its "Does not fix the symptom" line now states that test. Also taken there: after a deep dig, Phase 6 proposes the cheap always-on signal that would have shown the deciding fact at first look, gated by the `always_on_signal` key of `docs/conventions/debugging.yaml`, and searches for the fixed defect's siblings. Decided 2026-11-12: a hard stop on a doubtful premise is declined; `debugging:debug` keeps the premise check advisory on purpose, with its reproduction loop as the only hard gate (`plugins/debugging/skills/debug/SKILL.md:386`). Taken: the test-fix loop gains the same check, so `/testing:diagnose` runs the premise check after its second failed fix, reaching it by slash reference to `/debugging:debug` with the sentence as fallback (pending adoption: `testing:diagnose`, [#15836](https://github.com/melodic-software/claude-code-plugins/issues/15836)). | none | | [`principle-boundary-discipline`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-boundary-discipline), [`principle-type-system-discipline`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-type-system-discipline), [`principle-model-the-domain`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-model-the-domain) | [`implementation:implement`](../../plugins/implementation/skills/implement/SKILL.md), [`planning:design`'s type-discipline reference](../../plugins/planning/skills/design/reference/type-discipline.md), [`review:code-reviewer`](../../plugins/review/agents/code-reviewer.md), [`architecture:improve`](../../plugins/architecture/skills/improve/research/deepening/scan-briefing.md) | Partial | Taken: `implementation:implement` narrows values where they enter the system and relies on those types afterwards (`plugins/implementation/skills/implement/SKILL.md:52`); `planning:design` loads a type-discipline reference; feature mode builds a structure that names every case before it adds another branch arm, and reports that structure as a follow-up under a `minimal` posture (`plugins/implementation/skills/implement/context/feature.md:12`). The reviewer questions are in `review:code-reviewer`: a side-effect item asking whether I/O, clock, randomness or shared state reached for partway through logic can move to the caller and leave the logic pure (`plugins/review/agents/code-reviewer.md:77`), the cast and debug-output item (`:79`, see the `typescript-best-practices` row), and a second trigger on the Repeated Switches smell, a boolean added only to stay in step with an existing one, with one enum or state value as the remedy (`plugins/review/reference/design-smells.md` "Baseline", Repeated Switches); in `architecture:improve`'s scan briefing, a special-case-in-a-general-module signal (`plugins/architecture/skills/improve/research/deepening/scan-briefing.md:43`). Re-checked at 23e4138: holds; the three paths did not change between `23e4138` and `e43c7ee26e`. Re-checked at 118e73b0e1: holds. `principle-type-system-discipline` folded its tests into its patterns and `principle-model-the-domain` its why paragraph into its opening; `principle-boundary-discipline` is unchanged. Re-checked at 88d47514b8 ([cursor/plugins#634](https://github.com/cursor/plugins/pull/634), at `99743e9c15`): changed in `principle-type-system-discipline` only. It cut five bullets (illegal states unrepresentable, types as constructions, not lying to the type system, exhaustive matching, strengthening a type only where partiality appears) and dropped "refuse to lie to the compiler" from its description, keeping the branding, parse-at-the-boundary and derive-from-schema bullets. The matching rows of our type-discipline reference (sum types for exclusive states, an encoding that cannot hold an invalid value, tightening only where a function would fail, exhaustive branching, no unproven cast: `docs/contracts/type-discipline/README.md:19-23`, generated into `plugins/planning/skills/design/reference/type-discipline.md`) carry their own reasons there, so nothing taken is lost; upstream's `typescript-best-practices` still states the TypeScript forms. `principle-boundary-discipline` and `principle-model-the-domain` are unchanged. Decided 2026-11-12: `principle-type-system-discipline`'s branding rule, for two values that share a primitive, is taken as one language-neutral row in the type-discipline contract, which today states it only in its TypeScript file; the row takes no side on the open `as` versus type-guard question in the `typescript-best-practices` row (pending adoption: `docs/contracts/type-discipline/README.md`, [#15840](https://github.com/melodic-software/claude-code-plugins/issues/15840)). | none | | [`principle-build-the-lever`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/principle-build-the-lever) | [`discipline:script-the-deterministic-work`](../../plugins/discipline/skills/script-the-deterministic-work/SKILL.md) and its [`lever_scope` setting](../../plugins/discipline/reference/config.md), `implementation:implement-dispatch` | Options | Taken: the lever check, which `implementation:implement` runs before a multi-site block and `implementation:implement-dispatch` before a fan-out, has the caller edit the first site by hand, run the lever on a clean copy of that site and diff the two before any other site (`plugins/discipline/skills/script-the-deterministic-work/SKILL.md:175-178`); `lever_scope` (`deterministic` by default, or `non-trivial`) decides which changes get a lever (`plugins/discipline/reference/config.md:44`). Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; upstream dropped its Why, Pattern and Balance labels and kept the text. | none | @@ -117,7 +119,9 @@ is adopted by this record. | [`poteto-help`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/poteto-help) | [`session-flow:recommend-skills`](../../plugins/session-flow/skills/recommend-skills/SKILL.md), [`session-flow:workflow`](../../plugins/session-flow/skills/workflow/SKILL.md) | Partial | New at 118e73b0e1. A typed-only help router: it maps a question about pstack to the skill, playbook or guide page that answers it, hands back a prompt to send rather than starting the work, and asks about `/setup-pstack` when no model rule exists. No decision is recorded. Closest owners: `session-flow:recommend-skills` and `harness-ops:inventory`. Re-checked at 88d47514b8: changed: it routes to the four skills new at `88d47514b8`, mentions the formal-verification pair when a question is about a race or an invariant, and says pstack also installs in Claude Code under a `pstack:` prefix (see the `docs/harness/claude-code.md` row). Still no decision; the closest owners are unchanged. Re-checked at ae5650febf: changed: it routes to `ketchup-video` and `statechart` and rewords the no-merge autopilot prompt. Still no decision; the closest owners are unchanged. Decided 2026-11-12, landed in [#16359](https://github.com/melodic-software/claude-code-plugins/pull/16359): already have; `/session-flow:recommend-skills` answers a free-text question with one skill and an example prompt. The one part taken is the map from a kind of task to its recipe (her `poteto-mode` playbooks): which stages a kind of task enters is the workflow skill's job, so it is one "Task kinds" table in the workflow skill's steps reference, naming no skills (`plugins/session-flow/skills/workflow/context/steps.md:226-242`), which the generated cheat sheet joins with each skill's stage and arguments in its "By kind of task" table (`docs/skill-cheat-sheet.md:43-54`), in place of the hand-kept "Start from your problem" table; the eval case is `plugins/session-flow/evals/wf-bug-takes-task-kinds-stages/`. Re-checked at bf0c7cd80a: holds; one sentence no longer names `/why` among the skills that spawn subagents with per-role models. The task-kind map we took is unchanged. | none | | [`in-your-own-words`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/in-your-own-words) | [`playbooks:fable-5` problem framing](../../plugins/playbooks/skills/fable-5/context/problem-framing.md), `work-items:work` | Partial | New at 88d47514b8. A typed-only skill whose whole body asks the agent to restate, in its own words, the user's goals and the problem they are solving. No decision is recorded. Closest owner: `planning:interview`, whose rounds bring a task to shared understanding before work starts. Decided 2026-11-12, with the `poteto-mode` goal restatement: already owned. `playbooks:fable-5`'s problem-framing chapter restates the outcome, not the request (`plugins/playbooks/skills/fable-5/context/problem-framing.md:7-13`), and `work-items:work` restates an item as "I read this item as" before claiming it. The one gap, naming the smallest change expected, is taken into that restatement, which counts only a change that removes the cause (`plugins/playbooks/skills/fable-5/context/problem-framing.md:11`). | none | | [`sharpen`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/sharpen) | none | Not adopted (deferred; see [below](#sharpen-and-the-formal-verification-pair-not-now)) | New at 88d47514b8. Deferred under [#7566](https://github.com/melodic-software/claude-code-plugins/issues/7566). Re-checked at bf0c7cd80a: changed; the last sentence now has the rewritten prompt ask for a prototype of any choice an experiment can settle and a recommendation from what it showed, leaving only product and preference calls to the user. Reject: the deferral stands, because its reopen trigger, a repeated ask in the owner's sessions, has not fired. | none | -| [`create-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/create-formal-verification-skill), [`maintain-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/maintain-formal-verification-skill) | none yet | Pending adoption (new `formal-verification` plugin) | New at 88d47514b8. A formal-methods skill is parked by [`tlaplus-agentskills.md`](tlaplus-agentskills.md). Re-checked at ae5650febf: holds; a generated skill is now told to read TLA+ results with `statechart`, which is parked with this pair (see [below](#sharpen-and-the-formal-verification-pair-not-now)). Decided 2026-11-12 (map [#15651](https://github.com/melodic-software/claude-code-plugins/issues/15651)): the park is lifted. A new `formal-verification` plugin absorbs her three formal-verification skills, this pair and `statechart`, in three slices, each with its interview, and their pull requests update this row in detail: [the chart skill, setup and consumer contract, proven on the loop-lane claim protocol](https://github.com/melodic-software/claude-code-plugins/issues/15648), [the specify skill's propose, create and check forms](https://github.com/melodic-software/claude-code-plugins/issues/15773), and [the specify skill's refresh action](https://github.com/melodic-software/claude-code-plugins/issues/15775). | none | +| [`statechart`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/statechart) | [`formal-verification:chart`](../../plugins/formal-verification/skills/chart/SKILL.md) | Adopted (copied) | New at ae5650febf. Decided 2026-11-12 (map [#15651](https://github.com/melodic-software/claude-code-plugins/issues/15651)) and adopted at ec56937961 by [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648): her `SKILL.md`, `references/render.md` and every file under `scripts/` (tests and corpus included) are copied, not called, because her skill is `disable-model-invocation: true`. The scripts take the jar, Java and bounds as arguments and no longer install TLC or Java through mise; her pins and bounds became settings with her values as defaults (`plugins/formal-verification/defaults.json`). Her `SKILL.md` text is split between the chart skill and its `reference/` files. Re-checked at bf0c7cd80a: her Mermaid renderer fix and its tests ([cursor/plugins#1236](https://github.com/cursor/plugins/pull/1236)) are not in the copy. The copied scripts diverge as ours: her later changes are re-taken only through this record's drift re-audit. | none | +| [`create-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/create-formal-verification-skill) | [`formal-verification` contract](../../plugins/formal-verification/reference/formal-skill.md) | Adopted (copied) | New at 88d47514b8. Decided 2026-11-12 (map [#15651](https://github.com/melodic-software/claude-code-plugins/issues/15651)): the park recorded by [`tlaplus-agentskills.md`](tlaplus-agentskills.md) is lifted. Adopted at ec56937961: [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648) copies her opening and "What makes it good" text into the `formal-` contract, with her "refer to `/statechart` by name" rule naming `/formal-verification:chart`; the rest becomes the `specify` skill's create action ([#15773](https://github.com/melodic-software/claude-code-plugins/issues/15773)), whose sentence "TLA+ is the default" is replaced (ADR 0101). Copied text diverges as ours and is re-taken only through this record's drift re-audit. | none | +| [`maintain-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/maintain-formal-verification-skill) | [`formal-verification` contract](../../plugins/formal-verification/reference/formal-skill.md) | Adopted (copied) | New at 88d47514b8. Decided 2026-11-12 with the create skill. Adopted at ec56937961: [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648) takes her coverage record and sync commit into the contract's `sync.yaml`; her pass, outcomes and report become the `specify` skill's refresh action ([#15775](https://github.com/melodic-software/claude-code-plugins/issues/15775)). Copied text diverges as ours and is re-taken only through this record's drift re-audit. | none | | [`docs/harness/claude-code.md`](https://github.com/cursor/plugins/blob/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/docs/harness/claude-code.md) | none | Not taken (nothing to reauthor) | New at 88d47514b8. An adapter page that maps pstack's Cursor tool names, subagent fields, model slugs, paths and Cursor-only features to Claude Code, so pstack itself runs there as `/pstack:`. Every entry on this page is a reauthored skill of ours, not a run of an upstream skill, so the mapping applies to none of them. Re-checked at bf0c7cd80a: holds; only the default-model mapping lines changed. | none | **Principle parts check (the `principle-*` rows above).** Decision 58's 36 parts: 28 placed in the @@ -378,15 +382,17 @@ would enforce a guide the project may have rejected. The style question stays wi model of the lane protocol would have caught, or a consumer asking for model checking), and read both upstreams at their then-current HEAD before deciding. Re-checked at ae5650febf: the first now tells a generated skill to read TLA+ results with `statechart`; the parked decision stands. - Decided 2026-11-12: the park is lifted for this pair and `statechart`; see the pair's row for the - three `formal-verification` plugin work items. + Decided 2026-11-12: the park is lifted for this pair and `statechart`. Adopted at ec56937961 by + [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648); see the rows of the + three skills. - **`statechart`** (linked in the [Map](#map)) checks a TLA+ model and draws it as a chart with the shortest path to each state that breaks a rule. It is parked with the pair above, under the same page and trigger, and needs a TLC, Java and renderer install we have no consumer for. Read at ae5650febf: its `SKILL.md`, `references/render.md`, `package.json` and launcher. Its compiler sources, tests and corpus were listed, not read, because the decision rests on what the skill is for. Decided 2026-11-12: it becomes the `formal-verification` plugin's chart skill - ([#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648)). + ([#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648)), adopted at + ec56937961; see its row. ## Method provenance, for the record @@ -414,7 +420,7 @@ automation pack and the Claude Code harness page. A unit with a row above names - [`blast-radius`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/blast-radius): `review:quality-gate` - [`bro`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/bro): nothing taken - [`correct`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/correct): nothing taken (owners named in its row) -- [`create-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/create-formal-verification-skill): pending adoption, the `formal-verification` plugin (see its row) +- [`create-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/create-formal-verification-skill): adopted, the `formal-verification` plugin's `formal-` contract (see its row) - [`create-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/create-verification-skill): `app-control:map create` - [`figure-it-out`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/figure-it-out): `planning:plan`, `implementation:implement`, `implementation:implement-dispatch` - [`how`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/how): `discovery:explore` @@ -422,7 +428,7 @@ automation pack and the Claude Code harness page. A unit with a row above names - [`interrogate`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/interrogate): `review:fanout`, `review:code-reviewer`, `review:quality-gate` - [`ketchup`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/ketchup): `session-flow:orient` catch-up (see its row) - [`ketchup-video`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/ketchup-video): decided 2026-11-12, taken as a one-line offer in `session-flow:orient`'s catch-up, presence-gated like its existing visualize hand-off (pending adoption: [#15834](https://github.com/melodic-software/claude-code-plugins/issues/15834)) -- [`maintain-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/maintain-formal-verification-skill): pending adoption, the `formal-verification` plugin (see its row) +- [`maintain-formal-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/maintain-formal-verification-skill): adopted, the `formal-verification` plugin's `formal-` contract (see its row) - [`maintain-verification-skill`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/maintain-verification-skill): `app-control:map refresh` - [`make-bot-ui`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/make-bot-ui): nothing taken (Cursor runtime only) - [`no-comments`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/no-comments): `code-tidying:remove-comments`, `code-metrics:audit-suppressions` @@ -457,7 +463,7 @@ automation pack and the Claude Code harness page. A unit with a row above names - [`setup-pstack`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/setup-pstack): `multi-agent:route` - [`sharpen`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/sharpen): nothing taken (deferred; see its row) - [`show-me-your-work`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/show-me-your-work): `implementation:implement-dispatch`, `harness-ops:audit-install-state` -- [`statechart`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/statechart): pending adoption, the `formal-verification` plugin's chart skill (see the formal-verification pair's row) +- [`statechart`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/statechart): [`formal-verification:chart`](../../plugins/formal-verification/skills/chart/SKILL.md) (see its row) - [`swarm`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/swarm): `session-flow:orchestrate`, `multi-agent:assess`, `multi-agent:route` - [`tdd`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/tdd): `testing:write`, `debugging:debug` - [`teach`](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/skills/teach): `education:teach`, `education:explain` diff --git a/docs/upstream/tlaplus-agentskills.md b/docs/upstream/tlaplus-agentskills.md index f51b7e3307f..c9f8dd5fd01 100644 --- a/docs/upstream/tlaplus-agentskills.md +++ b/docs/upstream/tlaplus-agentskills.md @@ -6,13 +6,13 @@ licensed. Nothing in this marketplace is derived from it today. This page exists formal verification starts from a known commit instead of a fresh search. **Last audited upstream state:** `tlaplus/AgentSkills@f2adb5e4e2c6250661d1aff8bcc0b9f92d5442ec` (upstream -HEAD of `main` when read; the repository has no tags or releases). Git history of this file records -*when*; this line records only *what was audited*. +HEAD of `main` when re-read for [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648), +unchanged since the first read; the repository has no tags or releases). Git history of this file +records *when*; this line records only *what was audited*. **Recheck trigger:** a change, between the pinned commit and upstream HEAD, to a path a row we took or rejected something from links, a unit removed or added under the scope: re-audit the affected -rows. This page has no rows and no scope, so the drift check lists it as `untracked` and never -reports it as drift. The decision's recheck trigger below says when to re-read it. +rows. The decision's recheck trigger below says when to re-read it. ## What the pinned commit holds @@ -21,23 +21,31 @@ every place that must mention it, one breaks a single action into two steps that one writes a TLA+ spec that models the behavior of existing program code. The upstream README states the instructions are not tied to one agent product. +## Attribution table + +| Upstream (links at the pin) | Ours | Relation | Decision | +|---|---|---|---| +| [`tlaplus-from-source`](https://github.com/tlaplus/AgentSkills/tree/f2adb5e4e2c6250661d1aff8bcc0b9f92d5442ec/skills/tlaplus-from-source) | none | Not adopted | Its four phases (understand the code, choose abstractions, write the spec, propose properties) are the job of the `specify` skill's create action, slices 2 and 3 ([#15773](https://github.com/melodic-software/claude-code-plugins/issues/15773)). `/formal-verification:chart` writes TLA+ only under pstack's "Write the spec" rules and adds none of this skill's guidance. Re-read when `specify` is planned. | +| [`tlaplus-add-variable`](https://github.com/tlaplus/AgentSkills/tree/f2adb5e4e2c6250661d1aff8bcc0b9f92d5442ec/skills/tlaplus-add-variable) | none | Not adopted | An editing recipe for an existing spec. The `formal-` contract's Updating section leaves model edits to the agent following the code; no skill here edits a spec mechanically. | +| [`tlaplus-split-action`](https://github.com/tlaplus/AgentSkills/tree/f2adb5e4e2c6250661d1aff8bcc0b9f92d5442ec/skills/tlaplus-split-action) | none | Not adopted | Same as `tlaplus-add-variable`: an editing recipe with no consumer here. | + ## Decision -- **A `formal-verification` plugin is planned.** On 2026-11-12 the owner reopened the earlier "no - TLA+ skill" decision outside its recheck trigger (map +- **A `formal-verification` plugin ships model checking.** On 2026-11-12 the owner reopened the + earlier "no TLA+ skill" decision outside its recheck trigger (map [#15651](https://github.com/melodic-software/claude-code-plugins/issues/15651)). The plugin is built in three slices: [#15648](https://github.com/melodic-software/claude-code-plugins/issues/15648), [#15773](https://github.com/melodic-software/claude-code-plugins/issues/15773) and - [#15775](https://github.com/melodic-software/claude-code-plugins/issues/15775). Until they land, - no plugin in this marketplace ships model checking or TLA+ authoring. -- **Its source is pstack, not this repository.** The plugin adapts the formal-verification skills + [#15775](https://github.com/melodic-software/claude-code-plugins/issues/15775). The first adds + `/formal-verification:chart`, which checks a TLA+ spec with TLC, `/formal-verification:setup`, + and the `formal-` skill contract. +- **Its source is pstack, not this repository.** The plugin carries the formal-verification skills recorded in [`cursor-pstack.md`](cursor-pstack.md). Nothing wraps or depends on - tlaplus/AgentSkills. -- **No vendored copy.** No file from this upstream is stored here. If a slice takes anything from - it, this page gains attribution rows linking the upstream paths at a new pin. + tlaplus/AgentSkills, and the rows above take nothing from it. +- **No vendored copy.** No file from this upstream is stored here. ## Recheck trigger Re-read the upstream at its then-current HEAD, and move the pin to that commit, when a slice above -writes or changes TLA+ authoring guidance. +writes or changes TLA+ authoring guidance; the `specify` slices are the next. diff --git a/plugins/formal-verification/.claude-plugin/plugin.json b/plugins/formal-verification/.claude-plugin/plugin.json new file mode 100644 index 00000000000..72ef2fcaa25 --- /dev/null +++ b/plugins/formal-verification/.claude-plugin/plugin.json @@ -0,0 +1,39 @@ +{ + "name": "formal-verification", + "description": "Formal verification for the part of a codebase where a bug costs most. /formal-verification:chart model-checks a TLA+ spec with TLC and draws its states as a Mermaid chart, with the shortest path to each broken rule for a person to judge. /formal-verification:setup checks the toolchain and installs the pinned, checksummed model checker only on a typed yes. A consumer's formal- skill follows reference/formal-skill.md.", + "author": { + "name": "Melodic Software", + "email": "info@melodicsoftware.com" + }, + "version": "0.0.0", + "license": "MIT", + "keywords": [ + "formal-verification", + "tla-plus", + "tlc", + "model-checking", + "statechart", + "mermaid", + "skill" + ], + "metadata": { + "category": "testing" + }, + "userConfig": { + "model_checker_jar": { + "type": "file", + "title": "Model checker jar", + "description": "Path to tla2tools.jar, the TLC model checker. Unset uses the jar that setup installs under the plugin data directory." + }, + "java": { + "type": "file", + "title": "Java binary", + "description": "Path to the java binary that runs TLC. Unset uses java on PATH. The plugin never installs Java." + }, + "script_runtime": { + "type": "file", + "title": "Script runtime", + "description": "Path to the Node, Bun or Deno binary that runs the chart scripts. Unset lets the launcher pick the first supported one on PATH." + } + } +} diff --git a/plugins/formal-verification/CHANGELOG.md b/plugins/formal-verification/CHANGELOG.md new file mode 100644 index 00000000000..25082eabf73 --- /dev/null +++ b/plugins/formal-verification/CHANGELOG.md @@ -0,0 +1,4 @@ +# Changelog + +All notable changes to the `formal-verification` plugin are documented here. Format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. diff --git a/plugins/formal-verification/README.md b/plugins/formal-verification/README.md new file mode 100644 index 00000000000..0d2819c95af --- /dev/null +++ b/plugins/formal-verification/README.md @@ -0,0 +1,128 @@ +# formal-verification + +Formal verification for the part of a codebase where a bug costs most and tests reach least. +`/formal-verification:chart` checks a TLA+ model with TLC, draws its states as a Mermaid chart, and +gives the shortest path to each rule that breaks, for a person to judge. A consumer keeps each model +in its own `formal-` skill, shaped by [`reference/formal-skill.md`](reference/formal-skill.md). + +## Install + +```shell +/plugin marketplace add melodic-software/claude-code-plugins +/plugin install formal-verification@melodic-software +``` + +## Skills + +| Skill | What it does | +|---|---| +| `/formal-verification:chart` | Model-checks a TLA+ spec with TLC and writes `chart.mmd` and `report.md`: each rule that holds, each that breaks with its shortest path, and the rules a bound left unchecked. Model-invoked too, so a `formal-` skill's Run can call it. | +| `/formal-verification:setup` | `check` reports the script runtime, Java, the model checker and the renderer; `apply install-model-checker` and `apply install-renderer` download the pinned file into the plugin data directory and keep it only when its checksum matches. Typed only. | + +## Configuration + +Machine paths are plugin options, set through `/plugin configure`: the model checker jar, the Java +binary and the script runtime (the options block below). + +Version pins and default bounds are keys in the consumer's +`docs/conventions/formal-verification.yaml`, checked against +[`schemas/formal-verification.schema.json`](schemas/formal-verification.schema.json). An absent key +takes the shipped value in [`defaults.json`](defaults.json). Download URLs and checksums are not +settings: they live only in [`releases.json`](releases.json), and a version chosen in the +convention file must have an entry there. `scripts/settings.mjs` prints the +resolved values: + +```shell +node /scripts/settings.mjs --project-dir . +``` + +A bound for one model goes in that model's run command (`--chart-states`, `--rerun-states`), in its +`formal-` skill. + +## Prerequisites + +| Tool | Who installs it | +|---|---| +| A script runtime: Node, Bun or Deno (the launcher names the versions it accepts) | You. | +| Java (the `java.min_version` setting) | You. The plugin never installs Java. | +| The TLC model checker, `tla2tools.jar` | `/formal-verification:setup apply install-model-checker`, on your typed request, from the pinned URL and SHA-256. Or point the model checker jar option at your own. | +| The Pele renderer, only for an image of a chart | `/formal-verification:setup apply install-renderer`, from the pinned tarball and integrity string. | + +No script installs anything while a skill runs, and an unattended run that finds the toolchain +missing reports `blocked: toolchain missing` and stops. `prerequisites.json` declares the runtime, +Java, the jar and the renderer for `/harness-ops:prerequisites`; `scripts/toolchain.mjs check` +also checks the jar's pinned SHA-256. + +## Tests + +`node --test scripts/toolchain.test.mjs` covers settings resolution and the toolchain check and +install. The chart scripts carry their own suite under `skills/chart/scripts/test/`. + + + +### Options reference + +Generated from this plugin's `.claude-plugin/plugin.json`. For how Claude Code asks for +these and hands them to the plugin, see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `model_checker_jar` | file | *(none)* | Path to tla2tools.jar, the TLC model checker. Unset uses the jar that setup installs under the plugin data directory. | +| `java` | file | *(none)* | Path to the java binary that runs TLC. Unset uses java on PATH. The plugin never installs Java. | +| `script_runtime` | file | *(none)* | Path to the Node, Bun or Deno binary that runs the chart scripts. Unset lets the launcher pick the first supported one on PATH. | + +### How to set these + +Set the options above for `formal-verification@`, replacing `` with the +marketplace you installed this plugin from: + +- **In a session or headless:** [`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session) or + [`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure). The configure command is the preferred + headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its limits. +- **By hand:** under [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) in your **user** settings. + +Do **not** uninstall the plugin to reconfigure it: see [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps). +For a Claude Code release without `plugin configure`, see [Plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install). + +### Upstream documentation + +- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) +- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) +- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) +- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills) +- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect) +- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins) + + + +## Attribution + +`/formal-verification:chart` carries the `statechart` skill of pstack in +[cursor/plugins](https://github.com/cursor/plugins), its text and its scripts, changed so that the +scripts take the jar, Java and bounds as arguments and install nothing. The record is +[`docs/upstream/cursor-pstack.md`](../../docs/upstream/cursor-pstack.md). Those files are used under +this license: + +```text +MIT License + +Copyright (c) 2026 Lauren Tan + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` diff --git a/plugins/formal-verification/defaults.json b/plugins/formal-verification/defaults.json new file mode 100644 index 00000000000..252ff21de51 --- /dev/null +++ b/plugins/formal-verification/defaults.json @@ -0,0 +1,25 @@ +{ + "model_checker": { + "version": "1.7.4" + }, + "java": { + "min_version": "11", + "distribution": "temurin-25" + }, + "renderer": { + "package": "pele", + "version": "1.9.0", + "limit": 1000000, + "output_limit": 8000000, + "max_edges": 10000 + }, + "bounds": { + "chart_states": 500, + "rerun_states": 100000, + "timeout_seconds": 1800, + "heap": "4g", + "output_bytes": 1073741824, + "interval_max": 10000 + }, + "allowed_modules": ["Naturals", "Integers", "Reals", "Sequences", "FiniteSets", "Bags", "TLC", "TLCExt"] +} diff --git a/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/case.yaml b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/case.yaml new file mode 100644 index 00000000000..e1c4100bd20 --- /dev/null +++ b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/case.yaml @@ -0,0 +1,20 @@ +schema_version: "1.1" +name: ch-unattended-blocked-installs-nothing +graders: + - name: resolves-toolchain + type: tool_used + tool: Bash + input_match: 'toolchain\.mjs(?:\\?"|'')?\s+resolve\b' + arm: with-only + - name: reports-blocked + type: regex + pattern: 'blocked: toolchain missing' + target: last_message + arm: with-only + - name: no-install + type: tool_used + tool: Bash + input_match: '(?:toolchain\.mjs(?:\\?"|'')?\s+install\b|\b(?:mise|apt(?:-get)?|brew|winget|sdk)\s+install\b)' + min: 0 + max: 0 + arm: both diff --git a/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/prompt.md b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/prompt.md new file mode 100644 index 00000000000..36d8ff988ef --- /dev/null +++ b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/prompt.md @@ -0,0 +1,10 @@ +--- +description: 'An unattended chart run with no model checker jar installs nothing. chart SKILL.md Run step 1 resolves the toolchain with scripts/toolchain.mjs resolve; with the jar absent it prints blocked: toolchain missing, and with --unattended the skill reports that line and stops. The case data directory holds no jar. Host tools: node.' +tags: [formal-verification, chart, unattended, no-install] +max_turns: 10 +timeout_seconds: 300 +allowed_tools: [Bash, Read, Write, Edit, Glob, Grep, Skill] +expected_outcome: 'Resolves the toolchain, reports blocked: toolchain missing, and runs no install.' +--- + +Write a minimal TLA+ spec Counter.tla with its Counter.cfg in a scratch folder, then run /formal-verification:chart Counter.tla --unattended on it. diff --git a/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/no-install.json b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/no-install.json new file mode 100644 index 00000000000..50457246194 --- /dev/null +++ b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/no-install.json @@ -0,0 +1,11 @@ +{ + "pass": [ + {"answer": [], "why": "no calls"}, + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" resolve --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "the resolve step only"} + ], + "fail": [ + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" install model-checker --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "setup's install command, with the quoted script path"}, + {"answer": [{"tool": "Bash", "input": {"command": "node /plugins/formal-verification/scripts/toolchain.mjs install renderer --data-dir /data"}}], "why": "unquoted install"}, + {"answer": [{"tool": "Bash", "input": {"command": "brew install temurin"}}], "why": "installs Java itself"} + ] +} diff --git a/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/resolves-toolchain.json b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/resolves-toolchain.json new file mode 100644 index 00000000000..17bc35a006b --- /dev/null +++ b/plugins/formal-verification/evals/ch-unattended-blocked-installs-nothing/samples/resolves-toolchain.json @@ -0,0 +1,11 @@ +{ + "pass": [ + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" resolve --data-dir \"/data\" --project-dir \"/repo\" --jar '' --java '' --runtime ''"}}], "why": "the skill's command, with the quoted script path"}, + {"answer": [{"tool": "Bash", "input": {"command": "node /plugins/formal-verification/scripts/toolchain.mjs resolve --data-dir /data --project-dir /repo"}}], "why": "unquoted"} + ], + "fail": [ + {"answer": [], "why": "no calls"}, + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" check --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "check, not resolve"}, + {"answer": [{"tool": "Bash", "input": {"command": "cat /plugins/formal-verification/scripts/toolchain.mjs"}}], "why": "reads the script"} + ] +} diff --git a/plugins/formal-verification/evals/su-check-bare-read-only/case.yaml b/plugins/formal-verification/evals/su-check-bare-read-only/case.yaml new file mode 100644 index 00000000000..dcab1c86a8e --- /dev/null +++ b/plugins/formal-verification/evals/su-check-bare-read-only/case.yaml @@ -0,0 +1,26 @@ +schema_version: "1.1" +name: su-check-bare-read-only +graders: + - name: runs-toolchain-check + type: tool_used + tool: Bash + input_match: 'toolchain\.mjs(?:\\?"|'')?\s+check\b' + arm: with-only + - name: reports-rows + type: regex + pattern: '(?=[\s\S]*\bmodel-checker\b)(?=[\s\S]*\b(?:PASS|FAIL)\b)' + target: last_message + arm: both + - name: no-install + type: tool_used + tool: Bash + input_match: 'toolchain\.mjs(?:\\?"|'')?\s+install\b' + min: 0 + max: 0 + arm: both + - name: no-write + type: tool_used + tool: Write + min: 0 + max: 0 + arm: both diff --git a/plugins/formal-verification/evals/su-check-bare-read-only/prompt.md b/plugins/formal-verification/evals/su-check-bare-read-only/prompt.md new file mode 100644 index 00000000000..68570582649 --- /dev/null +++ b/plugins/formal-verification/evals/su-check-bare-read-only/prompt.md @@ -0,0 +1,10 @@ +--- +description: 'Bare setup runs the read-only check. setup SKILL.md sets disable-model-invocation: true, so the case invokes it by slash command. check is the default and runs scripts/toolchain.mjs check, whose rows include model-checker; nothing installs without a typed apply subaction. Host tools: node.' +tags: [formal-verification, setup, check, read-only] +max_turns: 10 +timeout_seconds: 300 +allowed_tools: [Bash, Read, Write, Edit, Glob, Grep, Skill] +expected_outcome: 'Runs scripts/toolchain.mjs check, reports its rows including model-checker, and installs and writes nothing.' +--- + +/formal-verification:setup diff --git a/plugins/formal-verification/evals/su-check-bare-read-only/samples/no-install.json b/plugins/formal-verification/evals/su-check-bare-read-only/samples/no-install.json new file mode 100644 index 00000000000..06785814b6a --- /dev/null +++ b/plugins/formal-verification/evals/su-check-bare-read-only/samples/no-install.json @@ -0,0 +1,10 @@ +{ + "pass": [ + {"answer": [], "why": "no calls"}, + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" check --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "the check only"} + ], + "fail": [ + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" install model-checker --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "setup's install command, with the quoted script path"}, + {"answer": [{"tool": "Bash", "input": {"command": "node /plugins/formal-verification/scripts/toolchain.mjs install renderer --data-dir /data"}}], "why": "unquoted install"} + ] +} diff --git a/plugins/formal-verification/evals/su-check-bare-read-only/samples/runs-toolchain-check.json b/plugins/formal-verification/evals/su-check-bare-read-only/samples/runs-toolchain-check.json new file mode 100644 index 00000000000..d02c9a8f29d --- /dev/null +++ b/plugins/formal-verification/evals/su-check-bare-read-only/samples/runs-toolchain-check.json @@ -0,0 +1,11 @@ +{ + "pass": [ + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" check --data-dir \"/data\" --project-dir \"/repo\" --jar '' --java '' --runtime ''"}}], "why": "the skill's command, with the quoted script path"}, + {"answer": [{"tool": "Bash", "input": {"command": "node /plugins/formal-verification/scripts/toolchain.mjs check --data-dir /data --project-dir /repo"}}], "why": "unquoted"} + ], + "fail": [ + {"answer": [], "why": "no calls"}, + {"answer": [{"tool": "Bash", "input": {"command": "node \"/plugins/formal-verification/scripts/toolchain.mjs\" resolve --data-dir \"/data\" --project-dir \"/repo\""}}], "why": "resolve, not check"}, + {"answer": [{"tool": "Bash", "input": {"command": "command -v java"}}], "why": "its own probe"} + ] +} diff --git a/plugins/formal-verification/lib/config-cascade.mjs b/plugins/formal-verification/lib/config-cascade.mjs new file mode 100644 index 00000000000..b3deb636513 --- /dev/null +++ b/plugins/formal-verification/lib/config-cascade.mjs @@ -0,0 +1,578 @@ +// GENERATED from lib/config-cascade.mjs by scripts/sync-shared-copies.sh. Do not edit this copy: +// edit the canonical source, then rerun the script. +// The four-layer plugin config cascade (docs/adr/0075): later layers win per key. +// +// resolve({plugin, projectRoot, home, schema, defaults, userConfig, teamOnly, floors, userHome}) +// -> {values, provenance: {"a.b": layer | [layers]}, prose: [paths], sections: [{heading, text, layer}], +// layers: [{name, path, state: "loaded" | "absent" | "invalid", errors, error_keys}], legacy: [{path, kind}]} +// +// readLayers({...}) -> each layer's own accepted values, unmerged (see its comment below) +// +// `error_keys[i]` tags `errors[i]`: the dotted key the error names (key-level), or null when it is +// about the layer as a whole (file-level: a file refused or unparsable, a value that is not a mapping). +// +// Layers, in order: "defaults" (the `defaults` object, already parsed by the caller), "userConfig" +// (the plugin's userConfig values, flattened names), "team" (/) and "local", the +// personal override (/.local). A file layer reads .yaml for config and .md +// for prose; it is absent when neither file exists. `home` is the convention home the caller +// resolved, relative to projectRoot unless absolute (default docs/conventions). There is no +// user-global file layer: a file under /docs/conventions is never read, and `userHome` +// (default os.homedir()) only locates the legacy files reported in `legacy`. `schema` is a JSON +// Schema object; the subset honored is type (object, string, array, null, integer, number, boolean), +// enum, properties, additionalProperties (false or a schema), items, minimum, maximum, minItems and +// maxItems. +// +// A key is a schema leaf: any node that is not an object with `properties`, or a path named in +// `teamOnly`. The setup writer's top-level `written_against` and `provenance` records are not keys, +// declared or not: every layer skips them, so they reach neither `values` nor a userConfig name. +// Each layer's leaves are checked one by one; a leaf whose value fails the schema is +// dropped from that layer with an error naming layer, file and key, and a lower layer's value is +// then never used (ADR 0075, the invalid-value rule): a valid higher layer still wins, otherwise the +// key takes its default. The personal override is the one exception, because it refines the team +// file: an invalid personal value leaves the team value standing. A key containing `.` is +// rejected the same way, since keys are joined with `.` into paths, and so are `__proto__`, +// `constructor` and `prototype`, at any depth inside a value too, which a caller's merge would treat +// as more than data. A refused file makes its layer invalid; the layer's other file still applies. The team and +// local layers come from the repository: each reads only regular files, never a symlink, and is +// invalid when a relative `home` resolves outside projectRoot. A team-only key is +// accepted in "defaults" and "team" and rejected elsewhere. A YAML file that does not parse, or +// whose top level is not a mapping, makes its layer invalid and contributes no values; its .md +// file still supplies prose. A leaf whose last segment is `disable` and whose value is a list is the +// union of every layer's list, and its provenance is an array of the layer names that set it, in +// layer order; every other key's provenance is a single layer-name string. +// +// Policy floors. `floors` maps a key path to a `Floor direction` value (the Implementers table of +// docs/contracts/config-cascade/README.md; the closed set is no-floor, team-only, lowest-value, +// any-layer-wins and stricter-value), or to {direction, scale} where stricter-value takes a scale +// from loosest to strictest (default: the leaf's schema `enum` order). When the team layer set a +// floor key, a personal value is accepted only if it is no looser in that direction: team-only takes +// an equal value (a list must keep every team item); lowest-value a number no higher; any-layer-wins +// a tightening value (`true` or "report") whenever the team value is one; stricter-value a value at +// or beyond the team value on the scale. A looser value is dropped with an error naming the layer, +// file and key, and the team value stands. Floors bind the personal override; a `*.disable` union key +// is not compared. +// +// userConfig maps each schema leaf path to its name joined with `_` (widget.limit is widget_limit); +// two leaves with one name throw. An empty string or an unrendered `${user_config.` placeholder is +// unset, names outside the schema are ignored, and a list, mapping or team-only key is rejected. +// A string value takes the leaf's integer, number or boolean type when the leaf does not accept +// strings. Legacy locations (.claude/.* under userHome and projectRoot, and a fenced +// `yaml config` block in the team .md) are reported in `legacy`, never read for values. +// +// Prose. A `.local.md` H2 section (a `## ` heading outside a code fence) replaces the team `.md` +// section with the same heading; every other team section is kept, a local section with a new +// heading follows them, and the team text before the first H2 is kept. `sections` lists the result in +// order, each with the layer it came from (`heading` is null for text before the first H2). +// This module reads files only. File contents are data; error messages quote them as JSON strings. +import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs"; +import { homedir } from "node:os"; +import { isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"; +import { parse } from "./yaml-subset.mjs"; + +const PLUGIN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; +const SCALARS = ["string", "integer", "number", "boolean", "null"]; +const DIRECTIONS = ["no-floor", "team-only", "lowest-value", "any-layer-wins", "stricter-value"]; +const clip = (text) => (text.length > 60 ? `${text.slice(0, 60)}...` : text); +const quote = (text) => JSON.stringify(clip(text)); +const show = (value) => clip(JSON.stringify(value) ?? String(value)); +const put = (object, key, value) => Object.defineProperty(object, key, { value, enumerable: true, writable: true, configurable: true }); +const isMapping = (v) => v !== null && typeof v === "object" && !Array.isArray(v); +const RESERVED = new Set(["__proto__", "constructor", "prototype"]); +const WRITER_KEYS = new Set(["written_against", "provenance"]); +const isWriterKey = (parts, key) => !parts.length && WRITER_KEYS.has(key); +const newLayer = (name, path, state, errors = [], error_keys = errors.map(() => null)) => ({ name, path, state, errors, error_keys }); +/** Records an error on `layer`, tagged with the dotted key it names, or null for a file-level one. */ +const record = (layer, message, key = null) => { + layer.errors.push(message); + layer.error_keys.push(key); +}; +/** Records `message` on `layer`, prefixed with the layer's name and path. */ +const recordOn = (layer, message, key) => record(layer, `${layer.name}${layer.path ? ` (${layer.path})` : ""}: ${message}`, key); + +function checkPlugin(plugin) { + if (typeof plugin !== "string" || !PLUGIN.test(plugin)) throw new Error(`config-cascade: plugin name ${JSON.stringify(plugin)} is not a plain name`); +} + +/** The convention home, whether a relative one escapes projectRoot, and the [name, stem] of each file layer. */ +function fileLayersOf(plugin, projectRoot, home) { + const homeDir = resolvePath(projectRoot, home); + // A relative home is inside the checkout by intent; a committed symlink must not carry it out. + const homeEscapes = !isAbsolute(home) && escapes(homeDir, projectRoot); + const stems = [ + ["team", join(homeDir, plugin)], + ["local", join(homeDir, `${plugin}.local`)], + ]; + return { homeDir, homeEscapes, stems }; +} + +const escapedLayer = (name, stem, homeDir) => + newLayer(name, `${stem}.yaml`, "invalid", [`${name} (${homeDir}): the convention home resolves outside the project; a repository layer stays inside it`]); + +/** {ok} for a readable repository layer file, {refused: why} for one that must not be read, {} when + * absent. A symlink is refused, since it could reach a file outside the checkout, and so is anything + * but a regular file, since a device or FIFO never finishes reading. */ +function fileState(path) { + let st; + try { + st = lstatSync(path); + } catch { + return {}; + } + if (st.isSymbolicLink()) return { refused: "is a symlink; a repository layer reads only regular files" }; + return st.isFile() ? { ok: true } : { refused: "is not a regular file" }; +} + +/** True when `dir` exists and its real path lies outside the real path of `root`. */ +function escapes(dir, root) { + try { + const rel = relative(realpathSync(root), realpathSync(dir)); + return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel); + } catch { + return false; + } +} +const typesOf = (node) => (node.type === undefined ? null : [node.type].flat()); + +const fits = { + object: isMapping, + array: Array.isArray, + string: (v) => typeof v === "string", + integer: Number.isInteger, + number: (v) => typeof v === "number" && Number.isFinite(v), + boolean: (v) => typeof v === "boolean", + null: (v) => v === null, +}; + +/** The schema for `key` under `node`: a schema, null when anything goes, false when it is unknown. */ +function child(node, key) { + if (isMapping(node.properties) && Object.hasOwn(node.properties, key)) return node.properties[key]; + if (node.additionalProperties === false) return false; + return isMapping(node.additionalProperties) ? node.additionalProperties : null; +} + +const isBranch = (node, path, teamOnly) => + isMapping(node) && isMapping(node.properties) && !teamOnly.has(path) && (typesOf(node)?.includes("object") ?? true); + +/** Why `value` does not fit `node`, as messages relative to the key; empty when it fits. */ +function check(value, node, at = "") { + const prefix = at ? `${at}: ` : ""; + const types = typesOf(node); + if (types && !types.some((t) => fits[t]?.(value))) return [`${prefix}expected ${types.join(" or ")}, got ${show(value)}`]; + if (Array.isArray(node.enum) && !node.enum.includes(value)) return [`${prefix}${show(value)} is not one of ${node.enum.map(show).join(", ")}`]; + if (typeof value === "number" && typeof node.minimum === "number" && value < node.minimum) return [`${prefix}${show(value)} must be at least ${node.minimum}`]; + if (typeof value === "number" && typeof node.maximum === "number" && value > node.maximum) return [`${prefix}${show(value)} must be at most ${node.maximum}`]; + if (Array.isArray(value) && typeof node.minItems === "number" && value.length < node.minItems) return [`${prefix}needs at least ${node.minItems} items, got ${value.length}`]; + if (Array.isArray(value) && typeof node.maxItems === "number" && value.length > node.maxItems) return [`${prefix}allows at most ${node.maxItems} items, got ${value.length}`]; + // An open node ({}) checks nothing but reserved names, which are refused at every depth. + if (Array.isArray(value)) return value.flatMap((item, i) => check(item, isMapping(node.items) ? node.items : {}, `${at}[${i}]`)); + if (!isMapping(value)) return []; + return Object.keys(value).flatMap((key) => { + const where = `${at}.${quote(key)}`; + if (RESERVED.has(key)) return [`${where}: a reserved name, never a config key`]; + const sub = child(node, key); + if (sub === false) return [`${where}: unknown key`]; + return check(value[key], sub ?? {}, where); + }); +} + +/** The accepted leaves of one layer's mapping, as [parts, value] pairs; rejections go to `fail` + * with the dotted key, and `true` third when the value itself was the problem. */ +function leaves(data, schema, { teamOnly, allowTeamOnly, fail }) { + const out = []; + const walk = (object, node, parts) => { + for (const key of Object.keys(object)) { + if (isWriterKey(parts, key)) continue; + const path = [...parts, key]; + const dotted = path.join("."); + const sub = child(node, key); + const value = object[key]; + if (RESERVED.has(key)) fail(`${quote(dotted)}: a reserved name, never a config key`, dotted); + else if (key.includes(".")) fail(`${quote(dotted)}: a key may not contain "."; nest it instead`, dotted); + else if (sub === false) fail(`${quote(dotted)}: unknown key`, dotted); + else if (teamOnly.has(dotted) && !allowTeamOnly) fail(`${quote(dotted)}: accepted only in the team layer`, dotted); + else if (sub && isBranch(sub, dotted, teamOnly)) { + if (isMapping(value)) walk(value, sub, path); + else if (value !== null) fail(`${quote(dotted)}: expected a mapping, got ${show(value)}`, dotted, true); + } else { + const problems = check(value, sub ?? {}); + if (problems.length) fail(`${quote(dotted)}: ${problems.join("; ")}`, dotted, true); + else out.push([path, value]); + } + } + }; + walk(data, schema, []); + return out; +} + +/** Flattened userConfig name to {path, node} for every schema leaf. */ +function flatNames(schema, teamOnly) { + const names = new Map(); + const walk = (node, parts) => { + for (const key of Object.keys(isMapping(node.properties) ? node.properties : {})) { + if (isWriterKey(parts, key)) continue; + const path = [...parts, key]; + const dotted = path.join("."); + const sub = node.properties[key]; + if (isBranch(sub, dotted, teamOnly)) { + walk(sub, path); + continue; + } + const name = path.join("_"); + if (names.has(name)) throw new Error(`config-cascade: schema keys ${names.get(name).dotted} and ${dotted} both flatten to userConfig name ${name}`); + names.set(name, { path, dotted, node: sub }); + } + }; + walk(schema, []); + return names; +} + +function coerce(raw, node) { + const types = typesOf(node) ?? []; + if (typeof raw !== "string" || types.includes("string")) return raw; + if ((types.includes("integer") || types.includes("number")) && /^[-+]?\d+(\.\d+)?$/.test(raw)) return Number(raw); + if (types.includes("boolean") && (raw === "true" || raw === "false")) return raw === "true"; + return raw; +} + +function userConfigLeaves(userConfig, names, teamOnly, fail) { + const out = []; + for (const [name, raw] of Object.entries(userConfig)) { + if (raw === undefined || raw === null || raw === "" || (typeof raw === "string" && raw.startsWith("${user_config."))) continue; + const leaf = names.get(name); + if (!leaf) continue; + const types = typesOf(leaf.node); + if (teamOnly.has(leaf.dotted)) fail(`${quote(leaf.dotted)}: accepted only in the team layer`, leaf.dotted); + else if (types && !types.every((t) => SCALARS.includes(t))) fail(`${quote(leaf.dotted)}: lists and mappings are set only in files`, leaf.dotted); + else { + const value = coerce(raw, leaf.node); + const problems = check(value, leaf.node); + if (problems.length) fail(`${quote(leaf.dotted)}: ${problems.join("; ")}`, leaf.dotted, true); + else out.push([leaf.path, value]); + } + } + return out; +} + +/** One file layer: its report entry, its parsed mapping (or null), and its prose path (or null). */ +function readLayer(name, stem) { + const path = `${stem}.yaml`; + const md = `${stem}.md`; + const layer = newLayer(name, path, "absent"); + const mdFile = fileState(md); + if (mdFile.refused) { + layer.state = "invalid"; + record(layer, `${name} (${md}): ${mdFile.refused}`); + } + const prose = mdFile.ok ? md : null; + if (prose) layer.state = "loaded"; + const yamlFile = fileState(path); + if (yamlFile.refused) { + layer.state = "invalid"; + record(layer, `${name} (${path}): ${yamlFile.refused}`); + } + if (!yamlFile.ok) return { layer, data: null, prose }; + return { layer, data: parseInto(layer, () => readFileSync(path, "utf8")), prose }; +} + +/** The mapping `text()` parses to, loading `layer`; null, with the layer invalid, when it does not parse or is not a mapping. */ +function parseInto(layer, text) { + try { + const doc = parse(text()) ?? {}; + if (!isMapping(doc)) throw new Error("the top level must be a mapping"); + if (layer.state !== "invalid") layer.state = "loaded"; + return doc; + } catch (e) { + layer.state = "invalid"; + record(layer, `${layer.name} (${layer.path}): ${e.message}`); + return null; + } +} + +/** The body of the first ``` config block outside any other fence in a Markdown text, running to + * the end when unclosed; null when there is none. */ +export function configBlockBody(text) { + let fence = null; // the open fence's marker run, backticks or tildes + let body = null; + for (const line of text.split(/\r\n|\r|\n/)) { + const run = line.match(/^(`{3,}|~{3,})/)?.[0]; + if (fence) { + if (run?.[0] === fence[0] && run.length >= fence.length && line.trimEnd().length === run.length) { + if (body) return body.join("\n"); + fence = null; + } else body?.push(line); + } else if (/^```[A-Za-z0-9_-]+ config\s*$/.test(line)) [fence, body] = ["```", []]; + else if (run) fence = run; + } + return body?.join("\n") ?? null; +} + +/** True when the Markdown file holds a ``` config block outside any other fence. */ +function hasConfigBlock(path) { + const text = fileState(path).ok ? readText(path) : null; + return text !== null && configBlockBody(text) !== null; +} + +/** A Markdown text as [{heading, text}], split at each H2 outside a code fence; the first entry holds + * the text before the first H2 (heading null) and is dropped when empty. */ +function splitSections(text) { + const out = [{ heading: null, lines: [] }]; + let fence = null; + for (const line of text.split(/(?<=\n)/)) { + const run = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1]; + if (fence) { + if (run?.[0] === fence[0] && run.length >= fence.length && line.trim().length === run.length) fence = null; + } else if (run) fence = run; + else { + const h = line.match(/^## +(.*?)(?: +#+)?\s*$/); + if (h) { + out.push({ heading: h[1].replace(/\s+/g, " ").trim(), lines: [line] }); + continue; + } + } + out.at(-1).lines.push(line); + } + return out.map(({ heading, lines }) => ({ heading, text: lines.join("") })).filter((s) => s.heading !== null || s.text.trim() !== ""); +} + +function readText(path) { + try { + return readFileSync(path, "utf8"); + } catch { + return null; + } +} + +/** The team sections with each same-heading local section in its place, then the local sections the + * team lacks. The first team section with a heading is replaced; a later team repeat of it is dropped. */ +function mergeSections(teamText, localText) { + const team = teamText === null ? [] : splitSections(teamText).map((s) => ({ ...s, layer: "team" })); + const local = localText === null ? [] : splitSections(localText).map((s) => ({ ...s, layer: "local" })); + const replacement = new Map(local.filter((s) => s.heading !== null).map((s) => [s.heading, s])); + const used = new Set(); + const out = []; + for (const s of team) { + if (s.heading === null || !replacement.has(s.heading)) out.push(s); + else if (!used.has(s.heading)) { + used.add(s.heading); + out.push(replacement.get(s.heading)); + } + } + const teamHeadings = new Set(team.map((s) => s.heading)); + for (const s of local) { + // Text before the first H2 follows the team's own only when the team has no file; a repeated heading keeps its last section. + const fresh = s.heading === null ? team.length === 0 : !teamHeadings.has(s.heading) && replacement.get(s.heading) === s; + if (fresh) out.push(s); + } + return out; +} + +function legacyFiles(dir, plugin, kind) { + let entries; + try { + entries = readdirSync(dir, { withFileTypes: true }); + } catch { + return []; + } + return entries.filter((e) => e.isFile() && e.name.startsWith(`${plugin}.`)).map((e) => ({ path: join(dir, e.name), kind: kind(e.name) })); +} + +function setPath(object, parts, value) { + let at = object; + for (const part of parts.slice(0, -1)) { + if (!Object.hasOwn(at, part) || !isMapping(at[part])) put(at, part, {}); + at = at[part]; + } + put(at, parts.at(-1), value); +} + +/** Validated floors: dotted key to {direction, scale}. */ +function normalizeFloors(floors) { + if (!isMapping(floors)) throw new Error("config-cascade: floors must be a mapping of key path to Floor direction"); + const out = new Map(); + for (const [key, raw] of Object.entries(floors)) { + const direction = typeof raw === "string" ? raw : raw?.direction; + if (!DIRECTIONS.includes(direction)) throw new Error(`config-cascade: floor ${JSON.stringify(key)} has direction ${show(direction)}, not one of ${DIRECTIONS.join(", ")}`); + out.set(key, { direction, scale: isMapping(raw) && Array.isArray(raw.scale) ? raw.scale : null }); + } + return out; +} + +function nodeAt(schema, parts) { + let node = schema; + for (const part of parts) { + node = node && child(node, part); + if (!node) return null; + } + return node; +} + +const tightening = (v) => v === true || v === "report"; + +/** Why `personal` loosens `team` in the floor's direction, or null when it does not. */ +function looser(floor, personal, team, node) { + if (JSON.stringify(personal) === JSON.stringify(team)) return null; + switch (floor.direction) { + case "team-only": + if (Array.isArray(personal) && Array.isArray(team) && team.every((t) => personal.some((p) => JSON.stringify(p) === JSON.stringify(t)))) return null; + return `${show(personal)} differs from the team value ${show(team)}, and the team value wins`; + case "lowest-value": + if (typeof personal === "number" && typeof team === "number" && personal <= team) return null; + return `${show(personal)} is not lower than or equal to the team value ${show(team)}`; + case "any-layer-wins": + if (!tightening(team) || tightening(personal)) return null; + return `${show(personal)} drops the team value ${show(team)}, which is the tightening one`; + case "stricter-value": { + const scale = floor.scale ?? node?.enum ?? []; + const a = scale.findIndex((v) => JSON.stringify(v) === JSON.stringify(personal)); + const b = scale.findIndex((v) => JSON.stringify(v) === JSON.stringify(team)); + if (a >= 0 && b >= 0 && a >= b) return null; + return `${show(personal)} is not as strict as the team value ${show(team)} on the scale ${show(scale)}`; + } + default: + return null; + } +} + +export function resolve({ plugin, projectRoot, home = "docs/conventions", schema, defaults, userConfig, teamOnly = [], floors = {}, userHome = homedir() }) { + checkPlugin(plugin); + const only = new Set(teamOnly); + const floorMap = normalizeFloors(floors); + const names = flatNames(schema, only); + const { homeDir, homeEscapes, stems } = fileLayersOf(plugin, projectRoot, home); + const layers = []; + const contributions = []; // [layer name, [[parts, value]], dotted keys whose value was invalid] + const prose = []; + const proseText = {}; + + // pairsOf(fail) returns the layer's accepted [parts, value] pairs; falsy when it contributes none. + const take = (layer, pairsOf) => { + const invalid = new Set(); + const fail = (message, key, valueFailed = false) => { + recordOn(layer, message, key); + if (valueFailed) invalid.add(key); + }; + if (pairsOf) contributions.push([layer.name, pairsOf(fail), invalid]); + layers.push(layer); + }; + const fileLeaves = (data, allowTeamOnly) => data && ((fail) => leaves(data, schema, { teamOnly: only, allowTeamOnly, fail })); + + const shaped = (name, given) => { + if (given === undefined || given === null) return { layer: newLayer(name, null, "absent"), ok: false }; + if (isMapping(given)) return { layer: newLayer(name, null, "loaded"), ok: true }; + return { layer: newLayer(name, null, "invalid", [`${name}: expected a mapping, got ${show(given)}`]), ok: false }; + }; + const d = shaped("defaults", defaults); + take(d.layer, d.ok && fileLeaves(defaults, true)); + const u = shaped("userConfig", userConfig); + take(u.layer, u.ok && ((fail) => userConfigLeaves(userConfig, names, only, fail))); + for (const [name, stem] of stems) { + if (homeEscapes) { + take(escapedLayer(name, stem, homeDir)); + continue; + } + const read = readLayer(name, stem); + take(read.layer, fileLeaves(read.data, name === "team")); + if (read.prose) { + prose.push(read.prose); + proseText[name] = readText(read.prose); + } + } + + const merged = new Map(); // dotted -> {parts, value, from} + let base = new Map(); // the defaults layer's entries, where an invalid higher value falls back to + const within = (dotted, key) => dotted === key || dotted.startsWith(`${key}.`); + for (const [name, pairs, invalid] of contributions) { + // A lower layer's value is never used for an invalid one; the personal override refines the team file, so its keys fall to team. + if (name !== "local") { + for (const key of invalid) { + for (const dotted of [...merged.keys()]) if (within(dotted, key)) merged.delete(dotted); + for (const [dotted, entry] of base) if (within(dotted, key)) merged.set(dotted, entry); + } + } + const layer = layers.find((l) => l.name === name); + for (const [parts, value] of pairs) { + const dotted = parts.join("."); + const prior = merged.get(dotted); + const floor = floorMap.get(dotted); + const union = parts.at(-1) === "disable" && Array.isArray(value); + if (name === "local" && floor && floor.direction !== "no-floor" && !union && prior && [prior.from].flat().includes("team")) { + const why = looser(floor, value, prior.value, nodeAt(schema, parts)); + if (why) { + record(layer, `local (${layer.path}): ${quote(dotted)}: loosens the ${floor.direction} policy floor: ${why}`, dotted); + continue; + } + } + if (union) { + const items = Array.isArray(prior?.value) ? [...prior.value] : []; + const seen = new Set(items.map((i) => JSON.stringify(i))); + for (const item of value) { + const key = JSON.stringify(item); + if (!seen.has(key)) items.push(item); + seen.add(key); + } + // An empty list adds nothing, so its layer is credited only when no layer set the key before. + const from = Array.isArray(prior?.from) ? prior.from : []; + merged.set(dotted, { parts, value: items, from: value.length > 0 || !prior ? [...from, name] : from }); + } else merged.set(dotted, { parts, value, from: name }); + } + if (name === "defaults") base = new Map(merged); + } + const values = {}; + const provenance = {}; + for (const [dotted, { parts, value, from }] of merged) { + setPath(values, parts, value); + put(provenance, dotted, from); + } + + const legacy = legacyOf(plugin, userHome, projectRoot, !homeEscapes && `${join(homeDir, plugin)}.md`); + const sections = mergeSections(proseText.team ?? null, proseText.local ?? null).map(({ heading, text, layer }) => ({ heading, text, layer })); + return { values, provenance, prose, sections, layers, legacy }; +} + +/** The legacy locations that exist; `teamMd` (or false) is the team .md checked for a fenced config block. */ +function legacyOf(plugin, userHome, projectRoot, teamMd) { + const found = [ + ...legacyFiles(join(userHome, ".claude"), plugin, () => "claude-user"), + ...(projectRoot ? legacyFiles(join(projectRoot, ".claude"), plugin, (n) => (n.startsWith(`${plugin}.local.`) ? "claude-local" : "claude-project")) : []), + ...(teamMd && hasConfigBlock(teamMd) ? [{ path: teamMd, kind: "fenced-block" }] : []), + ]; + // The project root may be the user home, so a file is reported under its first kind only. + return found.filter((entry, i) => found.findIndex((e) => e.path === entry.path) === i); +} + +/** + * Each layer's own accepted values, unmerged, for a caller that weighs the layers itself (the + * rendered-views publish rule reads every layer separately: lib/view-settings.mjs). The same reader, + * refusals and schema check as resolve(), with no precedence, floors or invalid-value fallback: an + * invalid value leaves only its own layer. Layers: "userConfig", then "team" and "local" when + * projectRoot is set. `team`, as {path, text}, replaces the working-tree team file (text null: + * absent), for a caller reading it from a git ref. + * readLayers({plugin, projectRoot, home, schema, userConfig, teamOnly, team, userHome}) + * -> {layers: [{name, path, state, errors, error_keys, values: {"a.b": value}}], legacy} + */ +export function readLayers({ plugin, projectRoot = null, home = "docs/conventions", schema, userConfig, teamOnly = [], team, userHome = homedir() }) { + checkPlugin(plugin); + const only = new Set(teamOnly); + const layers = []; + const add = (layer, pairsOf) => { + const values = {}; + for (const [parts, value] of pairsOf ? pairsOf((message, key) => recordOn(layer, message, key)) : []) put(values, parts.join("."), value); + layers.push({ ...layer, values }); + }; + if (isMapping(userConfig)) add(newLayer("userConfig", null, "loaded"), (fail) => userConfigLeaves(userConfig, flatNames(schema, only), only, fail)); + if (!projectRoot) return { layers, legacy: legacyOf(plugin, userHome, null, false) }; + const { homeDir, homeEscapes, stems } = fileLayersOf(plugin, projectRoot, home); + for (const [name, stem] of stems) { + const fileLeaves = (data) => data && ((fail) => leaves(data, schema, { teamOnly: only, allowTeamOnly: name === "team", fail })); + if (name === "team" && team) { + const layer = newLayer(name, team.path, "absent"); + add(layer, typeof team.text === "string" && fileLeaves(parseInto(layer, () => team.text))); + } else if (homeEscapes) { + add(escapedLayer(name, stem, homeDir)); + } else { + const read = readLayer(name, stem); + add(read.layer, fileLeaves(read.data)); + } + } + return { layers, legacy: legacyOf(plugin, userHome, projectRoot, !homeEscapes && `${join(homeDir, plugin)}.md`) }; +} diff --git a/plugins/formal-verification/lib/prerequisites.mjs b/plugins/formal-verification/lib/prerequisites.mjs new file mode 100755 index 00000000000..47d4e08e8d5 --- /dev/null +++ b/plugins/formal-verification/lib/prerequisites.mjs @@ -0,0 +1,745 @@ +#!/usr/bin/env node +// GENERATED from lib/prerequisites.mjs by scripts/sync-shared-copies.sh. Do not edit this copy: +// edit the canonical source, then rerun the script. +// Read a plugin's prerequisites.json and report which declared dependencies resolve. +// The contract is docs/contracts/prerequisites/README.md; the schema sits beside it. +// +// prerequisites.mjs report --plugin-root [--plugin-root ...] +// prerequisites.mjs check [--for ] [--data-dir ] +// prerequisites.mjs probe [--run-if-unset-or-true