job-forge 2.14.30 → 2.14.32

package/iso/commands/job-forge.md

@@ -102,6 +102,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 +215,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`, 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`, 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 ...`, and source path/line pointers returned by `npx job-forge index: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.
@@ -72,6 +72,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D13] Use `job-forge index:*` for deterministic artifact lookup when available. `index:has` and `index:query` rebuild `.jobforge-index.json` from `templates/index.json` on demand, covering reports, tracker day files, tracker TSVs, pipeline URLs, scan history, and ledger events without loading those growing files into prompt context.
   why: `iso-index` is not an MCP and adds no prompt/tool-schema tokens; it gives agents compact file/line pointers and duplicate prefilters before expensive reads or browser dispatches
 
+- [D13b] Use `job-forge facts:*` for deterministic source-backed fact materialization when available. `facts:has` and `facts:query` rebuild `.jobforge-facts.json` from `templates/facts.json` on demand, covering job URLs, scores, application statuses, tracker TSVs, preflight candidates, scan history, and ledger events with path/line provenance.
+  why: `iso-facts` is not an MCP and adds no prompt/tool-schema tokens; it turns authoritative files into compact queryable fact records so agents do not repeatedly reread broad artifact trees
+
 - [D14] Treat `templates/migrations.json` as the source of truth for consumer-project upgrades. Use `npx job-forge migrate:plan` or `npx job-forge migrate:check` when diagnosing harness drift; `job-forge sync` applies safe migrations automatically unless `JOB_FORGE_SKIP_MIGRATIONS=1` is set.
   why: `iso-migrate` is not an MCP and adds no prompt/tool-schema tokens; it prevents stale consumer scripts and generated-artifact ignores without asking agents to hand-edit package.json
 
@@ -87,16 +90,19 @@ 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
+
 ## 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 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].
