job-forge 2.14.27 → 2.14.28

package/.cursor/rules/main.mdc

@@ -83,12 +83,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
   why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
 
+- [D16] Treat `templates/preflight.json` as the source of truth for multi-apply dispatch safety. After candidate facts and gates are materialized from authoritative files, run `npx job-forge preflight:plan --candidates <file>` or `npx job-forge preflight:check --candidates <file>` before task dispatch; follow the emitted rounds and pre/post steps. This does not replace H2 four-source grep until those facts are materialized into the candidate JSON.
+  why: `iso-preflight` is not an MCP and adds no prompt/tool-schema tokens; it turns file-backed facts, duplicate/location gates, max-two rounds, and cleanup/merge/verify steps into an executable local plan instead of repeated 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]. 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], routing [D2, D10], proxy prompt hygiene [H8].
+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].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

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

@@ -82,6 +82,10 @@ Identity keys (terminal, outside opencode):
   npx job-forge canon:key company-role --company "Acme" --role "Staff Engineer"
   npx job-forge canon:compare company "OpenAI, Inc." "Open AI"
 
+Preflight dispatch plans (terminal, outside opencode):
+  npx job-forge preflight:plan --candidates batch/preflight-candidates.json
+  npx job-forge preflight:check --candidates batch/preflight-candidates.json
+
 Consumer migrations (terminal, outside opencode):
   npx job-forge migrate:plan           # preview package.json/.gitignore drift
   npx job-forge migrate:apply          # apply safe harness upgrade migrations
@@ -194,7 +198,19 @@ Step 3  — Pre-flight cleanup (once, before the loop)
   - geometra_list_sessions()
   - geometra_disconnect({ closeBrowser: true })
 
-Step 4  — Loop in rounds of 2 (Hard Limit #1)
+Step 4  — Materialize and check the dispatch plan
+  - Write file-backed candidate facts/gates to batch/preflight-candidates.json
+    (or another explicit JSON file). Include source paths for company, role,
+    companyRoleKey, URL, score, duplicate/location gates, and any skip/block
+    decision.
+  - Run npx job-forge preflight:check --candidates <file> to fail on missing
+    sources or blocked gates, then npx job-forge preflight:plan --candidates
+    <file> to get the bounded round list.
+  - Follow the emitted rounds. Do not dispatch blocked candidates, and do not
+    replace H2's four-source grep with preflight unless those grep results are
+    present in the candidate JSON.
+
+Step 5  — Loop in rounds of 2 (Hard Limit #1)
   for round in ceil(len(candidates) / 2):
     pair = candidates[round*2 : round*2 + 2]
     # If proxy is configured, do not paste proxy values into prompts.

package/AGENTS.md

@@ -78,12 +78,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
   why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
 
+- [D16] Treat `templates/preflight.json` as the source of truth for multi-apply dispatch safety. After candidate facts and gates are materialized from authoritative files, run `npx job-forge preflight:plan --candidates <file>` or `npx job-forge preflight:check --candidates <file>` before task dispatch; follow the emitted rounds and pre/post steps. This does not replace H2 four-source grep until those facts are materialized into the candidate JSON.
+  why: `iso-preflight` is not an MCP and adds no prompt/tool-schema tokens; it turns file-backed facts, duplicate/location gates, max-two rounds, and cleanup/merge/verify steps into an executable local plan instead of repeated 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]. 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], routing [D2, D10], proxy prompt hygiene [H8].
+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].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -78,12 +78,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
   why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
 
