pi-orchestrator-config 4.2.0 → 4.3.2

package/extensions/shared/oneshot.ts

@@ -0,0 +1,116 @@
+/**
+ * Oneshot argv helpers — skip session extras so `pi -p` / `--mode json` can exit.
+ *
+ * Lives in shared/ so coms/pidash/pidiff/pitasks can import without the
+ * orchestrator utils module. Keep ONESHOT_VALUE_FLAGS in sync with pi
+ * `parseArgs` (`@earendil-works/pi-coding-agent` `dist/cli/args.js`).
+ */
+
+import { createLogger } from "./logger.js";
+
+const log = createLogger("oneshot");
+
+/**
+ * Value-taking flags from pi `parseArgs`. `--mode` is handled separately.
+ * Next token is always a value, even if it starts with `-` (including `--`).
+ */
+const ONESHOT_VALUE_FLAGS = new Set([
+  "--model",
+  "--models",
+  "--provider",
+  "--api-key",
+  "--system-prompt",
+  "--append-system-prompt",
+  "--name",
+  "-n",
+  "--session",
+  "--session-id",
+  "--fork",
+  "--session-dir",
+  "--tools",
+  "-t",
+  "--exclude-tools",
+  "-xt",
+  "--thinking",
+  "--export",
+  "--extension",
+  "-e",
+  "--skill",
+  "--prompt-template",
+  "--theme",
+]);
+
+const PI_MODES = new Set(["text", "json", "rpc"]);
+
+/**
+ * True when argv is a oneshot pi invocation (`-p` / `--print` / `--mode json`).
+ * Session extras must not register — watchers and sockets keep the Node event
+ * loop alive after the reply.
+ *
+ * Mirrors pi `parseArgs` + `resolveAppMode` (without TTY): last valid
+ * `--mode <text|json|rpc>` wins; rpc is never oneshot; json is; print flag
+ * is oneshot unless last mode is rpc. `--mode=json` / `--mode=rpc` are unknown
+ * flags in pi (not mode). Value-aware so `--mode -p` does not treat `-p`
+ * as the print flag. No `--` end-of-options (parseArgs has none).
+ *
+ * Debug log uses isDebugEnabled() (same log_oneshot / PI_LOG_ONESHOT sources
+ * as fileLog). Level is cached 30s so register/argv scan does not re-stat.
+ *
+ * CLI/ACPX providers still load. Non-TTY stdin or stdout print (`echo | pi`,
+ * `pi | cat`) without those flags is not detected here — argv has no flags;
+ * use `ctx.mode` after session_start.
+ */
+export function isPiOneshotInvocation(argv: string[] = process.argv): boolean {
+  const args = argv.slice(2);
+  let lastMode: string | undefined;
+  let print = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-p" || arg === "--print") {
+      print = true;
+      continue;
+    }
+    if (arg === "--mode") {
+      const value = args[i + 1];
+      if (value !== undefined) {
+        i += 1;
+        if (PI_MODES.has(value)) lastMode = value;
+      }
+      continue;
+    }
+    if (ONESHOT_VALUE_FLAGS.has(arg) && args[i + 1] !== undefined) {
+      i += 1;
+    }
+  }
+  const oneshot = lastMode === "rpc" ? false : lastMode === "json" || print;
+  if (log.isDebugEnabled()) {
+    log.debug("oneshot argv", { oneshot, lastMode, print });
+  }
+  return oneshot;
+}
+
+/** True when pitasks/pidash/pidiff/coms should skip register. Caller returns if true. */
+export function shouldSkipOneshotRegister(
+  logger: { info: (msg: string) => void },
+  argv: string[] = process.argv,
+): boolean {
+  if (!isPiOneshotInvocation(argv)) return false;
+  logger.info("skip register: oneshot print/json");
+  return true;
+}
+
+/**
+ * Shutdown dream runs `runDreamAsync` → `spawnAsyncAgent` (not detached/unref'd).
+ * Skip when argv is oneshot OR session `mode` is print/json so `pi -p` can exit.
+ * Does not skip rpc/tui unless argv is oneshot (`-p` + `--mode rpc` is not oneshot).
+ */
+export function shouldSkipOneshotShutdownDream(
+  mode?: string | null,
+  argv: string[] = process.argv,
+): boolean {
+  const oneshot = isPiOneshotInvocation(argv);
+  const printOrJson = mode === "print" || mode === "json";
+  const skip = oneshot || printOrJson;
+  log.debug("skip shutdown dream?", { skip, oneshot, mode });
+  return skip;
+}

