job-forge 2.14.31 → 2.14.33

package/iso/commands/job-forge.md

@@ -93,6 +93,10 @@ Postflight dispatch settlement (terminal, outside opencode):
   npx job-forge postflight:status --plan batch/preflight-plan.json --outcomes batch/postflight-outcomes.json
   npx job-forge postflight:check --plan batch/preflight-plan.json --outcomes batch/postflight-outcomes.json
 
+Follow-up timeline (terminal, outside opencode):
+  npx job-forge timeline:due
+  npx job-forge timeline:check --fail-on overdue
+
 Consumer migrations (terminal, outside opencode):
   npx job-forge migrate:plan           # preview package.json/.gitignore drift
   npx job-forge migrate:apply          # apply safe harness upgrade migrations
@@ -102,6 +106,11 @@ Artifact contracts (terminal, outside opencode):
   npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
   npx job-forge tracker-line ... --write   # renders + validates tracker TSV locally
 
+Score policy (terminal, outside opencode):
+  npx job-forge score:check --input /tmp/score.json
+  npx job-forge score:gate --input /tmp/score.json --gate apply
+  npx job-forge score:explain
+
 Role capabilities (terminal, outside opencode):
   npx job-forge capabilities:explain general-free
   npx job-forge capabilities:check general-free --tool browser --mcp geometra --filesystem write
@@ -210,6 +219,9 @@ Step 4  — Materialize and check the dispatch plan
     (or another explicit JSON file). Include source paths for company, role,
     companyRoleKey, URL, score, duplicate/location gates, and any skip/block
     decision.
+  - If the candidate came from a fresh evaluation score JSON, run npx job-forge
+    score:check --input <score.json> and npx job-forge score:gate --input
+    <score.json> --gate apply before using that score as an apply gate.
   - Run npx job-forge preflight:check --candidates <file> to fail on missing
     sources or blocked gates, then npx job-forge preflight:plan --candidates
     <file> --json > batch/preflight-plan.json to get the bounded round list.

package/iso/instructions.md

@@ -19,13 +19,13 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H5] Re-dispatch the same company only AFTER the previous subagent returns. Never fire the same `task` twice while the first is still in flight.
   why: two in-flight subagents for the same URL race on Geometra sessions and on tracker TSV writes, corrupting state and sometimes double-submitting
 
-- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, `.jobforge-index.json`, `.jobforge-facts.json`, or `iso-trace`) rather than spawning a "check task status" subagent.
+- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, `.jobforge-index.json`, `.jobforge-facts.json`, `.jobforge-timeline.json`, or `iso-trace`) rather than spawning a "check task status" subagent.
   why: OpenCode status prompts can be delivered into the target subagent as a new user message; a 2026-04-25 trace caused a subagent to call `task` recursively instead of finishing the application
 
 - [H6] Application outcomes flow through `batch/tracker-additions/*.tsv`, not `data/pipeline.md`. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` then `npx job-forge verify` before ending the session.
   why: `pipeline.md` is the URL inbox (`[ ]` pending → `[x]` processed); `data/applications/YYYY-MM-DD.md` is the outcome log; the TSV pathway is the only safe bridge because `merge` handles column order and duplicate detection
 
-- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, and materialized fact records returned by `npx job-forge facts:query ...`.
+- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, emitted score JSON validated by `npx job-forge score:check --input ...`, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, and materialized fact records returned by `npx job-forge facts:query ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
 - [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
@@ -90,16 +90,22 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D18] Treat `templates/redact.json` as the source of truth before exporting local traces, prompts, reports, or fixtures outside the project. Use `npx job-forge redact:scan --input <file>`, `redact:apply --input <file> --output .jobforge-redacted/<file>`, or `redact:verify --input <file>` instead of hand-redacting with prose. This complements H8; it does not make it acceptable to paste secrets into prompts.
   why: `iso-redact` is not an MCP and adds no prompt/tool-schema tokens; it gives deterministic safe-export checks whose findings do not print matched secret values
 
