pi-orchestrator-config 4.22.3 → 4.22.4

package/agents/git-expert.md

@@ -44,11 +44,20 @@ Before ANY `git commit`, if `review_loop_enforcement` is `true`:
 {{SETTINGS:dco,commit_trailer,use_worktrees,allow_push_to_protected_branches}}
 
 - If `dco` is `true`: add `--signoff` to `git commit`. Skip if already present.
-- If `commit_trailer` is a string (e.g. `"Assisted-by"`): append trailer to the commit message.
-  Format: `TRAILER: PI (MODEL) <noreply@pi.dev>` — replace MODEL with your actual model id
-  (e.g. `litellm/claude-opus-4-6`). NEVER write the literal string `$PI_MODEL`; quoted heredocs
-  and single-quoted messages do not expand it and the trailer lands broken. Skip if already present.
-  If the value contains commas, use the first name.
+- If `commit_trailer` is a string (e.g. `"Assisted-by"`): every commit you make MUST carry that
+  trailer, and who writes it depends on the commit shape:
+  - `git commit -m "…"` → the enforcement hook appends `TRAILER: PI (<model>)`.
+    Do not write it yourself.
+  - `echo … | git commit -F -` → the hook appends it. Do not write it yourself.
+  - `git commit -F <file>` (message written to a file, including heredoc-to-file) → the hook never
+    sees the file's contents, so append the trailer yourself with the already-resolved id:
+    `printf '\n\nTRAILER: PI (%s)\n' "$PI_MODEL" >> <file>` and then commit. The shell expands
+    `$PI_MODEL` while writing the file, so no placeholder can reach the message.
+  Never write a bare `MODEL` placeholder and never leave an unexpanded `$PI_MODEL` in a `-m` message:
+  the enforcement hook **refuses** such a commit (it reports the placeholder line back), and it also
+  refuses a commit shape it cannot inspect when the message shows no trailer. The fix is always to
+  write the trailer yourself with the real id, then commit again.
+  Skip only when the message already carries that trailer.
 - If `use_worktrees` is `true`: BLOCK `git checkout` (except `git checkout -- <file>`) and `git switch`.
   Use `git worktree add .worktrees/NAME -b BRANCH DEFAULT_BRANCH` instead
   (detect default branch via `git symbolic-ref refs/remotes/origin/HEAD`, fallback to `main`).

package/extensions/orchestrator/enforcement-helpers.ts

@@ -2606,24 +2606,103 @@ function bodyAlreadySigned(text: string): boolean {
   return false;
 }
 
