@jwilger/pi-development-system 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/skills/delivery-discipline/SKILL.md

@@ -22,6 +22,14 @@ the issue time. Sessions outliving their grant is a security defect, so the
 check now uses expiry; clock-skew tolerance is deliberately not added.
 ```
 
+```text
+refactor(billing): extract invoice totals into a pure function
+
+Totals were computed inline in three handlers, so each fix had to land three
+times. Behaviour is unchanged (tests untouched); the next commit adds the
+rounding rule on top of this seam.
+```
+
 - Do not write a body that only restates the diff. The diff already says what;
   the body is the only place the reason survives.
 - Do not add `Co-Authored-By`, "Generated with" or any AI trailer. This is
@@ -41,8 +49,10 @@ check now uses expiry; clock-skew tolerance is deliberately not added.
 
 Do not start unrelated work while trunk CI is red. Fix it first; a red build
 hides every later failure. A push to a red trunk is a hard stop unless the
-commit is a `fix` and Jev reads its diff as only repairing the failing run (it needs
-the failing log and Jev online; otherwise the push is a hard stop). If `gh`
+commit is `fix(ci): …` (or another `fix`), touches only what the failing log names, and
+stays small (an unpushed diff over 8000 characters is never exempt); Jev must read it as
+only repairing the failing run, which needs the failing log and Jev online. Otherwise the
+push is a hard stop. If `gh`
 is missing or unauthenticated, CI reads as unknown and the push is allowed:
 check CI by other means before relying on it.
 

package/src/core/commit-command.ts

@@ -1,3 +1,4 @@
+import { splitLines } from "./git-intent.ts";
 import { resolveGit } from "./git-invocations.ts";
 
 export type CommitExtraction =
@@ -7,20 +8,21 @@ export type CommitExtraction =
   | { readonly kind: "unknown"; readonly trailers: readonly string[] };
 
 const HEREDOC =
-  /<<-?[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[^\n]*\n([\s\S]*?)\n[ \t]*\2[ \t]*(?:\n|$)/g;
-
-/** Heredoc bodies are data: take them out so their quotes cannot confuse line splitting. */
-function stripHeredocs(command: string): { rest: string; bodies: Heredoc[] } {
-  const bodies: Heredoc[] = [];
+  /<<-?[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1([^\n]*)\n([\s\S]*?)\n[ \t]*\2[ \t]*(?:\n|$)/g;
+
+/**
+ * Heredoc bodies are data: take them out so their quotes cannot confuse line splitting. The rest of
+ * the opening line stays (`| git commit -F -`) with a `#HD<n>` marker naming the removed body.
+ */
+function stripHeredocs(command: string): { rest: string; bodies: string[] } {
+  const bodies: string[] = [];
   const rest = command.replace(HEREDOC, (...m: unknown[]) => {
-    bodies.push({ body: String(m[3]), at: Number(m[m.length - 2]) });
-    return "\n";
+    bodies.push(String(m[4]).trim());
+    return `${String(m[3])} #HD${bodies.length - 1}\n`;
   });
   return { rest, bodies };
 }
 
