@codacy/verity-cli 0.20.0

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

@@ -0,0 +1,214 @@
+# /verity-analyze — Run Verity analysis on demand
+
+You are running an on-demand Verity analysis. This is like a "second opinion" — the user (or you) can invoke it at any point to get a quality and security review with rich context.
+
+**Usage:**
+- `/verity-analyze` — Curate files, write intent, select specs autonomously (deep review)
+- `/verity-analyze src/api/routes.ts src/db.ts` — Analyze specific files (quick check)
+- `/verity-analyze src/api/` — Analyze a directory and related files
+- `/verity-analyze --full` — Sample the full codebase (20 most recently modified files)
+- `/verity-analyze --intent "Implementing OAuth2 PKCE flow per spec/AUTH.md"` — User provides intent
+
+---
+
+## Step 1: Check configuration
+
+1. Verify `.verity/standard.yaml` exists. If not: "Run `/verity-setup` first."
+2. Verify `verity` CLI is available: `which verity`. If not: "Re-run the Verity installer: `curl -fsSL https://raw.githubusercontent.com/codacy/verity/main/install.sh | bash`"
+3. Run `verity auth verify` to check token is valid. If it fails: "Verity not configured. Run `/verity-setup` first."
+
+---
+
+## Step 2: Determine files to analyze
+
+### Quick mode (specific files or `--full`)
+
+**Specific files** (paths or directories provided):
+- Use the provided file paths directly. If a directory is given, include all analyzable files under it.
+- Verify each file exists.
+
+**`--full` flag** (full codebase sample):
+```bash
+FILES=$(git ls-files | grep -E '\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|rb|rs|c|cpp|h|hpp|cs|php)$')
+```
+If more than 20 files, select the 20 most recently modified:
+```bash
+echo "$FILES" | xargs ls -t | head -20
+```
+
+In quick mode, skip Steps 3 and 4 — go straight to Step 5.
+
+### Deep mode (no arguments, or directory hints)
+
+When no specific files are given, curate a comprehensive review scope:
+
+#### 2a. Start with changed files
+
+```bash
+CHANGED=$(git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null)
+CHANGED_CODE=$(echo "$CHANGED" | sort -u | grep -E '\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt|rb|rs|c|cpp|h|hpp|cs|php)$')
+```
+
+Also check if the agent just committed (clean tree but recent HEAD):
+```bash
+# If working tree is clean, check what the last commit changed
+git diff --name-only HEAD~1..HEAD 2>/dev/null
+```
+
+If the user provided directory hints (e.g., `/verity-analyze src/api/`), also include all files under those directories.
+
+#### 2b. Add related files
+
+For each changed file, identify and add:
+
+1. **Direct dependencies** — files that the changed file imports. Read the import/require statements and resolve the paths.
+2. **Reverse dependencies** — files that import the changed file. Grep for the module name across the codebase.
+3. **Type/interface files** — shared type definitions, interfaces, or schemas referenced by the changes.
+4. **Test files** — corresponding test files for changed modules (e.g., `foo.test.ts` for `foo.ts`, `test_foo.py` for `foo.py`).
+
+#### 2c. Prioritize and cap
+
+Rank files by relevance:
+1. Changed files (always included first)
+2. Direct dependencies that define interfaces/types being used
+3. Test files for changed code
+4. Reverse dependencies (consumers that might break)
+
+**Cap at 20 files total.** If you need to cut, drop reverse dependencies first, then tests.
+
+#### 2d. Track changed vs context
+
+Keep two lists:
+- **`changed_files`** — the files that were actually modified (git dirty or recently committed)
+- **`all_files`** — all files to include in the analysis (changed + context)
+
+If no analyzable files found: "No analyzable files found."
+
+---
+
+## Step 3: Write the intent description
+
+Synthesize the conversation context into a clear intent description. This is NOT the raw user prompt — it's your understanding of what the work is trying to achieve.
+
+**Template:**
+
+```
+I am [adding/modifying/fixing/refactoring] [feature/component name].
+
+Goal: [What the user asked for, or the problem being solved.]
+
+Approach: [Key architectural decisions. What patterns are being used?]
+
+Trade-offs: [Anything you chose deliberately that could be questioned.]
+
+Review focus: [Specific concerns you want the reviewer to evaluate.]
+```
+
+**Guidelines:**
+- Cap at 2000 characters
+- Be specific — "adding JWT auth with RS256 to /api/users" not "adding authentication"
+- Include trade-offs and areas of uncertainty — the reviewer will focus there
+- If the user provided `--intent`, use it as the base and augment with your understanding
+- Skip this step entirely in quick mode (specific files or --full)
+
+---
+
+## Step 4: Select relevant specs
+
+Identify spec/documentation files that provide context:
+
+- Specs referenced in the user's request
+- Specs that define interfaces or APIs being implemented
+- Architecture docs relevant to the area being changed
+
+**Read each spec file and prepare for inclusion.** Limits: max 10 files, 10KB per file, 30KB total.
+
+Common spec locations to check:
+- `spec/*.md`, `docs/*.md`
+- `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`
+
+If no specs are relevant, skip this step.
+
+---
+
+## Step 5: Run the analysis
+
+Use the `verity review` command with all the context you gathered:
+
+```bash
+verity review \
+  --files "src/auth/pkce.ts,src/auth/callback.ts,src/auth/types.ts,src/middleware/auth.ts" \
+  --changed "src/auth/pkce.ts,src/auth/callback.ts" \
+  --intent "I am adding OAuth2 PKCE authentication flow..." \
+  --specs "spec/AUTH.md,CLAUDE.md"
+```
+
+**Arguments:**
+- `--files` (required): Comma-separated list of ALL files to include (changed + context)
+- `--changed` (optional): Comma-separated list of actually-modified files (subset of --files). If omitted, all files are treated as changed.
+- `--intent` (optional): Your synthesized intent description. Quote it.
+- `--specs` (optional): Comma-separated list of spec file paths to include.
+
+The CLI handles static analysis, file reading with size limits, payload construction, and the API call.
+
+---
+
+## Step 6: Display results
+
+Parse the JSON response and format clearly:
+
+```
+=== Verity Analysis ===
+Gate Decision: WARN
+Quality: 7.5/10  |  Security: 8.0/10  |  Overall: 7.8/10
+Trend: stable
+
+--- Assessment ---
+[narrative from assessment.narrative]
+
+--- Findings (2) ---
+
+[HIGH] Service Role Client for Non-Admin Operations
+  File: supabase/functions/webhook/index.ts:25
+  Pattern: access-control-checks (CWE-639)
+  Fix: Limit SELECT fields to only what's needed for the notification.
+
+[MEDIUM] File Complexity Exceeds Threshold
+  File: supabase/functions/webhook/index.ts:1
+  Pattern: comprehensibility
+  Fix: Refactor into separate handler files per event type.
+
+--- Intent Alignment ---
+Score: 9/10 (aligned)
+Goal: "Add webhook handlers for Stripe events"
+Implementation matches intent. No gaps detected.
+
+--- Quality Dimensions ---
+Comprehensibility: 6.5/10 — webhook file is too large
+Modularity: 7.0/10 — good separation except webhook handler
+Type Safety: 9.0/10 — strict TypeScript throughout
+Test Adequacy: 5.0/10 — missing webhook handler tests
+
+--- Pending Items ---
+1. [HIGH] Add tests for webhook event handlers
+2. [MEDIUM] Refactor webhook into handler modules
+
+View full report: https://verity.md/runs/run-20260327-...?token=verityview_...
+```
+
+---
+
+## Step 7: Offer to fix
+
+- **If FAIL or findings exist**: "The analysis found N issues. Would you like me to fix them?" If yes, apply fixes from findings, then re-run (iteration 2 max). If iteration 2 still fails, report remaining issues for human review.
+- **If WARN**: "Non-blocking issues found. Would you like me to address them?"
+- **If PASS**: "Code meets the Standard. No issues found."
+
+---
+
+## Important notes
+
+- This does NOT replace the automatic stop hook. The hook still fires on every agent stop.
+- Runs are tagged with `trigger: "review"` in the database.
+- Size limits: 20 files max, 50KB per file, 200KB total code, 2000 char intent, 30KB specs.
+- If the service is unreachable, static analysis still runs locally.

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

