@codacy/verity-cli 0.32.6-experimental.df0a578 → 0.32.7

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

@@ -1,22 +1,20 @@
 ---
 description: >-
   Capture a durable learning at the end of a task: draft a concrete, cited observation from
-  what actually happened and record it straight into the project knowledge base. Use at natural
+  what actually happened, then confirm it with the user or record it directly. Use at natural
   task-completion moments, or when the user asks to record a lesson.
 ---
 # /verity-reflect — Capture learnings after a task
 
-At a natural task-completion moment, **the agent reflects and records** — draft a
-concrete, cited observation from what actually happened, write it to the project
-knowledge base, and say what you wrote. No question, no waiting.
+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.
 
-This is the second half of the "reflection flip". Verity first stopped asking the
-user to do the reflecting; it now also stops asking permission to keep it. The
-human is a reader and editor of the record, not a gate in front of it.
+## The flip — draft first, then confirm or auto-record
 
-## The flow
-
-### 1. Draft
+### 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
@@ -24,69 +22,47 @@ 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.
 
-That last rule is now the *only* filter. Nobody is going to catch a weak
-reflection before it lands, so do not record one.
-
 Pick the right `--kind` per item: `decision`, `gotcha`, `pattern`, `security`,
 `quality`, `intent`, `domain`, `integration`.
 
-**Citing the files is not decoration — it is what makes the reflection findable.**
-Verity scopes a node to the paths named in its text, and retrieval seeds on that
-scope. A reflection that names no file in this repo is recorded and then never
-surfaces again, in any future review. So write `src/payments/retry.ts:88`, not
-"the retry path".
-
-### 2. Record it
+### 2. Branch on run mode
 
-```bash
-verity reflect --user-input "<your draft>" --kind <kind>
-```
+**Interactive** (a person is at the keyboard — a TTY): show your draft and ask
+one question before recording:
 
-That is the whole step. It never blocks, never prompts, and works the same in a
-TTY, a hook, CI, or a cron run.
+> "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.)"
 
-If the reflection genuinely cannot name its files in prose, scope it explicitly:
+Then record the **final** text — with their corrections folded in — via:
 
 ```bash
-verity reflect --user-input "<your draft>" --kind <kind> --file-globs "src/auth/**"
+verity reflect --user-input "<final reflection>" --kind <kind>
 ```
 
-The command warns when a reflection resolved to no files, so you will know when
-this is needed rather than discovering it months later as a node nobody read.
+If they say "skip", do **not** record.
 
-**When the *user* authored the words** — they said "record this: …", or dictated
-a lesson in their own terms — add `--confirmed`:
+**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 "<what they said>" --kind <kind> --confirmed
+verity reflect --user-input "<your draft>" --kind <kind> --autonomous
 ```
 
-This is not a formality. Without the flag a reflection is stored as
-`source: agent` (confidence 0.7) — *Verity thought this, nobody checked it*. With
-it, `source: user` at confidence 1.0 — *a person stands behind this*. The
-dashboard, the retrieval ranking, and the next agent to read the node all rely on
-the difference. Never pass `--confirmed` for your own draft, even a good one.
-
-### 3. Tell the user, in one line
-
-The command prints the node id, the local file path, and a dashboard link. Relay
-it — one line, no ceremony:
-
-> Recorded a gotcha about the Stripe retry path → `.verity/memory/gotchas/n104-stripe-idempotency-keys.md`
-
-They did not agree to this in advance, so they need to know it happened and where
-to go if it is wrong. Do not ask them to confirm it after the fact either — the
-file is right there, and editing or deleting it is the correction.
+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.
 
-### 4. Where it lands
+### 3. Where it lands
 
-Only Verity's own memory namespace — `.verity/memory/` (mirrored to the service).
-Verity never writes a repo's own `agents/memory` or any other store. One node per
-item, synced to disk immediately so it is readable and editable straight away.
+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.
 
 ## Auto-reflection (extract from task history)
 
-Complementary to the above: trigger the server-side LLM extractor to mine the
+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:
@@ -95,8 +71,8 @@ mid-task:
 verity reflect
 ```
 
-Use the draft flow above for the **compound moment** (a specific insight worth a
-node); use auto-extract to harvest what the run history shows.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/verity-cli",
-  "version": "0.32.6-experimental.df0a578",
+  "version": "0.32.7",
   "description": "CLI for Verity quality gate service",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://verity.md",
@@ -23,7 +23,7 @@
   },
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "npm run build && VERITY_TEST_PREBUILT=1 node --import tsx --test $(find tests -name '*.test.ts' -not -path 'tests/e2e/*' | sort)",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "test:e2e": "node --import tsx --test --test-concurrency=1 tests/e2e/*.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run build"