@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/bin/lib/timeline.cjs

@@ -0,0 +1,605 @@
+"use strict";
+/**
+ * Phase Timeline: run records for the orchestrator `Agent()` spawns (Phase 35).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/timeline.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * Record store (D-01, D-02): `{phase_dir}/{padded}-TIMELINE.jsonl`, one JSON
+ * object per line, append-only. `start` appends a full record with null end
+ * fields; `end` appends a second complete line carrying the same `id`. The
+ * current state of a run is the LAST line with its id (D-06), so nothing is
+ * ever rewritten and a torn final line costs one record at most.
+ *
+ * Only the orchestrator calls this verb, on its own checkout, after `Agent()`
+ * returns (D-03). Time comes from `realClock` so `GSD_TEST_MODE` +
+ * `GSD_NOW_MS` make every test deterministic.
+ *
+ * Subcommands: `start <role> <phase>`, `end <role> <phase> <outcome>` and
+ * `summary <phase> [--banner]`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_SOURCE = exports.ROLE_AGENT = exports.TIMELINE_SOURCES = exports.TIMELINE_ROLES = void 0;
+exports.timelineFileName = timelineFileName;
+exports.foldRecords = foldRecords;
+exports.formatDuration = formatDuration;
+exports.buildPhaseTimeline = buildPhaseTimeline;
+exports.renderBanner = renderBanner;
+exports.cmdTimeline = cmdTimeline;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, ERROR_REASON } = io;
+/** Explicitly typed so TypeScript narrows after a failing guard (the destructured `io.error` does not). */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+const clock_cjs_1 = require("./clock.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseScopeMod = require("./phase-scope.cjs");
+const { resolvePhaseForRead, resolvePhaseForWrite } = phaseScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { extractPhaseToken } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelResolverMod = require("./model-resolver.cjs");
+const { resolveModelInternal } = modelResolverMod;
+const security_cjs_1 = require("./security.cjs");
+/** D-02: the eight roles. `other` carries an explicit agent and source. */
+exports.TIMELINE_ROLES = Object.freeze([
+    'researcher', 'pattern-mapper', 'planner', 'plan-checker',
+    'executor', 'code-reviewer', 'verifier', 'other',
+]);
+exports.TIMELINE_SOURCES = Object.freeze([
+    'plan-phase', 'execute-phase', 'code-review',
+]);
+/** D-08: the agent a role runs as when `--agent` is omitted (no entry for `other`). */
+exports.ROLE_AGENT = Object.freeze({
+    'researcher': 'pp-phase-researcher',
+    'pattern-mapper': 'pp-pattern-mapper',
+    'planner': 'pp-planner',
+    'plan-checker': 'pp-plan-checker',
+    'executor': 'pp-executor',
+    'code-reviewer': 'pp-code-reviewer',
+    'verifier': 'pp-verifier',
+});
+/** D-08: the workflow a role belongs to when `--source` is omitted (no entry for `other`). */
+exports.ROLE_SOURCE = Object.freeze({
+    'researcher': 'plan-phase',
+    'pattern-mapper': 'plan-phase',
+    'planner': 'plan-phase',
+    'plan-checker': 'plan-phase',
+    'executor': 'execute-phase',
+    'verifier': 'execute-phase',
+    'code-reviewer': 'code-review',
+});
+const PLAN_RE = /^[A-Za-z0-9_.-]{1,40}$/;
+const MAX_LINE_CHARS = 4096;
+const MAX_TEXT = 80;
+const ID_RE = /^(.+?)-(researcher|pattern-mapper|planner|plan-checker|executor|code-reviewer|verifier|other)(?:-(.+))?-(\d+)$/;
+const VALUE_FLAGS = new Set(['plan', 'agent', 'model', 'source', 'id', 'phase', 'role', 'outcome']);
+function isRole(value) {
+    return typeof value === 'string' && exports.TIMELINE_ROLES.includes(value);
+}
+function isSource(value) {
+    return typeof value === 'string' && exports.TIMELINE_SOURCES.includes(value);
+}
+/** `35-phase-timeline` -> `35-TIMELINE.jsonl` (D-01). */
+function timelineFileName(phaseDirName) {
+    return `${extractPhaseToken(phaseDirName) || phaseDirName}-TIMELINE.jsonl`;
+}
+/**
+ * Free text becomes one short line (T-35-01): prompt-injection markers are
+ * neutralised, control characters and `|` (the table delimiter) become spaces,
+ * whitespace collapses, length is capped. `safeAlphabet` additionally drops
+ * everything outside the agent/model alphabet.
+ */
+function cleanText(value, max = MAX_TEXT, safeAlphabet = false) {
+    const raw = typeof value === 'string' ? value : '';
+    let text = (0, security_cjs_1.sanitizeForPrompt)(raw) || '';
+    text = text.replace(/[\u0000-\u001f\u007f|]/g, ' ');
+    if (safeAlphabet)
+        text = text.replace(/[^A-Za-z0-9_.:@/[\] -]/g, '');
+    return text.replace(/\s+/g, ' ').trim().slice(0, max).trim();
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Turn one parsed JSON value into a record, or null when it fails the shape
+ * check (T-35-03). `duration_ms` is always recomputed from the two timestamps
+ * and clamped at 0 (T-35-04); a stored value is ignored. An `ended_at` that
+ * Date.parse rejects is dropped, which makes the run incomplete. Both
+ * timestamps are re-emitted in canonical ISO form, never as the stored text:
+ * `Date.parse` accepts strings the sanitizer would reject (parenthesised
+ * comments, for one), and the raw value would otherwise flow into `summary`,
+ * `stats.json` and the closing line `end` writes (T-35-03).
+ */
+function normalizeRecord(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const r = value;
+    if (typeof r['id'] !== 'string' || r['id'].length === 0 || r['id'].length > 160)
+        return null;
+    if (!isRole(r['role']))
+        return null;
+    if (typeof r['started_at'] !== 'string')
+        return null;
+    const startMs = Date.parse(r['started_at']);
+    if (!Number.isFinite(startMs))
+        return null;
+    const startedAt = new Date(startMs).toISOString();
+    const role = r['role'];
+    let endedAt = null;
+    let durationMs = null;
+    if (typeof r['ended_at'] === 'string') {
+        const endMs = Date.parse(r['ended_at']);
+        if (Number.isFinite(endMs)) {
+            endedAt = new Date(endMs).toISOString();
+            durationMs = Math.max(0, endMs - startMs);
+        }
+    }
+    const plan = typeof r['plan'] === 'string' && PLAN_RE.test(r['plan']) ? r['plan'] : null;
+    const outcome = typeof r['outcome'] === 'string' ? cleanText(r['outcome']) : null;
+    return {
+        id: r['id'],
+        phase: typeof r['phase'] === 'string' ? cleanText(r['phase'], 40, true) : '',
+        agent: cleanText(r['agent'], MAX_TEXT, true) || exports.ROLE_AGENT[role] || 'unknown',
+        role,
+        model: cleanText(r['model'], MAX_TEXT, true) || 'unknown',
+        plan,
+        started_at: startedAt,
+        ended_at: endedAt,
+        duration_ms: durationMs,
+        outcome,
+        source: isSource(r['source']) ? r['source'] : (exports.ROLE_SOURCE[role] ?? 'execute-phase'),
+    };
+}
+/** Every valid line of a file's text, in file order. Bad lines are skipped, never thrown on. */
+function parseEvents(text) {
+    const events = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim() || line.length > MAX_LINE_CHARS)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue; // torn or foreign line
+        }
+        const record = normalizeRecord(parsed);
+        if (record)
+            events.push(record);
+    }
+    return events;
+}
+function readEvents(file) {
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    return parseEvents(text);
+}
+/** D-06: the current state of each run is its last line. */
+function currentStates(events) {
+    const states = new Map();
+    events.forEach((record, index) => {
+        const prior = states.get(record.id);
+        states.set(record.id, { current: record, seq: prior ? prior.seq : index });
+    });
+    return states;
+}
+/**
+ * D-11: every run of a file's text, one per id (last line wins, D-06), sorted
+ * by `started_at` ascending with ties in file order. Torn and foreign lines are
+ * skipped, so a damaged file degrades to fewer runs instead of an error.
+ */
+function foldRecords(text) {
+    const states = [...currentStates(parseEvents(text)).values()];
+    states.sort((a, b) => {
+        const delta = Date.parse(a.current.started_at) - Date.parse(b.current.started_at);
+        return delta !== 0 ? delta : a.seq - b.seq;
+    });
+    return states.map((state) => state.current);
+}
+/** D-10: `38s`, `45m 10s`, `1h 12m`. Floors; negative and non-finite input is `0s`. */
+function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return '0s';
+    const total = Math.floor(ms / 1000);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    if (hours >= 1)
+        return `${hours}h ${String(minutes).padStart(2, '0')}m`;
+    if (minutes >= 1)
+        return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+    return `${seconds}s`;
+}
+const pad2 = (n) => String(n).padStart(2, '0');
+const localDate = (ms) => {
+    const d = new Date(ms);
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+};
+const localClock = (ms) => {
+    const d = new Date(ms);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+};
+/** max(end) - min(start) over the intervals, or null for an empty list. */
+function spanOf(intervals) {
+    if (intervals.length === 0)
+        return null;
+    let start = Infinity;
+    let end = -Infinity;
+    for (const i of intervals) {
+        if (i.start < start)
+            start = i.start;
+        if (i.end > end)
+            end = i.end;
+    }
+    return { start, end: Math.max(start, end) };
+}
+function labelOf(role, plan, model, duration) {
+    return `${role}${plan ? ' ' + plan : ''}${model && model !== 'inherit' ? ` (${model})` : ''} ${duration}`;
+}
+const runsLabel = (n) => (n === 1 ? '1 run' : `${n} runs`);
+/**
+ * D-04, D-10, D-11, D-13: fold records into the numbers every reader shows.
+ *
+ * Wall-clock interpretation (D-13): each source (plan-phase, execute-phase,
+ * code-review) gets one span, max(ended_at) - min(started_at) over its
+ * completed runs, so parallel executors count once and idle days between
+ * planning and executing drop out. The headline total is the length of the
+ * UNION of those spans: it equals the sum of the spans whenever they are
+ * disjoint, and a code review that runs inside the execute-phase span (the
+ * default flow: execute:post runs the review before the verifier) is counted
+ * once instead of twice. `elapsed` is the raw first-start to last-end span and
+ * agent time is the sum of completed durations. Orphans (no ended_at) are
+ * counted in `incomplete_count` and excluded from all three sums.
+ */
+function buildPhaseTimeline(records) {
+    const completed = records.filter((r) => r.ended_at !== null);
+    const intervalOf = (r) => {
+        const start = Date.parse(r.started_at);
+        return { start, end: start + (r.duration_ms ?? 0) };
+    };
+    const bySource = { 'plan-phase': 0, 'execute-phase': 0, 'code-review': 0 };
+    const spans = [];
+    for (const source of exports.TIMELINE_SOURCES) {
+        const span = spanOf(completed.filter((r) => r.source === source).map(intervalOf));
+        if (!span)
+            continue;
+        bySource[source] = span.end - span.start;
+        if (span.end > span.start)
+            spans.push(span);
+    }
+    spans.sort((a, b) => a.start - b.start);
+    let wallClockMs = 0;
+    let open = null;
+    for (const span of spans) {
+        if (open && span.start <= open.end) {
+            open = { start: open.start, end: Math.max(open.end, span.end) };
+        }
+        else {
+            if (open)
+                wallClockMs += open.end - open.start;
+            open = { ...span };
+        }
+    }
+    if (open)
+        wallClockMs += open.end - open.start;
+    const all = spanOf(completed.map(intervalOf));
+    const elapsedMs = all ? all.end - all.start : 0;
+    const agentTimeMs = completed.reduce((sum, r) => sum + (r.duration_ms ?? 0), 0);
+    const firstStart = records.length > 0 ? Date.parse(records[0].started_at) : null;
+    const date = firstStart === null ? null : localDate(firstStart);
+    const runs = records.map((r) => {
+        const startMs = Date.parse(r.started_at);
+        const done = r.ended_at !== null;
+        return {
+            ...r,
+            display: {
+                started: date !== null && localDate(startMs) !== date ? `${localDate(startMs).slice(5)} ${localClock(startMs)}` : localClock(startMs),
+                duration: done ? formatDuration(r.duration_ms ?? 0) : 'incomplete',
+                outcome: done ? (r.outcome ?? '') : 'incomplete',
+            },
+        };
+    });
+    const longest = completed
+        .map((r, index) => ({ r, index }))
+        .sort((a, b) => {
+        const byDuration = (b.r.duration_ms ?? 0) - (a.r.duration_ms ?? 0);
+        if (byDuration !== 0)
+            return byDuration;
+        const byStart = Date.parse(a.r.started_at) - Date.parse(b.r.started_at);
+        return byStart !== 0 ? byStart : a.index - b.index;
+    })
+        .slice(0, 3)
+        .map(({ r }) => {
+        const duration = formatDuration(r.duration_ms ?? 0);
+        return {
+            role: r.role,
+            plan: r.plan,
+            model: r.model,
+            duration_ms: r.duration_ms ?? 0,
+            duration,
+            label: labelOf(r.role, r.plan, r.model, duration),
+        };
+    });
+    const incompleteCount = records.length - completed.length;
+    let footer = `Total wall-clock: ${formatDuration(wallClockMs)} \u00b7 agent time ${formatDuration(agentTimeMs)} \u00b7 ${runsLabel(records.length)}`;
+    if (incompleteCount > 0)
+        footer += ` (${incompleteCount} incomplete)`;
+    if (elapsedMs !== wallClockMs)
+        footer += ` \u00b7 elapsed ${formatDuration(elapsedMs)}`;
+    return {
+        runs,
+        run_count: records.length,
+        incomplete_count: incompleteCount,
+        wall_clock_ms: wallClockMs,
+        wall_clock: formatDuration(wallClockMs),
+        elapsed_ms: elapsedMs,
+        elapsed: formatDuration(elapsedMs),
+        agent_time_ms: agentTimeMs,
+        agent_time: formatDuration(agentTimeMs),
+        by_source: bySource,
+        longest,
+        date,
+        footer,
+    };
+}
+/** D-14, D-15: the two banner lines, or '' when nothing completed. */
+function renderBanner(t) {
+    if (t.longest.length === 0)
+        return '';
+    return `Wall-clock: ${t.wall_clock} (${runsLabel(t.run_count)})\nLongest: ${t.longest.map((l) => l.label).join(' \u00b7 ')}`;
+}
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--banner') {
+            flags['banner'] = '1';
+        }
+        else if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            if (!VALUE_FLAGS.has(name))
+                error(`Unknown timeline flag: ${arg}`, ERROR_REASON.USAGE);
+            const next = argv[i + 1];
+            if (next === undefined)
+                error(`Missing value for ${arg}`, ERROR_REASON.USAGE);
+            flags[name] = next;
+            i++;
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, flags };
+}
+function requireRole(value) {
+    if (!isRole(value)) {
+        error(`Unknown role: ${String(value)}. Expected one of: ${exports.TIMELINE_ROLES.join(', ')}`, ERROR_REASON.USAGE);
+    }
+    return value;
+}
+function requirePlan(value) {
+    if (value === undefined)
+        return null;
+    if (!PLAN_RE.test(value))
+        error('--plan must match ^[A-Za-z0-9_.-]{1,40}$', ERROR_REASON.USAGE);
+    return value;
+}
+/** The live phase directory a record may be written into (T-35-02, T-35-05). */
+function resolveWriteTarget(cwd, phase) {
+    if (phase === undefined || phase === '')
+        error('Missing phase argument', ERROR_REASON.USAGE);
+    const verdict = resolvePhaseForWrite(cwd, phase);
+    if (!verdict.ok) {
+        if (verdict.reason === 'archived') {
+            error(`Phase ${phase} is archived; timeline records are written to live phases only`, ERROR_REASON.PHASE_NOT_FOUND);
+        }
+        error(`Phase ${phase} directory not found`, ERROR_REASON.PHASE_NOT_FOUND);
+    }
+    const dir = node_path_1.default.join(cwd, verdict.match.directory);
+    const dirName = node_path_1.default.basename(verdict.match.directory);
+    return { token: extractPhaseToken(dirName) || dirName, file: node_path_1.default.join(dir, timelineFileName(dirName)) };
+}
+function cmdStart(cwd, argv, raw) {
+    const { positionals, flags } = parseArgs(argv);
+    const role = requireRole(flags['role'] ?? positionals[0]);
+    const phase = flags['phase'] ?? positionals[1];
+    const plan = requirePlan(flags['plan']);
+    if (flags['source'] !== undefined && !isSource(flags['source'])) {
+        error(`Unknown source: ${flags['source']}. Expected one of: ${exports.TIMELINE_SOURCES.join(', ')}`, ERROR_REASON.USAGE);
+    }
+    if (role === 'other' && (flags['agent'] === undefined || flags['source'] === undefined)) {
+        error('Role "other" requires --agent and --source', ERROR_REASON.USAGE);
+    }
+    const agent = cleanText(flags['agent'], MAX_TEXT, true) || exports.ROLE_AGENT[role];
+    if (!agent)
+        error('Role "other" requires a non-empty --agent', ERROR_REASON.USAGE);
+    const source = isSource(flags['source']) ? flags['source'] : exports.ROLE_SOURCE[role];
+    if (!source)
+        error('Role "other" requires --source', ERROR_REASON.USAGE);
+    const { token, file } = resolveWriteTarget(cwd, phase);
+    let model = cleanText(flags['model'], MAX_TEXT, true);
+    if (!model) {
+        try {
+            model = cleanText(resolveModelInternal(cwd, agent), MAX_TEXT, true);
+        }
+        catch {
+            model = '';
+        }
+        if (!model)
+            model = 'unknown';
+    }
+    const prefix = `${token}-${role}${plan ? '-' + plan : ''}-`;
+    const siblings = new RegExp(`^${escapeRegex(prefix)}\\d+$`);
+    const existing = new Set();
+    for (const record of readEvents(file)) {
+        if (siblings.test(record.id))
+            existing.add(record.id);
+    }
+    const id = `${prefix}${existing.size + 1}`;
+    const record = {
+        id,
+        phase: token,
+        agent,
+        role,
+        model,
+        plan,
+        started_at: clock_cjs_1.realClock.nowIso(),
+        ended_at: null,
+        duration_ms: null,
+        outcome: null,
+        source,
+    };
+    node_fs_1.default.appendFileSync(file, JSON.stringify(record) + '\n');
+    output(record, raw, record.id);
+}
+function cmdEnd(cwd, argv, raw) {
+    const { positionals, flags } = parseArgs(argv);
+    let id;
+    let role;
+    let phase;
+    let outcomeText;
+    if (flags['id'] !== undefined) {
+        id = flags['id'];
+        const derived = ID_RE.exec(id);
+        phase = flags['phase'] ?? positionals[1] ?? (derived ? derived[1] : undefined);
+        outcomeText = flags['outcome'] ?? (positionals.length >= 3 ? positionals[2] : positionals.length === 1 ? positionals[0] : undefined);
+    }
+    else if (positionals.length === 1 && flags['outcome'] !== undefined && ID_RE.test(positionals[0])) {
+        id = positionals[0];
+        const derived = ID_RE.exec(id);
+        phase = flags['phase'] ?? (derived ? derived[1] : undefined);
+        outcomeText = flags['outcome'];
+    }
+    else {
+        role = requireRole(flags['role'] ?? positionals[0]);
+        phase = flags['phase'] ?? positionals[1];
+        outcomeText = flags['outcome'] ?? positionals[2];
+    }
+    if (outcomeText === undefined || cleanText(outcomeText) === '')
+        error('Missing outcome', ERROR_REASON.USAGE);
+    const outcome = cleanText(outcomeText);
+    const plan = requirePlan(flags['plan']);
+    const { file } = resolveWriteTarget(cwd, phase);
+    const states = currentStates(readEvents(file));
+    let target;
+    if (id !== undefined) {
+        const state = states.get(id);
+        if (state && state.current.ended_at === null)
+            target = state.current;
+        if (!target)
+            error(`No open timeline run with id ${id}`, ERROR_REASON.TIMELINE_NO_OPEN_RUN);
+    }
+    else {
+        let best;
+        for (const state of states.values()) {
+            const c = state.current;
+            if (c.ended_at !== null || c.role !== role)
+                continue;
+            if (plan !== null && c.plan !== plan)
+                continue;
+            if (!best) {
+                best = state;
+                continue;
+            }
+            const a = Date.parse(c.started_at);
+            const b = Date.parse(best.current.started_at);
+            if (a > b || (a === b && state.seq > best.seq))
+                best = state;
+        }
+        if (!best) {
+            error(`No open timeline run for role ${String(role)} in phase ${String(phase)}${plan ? ` (plan ${plan})` : ''}`, ERROR_REASON.TIMELINE_NO_OPEN_RUN);
+        }
+        target = best.current;
+    }
+    const endedAt = clock_cjs_1.realClock.nowIso();
+    const closed = {
+        id: target.id,
+        phase: target.phase,
+        agent: target.agent,
+        role: target.role,
+        model: target.model,
+        plan: target.plan,
+        started_at: target.started_at,
+        ended_at: endedAt,
+        duration_ms: Math.max(0, Date.parse(endedAt) - Date.parse(target.started_at)),
+        outcome,
+        source: target.source,
+    };
+    node_fs_1.default.appendFileSync(file, JSON.stringify(closed) + '\n');
+    output(closed, raw, closed.id);
+}
+function cmdSummary(cwd, argv, raw) {
+    const { positionals, flags } = parseArgs(argv);
+    const phase = flags['phase'] ?? positionals[0];
+    const banner = flags['banner'] !== undefined;
+    if (phase === undefined || phase === '')
+        error('Missing phase argument', ERROR_REASON.USAGE);
+    // Readers may use a live or an archived phase (D-12).
+    const match = resolvePhaseForRead(cwd, phase);
+    if (!match) {
+        if (banner)
+            return; // a completion block must never carry a stray line or an error
+        error(`Phase ${phase} not found`, ERROR_REASON.PHASE_NOT_FOUND);
+    }
+    const dir = node_path_1.default.join(cwd, match.directory);
+    let texts = [];
+    try {
+        texts = node_fs_1.default.readdirSync(dir)
+            .filter((name) => name.endsWith('-TIMELINE.jsonl'))
+            .sort()
+            .map((name) => node_fs_1.default.readFileSync(node_path_1.default.join(dir, name), 'utf-8'));
+    }
+    catch {
+        texts = [];
+    }
+    const runs = foldRecords(texts.join('\n'));
+    if (runs.length === 0) {
+        if (banner) {
+            output({ phase, present: false }, true, '');
+        }
+        else {
+            output({ phase, present: false, run_count: 0, message: 'no recorded runs' }, raw, 'no recorded runs');
+        }
+        return;
+    }
+    const timeline = buildPhaseTimeline(runs);
+    if (banner) {
+        output(timeline, true, renderBanner(timeline));
+    }
+    else {
+        output({ phase, present: true, ...timeline }, raw, timeline.footer);
+    }
+}
+function cmdTimeline(cwd, args, raw) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'start':
+            cmdStart(cwd, rest, raw);
+            return;
+        case 'end':
+            cmdEnd(cwd, rest, raw);
+            return;
+        case 'summary':
+            cmdSummary(cwd, rest, raw);
+            return;
+        default:
+            error(`Unknown timeline subcommand: ${String(sub)}. Available: start, end, summary`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}

