@codacy/verity-cli 0.31.1-experimental.02b82ff → 0.31.1-experimental.4cbb87c

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

@@ -1,6 +1,32 @@
 # /verity-setup — Configure Verity for this project
 
-You are setting up Verity, a quality gate for AI-generated code. Follow every step below. Do not skip steps or reorder them.
+You are finishing Verity's setup: the half that needs a model.
+
+**`verity init` already ran the deterministic half** — prerequisites, the skills,
+the Claude Code hooks (reconciled to the moments the user chose), `.gitignore`,
+the CLAUDE.md instructions, the optional GitHub login, and telemetry. It recorded
+the user's answers in `.verity/setup.json` and then handed off to you.
+
+So: **do not re-ask what init asked, and do not re-write what init wrote.** Wiring
+hooks or a `.gitignore` block here is how the two flows drifted apart before — the
+skill reconciled hooks init had just installed, silently removing them.
+
+⚠ **`verity init` NOW DERIVES THE STANDARD BY ITSELF**, so in most projects there
+is nothing here left to do — the languages, the tool selection, the curated
+pattern ids and `VERITY.md` are all lookups over this same catalogue, and the CLI
+does them in about two seconds (`verity standard synthesize`). Step 1 will tell
+you when that has already happened.
+
+**You are here for the part a lookup cannot produce:** project-specific patterns —
+"every route under `api/` uses the auth middleware", "RLS policies on all Supabase
+tables". `custom_patterns` is left EMPTY by the CLI precisely so a model can
+propose them from evidence rather than have them invented from a dependency list.
+
+**What is yours when there is no Standard at all** (Step 1 says so, or `--force`):
+1. Read the codebase and understand it (Step 2).
+2. Synthesize `.verity/standard.yaml` from what you found (Step 4).
+3. Write `.codacy/codacy.config.json` with curated, validated pattern ids (Step 5).
+4. Upload both, seed the knowledge base, write `VERITY.md` (Steps 7–8).
 
 **Reference files** (installed in this project at `.claude/skills/verity-setup/`):
 - `patterns-reference.yaml` — Research-backed patterns catalog (quality, security, language-specific)
@@ -8,17 +34,50 @@ You are setting up Verity, a quality gate for AI-generated code. Follow every st
 
 ---
 
-## Step 1: Check prerequisites
+## Step 1: Confirm the deterministic phase ran
 
-1. Verify `verity` CLI is installed: `which verity`
-   - If missing: tell the user to run the installer: `curl -fsSL https://raw.githubusercontent.com/codacy/verity/main/install.sh | bash` and stop.
-2. Verify `codacy-analysis` is installed: `which codacy-analysis`
-   - If missing: tell the user to run `npm install -g @codacy/analysis-cli` and stop.
-3. Check if `VERITY.md` already exists in the project root:
-   - If it exists and user didn't pass `--force`: say "Already configured. Run `/verity-setup --force` to reconfigure." and stop.
-   - If it exists with `--force`: continue (will overwrite).
-4. Get the git remote URL: `git remote get-url origin`
-   - If no remote: ask the user for a project identifier to use instead.
+```bash
+verity doctor --json
+```
+
+One read gives you prerequisites, which phase is done, the user's recorded
+answers, the hook wiring, and a `next` list. Branch on it:
+
+- **`phases.init.done` is false** → `verity init` has not run in this project.
+  Run it (it is idempotent, and it is what installed this skill):
+
+  ```bash
+  verity init --yes --no-setup
+  ```
+
+  `--yes` takes the recommended answer for every question — use it only because
+  you are already inside a Claude Code session and cannot ask on init's terminal.
+  Tell the user which defaults were taken and that `verity init` (run by hand in a
+  terminal) is where those choices are made. `--no-setup` stops init from trying
+  to launch a second Claude Code session on top of this one.
+- **`blocked` is true** → a required prerequisite is missing. Show the
+  `prerequisites[].remedy` lines and stop; nothing below can work.
+- **`artifacts.standard` is true and `phases.setup.done` is true** → the
+  project already has a Standard, derived or adopted. Your job is the part the CLI
+  leaves empty: propose 2–5 `custom_patterns` from the codebase, show them, and on
+  the user's agreement add them to `.verity/standard.yaml` and run
+  `verity standard push`. Do NOT rewrite the rest of the Standard — `standard push`
+  auto-versions, so a full re-synthesis lands as the version everybody is then
+  held to.
+- **`artifacts.standard` is true but `artifacts.analysisConfig` is false** → the
+  CLI derives this case too: `verity standard synthesize --config-only` rewrites
+  the config from the Standard already in place. Prefer that over doing it by hand.
+  ⚠ Do NOT suggest `--force` here — it REPLACES the Standard, and the team already
+  agreed that one. If you do it by hand, **Step 5 only**, then `verity config push`.
+- **`artifacts.verityMd` is true and the user did not pass `--force`** → already
+  configured. Say "Already configured. Run `/verity-setup --force` to
+  reconfigure." and stop.
+- A **warn**-status prerequisite (Claude Code, `@codacy/analysis-cli`) is not
+  fatal. Mention it once — a missing analysis CLI means no static findings — and
+  continue.
+
+Then get the git remote: `git remote get-url origin`. If there is none, ask the
+user for a project identifier to use instead.
 
 ---
 
