@codacy/verity-cli 0.33.3-experimental.52f1656 → 0.33.3-experimental.5a3f573

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

@@ -1,46 +1,62 @@
 ---
 description: >-
-  Set Verity up in this project: ask the two setup questions, run the deterministic
-  install, and repair a project the Claude Code plugin has just been added to. Use
-  right after installing the Verity plugin, or when Verity says this project is not
-  set up.
+  Set Verity up in this project: ask the setup questions in the session, run the
+  deterministic install with those answers, sign in, and repair a project the Claude
+  Code plugin has just been added to. Use right after installing the Verity plugin,
+  or when Verity says this project is not set up.
 disable-model-invocation: true
 ---
 # /verity-init — set Verity up in this project
 
-You are running the setup a plugin install cannot do for itself.
+You are running, inside this session, the same setup `verity init` runs at a
+terminal: the same questions, the same install, the same sign-in. The only
+difference is who asks. At a terminal the CLI prompts; here **you** ask, and pass
+the answers down as flags.
 
 **Why this skill exists.** Claude Code has no post-install hook and a plugin
 cannot invoke a skill, so installing Verity repairs nothing: it cannot remove a
 project's superseded skills, stand down duplicate hooks, or derive a Standard.
 All of that needs a command someone runs — this one.
 
-**`verity init` prompts on a terminal, and you are not one.** That is the whole
-problem this skill solves. Left to itself the CLI would take `--yes` and silently
-choose **stop-only** review — no pre-commit gate, no pre-push gate — for every
-plugin user, which is exactly the outcome we treat as a serious bug when it
-happens by accident. So **you** ask, in the session, where the user actually is.
+**`verity init` prompts on a terminal, and you are not one.** Run with `--yes`
+alone it takes the unattended answer to every question: stop-only review (no
+commit or push gate), no telemetry, no sign-in, nothing untracked. Every one of
+those is a decision that belongs to the user, so every one is asked here.
+
+Run every `verity` command below the way this session's context says (the
+plugin's own copy), not with plain `verity`, whenever the context names one.
 
 ---
 
-## Step 0: Check the CLI before asking anything
+## Step 0: Read where the project stands — before asking anything
+
+```bash
+verity doctor --json
+```
 
-If this session's context says the `verity` on PATH is a different version from
-the plugin's, **tell the user that first**, in one line, before the questions —
-with the `npm install -g` command the context gives. Finding out after they have
-answered is the failure this step exists to prevent: an older CLI cannot take the
-answers.
+From that one report:
 