+- [D16] Treat `templates/preflight.json` as the source of truth for multi-apply dispatch safety. After candidate facts and gates are materialized from authoritative files, run `npx job-forge preflight:plan --candidates <file>` or `npx job-forge preflight:check --candidates <file>` before task dispatch; follow the emitted rounds and pre/post steps. This does not replace H2 four-source grep until those facts are materialized into the candidate JSON.
+  why: `iso-preflight` is not an MCP and adds no prompt/tool-schema tokens; it turns file-backed facts, duplicate/location gates, max-two rounds, and cleanup/merge/verify steps into an executable local plan instead of repeated 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]. 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], routing [D2, D10], proxy prompt hygiene [H8].
+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].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

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 MCP-free local workflow state: `templates/canon.json` defines URL/company/role identity keys via `@razroo/iso-canon`, `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, and `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`. None of these add always-on prompt or tool-schema tokens.
+JobForge also keeps MCP-free local workflow state: `templates/canon.json` defines URL/company/role identity keys via `@razroo/iso-canon`, `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, `templates/preflight.json` defines safe dispatch rounds/gates via `@razroo/iso-preflight`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, and `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`. None of these add always-on 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 + Contract + Canon + Ledger + Capabilities + Context + Cache + Index + Migrate** | `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`, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
+| **Trace + Telemetry + Guard + Contract + Canon + Ledger + Capabilities + Context + Cache + Index + Preflight + Migrate** | `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`, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, `job-forge preflight:*` plans bounded apply dispatch rounds from file-backed candidate facts, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema 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
@@ -164,7 +164,7 @@ my-search/
 ├── .opencode/skills/job-forge.md # → skill router
 ├── .opencode/agents/             # → @general-free, @general-paid, @glm-minimal
 ├── modes/                        # → _shared.md + skill modes
-├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, capabilities.json, context.json, index.json, migrations.json
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, capabilities.json, context.json, index.json, preflight.json, migrations.json
 ├── batch/batch-prompt.md         # → batch worker prompt
 ├── batch/batch-runner.sh         # → parallel orchestrator
 │
@@ -190,7 +190,7 @@ JobForge/
 │   ├── sync.mjs                  # postinstall: creates symlinks in consumer project
 │   └── create-job-forge.mjs      # scaffolder
 ├── modes/                        # _shared.md + 16 skill modes
-├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, capabilities.json, context.json, migrations.json
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, capabilities.json, context.json, preflight.json, migrations.json
 ├── config/profile.example.yml    # template for consumer's profile.yml
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
@@ -202,6 +202,7 @@ JobForge/
 │   ├── cache.mjs                 # iso-cache-backed local artifact cache CLI
 │   ├── index.mjs                 # iso-index-backed artifact lookup CLI
 │   ├── canon.mjs                 # iso-canon-backed identity normalization CLI
+│   ├── preflight.mjs             # iso-preflight-backed dispatch planning CLI
 │   ├── migrate.mjs               # iso-migrate-backed consumer-project migrations
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish

package/bin/create-job-forge.mjs

