@codacy/verity-cli 0.33.3-experimental.52f1656 → 0.33.3-experimental.53cd005

package/data/skills/verity-prove/SKILL.md

@@ -1,174 +1,135 @@
 ---
 description: >-
-  Formally verify a small, risky piece of code with a Lean 4 model: pick candidates from git
-  history, CONFIRM with the user which code to model, write the model, run it locally with
-  `verity prove check`, and replay any counterexample on the real code before calling it a bug.
-  Use when the user asks to verify, prove, or model-check code, or asks "can this race / double
-  run / fail open?". Anything typed after /verity-prove is the user's hint: the file, function,
-  or worry to check.
+  Formally verify a small, risky piece of code with a Lean 4 model written by the
+  Verity service: rank candidates from git history and the user's hint, CONFIRM with
+  the user which code to model, have the service generate the model, check it locally
+  with `verity prove check`, and replay any counterexample on the real code before
+  calling it a bug. Use when the user asks to verify, prove, or model-check code, or
+  asks "can this race / double run / fail open?". Anything typed after /verity-prove
+  is the user's hint: the file, function, or worry to check.
 ---
 # /verity-prove — Formal verification of small pieces of code
 
 **The words after `/verity-prove` are the hint.** `/verity-prove` alone means "find me
 something worth checking"; `/verity-prove can the Stripe webhook double-charge on a
-redelivered event?` means that is the target and, if it is a worry, the property.
-Carry it through every step below as `$ARGUMENTS`.
+redelivered event?` names the target and the worry. Carry it through every step as
+`$ARGUMENTS`.
 
-Verity keeps **Lean 4 models of the riskiest code**, not of the codebase. A model is
-another tool for finding bugs: a few dozen lines that abstract ONE function and check
-a few properties by exhaustive bounded search. When a property fails you get the
-**shortest sequence of actions** that breaks it — a hypothesis to replay on the real
-code. When it holds you know exactly how far it was checked.
+Verity keeps **Lean 4 models of the riskiest code**, not of the codebase: a few dozen
+lines that abstract ONE function and check a few properties by exhaustive bounded
+search. When a property fails you get the **shortest sequence of actions** that breaks
+it — a hypothesis to replay on the real code.
 
-This skill is the **explicit, user-driven** entry; nothing in it blocks a commit or a
-push. (The push-time phase — `verity config formal push` — is a separate, opt-in path
-that uses the same tools.) Lean runs on this machine because the user asked for it.
+**The service does the work; you orchestrate and present.** Ranking, writing the model
+and replaying its counterexample all run on the Verity service through the CLI. You
+do not search the codebase by hand, read the Lean library, or write Lean yourself
+unless a step below says so. Each step is one command; read its output, decide, move on.
+Lean runs on this machine only because the user asked for it; nothing here blocks a
+commit or a push.
 
 ## The flow
 
-### 1. Find what deserves a model
+### 1. Candidates — one command
 
 ```bash
-verity prove candidates --limit 8            # git history + risk signals
-verity prove candidates --rank luna --json   # + a cheap model re-ranks and names a symbol
-verity prove candidates src/payments         # scoped to a path
+verity prove candidates --hint "$ARGUMENTS" --json    # hint given
+verity prove candidates --limit 8 --json              # no hint
 ```
 
-Each candidate says why: fix commits over commits, check-then-act, retries, caches,
-locks/leases, status transitions, money.
+The hint **widens the pool** (files it names by path or content come first) and the
+service ranks it, naming a symbol and the properties worth checking per file. Do not
+search for the code yourself: if the ranker's list does not contain what the user
+meant, say so and ask them for the file or function. A named file or function in the
+hint skips ranking: go straight to step 2 with it.
 
-**With a hint** (`$ARGUMENTS` non-empty) — a file, a function, or a worry in the user's
-own words ("can the webhook double-charge?", "does the retry ever lose the feedback?"):
+### 2. Confirm with the user — always
 
