job-forge 2.14.32 → 2.14.34

package/lib/jobforge-timeline.mjs

@@ -0,0 +1,294 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, join, relative } from 'path';
+import {
+  checkTimeline,
+  filterTimelineResult,
+  loadTimelineConfig,
+  parseJson,
+  parseJsonLines,
+  planTimeline,
+  verifyTimelineResult,
+} from '@razroo/iso-timeline';
+import { DATA_APPS_DIR, PROJECT_DIR, readAllEntries } from '../tracker-lib.mjs';
+import { jobForgeCompanyRoleKey, jobForgeUrlKey, legacyCompanyRoleKey, legacyUrlKey } from './jobforge-canon.mjs';
+
+export const TIMELINE_CONFIG_FILE = 'templates/timeline.json';
+export const TIMELINE_FILE = '.jobforge-timeline.json';
+export const TIMELINE_EVENTS_FILE = '.jobforge-timeline-events.jsonl';
+export const USER_TIMELINE_EVENTS_FILE = 'data/timeline-events.jsonl';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeTimelineConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_TIMELINE_CONFIG || join(projectDir, TIMELINE_CONFIG_FILE);
+}
+
+export function jobForgeTimelinePath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_TIMELINE || join(projectDir, TIMELINE_FILE);
+}
+
+export function jobForgeTimelineEventsPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_TIMELINE_EVENTS || join(projectDir, TIMELINE_EVENTS_FILE);
+}
+
+export function readJobForgeTimelineConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeTimelineConfigPath(projectDir);
+  return loadTimelineConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function timelineExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeTimelinePath(projectDir));
+}
+
+export function timelineEventsExist(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeTimelineEventsPath(projectDir));
+}
+
+export function readJobForgeTimeline(projectDir = resolveProjectDir()) {
+  const path = jobForgeTimelinePath(projectDir);
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function buildJobForgeTimelineEvents(projectDir = resolveProjectDir()) {
+  const events = [
+    ...applicationEvents(projectDir),
+    ...pipelineEvents(projectDir),
+    ...userEvents(projectDir),
+  ];
+  events.sort(compareEvents);
+  return events;
+}
+
+export function writeJobForgeTimelineEvents(events, options = {}, projectDir = resolveProjectDir()) {
+  const out = options.out || jobForgeTimelineEventsPath(projectDir);
+  mkdirSync(dirname(out), { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join('\n');
+  writeFileSync(out, `${content}${content ? '\n' : ''}`, 'utf8');
+  return out;
+}
+
+export function planJobForgeTimeline(options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeTimelineConfig(projectDir);
+  const events = options.events || buildJobForgeTimelineEvents(projectDir);
+  return planTimeline(config, events, { now: options.now });
+}
+
+export function dueJobForgeTimeline(options = {}, projectDir = resolveProjectDir()) {
+  return filterTimelineResult(planJobForgeTimeline(options, projectDir), ['overdue', 'due']);
+}
+
+export function checkJobForgeTimeline(options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeTimelineConfig(projectDir);
+  const events = options.events || buildJobForgeTimelineEvents(projectDir);
+  return checkTimeline(config, events, { now: options.now, failOn: options.failOn });
+}
+
+export function buildJobForgeTimeline(options = {}, projectDir = resolveProjectDir()) {
+  const events = buildJobForgeTimelineEvents(projectDir);
+  const result = planJobForgeTimeline({ now: options.now, events }, projectDir);
+  const eventsOut = writeJobForgeTimelineEvents(events, { out: options.eventsOut }, projectDir);
+  const out = options.out || jobForgeTimelinePath(projectDir);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  return { result, events, out, eventsOut };
+}
+
+export function verifyJobForgeTimeline(options = {}, projectDir = resolveProjectDir()) {
+  const result = options.result || readJobForgeTimeline(projectDir);
+  return verifyTimelineResult(result);
+}
+
+export function jobForgeTimelineSummary(projectDir = resolveProjectDir()) {
+  if (!timelineExists(projectDir)) {
+    return {
+      path: jobForgeTimelinePath(projectDir),
+      eventsPath: jobForgeTimelineEventsPath(projectDir),
+      config: jobForgeTimelineConfigPath(projectDir),
+      exists: false,
+      eventsExists: timelineEventsExist(projectDir),
+      items: 0,
+      due: 0,
+      overdue: 0,
+    };
+  }
+  const result = readJobForgeTimeline(projectDir);
+  return {
+    path: jobForgeTimelinePath(projectDir),
+    eventsPath: jobForgeTimelineEventsPath(projectDir),
+    config: jobForgeTimelineConfigPath(projectDir),
+    exists: true,
+    eventsExists: timelineEventsExist(projectDir),
+    items: result.stats?.total || 0,
+    due: result.stats?.due || 0,
+    overdue: result.stats?.overdue || 0,
+    generatedAt: result.generatedAt,
+    id: result.id,
+  };
+}
+
+function applicationEvents(projectDir) {
+  const { entries } = readAllEntries();
+  return entries
+    .map((entry) => applicationEvent(entry, projectDir))
+    .filter(Boolean);
+}
+
+function applicationEvent(entry, projectDir) {
+  const at = dateToIso(entry.date);
+  if (!at || !entry.company || !entry.role || !entry.status) return null;
+  const status = canonicalStatus(entry.status);
+  const key = safeCompanyRoleKey(entry.company, entry.role, projectDir);
+  return {
+    id: `jobforge:application-status:${entry.num}:${key}:${at}`,
+    key,
+    type: 'application.status',
+    at,
+    data: compactObject({
+      num: entry.num,
+      date: entry.date,
+      company: entry.company,
+      role: entry.role,
+      score: entry.score,
+      status,
+      pdf: entry.pdf,
+      report: entry.report,
+      notes: entry.notes,
+    }),
+    source: sourceForApplication(entry, projectDir),
+  };
+}
+
+function pipelineEvents(projectDir) {
+  const pipelinePath = join(projectDir, 'data', 'pipeline.md');
+  if (!existsSync(pipelinePath)) return [];
+  const scanDates = scanHistoryDates(projectDir);
+  const lines = readFileSync(pipelinePath, 'utf8').split('\n');
+  const events = [];
+  lines.forEach((line, index) => {
+    const match = line.match(/^\s*-\s*\[([ xX])\]\s+(https?:\/\/[^|\s#]+)(.*)$/);
+    if (!match) return;
+    const url = match[2].trim();
+    const at = dateToIso(scanDates.get(url) || firstDateInText(line));
+    if (!at) return;
+    const fields = (match[3] || '').split('|').map((field) => field.trim()).filter(Boolean);
+    const status = match[1].toLowerCase() === 'x' ? 'processed' : 'pending';
+    const key = safeUrlKey(url, projectDir);
+    events.push({
+      id: `jobforge:pipeline:${status}:${key}:${at}`,
+      key,
+      type: status === 'processed' ? 'pipeline.processed' : 'pipeline.item',
+      at,
+      data: compactObject({
+        status,
+        url,
+        company: fields[0],
+        role: fields[1],
+      }),
+      source: {
+        path: 'data/pipeline.md',
+        line: index + 1,
+      },
+    });
+  });
+  return events;
+}
+
+function userEvents(projectDir) {
+  const path = join(projectDir, USER_TIMELINE_EVENTS_FILE);
+  if (!existsSync(path)) return [];
+  return parseJsonLines(readFileSync(path, 'utf8'), path);
+}
+
+function scanHistoryDates(projectDir) {
+  const path = join(projectDir, 'data', 'scan-history.tsv');
+  const dates = new Map();
+  if (!existsSync(path)) return dates;
+  const lines = readFileSync(path, 'utf8').split('\n');
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    if (parts.length < 4) continue;
+    const date = parts[0]?.trim();
+    const url = parts[3]?.trim();
+    if (/^\d{4}-\d{2}-\d{2}/.test(date) && /^https?:\/\//.test(url)) dates.set(url, date);
+  }
+  return dates;
+}
+
+function sourceForApplication(entry, projectDir) {
+  const raw = String(entry._sourceFile || '');
+  if (/^\d{4}-\d{2}-\d{2}\.md$/.test(raw)) {
+    return { path: relativePath(projectDir, join(DATA_APPS_DIR, raw)) };
+  }
+  if (raw) return { path: relativePath(projectDir, raw) };
+  return undefined;
+}
+
+function dateToIso(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(text)) return `${text}T12:00:00.000Z`;
+  const parsed = new Date(text);
+  return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+
+function firstDateInText(value) {
+  return String(value || '').match(/\b\d{4}-\d{2}-\d{2}\b/)?.[0] || '';
+}
+
+function canonicalStatus(value) {
+  const text = String(value || '').trim();
+  const lower = text.toLowerCase();
+  const map = new Map([
+    ['evaluated', 'Evaluated'],
+    ['applied', 'Applied'],
+    ['responded', 'Responded'],
+    ['contacted', 'Contacted'],
+    ['interview', 'Interview'],
+    ['offer', 'Offer'],
+    ['rejected', 'Rejected'],
+    ['discarded', 'Discarded'],
+    ['failed', 'Failed'],
+    ['skip', 'SKIP'],
+  ]);
+  return map.get(lower) || text;
+}
+
+function safeCompanyRoleKey(company, role, projectDir) {
+  try {
+    return jobForgeCompanyRoleKey(company, role, projectDir);
+  } catch {
+    return legacyCompanyRoleKey(company, role);
+  }
+}
+
+function safeUrlKey(url, projectDir) {
+  try {
+    return jobForgeUrlKey(url, projectDir);
+  } catch {
+    return legacyUrlKey(url);
+  }
+}
+
+function compactObject(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function compareEvents(a, b) {
+  return `${a.at}\0${a.key}\0${a.type}\0${a.id || ''}`.localeCompare(`${b.at}\0${b.key}\0${b.type}\0${b.id || ''}`);
+}
+
+function relativePath(projectDir, value) {
+  const text = String(value || '');
+  if (!text) return '';
+  const rel = relative(projectDir, text);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replace(/\\/g, '/');
+  return text.replace(/\\/g, '/');
+}

package/modes/followup.md

@@ -1,6 +1,6 @@
 # Mode: followup — Follow-Up Timing & Nudge System
 
-Scans all day files in `data/applications/` for entries that need follow-up action based on their current state and how long they've been in that state.
+Uses `job-forge timeline:*` to scan local tracker and dated pipeline sources for entries that need follow-up action based on their current state and how long they've been in that state.
 
 **This mode is read-only on existing pipeline logic.** It reads the tracker and suggests actions — it never changes scores, reports, or pipeline behavior.
 
@@ -19,11 +19,11 @@ Scans all day files in `data/applications/` for entries that need follow-up acti
 
 ## Run This Workflow
 
-1. **Read** all day files in `data/applications/` — parse all entries with dates.
-2. **Compute** days since the date column for each entry (using today's date).
-3. **Filter** to entries matching the Timing Rules table above.
-4. **Sort** by urgency (most overdue first).
-5. **Present** action list.
+1. Run `npx job-forge timeline:due` first. It rebuilds the due queue from local tracker/pipeline sources without loading growing files into prompt context.
+2. If the user wants a persistent artifact, run `npx job-forge timeline:build`.
+3. Use `npx job-forge timeline:check --fail-on overdue` when the workflow should fail only on stale actions.
+4. Present the action list grouped by `OVERDUE`, `DUE`, and upcoming manual context if needed.
+5. Only read individual tracker/report files after the user selects an action that needs message drafting.
 
 ```
 ## Follow-Up Actions — {today's date}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.32",
+  "version": "2.14.34",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -78,6 +78,27 @@
     "postflight:status": "node bin/job-forge.mjs postflight:status",
     "postflight:check": "node bin/job-forge.mjs postflight:check",
     "postflight:explain": "node bin/job-forge.mjs postflight:explain",
+    "timeline:status": "node bin/job-forge.mjs timeline:status",
+    "timeline:build": "node bin/job-forge.mjs timeline:build",
+    "timeline:plan": "node bin/job-forge.mjs timeline:plan",
+    "timeline:due": "node bin/job-forge.mjs timeline:due",
+    "timeline:check": "node bin/job-forge.mjs timeline:check",
+    "timeline:verify": "node bin/job-forge.mjs timeline:verify",
+    "timeline:explain": "node bin/job-forge.mjs timeline:explain",
+    "prioritize:status": "node bin/job-forge.mjs prioritize:status",
+    "prioritize:items": "node bin/job-forge.mjs prioritize:items",
+    "prioritize:build": "node bin/job-forge.mjs prioritize:build",
+    "prioritize:rank": "node bin/job-forge.mjs prioritize:rank",
+    "prioritize:select": "node bin/job-forge.mjs prioritize:select",
+    "prioritize:check": "node bin/job-forge.mjs prioritize:check",
+    "prioritize:verify": "node bin/job-forge.mjs prioritize:verify",
+    "prioritize:explain": "node bin/job-forge.mjs prioritize:explain",
+    "lineage:status": "node bin/job-forge.mjs lineage:status",
+    "lineage:record": "node bin/job-forge.mjs lineage:record",
+    "lineage:check": "node bin/job-forge.mjs lineage:check",
+    "lineage:stale": "node bin/job-forge.mjs lineage:stale",
+    "lineage:verify": "node bin/job-forge.mjs lineage:verify",
+    "lineage:explain": "node bin/job-forge.mjs lineage:explain",
     "redact:scan": "node bin/job-forge.mjs redact:scan",
     "redact:verify": "node bin/job-forge.mjs redact:verify",
     "redact:apply": "node bin/job-forge.mjs redact:apply",
@@ -161,12 +182,15 @@
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-index": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",
+    "@razroo/iso-lineage": "^0.1.0",
     "@razroo/iso-migrate": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-postflight": "^0.1.0",
     "@razroo/iso-preflight": "^0.1.0",
+    "@razroo/iso-prioritize": "^0.1.0",
     "@razroo/iso-redact": "^0.1.0",
     "@razroo/iso-score": "^0.1.0",
+    "@razroo/iso-timeline": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"
   },

package/scripts/check-iso-smoke.mjs

@@ -20,6 +20,9 @@ const checks = [
   ["H6 requires merge and verify", () => every(files.instructions, ["batch/tracker-additions/*.tsv", "npx job-forge merge", "npx job-forge verify"])],
   ["H7 distrusts subagent prose", () => every(files.instructions, ["must originate from a file", "not from prior subagent prose"])],
   ["score policy points to local helper", () => every(files.instructions, ["[D19]", "templates/score.json", "npx job-forge score:check", "npx job-forge score:gate"])],
+  ["timeline policy points to local helper", () => every(files.instructions, ["[D20]", "templates/timeline.json", "npx job-forge timeline:due", "npx job-forge timeline:check --fail-on overdue"])],
+  ["prioritize policy points to local helper", () => every(files.instructions, ["[D21]", "templates/prioritize.json", "npx job-forge prioritize:build", "npx job-forge prioritize:select --limit N"])],
+  ["lineage policy points to local helper", () => every(files.instructions, ["[D22]", ".jobforge-lineage.json", "npx job-forge lineage:record", "npx job-forge lineage:check"])],
   ["shared prompt points to on-demand references", () => every(files.instructions, ["modes/{mode}.md", "modes/reference-setup.md", "modes/reference-portals.md", "modes/reference-geometra.md"])],
   ["apply mode owns high-stakes upgrade", () => every(files.apply, ["[D8]", "@general-paid", "4.0/5", "high-stakes"])],
   ["apply mode blocks provider auto-downgrade", () => every(files.apply, ["[D9]", "do not auto-downgrade", "inspect telemetry before retrying"])],

package/scripts/lineage.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+import { relative, resolve } from 'path';
+import {
+  formatCheckResult,
+  formatExplainGraph,
+  formatRecordResult,
+  formatStaleResult,
+  formatVerifyResult,
+  parseJson,
+} from '@razroo/iso-lineage';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  checkJobForgeLineage,
+  jobForgeLineagePath,
+  jobForgeLineageSummary,
+  lineageExists,
+  normalizeJobForgeLineageArtifact,
+  readJobForgeLineage,
+  readJobForgeLineageOrEmpty,
+  recordJobForgeLineage,
+  staleJobForgeLineage,
+  verifyJobForgeLineage,
+} from '../lib/jobforge-lineage.mjs';
+
+const USAGE = `job-forge lineage - deterministic artifact lineage and stale-output checks
+
+Usage:
+  job-forge lineage:status [--json]
+  job-forge lineage:record --artifact <file> [--input <file>...] [--optional-input <file>...] [--kind <kind>] [--command <cmd>] [--metadata <json>] [--now <iso>] [--json]
+  job-forge lineage:check [--artifact <file>] [--json]
+  job-forge lineage:stale [--json]
+  job-forge lineage:verify [--json]
+  job-forge lineage:explain [--artifact <file>] [--json]
+  job-forge lineage:path
+
+Default graph is .jobforge-lineage.json. Record generated reports, PDFs, and
+other derived artifacts against their source CV/profile/report inputs, then
+check whether outputs are stale after inputs change.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeLineagePath(PROJECT_DIR));
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'record') {
+    record(opts);
+  } else if (cmd === 'check') {
+    check(opts);
+  } else if (cmd === 'stale') {
+    stale(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown lineage command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = {
+    json: false,
+    help: false,
+    inputs: [],
+    optionalInputs: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--artifact') {
+      opts.artifact = valueAfter(args, ++i, '--artifact');
+    } else if (arg.startsWith('--artifact=')) {
+      opts.artifact = arg.slice('--artifact='.length);
+    } else if (arg === '--input') {
+      opts.inputs.push(valueAfter(args, ++i, '--input'));
+    } else if (arg.startsWith('--input=')) {
+      opts.inputs.push(arg.slice('--input='.length));
+    } else if (arg === '--optional-input') {
+      opts.optionalInputs.push(valueAfter(args, ++i, '--optional-input'));
+    } else if (arg.startsWith('--optional-input=')) {
+      opts.optionalInputs.push(arg.slice('--optional-input='.length));
+    } else if (arg === '--kind') {
+      opts.kind = valueAfter(args, ++i, '--kind');
+    } else if (arg.startsWith('--kind=')) {
+      opts.kind = arg.slice('--kind='.length);
+    } else if (arg === '--command') {
+      opts.command = valueAfter(args, ++i, '--command');
+    } else if (arg.startsWith('--command=')) {
+      opts.command = arg.slice('--command='.length);
+    } else if (arg === '--metadata') {
+      opts.metadata = parseMetadata(valueAfter(args, ++i, '--metadata'));
+    } else if (arg.startsWith('--metadata=')) {
+      opts.metadata = parseMetadata(arg.slice('--metadata='.length));
+    } else if (arg === '--now') {
+      opts.now = valueAfter(args, ++i, '--now');
+    } else if (arg.startsWith('--now=')) {
+      opts.now = arg.slice('--now='.length);
+    } else if (arg === '--out') {
+      opts.out = resolve(PROJECT_DIR, valueAfter(args, ++i, '--out'));
+    } else if (arg.startsWith('--out=')) {
+      opts.out = resolve(PROJECT_DIR, arg.slice('--out='.length));
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseMetadata(value) {
+  const parsed = parseJson(value, '--metadata');
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--metadata must be a JSON object');
+  }
+  return parsed;
+}
+
+function status(opts) {
+  const summary = jobForgeLineageSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  if (!summary.exists) {
+    console.log(`lineage: missing (${relativePath(summary.path)})`);
+    console.log('run: job-forge lineage:record --artifact <file> --input <file>');
+    return;
+  }
+  console.log(`lineage: ${relativePath(summary.path)}`);
+  console.log(`records: ${summary.records}`);
+  console.log(`current: ${summary.current}`);
+  console.log(`stale:   ${summary.stale}`);
+  console.log(`missing: ${summary.missing}`);
+  console.log(`check:   ${summary.ok ? 'PASS' : 'STALE'}`);
+}
+
+function record(opts) {
+  const result = recordJobForgeLineage({
+    artifact: opts.artifact,
+    inputs: opts.inputs,
+    optionalInputs: opts.optionalInputs,
+    kind: opts.kind,
+    command: opts.command,
+    metadata: opts.metadata,
+    now: opts.now,
+    out: opts.out,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatRecordResult(result.graph, result.record, relativePath(result.out)));
+}
+
+function check(opts) {
+  if (!lineageExists(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeLineagePath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`lineage: missing (${relativePath(jobForgeLineagePath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = checkJobForgeLineage({ artifact: opts.artifact }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatCheckResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function stale(opts) {
+  if (!lineageExists(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeLineagePath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`lineage: missing (${relativePath(jobForgeLineagePath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = staleJobForgeLineage({}, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatStaleResult(result));
+  }
+}
+
+function verify(opts) {
+  if (!lineageExists(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeLineagePath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`lineage: missing (${relativePath(jobForgeLineagePath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = verifyJobForgeLineage({}, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function explain(opts) {
+  const graph = lineageExists(PROJECT_DIR) ? readJobForgeLineage(PROJECT_DIR) : readJobForgeLineageOrEmpty(PROJECT_DIR);
+  const artifact = opts.artifact
+    ? normalizeJobForgeLineageArtifact(PROJECT_DIR, opts.artifact)
+    : undefined;
+  if (opts.json) {
+    const records = artifact ? graph.records.filter((record) => record.artifact.path === artifact) : graph.records;
+    console.log(JSON.stringify({ ...graph, records }, null, 2));
+    return;
+  }
+  console.log(formatExplainGraph(graph, artifact));
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}