package/extensions/shared/resolve-binary.ts

@@ -0,0 +1,191 @@
+/**
+ * Shared binary resolution helpers.
+ *
+ * In-process PATH scan for resolving CLI binaries. Avoids spawnSync("which")
+ * on auth/filter hot paths. Used by both CLI and ACPX provider drivers.
+ *
+ * Moved from cli-provider/shared/discover-cache.ts so both provider families
+ * can import without cross-provider dependencies.
+ *
+ * @module shared/resolve-binary
+ */
+
+import {
+  accessSync,
+  constants,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { extname, isAbsolute, join, posix, win32 } from "node:path";
+
+/** Cache keyed by `${platform}\0${binary}\0${PATH}\0${PATHEXT}` — successful resolves only. */
+const resolveBinaryCache = new Map<string, string>();
+
+export type ResolveBinaryEnv = {
+  PATH?: string;
+  PATHEXT?: string;
+};
+
+/** Parse PATHEXT into uppercase extensions (e.g. ".EXE"). Exported for tests. */
+export function parsePathext(pathextEnv?: string): string[] {
+  const raw = pathextEnv ?? process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM";
+  return raw
+    .split(";")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => (s.startsWith(".") ? s : `.${s}`).toUpperCase());
+}
+
+/**
+ * True when filePath has an extension listed in PATHEXT (case-insensitive).
+ * Extensionless files are not CreateProcess-launchable on Windows.
+ */
+export function isLaunchableWin32(
+  filePath: string,
+  pathextEnv?: string,
+): boolean {
+  const ext = extname(filePath);
+  if (!ext) return false;
+  return parsePathext(pathextEnv).includes(ext.toUpperCase());
+}
+
+/**
+ * Suffixes to try when scanning PATH for `binary`.
+ * On win32: if `binary` already has a PATHEXT extension, try as-is only;
+ * otherwise try each PATHEXT suffix (no bare/empty suffix).
+ */
+export function candidateSuffixesFor(
+  binary: string,
+  platform: NodeJS.Platform = process.platform,
+  pathextEnv?: string,
+): string[] {
+  if (platform !== "win32") return [""];
+  const ext = extname(binary);
+  if (ext && parsePathext(pathextEnv).includes(ext.toUpperCase())) {
+    return [""];
+  }
+  return parsePathext(pathextEnv);
+}
+
+/**
+ * PATH list separator for the *resolved* platform (not the host OS).
+ * Needed so win32 simulation on Unix splits semicolon-separated PATH correctly.
+ */
+export function pathDelimiterFor(platform: NodeJS.Platform): string {
+  return platform === "win32" ? win32.delimiter : posix.delimiter;
+}
+
+/** Exported for tests — regular file + platform launchability rules. */
+export function isExecutableForPlatform(
+  filePath: string,
+  platform: NodeJS.Platform,
+  pathextEnv?: string,
+): boolean {
+  let st;
+  try {
+    st = statSync(filePath);
+  } catch {
+    return false;
+  }
+  // Directories are often X_OK (searchable); only regular files are binaries.
+  if (!st.isFile()) return false;
+  // Win32: never treat any regular file as executable — require PATHEXT.
+  if (platform === "win32") return isLaunchableWin32(filePath, pathextEnv);
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function finalizeResolved(filePath: string): string {
+  try {
+    return realpathSync(filePath);
+  } catch {
+    return filePath;
+  }
+}
+
+function cacheKeyFor(
+  binary: string,
+  platform: NodeJS.Platform,
+  pathEnv: string,
+  pathextEnv: string,
+): string {
+  return `${platform}\0${binary}\0${pathEnv}\0${pathextEnv}`;
+}
+
+/**
+ * Resolve a binary for an explicit platform (injectable for win32 tests on Unix).
+ * Absolute paths still require a launchable PATHEXT extension on win32.
+ */
+export function resolveBinaryForPlatform(
+  binary: string,
+  platform: NodeJS.Platform,
+  env: ResolveBinaryEnv = {},
+): string | null {
+  if (!binary) return null;
+
+  const pathEnv = env.PATH ?? process.env.PATH ?? "";
+  const pathextEnv =
+    env.PATHEXT ?? process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM";
+  const cacheKey = cacheKeyFor(binary, platform, pathEnv, pathextEnv);
+  const cached = resolveBinaryCache.get(cacheKey);
+  if (cached !== undefined) {
+    if (isExecutableForPlatform(cached, platform, pathextEnv)) return cached;
+    resolveBinaryCache.delete(cacheKey);
+  }
+
+  const isExec = (p: string) =>
+    isExecutableForPlatform(p, platform, pathextEnv);
+
+  // Absolute or explicit relative path — check directly (mirrors `which /path`).
+  if (isAbsolute(binary) || binary.includes("/") || binary.includes("\\")) {
+    if (!isExec(binary)) return null;
+    const resolved = finalizeResolved(binary);
+    resolveBinaryCache.set(cacheKey, resolved);
+    return resolved;
+  }
+
+  const suffixes = candidateSuffixesFor(binary, platform, pathextEnv);
+  const envDelimiter = pathDelimiterFor(platform);
+  for (const dir of pathEnv.split(envDelimiter)) {
+    if (!dir) continue;
+    for (const suffix of suffixes) {
+      // PATHEXT is typically uppercase; Windows FS is case-insensitive.
+      // On case-sensitive hosts (win32 simulation in tests), also try lowercase.
+      const variants =
+        platform === "win32" && suffix && suffix !== suffix.toLowerCase()
+          ? [binary + suffix, binary + suffix.toLowerCase()]
+          : [binary + suffix];
+      for (const name of variants) {
+        const candidate = join(dir, name);
+        if (!isExec(candidate)) continue;
+        const resolved = finalizeResolved(candidate);
+        resolveBinaryCache.set(cacheKey, resolved);
+        return resolved;
+      }
+    }
+  }
+
+  // Do not cache misses — mid-session install with same PATH must rediscover.
+  return null;
+}
+
+/**
+ * Resolve a binary name (or absolute path) via an in-process PATH scan.
+ * Avoids spawnSync("which") on auth/filter hot paths.
+ * Returns realpath when possible, null if missing.
+ */
+export function resolveBinary(binary: string): string | null {
+  return resolveBinaryForPlatform(binary, process.platform, {
+    PATH: process.env.PATH,
+    PATHEXT: process.env.PATHEXT,
+  });
+}
+
+/** Clear PATH resolve cache (tests / PATH mutation). */
+export function clearResolveBinaryCache(): void {
+  resolveBinaryCache.clear();
+}

package/extensions/shared/types.ts

@@ -17,4 +17,7 @@ export interface SessionInfo {
   diffPort?: number | null;
   working?: boolean;
   name?: string;
+  comsName?: string;
+  comsPurpose?: string;
+  comsProject?: string;
 }

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.2.0",
+  "version": "4.3.2",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"
   ],
   "license": "MIT",