@@ -0,0 +1,39 @@
+# /verity-feedback — Send feedback
+
+## General feedback
+
+If the user provided a message (e.g., `/verity-feedback the analysis is too slow`), use their **exact words** as the message. Do NOT rephrase, expand, add context, or editorialize. Send exactly what they typed, nothing more.
+
+If they just typed `/verity-feedback` with no message, ask: "What feedback would you like to share?"
+
+```bash
+verity feedback message "<their exact message>"
+```
+
+On success: "Thanks, feedback sent!"
+On error: "Couldn't send feedback right now. Your message: [repeat it so it's not lost]."
+
+## Per-finding feedback
+
+If the user wants to mark a specific finding (e.g., a false positive from a recent analysis run), use the finding sub-command.
+
+Ask for the required info if not provided:
+- **run-id**: from the most recent analysis run (check `verity status` or the run output)
+- **pattern-id**: the Standard pattern that produced the finding (e.g., `no-hardcoded-secrets`, `file_length`)
+- **action**: one of `false_positive`, `acknowledged`, `will_fix_later`, `wrong_severity`, `useful`
+
+```bash
+verity feedback finding <run-id> <pattern-id> <action> "optional note"
+```
+
+Optional flags:
+- `--file <path>` — the file the finding applies to
+- `--line <n>` — the line number
+
+Example: marking a test file's fake JWT as a false positive:
+```bash
+verity feedback finding run-20260420-abc1 no-hardcoded-secrets false_positive "Fake JWT used in tests" --file src/auth/tokens.test.ts --line 42
+```
+
+On success: report whether auto-suppression is now active (requires ≥2 independent dismissals for the same pattern+file pattern).
+On error: show the error message.

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

