agentic-retro 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Coote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# agentic-retro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+agentic-retro ("agentic-retrospective") learns from your finished coding sessions and proposes improvements, as a plugin for Claude Code, Codex, and Pi.
+
+## How a batch runs
+
+```mermaid
+flowchart TD
+    A["Session ends<br/>(hook in each harness)"] --> B["CLI adds session to queue"]
+    B --> C{"5 sessions queued for this repo?"}
+    C -->|no| Z["Stop"]
+    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"]
+    F --> G["Output: one PR per repo, or a report file"]
+    G --> H["Next session start: hook prints<br/>'3 new proposals: link'"]
+    H --> I["User reviews proposals"]
+```
+
+- A session-end hook in each harness queues the session (`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
+
+## The life of a proposal
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> accepted: merged, or user says yes
+    open --> rejected: closed, removed, or user says no
+    open --> expired: 3 batches with no action
+```
+
+- Every proposal starts `open` in the ledger (`~/.agentic-retro/ledger.json`)
+- It becomes `accepted` or `rejected` once you act on it, or `expired` after 3 batches with no action (configurable)
+- agentic-retro never re-proposes a rejected or expired item
+
+## Install
+
+You need Node.js 20 or later.
+
+Add the marketplace and install the plugin:
+
+```
+/plugin marketplace add ac8318740/ac-agentic-coding
+/plugin install agentic-retro@ac-agentic-coding
+```
+
+Install the CLI the plugin's hooks call into:
+
+```
+npm install -g agentic-retro
+```
+
+Run setup, either from the CLI or with the bundled skill:
+
+```
+agentic-retro setup
+```
+
+```
+/agentic-retro:setup
+```
+
+- The `setup` skill asks every question itself and writes each answer with `agentic-retro config set`
+- `agentic-retro setup` runs the same questions as plain interactive prompts – the human alternative to the skill
+
+Both write the same `~/.agentic-retro/config.json`:
+
+- batch size and grouping
+- runner harness and permissions (`auto`, `scoped`, or `bypass`)
+- which categories run, and the output mode (PR or report)
+- where agent-setup proposals land
+
+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.
+
+## Skills
+
+- `run` – the batch agent's own skill; the runner starts it headless once a batch fills, and you can also invoke it to rerun a batch
+- `review` – walks a report, applies each change you accept, and marks the ledger
+- `setup` – drives the conversational config walkthrough
+- `retro` – reads ledger outcomes and metrics over time into a retrospective
+
+## CLI commands
+
+- `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 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
+- `agentic-retro mark <id> <accepted|rejected>` – record a decision on a proposal
+- `agentic-retro ledger` – list proposals, filtered by status
+- `agentic-retro sync` – refresh proposal outcomes from GitHub, then expire stale ones
+- `agentic-retro notice` – the session-start one-line proposal count (hooks call this)
+- `agentic-retro stats` – acceptance rate per category, and tokens per changed line
+- `agentic-retro install-pi` – write the Pi extension that stands in for Pi's missing hooks
+
+## 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.

package/cli/agentic-retro.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// agentic-retro: parses argv and routes each command to its module.
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { loadConfig, getKey, setKey } from './lib/config.js';
+import { setup } from './lib/setup.js';
+import { enqueue } from './lib/queue.js';
+import { propose, mark, link, listProposals, formatProposal } from './lib/ledger.js';
+import { syncOutcomes } from './lib/outcomes.js';
+import { notice } from './lib/notice.js';
+import { stats } from './lib/stats.js';
+import { installPi } from './lib/pi.js';
+
+const USAGE = `usage: agentic-retro <command>
+  setup
+  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]
+  stats [--json]
+  sync
+  install-pi`;
+
+const FLAGS = ['harness', 'session', 'transcript', 'cwd', 'repo', 'category', 'risk', 'title', 'pr', 'commit', 'status'];
+const options = Object.fromEntries(FLAGS.map((flag) => [flag, { type: 'string' }]));
+options.json = { type: 'boolean' };
+
+function config([action, key, value]) {
+  const current = loadConfig();
+  if (action === 'list') return console.log(JSON.stringify(current, null, 2));
+  if (action === 'set') return setKey(key, value);
+  if (action !== 'get') throw new Error(USAGE);
+  const found = getKey(current, key);
+  if (found === undefined) throw new Error(`unknown config key: ${key}`);
+  console.log(typeof found === 'object' ? JSON.stringify(found) : String(found));
+}
+
+// Harness hooks pipe JSON like {"session_id", "transcript_path", "cwd"} on stdin.
+// Bad JSON reads as no hook: a session-end hook must not fail the session.
+function readHook() {
+  if (process.stdin.isTTY) return {};
+  try {
+    return JSON.parse(readFileSync(0, 'utf8')) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function enqueueCommand(flags) {
+  const hook = flags.session ? {} : readHook();
+  if (!flags.session && !hook.session_id) return; // nothing to queue, and a hook must not fail the session
+  return enqueue({
+    harness: flags.harness,
+    sessionId: flags.session ?? hook.session_id,
+    transcript: flags.transcript ?? hook.transcript_path,
+    cwd: flags.cwd ?? hook.cwd,
+  });
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (command === 'help' || command === '--help') return console.log(USAGE);
+  const { values: flags, positionals } = parseArgs({ args: rest, options, allowPositionals: true });
+
+  if (command === 'setup') return setup();
+  if (command === 'config') return config(positionals);
+  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 === 'stats') return stats(flags);
+  if (command === 'install-pi') return installPi();
+  throw new Error(USAGE);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/cli/lib/commands.js

@@ -0,0 +1,89 @@
+// Builds the command that starts the batch agent in each harness.
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stateDir } from './paths.js';
+
+const ENV = { AGENTIC_RETRO_RUN: '1' };
+const SCOPED_TOOLS = 'Bash(git:*),Bash(gh:*),Bash(agentic-retro:*)';
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const PANE_ID = '<pane_id>';
+
+const prompt = (n) => `Use the agentic-retro run skill on batch ${n} in this folder.`;
+// opus is a Claude model name, not a codex/pi one, so for those harnesses treat it like
+// "default" (no flag) rather than passing it through unrecognized. Claude keeps it as-is.
+const modelFlag = (flag, model, isClaude = false) =>
+  (model === 'default' || (!isClaude && model === 'opus') ? [] : [flag, model]);
+const expandHome = (path) => (path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(1)) : path);
+
+const claudePermissions = {
+  auto: ['--permission-mode', 'auto'],
+  scoped: ['--permission-mode', 'acceptEdits', '--allowedTools', SCOPED_TOOLS],
+  bypass: ['--permission-mode', 'bypassPermissions'],
+};
+
+const codexPermissions = {
+  auto: ['-s', 'workspace-write', '--approve-for-me'],
+  scoped: ['-s', 'workspace-write'],
+  bypass: ['--dangerously-bypass-approvals-and-sandbox'],
+};
+
+// The batch agent edits the sessions' repos and the user's editable paths.
+// A headless run cannot ask for access, so each folder is granted up front.
+function sessionsOf(batchDir) {
+  const manifest = join(batchDir, 'batch.json');
+  return existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf8')).sessions : [];
+}
+
+function workDirs(config, sessions) {
+  const paths = [...sessions.map((s) => s.repo), ...(config.editable ?? []).map(expandHome)];
+  return [...new Set(paths.filter(Boolean))];
+}
+
+const addDirs = (dirs) => dirs.flatMap((dir) => ['--add-dir', dir]);
+
+// The prompt sits right after -p: --allowedTools and --add-dir take variadic lists that would swallow a later prompt.
+function claudeArgs({ model, permissions }, n, dirs) {
+  return ['-p', prompt(n), ...modelFlag('--model', model, true), ...claudePermissions[permissions], ...addDirs(dirs)];
+}
+
+// Codex's sandbox blocks the network by default, and the run skill needs gh.
+function codexArgs({ model, permissions }, n, dirs, batchDir) {
+  const network = permissions === 'bypass' ? [] : ['-c', 'sandbox_workspace_write.network_access=true'];
+  return ['exec', '-c', 'shell_environment_policy.inherit=all', ...network, ...modelFlag('-m', model),
+    ...codexPermissions[permissions], ...addDirs([stateDir(), ...dirs]), '--skip-git-repo-check', '-C', batchDir, prompt(n)];
+}
+
+// Pi never asks before a tool call, so every permissions mode runs the same way.
+// Pi has no plugin install, so it loads the run skill from this package.
+function piArgs({ model }, n) {
+  return ['-p', ...modelFlag('--model', model), '--skill', join(PACKAGE_ROOT, 'skills', 'run'), prompt(n)];
+}
+
+const shellQuote = (arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`);
+
+// herdr types the command into a new pane's shell, so it gets one quoted string (see #11).
+function herdrSteps(runner, dir, n, dirs) {
+  const line = ['claude', ...claudeArgs(runner, n, dirs)].map(shellQuote).join(' ');
+  return [
+    { file: 'herdr', args: ['workspace', 'create', '--cwd', dir, '--env', 'AGENTIC_RETRO_RUN=1', '--no-focus'], env: ENV, cwd: dir },
+    { file: 'herdr', args: ['pane', 'run', PANE_ID, line], env: ENV, cwd: dir },
+  ];
+}
+
+const harnesses = {
+  claude: (runner, n, dirs) => ({ file: 'claude', args: claudeArgs(runner, n, dirs) }),
+  codex: (runner, n, dirs, batchDir) => ({ file: 'codex', args: codexArgs(runner, n, dirs, batchDir) }),
+  pi: (runner, n) => ({ file: 'pi', args: piArgs(runner, n) }),
+};
+
+// Returns { file, args, env, cwd }, or for herdr a list of such steps.
+export function buildCommand(config, batchDir, n, sessions = sessionsOf(batchDir)) {
+  const runner = { permissions: 'auto', ...config.runner };
+  const dirs = workDirs(config, sessions);
+  if (runner.harness === 'herdr') return herdrSteps(runner, batchDir, n, dirs);
+  const build = harnesses[runner.harness];
+  if (!build) throw new Error(`unknown runner.harness: ${runner.harness}`);
+  return { ...build(runner, n, dirs, batchDir), env: ENV, cwd: batchDir };
+}

