agentic-retro 0.1.1 → 0.1.3

package/cli/lib/commands.js

@@ -1,5 +1,5 @@
 // Builds the command that starts the batch agent in each harness.
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -37,7 +37,15 @@ function sessionsOf(batchDir) {
 }
 
 function workDirs(config, sessions) {
-  const paths = [...sessions.map((s) => s.repo), ...(config.editable ?? []).map(expandHome)];
+  const editable = (config.editable ?? []).map((path) => {
+    path = expandHome(path);
+    try {
+      return statSync(path).isFile() ? dirname(path) : path;
+    } catch {
+      return path;
+    }
+  });
+  const paths = [...sessions.flatMap((s) => [s.repo, s.cwd]), ...editable];
   return [...new Set(paths.filter(Boolean))];
 }
 

package/cli/lib/outcomes.js

@@ -39,7 +39,7 @@ export function syncOutcomes() {
     if (status !== 'open') setStatus(p, status);
   }
 
-  for (const p of open()) {
+  for (const p of open().filter((p) => !p.pr)) {
     if (ledger.batchCount - p.batch >= expireAfterBatches) setStatus(p, 'expired');
   }
   saveLedger(ledger);

package/cli/lib/pi-extension.ts

@@ -2,27 +2,126 @@
 // Queues each finished session for a retro and shows new proposals at session start.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { execFile, spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const CLI = join(PACKAGE_ROOT, "cli", "agentic-retro.js");
+const SETUP_SKILL = join(PACKAGE_ROOT, "skills", "setup");
+const RUN_SKILL = join(PACKAGE_ROOT, "skills", "run");
+const REVIEW_SKILL = join(PACKAGE_ROOT, "skills", "review");
+const RETRO_SKILL = join(PACKAGE_ROOT, "skills", "retro");
+
+type CommandContext = {
+  addUserMessage?: (message: string) => void;
+  ui?: { notify: (message: string, level?: string) => void };
+};
+
+function argv(args: string) {
+  const values = [];
+  let current = "";
+  let quote = "";
+  let started = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const char = args[i];
+
+    if (quote && char === "\\" && (args[i + 1] === quote || args[i + 1] === "\\")) {
+      current += args[i + 1];
+      started = true;
+      i += 1;
+    } else if ((char === '"' || char === "'") && (!quote || quote === char)) {
+      quote = quote ? "" : char;
+      started = true;
+    } else if (/\s/.test(char) && !quote) {
+      if (started) values.push(current);
+      current = "";
+      started = false;
+    } else {
+      current += char;
+      started = true;
+    }
+  }
+
+  if (started) values.push(current);
+  return values;
+}
+
+function sendUserMessage(pi: ExtensionAPI, ctx: CommandContext, message: string) {
+  if (ctx.addUserMessage) return ctx.addUserMessage(message);
+  return pi.sendUserMessage(message);
+}
+
+function skillPrompt(skill: string, args: string) {
+  const request = args.trim();
+  return `Use the agentic-retro skill at ${skill}.${request ? `\n\nUser request: ${request}` : ""}`;
+}
+
+async function isChildTranscript(path) {
+  try {
+    const lines = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+    for await (const line of lines) {
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry?.type !== "session") continue;
+      return Object.hasOwn(entry, "parentSession");
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
 
 export default function (pi: ExtensionAPI) {
-  pi.on("session_shutdown", (event, ctx) => {
+  pi.registerCommand("agentic-retro", {
+    description: "Run the package-local agentic-retro CLI",
+    handler: async (args, ctx) => {
+      execFile(process.execPath, [CLI, ...argv(args)], (error, stdout, stderr) => {
+        const output = (stdout || stderr).trim();
+        if (output) ctx.ui.notify(output, error ? "error" : "info");
+      });
+    },
+  });
+
+  pi.registerCommand("agentic-retro:setup", {
+    description: "Run the bundled agentic-retro setup skill",
+    handler: async (args, ctx) => sendUserMessage(pi, ctx, skillPrompt(SETUP_SKILL, args)),
+  });
+  pi.registerCommand("agentic-retro:run", {
+    description: "Run the bundled agentic-retro run skill",
+    handler: async (args, ctx) => sendUserMessage(pi, ctx, skillPrompt(RUN_SKILL, args)),
+  });
+  pi.registerCommand("agentic-retro:review", {
+    description: "Run the bundled agentic-retro review skill",
+    handler: async (args, ctx) => sendUserMessage(pi, ctx, skillPrompt(REVIEW_SKILL, args)),
+  });
+  pi.registerCommand("agentic-retro:retro", {
+    description: "Run the bundled agentic-retro retro skill",
+    handler: async (args, ctx) => sendUserMessage(pi, ctx, skillPrompt(RETRO_SKILL, args)),
+  });
+
+  pi.on("session_shutdown", async (event, ctx) => {
     if (event.reason !== "quit") return; // "new", "resume", and "fork" only switch sessions
     if (process.env.AGENTIC_RETRO_RUN === "1") return; // batch agents never queue themselves
 
     const transcript = ctx.sessionManager.getSessionFile();
     if (!transcript) return; // nothing was said, so nothing was saved
+    if (await isChildTranscript(transcript)) return; // Pi sub-agent sessions are only context for their parent
 
-    const child = spawn("agentic-retro", [
-      "enqueue", "--harness", "pi",
+    const child = spawn(process.execPath, [
+      CLI, "enqueue", "--harness", "pi",
       "--session", ctx.sessionManager.getSessionId(),
       "--transcript", transcript,
       "--cwd", ctx.cwd,
     ], { detached: true, stdio: "ignore" });
-    child.on("error", () => {}); // CLI not installed: never break Pi
+    child.on("error", () => {}); // CLI missing/broken: never break Pi
     child.unref();
   });
 
   pi.on("session_start", (_event, ctx) => {
-    execFile("agentic-retro", ["notice"], (error, stdout) => {
+    execFile(process.execPath, [CLI, "notice"], (error, stdout) => {
       const line = stdout?.trim();
       if (!error && line) ctx.ui.notify(line, "info");
     });

package/cli/lib/pi.js

@@ -1,15 +1,20 @@
 // Pi has no hook config, so a small extension file stands in for the hooks.
-import { mkdirSync, copyFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), 'pi-extension.ts');
 
 export function installPi() {
   const dir = join(process.env.PI_HOME || join(homedir(), '.pi'), 'agent', 'extensions');
   mkdirSync(dir, { recursive: true });
   const file = join(dir, 'agentic-retro.ts');
-  copyFileSync(TEMPLATE, file);
+  const source = readFileSync(TEMPLATE, 'utf8').replace(
+    'const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");',
+    `const PACKAGE_ROOT = ${JSON.stringify(PACKAGE_ROOT)};`,
+  );
+  writeFileSync(file, source);
   console.log(`agentic-retro: wrote ${file}`);
 }

package/cli/lib/queue.js

@@ -1,18 +1,23 @@
 // The queue: finished sessions wait here until their group fills a batch.
 import { execFileSync } from 'node:child_process';
-import { readdirSync } from 'node:fs';
+import { createReadStream, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, basename } from 'node:path';
+import { join, basename, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
 import { readJson, writeJson } from './paths.js';
 import { loadConfig } from './config.js';
 import { startBatch } from './runner.js';
 
-function repoOf(cwd) {
+function repoOf(cwd, fallback = cwd) {
   try {
-    return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const options = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+    const commonDir = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-common-dir'], options).replace(/\n$/, '');
+    // Git lists the shared identity first: the main checkout or its separate metadata directory.
+    const worktrees = execFileSync('git', ['--git-dir', resolve(cwd, commonDir), 'worktree', 'list', '--porcelain', '-z'], options);
+    const main = worktrees.split('\0').find((field) => field.startsWith('worktree '));
+    return main ? main.slice('worktree '.length) : fallback;
   } catch {
-    return cwd;
+    return fallback;
   }
 }
 
@@ -37,14 +42,31 @@ function harnessOf(transcript) {
   return undefined;
 }
 
+async function isPiChildTranscript(transcript) {
+  if (!transcript) return false;
+  try {
+    const lines = createInterface({ input: createReadStream(transcript), crlfDelay: Infinity });
+    for await (const line of lines) {
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry?.type !== 'session') continue;
+      return Object.hasOwn(entry, 'parentSession');
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
 export async function enqueue({ harness, sessionId, transcript, cwd }) {
   if (process.env.AGENTIC_RETRO_RUN === '1') return; // batch agents never queue themselves
   transcript ||= findCodexRollout(sessionId) ?? null;
   harness ||= harnessOf(transcript);
   if (!harness || !sessionId || !cwd) throw new Error('enqueue needs a harness, session, and cwd');
+  if (harness === 'pi' && await isPiChildTranscript(transcript)) return;
 
-  const queue = readJson('queue.json', []);
-  if (queue.some((s) => s.sessionId === sessionId)) return;
+  const queue = readJson('queue.json', []).map((s) => ({ ...s, repo: repoOf(s.cwd, s.repo) }));
+  if (queue.some((s) => s.sessionId === sessionId)) return writeJson('queue.json', queue);
   const entry = { harness, sessionId, transcript, cwd, repo: repoOf(cwd), endedAt: new Date().toISOString() };
   queue.push(entry);
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "agentic-retro",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "agentic-retrospective: reviews finished agent coding sessions and proposes improvements",
   "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
   "bin": {
     "agentic-retro": "cli/agentic-retro.js"
   },
@@ -13,8 +16,22 @@
   "engines": {
     "node": ">=20"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "extensions": [
+      "cli/lib/pi-extension.ts"
+    ],
+    "skills": []
+  },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test \"test/**/*.test.js\""
   },
   "license": "MIT",
   "repository": {

package/skills/run/SKILL.md

@@ -109,20 +109,25 @@ agentic-retro propose --repo <target repo path> --category <category> [--risk lo
 
 Do this once per target repo. Skip a target with no git remote, and put its proposals in a report file instead (5b).
 
+Before you branch, read the repo's PR rules in its `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` and CI workflows, such as a `dev` base branch or a version bump.
+
 ```bash
 git -C "$repo" fetch origin
-base=$(git -C "$repo" symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')
+base=$(git -C "$repo" symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')  # override with the rules' base
 wt=$(mktemp -d)/wt
 git -C "$repo" worktree add -b "agentic-retro/batch-<n>" "$wt" "origin/$base"
 ```
 
 1. Apply each proposal in `$wt`, then commit it on its own: `git -C "$wt" add -A && git -C "$wt" commit -m "P12: <title>"`
-2. Push the branch: `git -C "$wt" push -u origin "agentic-retro/batch-<n>"`
-3. Write the body per `writing-proposals.md`, then open the PR from `$wt`: `gh pr create --base "$base" --title "<title>" --body-file <file>`
-4. Record the PR and commit on each proposal: `agentic-retro link P12 --pr <url> --commit <sha>`
-5. Remove the worktree: `git -C "$repo" worktree remove "$wt"`
-
-When `autoMergeLowRisk` is `true`, low-risk agent-setup proposals go on a second branch, `agentic-retro/batch-<n>-low-risk`, with their own PR. Merge that PR with `gh pr merge --merge` once it opens. Everything else waits for the user.
+2. Do the steps the rules require in one last commit without a proposal ID, so dropping a proposal keeps them. When a step needs a command you cannot run, say so at the top of the PR body
+3. Push the branch: `git -C "$wt" push -u origin "agentic-retro/batch-<n>"`
+4. Make sure the `agentic-retro` label exists from `$wt`: `(cd "$wt" && gh label create agentic-retro --force)`
+5. Write the body per `writing-proposals.md`, then open the PR from `$wt`: `(cd "$wt" && gh pr create --base "$base" --title "<title>" --body-file <file> --label agentic-retro)`
+6. Wait for CI with `gh pr checks <url> --watch`, then fix each failure in a new commit and push
+7. Record the PR and commit on each proposal: `agentic-retro link P12 --pr <url> --commit <sha>`
+8. Remove the worktree: `git -C "$repo" worktree remove "$wt"`
+
+When `autoMergeLowRisk` is `true`, low-risk agent-setup proposals go on a second branch, `agentic-retro/batch-<n>-low-risk`, with their own PR. Merge that PR with `gh pr merge --merge` once its checks pass. Everything else waits for the user.
 
 ## 5b. Report mode: one report file