@codacy/verity-cli 0.23.3 → 0.24.0

package/bin/verity.js

@@ -13710,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));
 }
@@ -16047,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) {
@@ -16141,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.)");
       }
@@ -16408,7 +16434,7 @@ function registerTelemetryCommands(program2) {
 }
 
 // src/cli.ts
-program.name("verity").description("CLI for Verity quality gate service").version("0.23.3").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.3",
+  "version": "0.24.0",
   "description": "CLI for Verity quality gate service",
   "homepage": "https://verity.md",
   "repository": {