@codacy/verity-cli 0.23.3 → 0.24.0-experimental.6a390ac

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-experimental.6a390ac",
   "description": "CLI for Verity quality gate service",
   "homepage": "https://verity.md",
   "repository": {