@@ -60,74 +119,30 @@ Record all findings. You will use them in the next steps.
 
 ---
 
-## Step 3: Ask analysis intensity
-
-Use the **AskUserQuestion** tool to ask:
+## Step 3: Read the choices already made
 
-> **Analysis intensity:**
-> - **lightweight** — Critical security only. Fastest (~3s). Good for rapid iteration.
-> - **balanced** (recommended) — Security + quality. Good coverage (~8s).
-> - **thorough** — All tools, all rules. Most comprehensive (~15s).
->
-> Which mode? [balanced]
-
-Default to `balanced` if the user says "default" or doesn't specify a preference.
-
----
+From the `verity doctor --json` output in Step 1:
 
-## Step 3a: Choose analysis moments
+| Field | What it is | Where you use it |
+|---|---|---|
+| `answers.intensity` | `lightweight` \| `balanced` \| `thorough` | Step 4 (`process_constraints.analysis_mode`) and Step 5 (which tools/patterns) |
+| `answers.moments` | `stop`, `pre-commit`, `pre-push` | Nothing to do — the hooks are already wired to exactly this |
+| `answers.telemetry` | `enabled` \| `declined` \| `deferred` | Nothing to do — mention `deferred` once (see below) |
 
-This decides **when** Verity reviews code. Use the **AskUserQuestion** tool with
-`multiSelect: true`:
-
-> **When should Verity review your code? (select all that apply)**
-> - **On stop** (recommended) — after every agent turn. Fast feedback while you work.
-> - **Before commit** — gates `git commit`; reviews the **staged** diff and blocks the commit on FAIL.
-> - **Before push / PR** — gates `git push` and `gh pr create`; reviews the **to-be-pushed** commits and blocks on FAIL.
->
-> Default: **On stop**
-
-Notes to convey if asked:
-- The git-moment gates run an independent reviewer at the boundary the customer cares
-  about; a FAIL blocks the commit/push so the agent fixes issues before they land
-  (capped at 2 review cycles so you're never stuck).
-- These are **Claude Code** hooks (they fire when the agent runs `git commit`/`git push`),
-  not native git hooks — no `.git/hooks` files, no GitHub App.
-- "On stop" alone matches today's behavior. Many teams pick **Before commit + Before push**
-  and turn **On stop** off to review only at real boundaries.
-
-Map the selection to moment ids: On stop → `stop`, Before commit → `pre-commit`,
-Before push/PR → `pre-push`. Remember this list; you apply it in **Step 9**.
-
----
-
-## Step 3b: Ask about cost & usage telemetry (opt-in)
-
-Cost & usage observability is **opt-in** and **required** for the `/usage` dashboard — all
-cost and token data comes from Claude Code's own OpenTelemetry export, so with telemetry off
-the dashboard stays empty.
-
-First check the current state (so you don't re-ask if it's already on):
-
-```bash
-verity telemetry check
-```
+**Do not ask these again.** They were asked on init's terminal, and the machine
+state already reflects them.
 
-- If it reports **enabled**, don't re-ask — tell the user telemetry is already on and continue
-  (mention `verity telemetry uninstall` only if they want to turn it off).
-- If **disabled**, use the **AskUserQuestion** tool:
+If `answers.intensity` is `null` (a project set up before this file existed, or a
+failed write), that is the only case where you ask — a single question, defaulting
+to `balanced`:
 
-> **Enable Claude Code cost & usage telemetry for this project?**
-> Verity can show cost, tokens, a per-agent / per-session / model breakdown, and a fleet cost
-> tree — by receiving Claude Code's built-in **OpenTelemetry** export. This sends usage
-> **metrics and traces only** (model names, token counts, USD cost, agent types, session IDs).
-> It does **NOT** send your prompts, code, or tool input/output. Without it, the `/usage`
-> dashboard stays empty.
-> - **Yes** (recommended) — enable telemetry
-> - **No** — skip (you can enable later with `verity telemetry install`)
+> **Analysis intensity:** lightweight (critical security only, ~3s) ·
+> **balanced** (security + quality, ~8s) · thorough (all tools, all rules, ~15s)
 
-Remember the answer; you act on it in Step 7b (the token must exist first). **Declining is
-fine and reversible** — nothing is written, and the next `/verity-setup` re-offers it.
+If `answers.telemetry` is `deferred`, the user asked for cost & usage telemetry
+before a token existed. Say so once, and that `verity login` followed by
+`verity telemetry install` finishes it. Do not run either — logging in is the
+user's decision to make at a terminal.
 
 ---
 
@@ -149,9 +164,9 @@ Generate `.verity/standard.yaml` by filling in the template:
    - Existing code patterns (e.g., "RLS policies on all Supabase tables")
    - Each pattern needs: id, description, severity, rationale
 
-5. **process_constraints**: Set `analysis_mode` to the user's choice from Step 3. Keep `self_healing_limit: 2`. Leave the knowledge-system flags (`compound_enabled`, `memory_graph_enabled`, `memory_graph_budget_tokens`, `knowledge_injection_budget_tokens`, `finding_autosuppress_threshold`) and intent thresholds (`intent_fail_threshold`, `intent_warn_threshold`) at their template defaults — they're surfaced so users can tune later, not so you pick new values during setup.
+5. **process_constraints**: Set `analysis_mode` to `answers.intensity` from Step 3. Keep `self_healing_limit: 2`. Leave the knowledge-system flags (`compound_enabled`, `memory_graph_enabled`, `memory_graph_budget_tokens`, `knowledge_injection_budget_tokens`, `finding_autosuppress_threshold`) and intent thresholds (`intent_fail_threshold`, `intent_warn_threshold`) at their template defaults — they're surfaced so users can tune later, not so you pick new values during setup.
 
-6. **tool_configuration**: Based on detected languages + mode, select tools from the patterns reference `tool_recommendations` section. For existing tool configs, set the config_file path.
+6. **tool_configuration**: Based on detected languages + the intensity from Step 3, select tools from the patterns reference `tool_recommendations` section. For existing tool configs, set the config_file path.
 
 Write the file to `.verity/standard.yaml`. Show the user a summary:
 > **Standard synthesized:**
@@ -480,57 +495,47 @@ binary — Semgrep needs Opengrep installed separately, and at `--log-level erro
 
 ---
 
-## Step 6: Verify authentication
+## Step 6: Check authentication
 
-Login now happens in `verity init` (an optional, skippable step), **not** here.
-This step only checks whether the user authenticated during init, and branches
-the rest of setup accordingly.
-
-**If the user asks what signing in does or why it matters, tell them:**
-- It confirms they have **write access to this repository** — the GitHub token is
-  used **once** to verify that, then discarded. Verity never stores it.
-- It does **not** give Verity access to their code. Code checked by the gate is
-  analyzed **in memory and discarded** — Verity never stores their code.
-- It is **required to store and access run history** for the repo (past results,
-  trends, and shareable reports).
-- Skipping keeps Verity fully **local-only**: the gate still runs and shows
-  findings, but nothing is uploaded.
+Login happens in `verity init` (an optional, skippable step), **not** here. This
+step only checks whether it happened, and branches the rest of setup.
 
 ```bash
 verity auth verify
 ```
 
-- **Token valid** (prints the project name): The user authenticated during
-  `verity init`. Continue to Step 7 — the Standard, config, and knowledge base
-  will upload.
-- **Not authenticated / no token**: The user skipped login in `verity init` (or
-  lacks write access). Verity runs in **local-only mode** — the gate still runs on
-  every stop and surfaces static findings, but nothing uploads and no
-  history/org/repo data is stored. **Skip Steps 7 and 7b** (they require a token)
-  and continue to Step 8. Tell the user they can authenticate anytime to unlock
-  deep review, history, and shareable reports by running:
+- **Token valid** (prints the project name): continue to Step 7 — the Standard,
+  config, and knowledge base will upload.
+- **Not authenticated / no token**: the user skipped login in `verity init` (or
+  lacks write access). Verity runs in **local-only mode** — the gate still runs
+  and surfaces findings, but nothing uploads and no history is stored. **Skip
+  Step 7** (it requires a token) and continue to Step 8. Tell them they can
+  authenticate anytime with:
 
   ```bash
   verity login         # one GitHub login covers every repo you can write to
-  # or: verity init    # re-runs init; offers the same auth prompt
   ```
 
-  Login is **provider-gated** (GitHub today): the CLI runs a GitHub App **device
-  flow** ("open https://github.com/login/device and enter code WXYZ-1234"),
-  proving the user has **write access** before the service issues a token. The
-  GitHub App requests only read-only permissions (Metadata + Email addresses);
-  the provider token is used once server-side to sweep the repositories the user
-  can write to, and is never persisted.
+  Then re-run `/verity-setup --force` to upload what was generated locally.
 
-  **One login covers every repository** the user can write to, not just this one.
-  Re-running `verity login` is also how access to newly-granted repos is picked
-  up, and how an expired verification is restored. If login reports this
-  repository is **not covered**, the Verity GitHub App has not been granted
-  access to it — grant it, then re-run `verity login`.
-
-When authenticated, the user's `token` and `service_url` are stored in the single
-global credentials file `~/.verity/credentials` — nothing secret is written into
-the repo. All subsequent `verity` upload commands work.
+**If the user asks what signing in does or why it matters:**
+- It confirms they have **write access to this repository** — the GitHub token is
+  used **once** for that check, then discarded. Verity never stores it.
+- It does **not** give Verity access to their code. Code checked by the gate is
+  analyzed **in memory and discarded**.
+- It is **required to store and access run history** (past results, trends,
+  shareable reports).
+- Login is **provider-gated** (GitHub today) via a GitHub App **device flow**
+  ("open https://github.com/login/device and enter code WXYZ-1234"). The App
+  requests only read-only permissions (Metadata + Email addresses).
+- **One login covers every repository** the user can write to. Re-running
+  `verity login` is also how newly-granted repos are picked up and how an expired
+  verification is restored. If login reports this repository is **not covered**,
+  the Verity GitHub App has not been granted access to it — grant it, then re-run
+  `verity login`.
+
+The token and service_url live in the single global file `~/.verity/credentials`
+— nothing secret is written into the repo.
 
 ---
 
@@ -570,31 +575,6 @@ This derives a small set of descriptive memory nodes from what you already analy
 
 ---
 
-## Step 7b: Enable telemetry (only if the user opted in at Step 3b)
-
-> **Skip this step if the user is not authenticated** (local-only mode) — telemetry
-> export requires the token. Note that `/usage` stays empty until they authenticate
-> and run `verity telemetry install`.
-
-If — and only if — the user said **Yes** in Step 3b, enable the Claude Code telemetry export
-now (the token from Step 6 must already exist):
-
-```bash
-verity telemetry install
-```
-
-This writes the `OTEL_*` env block plus an `otelHeadersHelper` to `.claude/settings.local.json`
-and points Claude Code's OpenTelemetry exporter at Verity's OTLP endpoint. No token is written to
-the file — the helper (`verity telemetry headers`) resolves the project token from
-`~/.verity/credentials` at session start, so the secret never lands in the repo. Tell the user it
-takes effect on their **next** Claude Code session, that first metrics appear within ~60s of
-activity, and point them at `/usage`.
-
-If the user declined, skip this step and note that `/usage` will stay empty until they run
-`verity telemetry install`.
-
----
-
 ## Step 8: Generate VERITY.md file
 
 Create `VERITY.md` at the project root with this content:
@@ -633,125 +613,7 @@ Every time the coding agent stops, the Verity hook:
 
 ---
 
-## Step 8b: Add knowledge base pointer and reflection instructions to CLAUDE.md
-
-If `CLAUDE.md` exists (or `.claude/CLAUDE.md`), append these two blocks. If it doesn't exist, create it with these blocks. Do NOT overwrite existing content — append only.
-
-```markdown
-
-## Project Knowledge Base
-> Read `.verity/memory/index.md` for accumulated project context, decisions, and conventions.
-
-## Post-task reflection
-When a task is complete (you've created a PR, the user says "done" or "ship it",
-or the work is clearly finished), **draft the reflection yourself first** — 1–3
-concrete things worth remembering (a decision, a gotcha, or a pattern), each
-cited with the files / PR / commands / error-signatures it came from. Skip
-entirely if nothing non-obvious happened.
-
-Then, depending on how the session is running:
-
-- **Interactive** (a person is at the keyboard): show your draft and ask one
-  question before recording —
-
-  > "Here's my reflection draft for the project memory: \<draft\>. Anything to
-  > confirm, correct, or add before I record it? (Say 'skip' to drop it.)"
-
-  Record the final text (with their corrections) via
-  `verity reflect --user-input "<final reflection>" --kind <kind>`. If they say
-  "skip", do not record.
-
-- **Autonomous** (headless / CI / cron, or `VERITY_AUTONOMOUS=1`): record your
-  draft directly, never blocking —
-  `verity reflect --user-input "<your draft>" --kind <kind> --autonomous`.
-```
-
-These blocks enable two capabilities:
-1. **Knowledge Base pointer** — agents can browse `.verity/memory/` for project context on demand (KNOWLEDGE-SYSTEM §8.2 Path B)
-2. **Post-task reflection** — the compound moment where the agent drafts a cited reflection and the user confirms/corrects it (interactive) or it's auto-recorded (autonomous), entering the knowledge base (KNOWLEDGE-SYSTEM §9.3)
-
----
-
-## Step 9: Wire the selected moments
-
-Apply the moments the user chose in **Step 3a**. Pass the comma-separated moment ids
-(always include the always-on intent hook automatically):
-
-```bash
-# Example: user chose On stop + Before commit + Before push
-verity hooks install --moments stop,pre-commit,pre-push
-```
-
-`--moments` reconciles Verity's own hooks in `.claude/settings.json` to **exactly**
-the selection (adding the git-moment gate, removing the Stop hook if unselected),
-while preserving every non-Verity hook. The `verity intent capture` hook is always
-installed. If the user picked only `stop` (the default), pass `--moments stop`.
-
-Then verify:
-
-```bash
-verity hooks check
-```
-
-Expected output (for `stop,pre-commit,pre-push`):
-```
-[verity] Stop hook (verity analyze): installed
-[verity] Intent hook (verity intent capture): installed
-[verity] Git-moment gate (verity guard): installed [commit, push]
-```
-
-The git-moment gate is a single `PreToolUse(Bash)` hook (`verity guard`) that
-intercepts `git commit` / `git push` / `gh pr create` and reviews the staged or
-to-be-pushed diff before it lands.
-
----
-
-## Step 10: Update .gitignore
-
-Add these entries to `.gitignore` (create it if it doesn't exist, append if it does):
-
-```
-# Verity — machine-local state. Everything in .verity/ is ignored EXCEPT the
-# shared standard and the knowledge graph, which are meant to be committed.
-.verity/*
-!.verity/standard.yaml
-!.verity/memory/
-.verity/memory/log.md
-.claude/settings.local.json
-```
-
-This is a whitelist on purpose: `.verity/` accumulates state files over time
-(`.snapshot/` holds byte-for-byte copies of analyzed files — including any
-secret the gate just flagged — plus `.cache/`, `.logs/`, `.baseline`,
-`.task-context`, session-suffixed `.last-analysis.*` files, and whatever comes
-next). Enumerating them one by one is how `.snapshot/` ended up committed in a
-real repo; ignoring everything and re-including the two shared artifacts means
-a future state file can never repeat that.
-
-**If the repo previously committed Verity state** (check with
-`git ls-files .verity`), untrack everything except the shared artifacts once:
-
-```bash
-git rm -r --cached .verity
-git add .verity/standard.yaml .verity/memory
-```
-
-`.claude/settings.local.json` is machine-local Claude Code config (telemetry endpoint + an
-`otelHeadersHelper` reference — no token). `verity telemetry install` adds this entry
-automatically.
-
-Do NOT gitignore `.verity/standard.yaml` or `VERITY.md` — those should be committed.
-
-**Commit the knowledge graph, but not its log.** The nodes under `.verity/memory/<domain>/` and `.verity/memory/index.md` are durable project knowledge meant to be committed and reviewed. But `.verity/memory/log.md` is an append-only, per-run timestamped activity log — it churns on every analysis and carries no reviewable content, so it is gitignored above. If a project already committed it, untrack it once with `git rm --cached .verity/memory/log.md`.
-
-**No secrets live in the repo anymore.** The project token is stored only in the single global
-file `~/.verity/credentials` (outside the repo, keyed by git remote), so there is no
-`.verity/credentials` to ignore. If an older install left one behind, the CLI folds it into the
-global store and removes it automatically on the next `verity` command.
-
----
-
-## Step 10b: Offer a `.verityignore` (optional)
+## Step 9: Offer a `.verityignore` (optional)
 
 Only if the codebase analysis in Step 2 found committed generated output —
 `dist/`, `build/`, vendored bundles, generated API clients, large fixture
@@ -793,32 +655,35 @@ Two things to tell the user, because both surprise people:
 Excluded files are still named in every run's coverage ledger, and the share of
 changed files they cover is reported — an ignore file is never silent.
 
-## Step 11: Show summary
+---
 
-Print a complete summary:
+## Step 10: Show summary
+
+Report both halves, so the user sees one flow rather than two:
 
 ```
-=== Verity Setup Complete ===
+=== Verity setup complete ===
 
 Project:      ${PROJECT_NAME}
 Languages:    ${LANGUAGES}
 Frameworks:   ${FRAMEWORKS}
 Architecture: ${ARCHITECTURE}
-Mode:         ${MODE}
-
-Standard:     v1 (4 quality, 7 security, N custom patterns)
-Tools:        ${TOOL_LIST}
-Service:      registered (project_id: ${PROJECT_ID})
-Hooks:        installed (verity analyze + verity intent capture)
-Telemetry:    ${TELEMETRY_STATUS}   (enabled → cost+usage at /usage, or disabled)
-
-Files created:
-  .verity/standard.yaml        — Quality standard
-  .codacy/codacy.config.json   — Analysis CLI config
-  VERITY.md                    — Project quality overview
-  .claude/settings.json        — Hook configuration (verified)
-  .claude/settings.local.json  — Telemetry env (only if enabled; gitignored)
-  .gitignore                   — Updated with Verity entries
-
-Next: You should now be seeing the first analysis happening below. The hook will fire automatically every time your agent stops working on something.
+Intensity:    ${MODE}            (chosen during verity init)
+
+This step wrote:
+  .verity/standard.yaml        — Standard v1 (4 quality, 7 security, N custom patterns)
+  .codacy/codacy.config.json   — ${TOOL_LIST}, curated patterns, validated
+  VERITY.md                    — project quality overview
+  .verityignore                — only if you created one in Step 9
+
+Already in place from verity init:
+  Hooks:      ${MOMENTS}        (+ intent, baseline, compact, session-end)
+  Telemetry:  ${TELEMETRY_STATUS}
+  Uploads:    ${authenticated ? "on — runs & memory sync to Verity" : "off — local-only mode"}
+
+Next: the gate now runs at the moments you chose. You should see the first
+analysis below.
 ```
+
+Run `verity doctor` if anything above looks wrong — it reports the real state of
+every part of the install.