@@ -151,6 +151,9 @@ const consumerPkg = {
     'canon:key': 'job-forge canon:key',
     'canon:compare': 'job-forge canon:compare',
     'canon:explain': 'job-forge canon:explain',
+    'preflight:plan': 'job-forge preflight:plan',
+    'preflight:check': 'job-forge preflight:check',
+    'preflight:explain': 'job-forge preflight:explain',
     'migrate:plan': 'job-forge migrate:plan',
     'migrate:apply': 'job-forge migrate:apply',
     'migrate:check': 'job-forge migrate:check',
@@ -257,6 +260,7 @@ Before doing any work, remember where things live in *this* project:
 | Local workflow ledger | \`.jobforge-ledger/events.jsonl\` | Deterministic append-only state; use \`job-forge ledger:*\` |
 | Local artifact index | \`.jobforge-index.json\` | Deterministic file/line lookup; use \`job-forge index:*\` |
 | Identity canonicalization | \`templates/canon.json\` | Stable URL/company/role keys; use \`job-forge canon:*\` |
+| Dispatch preflight policy | \`templates/preflight.json\` | Safe apply rounds/gates; use \`job-forge preflight:*\` |
 | Consumer migrations | \`templates/migrations.json\` | Safe script/gitignore upgrades; use \`job-forge migrate:*\` |
 | Scanner config | \`portals.yml\` (project root) | Company configs |
 | Profile / identity | \`config/profile.yml\` | Candidate name, email, target roles |
@@ -408,6 +412,7 @@ job-forge verify           # verify pipeline integrity
 job-forge ledger:status    # local deterministic workflow ledger status
 job-forge index:status     # local artifact index status
 job-forge canon:key company-role --company "Acme, Inc." --role "Senior SWE"
+job-forge preflight:plan --candidates batch/preflight-candidates.json
 job-forge migrate:check    # verify consumer package scripts/gitignore are current
 job-forge pdf cv.md out.pdf
 job-forge tokens --days 1  # per-session opencode token usage

package/bin/job-forge.mjs

@@ -26,6 +26,7 @@
  *   cache:*        Reuse local deterministic artifacts via iso-cache
  *   index:*        Query local artifacts via iso-index
  *   canon:*        Compute deterministic identity keys via iso-canon
+ *   preflight:*    Plan safe dispatch rounds via iso-preflight
  *   migrate:*      Apply deterministic consumer-project migrations via iso-migrate
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
@@ -137,6 +138,13 @@ const canonAliases = {
   'canon:path': 'path',
 };
 
+const preflightAliases = {
+  'preflight:plan': 'plan',
+  'preflight:check': 'check',
+  'preflight:explain': 'explain',
+  'preflight:path': 'path',
+};
+
 const migrateAliases = {
   'migrate:plan': 'plan',
   'migrate:apply': 'apply',
@@ -198,6 +206,9 @@ Commands:
   canon:key               Print stable URL/company/role/company-role keys
   canon:compare           Compare two identifiers as same/possible/different
   canon:explain           Show the active identity canonicalization policy
+  preflight:plan          Build bounded dispatch plan from candidate JSON
+  preflight:check         Fail if preflight candidates are blocked
+  preflight:explain       Show the active preflight workflow policy
   migrate:plan            Preview deterministic consumer-project migrations
   migrate:apply           Apply deterministic consumer-project migrations
   migrate:check           Fail if migrations are pending
@@ -242,6 +253,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge index:query "acme"
   job-forge canon:key company-role --company "Acme, Inc." --role "Senior SWE - Remote US"
   job-forge canon:compare company "OpenAI, Inc." "Open AI"
+  job-forge preflight:plan --candidates batch/preflight-candidates.json
+  job-forge preflight:check --candidates batch/preflight-candidates.json
   job-forge migrate:check
   job-forge migrate:apply
 
@@ -388,6 +401,21 @@ if (cmd === 'canon' || canonAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'preflight' || preflightAliases[cmd]) {
+  const preflightArgs = cmd === 'preflight'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [preflightAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/preflight.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...preflightArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 if (cmd === 'migrate' || migrateAliases[cmd]) {
   const migrateArgs = cmd === 'migrate'
     ? (rest.length === 0 ? ['help'] : rest)

package/docs/ARCHITECTURE.md

@@ -32,7 +32,7 @@ my-search/
 ├── .opencode/skills/job-forge.md     # → skill router
 ├── .opencode/agents/                 # → @general-free, @general-paid, @glm-minimal
 ├── modes/                            # → mode files
-├── templates/                        # → states.yml, portals.example.yml, cv-template.html
+├── templates/                        # → states.yml, portals.example.yml, cv-template.html, preflight.json
 ├── batch/batch-prompt.md             # → batch worker prompt
 ├── batch/batch-runner.sh             # → parallel orchestrator
 └── node_modules/job-forge/           # harness, installed from npm
@@ -166,6 +166,7 @@ jds/*.md                 →  Saved job descriptions referenced from the pipelin
 templates/states.yml     →  Canonical status values
 templates/canon.json      →  Canonical URL/company/role identity keys
 templates/context.json    →  Deterministic mode/reference context bundle policy
+templates/preflight.json  →  Safe apply dispatch rounds/gates policy
 templates/migrations.json → Safe consumer-project upgrade policy
 templates/cv-template.html → PDF generation template
 examples/*.md            →  Fictional layouts only (not read by scripts; see examples/README.md)
@@ -181,6 +182,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 - Ledger: `.jobforge-ledger/events.jsonl` (created by `job-forge ledger:rebuild`, `tracker-line --write`, or `merge`; gitignored personal state)
 - Index: `.jobforge-index.json` (created on demand by `job-forge index:*`; gitignored local lookup state)
 - Canon: `templates/canon.json` (identity rules inspected with `job-forge canon:*`)
+- Preflight: `templates/preflight.json` (dispatch rounds/gates inspected with `job-forge preflight:*`)
 - Migrations: `templates/migrations.json` (applied by `job-forge sync` and inspectable with `job-forge migrate:*`)
 - Capabilities: `templates/capabilities.json` (role boundary policy inspected with `job-forge capabilities:*`)
 - Context: `templates/context.json` (mode/reference file bundles inspected with `job-forge context:*`)
@@ -229,6 +231,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `scripts/index.mjs` | `npx job-forge index:status` / `index:has` / `index:query` | Deterministic `@razroo/iso-index` lookup over reports, tracker rows, TSVs, pipeline, scan history, and ledger events |
 | `scripts/canon.mjs` | `npx job-forge canon:normalize` / `canon:key` / `canon:compare` | Deterministic `@razroo/iso-canon` identity normalization for URLs, companies, roles, and company+role pairs |
 | `scripts/context.mjs` | `npx job-forge context:list` / `context:plan` / `context:check` / `context:render` | Deterministic `@razroo/iso-context` mode/reference context bundle planning and rendering |
+| `scripts/preflight.mjs` | `npx job-forge preflight:plan` / `preflight:check` / `preflight:explain` | Deterministic `@razroo/iso-preflight` dispatch planning for file-backed candidate facts and gates |
 | `scripts/migrate.mjs` | `npx job-forge migrate:plan` / `migrate:apply` / `migrate:check` | Deterministic `@razroo/iso-migrate` consumer-project upgrades for scripts and generated-artifact ignores |
 | `tracker-lib.mjs` | _(library)_ | Shared helpers for reading/writing day-based tracker files — imported by merge/dedup/verify/normalize |
 | `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project and applies safe migrations (also runs as `postinstall`) |

package/docs/CUSTOMIZATION.md

@@ -158,6 +158,10 @@ Artifact lookup policy lives in `templates/index.json` and is built locally by `
 
 URL, company, role, and company+role identity rules live in `templates/canon.json` and are enforced locally by `@razroo/iso-canon`. Use `job-forge canon:key company-role --company "OpenAI, Inc." --role "Senior SWE, AI Platform"` to derive the same duplicate key used by ledger/index helpers, and `job-forge canon:compare company "OpenAI, Inc." "Open AI"` to explain whether two values resolve to the same entity. Custom forks can extend aliases, suffixes, stop words, and match thresholds in `templates/canon.json`. This is not an MCP and does not add prompt or tool-schema tokens.
 
+## JobForge preflight plans
+
+Application dispatch policy lives in `templates/preflight.json` and is planned locally by `@razroo/iso-preflight`. After candidate facts and gate results have been materialized into JSON, use `job-forge preflight:plan --candidates <file>` to get bounded rounds and required pre/post steps, or `job-forge preflight:check --candidates <file>` to fail on missing source facts or blocked gates. This is not an MCP and does not add prompt or tool-schema tokens; it consumes only the candidate JSON you deliberately pass to it.
+
 ## JobForge consumer migrations
 
 Consumer-project migrations live in `templates/migrations.json` and are applied locally by `@razroo/iso-migrate`. `job-forge sync` applies safe migrations automatically after refreshing symlinks; use `JOB_FORGE_SKIP_MIGRATIONS=1` to opt out. Use `job-forge migrate:plan`, `job-forge migrate:apply`, and `job-forge migrate:check` to inspect or enforce script/gitignore drift explicitly. This is not an MCP and does not add prompt or tool-schema tokens.

package/docs/README.md

@@ -31,7 +31,7 @@ The harness exposes a single CLI (`job-forge`) installed as a `bin` entry. In a
 
 | What you need | Where to read |
 |---------------|---------------|
-| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `canon`, `context`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
+| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `canon`, `context`, `preflight`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
 | What each harness `.mjs` script does. | [ARCHITECTURE.md — Pipeline integrity](ARCHITECTURE.md#pipeline-integrity) and the scripts table underneath. |
 | Batch runner, TSV layout, and `batch/tracker-additions/` merge flow. | [batch/README.md](../batch/README.md). |
 | PR gate for harness contributions (`npm run verify` + `npm run build:dashboard`). | [CONTRIBUTING.md — Development](../CONTRIBUTING.md#development). |

package/docs/SETUP.md

@@ -132,6 +132,8 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Inspect context bundle budget | `npx job-forge context:plan apply` | `npm run context:plan -- apply` |
 | Inspect local JD/artifact cache | `npx job-forge cache:status` | `npm run cache:status` |
 | Inspect local artifact index | `npx job-forge index:status` | `npm run index:status` |
+| Plan safe application dispatch rounds | `npx job-forge preflight:plan --candidates batch/preflight-candidates.json` | `npm run preflight:plan -- --candidates ...` |
+| Fail on blocked preflight candidates | `npx job-forge preflight:check --candidates batch/preflight-candidates.json` | `npm run preflight:check -- --candidates ...` |
 | Inspect pending consumer migrations | `npx job-forge migrate:plan` | `npm run migrate:plan` |
 | 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` |

package/iso/commands/job-forge.md

@@ -85,6 +85,10 @@ Identity keys (terminal, outside opencode):
   npx job-forge canon:key company-role --company "Acme" --role "Staff Engineer"
   npx job-forge canon:compare company "OpenAI, Inc." "Open AI"
 
+Preflight dispatch plans (terminal, outside opencode):
+  npx job-forge preflight:plan --candidates batch/preflight-candidates.json
+  npx job-forge preflight:check --candidates batch/preflight-candidates.json
+
 Consumer migrations (terminal, outside opencode):
   npx job-forge migrate:plan           # preview package.json/.gitignore drift
   npx job-forge migrate:apply          # apply safe harness upgrade migrations
@@ -197,7 +201,19 @@ Step 3  — Pre-flight cleanup (once, before the loop)
   - geometra_list_sessions()
   - geometra_disconnect({ closeBrowser: true })
 
-Step 4  — Loop in rounds of 2 (Hard Limit #1)
+Step 4  — Materialize and check the dispatch plan
+  - Write file-backed candidate facts/gates to batch/preflight-candidates.json
+    (or another explicit JSON file). Include source paths for company, role,
+    companyRoleKey, URL, score, duplicate/location gates, and any skip/block
+    decision.
+  - Run npx job-forge preflight:check --candidates <file> to fail on missing
+    sources or blocked gates, then npx job-forge preflight:plan --candidates
+    <file> to get the bounded round list.
+  - Follow the emitted rounds. Do not dispatch blocked candidates, and do not
+    replace H2's four-source grep with preflight unless those grep results are
+    present in the candidate JSON.
+
+Step 5  — Loop in rounds of 2 (Hard Limit #1)
   for round in ceil(len(candidates) / 2):
     pair = candidates[round*2 : round*2 + 2]
     # If proxy is configured, do not paste proxy values into prompts.

package/iso/instructions.md

@@ -78,12 +78,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
   why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
 
+- [D16] Treat `templates/preflight.json` as the source of truth for multi-apply dispatch safety. After candidate facts and gates are materialized from authoritative files, run `npx job-forge preflight:plan --candidates <file>` or `npx job-forge preflight:check --candidates <file>` before task dispatch; follow the emitted rounds and pre/post steps. This does not replace H2 four-source grep until those facts are materialized into the candidate JSON.
+  why: `iso-preflight` is not an MCP and adds no prompt/tool-schema tokens; it turns file-backed facts, duplicate/location gates, max-two rounds, and cleanup/merge/verify steps into an executable local plan instead of repeated 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]. 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], routing [D2, D10], proxy prompt hygiene [H8].
+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].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/lib/jobforge-preflight.mjs

