@fernado03/zoo-flow 0.5.2 → 0.7.0

package/scripts/token-budget.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+const EXCEPTIONS_PATH = path.join(packageRoot, "quality", "token-budget.exceptions.json");
+const TIERS = [
+  { label: "tier-1-rules", dirs: [".roo/rules/", ".roo/rules-code-tweaker/", ".roo/rules-system-architect/", ".roo/rules-custom-orchestrator/"], max_bytes: 16000 },
+  { label: "tier-2-commands", dirs: [".roo/commands/"], max_bytes: 8000 },
+  { label: "tier-3-skills", dirs: [".roo/skills/"], max_bytes: 32000 },
+  { label: "tier-4-config", dirs: [".roomodes", ".roo/"], max_bytes: 4000, allow_files: true },
+  { label: "tier-5-docs", dirs: ["docs/"], max_bytes: 64000 },
+  { label: "tier-6-evidence", dirs: [".zoo-flow/evals/"], max_bytes: 8000 }
+];
+
+const failures = [];
+let exceptions = { overrides: {} };
+
+if (fs.existsSync(EXCEPTIONS_PATH)) {
+  try {
+    exceptions = JSON.parse(fs.readFileSync(EXCEPTIONS_PATH, "utf8"));
+  } catch (error) {
+    failures.push(`Invalid exceptions file: ${error.message}`);
+  }
+}
+
+function getExceptionKey(relativePath) {
+  return relativePath.replace(/\\/g, "/");
+}
+
+function getMaxOverride(relativePath) {
+  const key = getExceptionKey(relativePath);
+  const override = exceptions.overrides && exceptions.overrides[key];
+  return override ? override.max_bytes : null;
+}
+
+for (const tier of TIERS) {
+  for (const dirPattern of tier.dirs) {
+    const absPath = path.join(packageRoot, dirPattern);
+    if (!fs.existsSync(absPath)) continue;
+
+    let tierSize = 0;
+
+    if (tier.allow_files && fs.statSync(absPath).isFile()) {
+      const override = getMaxOverride(dirPattern);
+      if (override !== null) continue; // override allows it
+      const size = fs.statSync(absPath).size;
+      if (size > tier.max_bytes) {
+        failures.push(`${dirPattern} (${size} bytes) exceeds tier ${tier.label} limit (${tier.max_bytes})`);
+      }
+      continue;
+    }
+
+    const walkDir = (dir) => {
+      for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const stat = fs.statSync(full);
+        if (stat.isDirectory()) {
+          walkDir(full);
+        } else {
+          const ext = path.extname(full);
+          if (![".md", ".json", ".txt", ".yaml", ".yml", ".jsonl"].includes(ext)) continue;
+
+          const relative = path.relative(packageRoot, full).replace(/\\/g, "/");
+          const override = getMaxOverride(relative);
+          if (override !== null) continue; // allowed by exception
+
+          tierSize += stat.size;
+        }
+      }
+    };
+
+    walkDir(absPath);
+
+    if (tierSize > tier.max_bytes) {
+      failures.push(`${dirPattern} tree (${tierSize} bytes) exceeds tier ${tier.label} limit (${tier.max_bytes})`);
+    }
+  }
+}
+
+// Also check README and CONTEXT.md sizes
+const readmePath = path.join(packageRoot, "README.md");
+if (fs.existsSync(readmePath)) {
+  const size = fs.statSync(readmePath).size;
+  const override = getMaxOverride("README.md");
+  if (override === null && size > 24000) {
+    failures.push(`README.md (${size} bytes) exceeds default limit (24000)`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("\nToken budget check failed:\n");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  console.error("\nAdd exceptions in quality/token-budget.exceptions.json if this is intentional.\n");
+  process.exit(1);
+}
+
+console.log("Token budget check passed");

package/templates/full/.roo/commands/caveman.md

@@ -2,6 +2,6 @@
 description: "Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says \"caveman mode\", \"talk like caveman\", \"use caveman\", \"less tokens\", \"be brief\", or invokes /caveman."
 ---
 
-Run skill: `.roo/skills/productivity/caveman/SKILL.md`
+Skill: `.roo/skills/productivity/caveman/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/diagnose.md

@@ -1,7 +1,8 @@
 ---
 description: "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/diagnose/SKILL.md`
+Skill: `.roo/skills/engineering/diagnose/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/explore.md

@@ -1,13 +1,13 @@
----
-description: "Explore unfamiliar code before /feature, /refactor, or /fix. Produces written map."
-argument-hint: <feature or folder to map>
-mode: system-architect
----
-EXECUTION RULES:
-1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to the target area. Missing slots are not an error. If no slots are populated, output one line before step 2: "No context docs found. Run /grill-with-docs to start CONTEXT.md, or continue without context."
-2. RUN skill: `.roo/skills/engineering/zoom-out/SKILL.md`.
-3. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions.
-4. NEXT STEPS: Suggest `/grill-with-docs`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
-5. SAVE (Optional): Ask to save map to .scratch/explorations/<date>/explore-<slug>.md.
-
-$ARGUMENTS
+---
+description: "Explore unfamiliar code before /feature, /refactor, or /fix. Produces written map."
+argument-hint: <feature or folder to map>
+mode: system-architect
+---
+EXECUTION RULES:
+1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to the target area. Missing slots are not an error. If no slots are populated, output one line before step 2: "No context docs found. Run /grill-with-docs to start CONTEXT.md, or continue without context."
+2. RUN skill: `.roo/skills/engineering/zoom-out/SKILL.md`.
+3. OUTPUT MAP: Create markdown with sections: Domain language, Modules, Data flow, Seams/callers, ADRs, Open questions.
+4. NEXT STEPS: Suggest `/grill-with-docs`, `/feature`, `/refactor`, or `/fix`. DO NOT auto-launch.
+5. SAVE (Optional): Ask to save map to .scratch/explorations/<date>/explore-<slug>.md.
+
+$ARGUMENTS

package/templates/full/.roo/commands/feature.md

@@ -16,6 +16,6 @@ EXECUTION RULES (Run sequentially. Wait for user between phases):
 5. IMPLEMENT (Tweaker):
    - Architect summarizes issues.
    - Architect MUST `switch_mode` -> `code-tweaker`.
-   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/commit-and-document`.
+   - Tweaker: For each issue, execute the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`). After each ships, suggest `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

package/templates/full/.roo/commands/fix.md

@@ -15,6 +15,6 @@ EXECUTION RULES:
    - Tweaker MUST `switch_mode` -> `system-architect`.
 4. POST-MORTEM (Architect): Execute Phase 6. If architectural rot, suggest `/refactor`.
    - Architect MUST `switch_mode` -> `code-tweaker`.
-5. COMMIT (Tweaker): Suggest `/commit-and-document`.
+5. FOLLOW-UP (Tweaker): Suggest `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

package/templates/full/.roo/commands/grill-me.md

@@ -1,7 +1,8 @@
 ---
 description: "Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions \"grill me\"."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/productivity/grill-me/SKILL.md`
+Skill: `.roo/skills/productivity/grill-me/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/grill-with-docs.md

@@ -1,7 +1,8 @@
 ---
 description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/grill-with-docs/SKILL.md`
+Skill: `.roo/skills/engineering/grill-with-docs/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/handoff.md

@@ -1,8 +1,9 @@
 ---
 description: "Compact the current conversation into a handoff document for another agent to pick up."
 argument-hint: "What will the next session be used for?"
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/productivity/handoff/SKILL.md`
+Skill: `.roo/skills/productivity/handoff/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/improve-codebase-architecture.md

@@ -1,7 +1,8 @@
 ---
 description: "Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/improve-codebase-architecture/SKILL.md`
+Skill: `.roo/skills/engineering/improve-codebase-architecture/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/prototype.md

@@ -4,6 +4,6 @@ argument-hint: <prototype question or design uncertainty>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/prototype/SKILL.md`
+Skill: `.roo/skills/engineering/prototype/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/refactor.md

@@ -13,6 +13,6 @@ EXECUTION RULES:
    - Architect summarizes approved plan.
    - Architect MUST `switch_mode` -> `code-tweaker`.
    - Tweaker executes the `/tdd` command workflow (per `.roo/rules/01-command-protocol.md`) — new tests at interface, delete old.
-   - Tweaker suggests `/commit-and-document`.
+   - Tweaker suggests `/verify`, then `/review`, then `/commit-and-document`. Do not auto-launch.
 
 $ARGUMENTS

package/templates/full/.roo/commands/review.md

@@ -0,0 +1,11 @@
+---
+description: "Review a diff or branch against the requested spec, project standards, architecture, and likely regressions. Use before committing non-trivial work."
+argument-hint: <optional base ref, files, issue, PRD, or review focus>
+mode: system-architect
+---
+
+Review the current diff or requested target. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/review/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/commands/scaffold-context.md

@@ -1,13 +1,13 @@
----
-description: "Bootstrap .zoo-flow/CONTEXT.md (and 0-2 starter ADRs) for an existing project by scanning code for domain terms and cross-cutting decisions. Shows proposed entries inline and asks for confirm before writing. Use when starting Zoo Flow on a project with no CONTEXT.md, or to expand a thin one."
-argument-hint: <optional focus area, e.g. "auth", "billing", or empty for whole project>
-mode: code-tweaker
----
-
-EXECUTION RULES:
-1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to find current CONTEXT.md, ADRs.
-2. IF `.zoo-flow/CONTEXT.md` exists and is non-empty, ASK: skip / merge (default) / replace. Skip = do nothing. Merge = add only new terms, never overwrite. Replace = full rewrite from scan.
-3. RUN skill: `.roo/skills/engineering/scaffold-context/SKILL.md` with the same focus area.
-4. DO NOT auto-launch any follow-up commands.
-
-$ARGUMENTS
+---
+description: "Bootstrap .zoo-flow/CONTEXT.md (and 0-2 starter ADRs) for an existing project by scanning code for domain terms and cross-cutting decisions. Shows proposed entries inline and asks for confirm before writing. Use when starting Zoo Flow on a project with no CONTEXT.md, or to expand a thin one."
+argument-hint: <optional focus area, e.g. "auth", "billing", or empty for whole project>
+mode: code-tweaker
+---
+
+EXECUTION RULES:
+1. APPLY the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to find current CONTEXT.md, ADRs.
+2. IF `.zoo-flow/CONTEXT.md` exists and is non-empty, ASK: skip / merge (default) / replace. Skip = do nothing. Merge = add only new terms, never overwrite. Replace = full rewrite from scan.
+3. RUN skill: `.roo/skills/engineering/scaffold-context/SKILL.md` with the same focus area.
+4. DO NOT auto-launch any follow-up commands.
+
+$ARGUMENTS

package/templates/full/.roo/commands/setup-matt-pocock-skills.md

@@ -1,8 +1,8 @@
----
-description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, or `triage` — or if those skills appear to be missing issue tracker, triage label, or domain-doc configuration."
-mode: code-tweaker
----
-
-Run skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`
-
-$ARGUMENTS
+---
+description: "Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, or `triage` — or if those skills appear to be missing issue tracker, triage label, or domain-doc configuration."
+mode: code-tweaker
+---
+
+Skill: `.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/commands/tdd.md

@@ -4,6 +4,6 @@ argument-hint: <feature or bug to build>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/tdd/SKILL.md`
+Skill: `.roo/skills/engineering/tdd/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/to-issues.md

@@ -1,7 +1,8 @@
 ---
 description: "Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/to-issues/SKILL.md`
+Skill: `.roo/skills/engineering/to-issues/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/to-prd.md

@@ -1,7 +1,8 @@
 ---
 description: "Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/to-prd/SKILL.md`
+Skill: `.roo/skills/engineering/to-prd/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/triage.md

@@ -3,6 +3,6 @@ description: "Triage issues through a state machine driven by triage roles. Use
 mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/triage/SKILL.md`
+Skill: `.roo/skills/engineering/triage/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/tweak.md

@@ -4,6 +4,6 @@ argument-hint: <what to change>
 mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/engineering/tweak/SKILL.md`
+Skill: `.roo/skills/engineering/tweak/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/update-docs.md

@@ -1,22 +1,22 @@
----
-description: "Update repo documentation so it matches the current code."
-argument-hint: <doc or area to update>
-mode: code-tweaker
----
-
-Update repo documentation so it matches the current code. Surgical edits only — read existing docs first, verify claims against code, never rewrite wholesale unless the existing doc is unsalvageable. Follow the skill exactly.
-
-Skill: `.roo/skills/engineering/update-docs/SKILL.md`
-
-Apply the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to locate the target doc. If the slot is empty, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
-
-Do NOT use this for:
-
-- Domain glossary terms — use `/grill-with-docs`
-- ADRs — use `/grill-with-docs` or `/refactor`
-- Local commit journal entries — use `/commit-and-document`
-- Read-only understanding — use `/explore`
-
-If `$ARGUMENTS` is empty, ask once: "Which documentation file or area should I update?"
-
-$ARGUMENTS
+---
+description: "Update repo documentation so it matches the current code."
+argument-hint: <doc or area to update>
+mode: code-tweaker
+---
+
+Update repo documentation so it matches the current code. Surgical edits only — read existing docs first, verify claims against code, never rewrite wholesale unless the existing doc is unsalvageable. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/update-docs/SKILL.md`
+
+Apply the slot discovery rule from `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to locate the target doc. If the slot is empty, ask once: "No <slot> found. Create a stub at .zoo-flow/<slot>? (yes / pick-existing / skip)".
+
+Do NOT use this for:
+
+- Domain glossary terms — use `/grill-with-docs`
+- ADRs — use `/grill-with-docs` or `/refactor`
+- Local commit journal entries — use `/commit-and-document`
+- Read-only understanding — use `/explore`
+
+If `$ARGUMENTS` is empty, ask once: "Which documentation file or area should I update?"
+
+$ARGUMENTS

package/templates/full/.roo/commands/verify.md

@@ -0,0 +1,11 @@
+---
+description: "Run the smallest useful verification checks for the current change: tests, typecheck, lint, build, or targeted project checks. Never claim verified unless checks actually ran."
+argument-hint: <optional focus area, file, test, or command>
+mode: code-tweaker
+---
+
+Verify the current change with the smallest useful checks. Follow the skill exactly.
+
+Skill: `.roo/skills/engineering/verify/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/commands/write-a-skill.md

@@ -1,7 +1,8 @@
 ---
 description: "Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill."
+mode: code-tweaker
 ---
 
-Run skill: `.roo/skills/productivity/write-a-skill/SKILL.md`
+Skill: `.roo/skills/productivity/write-a-skill/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/commands/zoom-out.md

@@ -1,7 +1,8 @@
 ---
 description: "Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture."
+mode: system-architect
 ---
 
-Run skill: `.roo/skills/engineering/zoom-out/SKILL.md`
+Skill: `.roo/skills/engineering/zoom-out/SKILL.md`
 
 $ARGUMENTS

package/templates/full/.roo/rules/01-command-protocol.md

@@ -11,7 +11,7 @@ When assigned a slash command, execute its command workflow before task-specific
 3. Fallback: if `run_slash_command` is unavailable, disabled, rejected, or fails, read `.roo/commands/{command}.md`.
 
 4. After command content is loaded:
-   - If it explicitly contains `Skill: .roo/skills/.../SKILL.md`, read that exact skill and follow it.
+   - If it explicitly contains the canonical `Skill:` marker with `.roo/skills/.../SKILL.md`, read that exact skill and follow it.
    - If it contains direct workflow steps, execute those steps directly.
    - Do not assume every command has a skill.
    - Do not read any skill unless the command explicitly references it.

package/templates/full/.roo/rules/04-context-economy.md

@@ -1,29 +1,27 @@
-# Context Economy
-
-Use the smallest read that preserves correctness.
-
-Prefer `list_files`, `search_files`, or `codebase_search` before full-file reads.
-
-When reading files, prefer targeted line ranges or indentation/block reads when the relevant area is known.
-
-Batch related small reads when useful.
-
-Do not re-read unchanged files unless needed.
-
-For long command output, summarize or search the output instead of dumping everything.
-
-## Domain-doc read gate
-
-Do not read CONTEXT.md, CONTEXT-MAP.md, FLOW.md, APP_MAP.md, ARCHITECTURE.md, or ADRs by default.
-
-Read domain docs only when at least one is true:
-
-- The task touches domain language or terminology.
-- The task changes public behavior.
-- The task changes architecture, module seams, persistence, API shape, auth, payments, security, migrations, or cross-module design.
-- The command explicitly requires those docs, such as `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, or relevant `/update-docs`.
-- The user asks for documentation, architecture, product, or domain-context work.
-
-For low-risk localized edits, prefer code search and targeted file reads first.
-
-Missing CONTEXT.md or ADRs is not an error. Use the slot discovery rule in `.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md` to detect what is present, and proceed silently when nothing is.
+# Context Economy
+
+Use the smallest read that preserves correctness.
+
+Prefer `list_files`, `search_files`, or `codebase_search` before full-file reads.
+
+When reading files, prefer targeted line ranges or indentation/block reads when the relevant area is known.
+
+Batch related small reads when useful.
+
+Do not re-read unchanged files unless needed.
+
+For long command output, summarize or search the output instead of dumping everything.
+
+## Domain-doc read gate
+
+Do not read `.zoo-flow/CONTEXT.md` or `.zoo-flow/docs/adr/` files by default.
+
+Read domain docs only when at least one is true:
+
+- The task touches domain language or terminology.
+- The task changes public behavior.
+- The task changes architecture, module seams, persistence, API shape, auth, payments, security, migrations, or cross-module design.
+- The command explicitly requires those docs (e.g. `/feature`, `/refactor`, `/grill-with-docs`, `/scaffold-context`, `/update-docs`).
+- The user asks for documentation, architecture, product, or domain-context work.
+
+Missing CONTEXT.md or ADRs is not an error. Proceed silently when nothing is present.

package/templates/full/.roo/rules-code-tweaker/01-completion.md

@@ -13,11 +13,15 @@ Before any `attempt_completion`, re-read the command body and confirm no later p
 
 `attempt_completion` must include:
 
-- what was done
-- files changed or inspected
-- commands/tests run
-- status
-- blockers
-- recommended next command
-
-Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
+- what was done (exact scope)
+- files changed or inspected (paths)
+- commands/tests run (exact commands, pass/fail per command)
+- status (complete / partial / blocked with reason)
+- remaining risk (what was not checked or is uncertain)
+- recommended next command (one only, no auto-launch)
+
+Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
+
+For non-trivial `/tdd`, `/fix`, `/feature`, `/refactor`, or R3+ `/tweak` work, recommend `/verify` before `/review` before `/commit-and-document`. Do not auto-launch those commands.
+
+If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.