job-forge 2.14.32 → 2.14.34

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`, `.jobforge-prioritize.json`, `.jobforge-lineage.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, 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 ...`.
+- [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 ...`, materialized fact records returned by `npx job-forge facts:query ...`, selected next actions returned by `npx job-forge prioritize:select ...`, and lineage records returned by `npx job-forge lineage:explain ...`.
   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.
@@ -93,11 +93,20 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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
+
+- [D21] Treat `templates/prioritize.json` as the source of truth for choosing between evaluated applications, candidate facts, and due follow-ups. When the user asks what to do next or when a batch needs replacement candidates, run `npx job-forge prioritize:build` or `npx job-forge prioritize:select --limit N` instead of ranking items in prose.
+  why: `iso-prioritize` is not an MCP and adds no prompt/tool-schema tokens; it converts facts and timeline records into a deterministic ranked queue so agents do not reread broad tracker/report trees or invent priorities
+
+- [D22] Treat `.jobforge-lineage.json` as the source of truth for whether generated reports/PDFs are current. After creating or refreshing a derived report/PDF, record its inputs with `npx job-forge lineage:record --artifact <file> --input <source>...`; before reusing an old artifact after source changes, run `npx job-forge lineage:check --artifact <file>` or `npx job-forge lineage:check`.
+  why: `iso-lineage` is not an MCP and adds no prompt/tool-schema tokens; it detects stale outputs by hashing local files instead of asking agents to remember which CV/profile/report version produced an artifact
+
 ## 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 score checks/gates for scoring decisions [D19]. 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 priority queues when choosing next actions or replacements [D21]. Use lineage checks before reusing generated artifacts [D22]. 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].