+- [D19] Treat `templates/score.json` as the source of truth for offer scoring weights, bands, and gates. After emitting a report score JSON that will drive PDF/application/batch decisions, run `npx job-forge score:check --input <file>`; for apply decisions run `npx job-forge score:gate --input <file> --gate apply`. Do not recalculate weighted totals or thresholds manually when the local helper can check them.
+  why: `iso-score` is not an MCP and adds no prompt/tool-schema tokens; it makes scoring math, recommendation bands, and threshold booleans executable local policy instead of repeated model prose
+
+- [D20] Treat `templates/timeline.json` as the source of truth for follow-up and next-action timing. For follow-up triage, run `npx job-forge timeline:due` before reading tracker files; use `npx job-forge timeline:check --fail-on overdue` when a workflow must fail only on stale actions. Use `timeline:build` when a durable `.jobforge-timeline.json` artifact is useful.
+  why: `iso-timeline` is not an MCP and adds no prompt/tool-schema tokens; it turns timing windows over tracker/pipeline sources into executable local policy instead of repeated date math in model context
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
-3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use materialized facts when a fact query can answer the question [D13b]. Use canonical identity keys for duplicate checks [D15]. Use migration checks for harness drift [D14]. Use redaction checks before exporting local artifacts [D18]. Decide inline vs delegated work [D1].
+3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use materialized facts when a fact query can answer the question [D13b]. Use canonical identity keys for duplicate checks [D15]. Use score checks/gates for scoring decisions [D19]. Use timeline due/check commands for follow-up timing [D20]. Use migration checks for harness drift [D14]. Use redaction checks before exporting local artifacts [D18]. Decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], canon/index/facts/ledger prefilter when useful [D8, D13, D13b, D15], dedupe [H2], location filter [D5], materialize candidate facts/gates and run preflight plan/check [D16], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D17].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].
-8. Apply score gate [D4].
+8. Apply score gate [D4, D19].
 9. Merge contract-validated TSV outcomes [H6, D9].
 10. Verify tracker and run postflight check before ending [H6, D17].
 

package/lib/jobforge-score.mjs

