job-forge 2.14.16 → 2.14.18

package/.cursor/rules/main.mdc

@@ -62,6 +62,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
   why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
 
+- [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
+  why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
@@ -72,7 +75,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 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].
-9. Merge TSV outcomes [H6].
+9. Merge contract-validated TSV outcomes [H6, D9].
 10. Verify tracker before ending [H6].
 
 ## Routing

package/.opencode/skills/job-forge.md

@@ -72,6 +72,10 @@ Token usage check (terminal, outside opencode):
 Local workflow ledger (terminal, outside opencode):
   npx job-forge ledger:status          # .jobforge-ledger/events.jsonl summary
   npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
+
+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
 ```
 
 ---

package/AGENTS.md

@@ -57,6 +57,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
   why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
 
+- [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
+  why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
@@ -67,7 +70,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 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].
-9. Merge TSV outcomes [H6].
+9. Merge contract-validated TSV outcomes [H6, D9].
 10. Verify tracker before ending [H6].
 
 ## Routing

package/CLAUDE.md

@@ -57,6 +57,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
   why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
 
+- [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
+  why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
@@ -67,7 +70,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 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].
-9. Merge TSV outcomes [H6].
+9. Merge contract-validated TSV outcomes [H6, D9].
 10. Verify tracker before ending [H6].
 
 ## Routing

package/README.md

@@ -31,7 +31,7 @@ The scaffolded `opencode.json` already has three MCPs wired up — they launch a
 - **Gmail** — reads replies from recruiters
 - **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with `python3 -m pip install "state-trace[mcp]"`; the MCP command is `state-trace-mcp`.
 
-JobForge also keeps an MCP-free local workflow ledger at `.jobforge-ledger/events.jsonl` when you use `job-forge ledger:*`, `tracker-line --write`, or `merge`. This is deterministic state for duplicate/status checks; it does not add prompt or tool-schema tokens.
+JobForge also keeps MCP-free local workflow state: `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. Neither adds prompt or tool-schema tokens.
 
 `npm install` also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run `opencode`, `cursor`, `claude`, or `codex` in the same project and each picks up the shared MCP config and instructions.
 
@@ -78,7 +78,7 @@ JobForge turns opencode into a full job search command center. Instead of manual
 | **Durable Batch Orchestration** | `batch-runner.sh` uses `@razroo/iso-orchestrator` for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in `.jobforge-runs/`. |
 | **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
 | **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to `opencode-go/deepseek-v4-flash` so application runs avoid overloaded free-model pools. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
-| **Trace + Telemetry + Guard + Ledger** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, and `job-forge ledger:*` queries append-only workflow state without MCP/token overhead. |
+| **Trace + Telemetry + Guard + Contract + Ledger** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, and `job-forge ledger:*` queries append-only workflow state without MCP/token overhead. |
 | **Token Cost Visibility** | `job-forge tokens --days 1` for per-session breakdown; `job-forge session-report --since-minutes 60 --log` to flag sessions over budget and append history to `data/token-usage.tsv`. Auto-logged after every batch run. |
 
 ## Usage
@@ -193,6 +193,7 @@ JobForge/
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
 │   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
+│   ├── tracker-line.mjs          # iso-contract-backed tracker TSV renderer
 │   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish

package/bin/job-forge.mjs

@@ -120,7 +120,7 @@ Deterministic helpers (prefer these over LLM-derived values):
   next-num       Print next sequential report number (e.g. 521)
   slugify NAME   Convert a company/role name to a filename-safe slug
   today          Print today's date in YYYY-MM-DD
-  tracker-line   Emit a 9-col TSV row for batch/tracker-additions/
+  tracker-line   Render and validate a tracker TSV row for batch/tracker-additions/
 
 Cost visibility:
   session-report        Summarize recent session costs, warn on >budget sessions

package/docs/ARCHITECTURE.md

@@ -173,12 +173,12 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 
 - Reports: `{###}-{company-slug}-{YYYY-MM-DD}.md` (3-digit zero-padded)
 - PDFs: `cv-candidate-{company-slug}-{YYYY-MM-DD}.pdf`
-- Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`)
+- Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`; shape enforced by `templates/contracts.json`)
 - Ledger: `.jobforge-ledger/events.jsonl` (created by `job-forge ledger:rebuild`, `tracker-line --write`, or `merge`; gitignored personal state)
 
 ## Pipeline Integrity
 