-// Trailer-shaped line: `Token:` at line start (real newline, literal \n
-// escape, or command start), then the PI trailer identity. Anchoring to the
-// line start keeps mid-sentence prose and unrelated compound-command parts
-// untouched (Qodo 988d3a68) — only an actual trailer line is rewritten.
-const unexpandedTrailerLine = /(^|\n|\\n|-m\s+['"])([ \t]*[A-Za-z][A-Za-z0-9-]*:[ \t]*)PI \(\$PI_MODEL\)/g;
-
-/** #932: an agent may write the commit trailer with the literal `$PI_MODEL`
- *  (typically inside a quoted heredoc, where the shell cannot expand it).
- *  Rewrite the trailer identity to the resolved model id before the commit
- *  runs. Returns the fixed command, or null when nothing needed fixing.
- *  Scoped to `git commit` commands and to trailer-shaped lines only, so
- *  commit-message prose that legitimately mentions `$PI_MODEL` — bare or
- *  mid-sentence — and unrelated parts of compound commands are untouched. */
-export function fixUnexpandedCommitTrailer(command: string, modelId: string): string | null {
-	if (!command.includes("$PI_MODEL")) return null;
+// Trailer-shaped line: `Token:` at line start (real newline, literal \n escape, or
+// command start), then a PI trailer identity that is a PLACEHOLDER rather than a model
+// id. Detection only — the hook refuses such a commit instead of rewriting text it may
+// have misparsed (Qodo, PR #1004).
+const placeholderTrailerLine = /(^|\n|\\n|-m\s+['"])([ \t]*[A-Za-z][A-Za-z0-9-]*:[ \t]*)PI \(\$?\{?PI_MODEL\}?|MODEL\)/g;
+
+/** The trailer line carrying an unresolved placeholder, or null when the command has none.
+ *  A `Token:` anchor keeps prose that merely mentions the placeholder out of the result. */
+export function findPlaceholderTrailer(command: string): string | null {
+	if (!/(?:PI_MODEL|\bMODEL\b)/.test(command)) return null;
 	if (!/\bgit\s+commit\b/.test(command)) return null;
-	const fixed = command.replace(unexpandedTrailerLine, `$1$2PI (${modelId})`);
-	return fixed === command ? null : fixed;
+	const matches = [...command.matchAll(placeholderTrailerLine)];
+	const found = matches.at(-1);
+	if (!found) {
+		enfLog.debug("placeholder trailer none");
+		return null;
+	}
+	const line = `${(found[2] ?? "").trim()} PI (placeholder)`;
+	enfLog.warn("placeholder trailer found", line);
+	return line;
+}
+
+/** Trailers where git itself needs an address: `Co-authored-by` credits a person. */
+const TRAILERS_REQUIRING_EMAIL = new Set(["co-authored-by"]);
+
+/** The value appended after `<Trailer>:`. `Assisted-by` needs no address, `Co-authored-by`
+ *  does — hosting integrations only credit a co-author through `Name <email>`. */
+export function commitTrailerIdentity(trailerName: string, modelId: string): string {
+	const needsEmail = TRAILERS_REQUIRING_EMAIL.has(trailerName.trim().toLowerCase());
+	const identity = needsEmail ? `PI (${modelId}) <noreply@pi.dev>` : `PI (${modelId})`;
+	enfLog.debug("commit_trailer_identity", trailerName, needsEmail);
+	return identity;
+}
+
+/** Does a `-F <file>` commit message already carry the trailer?
+ *  The caller injects the reader so the decision is testable without touching disk —
+ *  the hook reads the file, it does not guess from the command text (Qodo, PR #1004). */
+export function messageFileTrailerState(
+	filePath: string,
+	trailerName: string,
+	read: (path: string) => string,
+): "has" | "missing" | "unreadable" {
+	try {
+		const state = commandHasTrailerByName(read(filePath).slice(0, 64_000), trailerName) ? "has" : "missing";
+		enfLog.debug("message_file_trailer", filePath, state);
+		return state;
+	} catch (error: any) {
+		// warn, not debug: trailer verification could not inspect the message, which is a
+		// degraded guarantee an operator needs to see (Qodo, PR #1004).
+		enfLog.warn("message_file_trailer unreadable", filePath, String(error?.message ?? error));
+		return "unreadable";
+	}
+}
+
+/** Append `<Trailer>: PI (<model>)` to the message of a real commit invocation.
+ *  Covers the two shapes whose message the hook can see — `echo … | git commit -F -`
+ *  and `git commit -m "…"` — and returns null when the trailer is already there or
+ *  the shape is not covered. Pure so the injection path is testable without a hook. */
+export function injectCommitTrailer(command: string, trailerName: string, modelId: string): string | null {
+	const identity = commitTrailerIdentity(trailerName, modelId);
+	// Pattern A: echo "..." | git commit -F -
+	const pipeIdx = command.lastIndexOf("|");
+	if (pipeIdx !== -1 && /git\s+commit\s+.*-F\s*-/.test(command.slice(pipeIdx))) {
+		const echoPart = command.slice(0, pipeIdx);
+		const gitPart = command.slice(pipeIdx);
+		const lastQuoteIdx = Math.max(echoPart.lastIndexOf('"'), echoPart.lastIndexOf("'"));
+		if (lastQuoteIdx > 0) {
+			if (commandHasTrailerByName(echoPart, trailerName)) {
+				enfLog.debug("inject_commit_trailer", "already present", trailerName);
+				return null;
+			}
+			const quoteChar = echoPart[lastQuoteIdx];
+			const escaped = quoteChar === "'"
+				? `${escapeForSingleQuote(trailerName)}: ${identity}`
+				: `${escapeForDoubleQuote(trailerName)}: ${identity}`;
+			enfLog.info("inject_commit_trailer", "piped", trailerName);
+			return echoPart.slice(0, lastQuoteIdx) + `\\n\\n${escaped.replace(/\n/g, "\\n")}` + echoPart.slice(lastQuoteIdx) + gitPart;
+		}
+		return null;
+	}
+	// Pattern B: git commit -m "..." or git commit -m '...'
+	const mFlagMatch = command.match(/git\s+commit\s+.*-m\s+(["'])([\s\S]*?)\1/);
+	if (!mFlagMatch) return null;
+	// Every `-m` is a message paragraph, so an existing trailer in ANY of them wins.
+	const allPayloads = [...command.matchAll(/-m\s+(["'])([\s\S]*?)\1/g)].map((m) => m[2] ?? "").join("\n");
+	if (commandHasTrailerByName(allPayloads, trailerName)) {
+		enfLog.debug("inject_commit_trailer", "already present", trailerName);
+		return null;
+	}
+	const quoteChar = mFlagMatch[1];
+	const escaped = quoteChar === "'"
+		? `${escapeForSingleQuote(trailerName)}: ${identity}`
+		: `${escapeForDoubleQuote(trailerName)}: ${identity}`;
+	const fullMatch = mFlagMatch[0];
+	const insertPos = command.indexOf(fullMatch) + fullMatch.length - 1;
+	enfLog.info("inject_commit_trailer", "inline", trailerName);
+	return command.slice(0, insertPos) + `\n\n${escaped}` + command.slice(insertPos);
 }
 
 /** Keep the first standalone valid footer, but use the current operation's model. */

package/extensions/orchestrator/enforcement.ts

@@ -20,7 +20,8 @@ import { getProjectTmpDir, resolveWorktreeRoot } from "./utils.js";
 import {
   conflictCandidateDirs,
   pushTargetsProtectedBranch,
-  fixUnexpandedCommitTrailer,
+  findPlaceholderTrailer,
+  messageFileTrailerState,
   maskQuotedRegions,
   isStdinFedShellStatement,
 } from "./enforcement-helpers.js";
@@ -53,6 +54,7 @@ import {
   gitSubArgRegions,
   hasGitAddBulk,
   hasGitAddForce,
+  injectCommitTrailer,
   injectSignoff,
   injectGhBodySignature,
   isGitIdentityConfigPath,
@@ -118,9 +120,23 @@ function writeRepeatState(state: { lastCmd: string; count: number }): void {
 
 
 
+/** Placeholder strings that are never a real model id — printing one in a trailer ships a bug. */
+const PLACEHOLDER_MODEL_IDS = new Set(["model", "pi_model", "$pi_model", "${pi_model}", "unknown"]);
+
 /** Resolve the model id used in commit/PR trailers (env first, then ctx). */
-function commitTrailerModelId(ctx: any): string {
-  return (process.env.PI_PRIMARY_MODEL || process.env.PI_MODEL || (ctx as any).model?.id || "unknown").replace(/[^a-zA-Z0-9._:@/ -]/g, "").trim() || "unknown";
+export function commitTrailerModelId(ctx: any): string {
+  for (const raw of [process.env.PI_PRIMARY_MODEL, process.env.PI_MODEL, (ctx as any).model?.id]) {
+    const trimmed = (raw ?? "").trim();
+    if (!trimmed) continue;
+    if (PLACEHOLDER_MODEL_IDS.has(trimmed.toLowerCase())) {
+      log.debug("commit_trailer: skipped placeholder model id", trimmed);
+      continue;
+    }
+    const clean = trimmed.replace(/[^a-zA-Z0-9._:@/ -]/g, "").trim();
+    if (clean) return clean;
+  }
+  log.warn("commit_trailer: no model id resolved — trailer identity is unknown");
+  return "unknown";
 }
 
 /** Inject commit trailer into command (Assisted-by, Co-authored-by, etc.) */
@@ -128,18 +144,20 @@ function commitTrailerModelId(ctx: any): string {
 let bridgedUi: ReturnType<typeof createBridgedUi> | null = null;
 
 async function handleCommitTrailer(command: string, event: any, ctx: any, gitCwd: string): Promise<EnforcementResult> {
-  // #932: rewrite a literal `$PI_MODEL` in the trailer identity — an agent
-  // following the git-expert trailer instruction may write the placeholder
-  // verbatim (quoted heredocs and single-quoted -m strings never expand it).
-  // This runs BEFORE the setting check and pattern matching so heredoc/-F
-  // commits — which the injection patterns below do not cover — still get a
-  // correct trailer, and the dedup check below sees the already-fixed name.
-  const literalModelId = commitTrailerModelId(ctx);
-  const fixedCommand = fixUnexpandedCommitTrailer(command, literalModelId);
-  if (fixedCommand !== null) {
-    log.info("commit_trailer: replaced unexpanded $PI_MODEL literal with model id", literalModelId);
-    command = fixedCommand;
-    event.input.command = fixedCommand;
+  // A placeholder trailer is REFUSED, never rewritten: the hook cannot safely tell
+  // command text from message prose (a commit message quoting the very shape it
+  // parses, a `;` inside quotes, indented examples), and rewriting the wrong span
+  // corrupts a message or edits an unrelated command. The agent has the text, so it
+  // fixes it and retries (Qodo, PR #1004).
+  const placeholder = findPlaceholderTrailer(command);
+  if (placeholder) {
+    return {
+      block: true,
+      reason:
+        `⛔ Commit refused: the trailer carries an unresolved placeholder (${placeholder}). ` +
+        `Write \`TRAILER: PI (${commitTrailerModelId(ctx)})\` instead of a MODEL/$PI_MODEL placeholder ` +
+        "and re-run the commit.",
+    };
   }
 
   const trailerSetting = getSetting(gitCwd, "commit_trailer");
@@ -147,7 +165,6 @@ async function handleCommitTrailer(command: string, event: any, ctx: any, gitCwd
 
   const modelId = commitTrailerModelId(ctx);
 
-  const piIdentity = `PI (${modelId}) <noreply@pi.dev>`;
   let trailerName: string;
 
   if (trailerSetting.includes(",")) {
@@ -184,55 +201,54 @@ async function handleCommitTrailer(command: string, event: any, ctx: any, gitCwd
     trailerName = trailerSetting;
   }
 
-  // Pattern A: echo "..." | git commit -F -
-  const pipeIdx = command.lastIndexOf("|");
-  if (pipeIdx !== -1 && /git\s+commit\s+.*-F\s*-/.test(command.slice(pipeIdx))) {
-    const echoPart = command.slice(0, pipeIdx);
-    const gitPart = command.slice(pipeIdx);
-    const lastDoubleQuote = echoPart.lastIndexOf('"');
-    const lastSingleQuote = echoPart.lastIndexOf("'");
-    const lastQuoteIdx = Math.max(lastDoubleQuote, lastSingleQuote);
-    if (lastQuoteIdx > 0) {
-      // Determine quote context for correct escaping
-      const quoteChar = echoPart[lastQuoteIdx];
-      // Scope dedup to the echo/message-construction portion (before the pipe), which
-      // excludes the git args. Do NOT attempt to slice out the exact quoted substring
-      // by backward-scanning for a quote — escaped quotes (\") inside the message would
-      // misparse the boundary and cause a missed trailer -> duplicate injection.
-      if (commandHasTrailerByName(echoPart, trailerName)) {
-        log.debug("commit_trailer already present in echo message (by name) — skipping injection", trailerName);
-        return undefined;
-      }
-      const escaped = quoteChar === "'"
-        ? `${escapeForSingleQuote(trailerName)}: ${piIdentity}`
-        : `${escapeForDoubleQuote(trailerName)}: ${piIdentity}`;
-      event.input.command =
-        echoPart.slice(0, lastQuoteIdx) + `\\n\\n${escaped.replace(/\n/g, "\\n")}` + echoPart.slice(lastQuoteIdx) + gitPart;
-    }
+  const injected = injectCommitTrailer(command, trailerName, modelId);
+  if (injected !== null) {
+    event.input.command = injected;
+    return undefined;
   }
-  // Pattern B: git commit -m "..." or git commit -m '...'
-  else {
-    const mFlagMatch = command.match(/git\s+commit\s+.*-m\s+(["'])([\s\S]*?)\1/);
-    if (mFlagMatch) {
-      const quoteChar = mFlagMatch[1];
-      // Scope duplicate-by-name detection to the -m message payload only
-      // (mFlagMatch[2]) — not the whole command — so an unrelated arg/env var
-      // containing the trailer token does not wrongly skip injection.
-      const payload = mFlagMatch[2];
-      if (commandHasTrailerByName(payload, trailerName)) {
-        log.debug("commit_trailer already present in message (by name) — skipping injection", trailerName);
-        return undefined;
-      }
-      const escaped = quoteChar === "'"
-        ? `${escapeForSingleQuote(trailerName)}: ${piIdentity}`
-        : `${escapeForDoubleQuote(trailerName)}: ${piIdentity}`;
-      const fullMatch = mFlagMatch[0];
-      const insertPos = command.indexOf(fullMatch) + fullMatch.length - 1;
-      event.input.command =
-        command.slice(0, insertPos) + `\n\n${escaped}` + command.slice(insertPos);
+  // `git commit -F <file>`: the message is a file we CAN read, so check it instead of
+  // guessing. Refusing a message that already carries the trailer would block the very
+  // flow the git-expert instruction describes (Qodo, PR #1004).
+  const fileMessage = command.match(/git\s+commit\b[^\n]*?-F\s+(?!-)(["']?)([^\s"']+)\1/);
+  if (fileMessage && fileMessage[2]) {
+    // The read happens BEFORE the command runs, so a command that writes the same file
+    // would be verified against its OLD contents while git commits the new ones. Refuse
+    // that shape instead of trusting the stale read (Qodo, PR #1004).
+    const filePathSrc = fileMessage[2].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (bashWritesToPath(command, maskQuotedRegions(command), filePathSrc)) {
+      log.warn("commit_trailer: message file is written by the same command", fileMessage[2]);
+      return {
+        block: true,
+        reason:
+          `⛔ Commit refused: this command writes ${fileMessage[2]} and commits it in the same call, ` +
+          "so the message cannot be verified before it is read. Write the message (with the trailer) in one call and commit in the next.",
+      };
+    }
+    const candidate = path.isAbsolute(fileMessage[2]) ? fileMessage[2] : join(gitCwd, fileMessage[2]);
+    const state = messageFileTrailerState(candidate, trailerName, (p) => readFileSync(p, "utf8"));
+    if (state === "has") {
+      log.debug("commit_trailer: message file already carries the trailer", candidate);
+      return undefined;
+    }
+    if (state === "missing") {
+      return {
+        block: true,
+        reason:
+          `⛔ Commit refused: the message file ${fileMessage[2]} has no \`${trailerName}\` trailer. ` +
+          `Append it with the real id — \`printf '\\n\\n" + trailerName + ": PI (%s)\\n' \"$PI_MODEL\" >> " + fileMessage[2] + "\` — then re-run the commit.`,
+      };
     }
   }
-
+  // Other opaque shapes must carry the trailer already; refusing beats guessing.
+  if (!commandHasTrailerByName(command, trailerName)) {
+    return {
+      block: true,
+      reason:
+        `⛔ Commit refused: no \`${trailerName}\` trailer found and this commit shape is opaque to the hook ` +
+        `(the message is built in a way it cannot inspect). Add \`${trailerName}: PI (${modelId})\` to the message ` +
+        "yourself — e.g. `printf '\\n\\n" + trailerName + ": PI (%s)\\n' \"$PI_MODEL\" >> <file>` for `-F <file>` — then re-run the commit.",
+    };
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.22.3",
+  "version": "4.22.4",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"

package/rules/00-orchestrator-core.md

@@ -34,6 +34,8 @@ Outside slash commands, never use edit, write, or bash directly (except `codemod
 
 ## Before Implementation (MANDATORY)
 
+**For 2+ distinct actions, your first action is one `TaskBulkCreate` listing every step** — before the first edit or the first agent call (see `60-task-tracking.md`).
+
 Before ANY code changes, run the pre-implementation checklist:
 
 → **See the "Pre-Implementation Checklist" section below** — Do NOT skip this step.

package/rules/60-task-tracking.md

@@ -7,58 +7,37 @@
 
 ---
 
-## When to Create Tasks
+## When Tasks Are Required
 
-**BEFORE starting any multi-step workflow (3+ steps)**, use `TaskCreate` to list ALL steps first.
+The request needs **2+ distinct actions** — then tasks are required:
 
-**Use tasks for:** feature implementation, bug fixes with multiple files,
-workflows from `rules/05-issue-first-workflow.md` or `rules/20-code-review-loop.md`,
-multi-file refactoring, or any work involving more than 2 actions.
+- more than one file to change, or code plus tests plus docs
+- any workflow from `05-issue-first-workflow.md` or `20-code-review-loop.md`
+- the user lists several things to do ("do X, then Y", numbered items)
+- work conditioned on a future event ("after Qodo approves, deploy and test") — create the tasks now, put the trigger in the description, and block the dependents on it
 
-**Deferred missions count as multi-step work.** When the user assigns work
-conditional on a future event ("after X", "once Y", "when Z"), create the
-tasks IMMEDIATELY in that same turn — the trigger condition goes in the task
-description, and dependent tasks block on the trigger task. Never carry a
-deferred mission only in conversation memory: compaction or a session
-restart loses it silently.
+**No tasks:** a single-step action, a one-file/one-line change, a question, an explanation, read-only investigation.
 
-- ❌ BAD: "after Qodo approves, deploy and test" → acknowledged, no task
-- ✅ GOOD: `TaskCreate("Deploy X locally — trigger: Qodo R6 clean")` + blocked follow-ups
+## First Action
 
-**Skip tasks for:** single-step actions, questions/explanations, or trivial fixes.
+Plan the whole job in **one `TaskBulkCreate` call** listing every step — not one `TaskCreate` per step, and not after the first edit. `TaskCreate` is for a single step added later.
 
----
-
-## Task Granularity
+When `TaskCreate`'s own tool description suggests per-step calls, **this rule wins**: one bulk call for the whole job.
 
-Tasks MUST be **detailed and specific** — not high-level summaries.
+## Granularity
 
-- ❌ BAD: `Implement the fix` / `Review code` / `Create PR`
-- ✅ GOOD: `Edit extensions/orchestrator/utils.ts — add timeout parameter to fetchData()` / `Run code review loop (3 async reviewers)` / `Create PR with description`
+One concrete action per task: which file, which change.
 
----
+- ❌ `Implement the fix` / `Create PR`
+- ✅ `Edit extensions/orchestrator/utils.ts — add timeout parameter to fetchData()` / `Create PR with the test plan`
 
-## Task Lifecycle (MANDATORY)
+## Lifecycle
 
-Create all tasks BEFORE starting work via `TaskCreate`.
-Mark each `in_progress` before starting and `completed` immediately after finishing via `TaskUpdate`.
-Work through tasks in order — do not skip tasks or start new work while unchecked tasks exist (unless user explicitly pivots).
-
----
+`in_progress` before starting a task, `completed` immediately after. Work in order. Never abandon a task — drop a stale one with `TaskUpdate status: "deleted"`.
 
 ## Side Questions
 
-Answer the question, then resume the next unchecked task immediately — the persistent task list tells you exactly where you left off.
-
----
-
-## Integration & Key Rules
-
-Task tracking works alongside existing workflow rules — include issue-first, code review, and documentation steps as individual tasks.
-{{IF:task_reminder_enabled}}
-Tasks are code-enforced (reminders after 4+ ignored turns).
-{{/IF}}
-Never abandon tasks — if scope changes, use `TaskUpdate` with `status: "deleted"` to remove obsolete tasks; the task list is your contract.
+Answer the question, then resume the next unchecked task — the task list says where you left off.
 
 ---