-4. Prepare Geometra dispatches: cleanup [H3], canon/index/ledger prefilter when useful [D8, D13, D15], dedupe [H2], location filter [D5], materialize candidate facts/gates and run preflight plan/check [D16], routing [D2, D10], proxy prompt hygiene [H8].
+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].
+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-facts.mjs

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  buildFacts,
+  checkFactRequirements,
+  factId,
+  hasFact,
+  loadFactsConfig,
+  parseJson,
+  queryFacts,
+  verifyFactSet,
+} from '@razroo/iso-facts';
+import {
+  jobForgeCompanyRoleKey,
+  jobForgeUrlKey,
+  legacyCompanyRoleKey,
+  legacyUrlKey,
+} from './jobforge-canon.mjs';
+
+export const FACTS_FILE = '.jobforge-facts.json';
+export const FACTS_CONFIG_FILE = 'templates/facts.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeFactsPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_FACTS || join(projectDir, FACTS_FILE);
+}
+
+export function jobForgeFactsConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_FACTS_CONFIG || join(projectDir, FACTS_CONFIG_FILE);
+}
+
+export function factsExist(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeFactsPath(projectDir));
+}
+
+export function readJobForgeFactsConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeFactsConfigPath(projectDir);
+  return loadFactsConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function buildJobForgeFacts(options = {}, projectDir = resolveProjectDir()) {
+  const config = readJobForgeFactsConfig(projectDir);
+  const factSet = canonicalizeJobForgeFacts(buildFacts(config, { root: projectDir }), projectDir);
+  const out = options.out || jobForgeFactsPath(projectDir);
+  if (options.write !== false) {
+    writeFileSync(out, `${JSON.stringify(factSet, null, 2)}\n`, 'utf8');
+  }
+  return { factSet, out };
+}
+
+export function readJobForgeFacts(projectDir = resolveProjectDir()) {
+  const path = jobForgeFactsPath(projectDir);
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+export function ensureJobForgeFacts(options = {}, projectDir = resolveProjectDir()) {
+  if (options.rebuild !== false || !factsExist(projectDir)) {
+    return buildJobForgeFacts({ out: options.out }, projectDir).factSet;
+  }
+  return readJobForgeFacts(projectDir);
+}
+
+export function queryJobForgeFacts(query = {}, options = {}, projectDir = resolveProjectDir()) {
+  return queryFacts(ensureJobForgeFacts(options, projectDir), query);
+}
+
+export function hasJobForgeFact(query = {}, options = {}, projectDir = resolveProjectDir()) {
+  return hasFact(ensureJobForgeFacts(options, projectDir), query);
+}
+
+export function verifyJobForgeFacts(options = {}, projectDir = resolveProjectDir()) {
+  const factSet = options.factSet || ensureJobForgeFacts(options, projectDir);
+  return verifyFactSet(factSet);
+}
+
+export function checkJobForgeFacts(options = {}, projectDir = resolveProjectDir()) {
+  const factSet = options.factSet || ensureJobForgeFacts(options, projectDir);
+  const config = readJobForgeFactsConfig(projectDir);
+  return checkFactRequirements(factSet, config.requirements || []);
+}
+
+export function jobForgeFactsSummary(projectDir = resolveProjectDir()) {
+  if (!factsExist(projectDir)) {
+    return {
+      path: jobForgeFactsPath(projectDir),
+      config: jobForgeFactsConfigPath(projectDir),
+      exists: false,
+      facts: 0,
+      files: 0,
+      sources: 0,
+    };
+  }
+  const factSet = readJobForgeFacts(projectDir);
+  return {
+    path: jobForgeFactsPath(projectDir),
+    config: jobForgeFactsConfigPath(projectDir),
+    exists: true,
+    facts: factSet.stats?.facts || 0,
+    files: factSet.stats?.files || 0,
+    sources: factSet.stats?.sources || 0,
+    configHash: factSet.configHash,
+  };
+}
+
+function canonicalizeJobForgeFacts(factSet, projectDir) {
+  const facts = (factSet.facts || []).map((fact) => canonicalizeJobForgeFact(fact, projectDir));
+  facts.sort(compareFacts);
+  return {
+    ...factSet,
+    facts,
+    stats: {
+      ...(factSet.stats || {}),
+      facts: facts.length,
+    },
+  };
+}
+
+function canonicalizeJobForgeFact(fact, projectDir) {
+  const key = canonicalFactKey(fact, projectDir);
+  if (key === fact.key) return fact;
+  const updated = { ...fact, key };
+  return { ...updated, id: factId(updated) };
+}
+
+function canonicalFactKey(fact, projectDir) {
+  if (isCompanyRoleFact(fact)) {
+    const { company, role } = companyRoleFields(fact);
+    if (company && role) return safeCompanyRoleKey(company, role, projectDir);
+  }
+  if (isUrlFact(fact)) {
+    const url = fact.fields?.url;
+    if (url) return safeUrlKey(url, projectDir);
+  }
+  return fact.key;
+}
+
+function isCompanyRoleFact(fact) {
+  return fact.key?.startsWith('company-role:') ||
+    fact.fact === 'application.status' ||
+    fact.fact === 'tracker.addition' ||
+    fact.fact === 'candidate.ready';
+}
+
+function companyRoleFields(fact) {
+  const fields = fact.fields || {};
+  return {
+    company: fields.company || fields.Company,
+    role: fields.role || fields.Role,
+  };
+}
+
+function isUrlFact(fact) {
+  return fact.key?.startsWith('url:') || fact.fact === 'job.url';
+}
+
+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 compareFacts(a, b) {
+  return `${a.fact}\0${a.key || ''}\0${a.value || ''}\0${a.source?.path || ''}\0${a.source?.line || ''}\0${a.id}`
+    .localeCompare(`${b.fact}\0${b.key || ''}\0${b.value || ''}\0${b.source?.path || ''}\0${b.source?.line || ''}\0${b.id}`);
+}

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.30",
+  "version": "2.14.32",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -55,6 +55,19 @@
     "index:has": "node bin/job-forge.mjs index:has",
     "index:verify": "node bin/job-forge.mjs index:verify",
     "index:explain": "node bin/job-forge.mjs index:explain",
+    "facts:build": "node bin/job-forge.mjs facts:build",
+    "facts:status": "node bin/job-forge.mjs facts:status",
+    "facts:verify": "node bin/job-forge.mjs facts:verify",
+    "facts:check": "node bin/job-forge.mjs facts:check",
+    "facts:has": "node bin/job-forge.mjs facts:has",
+    "facts:query": "node bin/job-forge.mjs facts:query",
+    "facts:explain": "node bin/job-forge.mjs facts:explain",
+    "score:compute": "node bin/job-forge.mjs score:compute",
+    "score:verify": "node bin/job-forge.mjs score:verify",
+    "score:check": "node bin/job-forge.mjs score:check",
+    "score:gate": "node bin/job-forge.mjs score:gate",
+    "score:compare": "node bin/job-forge.mjs score:compare",
+    "score:explain": "node bin/job-forge.mjs score:explain",
     "canon:normalize": "node bin/job-forge.mjs canon:normalize",
     "canon:key": "node bin/job-forge.mjs canon:key",
     "canon:compare": "node bin/job-forge.mjs canon:compare",
@@ -144,6 +157,7 @@
     "@razroo/iso-capabilities": "^0.1.0",
     "@razroo/iso-context": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
+    "@razroo/iso-facts": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-index": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",
@@ -152,6 +166,7 @@
     "@razroo/iso-postflight": "^0.1.0",
     "@razroo/iso-preflight": "^0.1.0",
     "@razroo/iso-redact": "^0.1.0",
+    "@razroo/iso-score": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"
   },

package/scripts/check-iso-smoke.mjs

@@ -19,6 +19,7 @@ const checks = [
   ["H5 blocks same-company concurrent retry", () => every(files.instructions, ["Re-dispatch the same company only AFTER", "previous subagent returns"])],
   ["H6 requires merge and verify", () => every(files.instructions, ["batch/tracker-additions/*.tsv", "npx job-forge merge", "npx job-forge verify"])],
   ["H7 distrusts subagent prose", () => every(files.instructions, ["must originate from a file", "not from prior subagent prose"])],
+  ["score policy points to local helper", () => every(files.instructions, ["[D19]", "templates/score.json", "npx job-forge score:check", "npx job-forge score:gate"])],
   ["shared prompt points to on-demand references", () => every(files.instructions, ["modes/{mode}.md", "modes/reference-setup.md", "modes/reference-portals.md", "modes/reference-geometra.md"])],
   ["apply mode owns high-stakes upgrade", () => every(files.apply, ["[D8]", "@general-paid", "4.0/5", "high-stakes"])],
   ["apply mode blocks provider auto-downgrade", () => every(files.apply, ["[D9]", "do not auto-downgrade", "inspect telemetry before retrying"])],