package/cli/lib/config.js

@@ -0,0 +1,56 @@
+// Config: defaults merged with config.json, read and written through dotted keys.
+import { readJson, writeJson } from './paths.js';
+
+export const DEFAULTS = {
+  batch: { size: 5, group: 'repo' },
+  runner: { harness: 'claude', model: 'opus', permissions: 'auto' },
+  categories: { clarity: true, 'agent-setup': true, 'repo-for-agents': true },
+  scope: 'touched',
+  output: 'pr',
+  autoMergeLowRisk: false,
+  expireAfterBatches: 3,
+  editable: [],
+  targets: { preset: '~/.claude/skills', note: '' },
+  notes: '',
+};
+
+const isObject = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+function merge(base, over) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    result[key] = isObject(base[key]) && isObject(value) ? merge(base[key], value) : value;
+  }
+  return result;
+}
+
+export function loadConfig() {
+  return merge(DEFAULTS, readJson('config.json', {}));
+}
+
+export function saveConfig(config) {
+  writeJson('config.json', config);
+}
+
+export function getKey(config, key) {
+  return key.split('.').reduce((node, part) => (isObject(node) ? node[part] : undefined), config);
+}
+
+// "5" -> 5, "true" -> true, '["a"]' -> ["a"]; keys whose default is text stay text.
+export function parseValue(key, text) {
+  if (typeof getKey(DEFAULTS, key) === 'string') return text;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export function setKey(key, text) {
+  const current = getKey(DEFAULTS, key);
+  if (current === undefined) throw new Error(`unknown config key: ${key}`);
+  // Setting a whole section, e.g. "batch", would replace every key inside it.
+  if (isObject(current)) throw new Error(`${key} is a section; set one of its keys, e.g. ${key}.<key>`);
+  const config = loadConfig();
+  const parts = key.split('.');
+  const last = parts.pop();
+  const parent = parts.reduce((node, part) => node[part], config);
+  parent[last] = parseValue(key, text);
+  saveConfig(config);
+}

package/cli/lib/digest.js

@@ -0,0 +1,107 @@
+// Writes a short markdown digest and one metrics.jsonl line per session in a batch.
+import { mkdirSync, writeFileSync, appendFileSync, existsSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+import { statePath } from './paths.js';
+import * as claude from './transcripts/claude.js';
+import * as codex from './transcripts/codex.js';
+import * as pi from './transcripts/pi.js';
+
+const readers = { claude, codex, pi };
+
+// Caps keep a digest under 200 lines however long the session ran.
+const MAX_MESSAGE = 500;
+const MAX_TARGET = 120;
+const MAX_USER = 50;
+const MAX_TIMELINE = 60;
+const MAX_ERRORS = 20;
+const MAX_FILES = 30;
+
+const oneLine = (text, max) => {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max)}...` : flat;
+};
+
+// The first `max` items as lines, plus a note for the rest.
+function capped(items, max, format) {
+  const lines = items.slice(0, max).map(format);
+  if (items.length > max) lines.push(`- ... ${items.length - max} more`);
+  return lines.length ? lines : ['- none'];
+}
+
+async function readTranscript(harness, transcript) {
+  const reader = readers[harness];
+  if (!reader || !transcript || !existsSync(transcript)) return null;
+  try {
+    return await reader.readSession(transcript);
+  } catch {
+    return null;
+  }
+}
+
+function metricsOf(n, s, parsed) {
+  const sum = (key) => (parsed ? parsed.edits.reduce((total, e) => total + e[key], 0) : null);
+  return {
+    batch: n, harness: s.harness, sessionId: s.sessionId, repo: s.repo ?? null,
+    userTurns: parsed?.turns.user ?? null,
+    assistantTurns: parsed?.turns.assistant ?? null,
+    inputTokens: parsed?.usage?.input ?? null,
+    outputTokens: parsed?.usage?.output ?? null,
+    linesAdded: sum('added'),
+    linesRemoved: sum('removed'),
+  };
+}
+
+// Sums edits per file, in the order files were first touched.
+function filesEdited(edits) {
+  const files = new Map();
+  for (const { file, added, removed } of edits) {
+    const total = files.get(file) ?? { file, added: 0, removed: 0 };
+    files.set(file, { file, added: total.added + added, removed: total.removed + removed });
+  }
+  return [...files.values()];
+}
+
+function digestOf(s, parsed, m) {
+  const header = [
+    `# Session ${s.sessionId}`, '',
+    `- harness: ${s.harness}`,
+    `- repo: ${s.repo ?? 'unknown'}`,
+    `- cwd: ${parsed?.cwd ?? s.cwd ?? 'unknown'}`,
+    `- transcript: ${s.transcript ?? 'none'}`,
+  ];
+  if (!parsed) return [...header, '', 'Transcript missing: no transcript was found for this session, so there is no digest or metrics.'];
+
+  const show = (v) => (v === null ? 'n/a' : v);
+  const calls = parsed.toolCalls;
+  const errors = calls.filter((c) => c.error);
+  return [
+    ...header,
+    `- start: ${parsed.start ?? 'unknown'}`,
+    `- end: ${s.endedAt ?? parsed.end ?? 'unknown'}`,
+    `- turns: ${m.userTurns} user, ${m.assistantTurns} assistant`,
+    `- tokens: ${show(m.inputTokens)} in, ${show(m.outputTokens)} out`,
+    `- lines: +${m.linesAdded} -${m.linesRemoved}`,
+    `- subagents: ${parsed.subagents}`,
+    '', `## User messages (${parsed.userMessages.length})`, '',
+    ...capped(parsed.userMessages, MAX_USER, (text, i) => `${i + 1}. ${oneLine(text, MAX_MESSAGE)}`),
+    '', `## Tool calls (${calls.length})`, '',
+    ...capped(calls, MAX_TIMELINE, (c) => `- ${c.tool} ${oneLine(c.target, MAX_TARGET)}${c.error ? ' [error]' : ''}`),
+    '', `## Errors (${errors.length})`, '',
+    ...capped(errors, MAX_ERRORS, (c) => `- ${c.tool} ${oneLine(c.target, 60)}: ${oneLine(c.error, MAX_TARGET)}`),
+    '', '## Files edited', '',
+    ...capped(filesEdited(parsed.edits), MAX_FILES, (f) => `- ${basename(f.file ?? '?')} +${f.added} -${f.removed} (${f.file})`),
+  ];
+}
+
+export async function writeBatchDigests(n, sessions) {
+  const metricsPath = statePath('metrics.jsonl');
+  mkdirSync(dirname(metricsPath), { recursive: true });
+  for (const s of sessions) {
+    const parsed = await readTranscript(s.harness, s.transcript);
+    const m = metricsOf(n, s, parsed);
+    const path = statePath('batches', String(n), `${s.sessionId}.md`);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, digestOf(s, parsed, m).join('\n') + '\n');
+    appendFileSync(metricsPath, JSON.stringify(m) + '\n');
+  }
+}

