job-forge 2.14.33 → 2.14.35

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 !== ''),
+  );
+}

package/modes/README.md

@@ -3,11 +3,13 @@
 Markdown prompts used together with the root [`AGENTS.md`](../AGENTS.md). Each file aligns with a `/job-forge …` entry point or shared behavior described there.
 
 - **`_shared.md`** — Archetypes, scoring dimensions, negotiation scaffolding. Edit this first when you change how offers are classified or weighted.
+- **`reference-local-helpers.md`** — On-demand map of deterministic local helpers and when they replace prose, broad file reads, or manual policy checks.
 - **Per-command files** — Each `*.md` here pairs with a `/job-forge …` entry in [`AGENTS.md`](../AGENTS.md). How modes connect to batch, tracker, and scripts is spelled out in [**Architecture — Modes**](../docs/ARCHITECTURE.md#modes-modes).
 
 | File | Role |
 |------|------|
 | [`_shared.md`](_shared.md) | Shared archetypes, scoring, negotiation scaffolding |
+| [`reference-local-helpers.md`](reference-local-helpers.md) | Deterministic helper selection, mandatory uses, and integration enforcement |
 | [`auto-pipeline.md`](auto-pipeline.md) | Default path when the user pastes a JD or URL — full evaluate → report → PDF → tracker flow |
 | [`offer.md`](offer.md) | Explicit full evaluation (blocks A–F) for a single offer |
 | [`compare.md`](compare.md) | Side-by-side comparison of multiple offers |

package/modes/reference-local-helpers.md

@@ -0,0 +1,55 @@
+# Reference: Local Helpers
+
+JobForge's architectural helpers are local CLIs and JSON policies, not MCPs. They add no always-on prompt or tool-schema tokens. Use them when they can answer a question or validate an artifact more deterministically than prose.
+
+## Selection Rule
+
+Prefer a local helper when the workflow needs:
+
+- Identity, duplicate, or status truth.
+- Machine-readable artifact validation.
+- Context, capability, or migration policy.
+- Dispatch planning or settlement.
+- Scoring, timing, priority, or lineage decisions.
+- Safe export checks.
+
+Do not paste whole helper outputs into prompts unless the downstream agent needs that exact file-backed result. Prefer passing paths, ids, keys, and short summaries.
+
+## Helper Map
+
+| Need | Source / state | Command |
+|---|---|---|
+| Trace inspection | Local OpenCode transcripts | `npx job-forge trace:*` |
+| Run telemetry | Local traces + tracker TSV state | `npx job-forge telemetry:*` |
+| Guard audits | `templates/guards/jobforge-baseline.yaml` | `npx job-forge guard:*` |
+| Workflow state | `.jobforge-ledger/events.jsonl` | `npx job-forge ledger:*` |
+| Artifact contracts | `templates/contracts.json` | `npx job-forge tracker-line ... --write`; `npx job-forge verify` |
+| Role capability policy | `templates/capabilities.json` | `npx job-forge capabilities:*` |
+| Context bundle policy | `templates/context.json` | `npx job-forge context:*` |
+| JD/artifact reuse | `.jobforge-cache/` | `npx job-forge cache:*` |
+| Artifact lookup | `.jobforge-index.json` from `templates/index.json` | `npx job-forge index:*` |
+| Source-backed facts | `.jobforge-facts.json` from `templates/facts.json` | `npx job-forge facts:*` |
+| Consumer upgrades | `templates/migrations.json` | `npx job-forge migrate:*` |
+| Identity keys | `templates/canon.json` | `npx job-forge canon:*` |
+| Apply dispatch safety | `templates/preflight.json` | `npx job-forge preflight:*` |
+| Dispatch settlement | `templates/postflight.json` | `npx job-forge postflight:*` |
+| Safe export | `templates/redact.json` | `npx job-forge redact:*` |
+| Offer scoring | `templates/score.json` | `npx job-forge score:*` |
+| Follow-up timing | `templates/timeline.json` | `npx job-forge timeline:*` |
+| Next-action ranking | `templates/prioritize.json` | `npx job-forge prioritize:*` |
+| Artifact lineage | `.jobforge-lineage.json` | `npx job-forge lineage:*` |
+
+## Mandatory Uses
+
+- Before duplicate-sensitive apply dispatches, use `canon:key`, `index:has`, `facts:has`, or `ledger:has` as cheap prefilters when useful, then still apply the H2 four-source grep unless the candidate JSON already materializes those sources.
+- For tracker additions, prefer `tracker-line --write`; if TSV is emitted manually, `merge` and `verify` must validate it through `templates/contracts.json`.
+- For score-driven apply/PDF decisions, run `score:check --input <file>` and `score:gate --input <file> --gate apply`.
+- For follow-up triage, run `timeline:due`; use `timeline:check --fail-on overdue` when stale follow-ups should fail the workflow.
+- For next-action or replacement-candidate selection, run `prioritize:build` or `prioritize:select --limit N`.
+- For generated reports or PDFs reused after input changes, run `lineage:check --artifact <file>` if lineage exists; after creating derived artifacts, record them with `lineage:record --artifact <file> --input <source>...`.
+- Before exporting traces, prompts, reports, or fixtures outside the project, run `redact:scan`, `redact:apply`, or `redact:verify`.
+- When diagnosing consumer harness drift, run `migrate:plan` or `migrate:check`; `job-forge sync` applies safe migrations automatically unless `JOB_FORGE_SKIP_MIGRATIONS=1` is set.
+
+## Enforcement
+
+The integration surface is checked by `npm run lint:helpers`. That check verifies helper dependencies, package scripts, scaffolder scripts, migration scripts, generated ignores, templates, and this reference stay aligned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.33",
+  "version": "2.14.35",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -85,6 +85,20 @@
     "timeline:check": "node bin/job-forge.mjs timeline:check",
     "timeline:verify": "node bin/job-forge.mjs timeline:verify",
     "timeline:explain": "node bin/job-forge.mjs timeline:explain",
+    "prioritize:status": "node bin/job-forge.mjs prioritize:status",
+    "prioritize:items": "node bin/job-forge.mjs prioritize:items",
+    "prioritize:build": "node bin/job-forge.mjs prioritize:build",
+    "prioritize:rank": "node bin/job-forge.mjs prioritize:rank",
+    "prioritize:select": "node bin/job-forge.mjs prioritize:select",
+    "prioritize:check": "node bin/job-forge.mjs prioritize:check",
+    "prioritize:verify": "node bin/job-forge.mjs prioritize:verify",
+    "prioritize:explain": "node bin/job-forge.mjs prioritize:explain",
+    "lineage:status": "node bin/job-forge.mjs lineage:status",
+    "lineage:record": "node bin/job-forge.mjs lineage:record",
+    "lineage:check": "node bin/job-forge.mjs lineage:check",
+    "lineage:stale": "node bin/job-forge.mjs lineage:stale",
+    "lineage:verify": "node bin/job-forge.mjs lineage:verify",
+    "lineage:explain": "node bin/job-forge.mjs lineage:explain",
     "redact:scan": "node bin/job-forge.mjs redact:scan",
     "redact:verify": "node bin/job-forge.mjs redact:verify",
     "redact:apply": "node bin/job-forge.mjs redact:apply",
@@ -96,11 +110,12 @@
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
+    "lint:helpers": "node scripts/check-helper-integration.mjs .",
     "test:agentmd": "agentmd test iso/instructions.md --fixtures fixtures/instructions.yml --via claude-code --model claude-haiku-4-5 --concurrency 2",
     "test:agentmd:baseline": "agentmd test iso/instructions.md --fixtures fixtures/instructions.yml --via claude-code --model claude-haiku-4-5 --concurrency 2 --trials 3 --format json --out fixtures/baseline.json",
     "test:agentmd:apply": "agentmd test modes/apply.md --fixtures fixtures/modes/apply.yml --via claude-code --model claude-haiku-4-5 --concurrency 2 --trials 3",
     "lint:agentmd:modes": "agentmd lint modes/apply.md",
-    "smoke:iso": "iso plan . && iso build . --dry-run && iso-route verify models.yaml && node scripts/check-iso-smoke.mjs . && JOBFORGE_ROOT=$PWD iso-eval run fixtures/iso-smoke/eval.yml",
+    "smoke:iso": "iso plan . && iso build . --dry-run && iso-route verify models.yaml && node scripts/check-iso-smoke.mjs . && node scripts/check-helper-integration.mjs . && JOBFORGE_ROOT=$PWD iso-eval run fixtures/iso-smoke/eval.yml",
     "build:config": "iso build .",
     "prepack": "iso build .",
     "release:check-source": "node ./scripts/release/check-source.mjs",
@@ -168,10 +183,12 @@
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-index": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",
+    "@razroo/iso-lineage": "^0.1.0",
     "@razroo/iso-migrate": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-postflight": "^0.1.0",
     "@razroo/iso-preflight": "^0.1.0",
+    "@razroo/iso-prioritize": "^0.1.0",
     "@razroo/iso-redact": "^0.1.0",
     "@razroo/iso-score": "^0.1.0",
     "@razroo/iso-timeline": "^0.1.0",

package/scripts/check-helper-integration.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const root = resolve(process.argv[2] || '.');
+
+const pkg = readJson('package.json');
+const migrations = readJson('templates/migrations.json');
+const bin = readText('bin/job-forge.mjs');
+const create = readText('bin/create-job-forge.mjs');
+const reference = readText('modes/reference-local-helpers.md');
+const rootIgnore = readText('.gitignore');
+const architecture = readText('docs/ARCHITECTURE.md');
+
+const migrationScripts = migrationValue('jobforge-managed-scripts', '/scripts');
+const migrationIgnores = migrationValue('jobforge-generated-ignores');
+
+const groups = [
+  helper('trace', '@razroo/iso-trace', ['list', 'stats', 'show']),
+  helper('telemetry', '', ['list', 'status', 'show', 'watch']),
+  helper('guard', '@razroo/iso-guard', ['audit', 'explain'], { template: 'templates/guards/jobforge-baseline.yaml' }),
+  helper('ledger', '@razroo/iso-ledger', ['status', 'rebuild', 'verify', 'has', 'query'], { artifacts: ['.jobforge-ledger/'] }),
+  helper('capabilities', '@razroo/iso-capabilities', ['list', 'explain', 'check', 'render'], { template: 'templates/capabilities.json', migrated: true }),
+  helper('context', '@razroo/iso-context', ['list', 'explain', 'plan', 'check', 'render'], { template: 'templates/context.json', migrated: true }),
+  helper('cache', '@razroo/iso-cache', ['key', 'has', 'get', 'put', 'status', 'list', 'verify', 'prune'], { artifacts: ['.jobforge-cache/'], migrated: true }),
+  helper('index', '@razroo/iso-index', ['build', 'status', 'query', 'has', 'verify', 'explain'], { template: 'templates/index.json', artifacts: ['.jobforge-index.json'], migrated: true }),
+  helper('facts', '@razroo/iso-facts', ['build', 'status', 'verify', 'check', 'has', 'query', 'explain'], { template: 'templates/facts.json', artifacts: ['.jobforge-facts.json'], migrated: true }),
+  helper('score', '@razroo/iso-score', ['compute', 'verify', 'check', 'gate', 'compare', 'explain'], { template: 'templates/score.json', migrated: true }),
+  helper('canon', '@razroo/iso-canon', ['normalize', 'key', 'compare', 'explain'], { template: 'templates/canon.json', migrated: true }),
+  helper('preflight', '@razroo/iso-preflight', ['plan', 'check', 'explain'], { template: 'templates/preflight.json', artifacts: ['batch/preflight-candidates.json', 'batch/preflight-plan.json'], migrated: true }),
+  helper('postflight', '@razroo/iso-postflight', ['status', 'check', 'explain'], { template: 'templates/postflight.json', artifacts: ['batch/postflight-outcomes.json'], migrated: true }),
+  helper('timeline', '@razroo/iso-timeline', ['status', 'build', 'plan', 'due', 'check', 'verify', 'explain'], { template: 'templates/timeline.json', artifacts: ['.jobforge-timeline.json', '.jobforge-timeline-events.jsonl', 'data/timeline-events.jsonl'], migrated: true }),
+  helper('prioritize', '@razroo/iso-prioritize', ['status', 'items', 'build', 'rank', 'select', 'check', 'verify', 'explain'], { template: 'templates/prioritize.json', artifacts: ['.jobforge-prioritize.json', '.jobforge-prioritize-items.json'], migrated: true }),
+  helper('lineage', '@razroo/iso-lineage', ['status', 'record', 'check', 'stale', 'verify', 'explain'], { artifacts: ['.jobforge-lineage.json'], migrated: true }),
+  helper('redact', '@razroo/iso-redact', ['scan', 'verify', 'apply', 'explain'], { template: 'templates/redact.json', artifacts: ['.jobforge-redacted/'], migrated: true }),
+  helper('migrate', '@razroo/iso-migrate', ['plan', 'apply', 'check', 'explain'], { template: 'templates/migrations.json', migrated: true }),
+];
+
+const packageOnly = [
+  { id: 'contract', pkg: '@razroo/iso-contract', template: 'templates/contracts.json', needles: ['templates/contracts.json', 'tracker-line'] },
+  { id: 'orchestrator', pkg: '@razroo/iso-orchestrator', file: 'scripts/batch-orchestrator.mjs', needles: ['iso-orchestrator'] },
+];
+
+const errors = [];
+
+for (const group of groups) {
+  if (group.pkg) hasDependency(group.pkg, group.id);
+  if (group.template) fileExists(group.template, group.id);
+  fileExists(`scripts/${group.id}.mjs`, group.id);
+
+  if (!bin.includes(`const ${group.id}Aliases`)) {
+    errors.push(`${group.id}: missing ${group.id}Aliases in bin/job-forge.mjs`);
+  }
+  if (!bin.includes(`scripts/${group.id}.mjs`)) {
+    errors.push(`${group.id}: bin/job-forge.mjs does not dispatch scripts/${group.id}.mjs`);
+  }
+  if (!reference.includes(`job-forge ${group.id}:*`)) {
+    errors.push(`${group.id}: modes/reference-local-helpers.md does not mention job-forge ${group.id}:*`);
+  }
+  if (!architecture.includes(`scripts/${group.id}.mjs`)) {
+    errors.push(`${group.id}: docs/ARCHITECTURE.md script table does not mention scripts/${group.id}.mjs`);
+  }
+
+  for (const alias of group.aliases) {
+    if (!pkg.scripts?.[alias]) errors.push(`${group.id}: package.json missing script ${alias}`);
+    if (!createIncludesScript(alias)) errors.push(`${group.id}: create-job-forge missing script ${alias}`);
+    if (group.migrated && migrationScripts?.[alias] !== `job-forge ${alias}`) {
+      errors.push(`${group.id}: migrations.json missing managed script ${alias}`);
+    }
+  }
+
+  for (const artifact of group.artifacts) {
+    if (!rootIgnore.includes(artifact)) errors.push(`${group.id}: .gitignore missing ${artifact}`);
+    if (!create.includes(artifact)) errors.push(`${group.id}: create-job-forge .gitignore template missing ${artifact}`);
+    if (group.migrated && !migrationIgnores.includes(artifact)) {
+      errors.push(`${group.id}: migrations.json generated ignores missing ${artifact}`);
+    }
+  }
+}
+
+for (const item of packageOnly) {
+  hasDependency(item.pkg, item.id);
+  if (item.template) fileExists(item.template, item.id);
+  if (item.file) fileExists(item.file, item.id);
+  for (const needle of item.needles || []) {
+    if (!reference.includes(needle) && !architecture.includes(needle)) {
+      errors.push(`${item.id}: expected documentation needle "${needle}"`);
+    }
+  }
+}
+
+if (/\[D(?:9|1\d|2[0-9])\]/.test(readText('iso/instructions.md'))) {
+  errors.push('iso/instructions.md still has detailed helper D-rules; keep helper details in modes/reference-local-helpers.md');
+}
+
+if (errors.length) {
+  console.error('JobForge helper integration check failed:');
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log(`JobForge helper integration passed (${groups.length + packageOnly.length} helpers).`);
+
+function helper(id, pkg, commands, options = {}) {
+  return {
+    id,
+    pkg,
+    aliases: commands.map((command) => `${id}:${command}`),
+    template: options.template || '',
+    artifacts: options.artifacts || [],
+    migrated: Boolean(options.migrated),
+  };
+}
+
+function readJson(path) {
+  return JSON.parse(readText(path));
+}
+
+function readText(path) {
+  return readFileSync(join(root, path), 'utf8');
+}
+
+function fileExists(path, id) {
+  if (!existsSync(join(root, path))) errors.push(`${id}: missing ${path}`);
+}
+
+function hasDependency(name, id) {
+  if (!pkg.dependencies?.[name] && !pkg.devDependencies?.[name]) {
+    errors.push(`${id}: package.json missing dependency ${name}`);
+  }
+}
+
+function migrationValue(id, pointer = '') {
+  const migration = migrations.migrations?.find((item) => item.id === id);
+  const operation = migration?.operations?.find((item) => pointer ? item.pointer === pointer : item.type === 'ensure-lines');
+  return pointer ? operation?.value : operation?.lines || [];
+}
+
+function createIncludesScript(alias) {
+  return create.includes(`'${alias}': 'job-forge ${alias}'`) ||
+    create.includes(`"${alias}": "job-forge ${alias}"`);
+}

package/scripts/check-iso-smoke.mjs

@@ -5,6 +5,7 @@ import { resolve } from "node:path";
 const root = resolve(process.argv[2] ?? ".");
 const files = {
   instructions: readFileSync(resolve(root, "iso/instructions.md"), "utf8"),
+  helpers: readFileSync(resolve(root, "modes/reference-local-helpers.md"), "utf8"),
   apply: readFileSync(resolve(root, "modes/apply.md"), "utf8"),
   models: readFileSync(resolve(root, "models.yaml"), "utf8"),
   config: readFileSync(resolve(root, "iso/config.json"), "utf8"),
@@ -19,8 +20,9 @@ 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"])],
-  ["timeline policy points to local helper", () => every(files.instructions, ["[D20]", "templates/timeline.json", "npx job-forge timeline:due", "npx job-forge timeline:check --fail-on overdue"])],
+  ["root points to consolidated helper reference", () => every(files.instructions, ["[D8]", "modes/reference-local-helpers.md", "deterministic local helpers"])],
+  ["helper reference covers score/timeline/prioritize/lineage", () => every(files.helpers, ["templates/score.json", "npx job-forge score:*", "templates/timeline.json", "npx job-forge timeline:*", "templates/prioritize.json", "npx job-forge prioritize:*", ".jobforge-lineage.json", "npx job-forge lineage:*"])],
+  ["root helper defaults are consolidated", () => !/\[D(?:9|1\d|2[0-9])\]/.test(files.instructions)],
   ["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"])],