-```bash
-verity prove candidates --hint "$ARGUMENTS"
-```
+**Do not generate a model until the user has said which code.** Present at most three
+candidates in one short message: file, the symbol the ranker named, the first property
+it suggested, the reason. Ask. Their answer is the scope; do not widen it. If the hint
+is a worry in the user's words, it becomes an `intent` property — that needs no further
+confirmation, they just gave it.
 
-A named file or function skips the ranking entirely: go to step 2 with it. A *worry*
-becomes an `intent` property in step 4, with `source := "user, <date>: <their words>"`;
-it needs no further confirmation, they just gave it. The candidates list is still shown,
-so the user sees what else the history says — but the hint decides.
+A hint that names the code, or a candidate the user saw in an earlier session, is
+**not** a confirmation of the exact symbol and property. Still ask, in one line:
+"I'll model `<file>#<symbol>` for `<property>` — go ahead?" It costs the user one word.
 
-### 2. Confirm with the user — always
+### 3. Set up once per repo
 
-**Do not write a model until the user has said which code.** Present at most three
-candidates in one short message, each as: file, the function you would model, the
-property you would check first, and the reason from the signals. Then ask. The user may
-pick one, name something else, or narrow the property. Their answer is the scope; do not
-widen it.
+```bash
+verity prove init
+```
 
-A model is a claim about what the code *means*. Only the person who owns the code can
-say whether that claim is worth checking.
+If Lean is missing, say what will be installed and where before running
+`verity lean install` (official release, ≈800 MB download, 2.7 GB on disk, into
+`~/.verity/lean`). Everything else needs only `verity login`.
 
-### 3. Set up the project (once per repo)
+### 4. Generate the model — one command
 
 ```bash
-verity prove init
+verity prove generate src/pay.ts#charge --hint "$ARGUMENTS"
+verity prove generate src/handler.ts --lines 120-180 --hint "$ARGUMENTS"   # a region
 ```
 
-Creates `.verity/proofs/` — a Lake project with Verity's library (`Verity.System`,
-`Verity.check`, a bounded explorer). Re-running refreshes the library and never touches
-`Models/`. If Lean is missing, install it only after telling the user what will be
-installed and where: `verity lean install` (official release, ≈800 MB download, 2.7 GB
-on disk, into `~/.verity/lean`). Ranking (`--hint`, `--rank luna`) and `verity prove
-replay` run on the Verity service with the user's login (`verity login`); without a
-login, ranking is deterministic and replay is by hand (step 6.2).
-
-### 4. Write the model — `Models/<Name>.lean`
-
-Rules that keep models small and honest:
-
-- **One symbol.** The header names it: `Verity.model { name, abstracts := [{ file, symbol, sha256 }] }`.
-  Get the hash with `verity prove hash <file>`. `verity prove check` reports drift when the file changes.
-  When the code is a *region* rather than a named function (a branch inside a large
-  handler), add `lines := "a-b"` (1-based, inclusive) — `verity prove replay` needs it
-  to know which real lines must run.
-- **State = only what the property reads.** Actions = the operations that can interleave
-  (a retry, a second call, a concurrent writer). Steps = what the code does, not what it should.
-- **Properties are tagged.** `kind := .structural` for the catalogue (idempotence, no lost
-  update, status only moves forward, retries terminate, never fails open, bounded size,
-  check-then-act is atomic, no double effect). `kind := .intent` **only** when a human
-  wrote the expectation down — a doc comment, an ADR, a ticket, a Standard rule — and
-  `source :=` cites it. Never invent intent.
-- **End with the checks.** `#eval Verity.model …` then one `#eval Verity.check …` per
-  property (bounded exploration), `Verity.checkData` for input properties, `Verity.proved`
-  only beside a real theorem. `sorry` fails the run.
-- Keep it under ~120 lines. If it wants more, the scope is wrong — go back to step 2.
-
-`Models/README.md` has the skeleton; `cli/tests/fixtures/proofs/SeedRunner.lean` in
-Verity's own repo is a worked example (the VRT-243 seed-duplication bug).
-
-### 5. Check it
+The service writes the model, the linter fences it, this machine elaborates it, with
+up to **3** rounds on compiler errors — all inside the command. It prints the check:
+per property `✓ holds to bound k`, `✗ COUNTEREXAMPLE` with the trace, or `? inconclusive`.
+Only if it ends with "no model elaborated" do you write one by hand from
+`.verity/proofs/Models/README.md` (one symbol, ≤ ~120 lines, `#eval Verity.model …`
+header, one `#eval Verity.check …` per property, tagged `.structural` or `.intent` with
+`source :=`); check it with `verity prove check <Name>`.
+
+### 5. Replay before you call it a bug — one command
 
 ```bash
-verity prove check <Name>          # one model
-verity prove check                 # every model
-verity prove check <Name> --json   # for scripts
+verity prove replay <Name>                 # every counterexample
+verity prove replay <Name> --property P2   # one
 ```
 