-Then run every command below the way the context says (the plugin's own copy),
-not with plain `verity`.
+- **`blocked` is true** → show the `prerequisites[].remedy` lines and stop.
+  Nothing below can work.
+- **`hooks.versions.skew` is set** → tell the user first, in one line, with
+  `hooks.versions.skew.remedy`. An older CLI cannot take the answers, so they
+  should hear it now, not after answering.
+- **`answers`** holds what a previous run recorded (`intensity`, `moments`,
+  `telemetry`). On a re-run those are the defaults — pre-select them. The shipped
+  defaults are only for a project with nothing recorded.
+- **`telemetry.enabled`** decides whether the telemetry question is asked at all.
+- **`memory.trackedFiles > 0` and `memory.optedOut` is false** → the graph
+  question applies.
+- **`trackedState.files > 0`** → the committed-state question applies.
 
-## Step 1: Ask both questions in ONE prompt
+## Step 1: Ask — once, in one prompt
 
-Use `AskUserQuestion` with **both** questions in a single call. Do not ask them
-one at a time, and do not ask them in prose — this is the only interruption the
-setup gets, so spend it once.
+Use `AskUserQuestion` with every question that applies **in a single call**, in
+this order. It takes at most four; if more apply, put the rest in ONE follow-up
+call. Do not ask one at a time, and do not ask in prose unless `AskUserQuestion`
+is unavailable (then ask in prose and **wait** — never choose for the user).
 
-**Question 1 — "When should Verity review your code?"** (multi-select)
+**1 — "When should Verity review your code?"** (multi-select, always asked)
 
 | Option | Description |
 |---|---|
@@ -48,12 +64,12 @@ setup gets, so spend it once.
 | `Before commit` | Reviews the staged diff and blocks the commit on a failing review. |
 | `Before push / PR` | Reviews the commits about to be pushed and blocks on a failing review. |
 
-Pre-select **After every turn**, and do not call it "recommended": under the
-plugin it runs whatever the answer, and a user who unticks it should not find
-that out afterwards. Say plainly in the question text that choosing only the
-first means **git commits and pushes are not gated**.
+Pre-select the recorded moments, or **After every turn** on a first run, and do
+not call it "recommended": under the plugin it runs whatever the answer. Say
+plainly in the question text that choosing only the first means **git commits
+and pushes are not gated**.
 
-**Question 2 — "How deeply should Verity review?"** (single-select)
+**2 — "How deeply should Verity review?"** (single-select, always asked)
 
 | Option | Description |
 |---|---|
@@ -61,75 +77,157 @@ first means **git commits and pushes are not gated**.
 | `Lightweight` | Critical security only, about 3s. |
 | `Thorough` | All tools, all rules, about 15s. |
 
+**3 — "Send cost & usage telemetry to Verity?"** (single-select; **only when
+`telemetry.enabled` is false**)
+
+| Option | Description |
+|---|---|
+| `Yes, enable it` | Powers the /usage dashboard. Sends Claude Code's own OpenTelemetry metrics and traces: model names, token counts, cost, session ids. Not your prompts, code, or tool input/output. |
+| `No` | /usage stays empty. Enable later with `verity telemetry install`. |
+
+**4 — "Sign in to Verity now?"** (single-select, always asked)
+
+| Option | Description |
+|---|---|
+| `Sign in now (recommended)` | One GitHub login covers every repository you can write to, for 90 days. Needed for run history, cloud memory and the dashboard. If you are already signed in this just confirms it. |
+| `Skip for now` | The gate still reviews your code locally; nothing is saved. Sign in later with `/verity-init` or `verity login`. |
+
+If asked, explain: the GitHub token is used once to check which repositories they
+can write to, then discarded; signing in does not give Verity access to their
+code, which is analyzed in memory and never stored.
+
+**5 — "Stop tracking Verity's knowledge graph in git?"** (only when the graph
+question applies; say how many files)
+
+| Option | Description |
+|---|---|
+| `Yes, untrack it (recommended)` | Files stay on disk; their removal from the index is staged for you to commit. Generated notes stop appearing in every diff and PR. |
+| `No, not now` | Nothing changes. `verity memory track` records it as deliberate. |
+
+**6 — "Untrack committed Verity state?"** (only when `trackedState.files > 0`;
+say how many files)
+
+| Option | Description |
+|---|---|
+| `Yes, untrack it (recommended)` | Machine-local files that should never have been committed — they can include copies of flagged secrets. Files stay on disk; the removal is staged. |
+| `No, not now` | Nothing changes. |
+
 ## Step 2: Run the install with those answers
 
-Map the answers to flags and run it — one command, no prompts, nothing silently
-defaulted:
+One command, no prompts, nothing silently defaulted:
 
 ```bash
-verity init --yes --no-setup --moments <stop[,pre-commit][,pre-push]> --intensity <balanced|lightweight|thorough>
+verity init --yes --no-setup \
+  --moments <stop[,pre-commit][,pre-push] | none> \
+  --intensity <balanced|lightweight|thorough> \
+  [--telemetry on|off] [--untrack-memory] [--untrack-state]
 ```
 
-`--moments none` is the deliberate way to gate nothing; an unrecognised value is
-refused rather than dropped, so a typo cannot quietly remove a gate.
+- Pass `--telemetry` only when question 3 was asked. Omitting it leaves the
+  recorded choice alone.
+- Pass `--untrack-memory` / `--untrack-state` only on a yes.
+- Pass `stop` only if they ticked it. Under the plugin the Stop review runs either
+  way and `verity init` says so.
+- An unrecognised value is refused rather than dropped, so a typo cannot quietly
+  remove a gate. If init exits non-zero, show its error and stop.
+
+This is idempotent and does the whole install: removes the project's own
+`.claude/skills/verity-*` copies that the plugin supersedes, stands down duplicate
+`.claude/settings.json` hooks, adopts the team's Standard from the service or
+derives one from the codebase, heals a stale analysis config, and records the
+plugin version — which is what stops Verity asking at every session start.
 
-Pass `stop` only if they ticked it. Under the plugin the Stop review runs either
-way and `verity init` says so; recording their real answer is what lets it be
-honoured once Stop can be turned off.
+Init runs before sign-in, so on a first run it says it skipped authentication and
+that telemetry needs a token. That is expected — Step 3 handles both. Do not
+repeat those lines to the user as problems.
 
-This is idempotent and does the whole job: removes the project's own
-`.claude/skills/verity-*` copies that the plugin supersedes (they are why the
-slash-command list shows every skill twice), stands down duplicate
-`.claude/settings.json` hooks so a turn is reviewed once, derives the Standard
-and the analysis config if there is none, heals a stale one, and records the
-plugin version — which is what stops Verity asking at every session start.
+## Step 3: Sign in — here, in two halves
+
+Skip this step if they chose **Skip for now**; say the gate runs locally and how
+to sign in later.
+
+`verity login` on its own prints a code and then blocks until it is approved, and
+you would only see the code after it ended. So it is split:
+
+```bash
+verity login --start
+```
+
+It prints one JSON object on stdout:
+
+- **`"status": "logged_in"`** → they already are. Say so and go to Step 4.
+- **`"status": "pending"`** → show the user `verification_uri` and `user_code`
+  exactly as given, and ask them to approve it in their browser and tell you when
+  they have. Wait for their reply. Do not run anything in the meantime.
+- **`"status": "failed"`** → show the error, and tell them to run `verity login`
+  in their own terminal later. Go to Step 4.
+
+When they say it is approved (or ask you to check):
 
-Report what it removed. Those skill directories are usually committed, so the
-deletions will show in `git status` and are the user's to commit.
+```bash
+verity login --finish
+```
+
+Give the tool call at least a 150-second timeout; it waits up to 100 seconds.
+
+- **exit 0, `"status": "logged_in"`** → report the lines it printed about the
+  account and whether this repository is covered, word for word where it names a
+  link to grant the Verity GitHub App.
+- **exit 2, `"status": "pending"`** → not approved yet. Show the code again, wait
+  for them, and run `--finish` again.
+- **exit 1** → `denied`, `expired`, `service_changed`, `no_pending` or `failed`.
+  Show the error. For `expired` or `no_pending`, offer to start again with
+  `--start`.
+
+If they change their mind while a code is pending, run `verity login --cancel`.
 
-## Step 3: Tell the user to sign in — in their own terminal
+⚠ Never run plain `verity login` from here, and never tell a user whose Step 0
+reported a version skew to run it in a terminal until they have fixed the skew —
+the old global CLI can sign the machine in to a different server, and the plugin
+follows that sign-in.
 
-**Do not run `verity login` yourself.** It is a GitHub device flow: it prints a
-code, waits for the user to approve it in a browser, and blocks until they do.
-Started from a tool call it just hangs, and the user never sees the code.
+## Step 4: Finish telemetry, if it waited on sign-in
 
-Say this, and stop:
+If they said yes to telemetry and init reported it needs a token, and Step 3
+signed them in:
 
-> Verity is set up. One more step, in your own terminal — not here:
->
-> ```
-> verity login
-> ```
->
-> It prints a code and a link; approve it in your browser. One login covers every
-> repository you can write to, for 90 days. Without it the gate still reviews
-> your code — it just records nothing, so there is no history, no cloud memory
-> and no dashboard.
+```bash
+verity telemetry install
+```
+
+It takes effect on their next Claude Code session.
 
-If `verity status` already reports an account, skip this step and say so.
+## Step 5: Report what happened
 
-If Step 0 found a version mismatch, the `verity` in their terminal is the old
-global one, not the plugin's: tell them to update it first (the `npm install -g`
-command from Step 0), then log in. An older or experimental build can sign the
-machine in to a different server, and the plugin follows that sign-in.
+```bash
+verity doctor --json
+```
 