package/lib/jobforge-lineage.mjs

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'path';
+import {
+  checkLineage,
+  emptyLineageGraph,
+  loadLineageGraph,
+  parseJson,
+  recordLineage,
+  verifyLineageGraph,
+} from '@razroo/iso-lineage';
+
+export const LINEAGE_FILE = '.jobforge-lineage.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeLineagePath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_LINEAGE || join(projectDir, LINEAGE_FILE);
+}
+
+export function lineageExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeLineagePath(projectDir));
+}
+
+export function readJobForgeLineage(projectDir = resolveProjectDir()) {
+  const path = jobForgeLineagePath(projectDir);
+  return loadLineageGraph(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function readJobForgeLineageOrEmpty(projectDir = resolveProjectDir()) {
+  return lineageExists(projectDir) ? readJobForgeLineage(projectDir) : emptyLineageGraph();
+}
+
+export function writeJobForgeLineage(graph, options = {}, projectDir = resolveProjectDir()) {
+  const out = options.out || jobForgeLineagePath(projectDir);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(graph, null, 2)}\n`, 'utf8');
+  return out;
+}
+
+export function recordJobForgeLineage(options = {}, projectDir = resolveProjectDir()) {
+  const graph = options.graph || readJobForgeLineageOrEmpty(projectDir);
+  const updated = recordLineage(graph, {
+    root: projectDir,
+    artifact: required(options.artifact, '--artifact'),
+    inputs: options.inputs || [],
+    optionalInputs: options.optionalInputs || [],
+    ...(options.kind ? { kind: options.kind } : {}),
+    ...(options.command ? { command: options.command } : {}),
+    ...(options.now ? { now: options.now } : {}),
+    ...(options.metadata ? { metadata: options.metadata } : {}),
+  });
+  const out = writeJobForgeLineage(updated, { out: options.out }, projectDir);
+  const artifact = storedPath(projectDir, options.artifact);
+  const record = updated.records.find((item) => item.artifact.path === artifact);
+  if (!record) throw new Error(`${artifact} was not recorded`);
+  return { graph: updated, record, out };
+}
+
+export function checkJobForgeLineage(options = {}, projectDir = resolveProjectDir()) {
+  const graph = options.graph || readJobForgeLineage(projectDir);
+  return checkLineage(graph, {
+    root: projectDir,
+    ...(options.artifact ? { artifact: options.artifact } : {}),
+  });
+}
+
+export function staleJobForgeLineage(options = {}, projectDir = resolveProjectDir()) {
+  return checkJobForgeLineage(options, projectDir);
+}
+
+export function verifyJobForgeLineage(options = {}, projectDir = resolveProjectDir()) {
+  const graph = options.graph || readJobForgeLineage(projectDir);
+  return verifyLineageGraph(graph);
+}
+
+export function jobForgeLineageSummary(projectDir = resolveProjectDir()) {
+  if (!lineageExists(projectDir)) {
+    return {
+      path: jobForgeLineagePath(projectDir),
+      exists: false,
+      records: 0,
+      current: 0,
+      stale: 0,
+      missing: 0,
+    };
+  }
+  const graph = readJobForgeLineage(projectDir);
+  const result = checkJobForgeLineage({ graph }, projectDir);
+  return {
+    path: jobForgeLineagePath(projectDir),
+    exists: true,
+    id: graph.id,
+    records: graph.records.length,
+    current: result.current,
+    stale: result.stale,
+    missing: result.missing,
+    ok: result.ok,
+  };
+}
+
+export function normalizeJobForgeLineageArtifact(projectDir = resolveProjectDir(), artifact = '') {
+  return storedPath(projectDir, artifact);
+}
+
+function required(value, flag) {
+  if (!value) throw new Error(`lineage:record requires ${flag}`);
+  return value;
+}
+
+function storedPath(root, path) {
+  const absRoot = resolve(root);
+  const abs = resolve(absRoot, path);
+  const rel = relative(absRoot, abs);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return normalizePath(rel);
+  return normalizePath(abs);
+}
+
+function normalizePath(path) {
+  return path.split(sep).join('/');
+}

package/lib/jobforge-prioritize.mjs

@@ -0,0 +1,294 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import {
+  checkPrioritize,
+  loadPrioritizeConfig,
+  parseJson,
+  prioritize,
+  selectPrioritized,
+  verifyPrioritizeResult,
+} from '@razroo/iso-prioritize';
+import { ensureJobForgeFacts } from './jobforge-facts.mjs';
+import { dueJobForgeTimeline } from './jobforge-timeline.mjs';
+
+export const PRIORITIZE_CONFIG_FILE = 'templates/prioritize.json';
+export const PRIORITIZE_FILE = '.jobforge-prioritize.json';
+export const PRIORITIZE_ITEMS_FILE = '.jobforge-prioritize-items.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgePrioritizeConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_PRIORITIZE_CONFIG || join(projectDir, PRIORITIZE_CONFIG_FILE);
+}
+
+export function jobForgePrioritizePath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_PRIORITIZE || join(projectDir, PRIORITIZE_FILE);
+}
+
+export function jobForgePrioritizeItemsPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_PRIORITIZE_ITEMS || join(projectDir, PRIORITIZE_ITEMS_FILE);
+}
+
+export function prioritizeExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgePrioritizePath(projectDir));
+}
+
+export function readJobForgePrioritizeConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgePrioritizeConfigPath(projectDir);
+  return loadPrioritizeConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function readJobForgePrioritize(projectDir = resolveProjectDir()) {
+  const path = jobForgePrioritizePath(projectDir);
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function readJobForgePrioritizeItems(projectDir = resolveProjectDir()) {
+  const path = jobForgePrioritizeItemsPath(projectDir);
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function buildJobForgePrioritizeItems(options = {}, projectDir = resolveProjectDir()) {
+  const factSet = options.facts || ensureJobForgeFacts({ rebuild: options.rebuild !== false }, projectDir);
+  const items = [];
+
+  for (const fact of factSet.facts || []) {
+    const candidate = candidateItem(fact);
+    if (candidate) items.push(candidate);
+
+    const evaluated = evaluatedTrackerItem(fact);
+    if (evaluated) items.push(evaluated);
+  }
+
+  for (const item of dueJobForgeTimeline({ now: options.now }, projectDir).items || []) {
+    const followup = timelineItem(item);
+    if (followup) items.push(followup);
+  }
+
+  return { items: dedupeItems(items) };
+}
+
+export function rankJobForgePrioritize(options = {}, projectDir = resolveProjectDir()) {
+  const config = options.config || readJobForgePrioritizeConfig(projectDir);
+  const items = options.items || buildJobForgePrioritizeItems(options, projectDir);
+  return prioritize(config, items, { profile: options.profile, limit: options.limit });
+}
+
+export function selectJobForgePrioritize(options = {}, projectDir = resolveProjectDir()) {
+  return selectPrioritized(rankJobForgePrioritize(options, projectDir));
+}
+
+export function checkJobForgePrioritize(options = {}, projectDir = resolveProjectDir()) {
+  const config = options.config || readJobForgePrioritizeConfig(projectDir);
+  const items = options.items || buildJobForgePrioritizeItems(options, projectDir);
+  return checkPrioritize(config, items, {
+    profile: options.profile,
+    limit: options.limit,
+    minSelected: options.minSelected,
+    failOn: options.failOn,
+  });
+}
+
+export function writeJobForgePrioritize(result, options = {}, projectDir = resolveProjectDir()) {
+  const out = options.out || jobForgePrioritizePath(projectDir);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  return out;
+}
+
+export function writeJobForgePrioritizeItems(items, options = {}, projectDir = resolveProjectDir()) {
+  const out = options.out || jobForgePrioritizeItemsPath(projectDir);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(items, null, 2)}\n`, 'utf8');
+  return out;
+}
+
+export function verifyJobForgePrioritize(options = {}, projectDir = resolveProjectDir()) {
+  const result = options.result || readJobForgePrioritize(projectDir);
+  return verifyPrioritizeResult(result);
+}
+
+export function jobForgePrioritizeSummary(projectDir = resolveProjectDir()) {
+  if (!prioritizeExists(projectDir)) {
+    return {
+      path: jobForgePrioritizePath(projectDir),
+      itemsPath: jobForgePrioritizeItemsPath(projectDir),
+      config: jobForgePrioritizeConfigPath(projectDir),
+      exists: false,
+      items: 0,
+      selected: 0,
+      candidate: 0,
+      skipped: 0,
+      blocked: 0,
+    };
+  }
+
+  const result = readJobForgePrioritize(projectDir);
+  return {
+    path: jobForgePrioritizePath(projectDir),
+    itemsPath: jobForgePrioritizeItemsPath(projectDir),
+    config: jobForgePrioritizeConfigPath(projectDir),
+    exists: true,
+    items: result.stats?.total || 0,
+    selected: result.stats?.selected || 0,
+    candidate: result.stats?.candidate || 0,
+    skipped: result.stats?.skipped || 0,
+    blocked: result.stats?.blocked || 0,
+    id: result.id,
+    profile: result.profile,
+  };
+}
+
+function candidateItem(fact) {
+  if (fact.fact !== 'candidate.ready') return null;
+  const fields = fact.fields || {};
+  const company = stringField(fields.company);
+  const role = stringField(fields.role);
+  const score = parseScore(fields.score);
+
+  return compactItem({
+    id: `candidate-${slug(fields.id || fact.key || fact.id)}`,
+    key: fact.key,
+    type: 'apply',
+    title: title(company, role, 'apply'),
+    tags: ['apply', 'candidate'],
+    data: compactObject({
+      company,
+      role,
+      score,
+      urgency: score >= 4 ? 8 : 6,
+      ageDays: 0,
+      sourceQuality: sourceQuality(fact, score),
+      status: fields.gateStatus || 'Evaluated',
+      gateStatus: fields.gateStatus,
+      locationStatus: fields.locationStatus,
+      url: fields.url,
+    }),
+    source: fact.source,
+  });
+}
+
+function evaluatedTrackerItem(fact) {
+  if (fact.fact !== 'application.status') return null;
+  const fields = fact.fields || {};
+  const status = stringField(fields.status || fact.value);
+  if (status !== 'Evaluated') return null;
+  const company = stringField(fields.company);
+  const role = stringField(fields.role);
+  const score = parseScore(fields.score);
+
+  return compactItem({
+    id: `evaluated-${slug(fields.num || fact.key || fact.id)}`,
+    key: fact.key,
+    type: 'apply',
+    title: title(company, role, 'apply'),
+    tags: ['apply', 'tracker'],
+    data: compactObject({
+      company,
+      role,
+      score,
+      urgency: score >= 4 ? 8 : 5,
+      ageDays: ageDays(fields.date),
+      sourceQuality: sourceQuality(fact, score),
+      status,
+      report: fields.report,
+      pdf: fields.pdf,
+    }),
+    source: fact.source,
+  });
+}
+
+function timelineItem(item) {
+  const data = item.event?.data || {};
+  const company = stringField(data.company);
+  const role = stringField(data.role);
+  const score = parseScore(data.score);
+
+  return compactItem({
+    id: `timeline-${slug(item.id)}`,
+    key: item.key,
+    type: 'followup',
+    title: title(company, role, item.action || 'follow-up'),
+    tags: ['followup', item.state],
+    data: compactObject({
+      company,
+      role,
+      score,
+      urgency: item.state === 'overdue' ? 10 : 8,
+      ageDays: ageDays(item.event?.at),
+      sourceQuality: sourceQuality(item.event, score),
+      status: data.status,
+      timelineState: item.state,
+      action: item.action,
+      rule: item.rule,
+    }),
+    source: item.event?.source,
+  });
+}
+
+function dedupeItems(items) {
+  const byId = new Map();
+  for (const item of items) {
+    const existing = byId.get(item.id);
+    if (!existing || priorityValue(item) > priorityValue(existing)) byId.set(item.id, item);
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function priorityValue(item) {
+  return Number(item.data?.score || 0) * 100 +
+    Number(item.data?.urgency || 0) * 10 +
+    Number(item.data?.sourceQuality || 0);
+}
+
+function parseScore(value) {
+  const match = String(value || '').match(/([0-9]+(?:\.[0-9]+)?)(?:\s*\/\s*5)?/);
+  if (!match) return 0;
+  return Math.max(0, Math.min(5, Number(match[1])));
+}
+
+function ageDays(value) {
+  const text = String(value || '').trim();
+  if (!text) return 0;
+  const parsed = new Date(text);
+  if (Number.isNaN(parsed.getTime())) return 0;
+  return Math.max(0, Math.floor((Date.now() - parsed.getTime()) / 86400000));
+}
+
+function sourceQuality(sourceLike, score) {
+  if (sourceLike?.source?.path && score > 0) return 1;
+  return score > 0 ? 0.8 : 0;
+}
+
+function stringField(value) {
+  return value === undefined || value === null ? '' : String(value);
+}
+
+function title(company, role, suffix) {
+  const base = [company, role].filter(Boolean).join(' - ');
+  return suffix && base ? `${base} ${suffix}` : base || suffix || 'JobForge item';
+}
+
+function slug(value) {
+  return String(value || 'item')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'item';
+}
+
+function compactItem(item) {
+  return {
+    ...item,
+    tags: (item.tags || []).filter(Boolean),
+    ...(item.source ? { source: item.source } : {}),
+  };
+}
+
+function compactObject(input) {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => value !== undefined && value !== null && value !== ''),
+  );
+}