-From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
+From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), validates every tracker row against `templates/contracts.json`, warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
 
 **`verify-pipeline.mjs` checks (same order as the script header):**
 
@@ -187,12 +187,13 @@ From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify
 3. Report column markdown links resolve to files under the repo root.
 4. Score column matches `X.X/5`, `N/A`, or `DUP`.
 5. Table data rows have enough pipe-delimited columns.
-6. No unmerged `batch/tracker-additions/*.tsv` files (warns if any remain).
-7. Score column has no markdown bold.
-8. Warn when state ids in `templates/states.yml` drift from the script’s built-in fallback list (or when the file exists but ids failed to parse).
-9. Validate `.jobforge-ledger/events.jsonl` when present.
+6. Tracker rows satisfy the `jobforge.tracker-row` contract in `templates/contracts.json`.
+7. No unmerged `batch/tracker-additions/*.tsv` files (warns if any remain).
+8. Score column has no markdown bold.
+9. Warn when state ids in `templates/states.yml` drift from the script’s built-in fallback list (or when the file exists but ids failed to parse).
+10. Validate `.jobforge-ledger/events.jsonl` when present.
 
-When the tracker file is missing, checks 1–5 and 7 are skipped; checks 6 and 8 still run.
+When the tracker file is missing, checks 1-6 and 8 are skipped; checks 7, 9, and 10 still run when applicable.
 
 ## Contributing touchpoints
 

package/docs/CUSTOMIZATION.md

@@ -138,6 +138,10 @@ npx job-forge ledger:verify
 
 `tracker-line --write` records tracker-addition events, `merge` records add/update/skip outcomes, and `ledger:rebuild` backfills events from `data/applications/`, `batch/tracker-additions/`, `batch/tracker-additions/merged/`, and `data/pipeline.md`.
 
+## JobForge artifact contracts
+
+Machine-readable artifact shapes live in `templates/contracts.json` and are enforced by `@razroo/iso-contract`. `job-forge tracker-line` renders tracker additions through the `jobforge.tracker-row` contract, `merge` validates pending TSV/table rows before writing tracker files, and `verify` validates existing tracker rows against the same contract. Custom forks can extend `templates/contracts.json`, but keep the tracker status enum aligned with `templates/states.yml`.
+
 ## JobForge guard audits
 
 Guard audits run deterministic `@razroo/iso-guard` policies over the same local OpenCode traces. The default policy lives at `templates/guards/jobforge-baseline.yaml` and checks rules that are reliable from transcript data, including max two task dispatches per assistant message, no task-status polling via `task`, no raw proxy configuration in task prompts, and no child session task recursion.

package/docs/SETUP.md

@@ -125,6 +125,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 |--------|---------|-----------|
 | Pipeline health check | `npx job-forge verify` | `npm run verify` |
 | Merge `batch/tracker-additions/*.tsv` into the tracker | `npx job-forge merge` | `npm run merge` |
+| Inspect tracker row contract | `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` | _(none)_ |
 | Map status column to canonical labels | `npx job-forge normalize` | `npm run normalize` |
 | Merge duplicate company/role rows | `npx job-forge dedup` | `npm run dedup` |
 | Generate ATS-optimized CV PDF | `npx job-forge pdf` | `npm run pdf` |

package/iso/commands/job-forge.md

@@ -75,6 +75,10 @@ Token usage check (terminal, outside opencode):
 Local workflow ledger (terminal, outside opencode):
   npx job-forge ledger:status          # .jobforge-ledger/events.jsonl summary
   npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