-Per property: `✓ holds to bound k`, `✓ proved`, `✗ COUNTEREXAMPLE` with the trace and
-the state after each step, or `? inconclusive` (state cap).
-
-**Hard caps — never loop:**
-- elaboration errors: at most **3** fix rounds, then stop and say the model could not be
-  built;
-- a counterexample that **diverges** on replay (the model was wrong about the code): at
-  most **2** model revisions, each naming what the replay showed was different; after
-  that, stop and report "no faithful model found for `<symbol>`" — that is a valid result;
-- never weaken or delete a property to make it pass; never add a property to make
-  something fail.
-
-A wrong model is expected some of the time. It costs a replay and is discarded; it never
-costs a false bug, because only a *reproduced* counterexample is reported (step 6).
-
-### 6. Replay before you call it a bug
-
-A counterexample is a fact about the **model**. Before reporting a bug:
-
-1. Run the replay in OpenAI's disposable container (network off, deleted afterwards):
-
-   ```bash
-   verity prove replay <Name>                 # every counterexample
-   verity prove replay <Name> --property P2   # one
-   ```
-
-   It hands a model the trace, the Lean file and the real source — the abstracted
-   file's content leaves the machine for the Verity service and OpenAI's container;
-   only git-tracked files are ever read — and requires three things before accepting
-   its answer: code actually ran (a shell call with output), the real function's lines
-   appear verbatim in what it wrote, and the harness itself printed
-   `REPLAY_RESULT=reproduced`. `REPRODUCED` → the
-   real code does this. `DIVERGED` → the model is wrong about the code. `UNVERIFIED` →
-   not evidence either way. `UNREPLAYABLE` → it could not run the function faithfully.
-   Read its reason: the stubs it chose are where a false reproduction hides.
-2. When the replay is unverified or unreplayable — or the code needs a runtime the
-   container lacks (Deno edge functions, a real database) — replay by hand: read the
-   real function again, map every trace action to a real call, and reproduce it with a
-   throwaway harness in a scratch directory that loads the real module and stubs only
-   I/O boundaries. **Never edit the user's source files to do this.**
-3. Reproduced → report it as a bug, with the trace and the reproduction. Not reproduced
-   → the model is wrong (`model-divergence`): say so, fix the model, do not report a bug.
-
-This is the rule Verity applies everywhere (memory: *replay formal counterexamples
-against changed code before blocking*). A model that finds a bug in itself is noise.
-
-### 7. Report, in a few lines
-
-State what was modelled, what was checked to what bound, what was refuted and whether
-it replayed, and what remains `intent` awaiting the user's confirmation. **Never offer
-to commit the model** — `.verity/proofs/` is machine-local and ignores itself; models
-would only confuse reviewers. What reaches the team is the bug report and, when asked,
-the fix. Then record the outcome:
+The service replays the trace on the real code in a network-less container and accepts
+an answer only when code ran, the real function's lines appear verbatim in the harness,
+and the harness itself printed `REPLAY_RESULT=reproduced`. A model's counterexamples
+replay in parallel, so the command takes about as long as one replay (~30 s). **Run it
+in the foreground and wait for it**: do not background it, do other work, or report
+before every verdict is in. Read the verdict:
+
+- **REPRODUCED** — the real code does this. **This is final: do not replay by hand
+  as well.** Report it as a bug (step 6).
+- **DIVERGED** — the model is wrong about the code. Revise it **at most twice**, each
+  time saying what the replay showed:
+  `verity prove generate <target> --revise <Name> --note "<what the replay showed>"`,
+  then replay again. After two divergences, report "no faithful model found for
+  `<symbol>`" — that is a valid result, not a bug.
+- **UNVERIFIED / UNREPLAYABLE** — not evidence either way. Only now replay by hand:
+  a throwaway harness in a scratch directory that loads the real module and stubs only
+  I/O boundaries **in memory**. Never edit the user's source files, and never read from
+  or write to the user's databases, services or local stacks to do this — ask first if
+  a stub cannot be faithful.
+
+Never weaken or delete a property to get green; never add one to make something fail.
+
+### 6. Report, in a few lines
+
+What was modelled, what was checked to what bound, what was refuted and whether it
+replayed, and what remains `intent` awaiting the user's confirmation. **Never offer to
+commit the model** — `.verity/proofs/` is machine-local and ignores itself. What reaches
+the team is the bug report and, when asked, the fix. Then record the outcome:
 
 ```bash
 verity reflect --user-input "Modelled runSeed (cli/src/lib/seed-runner.ts): P1 at-most-once refuted in 2 steps, replayed — guard checks a path the server never writes." --kind gotcha
 ```
 