-  "workspaces": ["packages/pi-sidecar", "packages/pi-vertex-claude"],
+  "workspaces": [
+    "packages/pi-sidecar",
+    "packages/pi-vertex-claude"
+  ],
   "files": [
     "extensions/acpx-provider/",
     "extensions/cli-provider/",
@@ -17,17 +20,20 @@
     "extensions/image-gen/",
     "extensions/pidash/*.ts",
     "extensions/pidiff/*.ts",
+    "extensions/pitasks/",
     "agents/",
     "rules/",
     "prompts/",
     "templates/",
-    "skills/"
+    "skills/",
+    "settings-keys.json"
   ],
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
     "acpx": ">=0.12.0 <1",
     "chokidar": "^5.0.0",
     "discord.js": "^14.0.0",
+    "strip-json-comments": "^5.0.3",
     "ws": "^8.0.0"
   },
   "devDependencies": {

package/prompts/coderabbit-rate-limit.md

@@ -72,6 +72,8 @@ This outputs JSON to stdout. Parse the result:
 
 - If `rate_limited` is `false` — notify user "Not rate limited" and exit
 - If `rate_limited` is `true` — read `wait_seconds` and proceed to Phase 3
+  - If `fallback` is `true`, the wait time is **estimated** from the comment timestamp
+    (1-hour window), not parsed from the comment body. Warn the user that timing is approximate.
 
 ### Phase 3: Wait and Trigger Review
 

package/rules/00-orchestrator-core.md

@@ -8,6 +8,8 @@
 
 ---
 
+{{IF:orchestrator_edit_write_block}}
+
 ## Delegation Model
 
 The orchestrator delegates — never implements directly.
@@ -28,6 +30,7 @@ Outside slash commands, never use edit, write, or bash directly (except `mcpl`)
 **Never delegate:** slash commands — execute them directly (see slash command rules).
 
 ---
+{{/IF}}
 
 ## Before Implementation (MANDATORY)
 

package/rules/10-agent-routing.md

@@ -19,7 +19,7 @@
 | Debugging | `debugger` |
 | API docs | `api-documenter` |
 | External repo security audit | `security-auditor` |
-| External AI agents (cursor, codex, gemini, claude, copilot, etc.) | `/acpx-prompt` |
+| {{IF:external_ai_agents}}External AI agents (cursor, codex, gemini, claude, copilot, etc.){{/IF}} | {{IF:external_ai_agents}}`/acpx-prompt`{{/IF}} |
 | External library/framework docs (React, FastAPI, Django, etc.) | `docs-fetcher` |
 
 ## Routing by Intent, Not Tool
@@ -56,3 +56,14 @@ Some agents are dispatched internally by rules or prompt templates, not by the r
 ## Fallback
 
 **Fallback:** No specialist? → `worker` agent
+
+## Model Override
+
+When the user asks to run an agent with a specific model:
+
+1. Use `list_models` tool to discover available providers and models.
+2. Pass the model to `subagent(model="provider/model-id")`.
+3. Format: `provider/model-id` (e.g., `litellm/claude-opus-4-6-1m`) or just `model-id` (overrides model only; provider follows normal resolution chain).
+4. For parallel tasks, set `model` per-task in the tasks array. Top-level `model` is used as fallback for tasks without their own.
+5. Chain steps share the top-level `model` — no per-step override.
+6. Explicit `model` param overrides agent_overrides, frontmatter, and settings.

package/rules/20-code-review-loop.md

@@ -4,6 +4,7 @@ After ANY code change, send to ALL 6 agents (5 reviewers + test-automator) IN PA
 
 ## Commit enforcement
 
+{{IF:review_loop_enforcement}}
 When `review_loop_enforcement` is enabled, the enforcement rule in `enforcement.ts` blocks `git commit` unless:
 
 - Review status is `clean` (all reviewers returned 0 findings)
@@ -17,23 +18,26 @@ call `addReviewerPending`/`recordReviewerResult` from bash, write to the JSON fi
 or use any method to fake a clean state. The enforcement system detects and blocks this.
 The ONLY way to reach `clean` status is to run the actual review agents.
 
-Resolution: project `.pi/pi-config-settings.json` → global `~/.pi/pi-config-settings.json` → `PI_REVIEW_LOOP_ENFORCEMENT` env var → `false`.
+Resolution is handled automatically via project settings injection.
 
 - MUST loop until clean or the max cycle cap is reached — see "Cycle Definition & Max Cycles" below.
+{{/IF}}
 
-If disabled:
+{{IFNOT:review_loop_enforcement}}
+Single review pass is sufficient — no commit blocking from the review loop.
+Step 5a (fix/explain every finding) is optional: fix what you agree with, skip what you don't.
+{{/IFNOT}}
 
-- Single review pass is sufficient
-- No commit blocking
+**All 6 agents are always called.** `review_loop_enforcement` controls whether the loop repeats.
 
-**In both cases, all 6 agents are always called.** `review_loop_enforcement` controls whether the loop repeats; when enabled,
-`review_loop_max_cycles` caps **total** cycles including the first (see Cycle Definition below).
+{{IF:review_loop_enforcement}}
+When enabled, `review_loop_max_cycles` caps **total** cycles including the first (see Cycle Definition below).
 
 ### Cycle Definition & Max Cycles
 
 One **cycle** = call all 6 reviewers (in parallel) → fix/explain findings → end of cycle.
 
-**The cycle count IS the `cycle` field in `pi-config-review-state.json`** — the same counter shown by
+**The cycle count IS the `cycle` field in `pi-config-review-state.jsonl`** — the same counter shown by
 `/review-status` and the review UI status card. It increments each time reviewers are (re-)dispatched
 for a fresh pass. Step 5's branches below MUST compare against that same counter — do not track cycles
 mentally or separately.
@@ -46,8 +50,8 @@ Disable the review loop via `review_loop_enforcement: false` — not via max_cyc
 Cap check is after 5a; it only blocks `go to 2` (re-dispatch of step 2 / all 6 agents,
 including test-automator), not completing the current cycle's fix/explain.
 
-**After 5a completes on the max cycle, two outcomes — neither unblocks `git commit`**
-(still controlled solely by `review_loop_enforcement`; status must be `clean` + `tests_passed: true`):
+**After 5a completes on the max cycle, two outcomes** (report them; commit may still be
+allowed via the max-cycle path — see step 6):
 
 - **Not fixed** (explained why not) → outstanding — report them.
 - **Fixed** (verification blocked by the cap) → cannot re-dispatch to confirm clean — report that
@@ -64,24 +68,30 @@ cycle3: dispatch → findings → 5a (fix|explain) → cycle >= max → stop (no
 ```text
 1. Specialist writes/fixes code
 2. Send ALL 6 agents IN PARALLEL (async): 5 reviewers + test-automator
+   **On cycle 2+: MANDATORY — include prior cycle findings + responses in each reviewer's prompt (see Step 5a format).**
+   Reviewers without this context will blindly repeat the same findings. This is not optional.
 3. Wait for all 6 to complete
 4. Merge & deduplicate review findings
 5. Has findings OR tests failed?
    ── Neither? ↓ status: clean, tests_passed: true
    ── Findings and/or tests failed? → ALWAYS run 5a first: fix code OR explain why not, for EACH finding;
-      fix code for failing tests. Then check state.cycle (from `pi-config-review-state.json`):
+      fix code for failing tests. Then check state.cycle (from `pi-config-review-state.jsonl`):
         · cycle < {{REVIEW_LOOP_MAX_CYCLES}}? → go to 2 (re-run all 6 with prior findings + responses)
         · cycle >= {{REVIEW_LOOP_MAX_CYCLES}}? → **STOP** (terminal): report the two-outcome result
           (see "Cycle Definition & Max Cycles" above). Do NOT proceed to step 6.
-6. NOW you can commit — the pre-commit hook will pass (only when status is `clean` AND `tests_passed: true`)
-✅ DONE — commit/push allowed (enforcement checks status: clean AND tests_passed: true)
+6. NOW you can commit — the pre-commit hook will pass when:
+   - status is `clean` AND `tests_passed: true`, OR
+   - max cycles exhausted (`has_findings` or `clean`, no pending reviewers, `cycle >= review_loop_max_cycles` — no `tests_passed` check)
+✅ DONE — commit/push allowed
 ```
 
-🚨 **Step 6 applies only when clean.** Do NOT attempt `git commit` before reaching `clean` + `tests_passed: true`.
+🚨 **Step 6 applies when clean OR max cycles exhausted.** Do NOT attempt `git commit` before that.
 The enforcement rule blocks commits until this is satisfied — if it blocks you, run the reviewers.
 **After a cap stop:** report the two-outcome result (**Not fixed** → outstanding, **Fixed** → verification
-blocked); raise `review_loop_max_cycles` or disable `review_loop_enforcement` if needed — do **not**
+blocked); commit is allowed when status is `has_findings` or `clean`, no reviewers pending, and
+`cycle >= review_loop_max_cycles` (no `tests_passed` requirement); do **not**
 return to step 2 (re-dispatch of all 6 agents, including test-automator).
+{{/IF}}
 
 ## Review Agents
 
@@ -100,7 +110,7 @@ Six agents run in parallel for comprehensive coverage:
 Do NOT block waiting for results — continue working while they run.**
 
 Send reviewers "Review the code changes" — never mention `git diff HEAD` in the task prompt.
-Reviewers get `$PI_REVIEW_BASE_BRANCH` env var and use `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD` themselves.
+Reviewers get `$PI_REVIEW_BASE_BRANCH` env var and use `git diff origin/$PI_REVIEW_BASE_BRANCH` themselves (includes uncommitted changes).
 
 Reviewers return structured JSON: `{"findings": [{"severity": "...", "file": "...", "line": N, "description": "...", "suggestion": "..."}]}`.
 The async runner validates the output is valid JSON and retries if not (up to 3 times).
@@ -118,7 +128,9 @@ reviewers, even on the same file/line. A quality finding about *how* code is wri
 address *whether* the code matches the spec. Always keep both. Spec findings CAN still be
 deduplicated against other spec findings when they are truly the same issue.
 
-## Step 5a: Respond to Findings (when `review_loop_enforcement` is enabled)
+{{IF:review_loop_enforcement}}
+
+## Step 5a: Respond to Findings
 
 For each finding from step 4, do ONE of:
 
@@ -137,7 +149,7 @@ The following findings were raised in review cycle {N}. Each has been either fix
 explained. Do NOT re-raise findings that were adequately addressed. Only re-raise if:
 - The code fix is incorrect or incomplete
 - The explanation is invalid or factually wrong
-- You disagree with the reasoning (explain why)
+- You disagree with the reasoning (state why in the finding description field)
 
 Findings with valid explanations that you accept → do not re-raise.
 Findings that were fixed in code → verify the fix, do not re-raise if correct.
@@ -151,29 +163,38 @@ Findings that were fixed in code → verify the fix, do not re-raise if correct.
 - If a finding was fixed → verify the fix is correct, don't re-raise
 - If a finding was explained with a valid technical reason → accept it, don't re-raise
 - If the explanation is wrong or the fix is incomplete → re-raise with specific pushback
-
-**When `review_loop_enforcement` is disabled:** Step 5a is optional. Single review pass
-is sufficient — fix what you agree with, skip what you don't. No need to explain skips.
+{{/IF}}
 
 ## Key Rules
 
 Never skip code review — all 6 agents always run (5 reviewers + test-automator).
+Exception: on `chore/bump-version` branches (release version bumps), review dirty-tracking and commit blocking are skipped.
+{{IF:review_loop_enforcement}}
 When `review_loop_enforcement` is enabled: loop, respond to each finding (fix or explain), and re-run all 6 from step 2
 until clean or the cycle cap is reached — see "Cycle Definition & Max Cycles" above for the exact stop conditions.
-When disabled: single pass is sufficient; no mandatory re-loop or explanations.
+{{/IF}}
+{{IFNOT:review_loop_enforcement}}
+When `review_loop_enforcement` is disabled: single pass is sufficient; no mandatory re-loop or explanations.
+{{/IFNOT}}
 Minor test/config-only fixes skip re-review (go to step 5); substantive code changes require full re-review.
 
 ## Test Tracking
 
-Test results are tracked in `pi-config-review-state.json` via the `tests_passed` field.
-This is **code-enforced** — commit/push is blocked unless `tests_passed: true` (when `review_loop_enforcement` is enabled).
+Test results are tracked in `pi-config-review-state.jsonl` via the `tests_passed` field.
+
+{{IF:review_loop_enforcement}}
+This is **code-enforced** — commit/push is blocked unless `tests_passed: true`.
+{{/IF}}
+{{IFNOT:review_loop_enforcement}}
+Tests still run and `tests_passed` is still recorded; commit is not blocked by review state when enforcement is off.
+{{/IFNOT}}
 
 **How `tests_passed` gets set:**
 
 - **Bash hook detection:** When any agent runs a test command (`pytest`, `npm test`, `npx tsx --test`, `tox`, `go test`, `vitest`, `jest`, `mocha`),
   the enforcement hook detects it and auto-marks `tests_passed` based on exit code.
 - **Agent completion:** When `test-automator` or `test-runner` agents complete, their result auto-marks `tests_passed`.
-- **Reset on edit:** Any file edit triggers `markNeedsReview()`, which resets `tests_passed: false` —
+- **Reset on edit:** Any file edit triggers `markNeedsReview()` (except on `chore/bump-version` branches), which resets `tests_passed: false` —
   preventing stale results.
 
 **Duplicate test run avoidance:** If a specialist already ran tests before the review loop, `tests_passed` may already be `true`.
@@ -215,20 +236,26 @@ If both `git apply` methods fail, skip baseline comparison and note "baseline co
 For automated review flows (autorabbit, autoqodo), use **two-stage order** instead of parallel:
 
 1. **Stage 1 — Spec Compliance:** Does code meet requirements? All deliverables implemented? No scope creep?
+{{IF:review_loop_enforcement}}
    Loop Stage 1 until passed OR the shared cycle cap is reached.
+{{/IF}}
 2. **Stage 2 — Code Quality:** Quality, security, guidelines adherence.
+{{IF:review_loop_enforcement}}
    Loop Stage 2 until passed OR the shared cycle cap is reached.
+{{/IF}}
 
+{{IF:review_loop_enforcement}}
 **Staged cycle definition:** one **cycle** = one pass of the *current* stage's reviewers (in parallel)
 → fix/explain that stage's findings → end of cycle. This mirrors the parallel-mode cycle definition
 (see "Cycle Definition & Max Cycles" above), scoped to one stage's reviewers instead of all 6.
 
 **The `review_loop_max_cycles` cap is shared across both stages — one total budget, not one per stage.**
 Stage 1 and Stage 2 both draw from and increment the same `cycle` counter in
-`pi-config-review-state.json`. Cap check, 5a-before-cap, and two-outcome reporting follow
+`pi-config-review-state.jsonl`. Cap check, 5a-before-cap, and two-outcome reporting follow
 "Cycle Definition & Max Cycles" above. Stage-specific stops: if Stage 1 is **not clean** when the cap is hit, stop entirely — do not proceed
 to Stage 2 (covers both **Not fixed** and **Fixed** (verification blocked)). If hit during Stage 2,
 stop looping Stage 2.
+{{/IF}}
 
 Don't polish code that doesn't meet spec — it wastes work.
 Parallel mode (all 6 agents at once) remains default for manual reviews.

package/rules/30-prompt-templates.md

@@ -7,12 +7,16 @@
 3. **The prompt decides** when to run directly and when to delegate to agents
 4. If the prompt says "run this bash command" — run it directly
 5. If the prompt says "delegate to X agent" — delegate
+{{IF:orchestrator_edit_write_block}}
 6. If the prompt doesn't specify — follow normal orchestrator rules (delegate to specialists)
+{{/IF}}
 
 ## Key Rules
 
 - The orchestrator **maintains control** of the prompt workflow
+{{IF:orchestrator_edit_write_block}}
 - The prompt template's instructions **override** general delegation rules when they conflict
+{{/IF}}
 - **NEVER** delegate the `/command` itself to an agent — only delegate sub-tasks when the prompt says to
 
 ❌ **WRONG**: `/mycommand` → delegate entire prompt to an agent

package/rules/35-memory.md

@@ -56,7 +56,7 @@ Search past conversation summaries for references to previous sessions. Returns
 
 ```text
 .pi/memory/
-├── memory-scores.json     # Scoring backend (auto-managed)
+├── memory-scores.jsonl     # Scoring backend (auto-managed)
 └── topics/
     ├── preferences.md     # [preference] entries
     ├── lessons.md         # [lesson] entries
@@ -228,8 +228,8 @@ On reinforce crossing a threshold, a promotion pass runs automatically.
 
 `memory_add` / `memory_edit` accept optional `sourceSession`, `derivedFrom`, `informs`.
 Preference extractor sets `sourceSession` when the session id is available.
-Dream may write `.pi/memory/provenance-pending.json`; merge happens on dream complete.
-Stored in `memory-scores.json` only — not injected into the situation report.
+Dream may write `.pi/memory/provenance-pending.jsonl`; merge happens on dream complete.
+Stored in `memory-scores.jsonl` only — not injected into the situation report.
 Shown in `memory_search` / `memory_reflect` when present.
 
 ---

package/rules/40-critical-rules.md

@@ -49,6 +49,8 @@ Always pass `cwd` when delegating to subagents in all modes — omitting it caus
 
 ---
 
+{{IF:use_worktrees}}
+
 ## Multi-PR / Multi-Branch Work
 
 **NEVER switch branches in the main worktree** when working on multiple PRs — other agents may be running there.
@@ -60,6 +62,7 @@ git worktree remove .worktrees/pr-42  # when done
 ```
 
 ---
+{{/IF}}
 
 ## User Interaction