agentic-retro 0.1.2 → 0.1.4

package/README.md

@@ -6,9 +6,11 @@ agentic-retro ("agentic-retrospective") learns from your finished coding session
 
 ```mermaid
 flowchart TD
-    A["Session ends<br/>(hook in each harness)"] --> B["CLI adds session to queue"]
+    A["Session ends<br/>(hook in each harness)"] --> P{"Project enabled?"}
+    P -->|no| Z["Stop"]
+    P -->|yes| B["CLI adds session to queue"]
     B --> C{"5 sessions queued for this repo?"}
-    C -->|no| Z["Stop"]
+    C -->|no| Z
     C -->|yes| D["CLI writes digests and metrics,<br/>and updates past proposal outcomes"]
     D --> E["Runner starts one lead agent;<br/>it runs one subagent per ticked category<br/>(Claude, Codex, Pi, or herdr pane)"]
     E --> F["Subagents write proposals,<br/>skipping anything rejected or expired before"]
@@ -17,7 +19,7 @@ flowchart TD
     H --> I["User reviews proposals"]
 ```
 
-- A session-end hook in each harness queues the session (`agentic-retro enqueue`)
+- A session-end hook queues sessions only for explicitly enabled repositories (`agentic-retro enqueue`)
 - Once a repo has 5 queued sessions (configurable), the CLI starts a batch
 - One lead agent runs per batch, and it runs one subagent per ticked category: code clarity, agent setup, repo changes
 - Agents write proposals as a PR (one per repo) or a report file, per your setup choice
@@ -73,6 +75,23 @@ Both write the same `~/.agentic-retro/config.json`:
 - which categories run, and the output mode (PR or report)
 - where agent-setup proposals land
 
+Enable collection separately in each repository you want reviewed:
+
+```sh
+agentic-retro project enable
+agentic-retro project status
+# Stop collection and startup notices for this repository:
+agentic-retro project disable
+```
+
+- Every repository starts disabled, including repositories used before this update
+- Run these commands from any worktree or subdirectory, or pass `--cwd <dir>`
+- All worktrees share the setting, including worktrees elsewhere on the machine
+- Git stores `agentic-retro.enabled` in its shared local configuration, outside tracked files
+- Separate clones require separate opt-in
+- Disabling retains queued sessions but excludes them from future batches until re-enabled
+- Disabling does not stop an already-running batch
+
 Using Pi? Run `agentic-retro install-pi` once. Pi has no hook config, so this extension queues finished Pi sessions and shows the notice.
 
 Using Codex? It asks you to trust the new session-end hook the first time a session ends after install.
@@ -88,7 +107,8 @@ Using Codex? It asks you to trust the new session-end hook the first time a sess
 
 - `agentic-retro about` – print a short intro to what agentic-retro does
 - `agentic-retro setup` – interactive config, the human alternative to the setup skill
-- `agentic-retro config list | get <key> | set <key> <value>` – read or write one config key
+- `agentic-retro config list | get <key> | set <key> <value>` – read or write one global config key
+- `agentic-retro project enable | disable | status [--cwd <dir>]` – control collection and notices for one repository
 - `agentic-retro enqueue` – add a finished session to the queue (hooks call this)
 - `agentic-retro propose` – record a new proposal (batch agents call this)
 - `agentic-retro link <id>` – attach a PR and commit to a proposal
@@ -101,4 +121,6 @@ Using Codex? It asks you to trust the new session-end hook the first time a sess
 
 ## State
 
-Everything lives under `~/.agentic-retro/` (override with `AGENTIC_RETRO_HOME`): `config.json`, `queue.json`, `ledger.json`, `metrics.jsonl`, per-batch digests, and report files.
+- Runtime state lives under `~/.agentic-retro/` (override with `AGENTIC_RETRO_HOME`): config, queue, ledger, metrics, batch digests, and reports
+- Repository activation lives in Git's shared local configuration and never enters the tracked checkout
+- Keep runtime state outside repositories; Git ignores its own metadata automatically

package/cli/agentic-retro.js

@@ -11,17 +11,19 @@ import { notice } from './lib/notice.js';
 import { stats } from './lib/stats.js';
 import { installPi } from './lib/pi.js';
 import { INTRO } from './lib/intro.js';
