@dzhechkov/harness-cli 0.3.219 → 0.3.221

package/README.md

@@ -480,7 +480,7 @@ dz mcp-scan          [path] [--json]   (static agent-permission audit; exit 0/1/
 dz architecture      [--json] [--revise] [--check --slug <s> --desc "<text>" [--cmd a,b] [--subsystem <id>]]   # product map (subsystems = the README jobs + foundation/arsenal/ops); --revise = drift check (exit 1); --check = forward-looking сverka of a proposed feature vs map+vision (exit 2 on a hard-stop dup)
 dz project-skills    [--json] [--stages-json]   # polymorphic feature-adr: resolve architecture/project-skills.json (fixed roles product-vision/critic/brand/impl-bar + open extra[]) into per-stage guidance; absent = generic run (byte-identical); feature-adr Step 0 reads it
 dz mr-rakes          [--json] [--candidate N --confirmed N] [--teach] [--gen-critic <path> [--apply]]   # mine review artifacts (features' QE reports + REVIEW files) for RECURRING mistakes; anti-noise (≥2/≥3 distinct sources); close into dz teach + a project-critic skill (R2 critic role)
-dz retro             [transcript] [--json] [--threshold N] [--no-teach] [--install-hook]   # per-session retro: mine the current session for recurring PROCESS rakes (claimed-done-without-verify, n-fix-cycles, ignored-correction), drill the user (socratic + checklist) AND teach the agent — co-learning via the dz teach store
+dz retro             [transcript] [--json] [--threshold N] [--no-teach] [--install-hook]   # per-session retro: mine the current session for recurring PROCESS rakes (claimed-done-without-verify, committed-without-verify, n-fix-cycles, ignored-correction), drill the user (socratic + checklist) AND teach the agent — co-learning via the dz teach store
 dz publish           [--filter <name>] [--bump-only] [--claim-check <off|warn|error>]   (dry-run by default; pass --yes/--confirm to go live; claim-check gate defaults to warn — surfaces README claim findings, never blocks)
 dz auto-canonicalize --source <github-url> --pack <skills-pack>
 dz sync-upstream     [--package <dir>] [--list] [--all]
@@ -1338,6 +1338,72 @@ claude mcp add agentdb --env AGENTDB_PATH="$PWD/.dz/agentdb.db" -- npx agentdb@l
 
 ---
 
+## Architecture-aware & self-learning workflow (`architecture` · `project-skills` · `mr-rakes` · `retro`)
+
+Four commands that make the harness *self-aware*: it maps your product, keeps new features aligned to it, and
+learns from your reviews and sessions. Each shows **when to reach for it**, the exact command, and what it prints.
+
+### `dz architecture` — when you've lost the big picture, or before adding a feature
+
+```bash
+dz architecture              # the product map: subsystems (the 5 README jobs + foundation/arsenal/ops) + their packages/commands
+dz architecture --revise     # drift check: packages in no subsystem, or a command owned by two (exit 1 on drift)
+dz architecture --check --slug add-forecast --desc "forecast the next skill for a task" --cmd forecast   # сheck a feature you're about to build
+```
+```
+✓ architecture сverka: ok — Feature aligns with the product map and vision.
+# …or, if you would re-add an existing command:
+⛔ block (confidence 0.90) — duplicate-command: "recall" already exists in subsystem "learn". Confirm this is intentional.
+```
+The map is `architecture/subsystems.manifest.json` + `architecture/vision.md` (committed). `--check` exits **2**
+on a hard-stop, so you can gate it in CI or at feature-adr Step 0.
+
+### `dz project-skills` — when a project has its own conventions to fold into every feature-adr run
+
+Drop an `architecture/project-skills.json` (no pipeline edits needed):
+```json
+{ "version": 1,
+  "roles": { "product-vision": "architecture/vision.md", "critic": ".dz-skills/my-critic/SKILL.md" },
+  "extra": [ { "skill": ".dz-skills/security-checklist/SKILL.md", "phase": "qe", "as": "guidance" } ] }
+```
+```bash
+dz project-skills            # who-injected report (which skill feeds which stage)
+dz project-skills --json     # the plan feature-adr Step 0 reads
+```
+No manifest ⇒ a normal generic run (byte-identical). With one, feature-adr folds each skill into its stage as guidance
+(`product-vision`→design+QE, `critic`→QE, `brand`→code).
+
+### `dz mr-rakes` — when you want to learn what mistakes this project keeps repeating
+
+Run it once you have a few reviews (feature-adr QE reports / MR reviews) to mine the **recurring** rakes:
+```bash
+dz mr-rakes                                                              # ranked rakes (≥2/≥3 distinct sources; one-offs dropped)
+dz mr-rakes --teach                                                     # auto-teach confirmed rakes to the dz store (surfaced by recall)
+dz mr-rakes --gen-critic architecture/project-critic/SKILL.md --apply   # write a project-critic skill (propose without --apply)
+```
+```
+mr-rakes: 2 rake(s) from 78 finding(s) (73 one-offs dropped):
+  [confirmed] BLOCKER ×3 — ADR-named safety property left untested  (untested-adr-property)
+```
+The generated critic is exactly what a `project-skills.json` `critic` role points at — the loop closes.
+
+### `dz retro` — when you finish a coding session and want to learn from it
+
+```bash
+dz retro                     # mine the current session → drills for recurring PROCESS rakes + teach the agent
+dz retro --no-teach          # just the drills (don't write the store)
+dz retro --install-hook      # print the opt-in SessionEnd hook to run it automatically
+```
+```
+retro: 2 recurring rake(s) to drill (from 6800 events):
+  🔁 git commit after a code change without running tests/build first — 2× (recurring)
+     Before that `git commit` — did the tests/build actually pass in THIS session, or did you assume?
+     --- reveal (cover this, predict first) ---
+     ✅ Run the tests/build (and read the output) BEFORE `git commit`. (see the `validate` skill)
+```
+First-seen rakes accrue silently; only **recurring** ones get a drill (no nagging on a one-off). The user gets the
+drill, the agent gets the taught rule — from the same mistake, out of one shared `dz teach` store.
+
 ## Recipes & FAQ
 
 Scenario → exact command → how to verify → gotcha. **Three gotchas worth calling out up front:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.219",
+  "version": "0.3.221",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.114"
+    "@dzhechkov/harness-core": "0.3.115"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",