@@ -0,0 +1,29 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  loadPreflightConfig,
+  parseJson,
+  planPreflight,
+} from '@razroo/iso-preflight';
+
+export const PREFLIGHT_CONFIG_FILE = 'templates/preflight.json';
+export const PREFLIGHT_WORKFLOW = 'jobforge.apply';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgePreflightConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_PREFLIGHT_CONFIG || join(projectDir, PREFLIGHT_CONFIG_FILE);
+}
+
+export function readJobForgePreflightConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgePreflightConfigPath(projectDir);
+  return loadPreflightConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function planJobForgePreflight(candidateInput, options = {}, projectDir = resolveProjectDir()) {
+  return planPreflight(readJobForgePreflightConfig(projectDir), candidateInput, {
+    workflow: options.workflow || PREFLIGHT_WORKFLOW,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.27",
+  "version": "2.14.28",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -59,6 +59,9 @@
     "canon:key": "node bin/job-forge.mjs canon:key",
     "canon:compare": "node bin/job-forge.mjs canon:compare",
     "canon:explain": "node bin/job-forge.mjs canon:explain",
+    "preflight:plan": "node bin/job-forge.mjs preflight:plan",
+    "preflight:check": "node bin/job-forge.mjs preflight:check",
+    "preflight:explain": "node bin/job-forge.mjs preflight:explain",
     "migrate:plan": "node bin/job-forge.mjs migrate:plan",
     "migrate:apply": "node bin/job-forge.mjs migrate:apply",
     "migrate:check": "node bin/job-forge.mjs migrate:check",
@@ -139,6 +142,7 @@
     "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-migrate": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
+    "@razroo/iso-preflight": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"
   },

package/scripts/preflight.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import { isAbsolute, relative, resolve } from 'path';
+import {
+  formatConfigSummary,
+  formatPreflightPlan,
+  loadPreflightConfig,
+  parseJson,
+  planPreflight,
+} from '@razroo/iso-preflight';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  jobForgePreflightConfigPath,
+  planJobForgePreflight,
+  readJobForgePreflightConfig,
+} from '../lib/jobforge-preflight.mjs';
+
+const USAGE = `job-forge preflight - deterministic dispatch planning for JobForge
+
+Usage:
+  job-forge preflight:plan --candidates <file> [--workflow jobforge.apply] [--json]
+  job-forge preflight:check --candidates <file> [--workflow jobforge.apply] [--json]
+  job-forge preflight:explain [--json]
+  job-forge preflight:path
+
+Candidate files are JSON arrays, or objects with a candidates array. The policy
+is templates/preflight.json. This is local project state, not an MCP and not
+prompt context.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(configPath(opts));
+  } else if (cmd === 'plan' || cmd === 'check') {
+    runPlan(cmd, opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown preflight command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = {
+    json: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--candidates' || arg === '-c') {
+      opts.candidates = valueAfter(args, ++i, arg);
+    } else if (arg.startsWith('--candidates=')) {
+      opts.candidates = arg.slice('--candidates='.length);
+    } else if (arg === '--workflow') {
+      opts.workflow = valueAfter(args, ++i, '--workflow');
+    } else if (arg.startsWith('--workflow=')) {
+      opts.workflow = arg.slice('--workflow='.length);
+    } else if (arg === '--config') {
+      opts.config = valueAfter(args, ++i, '--config');
+    } else if (arg.startsWith('--config=')) {
+      opts.config = arg.slice('--config='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function runPlan(mode, opts) {
+  if (!opts.candidates) throw new Error(`${mode} requires --candidates <file>`);
+  const candidates = readJsonFile(resolveInputPath(opts.candidates));
+  const result = opts.config
+    ? planPreflight(readConfig(opts), candidates, { workflow: opts.workflow })
+    : planJobForgePreflight(candidates, { workflow: opts.workflow }, PROJECT_DIR);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatPreflightPlan(result, mode));
+  }
+
+  if (mode === 'check' && !result.ok) process.exit(1);
+}
+
+function explain(opts) {
+  const config = readConfig(opts);
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(configPath(opts))}`);
+  console.log(formatConfigSummary(config));
+}
+
+function readConfig(opts) {
+  if (opts.config) {
+    const path = resolveInputPath(opts.config);
+    return loadPreflightConfig(readJsonFile(path));
+  }
+  return readJobForgePreflightConfig(PROJECT_DIR);
+}
+
+function configPath(opts) {
+  return opts.config ? resolveInputPath(opts.config) : jobForgePreflightConfigPath(PROJECT_DIR);
+}
+
+function readJsonFile(path) {
+  return parseJson(readFileSync(path, 'utf8'), path);
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function resolveInputPath(path) {
+  return isAbsolute(path) ? path : resolve(PROJECT_DIR, path);
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/templates/capabilities.json

@@ -14,6 +14,7 @@
           "npx job-forge cache:*",
           "npx job-forge index:*",
           "npx job-forge canon:*",
+          "npx job-forge preflight:*",
           "rg *"
         ],
         "deny": [
@@ -37,7 +38,8 @@
           "npx job-forge merge",
           "npx job-forge guard:*",
           "npx job-forge telemetry:*",
-          "npx job-forge trace:*"
+          "npx job-forge trace:*",
+          "npx job-forge preflight:*"
         ]
       },
       "filesystem": "read-only",
