@codacy/verity-cli 0.23.2 → 0.24.0

package/bin/verity.js

@@ -12833,6 +12833,11 @@ function getPushRangeFiles() {
   const last = diff("HEAD~1..HEAD");
   return { files: last, range: last.length > 0 ? "HEAD~1..HEAD" : null };
 }
+function getPushRangeMessages() {
+  const { range } = getPushRangeFiles();
+  if (!range) return "";
+  return execGit(`git log ${range} --format=%B%x00`).split("\0").map((s) => s.trim()).filter(Boolean).join("\n\n");
+}
 function getWorktreeFiles() {
   const result = [];
   const worktreeDir = ".claude/worktrees";
@@ -13705,7 +13710,12 @@ function isReflectionQuestion(response) {
     /reflection\s+for\s+future\s+agents/i,
     /what(?:'s|\s+is)\s+one\s+thing\s+you\s+learned/i,
     /say\s+['"]?skip['"]?\s+to\s+skip/i,
-    /quick\s+reflection\s+question/i
+    /quick\s+reflection\s+question/i,
+    // Post-flip (VRT-21): the agent drafts the reflection itself and, when
+    // interactive, asks the user to confirm/correct before recording. That
+    // turn authors no code either, so it's still a reflection turn.
+    /reflection\s+draft/i,
+    /confirm,?\s+correct,?\s+or\s+add/i
   ];
   return markers.some((m) => m.test(response));
 }
@@ -15057,7 +15067,48 @@ function registerGuardCommand(program2) {
 function getMomentFiles(moment) {
   return moment === "pre-commit" ? getStagedFiles() : getPushRangeFiles().files;
 }
-function buildGuardRequest(moment, files, iter, sessionId) {
+function matchFlagValue(command, flags) {
+  const re = new RegExp(`(?<![\\w-])(?:${flags})(?:=|\\s+)('((?:[^'\\\\]|\\\\.)*)'|"((?:[^"\\\\]|\\\\.)*)"|([^\\s'"-][^\\s]*))`);
+  const m = re.exec(command);
+  if (!m) return null;
+  const v = m[2] ?? m[3] ?? m[4];
+  return v != null ? v.replace(/\\(["'])/g, "$1") : null;
+}
+function parseCommitMessage(command) {
+  const parts = [];
+  const re = /(?<![\w-])(?:--message|-am|-m)(?:=|\s+)('((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)"|([^\s'"-][^\s]*))/g;
+  let m;
+  while ((m = re.exec(command)) !== null) {
+    const v = m[2] ?? m[3] ?? m[4];
+    if (v != null && v.length) parts.push(v.replace(/\\(["'])/g, "$1"));
+  }
+  return parts.length ? parts.join("\n\n") : null;
+}
+function parsePrIntent(command) {
+  const title = matchFlagValue(command, "--title|-t");
+  const body = matchFlagValue(command, "--body|-b");
+  const parts = [title, body].filter((x) => !!x);
+  return parts.length ? parts.join("\n\n") : null;
+}
+var TRIVIAL_INTENT = /^(wip|tmp|temp|test|fix|chore|amend|\.+|fixup!.*|squash!.*|merge\b.*)$/i;
+var SHELL_PLUMBING = /\$\(|`|<<-?\s*['"]?[A-Za-z_]/;
+function isSubstantiveIntent(text) {
+  if (!text) return false;
+  const t = text.trim();
+  if (t.length < 12) return false;
+  if (TRIVIAL_INTENT.test(t)) return false;
+  if (SHELL_PLUMBING.test(t)) return false;
+  return true;
+}
+function extractStatedIntent(moment, command) {
+  const text = moment === "pre-commit" ? parseCommitMessage(command) : parsePrIntent(command) ?? (getPushRangeMessages() || null);
+  return isSubstantiveIntent(text) ? text : null;
+}
+function hasBlockingFinding(response) {
+  const findings = response.findings ?? [];
+  return findings.some((f) => f.scope !== "pre-existing" && ["critical", "high"].includes((f.severity ?? "").toLowerCase()));
+}
+function buildGuardRequest(moment, files, iter, sessionId, command) {
   const analyzable = filterAnalyzable(files);
   const securityFiles = filterSecurity(files);
   let staticResults;
@@ -15087,20 +15138,21 @@ function buildGuardRequest(moment, files, iter, sessionId) {
   };
   const specs = discoverSpecs();
   const plans = discoverPlans();
-  if (specs.length > 0 || plans.length > 0) {
+  const statedIntent = extractStatedIntent(moment, command);
+  if (specs.length > 0 || plans.length > 0 || statedIntent) {
     const intentContext = {};
+    if (statedIntent) intentContext.user_prompt = statedIntent;
     if (specs.length > 0) intentContext.specs = specs;
     if (plans.length > 0) intentContext.plans = plans;
     requestBody.intent_context = intentContext;
   }
   return requestBody;
 }
-function allowWithNotice(moment, decision) {
-  resetIter(moment);
-  if (decision === "WARN") {
-    process.stderr.write(`${YELLOW}Verity ${moment}: WARN \u2014 proceeding. See findings in the report.${NC}
-`);
-  }
+function emitAllowNotice(userMsg, agentMsg) {
+  process.stdout.write(JSON.stringify({
+    systemMessage: userMsg,
+    hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: agentMsg }
+  }) + "\n");
   process.exit(0);
 }
 async function runGuard(opts, globals) {
@@ -15114,19 +15166,21 @@ async function runGuard(opts, globals) {
   }
   const moment = classifyCommand(command, on);
   if (!moment) process.exit(0);
+  const verb = moment === "pre-commit" ? "commit" : "push";
   const iter = readIter(moment);
   if (iter >= GUARD_BLOCK_CAP) {
-    process.stderr.write(`${DIM}Verity ${moment}: ${GUARD_BLOCK_CAP} review cycles reached \u2014 allowing through.${NC}
-`);
     resetIter(moment);
-    process.exit(0);
+    emitAllowNotice(
+      `Verity ${moment}: ${GUARD_BLOCK_CAP} review cycles reached \u2014 allowing the ${verb} through`,
+      `Verity ${moment}: review-cycle cap (${GUARD_BLOCK_CAP}) reached; the ${verb} was allowed without a further block.`
+    );
   }
   const files = getMomentFiles(moment);
   if (files.length === 0) process.exit(0);
   const tokenResult = await resolveToken(globals.token);
   const urlResult = await resolveServiceUrl(globals.serviceUrl);
   if (!tokenResult.ok || !urlResult.ok) process.exit(0);
-  const requestBody = buildGuardRequest(moment, files, iter, sessionId);
+  const requestBody = buildGuardRequest(moment, files, iter, sessionId, command);
   if (!requestBody) process.exit(0);
   const result = await analyzeRequest({
     serviceUrl: urlResult.data,
@@ -15137,21 +15191,39 @@ async function runGuard(opts, globals) {
     cmd: "guard"
   });
   if (!result.ok) {
-    process.stderr.write(`${DIM}Verity ${moment}: service unavailable \u2014 allowing commit/push (${result.error}).${NC}
-`);
-    process.exit(0);
-  }
-  if (opts.json) {
-    process.stdout.write(JSON.stringify(result.data) + "\n");
+    emitAllowNotice(
+      `\u26A0 Verity ${moment}: service offline \u2014 ${verb}ed WITHOUT review`,
+      `Verity ${moment}: service unavailable (${result.error}); the ${verb} was allowed WITHOUT a Verity review.`
+    );
   }
+  if (opts.json) process.stderr.write(JSON.stringify(result.data) + "\n");
   const response = result.data;
   const decision = response.gate_decision ?? "PASS";
-  if (decision === "FAIL") {
+  const viewUrl = response.view_url ?? "";
+  const link = viewUrl ? ` \u2014 ${viewUrl}` : "";
+  if (decision === "FAIL" && hasBlockingFinding(response)) {
     writeIter(moment, iter + 1);
     writeBlockMessage(moment, response);
     process.exit(2);
   }
-  allowWithNotice(moment, decision);
+  resetIter(moment);
+  if (decision === "FAIL") {
+    const narrative = response.assessment?.narrative ?? "";
+    emitAllowNotice(
+      `\u26A0 Verity ${moment}: the ${verb} may not match its stated purpose \u2014 proceeding${link}`,
+      `Verity ${moment}: intent-alignment WARNING (not blocked).${narrative ? " " + narrative : ""}${viewUrl ? ` Report: ${viewUrl}` : ""}`
+    );
+  }
+  if (decision === "WARN") {
+    emitAllowNotice(
+      `\u26A0 Verity ${moment}: WARN \u2014 proceeding${link}`,
+      `Verity ${moment} review: WARN (proceeding).${viewUrl ? ` Report: ${viewUrl}` : ""}`
+    );
+  }
+  emitAllowNotice(
+    `\u2713 Verity ${moment}: PASS${link}`,
+    `Verity ${moment} review: PASS.${viewUrl ? ` Report: ${viewUrl}` : ""}`
+  );
 }
 function writeBlockMessage(moment, response) {
   const label2 = moment === "pre-commit" ? "pre-commit" : "pre-push";
@@ -15980,10 +16052,29 @@ function registerResetCommand(program2) {
   });
 }
 
+// src/lib/run-mode.ts
+function parseAutonomousEnv(raw) {
+  if (raw === void 0) return void 0;
+  const v = raw.trim().toLowerCase();
+  if (v === "") return void 0;
+  if (v === "0" || v === "false" || v === "off" || v === "no") return false;
+  return true;
+}
+function resolveRunMode(inputs = {}) {
+  if (inputs.autonomousFlag === true) return "autonomous";
+  if (inputs.autonomousFlag === false) return "interactive";
+  const env = inputs.env ?? process.env;
+  const envDecision = parseAutonomousEnv(env.VERITY_AUTONOMOUS);
+  if (envDecision !== void 0) return envDecision ? "autonomous" : "interactive";
+  const isTTY = inputs.isTTY ?? Boolean(process.stdin?.isTTY);
+  return isTTY ? "interactive" : "autonomous";
+}
+
 // src/commands/reflect.ts
 function registerReflectCommand(program2) {
-  program2.command("reflect").description("Capture learnings \u2014 auto-extract or submit a human reflection").option("--user-input <text>", "Your reflection (becomes a high-confidence knowledge node)").option("--kind <kind>", "Node kind (decision, gotcha, pattern, security, quality, intent, domain, integration)", "gotcha").option("--task-id <id>", "Task to reflect on (defaults to current task)").action(async (opts) => {
+  program2.command("reflect").description("Capture learnings \u2014 auto-extract or submit a human reflection").option("--user-input <text>", "The reflection to record (the agent-drafted or user-confirmed text)").option("--kind <kind>", "Node kind (decision, gotcha, pattern, security, quality, intent, domain, integration)", "gotcha").option("--task-id <id>", "Task to reflect on (defaults to current task)").option("--autonomous", "Record the drafted reflection without a confirm step (auto-detected from TTY / VERITY_AUTONOMOUS when omitted)").action(async (opts) => {
     const globals = program2.opts();
+    const mode = resolveRunMode({ autonomousFlag: opts.autonomous });
     await ensureMemoryDir();
     const tokenResult = await resolveToken(globals.token);
     if (!tokenResult.ok) {
@@ -16074,7 +16165,9 @@ function registerReflectCommand(program2) {
       const nodeId = result.data.node_id;
       const filePath = result.data.file_path;
       printInfo(`Queued: ${nodeId} (will sync to .verity/memory/${filePath} on next analysis).`);
-      printInfo("Your reflection is now part of the project knowledge base (confidence: 100%).");
+      printInfo(
+        mode === "autonomous" ? "Recorded autonomously (no confirm step) into the project knowledge base." : "Recorded your confirmed reflection into the project knowledge base."
+      );
       if (taskResolution === "none") {
         printInfo("(No task context \u2014 reflection lives at the project level.)");
       }
@@ -16341,7 +16434,7 @@ function registerTelemetryCommands(program2) {
 }
 
 // src/cli.ts
-program.name("verity").description("CLI for Verity quality gate service").version("0.23.2").option("--token <token>", "Override authentication token").option("--service-url <url>", "Override service URL").option("--verbose", "Log HTTP requests/responses to stderr");
+program.name("verity").description("CLI for Verity quality gate service").version("0.24.0").option("--token <token>", "Override authentication token").option("--service-url <url>", "Override service URL").option("--verbose", "Log HTTP requests/responses to stderr");
 registerAuthCommands(program);
 registerHooksCommands(program);
 registerIntentCommands(program);

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

@@ -1,47 +1,83 @@
 # /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.
+At a natural task-completion moment, **the agent reflects first** — draft a
+concrete, cited observation from what actually happened — then either confirm it
+with the user (interactive) or record it directly (autonomous). This is the
+"reflection flip": Verity stops asking the user to do the reflecting and instead
+does the work, with the human as editor rather than author.
 
-## Auto-reflection (extract from task history)
+## The flip — draft first, then confirm or auto-record
+
+### 1. Self-draft (always)
+
+When a task is complete, draft **1–3** things genuinely worth remembering — a
+**decision**, a **gotcha**, or a **pattern** — from what happened this task. Each
+item must be **concrete and cited**: name the files, PR, commands, or
+error-signatures it came from. **Skip entirely if nothing non-obvious happened**
+— an empty reflection is better than a filler one.
+
+Pick the right `--kind` per item: `decision`, `gotcha`, `pattern`, `security`,
+`quality`, `intent`, `domain`, `integration`.
+
+### 2. Branch on run mode
 
-When called without `--user-input`, triggers the LLM extractor to review the current task's run history and produce 0-3 knowledge nodes:
+**Interactive** (a person is at the keyboard — a TTY): 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.)"
+
+Then record the **final** text — with their corrections folded in — via:
 
 ```bash
-verity reflect
+verity reflect --user-input "<final reflection>" --kind <kind>
+```
+
+If they say "skip", do **not** record.
+
+**Autonomous** (no person to confirm — headless / CI / cron, or
+`VERITY_AUTONOMOUS=1`, or a non-TTY session): record your draft **directly**,
+never blocking:
+
+```bash
+verity reflect --user-input "<your draft>" --kind <kind> --autonomous
 ```
 
-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.
+Mode is auto-detected when you omit the flag (TTY ⇒ interactive, non-TTY ⇒
+autonomous); pass `--autonomous` to be explicit, or set `VERITY_AUTONOMOUS=0` to
+force a confirm step even in a headless run.
+
+### 3. Where it lands
+
+The reflection is recorded **only to Verity's own memory namespace** —
+`.verity/memory/` (synced to the service). Verity never writes a repo's own
+`agents/memory` or any other store. One node per item; `source: 'user'`,
+`confidence: 1.0`, never auto-archived.
 
-## Human reflection (the compound moment)
+## Auto-reflection (extract from task history)
 
-When the user provides their own insight, it becomes a high-confidence node (`source: user`, `confidence: 1.0`) that is never auto-archived:
+Complementary to the flip: trigger the server-side LLM extractor to mine the
+current task's run history and produce 0–3 nodes. This is the same extraction
+that runs automatically on task close and every 5 runs — use it to trigger
+mid-task:
 
 ```bash
-verity reflect --user-input "The Stripe retry logic needs idempotency keys or we double-charge"
+verity reflect
 ```
 
-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
+Use the self-draft flow above for the **compound moment** (a specific insight
+worth a confirmed node); use auto-extract to harvest what the run history shows.
 
 ## When to reflect
 
-The agent should ask for a reflection at natural task-completion moments:
+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
+## Examples of good drafts
 
-- "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`
+- "The Stripe retry logic needs idempotency keys or we double-charge — hit it in `payments/retry.ts:88`." → `gotchas/stripe-idempotency-keys.md`
+- "We chose advisory locks over optimistic locking because Supabase supports them natively (see PR #214)." → `decisions/advisory-locks-for-versioning.md`
+- "Don't touch the RLS policies without updating the cleanup cron — they're coupled (`migrations/0190`, `cron/cleanup.sql`)." → `gotchas/rls-cleanup-coupling.md`

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

@@ -425,18 +425,31 @@ If `CLAUDE.md` exists (or `.claude/CLAUDE.md`), append these two blocks. If it d
 
 ## 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), ask the user one question before moving on:
+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.
 
-> "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.)"
+Then, depending on how the session is running:
 
-If the user responds (not "skip"), run `verity reflect --user-input "<their response>"`.
+- **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 user's judgment enters the knowledge base (KNOWLEDGE-SYSTEM §9.3)
+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)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/verity-cli",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "CLI for Verity quality gate service",
   "homepage": "https://verity.md",
   "repository": {