-type Heredoc = { readonly body: string; readonly at: number };
-
 type Options = {
   messages: string[];
   trailers: string[];
@@ -35,10 +37,11 @@ type Parsed = {
   readonly next: number;
 };
 
-const LONG: ReadonlyArray<readonly [string, Parsed["kind"]]> = [
-  ["--message", "message"],
-  ["--file", "file"],
-  ["--trailer", "trailer"],
+/** Option, kind and the shortest prefix git still resolves uniquely (`--fi` would be `--fixup`). */
+const LONG: ReadonlyArray<readonly [string, Parsed["kind"], number]> = [
+  ["--message", "message", 4],
+  ["--file", "file", 5],
+  ["--trailer", "trailer", 4],
 ];
 
 /** The option a `--name`/`--na=value` spelling means; git accepts any unambiguous prefix (3+ chars). */
@@ -46,11 +49,9 @@ function longOption(arg: string): { kind: Parsed["kind"]; inline: string | undef
   if (!arg.startsWith("--")) return undefined;
   const eq = arg.indexOf("=");
   const name = eq < 0 ? arg : arg.slice(0, eq);
-  if (name.length < 5) return undefined;
-  const hit = LONG.find(([long]) => long.startsWith(name));
-  return hit === undefined
-    ? undefined
-    : { kind: hit[1], inline: eq < 0 ? undefined : arg.slice(eq + 1) };
+  const hit = LONG.find(([long, , min]) => name.length >= min && long.startsWith(name));
+  if (hit === undefined) return undefined;
+  return { kind: hit[1], inline: eq < 0 ? undefined : arg.slice(eq + 1) };
 }
 
 /** Reads the message/file/trailer option starting at args[i], in any of its spellings. */
@@ -71,17 +72,22 @@ function parseArg(args: readonly string[], i: number): Parsed | undefined {
   return undefined;
 }
 
+/** A value that is itself a substitution or variable (not prose that mentions backticks). */
+const OPAQUE_VALUE = /^\s*(?:\$\(|`)|^\$\{?\w+\}?$/;
+
+function record(options: Options, parsed: Parsed): void {
+  if (parsed.kind === "file") options.file = parsed.value;
+  else if (parsed.kind === "trailer") options.trailers.push(parsed.value ?? "");
+  else if (parsed.value === undefined || OPAQUE_VALUE.test(parsed.value)) options.opaque = true;
+  else options.messages.push(parsed.value);
+}
+
 function readOptions(args: readonly string[]): Options {
   const options: Options = { messages: [], trailers: [], file: undefined, opaque: false };
-  let i = 0;
-  while (i < args.length) {
+  for (let i = 0; i < args.length; ) {
     const parsed = parseArg(args, i);
+    if (parsed !== undefined) record(options, parsed);
     i = parsed?.next ?? i + 1;
-    if (parsed === undefined) continue;
-    if (parsed.kind === "file") options.file = parsed.value;
-    else if (parsed.kind === "trailer") options.trailers.push(parsed.value ?? "");
-    else if (parsed.value === undefined || /\$\(|`/.test(parsed.value)) options.opaque = true;
-    else options.messages.push(parsed.value);
   }
   return options;
 }
@@ -92,18 +98,22 @@ const unknown = (trailers: readonly string[] = []): CommitExtraction => ({
 });
 
 const STDIN_PATHS = new Set(["-", "/dev/stdin", "/proc/self/fd/0"]);
+const MARKER = /#HD(\d+)/g;
 
-/** The heredoc that is this commit's input: the first one written after the word `commit`. */
-const heredocFor = (command: string, bodies: readonly Heredoc[]): string | undefined => {
-  const from = command.search(/\bcommit\b/);
-  return bodies.find((h) => h.at >= from)?.body.trim();
+/** Body of the first heredoc opened on this line or later (its stdin, or the `$(cat <<EOF)` message). */
+const heredocFrom = (lines: readonly string[], line: number, bodies: readonly string[]) => {
+  for (const text of lines.slice(line)) {
+    const hit = [...text.matchAll(MARKER)][0];
+    if (hit !== undefined) return bodies[Number(hit[1])];
+  }
+  return undefined;
 };
 
 function extractOne(args: readonly string[], heredoc: string | undefined): CommitExtraction {
   const options = readOptions(args);
   if (options.file !== undefined && STDIN_PATHS.has(options.file)) {
     return heredoc === undefined
-      ? unknown(options.trailers)
+      ? { kind: "file", path: "-" }
       : { kind: "message", message: heredoc };
   }
   if (options.file !== undefined) return { kind: "file", path: options.file };
@@ -121,9 +131,10 @@ function extractOne(args: readonly string[], heredoc: string | undefined): Commi
 export function extractCommits(command: string): CommitExtraction[] {
   const { rest, bodies } = stripHeredocs(command);
   const resolution = resolveGit(rest);
-  const heredoc = heredocFor(command, bodies);
-  const commits = resolution.invocations.filter((g) => g.sub === "commit");
-  const found = commits.map((g) => extractOne(g.args, heredoc));
+  const lines = splitLines(rest);
+  const found = resolution.invocations.flatMap((g) =>
+    g.sub === "commit" ? [extractOne(g.args, heredocFrom(lines, g.line, bodies))] : [],
+  );
   const hidden = resolution.opaque && /\bcommit\b/.test(command);
   return hidden ? [...found, unknown()] : found;
 }

package/src/core/commit-message.ts

@@ -93,7 +93,8 @@ export function findForbiddenTrailers(
     });
 }
 
-const AI_TRAILER_ANYWHERE = /(?:co-authored-by|generated-by)\s*[:=]/gi;
+const AI_TRAILER_ANYWHERE =
+  /(?:co-authored-by|generated-by)\s*[:=]|signed-off-by\s*[:=][^\n]*\b(?:ai|claude|copilot|codex|gpt|chatgpt|openai|anthropic|gemini|llm)\b/gi;
 
 /** AI-attribution trailer keys anywhere in free text (command lines, quoted strings, printf bodies). */
 export function findForbiddenTrailerKeys(text: string): string[] {

package/src/core/git-invocations.ts

@@ -19,6 +19,8 @@ export type GitInvocation = {
   readonly args: readonly string[];
   /** Directory the command runs in, relative to the starting one (from `cd` and `git -C`), when it moved. */
   readonly dir?: string;
+  /** Index of the (newline-split) line of the top-level command this invocation sits on. */
+  readonly line: number;
 };
 
 export type GitResolution = {
@@ -27,7 +29,12 @@ export type GitResolution = {
   readonly opaque: boolean;
 };
 
-type Collector = { invocations: GitInvocation[]; opaque: boolean; dir: string | undefined };
+type Collector = {
+  invocations: GitInvocation[];
+  opaque: boolean;
+  dir: string | undefined;
+  line: number;
+};
 
 const firstCommand = (tokens: readonly string[]): number => {
   const at = tokens.findIndex((t) => !(isAssignment(t) || WRAPPERS.has(t) || KEYWORDS.has(t)));
@@ -53,7 +60,8 @@ function visitGit(rest: readonly string[], into: Collector): void {
   if (sub.startsWith("$")) into.opaque = true;
   else {
     const args = rest.slice(j + 1);
-    into.invocations.push(dir === undefined ? { sub, args } : { sub, args, dir });
+    const line = into.line;
+    into.invocations.push(dir === undefined ? { sub, args, line } : { sub, args, dir, line });
   }
 }
 
@@ -85,14 +93,17 @@ function visitSegment(tokens: readonly string[], into: Collector): void {
   else if (SHELLS.has(base) || base === "eval") visitScript(base, rest, into);
   else if (OPAQUE.has(base)) into.opaque = into.opaque || gitIndex(rest) >= 0;
   else if (base === "git") visitGit(rest, into);
-  else if (!DATA_ONLY.has(base) && gitIndex(rest) >= 0) {
-    // Wrapper with options (`sudo -E git …`, `timeout 5 git …`): resolve from the git token.
-    visitSegment(rest.slice(gitIndex(rest)), into);
-  }
+  else visitWrapped(base, rest, into);
+}
+
+/** Wrapper with options (`sudo -E git …`, `timeout 5 git …`): resolve from the git token. */
+function visitWrapped(base: string, rest: readonly string[], into: Collector): void {
+  const at = gitIndex(rest);
+  if (!DATA_ONLY.has(base) && at >= 0) visitSegment(rest.slice(at), into);
 }
 
 function merge(into: Collector, other: GitResolution): void {
-  into.invocations.push(...other.invocations);
+  into.invocations.push(...other.invocations.map((g) => ({ ...g, line: into.line })));
   if (other.opaque) into.opaque = true;
 }
 
@@ -101,9 +112,11 @@ function merge(into: Collector, other: GitResolution): void {
  * `timeout`, `if … then`), `bash -c`/`eval` scripts and `$(…)` substitutions. Heredoc bodies are data.
  */
 export function resolveGit(command: string): GitResolution {
-  const into: Collector = { invocations: [], opaque: false, dir: undefined };
+  const into: Collector = { invocations: [], opaque: false, dir: undefined, line: 0 };
   let heredocEnd: string | undefined;
-  for (const line of splitLines(command)) {
+  const lines = splitLines(command);
+  for (const [index, line] of lines.entries()) {
+    into.line = index;
     if (heredocEnd !== undefined) {
       if (line.trim() === heredocEnd) heredocEnd = undefined;
       continue;

package/src/core/push-command.ts

@@ -5,6 +5,10 @@ export type PushTarget = {
   /** Destination branch names named by refspecs; empty means "the current branch's default". */
   readonly branches: readonly string[];
   readonly allBranches: boolean;
+  /** The refspecs name `HEAD`, so the current branch is pushed too. */
+  readonly usesHead: boolean;
+  /** `--tags` with no refspec: only tags are pushed, no branch. */
+  readonly tagsOnly: boolean;
   /** Where the push runs when `cd`/`git -C` moved it away from the session's directory. */
   readonly dir?: string | undefined;
 };
@@ -12,17 +16,26 @@ export type PushTarget = {
 const VALUE_OPTIONS = new Set(["--repo", "-o", "--push-option", "--receive-pack", "--exec"]);
 const isDynamic = (refspec: string): boolean => /[$`*?[]/.test(refspec);
 
+/** A dry run pushes nothing. */
+const isDryRun = (args: readonly string[]): boolean =>
+  args.some((a) => a === "--dry-run" || a === "-n" || /^-[a-zA-Z]*n[a-zA-Z]*$/.test(a));
+
 const destination = (refspec: string): string => {
   const dst = refspec.includes(":") ? refspec.slice(refspec.lastIndexOf(":") + 1) : refspec;
   return dst.replace(/^\+/, "").replace(/^(?:refs\/)?heads\//, "");
 };
 
-type ParsedArgs = { positional: string[]; all: boolean; repo: string | undefined };
+type ParsedArgs = {
+  positional: string[];
+  all: boolean;
+  tags: boolean;
+  repo: string | undefined;
+};
 
 const VALUE_PREFIX = "--repo=";
 
 function positionalArgs(args: readonly string[]): ParsedArgs {
-  const parsed: ParsedArgs = { positional: [], all: false, repo: undefined };
+  const parsed: ParsedArgs = { positional: [], all: false, tags: false, repo: undefined };
   let valueFor: "repo" | "skip" | undefined;
   for (const a of args) {
     if (valueFor === "repo") parsed.repo = a;
@@ -31,13 +44,14 @@ function positionalArgs(args: readonly string[]): ParsedArgs {
     else if (a.startsWith(VALUE_PREFIX)) parsed.repo = a.slice(VALUE_PREFIX.length);
     else if (VALUE_OPTIONS.has(a)) valueFor = "skip";
     else if (a === "--all" || a === "--mirror") parsed.all = true;
+    else if (a === "--tags") parsed.tags = true;
     else if (!a.startsWith("-")) parsed.positional.push(a);
   }
   return parsed;
 }
 
 const toTarget = (args: readonly string[], dir: string | undefined): PushTarget => {
-  const { positional, all, repo } = positionalArgs(args);
+  const { positional, all, tags, repo } = positionalArgs(args);
   // With --repo, every positional argument is a refspec.
   const [remote, ...refspecs] = repo === undefined ? positional : [repo, ...positional];
   const destinations = refspecs.map(destination);
@@ -46,6 +60,8 @@ const toTarget = (args: readonly string[], dir: string | undefined): PushTarget
     remote,
     branches: destinations.filter(named),
     allBranches: all || destinations.some(isDynamic),
+    usesHead: destinations.includes("HEAD"),
+    tagsOnly: tags && refspecs.length === 0 && !all,
     ...(dir === undefined ? {} : { dir }),
   };
 };
@@ -54,11 +70,21 @@ const toTarget = (args: readonly string[], dir: string | undefined): PushTarget
 export function pushTargets(command: string): PushTarget[] {
   const resolution = resolveGit(command);
   const targets = resolution.invocations.flatMap((g) =>
-    g.sub === "push" ? [toTarget(g.args, g.dir)] : [],
+    g.sub === "push" && !isDryRun(g.args) ? [toTarget(g.args, g.dir)] : [],
   );
   // git run through something opaque (xargs, `$CMD`): a push cannot be ruled out, so assume the worst.
   const opaquePush = resolution.opaque && /\bpush\b/.test(command);
   return opaquePush
-    ? [...targets, { remote: undefined, branches: [], allBranches: true }]
+    ? [
+        ...targets,
+        {
+          remote: undefined,
+          branches: [],
+          allBranches: true,
+          usesHead: false,
+          tagsOnly: false,
+          dir: undefined,
+        },
+      ]
     : targets;
 }

package/src/gates/commit-guard.ts

@@ -61,15 +61,21 @@ function messageNeeds(message: string): Need[] {
     : [{ gate: RATIONALE, why: "the message has no body explaining why the change was made" }];
 }
 
-/** What is about to be committed, as far as the working tree shows (staged and unstaged tracked changes). */
+/** `-a`/`--all`, or a `git add` in the same command, widen the commit beyond what is staged. */
+const stagesEverything = (command: string): boolean =>
+  /(?:^|\s)(?:-[a-zA-Z]*a[a-zA-Z]*|--all|--include)(?:\s|$)|\bgit\s+add\b/.test(command);
+
+/** What is about to be committed: the staged changes, or every tracked change when the commit stages them itself. */
 async function pendingDiff(
   exec: Exec,
   cwd: string,
+  command: string,
 ): Promise<{ stat: string; diff: string } | undefined> {
   try {
+    const base = stagesEverything(command) ? ["diff", "HEAD"] : ["diff", "--cached"];
     const [stat, diff] = await Promise.all([
-      exec("git", ["diff", "HEAD", "--stat"], { cwd, timeout: 10_000 }),
-      exec("git", ["diff", "HEAD"], { cwd, timeout: 10_000 }),
+      exec("git", [...base, "--stat"], { cwd, timeout: 10_000 }),
+      exec("git", base, { cwd, timeout: 10_000 }),
     ]);
     if (stat.code !== 0 || diff.code !== 0 || diff.stdout.trim() === "") return undefined;
     return { stat: stat.stdout, diff: diff.stdout };
@@ -83,8 +89,9 @@ async function jevNeeds(
   ctx: ExtensionContext,
   message: string,
   bodyPresent: boolean,
+  command: string,
 ): Promise<Need[]> {
-  const pending = await pendingDiff(deps.exec, ctx.cwd);
+  const pending = await pendingDiff(deps.exec, ctx.cwd, command);
   if (pending === undefined) return [];
   const judged = await judgeCommit(deps.jev(ctx), {
     message,
@@ -131,10 +138,11 @@ async function needsOf(
   deps: CommitGuardDeps,
   ctx: ExtensionContext,
   message: string,
+  command: string,
 ): Promise<Need[]> {
   const needs = messageNeeds(message);
   const bodyPresent = !needs.some((n) => n.why.startsWith("the message has no body"));
-  const viaJev = await jevNeeds(deps, ctx, message, bodyPresent);
+  const viaJev = await jevNeeds(deps, ctx, message, bodyPresent, command);
   return [...needs, ...viaJev.filter((n) => !needs.some((m) => m.gate === n.gate))];
 }
 
@@ -152,8 +160,15 @@ export function registerCommitGuard(deps: CommitGuardDeps): void {
 
     const known = messages.flatMap((m) => (m === undefined ? [] : [m]));
     const all: Need[] = [];
+    // A -F file that cannot be read now (written by this same command, or stdin) cannot be checked.
+    if (extractions.some((e, i) => e.kind === "file" && messages[i] === undefined)) {
+      all.push({
+        gate: RATIONALE,
+        why: "the message file cannot be read before the commit runs, so its rationale cannot be checked; use -m or a heredoc",
+      });
+    }
     for (const message of known) {
-      for (const need of await needsOf(deps, ctx, message)) {
+      for (const need of await needsOf(deps, ctx, message, command)) {
         if (!all.some((n) => n.gate === need.gate)) all.push(need);
       }
     }

package/src/gates/push-guard.ts

@@ -32,6 +32,7 @@ const gate = (id: string): GateId => {
   if (isParseError(parsed)) throw new Error(parsed.message);
   return parsed;
 };
+const FIX_DIFF_LIMIT = 8000;
 const RED_TRUNK = gate("push.red-trunk");
 const DELIVERY_MODE = gate("push.delivery-mode");
 
@@ -54,7 +55,12 @@ async function pushesTrunk(
   for (const t of targets) {
     if (t.allBranches || t.branches.includes(trunk)) return true;
     const where = t.dir === undefined ? cwd : resolve(cwd, t.dir);
-    if (t.branches.length === 0 && (await currentBranch(exec, where)) === trunk) return true;
+    if (t.tagsOnly) continue;
+    if (t.branches.length === 0 || t.usesHead) {
+      // No refspec: the current branch decides. When it cannot be read, assume it is the trunk.
+      const branch = await currentBranch(exec, where);
+      if (branch === undefined || branch === trunk) return true;
+    }
   }
   return false;
 }
@@ -74,7 +80,10 @@ async function repairsRedTrunk(
   if (message.code !== 0 || !parsed.ok || parsed.value.type !== "fix") return false;
   const range = `${config.delivery.remote}/${config.delivery.trunk}..HEAD`;
   const diff = await deps.exec("git", ["diff", range], { cwd: ctx.cwd, timeout: 10_000 });
-  if (diff.code !== 0 || diff.stdout.trim() === "") return false;
+  // Jev only reads a bounded diff; a longer range could hide unrelated change past what it sees.
+  if (diff.code !== 0 || diff.stdout.trim() === "" || diff.stdout.length > FIX_DIFF_LIMIT) {
+    return false;
+  }
   const failingLog = await getFailureLog(deps.exec, ctx.cwd, runId);
   if (failingLog.trim() === "") return false; // nothing to compare the diff against: fail closed
   const judged = await judgeFixRelated(deps.jev(ctx), {

package/src/state/ci-watch.ts

@@ -23,7 +23,11 @@ export async function watchCi(options: WatchOptions): Promise<CiState> {
       branch: options.branch,
       cwd: options.cwd,
     });
-    const stale = options.expectSha !== undefined && trunk.headSha !== options.expectSha;
+    // `gh` missing or no runs at all (no sha) is unknown, not a run that has yet to appear.
+    const stale =
+      options.expectSha !== undefined &&
+      trunk.headSha !== undefined &&
+      trunk.headSha !== options.expectSha;
     const status = stale ? "pending" : trunk.status;
     last = trunk.headSha === undefined ? { status } : { status, sha: trunk.headSha };
     options.onObserved(last);