package/cli/lib/ledger.js

@@ -0,0 +1,78 @@
+// The ledger: every proposal a batch agent makes, and what became of it.
+import { readJson, writeJson } from './paths.js';
+
+export const CATEGORIES = ['clarity', 'agent-setup', 'repo-for-agents'];
+const RISKS = ['low', 'high'];
+const MARKABLE = ['accepted', 'rejected'];
+
+export function loadLedger() {
+  return readJson('ledger.json', { nextId: 1, batchCount: 0, proposals: [] });
+}
+
+export function saveLedger(ledger) {
+  writeJson('ledger.json', ledger);
+}
+
+export function setStatus(proposal, status) {
+  proposal.status = status;
+  proposal.statusAt = new Date().toISOString();
+}
+
+export function propose({ repo, category, risk, title, pr, commit }) {
+  if (!repo || !title) throw new Error('propose needs --repo and --title');
+  if (!CATEGORIES.includes(category)) throw new Error(`unknown category: ${category}`);
+  if (risk && category !== 'agent-setup') throw new Error('only agent-setup proposals carry a risk');
+  if (risk && !RISKS.includes(risk)) throw new Error(`risk must be low or high: ${risk}`);
+
+  const ledger = loadLedger();
+  const id = `P${ledger.nextId++}`;
+  ledger.proposals.push({
+    id, batch: ledger.batchCount, repo, category, risk: risk ?? null, title, status: 'open',
+    createdAt: new Date().toISOString(), statusAt: null, pr: pr ?? null, commit: commit ?? null,
+  });
+  saveLedger(ledger);
+  return id;
+}
+
+function findProposal(ledger, id) {
+  const proposal = ledger.proposals.find((p) => p.id === id);
+  if (!proposal) throw new Error(`no proposal ${id}`);
+  return proposal;
+}
+
+export function mark(id, status) {
+  if (!MARKABLE.includes(status)) throw new Error(`status must be accepted or rejected: ${status}`);
+  const ledger = loadLedger();
+  setStatus(findProposal(ledger, id), status);
+  saveLedger(ledger);
+}
+
+// The run skill links a proposal to its PR and commit once they exist.
+export function link(id, { pr, commit }) {
+  const ledger = loadLedger();
+  const proposal = findProposal(ledger, id);
+  if (pr) proposal.pr = pr;
+  if (commit) proposal.commit = commit;
+  saveLedger(ledger);
+}
+
+// Each batch run takes the next number; proposals remember it so they can expire.
+export function nextBatch() {
+  const ledger = loadLedger();
+  ledger.batchCount += 1;
+  saveLedger(ledger);
+  return ledger.batchCount;
+}
+
+// status may be a comma list, e.g. "rejected,expired".
+export function listProposals(status) {
+  const { proposals } = loadLedger();
+  if (!status) return proposals;
+  const wanted = status.split(',');
+  return proposals.filter((p) => wanted.includes(p.status));
+}
+
+export function formatProposal(p) {
+  const risk = p.risk ? ` (${p.risk} risk)` : '';
+  return `${p.id}  ${p.status}  ${p.category}${risk}  ${p.title}  [${p.repo}]`;
+}

