agentic-retro 0.1.3 → 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

@@ -78,7 +78,7 @@ export default function (pi: ExtensionAPI) {
   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) => {
+      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");
       });
@@ -121,7 +121,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", (_event, ctx) => {
-    execFile(process.execPath, [CLI, "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/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,25 +1,12 @@
 // The queue: finished sessions wait here until their group fills a batch.
-import { execFileSync } from 'node:child_process';
 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) {
@@ -60,6 +47,7 @@ async function isPiChildTranscript(transcript) {
 
 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');
@@ -72,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,6 +1,6 @@
 {
   "name": "agentic-retro",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "agentic-retrospective: reviews finished agent coding sessions and proposes improvements",
   "type": "module",
   "keywords": [

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.