@@ -0,0 +1,212 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  compareScoreResults,
+  computeScore,
+  evaluateGate,
+  loadScoreConfig,
+  parseJson,
+  scoreResultId,
+  verifyScoreResult,
+} from '@razroo/iso-score';
+
+export const SCORE_CONFIG_FILE = 'templates/score.json';
+export const SCORE_PROFILE = 'jobforge';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeScoreConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_SCORE_CONFIG || join(projectDir, SCORE_CONFIG_FILE);
+}
+
+export function readJobForgeScoreConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeScoreConfigPath(projectDir);
+  return loadScoreConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function readJsonFile(path) {
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function normalizeJobForgeScoreInput(input) {
+  if (!isObject(input)) throw new Error('score input must be a JSON object');
+
+  if ('dimensions' in input) {
+    return {
+      ...input,
+      profile: stringOr(input.profile, SCORE_PROFILE),
+    };
+  }
+
+  if (!isObject(input.scores)) {
+    throw new Error('score input must contain either dimensions or JobForge scores');
+  }
+
+  const dimensions = {};
+  for (const [id, raw] of Object.entries(input.scores)) {
+    if (!isObject(raw)) throw new Error(`scores.${id} must be a JSON object`);
+    dimensions[id] = {
+      score: Number(raw.score),
+      note: stringOr(raw.rationale, stringOr(raw.note, '')),
+      evidence: Array.isArray(raw.evidence) ? raw.evidence.filter((item) => typeof item === 'string') : [],
+    };
+  }
+
+  return stripUndefined({
+    subject: [input.company, input.role].filter((value) => typeof value === 'string' && value.length > 0).join(' - ') || undefined,
+    profile: SCORE_PROFILE,
+    dimensions,
+    facts: stripUndefined({
+      report_num: jsonScalar(input.report_num),
+      company: jsonScalar(input.company),
+      role: jsonScalar(input.role),
+      archetype: jsonScalar(input.archetype),
+      url: jsonScalar(input.url),
+      date: jsonScalar(input.date),
+    }),
+    meta: stripUndefined({
+      sourceShape: 'jobforge-score-json',
+      expectedWeightedTotal: jsonScalar(input.weighted_total),
+      recommendation: jsonScalar(input.recommendation),
+      pdf_threshold_met: typeof input.pdf_threshold_met === 'boolean' ? input.pdf_threshold_met : undefined,
+      draft_answers_threshold_met: typeof input.draft_answers_threshold_met === 'boolean' ? input.draft_answers_threshold_met : undefined,
+    }),
+  });
+}
+
+export function computeJobForgeScore(input, options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeScoreConfig(projectDir);
+  const normalized = normalizeJobForgeScoreInput(input);
+  const result = computeScore(config, normalized, { profile: options.profile || normalized.profile || SCORE_PROFILE });
+  return withJobForgeIssues(result, normalized);
+}
+
+export function checkJobForgeScore(input, options = {}, projectDir = resolveProjectDir()) {
+  const result = computeJobForgeScore(input, options, projectDir);
+  const errors = result.issues.filter((issue) => issue.severity === 'error').length;
+  const warnings = result.issues.filter((issue) => issue.severity === 'warn').length;
+  return {
+    ok: errors === 0,
+    errors,
+    warnings,
+    result,
+    issues: result.issues,
+  };
+}
+
+export function evaluateJobForgeScoreGate(input, options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeScoreConfig(projectDir);
+  const normalized = normalizeJobForgeScoreInput(input);
+  const base = evaluateGate(config, normalized, {
+    profile: options.profile || normalized.profile || SCORE_PROFILE,
+    gate: options.gate,
+  });
+  const result = withJobForgeIssues(base.result, normalized);
+  const errors = result.issues.some((issue) => issue.severity === 'error');
+  const gate = errors
+    ? { ...base.gate, pass: false, reason: `${base.gate.reason}; score has error issues` }
+    : base.gate;
+  return {
+    ok: gate.pass,
+    gate,
+    result,
+  };
+}
+
+export function verifyJobForgeScoreResult(result) {
+  return verifyScoreResult(result);
+}
+
+export function compareJobForgeScores(leftInput, rightInput, options = {}, projectDir = resolveProjectDir()) {
+  const left = computeJobForgeScore(leftInput, options, projectDir);
+  const right = computeJobForgeScore(rightInput, options, projectDir);
+  return compareScoreResults(left, right);
+}
+
+function withJobForgeIssues(result, normalized) {
+  const issues = [...result.issues, ...jobForgeShapeIssues(result, normalized)];
+  if (issues.length === result.issues.length) return result;
+  const updated = { ...result, issues };
+  updated.id = scoreResultId(updated);
+  return updated;
+}
+
+function jobForgeShapeIssues(result, normalized) {
+  if (normalized.meta?.sourceShape !== 'jobforge-score-json') return [];
+
+  const issues = [];
+  const expectedTotal = normalized.meta.expectedWeightedTotal;
+  if (typeof expectedTotal === 'number' && Math.abs(round1(expectedTotal) - result.score) > 0.0001) {
+    issues.push(error('weighted-total-mismatch', `weighted_total ${expectedTotal} does not match computed score ${result.score}`));
+  }
+
+  const expectedRecommendation = recommendationFor(result.score);
+  if (normalized.meta.recommendation !== undefined && normalized.meta.recommendation !== expectedRecommendation) {
+    issues.push(error('recommendation-mismatch', `recommendation must be "${expectedRecommendation}" for score ${result.score}`));
+  }
+
+  const expectedPdf = result.score >= 3;
+  if (normalized.meta.pdf_threshold_met !== undefined && normalized.meta.pdf_threshold_met !== expectedPdf) {
+    issues.push(error('pdf-threshold-mismatch', `pdf_threshold_met must be ${expectedPdf} for score ${result.score}`));
+  }
+
+  const expectedDraft = result.score >= 3.5;
+  if (normalized.meta.draft_answers_threshold_met !== undefined && normalized.meta.draft_answers_threshold_met !== expectedDraft) {
+    issues.push(error('draft-answers-threshold-mismatch', `draft_answers_threshold_met must be ${expectedDraft} for score ${result.score}`));
+  }
+
+  for (const dimension of result.dimensions) {
+    if (!isHalfStep(dimension.score)) {
+      issues.push(error('invalid-score-step', `dimension "${dimension.id}" score must use 0.5 increments`, dimension.id));
+    }
+    if (!dimension.note || dimension.note.trim().length === 0) {
+      issues.push(error('missing-rationale', `dimension "${dimension.id}" rationale is required`, dimension.id));
+    } else if (dimension.note.length > 80) {
+      issues.push(error('rationale-too-long', `dimension "${dimension.id}" rationale must be <= 80 characters`, dimension.id));
+    } else if (hasMarkdown(dimension.note)) {
+      issues.push(error('rationale-markdown', `dimension "${dimension.id}" rationale must not contain markdown`, dimension.id));
+    }
+  }
+
+  return issues;
+}
+
+function recommendationFor(score) {
+  if (score >= 3.5) return 'apply';
+  if (score >= 3) return 'apply_with_caveats';
+  return 'skip';
+}
+
+function isHalfStep(value) {
+  return Number.isFinite(value) && Number.isInteger(value * 2);
+}
+
+function hasMarkdown(value) {
+  return /(`|\*\*|__|\[[^\]]+\]\(|^#{1,6}\s)/.test(value);
+}
+
+function error(code, message, dimension) {
+  return stripUndefined({ severity: 'error', code, message, dimension });
+}
+
+function stringOr(value, fallback) {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function jsonScalar(value) {
+  return value === null || ['string', 'number', 'boolean'].includes(typeof value) ? value : undefined;
+}
+
+function round1(value) {
+  return Math.round(Number(value) * 10) / 10;
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}

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/_shared.md

@@ -147,7 +147,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 
 ## Use this canonical scoring model (SINGLE SOURCE OF TRUTH)
 
-**ALL evaluation modes MUST use this exact model.** Whether the offer is evaluated via `offer`, `auto-pipeline`, `batch`, or compared via `compare`, the score is computed the same way. This ensures scores are comparable across the entire pipeline.
+**ALL evaluation modes MUST use this exact model.** Whether the offer is evaluated via `offer`, `auto-pipeline`, `batch`, or compared via `compare`, the score is computed the same way. The executable source of truth is `templates/score.json`; use `npx job-forge score:check --input <score.json>` and `score:gate --gate apply` when validating emitted score JSON instead of recalculating gates in prose. This ensures scores are comparable across the entire pipeline.
 
 | # | Dimension | Weight | 1 | 3 | 5 |
 |---|-----------|--------|---|---|---|
@@ -209,8 +209,9 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 **After emitting the JSON:**
 
 1. Embed the same JSON block verbatim in the report `.md` under a `## Score` section (fenced as ` ```json `).
-2. Write Blocks A-F **referencing** the scores by key (e.g., "Seniority fit: 3/5 — Senior IC, no formal management"). Do NOT re-list all 10 dimensions in prose. Do NOT repeat the rationales verbatim.
-3. Do NOT narrate the scoring process in thinking before emitting the JSON. Decide, emit, move on.
+2. Save/check the emitted block when it will drive a PDF, application gate, comparison, or batch dispatch: `npx job-forge score:check --input <score.json>` and, for apply decisions, `npx job-forge score:gate --input <score.json> --gate apply`.
+3. Write Blocks A-F **referencing** the scores by key (e.g., "Seniority fit: 3/5 — Senior IC, no formal management"). Do NOT re-list all 10 dimensions in prose. Do NOT repeat the rationales verbatim.
+4. Do NOT narrate the scoring process in thinking before emitting the JSON. Decide, emit, move on.
 
 **Score interpretation (use consistently everywhere):**
 - **4.5-5.0** — Strong match. Generate PDF + draft answers. Apply promptly.

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}