@@ -62,7 +64,8 @@
           "npx job-forge capabilities:*",
           "npx job-forge cache:*",
           "npx job-forge index:*",
-          "npx job-forge canon:*"
+          "npx job-forge canon:*",
+          "npx job-forge preflight:*"
         ],
         "deny": [
           "task *"

package/templates/migrations.json

@@ -37,6 +37,9 @@
             "canon:key": "job-forge canon:key",
             "canon:compare": "job-forge canon:compare",
             "canon:explain": "job-forge canon:explain",
+            "preflight:plan": "job-forge preflight:plan",
+            "preflight:check": "job-forge preflight:check",
+            "preflight:explain": "job-forge preflight:explain",
             "migrate:plan": "job-forge migrate:plan",
             "migrate:apply": "job-forge migrate:apply",
             "migrate:check": "job-forge migrate:check",

package/templates/preflight.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "workflows": [
+    {
+      "name": "jobforge.apply",
+      "description": "Plan safe JobForge application dispatch rounds before Geometra/task work starts.",
+      "roundSize": 2,
+      "idFact": "id",
+      "conflictFact": "companyRoleKey",
+      "requiredFacts": [
+        "id",
+        "company",
+        "role",
+        "companyRoleKey",
+        "url",
+        "score"
+      ],
+      "sourceRequiredFacts": [
+        "company",
+        "role",
+        "companyRoleKey",
+        "url",
+        "score"
+      ],
+      "requireGateSources": true,
+      "gatePolicy": {
+        "skipStatuses": [
+          "skip",
+          "skipped"
+        ],
+        "blockStatuses": [
+          "block",
+          "blocked",
+          "fail",
+          "failed"
+        ]
+      },
+      "preSteps": [
+        {
+          "id": "geometra-cleanup",
+          "label": "Disconnect stale Geometra sessions before dispatch",
+          "command": "geometra_list_sessions && geometra_disconnect({ closeBrowser: true })"
+        }
+      ],
+      "postSteps": [
+        {
+          "id": "merge",
+          "label": "Merge tracker TSV outcomes",
+          "command": "npx job-forge merge"
+        },
+        {
+          "id": "verify",
+          "label": "Verify tracker integrity",
+          "command": "npx job-forge verify"
+        }
+      ]
+    }
+  ]
+}