package/cli/lib/notice.js

@@ -0,0 +1,36 @@
+// Session-start notice: one line naming the proposals not yet shown.
+import { existsSync } from 'node:fs';
+import { stateDir, statePath, readJson, writeJson } from './paths.js';
+import { loadConfig } from './config.js';
+import { listProposals } from './ledger.js';
+
+function linkFor(proposal, output) {
+  return output === 'report' ? statePath('reports', `${proposal.batch}.md`) : proposal.pr;
+}
+
+// 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 '';
+
+  const { output } = loadConfig();
+  const { noticed = [] } = readJson('notice.json', {});
+  const open = listProposals('open');
+  const fresh = open.filter((p) => !noticed.includes(p.id));
+  if (!fresh.length) return '';
+
+  const shown = open.filter((p) => noticed.includes(p.id) || (fresh.includes(p) && linkFor(p, output)));
+  writeJson('notice.json', { noticed: shown.map((p) => p.id) });
+  const links = [...new Set(fresh.map((p) => linkFor(p, output)).filter(Boolean))];
+  const count = `${fresh.length} new proposal${fresh.length === 1 ? '' : 's'}`;
+  if (!links.length) return `agentic-retro: ${count} – ask your agent to review them`;
+  return `agentic-retro: ${count}: ${links.join(', ')}`;
+}
+
+// A session-start hook must never break the session, so any failure prints nothing.
+export function notice({ json }) {
+  let line = '';
+  try { line = noticeLine(); } catch {}
+  if (!line) return;
+  console.log(json ? JSON.stringify({ systemMessage: line }) : line);
+}