-## Step 4: Offer the part a lookup cannot produce
+Summarise from this report, not from memory of what you ran:
 
-The Standard `init` derives covers the research-backed patterns for the
-languages and tools it found. What it deliberately leaves empty is
-`custom_patterns` — rules like *"every route under `api/` uses the auth
-middleware"*, which need something to read the code for intent.
+- what init removed (superseded skills, duplicate hooks) — those skill
+  directories are usually committed, so the deletions show in `git status` and
+  are the user's to commit;
+- whether the Standard was **adopted** from the service or **derived** from the
+  codebase (init's output says which);
+- the moments and intensity now in effect, and who wires the hooks
+  (`hooks.source`);
+- anything untracked, and that the staged removal is theirs to commit;
+- sign-in and telemetry state;
+- each line of `next`, if any.
 
-Offer `/verity-setup` for that, and say it is optional: the gate is already
-running.
+Then offer `/verity-setup` for the part a lookup cannot produce — project-specific
+`custom_patterns` such as *"every route under `api/` uses the auth middleware"* —
+and say it is optional: the gate is already running.
 
 ---
 
 ## What NOT to do here
 
 - **Do not wire hooks or edit `.gitignore` yourself.** `verity init` owns that.
-  Doing it here is how the two flows drifted apart before — the skill reconciled
-  hooks init had just installed and silently removed them.
-- **Do not synthesize a Standard by hand.** The CLI derives it in about two
-  seconds from the same catalogue you would be reading.
-- **Do not run `verity login`.** Step 3.
+  Doing it here is how the two flows drifted apart before.
+- **Do not synthesize a Standard by hand.** The CLI derives it in seconds from
+  the same catalogue you would be reading.
+- **Do not answer a question for the user**, including by leaving a flag off
+  because it seemed obvious. An omitted question is an unattended answer.
+- **Do not run plain `verity login`.** Step 3.

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.