@@ -0,0 +1,87 @@
+# /verity-insights — Project quality insights and Standard evolution
+
+Surface metrics from accumulated run data and manage Standard evolution suggestions.
+
+## Metrics overview
+
+Gather data from multiple sources to give the user a quality health report:
+
+```bash
+# Knowledge base size — active lessons or memory nodes
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/lessons" | jq '.total_active'
+
+# Memory graph stats (if graph enabled)
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/memory/nodes" | jq '.total'
+
+# Run trends — use verity status for a quick summary
+verity status
+
+# Pending suggestions — Standard evolution candidates
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/standard-suggestions" | jq '.suggestions | length'
+```
+
+### What to surface
+
+1. **Pattern signal/noise**: patterns with high FP rates (candidates for retirement or severity lowering)
+2. **High-value patterns**: patterns with high TP rates (proving their worth)
+3. **Active suppressions**: count of per-finding false-positive suppressions
+4. **Knowledge base size**: lesson/node count by kind, recent additions
+5. **Score trends**: quality and security scores over the last 10 runs
+6. **Finding recurrence**: how often the same finding_key reappears (should decrease over time)
+7. **Lesson injection rate**: % of recent runs where ≥1 lesson/node was injected
+
+## Standard evolution suggestions
+
+The system analyzes accumulated telemetry and suggests Standard changes:
+
+### View pending suggestions
+
+```bash
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/standard-suggestions" | jq '.suggestions[]'
+```
+
+Suggestion kinds:
+- **retire_pattern**: Pattern had 90+ runs with zero findings — not earning its place
+- **lower_severity**: Pattern has >50% false-positive rate — too noisy at current severity
+- **sharpen**: Pattern has >80% true-positive rate over 50+ findings — consider raising severity
+- **add_exclusion**: Pattern dismissed ≥3 times for same file pattern — add file-scope exclusion
+- **promote_lesson**: High-confidence lesson cited ≥5 times — promote to custom Standard pattern
+
+### Approve a suggestion
+
+Approving creates a new Standard version automatically:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/standard-suggestions/<suggestion-id>/approve"
+```
+
+### Reject a suggestion
+
+Rejected suggestions won't resurface for 30 days:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/standard-suggestions/<suggestion-id>/reject"
+```
+
+### Generate suggestions manually
+
+Normally runs weekly. To trigger manually:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/generate-suggestions"
+```
+
+## How evolution works
+
+1. **Observe**: Every run accumulates pattern telemetry (signal vs noise) and finding feedback
+2. **Aggregate**: Weekly job reads telemetry + feedback → produces evolution candidates
+3. **Review**: User sees suggestions with evidence (run counts, FP rates, citation counts)
+4. **Apply**: Approved suggestions become a new Standard version (immutable, rollback-safe)
+5. **No autonomous changes** in v1 — every suggestion requires human approval

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

@@ -0,0 +1,63 @@
+# /verity-learn — View and manage project knowledge
+
+Project knowledge is durable insights extracted from analysis runs — decisions, patterns, gotchas, and conventions. When the memory graph is enabled (`memory_graph_enabled`), this skill delegates to the graph. Otherwise, it uses flat lessons.
+
+## Graph mode (memory_graph_enabled = true)
+
+When the memory graph is active, `/verity-learn` delegates to `/verity-memory`. Use these commands:
+
+- **List nodes**: `ls .verity/memory/*/` or see `/verity-memory list`
+- **Show a node**: `cat .verity/memory/<domain>/<slug>.md` or see `/verity-memory show <node_id>`
+- **Walk the graph**: see `/verity-memory walk --files <files>`
+- **Add knowledge**: see `/verity-memory add <kind> "<title>"`
+
+For full documentation, use `/verity-memory`.
+
+## Flat mode (memory_graph_enabled = false, default for existing projects)
+
+### List lessons
+
+```bash
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/lessons" | jq '.lessons[] | {id, kind, title, confidence}'
+```
+
+### Add a lesson (user-authored)
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/lessons" \
+  -d '{
+    "kind": "gotcha",
+    "title": "RLS policies and cleanup cron are coupled",
+    "body": "Changing RLS policies without updating the cleanup cron will break retention.",
+    "file_globs": ["server/supabase/migrations/**"]
+  }'
+```
+
+Valid kinds: `bug_pattern`, `architectural_decision`, `gotcha`, `preferred_convention`, `false_positive_rule`, `intent_template`.
+
+### Archive a lesson
+
+```bash
+curl -s -X PATCH -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/lessons/<lesson-id>" \
+  -d '{"status": "archived"}'
+```
+
+### Trigger extraction
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/extract" \
+  -d '{"task_id": "<task-uuid>"}'
+```
+
+## How it works
+
+1. **Extraction**: When a task closes or reaches 5 runs, an LLM extracts 0-3 durable knowledge items.
+2. **Injection**: On each analysis run, the most relevant knowledge is scored and injected into the reviewer prompt.
+3. **Compounding**: Knowledge that proves useful gets higher confidence. Unused knowledge is eventually archived.

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

@@ -0,0 +1,113 @@
+# /verity-memory — Manage the project knowledge graph
+
+The memory graph is a collection of markdown nodes at `.verity/memory/` organized into 8 domains. Each node has YAML frontmatter with typed edges that form a graph. The graph is the project's accumulated knowledge — decisions, patterns, gotchas, security constraints, and more.
+
+## Commands
+
+### List nodes
+
+```bash
+# List all active nodes
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/memory/nodes" | jq '.nodes[] | {node_id, kind, title, confidence}'
+
+# Filter by kind
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/memory/nodes?kind=security" | jq '.nodes[]'
+```
+
+Or browse locally: `ls .verity/memory/*/`
+
+### Show a node
+
+```bash
+curl -s -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/memory/nodes/<node_id>" | jq '.'
+```
+
+Or read directly: `cat .verity/memory/decisions/<slug>.md`
+
+### Walk the graph
+
+Find related knowledge by seeding from files you're working on:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/memory/walk" \
+  -d '{"seed_files": ["src/auth/tokens.ts"], "max_hops": 2, "budget_tokens": 2000}'
+```
+
+### Add a node (user-authored)
+
+User-authored nodes get `confidence: 1.0` and are never auto-archived:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/memory/nodes" \
+  -d '{
+    "kind": "gotcha",
+    "title": "RLS policies and cleanup cron are coupled",
+    "body": "Changing RLS policies without updating the cleanup cron will break retention.",
+    "file_globs": ["server/supabase/migrations/**"],
+    "domains": ["security", "database"]
+  }'
+```
+
+Valid kinds: `decision`, `quality`, `security`, `intent`, `gotcha`, `pattern`, `domain`, `integration`.
+
+Or create the markdown file directly at `.verity/memory/<domain>/<slug>.md` with proper frontmatter (see `.verity/memory/SCHEMA.md` for the template).
+
+### Edit a node
+
+Edit the markdown file directly at `.verity/memory/<domain>/<slug>.md`. Changes sync to the cloud on the next analysis run. User edits are always preserved (repo wins for `source: user`).
+
+### Archive a node
+
+```bash
+curl -s -X PATCH -H "Authorization: Bearer $VERITY_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$(verity config service-url)/compound/memory/nodes/<node_id>" \
+  -d '{"status": "archived"}'
+```
+
+### Search nodes
+
+Use full-text search via the list endpoint, or `grep -r "keyword" .verity/memory/` locally.
+
+### Run lint
+
+Check for orphan nodes, stale knowledge, missing backlinks, and contradictions:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $VERITY_TOKEN" \
+  "$(verity config service-url)/compound/memory/lint"
+```
+
+Results appear in `.verity/memory/log.md` after the next sync.
+
+## How the graph works
+
+1. **Extraction**: When tasks close or reach 5 runs, an LLM extracts 0-3 knowledge nodes with typed edges.
+2. **Sync**: On every analysis run, the CLI sends a manifest of local files. The server returns new nodes as `memory_writes[]` that the CLI applies locally.
+3. **Injection**: The reviewer prompt receives a graph-walk neighborhood (2 hops from changed files, budget-capped at 2000 tokens).
+4. **Linking**: Nodes connect opportunistically via shared file_globs, keyword overlap, and shared evidence runs.
+5. **Lint**: Weekly checks for orphans, stale nodes, contradictions, and missing backlinks.
+
+## Domains
+
+| Directory | Purpose |
+|-----------|---------|
+| `decisions/` | Architectural choices (WHY is it this way?) |
+| `quality/` | Quality patterns (WHAT does "good" mean here?) |
+| `security/` | Security constraints (WHAT must be protected?) |
+| `intent/` | Intent templates (WHAT does the user expect?) |
+| `gotchas/` | Footguns and surprises (WHAT will trip you up?) |
+| `patterns/` | Code conventions (HOW should it be done?) |
+| `domain/` | Business logic concepts (WHAT does this mean?) |
+| `integrations/` | External system knowledge (WHAT's around us?) |
+
+## Obsidian compatibility
+
+The `.verity/memory/` directory is designed to open directly in Obsidian, Foam, or Logseq. Nodes use `[[wikilink]]` syntax for cross-references.

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

@@ -0,0 +1,47 @@
+# /verity-reflect — Capture learnings after a task
+
+Trigger knowledge extraction for the current task, or submit a human reflection that becomes a high-confidence knowledge node.
+
+## Auto-reflection (extract from task history)
+
+When called without `--user-input`, triggers the LLM extractor to review the current task's run history and produce 0-3 knowledge nodes:
+
+```bash
+verity reflect
+```
+
+This is the same extraction that runs automatically on task close and every 5 runs. Use this to manually trigger it mid-task if you've learned something significant.
+
+## Human reflection (the compound moment)
+
+When the user provides their own insight, it becomes a high-confidence node (`source: user`, `confidence: 1.0`) that is never auto-archived:
+
+```bash
+verity reflect --user-input "The Stripe retry logic needs idempotency keys or we double-charge"
+```
+
+The CLI will:
+1. Call the extractor LLM to classify the reflection into a domain (decisions/, patterns/, gotchas/, etc.)
+2. Set `source: 'user'` and `confidence: 1.0`
+3. Opportunistically link to existing nodes
+4. Write the node locally and sync to cloud
+
+## When to reflect
+
+The agent should ask for a reflection at natural task-completion moments:
+
+- After creating a PR
+- When the user says "done", "ship it", or "that's it"
+- When a task is explicitly closed
+
+The reflection prompt (installed in CLAUDE.md during setup):
+
+> "Quick reflection for future agents: what's one thing you learned during this task that would help next time? A decision, a gotcha, a pattern — anything worth remembering. (Say 'skip' to skip.)"
+
+If the user says "skip", do NOT call `verity reflect`. The reflection is optional.
+
+## Examples of good reflections
+
+- "The Stripe retry logic needs to use idempotency keys or we double-charge. Learned this the hard way." → `gotchas/stripe-idempotency-keys.md`
+- "We decided to use advisory locks instead of optimistic locking because Supabase supports it natively." → `decisions/advisory-locks-for-versioning.md`
+- "Don't touch the RLS policies without updating the cleanup cron job — they're coupled." → `gotchas/rls-cleanup-coupling.md`