+The abstracted file's content leaves the machine for the Verity service and its
+replay container; only git-tracked files are ever read.
+
 ## Do not
 
+- Search the codebase yourself before the ranker has answered, or instead of asking the user.
 - Model code the user did not confirm.
-- Present a model-only counterexample as a bug.
-- Put `sorry` in a model, or weaken a property to get green.
-- Touch source files, run Lean from a hook, or install anything silently.
+- Write Lean by hand while `verity prove generate` can still try.
+- Replay by hand after a REPRODUCED verdict, or present a model-only counterexample as a bug.
+- Background `verity prove replay`, or report before its verdicts are in.
+- Write to the user's databases or local services, even throwaway rows.
+- Put `sorry` in a model, weaken a property to get green, or touch source files.
+- Run Lean from a hook, or install anything silently.
 - Commit, stage, or un-ignore anything under `.verity/proofs/`.
-- Model a whole module. If the state has more than ~6 fields, narrow it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/verity-cli",
-  "version": "0.33.3-experimental.52f1656",
+  "version": "0.33.3-experimental.53cd005",
   "description": "CLI for Verity quality gate service",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://verity.md",
@@ -13,6 +13,7 @@
   "files": [
     "bin/verity.js",
     "data/skills/",
+    "data/grammars/",
     "package.json",
     "README.md",
     "LICENSE",
@@ -31,8 +32,14 @@
   "devDependencies": {
     "@types/node": "^20",
     "esbuild": "^0.25.12",
+    "tree-sitter-go": "0.25.0",
+    "tree-sitter-java": "0.23.5",
+    "tree-sitter-javascript": "0.25.0",
+    "tree-sitter-python": "0.25.0",
+    "tree-sitter-typescript": "0.23.2",
     "tsx": "^4.21.0",
-    "typescript": "^5.4"
+    "typescript": "^5.4",
+    "web-tree-sitter": "0.27.0"
   },
   "dependencies": {
     "commander": "^12",