+
+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
 ```
 
 ---

package/iso/instructions.md

@@ -57,6 +57,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
   why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
 
+- [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
+  why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
@@ -67,7 +70,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 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].
-9. Merge TSV outcomes [H6].
+9. Merge contract-validated TSV outcomes [H6, D9].
 10. Verify tracker before ending [H6].
 
 ## Routing

package/lib/jobforge-contracts.mjs

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  contractNames,
+  explainContract,
+  formatIssue,
+  getContract,
+  loadContractCatalog,
+  parseRecord,
+  renderRecord,
+  validateRecord,
+} from '@razroo/iso-contract';
+import { DEFAULT_STATES, loadCanonicalStates } from './canonical-states.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+export const CONTRACTS_RELATIVE_PATH = 'templates/contracts.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeContractsPath(projectDir = resolveProjectDir()) {
+  const projectPath = join(projectDir, CONTRACTS_RELATIVE_PATH);
+  if (existsSync(projectPath)) return projectPath;
+  return join(PKG_ROOT, CONTRACTS_RELATIVE_PATH);
+}
+
+export function loadJobForgeContractCatalog(projectDir = resolveProjectDir()) {
+  const path = jobForgeContractsPath(projectDir);
+  const input = JSON.parse(readFileSync(path, 'utf-8'));
+  applyCanonicalStatusValues(input, projectDir);
+  return loadContractCatalog(input);
+}
+
+export function listJobForgeContracts(projectDir = resolveProjectDir()) {
+  return contractNames(loadJobForgeContractCatalog(projectDir));
+}
+
+export function getJobForgeContract(name, projectDir = resolveProjectDir()) {
+  return getContract(loadJobForgeContractCatalog(projectDir), name);
+}
+
+export function explainJobForgeContract(name, projectDir = resolveProjectDir()) {
+  return explainContract(getJobForgeContract(name, projectDir));
+}
+
+export function getTrackerRowContract(projectDir = resolveProjectDir()) {
+  return getJobForgeContract('jobforge.tracker-row', projectDir);
+}
+
+export function validateTrackerRow(record, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const normalized = normalizeTrackerRowRecord(record, options);
+  const contract = options.allowMissingReport
+    ? trackerRowContractWithOptionalReport(getTrackerRowContract(projectDir))
+    : getTrackerRowContract(projectDir);
+  return validateRecord(contract, normalized);
+}
+
+export function parseTrackerRow(text, formatName = 'tsv', options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const contract = getTrackerRowContract(projectDir);
+  const parsed = parseRecord(contract, text, formatName);
+  const normalized = normalizeTrackerRowRecord(parsed.record, options);
+  const validation = validateRecord(contract, normalized);
+  return { record: validation.record, validation, format: formatName };
+}
+
+export function renderTrackerRow(record, formatName = 'tsv', options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const normalized = normalizeTrackerRowRecord(record, options);
+  return renderRecord(getTrackerRowContract(projectDir), normalized, formatName);
+}
+
+export function formatContractIssues(result) {
+  return result.issues.map(formatIssue).join('; ');
+}
+
+export function canonicalStatusValues(projectDir = resolveProjectDir()) {
+  return loadCanonicalStates(projectDir) || loadCanonicalStates(PKG_ROOT) || DEFAULT_STATES;
+}
+
+function normalizeTrackerRowRecord(record, options = {}) {
+  const out = { ...record };
+  if (out.status !== undefined && options.normalizeStatus) {
+    out.status = options.normalizeStatus(String(out.status));
+  }
+  return out;
+}
+
+function trackerRowContractWithOptionalReport(contract) {
+  return {
+    ...contract,
+    fields: contract.fields.map((field) => (
+      field.name === 'report' ? { ...field, required: false } : field
+    )),
+  };
+}
+
+function applyCanonicalStatusValues(input, projectDir) {
+  const statuses = canonicalStatusValues(projectDir);
+  for (const contract of input.contracts || []) {
+    if (contract.name !== 'jobforge.tracker-row') continue;
+    const field = (contract.fields || []).find((item) => item.name === 'status');
+    if (field) field.values = statuses;
+  }
+}

package/merge-tracker.mjs

@@ -30,6 +30,7 @@ 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');
@@ -156,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;
@@ -222,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)) {

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.16",
+  "version": "2.14.18",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -96,6 +96,7 @@
     "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",

package/scripts/tracker-line.mjs

@@ -25,6 +25,7 @@
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { recordTrackerAdditionWritten } from '../lib/jobforge-ledger.mjs';
+import { formatContractIssues, renderTrackerRow } from '../lib/jobforge-contracts.mjs';
 
 const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
 
@@ -54,8 +55,15 @@ const write = process.argv.includes('--write');
 const paddedNum = String(num).padStart(3, '0');
 const reportLink = `[${num}](reports/${paddedNum}-${slug}-${date}.md)`;
 const scoreField = score.includes('/') ? score : `${score}/5`;
+const record = { num, date, company, role, status, score: scoreField, pdf, report: reportLink, notes };
+const rendered = renderTrackerRow(record, 'tsv', { projectDir: PROJECT_DIR });
 
-const line = [num, date, company, role, status, scoreField, pdf, reportLink, notes].join('\t');
+if (!rendered.validation.ok) {
+  console.error(`tracker-line contract failed: ${formatContractIssues(rendered.validation)}`);
+  process.exit(1);
+}
+
+const line = rendered.text;
 
 if (write) {
   const dir = join(PROJECT_DIR, 'batch/tracker-additions');
@@ -63,9 +71,7 @@ if (write) {
   const path = join(dir, `${num}.tsv`);
   writeFileSync(path, line + '\n', 'utf-8');
   try {
-    recordTrackerAdditionWritten({
-      num, date, company, role, status, score: scoreField, pdf, report: reportLink, notes,
-    }, { projectDir: PROJECT_DIR, sourceFile: path });
+    recordTrackerAdditionWritten(rendered.validation.record, { projectDir: PROJECT_DIR, sourceFile: path });
   } catch (error) {
     console.warn(`warning: could not append tracker-line ledger event: ${error instanceof Error ? error.message : String(error)}`);
   }

package/templates/contracts.json

@@ -0,0 +1,54 @@
+{
+  "contracts": [
+    {
+      "name": "jobforge.tracker-row",
+      "version": "1.0.0",
+      "description": "Canonical JobForge tracker row used by batch/tracker-additions and data/applications day files.",
+      "fields": [
+        { "name": "num", "type": "integer", "required": true, "min": 1 },
+        { "name": "date", "type": "date", "required": true },
+        { "name": "company", "type": "string", "required": true },
+        { "name": "role", "type": "string", "required": true },
+        {
+          "name": "status",
+          "type": "enum",
+          "required": true,
+          "values": ["Evaluated", "Applied", "Responded", "Contacted", "Interview", "Offer", "Rejected", "Discarded", "Failed", "SKIP"]
+        },
+        { "name": "score", "type": "score", "required": true },
+        { "name": "pdf", "type": "string", "required": true },
+        { "name": "report", "type": "markdown-link", "required": true },
+        { "name": "notes", "type": "string" }
+      ],
+      "formats": {
+        "tsv": {
+          "style": "delimited",
+          "delimiter": "tab",
+          "fields": ["num", "date", "company", "role", "status", "score", "pdf", "report", "notes"]
+        },
+        "day-tsv": {
+          "style": "delimited",
+          "delimiter": "tab",
+          "fields": ["num", "date", "company", "role", "score", "status", "pdf", "report", "notes"]
+        },
+        "markdown": {
+          "style": "markdown-table-row",
+          "fields": ["num", "date", "company", "role", "score", "status", "pdf", "report", "notes"]
+        }
+      }
+    },
+    {
+      "name": "jobforge.apply-outcome",
+      "version": "1.0.0",
+      "description": "Structured final outcome emitted by an application subagent.",
+      "fields": [
+        { "name": "status", "type": "enum", "required": true, "values": ["APPLIED", "APPLY FAILED", "SKIP", "Discarded"] },
+        { "name": "company", "type": "string", "required": true },
+        { "name": "role", "type": "string", "required": true },
+        { "name": "url", "type": "url", "required": true },
+        { "name": "trackerTsv", "type": "string" },
+        { "name": "reason", "type": "string" }
+      ]
+    }
+  ]
+}

package/verify-pipeline.mjs

@@ -12,10 +12,11 @@
  * 3. All report links point to existing files
  * 4. Scores match format X.XX/5 or N/A or DUP
  * 5. All rows have proper pipe-delimited format
- * 6. No pending TSVs in tracker-additions/ (runs even when tracker file is missing)
- * 7. No markdown bold in score column
- * 8. Drift warning if states.yml ids differ from the built-in fallback list
- * 9. Ledger file verifies if .jobforge-ledger/events.jsonl exists
+ * 6. Tracker rows match templates/contracts.json
+ * 7. No pending TSVs in tracker-additions/ (runs even when tracker file is missing)
+ * 8. No markdown bold in score column
+ * 9. Drift warning if states.yml ids differ from the built-in fallback list
+ * 10. Ledger file verifies if .jobforge-ledger/events.jsonl exists
  *
  * Run: node verify-pipeline.mjs   (from repo root; same as npm run verify)
  */
@@ -28,6 +29,11 @@ import {
   usesDayFiles, readAllEntries, listDayFiles, dayFilePath,
 } from './tracker-lib.mjs';
 import { jobForgeLedgerPath, ledgerExists, verifyJobForgeLedger } from './lib/jobforge-ledger.mjs';
+import {
+  canonicalStatusValues,
+  formatContractIssues,
+  validateTrackerRow,
+} from './lib/jobforge-contracts.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const STATES_FILE = existsSync(join(PROJECT_DIR, 'templates/states.yml'))
@@ -42,7 +48,7 @@ const appsDisplay = usesDayFiles()
 
 const CANONICAL_STATUSES = [
   'evaluated', 'applied', 'contacted', 'responded', 'interview',
-  'offer', 'rejected', 'discarded', 'skip',
+  'offer', 'rejected', 'discarded', 'failed', 'skip',
 ];
 
 const ALIASES = {
@@ -78,6 +84,7 @@ function loadStatesFromYaml(filePath) {
 }
 
 const statesMeta = loadStatesFromYaml(STATES_FILE);
+const CONTRACT_STATUSES = canonicalStatusValues(PROJECT_DIR);
 
 function statusIsAllowed(statusOnlyLower) {
   if (statesMeta) {
@@ -167,6 +174,7 @@ console.log(`\n📊 Checking ${entries.length} entries from ${source === 'day' ?
 
 // --- Check 1: Canonical statuses ---
 let badStatuses = 0;
+// --- Check 6: Contract ---
 for (const e of entries) {
   const clean = e.status.replace(/\*\*/g, '').trim().toLowerCase();
   const statusOnly = clean.replace(/\s+\d{4}-\d{2}-\d{2}.*$/, '').trim();
@@ -231,6 +239,7 @@ if (badScores === 0) ok('All scores valid');
 
 // --- Check 5: Row format ---
 let badRows = 0;
+let contractFailures = 0;
 // Re-read raw lines for format check
 if (source === 'day') {
   for (const file of listDayFiles()) {
@@ -260,10 +269,23 @@ if (source === 'day') {
 }
 if (badRows === 0) ok('All rows properly formatted');
 
-// --- Check 6: Pending TSVs ---
+for (const e of entries) {
+  const result = validateTrackerRow(contractRecordForEntry(e), {
+    allowMissingReport: true,
+    projectDir: PROJECT_DIR,
+    normalizeStatus: normalizeStatusForContract,
+  });
+  if (!result.ok) {
+    error(`#${e.num}: Tracker row contract failed: ${formatContractIssues(result)}`);
+    contractFailures++;
+  }
+}
+if (contractFailures === 0) ok('All tracker rows match iso-contract');
+
+// --- Check 7: Pending TSVs ---
 checkPendingTrackerAdditions();
 
-// --- Check 7: Bold in scores ---
+// --- Check 8: Bold in scores ---
 let boldScores = 0;
 for (const e of entries) {
   if (e.score.includes('**')) {
@@ -286,3 +308,30 @@ if (errors === 0 && warnings === 0) {
   console.log('🔴 Pipeline has errors — fix before proceeding');
 }
 process.exit(errors > 0 ? 1 : 0);
+
+function normalizeStatusForContract(status) {
+  const clean = status.replace(/\*\*/g, '').replace(/\s+\d{4}-\d{2}-\d{2}.*$/, '').trim();
+  const lower = clean.toLowerCase();
+  const direct = CONTRACT_STATUSES.find((value) => value.toLowerCase() === lower);
+  if (direct) return direct;
+  if (ALIASES[lower] === 'applied') return 'Applied';
+  return clean;
+}
+
+function contractRecordForEntry(entry) {
+  const record = {
+    num: entry.num,
+    date: entry.date,
+    company: entry.company,
+    role: entry.role,
+    score: entry.score,
+    status: entry.status,
+    pdf: entry.pdf,
+    report: entry.report,
+    notes: entry.notes,
+  };
+  if (!/\]\([^)]+\)/.test(String(record.report || ''))) {
+    delete record.report;
+  }
+  return record;
+}