package/cli/lib/outcomes.js

@@ -0,0 +1,46 @@
+// Sync: settle open proposals from their PRs, then expire the stale ones.
+import { execFileSync } from 'node:child_process';
+import { loadConfig } from './config.js';
+import { loadLedger, saveLedger, setStatus } from './ledger.js';
+
+// A failed lookup (network, deleted repo) leaves the proposal open for the next sync.
+function viewPr(pr) {
+  const gh = process.env.AGENTIC_RETRO_GH || 'gh';
+  try {
+    const output = execFileSync(gh, ['pr', 'view', pr, '--json', 'state,commits'], { encoding: 'utf8' });
+    return JSON.parse(output);
+  } catch (error) {
+    console.error(`agentic-retro: could not check ${pr}: ${error.message.split('\n')[0]}`);
+    return { state: 'OPEN', commits: [] };
+  }
+}
+
+// Each proposal is its own commit with its ID in the headline, e.g. "P12: shorten the map skill".
+function commitSurvived(view, id) {
+  const pattern = new RegExp(`\\b${id}\\b`);
+  return view.commits.some((c) => pattern.test(c.messageHeadline));
+}
+
+function outcome(view, id) {
+  if (view.state === 'MERGED') return commitSurvived(view, id) ? 'accepted' : 'rejected';
+  if (view.state === 'CLOSED') return 'rejected';
+  return 'open';
+}
+
+export function syncOutcomes() {
+  const ledger = loadLedger();
+  const { expireAfterBatches } = loadConfig();
+  const open = () => ledger.proposals.filter((p) => p.status === 'open');
+
+  const views = new Map();
+  for (const p of open().filter((p) => p.pr)) {
+    if (!views.has(p.pr)) views.set(p.pr, viewPr(p.pr));
+    const status = outcome(views.get(p.pr), p.id);
+    if (status !== 'open') setStatus(p, status);
+  }
+
+  for (const p of open()) {
+    if (ledger.batchCount - p.batch >= expireAfterBatches) setStatus(p, 'expired');
+  }
+  saveLedger(ledger);
+}

package/cli/lib/paths.js

@@ -0,0 +1,23 @@
+// Where state lives, and how to read and write its JSON files.
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export function stateDir() {
+  return process.env.AGENTIC_RETRO_HOME || join(homedir(), '.agentic-retro');
+}
+
+export function statePath(...parts) {
+  return join(stateDir(), ...parts);
+}
+
+export function readJson(name, fallback) {
+  const path = statePath(name);
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : fallback;
+}
+
+export function writeJson(name, data) {
+  const path = statePath(name);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}