package/pp-core/bin/lib/vault-standards-review.cjs

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.DEVIATIONS_FILE = exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.readDeviations = readDeviations;
 exports.deriveStandardsReview = deriveStandardsReview;
 exports.formatReviewCounts = formatReviewCounts;
 exports.validateReviewArtifact = validateReviewArtifact;
@@ -59,6 +60,8 @@ exports.REVIEW_VERDICTS_HEADING = '## Standard Verdicts';
 exports.REVIEW_FILES_CAP = 200;
 /** Bound on a git query a review makes. */
 const REVIEW_GIT_TIMEOUT_MS = 30_000;
+/** Where the Discovery Sprint records agreed departures from the vault. */
+exports.DEVIATIONS_FILE = '.planning/discovery/_deviations.md';
 // ─── Derivation ──────────────────────────────────────────────────────────────
 const PLAN_RE = /(^|-)PLAN\.md$/;
 const SUMMARY_RE = /(^|-)SUMMARY\.md$/;
@@ -73,6 +76,47 @@ function readBounded(abs) {
         return null;
     }
 }
+/**
+ * The deviations on file, read by header name so Batch 3's full grammar can
+ * add or reorder columns without touching this reader. `gap` is set when the
+ * file exists but yields no readable table with both join columns.
+ */
+function readDeviations(root) {
+    const abs = node_path_1.default.join(root, exports.DEVIATIONS_FILE);
+    if (!node_fs_1.default.existsSync(abs))
+        return { deviations: [], gap: null };
+    const text = readBounded(abs);
+    if (text === null)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} could not be read (unreadable or over the size cap), so deviations on file are unknown` };
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const table = require('./discovery-table.cjs');
+    const deviations = [];
+    let joinable = false;
+    for (const section of table.splitSections(text.split(/\r?\n/), 2)) {
+        for (const tbl of table.parseTables(section.body)) {
+            const names = tbl.header.map((h) => h.trim().toLowerCase());
+            const col = (name) => names.indexOf(name);
+            const standard = col('standard');
+            const status = col('status');
+            if (standard === -1 || status === -1)
+                continue;
+            joinable = true;
+            const cell = (row, i) => (i === -1 ? '' : (row.cells[i] ?? '').trim());
+            for (const row of tbl.rows) {
+                deviations.push({
+                    id: cell(row, col('id')),
+                    standard: cell(row, standard),
+                    status: cell(row, status),
+                    decision: cell(row, col('decision')),
+                    approver: cell(row, col('approver')),
+                });
+            }
+        }
+    }
+    if (!joinable)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} carries no table with Standard and Status columns, so deviations on file are unknown` };
+    return { deviations, gap: null };
+}
 function consultedText(entry, hasSummary) {
     if (!hasSummary)
         return 'no summary';
@@ -206,6 +250,9 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             });
         }
     }
+    const onFile = readDeviations(root);
+    if (onFile.gap !== null)
+        gaps.push(onFile.gap);
     if (plans.length === 0 || documents.size === 0) {
         return {
             status: 'no-records',
@@ -216,9 +263,10 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             plans,
             documents: [],
             gaps,
+            deviations: onFile.deviations,
         };
     }
-    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps };
+    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps, deviations: onFile.deviations };
 }
 /** The counts line, in verdict order: `p PASS · f FAIL · n N-A · i INCONCLUSIVE (of N documents)`. */
 function formatReviewCounts(counts) {