feat(retro): absorb inline git/awk metrics into bin/gstack-retro-metrics + carve report format

RETRO_METRICS_PROTO: 1 contract, local git reads only (fetch stays in the skill prose), degraded path documented in the skeleton. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-09 14:38:59 +02:00 · 2026-08-25 17:47:32 +00:00
parent b007814be0
commit e0250aa128
10 changed files with 1245 additions and 705 deletions
@@ -0,0 +1,314 @@
+/**
+ * Contract + behavior tests for bin/gstack-retro-metrics (retro
+ * token-reduction wave — the inline git/awk pipelines from retro/SKILL.md
+ * Steps 0.5-9 and 11, consolidated into one script).
+ *
+ * Three layers:
+ *  1. CONTRACT — every labeled `KEY:` line the rendered retro prose
+ *     interprets must be emitted (hermetic temp HOME + GSTACK_HOME, synthetic
+ *     git repo fixture with pinned author AND committer dates).
+ *  2. BEHAVIOR — deterministic values on the fixture: commit/type/session
+ *     counts, streak anchoring, window --until, local-branch fallback,
+ *     AI-trailer vs human co-author split, VERSION range, aux-file presence.
+ *  3. EDGES — a 1-commit repo and a non-repo dir both survive (exit 0, no
+ *     dropped lines); the skill fence shape stays pinned in the template.
+ *
+ * All hermetic: HOME + GSTACK_HOME point at throwaway temp dirs; the script
+ * runs from the live worktree bin/ (the subject under test).
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { execFileSync, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const SCRIPT = path.join(ROOT, 'bin', 'gstack-retro-metrics');
+
+let tmpHome: string;
+let tmpGstackHome: string;
+let repoDir: string;
+
+function hermeticEnv(): Record<string, string> {
+  return { PATH: process.env.PATH!, HOME: tmpHome, GSTACK_HOME: tmpGstackHome };
+}
+
+function runMetrics(args: string[], cwd: string = repoDir): string {
+  return execFileSync(SCRIPT, args, { encoding: 'utf-8', cwd, env: hermeticEnv() });
+}
+
+/** Commit with pinned author AND committer dates (guard + --until read %ci). */
+function commit(dir: string, msg: string, date: string, author?: { name: string; email: string }): void {
+  const env: Record<string, string> = {
+    ...hermeticEnv(),
+    GIT_COMMITTER_DATE: date,
+    ...(author ? { GIT_AUTHOR_NAME: author.name, GIT_AUTHOR_EMAIL: author.email } : {}),
+  };
+  const r = spawnSync('git', ['commit', '-m', msg, '--date', date], {
+    cwd: dir, stdio: 'pipe', timeout: 10_000, env,
+  });
+  if (r.status !== 0) throw new Error(`fixture commit failed: ${r.stderr}`);
+}
+
+function git(dir: string, args: string[]): void {
+  const r = spawnSync('git', args, { cwd: dir, stdio: 'pipe', timeout: 10_000, env: hermeticEnv() });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
+}
+
+function write(dir: string, file: string, content: string): void {
+  fs.writeFileSync(path.join(dir, file), content);
+  git(dir, ['add', file]);
+}
+
+beforeAll(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-rm-home-'));
+  tmpGstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-rm-gh-'));
+  repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-rm-repo-'));
+
+  git(repoDir, ['init', '-b', 'main']);
+  git(repoDir, ['config', 'user.email', 'dev@example.com']);
+  git(repoDir, ['config', 'user.name', 'Dev']);
+
+  // Day 1 — one 20-minute session (2 commits) + one solo commit later.
+  write(repoDir, 'app.ts', 'console.log("hello");\n');
+  commit(repoDir, 'feat: initial app', '2026-03-10T09:00:00');
+  write(repoDir, 'auth.ts', 'export function login() {}\n');
+  commit(repoDir, 'feat: add auth (#12)', '2026-03-10T09:20:00');
+  write(repoDir, 'foo.test.ts', 'test("login", () => {});\n');
+  commit(repoDir, 'test(qa): add regression test', '2026-03-10T11:00:00');
+
+  // Day 2 — 5-minute session; first commit carries an AI trailer AND a human
+  // co-author trailer.
+  write(repoDir, 'app.ts', '// wire auth\nimport "./auth";\nconsole.log("hello");\n');
+  commit(
+    repoDir,
+    'fix: wire auth\n\nCo-Authored-By: Claude Opus <noreply@anthropic.com>\nCo-Authored-By: Alice Smith <alice@example.com>',
+    '2026-03-11T10:00:00',
+  );
+  write(repoDir, 'VERSION', '1.0.0.0\n');
+  commit(repoDir, 'chore: add VERSION', '2026-03-11T10:05:00');
+
+  // Day 3 — a second author bumps VERSION (contributors=2, team streak=3).
+  write(repoDir, 'VERSION', '1.1.0.0\n');
+  commit(repoDir, 'chore: bump VERSION', '2026-03-12T09:30:00', { name: 'Bob', email: 'bob@example.com' });
+});
+
+afterAll(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.rmSync(tmpGstackHome, { recursive: true, force: true });
+  fs.rmSync(repoDir, { recursive: true, force: true });
+});
+
+/** Labeled keys the rendered retro prose interprets (Steps 1-11). */
+const REQUIRED_KEYS = [
+  'RETRO_METRICS_PROTO',
+  'GUARD_REMOTE',
+  'GUARD_HEAD',
+  'RETRO_REF',
+  'GUARD_LATEST_COMMIT',
+  'WINDOW_SINCE',
+  'WINDOW_UNTIL',
+  'USER_NAME',
+  'USER_EMAIL',
+  'COMMIT',
+  'COMMITS',
+  'MERGE_COMMITS',
+  'CONTRIBUTORS',
+  'INSERTIONS',
+  'DELETIONS',
+  'NET_LOC',
+  'TEST_INSERTIONS',
+  'TEST_RATIO',
+  'WEIGHTED_COMMITS',
+  'ACTIVE_DAYS',
+  'TEST_FILES_CHANGED',
+  'SESSIONS',
+  'DEEP_SESSIONS',
+  'MEDIUM_SESSIONS',
+  'MICRO_SESSIONS',
+  'TOTAL_ACTIVE_MINUTES',
+  'AVG_SESSION_MINUTES',
+  'LOC_PER_SESSION_HOUR',
+  'COMMIT_TYPES',
+  'FIX_RATIO',
+  'COMMIT_SIZE_BUCKETS',
+  'HOURS',
+  'PEAK_HOUR',
+  'FOCUS_SCORE',
+  'BIGGEST_COMMIT',
+  'HOTSPOT',
+  'AUTHOR',
+  'AUTHOR_BIGGEST',
+  'WEEK',
+  'COAUTHOR',
+  'AI_ASSISTED_COMMITS',
+  'LOGICAL_SLOC_ADDED',
+  'PRS_REFERENCED',
+  'PR_REFS',
+  'TEST_FILES_TOTAL',
+  'REGRESSION_TEST_COMMITS',
+  'REGRESSION_COMMIT',
+  'VERSION_RANGE',
+  'TEAM_STREAK',
+  'USER_STREAK',
+  'RETRO_CONTEXT',
+  'GREPTILE_HISTORY',
+  'TODOS_FILE',
+  'SKILL_USAGE_LOG',
+  'EUREKA_LOG',
+  'RETRO_METRICS_END',
+] as const;
+
+describe('gstack-retro-metrics contract', () => {
+  test('emits every labeled key the retro prose interprets', () => {
+    const out = runMetrics(['--base', 'main', '--since', '2026-03-09T00:00:00']);
+    const missing = REQUIRED_KEYS.filter((k) => !new RegExp(`^${k}: `, 'm').test(out));
+    expect(missing, `Script stopped emitting: ${missing.join(', ')} — the prose contract broke`).toEqual([]);
+  });
+
+  test('proto handshake is the FIRST line', () => {
+    const out = runMetrics(['--base', 'main', '--since', '2026-03-09T00:00:00']);
+    expect(out.split('\n')[0]).toBe('RETRO_METRICS_PROTO: 1');
+  });
+
+  test('the skill fence invokes the script with primary path + degraded fallback', () => {
+    const tmpl = fs.readFileSync(path.join(ROOT, 'retro', 'SKILL.md.tmpl'), 'utf-8');
+    expect(tmpl).toContain('$HOME/.claude/skills/gstack/bin/gstack-retro-metrics');
+    expect(tmpl).toContain('".claude/skills/gstack/bin/gstack-retro-metrics"');
+    expect(tmpl).toContain('--base "<default>" --since "<since>"');
+    expect(tmpl).toContain(
+      'RETRO_METRICS: unavailable — stale install (compute metrics manually from the steps below)',
+    );
+    // Degraded-mode prose keys off the proto handshake.
+    expect(tmpl).toContain('RETRO_METRICS_PROTO: 1');
+  });
+
+  test('script is executable', () => {
+    expect(fs.statSync(SCRIPT).mode & 0o111).toBeTruthy();
+  });
+});
+
+describe('gstack-retro-metrics behavior', () => {
+  test('deterministic aggregates on the fixture', () => {
+    const out = runMetrics(['--base', 'main', '--since', '2026-03-09T00:00:00']);
+    expect(out).toMatch(/^COMMITS: 6$/m);
+    expect(out).toMatch(/^CONTRIBUTORS: 2$/m);
+    expect(out).toMatch(/^ACTIVE_DAYS: 3$/m);
+    // No origin remote: guard discloses, ref falls back to the local branch.
+    expect(out).toMatch(/^GUARD_REMOTE: none$/m);
+    expect(out).toMatch(/^GUARD_HEAD: main$/m);
+    expect(out).toMatch(/^RETRO_REF: main$/m);
+    expect(out).toMatch(/^GUARD_LATEST_COMMIT: 2026-03-12$/m);
+    // Conventional-commit mix (feat 2, fix 1, test 1, chore 2).
+    const types = out.match(/^COMMIT_TYPES: (.*)$/m)![1];
+    expect(types).toContain('feat=2');
+    expect(types).toContain('fix=1');
+    expect(types).toContain('test=1');
+    expect(types).toContain('chore=2');
+    // Session detection: [09:00,09:20]=medium, [11:00]=micro, [10:00,10:05]=micro, [09:30]=micro.
+    expect(out).toMatch(/^SESSIONS: 4$/m);
+    expect(out).toMatch(/^MEDIUM_SESSIONS: 1$/m);
+    expect(out).toMatch(/^MICRO_SESSIONS: 3$/m);
+    expect(out).toMatch(/^DEEP_SESSIONS: 0$/m);
+    expect(out).toMatch(/^TOTAL_ACTIVE_MINUTES: 25$/m);
+    // Test health.
+    expect(out).toMatch(/^TEST_FILES_TOTAL: 1$/m);
+    expect(out).toMatch(/^TEST_FILES_CHANGED: 1$/m);
+    expect(out).toMatch(/^REGRESSION_TEST_COMMITS: 1$/m);
+    expect(out).toMatch(/^REGRESSION_COMMIT: \w+ test\(qa\): add regression test$/m);
+    // PR refs from subjects.
+    expect(out).toMatch(/^PRS_REFERENCED: 1$/m);
+    expect(out).toMatch(/^PR_REFS: #12$/m);
+    // AI trailer counted separately from the human co-author credit.
+    expect(out).toMatch(/^AI_ASSISTED_COMMITS: 1$/m);
+    expect(out).toMatch(/^COAUTHOR: \w+\|Alice Smith <alice@example\.com>$/m);
+    expect(out).not.toMatch(/^COAUTHOR: .*anthropic\.com/m);
+    // VERSION range across the window.
+    expect(out).toMatch(/^VERSION_RANGE: v1\.0\.0\.0 → v1\.1\.0\.0$/m);
+    // Streaks anchored at the newest commit date, never the wall clock.
+    expect(out).toMatch(/^TEAM_STREAK: 3 days \(anchor 2026-03-12\)$/m);
+    expect(out).toMatch(/^USER_STREAK: 2 days \(anchor 2026-03-11\)$/m);
+    // Hour histogram carries the fixture's commit hours.
+    const hours = out.match(/^HOURS: (.*)$/m)![1];
+    expect(hours).toContain('09=');
+    expect(hours).toContain('10=');
+  });
+
+  test('--until bounds the window (compare mode prior window)', () => {
+    const out = runMetrics([
+      '--base', 'main',
+      '--since', '2026-03-09T00:00:00',
+      '--until', '2026-03-11T00:00:00',
+    ]);
+    expect(out).toMatch(/^COMMITS: 3$/m);
+    expect(out).toMatch(/^ACTIVE_DAYS: 1$/m);
+    expect(out).toMatch(/^WINDOW_UNTIL: 2026-03-11T00:00:00$/m);
+  });
+
+  test('aux inputs report present when the files exist under GSTACK_HOME', () => {
+    fs.writeFileSync(path.join(tmpGstackHome, 'greptile-history.md'), '# history\n');
+    fs.mkdirSync(path.join(tmpGstackHome, 'analytics'), { recursive: true });
+    fs.writeFileSync(path.join(tmpGstackHome, 'analytics', 'skill-usage.jsonl'), '{}\n');
+    try {
+      const out = runMetrics(['--base', 'main', '--since', '2026-03-09T00:00:00']);
+      expect(out).toMatch(/^GREPTILE_HISTORY: present /m);
+      expect(out).toMatch(/^SKILL_USAGE_LOG: present /m);
+      expect(out).toMatch(/^RETRO_CONTEXT: absent$/m);
+      expect(out).toMatch(/^EUREKA_LOG: absent$/m);
+    } finally {
+      fs.rmSync(path.join(tmpGstackHome, 'greptile-history.md'), { force: true });
+      fs.rmSync(path.join(tmpGstackHome, 'analytics'), { recursive: true, force: true });
+    }
+  });
+
+  test('zero-commit window still emits the full labeled surface', () => {
+    const out = runMetrics([
+      '--base', 'main',
+      '--since', '2020-01-01T00:00:00',
+      '--until', '2020-01-08T00:00:00',
+    ]);
+    expect(out).toMatch(/^COMMITS: 0$/m);
+    expect(out).toMatch(/^SESSIONS: 0$/m);
+    expect(out).toMatch(/^RETRO_METRICS_END: ok$/m);
+  });
+});
+
+describe('gstack-retro-metrics edges', () => {
+  test('survives a repo with exactly 1 commit', () => {
+    const oneDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-rm-one-'));
+    try {
+      git(oneDir, ['init', '-b', 'main']);
+      git(oneDir, ['config', 'user.email', 'solo@example.com']);
+      git(oneDir, ['config', 'user.name', 'Solo']);
+      write(oneDir, 'a.txt', 'hi\n');
+      commit(oneDir, 'feat: first', '2026-03-10T09:00:00');
+      const out = runMetrics(['--base', 'main', '--since', '2026-03-09T00:00:00'], oneDir);
+      expect(out).toMatch(/^COMMITS: 1$/m);
+      expect(out).toMatch(/^CONTRIBUTORS: 1$/m);
+      expect(out).toMatch(/^SESSIONS: 1$/m);
+      expect(out).toMatch(/^MICRO_SESSIONS: 1$/m);
+      expect(out).toMatch(/^TEAM_STREAK: 1 days \(anchor 2026-03-10\)$/m);
+      expect(out).toMatch(/^BIGGEST_COMMIT: \w+\|1\|Solo\|feat: first$/m);
+      expect(out).toMatch(/^RETRO_METRICS_END: ok$/m);
+    } finally {
+      fs.rmSync(oneDir, { recursive: true, force: true });
+    }
+  });
+
+  test('non-repo dir reports RETRO_METRICS_ERROR and exits 0', () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-rm-empty-'));
+    try {
+      const out = runMetrics(['--since', '7 days ago'], emptyDir);
+      expect(out).toContain('RETRO_METRICS_PROTO: 1');
+      expect(out).toContain('RETRO_METRICS_ERROR: not inside a git repository');
+    } finally {
+      fs.rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  test('local reads only: no network git ops or curl anywhere in the script', () => {
+    const script = fs.readFileSync(SCRIPT, 'utf-8');
+    expect(script).not.toMatch(/(^|[;|&`($!]|\s)git(\s+-C\s+\S+)?\s+(push|pull|fetch|clone|ls-remote)\b/m);
+    expect(script).not.toMatch(/(^|[|&;(`]|\s|\$\()curl\s/);
+  });
+});
@@ -2,20 +2,24 @@
 * Regression tests for #1624 — /retro silently produced empty/misleading
 * output when "today" anchor was wrong or origin/<default> was stale.
 *
- * The fix is Step 0.5 in retro/SKILL.md.tmpl: four ordered pre-check
- * branches before any window analysis. These tests are static invariants
- * against the template body — they fail the build if the guard is removed,
- * weakened, or its ordering broken.
+ * The guard survived the retro token-reduction wave in two halves:
+ *   - LOCAL checks (remote present? detached HEAD? newest commit date on the
+ *     analyzed ref) live in bin/gstack-retro-metrics, emitted as
+ *     GUARD_REMOTE / GUARD_HEAD / GUARD_LATEST_COMMIT lines.
+ *   - The FETCH (network op — kept in skill prose, never in the script) and
+ *     the ordered skip/BLOCK decision rules live in retro/SKILL.md.tmpl
+ *     (Step 0.5 fetch fence + Step 1 guard prose).
 *
- * Branches under test:
- *   1. no-remote skip          — git remote returns empty
- *   2. detached-HEAD skip      — git symbolic-ref --quiet HEAD returns empty
- *   3. fetch-fail warn         — git fetch origin <default> exits non-zero
- *   4. stale-base BLOCK        — fetch ok, latest commit older than window
+ * These static invariants fail the build if the guard is removed, weakened,
+ * or its ordering broken:
+ *   1. no-remote skip          — script emits GUARD_REMOTE: none
+ *   2. detached-HEAD skip      — script emits GUARD_HEAD: detached
+ *   3. fetch-fail warn         — Step 0.5 fence discloses and proceeds
+ *   4. stale-base BLOCK        — fetch ok + latest commit older than window
 *
- * Each branch must short-circuit further checks (only one verdict wins) and
- * must surface a disclosure line on stderr so the narrative carries the
- * reason rather than silently misreporting.
+ * Skip paths must carry a disclosure into the narrative; BLOCK must cite the
+ * date and the remediation. Behavioral coverage of the script's guard
+ * emissions lives in test/gstack-retro-metrics.test.ts.
 */
 import { describe, expect, test } from "bun:test";
 import * as fs from "node:fs";
@@ -23,124 +27,120 @@ import * as path from "node:path";

 const ROOT = path.resolve(import.meta.dir, "..");
 const RETRO_TMPL = path.join(ROOT, "retro", "SKILL.md.tmpl");
-const RETRO_MD = path.join(ROOT, "retro", "SKILL.md");
+const METRICS_SCRIPT = path.join(ROOT, "bin", "gstack-retro-metrics");

 function readTmpl(): string {
  return fs.readFileSync(RETRO_TMPL, "utf-8");
 }

-function readMd(): string {
-  return fs.readFileSync(RETRO_MD, "utf-8");
+function readScript(): string {
+  return fs.readFileSync(METRICS_SCRIPT, "utf-8");
 }

-describe("#1624 retro stale-base guard — Step 0.5 exists and is ordered before Step 1", () => {
-  test("Step 0.5 header is present in template", () => {
-    const body = readTmpl();
-    expect(body).toMatch(/### Step 0\.5: Stale-base \+ bad-today-anchor pre-flight guard/);
-  });
-
-  test("Step 0.5 appears before Step 1: Gather Raw Data", () => {
+describe("#1624 retro stale-base guard — pre-flight ordered before analysis", () => {
+  test("Step 0.5 fetch pre-flight is present and precedes Step 1", () => {
    const body = readTmpl();
    const step05 = body.indexOf("### Step 0.5:");
-    const step1 = body.indexOf("### Step 1: Gather Raw Data");
+    const step1 = body.indexOf("### Step 1: Gather");
    expect(step05).toBeGreaterThan(-1);
    expect(step1).toBeGreaterThan(-1);
    expect(step05).toBeLessThan(step1);
  });

-  test("regenerated SKILL.md carries the Step 0.5 guard", () => {
-    const md = readMd();
-    expect(md).toMatch(/Step 0\.5: Stale-base \+ bad-today-anchor pre-flight guard/);
+  test("guard evaluation prose sits in Step 1 before the metric interpretation steps", () => {
+    const body = readTmpl();
+    const guard = body.indexOf("Stale-base + bad-today-anchor guard");
+    const step2 = body.indexOf("### Step 2: Compute Metrics");
+    expect(guard).toBeGreaterThan(-1);
+    expect(step2).toBeGreaterThan(-1);
+    expect(guard).toBeLessThan(step2);
  });
 });

 describe("#1624 retro guard — branch A: no-remote skip", () => {
-  test("template checks for 'origin' remote absence and skips with disclosure", () => {
-    const body = readTmpl();
-    // Must check git remote for 'origin' and short-circuit
-    expect(body).toMatch(/git remote[^|]*\|\s*grep -c '\^origin\$'/);
-    expect(body).toMatch(/RETRO_GUARD: no 'origin' remote/);
+  test("script checks for 'origin' remote absence and emits GUARD_REMOTE", () => {
+    const script = readScript();
+    expect(script).toMatch(/git remote[^|]*\|\s*grep -c '\^origin\$'/);
+    expect(script).toContain("GUARD_REMOTE: none");
+    expect(script).toContain("GUARD_REMOTE: origin");
  });

-  test("no-remote skip sets a verdict variable that gates later checks", () => {
+  test("template prose treats GUARD_REMOTE: none as proceed-with-disclosure", () => {
    const body = readTmpl();
-    // The verdict variable must be set so later branches short-circuit
-    expect(body).toMatch(/_RETRO_GUARD_VERDICT="skip-no-remote"/);
+    expect(body).toMatch(/GUARD_REMOTE: none/);
  });
 });

 describe("#1624 retro guard — branch B: detached-HEAD skip", () => {
-  test("template checks for detached HEAD via git symbolic-ref", () => {
-    const body = readTmpl();
-    expect(body).toMatch(/git symbolic-ref --quiet HEAD/);
-    expect(body).toMatch(/RETRO_GUARD: detached HEAD/);
+  test("script checks for detached HEAD via git symbolic-ref and emits GUARD_HEAD", () => {
+    const script = readScript();
+    expect(script).toMatch(/git symbolic-ref --quiet --short HEAD/);
+    expect(script).toContain("GUARD_HEAD: detached");
  });

-  test("detached-HEAD branch is gated by prior verdict check (ordering)", () => {
+  test("template prose treats GUARD_HEAD: detached as proceed-with-disclosure", () => {
    const body = readTmpl();
-    // The detached-HEAD block must be guarded by the verdict check so
-    // no-remote always wins if both are true.
-    const branchBStart = body.indexOf("# Pre-check B: detached HEAD");
-    expect(branchBStart).toBeGreaterThan(-1);
-    const branchBSlice = body.slice(branchBStart, branchBStart + 500);
-    expect(branchBSlice).toMatch(/if \[ -z "\$_RETRO_GUARD_VERDICT" \]/);
+    expect(body).toMatch(/GUARD_HEAD: detached/);
  });
 });

 describe("#1624 retro guard — branch C: fetch-fail warn", () => {
-  test("template warns and proceeds against last-known origin when fetch fails", () => {
+  test("fetch stays in skill prose (never in the script) and warns on failure", () => {
    const body = readTmpl();
-    // Match either `git fetch ... ||` or `if ! git fetch ...` shape.
-    expect(body).toMatch(/(?:if !\s+|[^\n]*\|\|\s*)git fetch origin <default>|git fetch origin <default>[^\n]*--quiet 2>\/dev\/null; then/);
-    expect(body).toMatch(/fetch[^\n]*failed[^\n]*offline/);
-    expect(body).toMatch(/_RETRO_GUARD_VERDICT="warn-fetch-failed"/);
+    expect(body).toMatch(/git fetch origin <default> --quiet/);
+    expect(body).toMatch(/RETRO_FETCH: failed[^\n]*offline/);
+    // The script must stay local-reads-only: no fetch/pull/push/clone.
+    const script = readScript();
+    expect(script).not.toMatch(/(^|[;|&`($!]|\s)git(\s+-C\s+\S+)?\s+(push|pull|fetch|clone|ls-remote)\b/m);
  });

-  test("fetch-fail warn is gated by prior verdict check (ordering)", () => {
+  test("fetch failure downgrades BLOCK to proceed (ordering)", () => {
    const body = readTmpl();
-    const branchCStart = body.indexOf("# Pre-check C: fetch origin");
-    expect(branchCStart).toBeGreaterThan(-1);
-    const branchCSlice = body.slice(branchCStart, branchCStart + 500);
-    expect(branchCSlice).toMatch(/if \[ -z "\$_RETRO_GUARD_VERDICT" \]/);
+    // Rule 1 (skip paths incl. fetch-fail) must be evaluated before rule 2
+    // (BLOCK), and BLOCK must be conditioned on the fetch having succeeded.
+    const skipRule = body.indexOf("the Step 0.5 fetch failed");
+    const blockRule = body.indexOf("Retro window is stale");
+    expect(skipRule).toBeGreaterThan(-1);
+    expect(blockRule).toBeGreaterThan(-1);
+    expect(skipRule).toBeLessThan(blockRule);
+    expect(body).toMatch(/fetch succeeded AND/);
  });
 });

 describe("#1624 retro guard — branch D: stale-base BLOCK", () => {
-  test("template extracts latest origin/<default> commit date via git log -1 --format=%ci", () => {
-    const body = readTmpl();
-    // The BLOCK check must read the actual latest-commit date so the
-    // disclosure is concrete (not generic).
-    expect(body).toMatch(/git log -1 --format=%ci origin\/<default>/);
+  test("script extracts the latest analyzed-ref commit date via git log -1 --format=%ci", () => {
+    const script = readScript();
+    expect(script).toMatch(/git log -1 --format=%ci/);
+    expect(script).toContain("GUARD_LATEST_COMMIT:");
  });

  test("BLOCK prose names latest-commit date and instructs user remediation", () => {
    const body = readTmpl();
-    // The BLOCK message must cite the date AND tell the user how to recover.
-    // "Retro window is stale" is the canonical first line.
    expect(body).toMatch(/Retro window is stale/);
    expect(body).toMatch(/git fetch origin <default>/);
    expect(body).toMatch(/Confirm today's date/);
  });

-  test("BLOCK branch is gated by prior verdict checks (ordering)", () => {
+  test("today comes from the session reminder, never the system clock", () => {
    const body = readTmpl();
-    const branchDStart = body.indexOf("# Pre-check D:");
-    expect(branchDStart).toBeGreaterThan(-1);
-    const branchDSlice = body.slice(branchDStart, branchDStart + 800);
-    expect(branchDSlice).toMatch(/if \[ -z "\$_RETRO_GUARD_VERDICT" \]/);
+    expect(body).toMatch(/session reminder/);
+    expect(body).toMatch(/NEVER from `date`/);
  });
 });

 describe("#1624 retro guard — disclosure must reach the narrative", () => {
-  test("template names the skip paths that must carry a disclosure line", () => {
+  test("skip paths carry a disclosure line into the retro output", () => {
    const body = readTmpl();
-    // The post-bash prose must explicitly tell the model to surface
-    // these reasons in the retro output rather than silently dropping them.
-    expect(body).toMatch(/skip-no-remote/);
-    expect(body).toMatch(/skip-detached/);
-    expect(body).toMatch(/warn-fetch-failed/);
-    // The prose names disclosure + narrative together (either order) so the
-    // retro output is never silently confidently-wrong.
+    // The prose ties disclosure + narrative together so the retro output is
+    // never silently confidently-wrong on offline/local-only runs.
+    expect(body).toMatch(/offline run, window not freshness-verified/);
    expect(body).toMatch(/(?:disclosure[\s\S]{0,200}narrative|narrative[\s\S]{0,200}disclosure)/);
  });
+
+  test("non-default analyzed ref is disclosed (RETRO_REF)", () => {
+    const body = readTmpl();
+    expect(body).toMatch(/RETRO_REF/);
+    const script = readScript();
+    expect(script).toContain("RETRO_REF:");
+  });
 });
@@ -6,7 +6,7 @@ import {
  logCost, recordE2E,
  createEvalCollector, finalizeEvalCollector,
 } from './helpers/e2e-helpers';
-import { extractSkillSections, RETRO_E2E_SECTIONS } from './helpers/skill-fixture';
+import { extractSkillSections } from './helpers/skill-fixture';
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -14,6 +14,53 @@ import * as os from 'os';

 const evalCollector = createEvalCollector('e2e-retro');

+// Carved-skill fixture (retro wave): the repo-scoped retro flow lives in the
+// skeleton's H2 sections below, and the narrative report format lives in
+// retro/sections/report-format.md (the skeleton Step 14 is a STOP-Read
+// pointer). The fixture ships skeleton + section + bin/gstack-retro-metrics —
+// still an extraction, not a full-file copy (sections ARE the minimal
+// on-demand units; same pattern as skill-e2e-review-army.test.ts).
+const RETRO_SKELETON_SECTIONS = [
+  'When to invoke this skill',
+  'Step 0: Detect platform and base branch',
+  'User-invocable',
+  'Arguments',
+  'Instructions',
+  'Prior Learnings',
+  'Capture Learnings',
+  'Tone',
+  'Important Rules',
+];
+
+/** Write retro/SKILL.md + sections + the metrics script into a fixture dir. */
+function buildRetroFixture(dir: string): void {
+  let skillMd = extractSkillSections(path.join(ROOT, 'retro'), RETRO_SKELETON_SECTIONS);
+  // The skeleton's STOP-Read points at the installed absolute section path
+  // (~/.claude/skills/gstack/retro/sections/...), which doesn't exist under
+  // the hermetic temp HOME — repoint it at the fixture copy.
+  skillMd = skillMd.replace(
+    /[^\s`]*\/retro\/sections\/report-format\.md/g,
+    path.join(dir, 'retro', 'sections', 'report-format.md'),
+  );
+  fs.mkdirSync(path.join(dir, 'retro', 'sections'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'retro', 'SKILL.md'), skillMd);
+  fs.copyFileSync(
+    path.join(ROOT, 'retro', 'sections', 'report-format.md'),
+    path.join(dir, 'retro', 'sections', 'report-format.md'),
+  );
+  // The Step 1 fence resolves bin/gstack-retro-metrics via
+  // $HOME/.claude/skills/gstack/bin first (absent in the hermetic HOME), then
+  // the cwd-relative .claude/skills/gstack/bin fallback — satisfy the fallback
+  // so the run exercises the real script instead of the degraded path.
+  const binDir = path.join(dir, '.claude', 'skills', 'gstack', 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  fs.copyFileSync(
+    path.join(ROOT, 'bin', 'gstack-retro-metrics'),
+    path.join(binDir, 'gstack-retro-metrics'),
+  );
+  fs.chmodSync(path.join(binDir, 'gstack-retro-metrics'), 0o755);
+}
+
 // --- Retro base branch detection smoke test ---

 describeIfSelected('Base branch detection', ['retro-base-branch'], () => {
@@ -52,11 +99,7 @@ describeIfSelected('Base branch detection', ['retro-base-branch'], () => {

    // Retro skill — extract the repo-scoped retro flow only (drops the shared
    // preamble + global/compare modes; CLAUDE.md: "extract, don't copy").
-    fs.mkdirSync(path.join(dir, 'retro'), { recursive: true });
-    fs.writeFileSync(
-      path.join(dir, 'retro', 'SKILL.md'),
-      extractSkillSections(path.join(ROOT, 'retro'), RETRO_E2E_SECTIONS),
-    );
+    buildRetroFixture(dir);

    const result = await runSkillTest({
      prompt: `Read retro/SKILL.md for instructions on how to run a retrospective.
@@ -137,12 +180,8 @@ describeIfSelected('Retro E2E', ['retro'], () => {
    run('git', ['add', 'README.md']);
    run('git', ['commit', '-m', 'docs: add README', '--date', '2026-03-12T16:00:00']);

-    // Retro skill — extracted repo-scoped flow, not the full 1820-line file.
-    fs.mkdirSync(path.join(retroDir, 'retro'), { recursive: true });
-    fs.writeFileSync(
-      path.join(retroDir, 'retro', 'SKILL.md'),
-      extractSkillSections(path.join(ROOT, 'retro'), RETRO_E2E_SECTIONS),
-    );
+    // Retro skill — extracted repo-scoped flow, not the full file.
+    buildRetroFixture(retroDir);
  });

  afterAll(() => {
@@ -195,14 +195,24 @@ describe('real-skill pins: section lists used by E2E fixtures', () => {
    expect(army).toContain('MULTI-SPECIALIST CONFIRMED');
  });

-  test('RETRO_E2E_SECTIONS extracts from retro/SKILL.md', () => {
-    const out = extractSkillSections(path.join(ROOT, 'retro'), RETRO_E2E_SECTIONS);
+  test('RETRO_E2E_SECTIONS skeleton extracts from retro/SKILL.md + carved section', () => {
+    // Carved (retro wave): the '## Engineering Retro: [date range]' report
+    // format lives in retro/sections/report-format.md; the E2E fixture builds
+    // skeleton sections + the section file (see skill-e2e-retro.test.ts).
+    const skeletonSections = RETRO_E2E_SECTIONS.filter(
+      (s) => s !== 'Engineering Retro: [date range]',
+    );
+    const out = extractSkillSections(path.join(ROOT, 'retro'), skeletonSections);
    // Steps 0.5-14 live under Prior Learnings / Capture Learnings.
-    expect(out).toContain('### Step 1: Gather Raw Data');
+    expect(out).toContain('### Step 1: Gather');
    expect(out).toContain('### Step 14: Write the Narrative');
-    expect(out).toContain('## Engineering Retro: [date range]');
    expect(out).not.toContain('## Global Retrospective Mode');
    expect(out).not.toContain('## Telemetry (run last)');
+
+    const reportFormat = fs.readFileSync(
+      path.join(ROOT, 'retro', 'sections', 'report-format.md'), 'utf-8');
+    expect(reportFormat).toContain('## Engineering Retro: [date range]');
+    expect(reportFormat).toContain('### Team Breakdown');
  });

  test('CODEX_REVIEW_E2E_SECTIONS extracts from the Codex host variant when present', () => {