+import { project } from './lib/project.js';
 
 const USAGE = `usage: agentic-retro <command>
   about
   setup
+  project enable | disable | status [--cwd <dir>]
   config list | get <key> | set <key> <value>
   enqueue [--harness <h>] [--session <id> --transcript <path> --cwd <dir>]   (or hook JSON on stdin)
   propose --repo <path> --category <c> [--risk low|high] --title <t> [--pr <pr> --commit <msg>]
   mark <id> <accepted|rejected>
   link <id> [--pr <url>] [--commit <sha>]
   ledger [--status <s>[,<s>...]]
-  notice [--json]
+  notice [--json] [--cwd <dir>]
   stats [--json]
   sync
   install-pi`;
@@ -69,13 +71,14 @@ async function main() {
 
   if (command === 'setup') return setup();
   if (command === 'config') return config(positionals);
+  if (command === 'project') return project(positionals[0], flags.cwd);
   if (command === 'enqueue') return enqueueCommand(flags);
   if (command === 'propose') return console.log(propose(flags));
   if (command === 'mark') return mark(...positionals);
   if (command === 'link') return link(positionals[0], flags);
   if (command === 'ledger') return listProposals(flags.status).forEach((p) => console.log(formatProposal(p)));
   if (command === 'sync') return syncOutcomes();
-  if (command === 'notice') return notice(flags);
+  if (command === 'notice') return notice({ ...flags, cwd: flags.cwd ?? readHook().cwd ?? process.cwd() });
   if (command === 'stats') return stats(flags);
   if (command === 'install-pi') return installPi();
   if (command === 'about') return process.stdout.write(INTRO);

package/cli/lib/notice.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { stateDir, statePath, readJson, writeJson } from './paths.js';
 import { loadConfig } from './config.js';
 import { listProposals } from './ledger.js';
+import { projectEnabled, repoOf } from './project.js';
 
 function linkFor(proposal, output) {
   return output === 'report' ? statePath('reports', `${proposal.batch}.md`) : proposal.pr;
@@ -10,13 +11,15 @@ function linkFor(proposal, output) {
 
 // notice.json remembers which open proposals were already shown with their link.
 // In PR mode a proposal without a PR stays new, so a later notice can name its PR.
-export function noticeLine() {
-  if (process.env.AGENTIC_RETRO_RUN === '1' || !existsSync(stateDir())) return '';
+export function noticeLine(cwd = process.cwd()) {
+  if (process.env.AGENTIC_RETRO_RUN === '1' || !projectEnabled(cwd) || !existsSync(stateDir())) return '';
+  const repo = repoOf(cwd);
 
   const { output } = loadConfig();
   const { noticed = [] } = readJson('notice.json', {});
   const open = listProposals('open');
-  const fresh = open.filter((p) => !noticed.includes(p.id));
+  const fresh = open.filter((p) => !noticed.includes(p.id)).filter((p) => repoOf(p.repo) === repo ||
+    readJson(`batches/${p.batch}/batch.json`, { sessions: [] }).sessions.some((s) => repoOf(s.cwd, s.repo) === repo));
   if (!fresh.length) return '';
 
   const shown = open.filter((p) => noticed.includes(p.id) || (fresh.includes(p) && linkFor(p, output)));
@@ -28,9 +31,9 @@ export function noticeLine() {
 }
 
 // A session-start hook must never break the session, so any failure prints nothing.
-export function notice({ json }) {
+export function notice({ json, cwd }) {
   let line = '';
-  try { line = noticeLine(); } catch {}
+  try { line = noticeLine(cwd); } catch {}
   if (!line) return;
   console.log(json ? JSON.stringify({ systemMessage: line }) : line);
 }

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)], { cwd: ctx.cwd }, (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", "--cwd", ctx.cwd], (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/project.js

@@ -0,0 +1,42 @@
+// Repository identity and opt-in live in Git's shared metadata, not in a checkout.
+import { execFileSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+
+const options = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+const KEY = 'agentic-retro.enabled';
+
+function commonDir(cwd) {
+  const path = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-common-dir'], options).replace(/\n$/, '');
+  return resolve(cwd, path);
+}
+
+export function repoOf(cwd, fallback = cwd) {
+  try {
+    // Git lists the shared identity first: the main checkout or its separate metadata directory.
+    const worktrees = execFileSync('git', ['--git-dir', commonDir(cwd), 'worktree', 'list', '--porcelain', '-z'], options);
+    const main = worktrees.split('\0').find((field) => field.startsWith('worktree '));
+    return main ? main.slice('worktree '.length) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function projectEnabled(cwd) {
+  if (!cwd) return false;
+  try {
+    // Read only the shared config: global and per-worktree overrides cannot enable a project.
+    return execFileSync('git', ['config', '--file', join(commonDir(cwd), 'config'), '--bool', '--get', KEY], options).trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+export function project(action, cwd = process.cwd()) {
+  if (!['enable', 'disable', 'status'].includes(action)) throw new Error('usage: agentic-retro project enable|disable|status [--cwd <dir>]');
+  if (action !== 'status') {
+    let dir;
+    try { dir = commonDir(cwd); } catch { throw new Error('project enable/disable needs a Git repository'); }
+    execFileSync('git', ['config', '--file', join(dir, 'config'), KEY, String(action === 'enable')], options);
+  }
+  console.log(projectEnabled(cwd) ? 'enabled' : 'disabled');
+}

package/cli/lib/queue.js

@@ -1,24 +1,12 @@
 // 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, resolve } from 'node:path';
+import { join, basename } 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, fallback = cwd) {
-  try {
-    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 fallback;
-  }
-}
+import { projectEnabled, repoOf } from './project.js';
 
 // Codex sometimes ends a session with a null transcript_path, so look for its rollout file.
 function findCodexRollout(sessionId) {
@@ -41,11 +29,29 @@ 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
+  if (!projectEnabled(cwd)) return;
   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', []).map((s) => ({ ...s, repo: repoOf(s.cwd, s.repo) }));
   if (queue.some((s) => s.sessionId === sessionId)) return writeJson('queue.json', queue);
@@ -54,7 +60,7 @@ export async function enqueue({ harness, sessionId, transcript, cwd }) {
 
   const { batch } = loadConfig();
   const sameGroup = (s) => batch.group === 'global' || s.repo === entry.repo;
-  const group = queue.filter(sameGroup);
+  const group = queue.filter((s) => sameGroup(s) && projectEnabled(s.repo));
   if (group.length < batch.size) return writeJson('queue.json', queue);
 
   // Save first and remove after, so a failed hand-off leaves the sessions queued.

package/cli/lib/setup.js

@@ -50,5 +50,5 @@ export async function setup() {
 
   rl.close();
   saveConfig(config);
-  process.stdout.write('\nSaved config.json\n');
+  process.stdout.write('\nSaved config.json\nRepositories remain disabled until you run: agentic-retro project enable\n');
 }

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "agentic-retro",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/setup/SKILL.md

@@ -25,7 +25,7 @@ Offer the presets below for each question, and let the user type a different ans
 1. **Batch size** – sessions per batch, default 5
 2. **Grouping** – `repo` (default) or `global`
 3. **Runner harness** – `claude`, `codex`, or `pi`; add `herdr` to the choices only if `command -v herdr` finds it
-4. **Model** – `opus` or `default`; `opus` applies to Claude, Codex and Pi use their own default unless given a model name they understand (for example `o3`)
+4. **Model** – `opus` or `default`; `opus` applies to Claude, Codex and Pi use their default unless given a model name they understand (for example `o3`)
 5. **Runner permissions** – how much the batch agent can do without asking:
     - `auto` (default) – the harness's own auto mode
     - `scoped` – file edits, plus only `git`, `gh`, and `agentic-retro` commands
@@ -67,6 +67,14 @@ Never edit `config.json` by hand. `config set` is the only path that keeps the s
 
 Run `command -v pi`. If it finds Pi, ask whether to install the agentic-retro extension for it. On yes, run `agentic-retro install-pi`.
 
+## Enable this repository
+
+Every repository starts disabled. Ask whether the user wants to enable collection in the current repository.
+
+On yes, run `agentic-retro project enable` from that repository. All its worktrees share this untracked Git setting.
+
+On no, leave the repository disabled. Global configuration alone does not enable collection.
+
 ## Finish
 
 Run `agentic-retro config list` and show the user the result.