job-forge 2.14.15 → 2.14.17

package/lib/jobforge-ledger.mjs

@@ -0,0 +1,214 @@
+import { existsSync } from 'fs';
+import { isAbsolute, join, relative } from 'path';
+import {
+  appendEvent,
+  hasEvent,
+  materializeLedger,
+  queryEvents,
+  readLedger,
+  verifyLedger,
+} from '@razroo/iso-ledger';
+
+export const LEDGER_DIR = '.jobforge-ledger';
+export const LEDGER_FILE = 'events.jsonl';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeLedgerPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_LEDGER || join(projectDir, LEDGER_DIR, LEDGER_FILE);
+}
+
+export function jobForgeLedgerOptions(projectDir = resolveProjectDir()) {
+  return { path: jobForgeLedgerPath(projectDir) };
+}
+
+export function ledgerExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeLedgerPath(projectDir));
+}
+
+export function readJobForgeLedger(projectDir = resolveProjectDir()) {
+  if (!ledgerExists(projectDir)) return [];
+  return readLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function verifyJobForgeLedger(projectDir = resolveProjectDir()) {
+  return verifyLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function queryJobForgeLedger(options = {}, projectDir = resolveProjectDir()) {
+  return queryEvents(readJobForgeLedger(projectDir), options);
+}
+
+export function hasJobForgeEvent(options = {}, projectDir = resolveProjectDir()) {
+  return hasEvent(readJobForgeLedger(projectDir), options);
+}
+
+export function jobForgeLedgerSummary(projectDir = resolveProjectDir()) {
+  const events = readJobForgeLedger(projectDir);
+  const materialized = materializeLedger(events);
+  return {
+    path: jobForgeLedgerPath(projectDir),
+    exists: ledgerExists(projectDir),
+    events: events.length,
+    entities: materialized.entityCount,
+    latest: events.at(-1) || null,
+  };
+}
+
+export function appendJobForgeEvent(input, projectDir = resolveProjectDir()) {
+  return appendEvent(jobForgeLedgerOptions(projectDir), input);
+}
+
+export function recordTrackerAdditionWritten(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  return appendJobForgeEvent(buildApplicationEvent('jobforge.tracker_addition.written', addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: 'tracker-addition-written',
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function recordTrackerMergeResult(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const outcome = options.outcome || 'processed';
+  return appendJobForgeEvent(buildApplicationEvent(`jobforge.tracker_merge.${outcome}`, addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: `tracker-merge-${outcome}`,
+    data: {
+      outcome,
+      duplicateNum: jsonValue(options.duplicateNum),
+      reason: jsonValue(options.reason),
+    },
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function buildApplicationEvent(type, app, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = companyRoleKey(app.company, app.role);
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : '';
+  const idempotencyParts = [
+    options.idempotencyPrefix || type,
+    sourceFile,
+    app.num,
+    app.date,
+    key,
+    app.status,
+    app.score,
+  ].filter((value) => value !== undefined && value !== null && String(value).length > 0);
+
+  return {
+    type,
+    key,
+    subject: applicationSubject(app.company, app.role),
+    idempotencyKey: idempotencyParts.join(':'),
+    data: compactObject({
+      num: numberOrString(app.num),
+      date: stringOrEmpty(app.date),
+      company: stringOrEmpty(app.company),
+      role: stringOrEmpty(app.role),
+      score: stringOrEmpty(app.score),
+      status: stringOrEmpty(app.status),
+      pdf: stringOrEmpty(app.pdf),
+      report: stringOrEmpty(app.report),
+      notes: stringOrEmpty(app.notes),
+      sourceFile,
+      ...compactObject(options.data || {}),
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function buildPipelineEvent(item, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = item.url ? urlKey(item.url) : `pipeline:${item.lineNumber || 'unknown'}`;
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : 'data/pipeline.md';
+  const state = item.checked ? 'processed' : 'pending';
+
+  return {
+    type: 'jobforge.pipeline.item',
+    key,
+    subject: key,
+    idempotencyKey: `pipeline:${state}:${item.url || item.lineNumber || item.line || 'unknown'}`,
+    data: compactObject({
+      state,
+      checked: Boolean(item.checked),
+      url: stringOrEmpty(item.url),
+      company: stringOrEmpty(item.company),
+      role: stringOrEmpty(item.role),
+      line: stringOrEmpty(item.line),
+      lineNumber: numberOrString(item.lineNumber),
+      sourceFile,
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function companyRoleKey(company, role) {
+  return `company-role:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function applicationSubject(company, role) {
+  return `application:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function urlKey(url) {
+  return `url:${String(url || '').trim()}`;
+}
+
+export function slugPart(value) {
+  const slug = String(value || 'unknown')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'unknown';
+}
+
+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, '/');
+}
+
+function compactObject(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj || {})) {
+    const clean = jsonValue(value);
+    if (clean !== undefined) out[key] = clean;
+  }
+  return out;
+}
+
+function jsonValue(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.map(jsonValue).filter((item) => item !== undefined);
+  if (typeof value === 'object') return compactObject(value);
+  return String(value);
+}
+
+function stringOrEmpty(value) {
+  if (value === undefined || value === null) return undefined;
+  const text = String(value);
+  return text.length > 0 ? text : undefined;
+}
+
+function numberOrString(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && String(value).trim() !== '' ? number : String(value);
+}

package/merge-tracker.mjs

@@ -29,6 +29,8 @@ import {
 import {
   DEFAULT_STATES, loadCanonicalStates, buildStatusDetectionRegex,
 } from './lib/canonical-states.mjs';
+import { recordTrackerMergeResult } from './lib/jobforge-ledger.mjs';
+import { formatContractIssues, parseTrackerRow } from './lib/jobforge-contracts.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const MERGED_DIR = join(ADDITIONS_DIR, 'merged');
@@ -155,64 +157,22 @@ function parseTsvContent(content, filename) {
   content = content.trim();
   if (!content) return null;
 
-  let parts;
-  let addition;
+  const format = detectTrackerRowFormat(content);
+  const parsed = parseTrackerRow(content, format, {
+    projectDir: PROJECT_DIR,
+    normalizeStatus: validateStatus,
+  });
 
-  if (content.startsWith('|')) {
-    parts = content.split('|').map(s => s.trim()).filter(Boolean);
-    if (parts.length < 8) {
-      console.warn(`⚠️  Skipping malformed pipe-delimited ${filename}: ${parts.length} fields`);
-      return null;
-    }
-    addition = {
-      num: parseInt(parts[0]),
-      date: parts[1],
-      company: parts[2],
-      role: parts[3],
-      score: parts[4],
-      status: validateStatus(parts[5]),
-      pdf: parts[6],
-      report: parts[7],
-      notes: parts[8] || '',
-    };
-  } else {
-    parts = content.split('\t');
-    if (parts.length < 8) {
-      console.warn(`⚠️  Skipping malformed TSV ${filename}: ${parts.length} fields`);
-      return null;
-    }
-
-    const col4 = parts[4].trim();
-    const col5 = parts[5].trim();
-    const col4LooksLikeScore = /^\d+\.?\d*\/5$/.test(col4) || col4 === 'N/A' || col4 === 'DUP';
-    const col5LooksLikeScore = /^\d+\.?\d*\/5$/.test(col5) || col5 === 'N/A' || col5 === 'DUP';
-    const col4LooksLikeStatus = STATUS_DETECT_RE.test(col4);
-    const col5LooksLikeStatus = STATUS_DETECT_RE.test(col5);
-
-    let statusCol, scoreCol;
-    if (col4LooksLikeStatus && !col4LooksLikeScore) {
-      statusCol = col4; scoreCol = col5;
-    } else if (col4LooksLikeScore && col5LooksLikeStatus) {
-      statusCol = col5; scoreCol = col4;
-    } else if (col5LooksLikeScore && !col4LooksLikeScore) {
-      statusCol = col4; scoreCol = col5;
-    } else {
-      statusCol = col4; scoreCol = col5;
-    }
-
-    addition = {
-      num: parseInt(parts[0]),
-      date: parts[1],
-      company: parts[2],
-      role: parts[3],
-      status: validateStatus(statusCol),
-      score: scoreCol,
-      pdf: parts[6],
-      report: parts[7],
-      notes: parts[8] || '',
-    };
+  if (!parsed.validation.ok) {
+    console.warn(`⚠️  Skipping ${filename}: tracker contract failed (${format}) — ${formatContractIssues(parsed.validation)}`);
+    return null;
   }
 
+  const addition = {
+    ...parsed.validation.record,
+    num: Number(parsed.validation.record.num),
+  };
+
   if (isNaN(addition.num) || addition.num === 0) {
     console.warn(`⚠️  Skipping ${filename}: invalid entry number`);
     return null;
@@ -221,6 +181,18 @@ function parseTsvContent(content, filename) {
   return addition;
 }
 
+function detectTrackerRowFormat(content) {
+  if (content.startsWith('|')) return 'markdown';
+
+  const parts = content.split('\t');
+  const col4 = (parts[4] || '').trim();
+  const col5 = (parts[5] || '').trim();
+  const col4LooksLikeScore = /^\d+\.?\d*\/5$/.test(col4) || col4 === 'N/A' || col4 === 'DUP';
+  const col5LooksLikeStatus = STATUS_DETECT_RE.test(col5);
+
+  return col4LooksLikeScore && col5LooksLikeStatus ? 'day-tsv' : 'tsv';
+}
+
 // ---- Main ----
 
 if (!existsSync(ADDITIONS_DIR)) {
@@ -288,6 +260,7 @@ let added = 0;
 let updated = 0;
 let skipped = 0;
 const newEntries = [];
+const ledgerRecords = [];
 
 for (const file of tsvFiles) {
   const content = readFileSync(join(ADDITIONS_DIR, file), 'utf-8').trim();
@@ -359,12 +332,15 @@ for (const file of tsvFiles) {
         }
       }
       updated++;
+      ledgerRecords.push({ addition, outcome: 'updated', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason });
     } else if (statusRegresses) {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} status ${duplicate.status} outranks new ${addition.status})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'status-regression' });
     } else {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} ${oldScore} >= new ${newScore})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'no-improvement' });
     }
   } else {
     const entryNum = addition.num > maxNum ? addition.num : ++maxNum;
@@ -376,6 +352,7 @@ for (const file of tsvFiles) {
     });
     added++;
     console.log(`➕ Add #${entryNum}: ${addition.company} — ${addition.role} (${addition.score})`);
+    ledgerRecords.push({ addition: { ...addition, num: entryNum }, outcome: 'added', sourceFile: join(ADDITIONS_DIR, file), reason: 'new-entry' });
   }
 }
 
@@ -410,6 +387,23 @@ if (!DRY_RUN) {
     renameSync(join(ADDITIONS_DIR, file), join(MERGED_DIR, file));
   }
   console.log(`\n✅ Moved ${tsvFiles.length} TSVs to merged/`);
+
+  let ledgerEvents = 0;
+  for (const record of ledgerRecords) {
+    try {
+      const result = recordTrackerMergeResult(record.addition, {
+        projectDir: PROJECT_DIR,
+        sourceFile: record.sourceFile,
+        outcome: record.outcome,
+        duplicateNum: record.duplicateNum,
+        reason: record.reason,
+      });
+      if (result.appended) ledgerEvents++;
+    } catch (error) {
+      console.warn(`⚠️  Could not append ledger event for ${record.sourceFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.log(`🧾 Ledger: ${ledgerEvents} event(s) appended`);
 }
 
 console.log(`\n📊 Summary: +${added} added, 🔄${updated} updated, ⏭️${skipped} skipped`);

package/modes/reference-setup.md

@@ -112,6 +112,18 @@ Mode routing is specified in the top-level **## Routing** section. Each mode is
 
 ## TSV Format for Tracker Additions
 
+Prefer the deterministic helper:
+
+```bash
+npx job-forge tracker-line --num 521 --date 2026-04-15 --company "Anthropic" --role "Manager, FDE" --status Evaluated --score 4.2 --pdf no --slug anthropic-manager-fde --notes "Strong fit" --write
+```
+
+The helper renders and validates the row against `templates/contracts.json` via `@razroo/iso-contract`. To inspect the contract directly:
+
+```bash
+npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
+```
+
 Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slug}.tsv`. Single line, 9 tab-separated columns:
 
 ```
@@ -129,7 +141,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 8. `report` -- markdown link `[num](reports/...)`
 9. `notes` -- one-line summary
 
-**Note:** In applications.md, score comes BEFORE status. The merge script handles this column swap automatically.
+**Note:** In applications.md, score comes BEFORE status. The merge script handles this column swap automatically and validates both shapes with the tracker-row contract.
 
 - Scripts in `.mjs`, configuration in YAML
 - Output in `output/` (gitignored), Reports in `reports/`
@@ -146,9 +158,10 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 2. **YES you can edit day files in `data/applications/` to UPDATE status/notes of existing entries.**
 3. All reports MUST include `**URL:**` in the header (between Score and PDF).
 4. All statuses MUST be canonical (see `templates/states.yml`).
-5. Health check: `npx job-forge verify`
-6. Normalize statuses: `npx job-forge normalize`
-7. Dedup: `npx job-forge dedup`
+5. Tracker rows MUST satisfy `templates/contracts.json`.
+6. Health check: `npx job-forge verify`
+7. Normalize statuses: `npx job-forge normalize`
+8. Dedup: `npx job-forge dedup`
 
 ### Canonical States (applications day files)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.15",
+  "version": "2.14.17",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -27,6 +27,11 @@
     "telemetry:watch": "node bin/job-forge.mjs telemetry:watch",
     "guard:audit": "node bin/job-forge.mjs guard:audit",
     "guard:explain": "node bin/job-forge.mjs guard:explain",
+    "ledger:status": "node bin/job-forge.mjs ledger:status",
+    "ledger:rebuild": "node bin/job-forge.mjs ledger:rebuild",
+    "ledger:verify": "node bin/job-forge.mjs ledger:verify",
+    "ledger:has": "node bin/job-forge.mjs ledger:has",
+    "ledger:query": "node bin/job-forge.mjs ledger:query",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -91,7 +96,9 @@
     "node": ">=20.6.0"
   },
   "dependencies": {
+    "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",
+    "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"