job-forge 2.14.30 → 2.14.31

package/.cursor/rules/main.mdc

@@ -24,13 +24,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, `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.
@@ -77,6 +77,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
 
@@ -96,8 +99,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 
 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 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].

package/AGENTS.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, `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
 
@@ -91,8 +94,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 
 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 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].

package/CLAUDE.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, `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
 
@@ -91,8 +94,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 
 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 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].

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/preflight.json` defines safe dispatch rounds/gates via `@razroo/iso-preflight`, `templates/postflight.json` defines safe dispatch settlement via `@razroo/iso-postflight`, `templates/redact.json` defines safe-export redaction rules via `@razroo/iso-redact`, `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/postflight.json` defines safe dispatch settlement via `@razroo/iso-postflight`, `templates/redact.json` defines safe-export redaction rules via `@razroo/iso-redact`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `templates/facts.json` defines source-backed fact extraction via `@razroo/iso-facts`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`, and `.jobforge-facts.json` materializes queryable facts with provenance. 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 + Preflight + Postflight + Redact + 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, `job-forge postflight:*` settles dispatch outcomes/artifacts/post-steps, `job-forge redact:*` sanitizes local exports, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
+| **Trace + Telemetry + Guard + Contract + Canon + Ledger + Capabilities + Context + Cache + Index + Facts + Preflight + Postflight + Redact + 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 facts:*` materializes source-backed job/application/candidate facts, `job-forge preflight:*` plans bounded apply dispatch rounds from file-backed candidate facts, `job-forge postflight:*` settles dispatch outcomes/artifacts/post-steps, `job-forge redact:*` sanitizes local exports, 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
@@ -148,6 +148,7 @@ my-search/
 ├── .jobforge-ledger/              # append-only local workflow events (personal, gitignored)
 ├── .jobforge-cache/               # content-addressed local JD/artifact cache (personal, gitignored)
 ├── .jobforge-index.json           # deterministic artifact lookup index (generated, gitignored)
+├── .jobforge-facts.json           # deterministic fact set with provenance (generated, gitignored)
 ├── .jobforge-redacted/            # sanitized local exports (generated, gitignored)
 ├── reports/                      # generated evaluation reports (personal, gitignored)
 ├── batch/{batch-input,batch-state}.tsv, tracker-additions/, logs/   # personal
@@ -165,7 +166,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, preflight.json, postflight.json, redact.json, migrations.json
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, capabilities.json, context.json, index.json, facts.json, preflight.json, postflight.json, redact.json, migrations.json
 ├── batch/batch-prompt.md         # → batch worker prompt
 ├── batch/batch-runner.sh         # → parallel orchestrator
 │
@@ -191,7 +192,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, preflight.json, postflight.json, redact.json, migrations.json
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, capabilities.json, context.json, facts.json, preflight.json, postflight.json, redact.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 +203,7 @@ JobForge/
 │   ├── context.mjs               # iso-context-backed context bundle CLI
 │   ├── cache.mjs                 # iso-cache-backed local artifact cache CLI
 │   ├── index.mjs                 # iso-index-backed artifact lookup CLI
+│   ├── facts.mjs                 # iso-facts-backed local fact materialization
 │   ├── canon.mjs                 # iso-canon-backed identity normalization CLI
 │   ├── preflight.mjs             # iso-preflight-backed dispatch planning CLI
 │   ├── postflight.mjs            # iso-postflight-backed dispatch settlement CLI

package/bin/create-job-forge.mjs

@@ -147,6 +147,13 @@ const consumerPkg = {
     'index:has': 'job-forge index:has',
     'index:query': 'job-forge index:query',
     'index:explain': 'job-forge index:explain',
+    'facts:build': 'job-forge facts:build',
+    'facts:status': 'job-forge facts:status',
+    'facts:verify': 'job-forge facts:verify',
+    'facts:check': 'job-forge facts:check',
+    'facts:has': 'job-forge facts:has',
+    'facts:query': 'job-forge facts:query',
+    'facts:explain': 'job-forge facts:explain',
     'canon:normalize': 'job-forge canon:normalize',
     'canon:key': 'job-forge canon:key',
     'canon:compare': 'job-forge canon:compare',
@@ -262,6 +269,7 @@ Before doing any work, remember where things live in *this* project:
 | Scanner dedup history | \`data/scan-history.tsv\` | Only touch in \`/job-forge scan\` |
 | 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:*\` |
+| Local fact set | \`.jobforge-facts.json\` | Deterministic source-backed facts; use \`job-forge facts:*\` |
 | 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:*\` |
 | Dispatch postflight policy | \`templates/postflight.json\` | Safe apply settlement; use \`job-forge postflight:*\` |
@@ -356,6 +364,7 @@ data/token-usage.tsv
 .jobforge-ledger/
 .jobforge-cache/
 .jobforge-index.json
+.jobforge-facts.json
 .jobforge-runs/
 reports/
 !reports/.gitkeep
@@ -418,6 +427,7 @@ job-forge merge            # merge batch/tracker-additions/*.tsv into the tracke
 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 facts:status     # local source-backed fact status
 job-forge canon:key company-role --company "Acme, Inc." --role "Senior SWE"
 job-forge preflight:plan --candidates batch/preflight-candidates.json
 job-forge postflight:status --plan batch/preflight-plan.json --outcomes batch/postflight-outcomes.json

package/bin/job-forge.mjs

@@ -25,6 +25,7 @@
  *   context:*      Query/render deterministic context bundles via iso-context
  *   cache:*        Reuse local deterministic artifacts via iso-cache
  *   index:*        Query local artifacts via iso-index
+ *   facts:*        Materialize source-backed local facts via iso-facts
  *   canon:*        Compute deterministic identity keys via iso-canon
  *   preflight:*    Plan safe dispatch rounds via iso-preflight
  *   postflight:*   Settle dispatch outcomes via iso-postflight
@@ -132,6 +133,17 @@ const indexAliases = {
   'index:path': 'path',
 };
 
+const factsAliases = {
+  'facts:build': 'build',
+  'facts:status': 'status',
+  'facts:query': 'query',
+  'facts:has': 'has',
+  'facts:verify': 'verify',
+  'facts:check': 'check',
+  'facts:explain': 'explain',
+  'facts:path': 'path',
+};
+
 const canonAliases = {
   'canon:normalize': 'normalize',
   'canon:key': 'key',
@@ -220,6 +232,12 @@ Commands:
   index:has               Check indexed URL/company-role/report facts without loading source files
   index:query             Query indexed reports, tracker rows, TSVs, scan history, pipeline, and ledger
   index:verify            Validate local artifact index integrity
+  facts:status            Show local materialized fact set status
+  facts:build             Rebuild .jobforge-facts.json from templates/facts.json
+  facts:has               Check source-backed job/application/candidate facts
+  facts:query             Query materialized facts with source path/line provenance
+  facts:verify            Validate local fact set integrity
+  facts:check             Check configured fact requirements
   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
@@ -275,6 +293,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge cache:put --url https://example.test/jobs/123 --input @jds/example.md
   job-forge index:has --key "company-role:acme:staff-engineer"
   job-forge index:query "acme"
+  job-forge facts:has --fact application.status --key "company-role:acme:staff-engineer"
+  job-forge facts:query --fact job.url --tag report
   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
@@ -414,6 +434,21 @@ if (cmd === 'index' || indexAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'facts' || factsAliases[cmd]) {
+  const factsArgs = cmd === 'facts'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [factsAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/facts.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...factsArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 if (cmd === 'canon' || canonAliases[cmd]) {
   const canonArgs = cmd === 'canon'
     ? (rest.length === 0 ? ['help'] : rest)

package/docs/ARCHITECTURE.md

@@ -162,10 +162,12 @@ portals.yml              →  Scanner configuration
 data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/pipeline.md)
 .jobforge-ledger/events.jsonl → Append-only workflow events for cheap local duplicate/status checks
 .jobforge-index.json     →  Deterministic artifact lookup index built from templates/index.json
+.jobforge-facts.json     →  Deterministic fact set built from templates/facts.json
 jds/*.md                 →  Saved job descriptions referenced from the pipeline (`local:jds/{file}`)
 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/facts.json      →  Source-backed fact extraction policy
 templates/preflight.json  →  Safe apply dispatch rounds/gates policy
 templates/postflight.json →  Safe apply dispatch settlement policy
 templates/migrations.json → Safe consumer-project upgrade policy
@@ -182,6 +184,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 - Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`; shape enforced by `templates/contracts.json`)
 - Ledger: `.jobforge-ledger/events.jsonl` (created by `job-forge ledger:rebuild`, `tracker-line --write`, or `merge`; gitignored personal state)
 - Index: `.jobforge-index.json` (created on demand by `job-forge index:*`; gitignored local lookup state)
+- Facts: `.jobforge-facts.json` (created on demand by `job-forge facts:*`; gitignored local fact state)
 - Canon: `templates/canon.json` (identity rules inspected with `job-forge canon:*`)
 - Preflight: `templates/preflight.json` (dispatch rounds/gates inspected with `job-forge preflight:*`)
 - Postflight: `templates/postflight.json` (dispatch outcomes/artifacts/post-steps inspected with `job-forge postflight:*`)
@@ -191,7 +194,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 
 ## Pipeline Integrity
 
-From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), validates every tracker row against `templates/contracts.json`, warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. If `.jobforge-index.json` exists, verify validates the artifact index. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
+From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), validates every tracker row against `templates/contracts.json`, warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. If `.jobforge-index.json` exists, verify validates the artifact index. If `.jobforge-facts.json` exists, verify validates the materialized fact set. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
 
 **`verify-pipeline.mjs` checks (same order as the script header):**
 
@@ -206,6 +209,7 @@ From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify
 9. Warn when state ids in `templates/states.yml` drift from the script’s built-in fallback list (or when the file exists but ids failed to parse).
 10. Validate `.jobforge-ledger/events.jsonl` when present.
 11. Validate `.jobforge-index.json` when present.
+12. Validate `.jobforge-facts.json` when present.
 
 When the tracker file is missing, checks 1-6 and 8 are skipped; checks 7, 9, 10, and 11 still run when applicable.
 
@@ -231,6 +235,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@razroo/iso-guard` policy audits over local OpenCode traces |
 | `scripts/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@razroo/iso-ledger` state over tracker, TSV, and pipeline files |
 | `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/facts.mjs` | `npx job-forge facts:status` / `facts:has` / `facts:query` | Deterministic `@razroo/iso-facts` materialization over job URLs, scores, application statuses, preflight candidates, 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 |

package/docs/CUSTOMIZATION.md

@@ -154,6 +154,10 @@ Mode/reference context bundles live in `templates/context.json` and are planned
 
 Artifact lookup policy lives in `templates/index.json` and is built locally by `@razroo/iso-index`. Use `job-forge index:has --key "company-role:acme:staff-engineer"` as a cheap duplicate/source prefilter, `job-forge index:query "acme"` to get compact source path/line pointers, and `job-forge index:verify` to validate `.jobforge-index.json`. Query, has, and verify rebuild the index on demand, so scaffolded projects need no setup. JobForge canonicalizes company/role and URL records through `templates/canon.json` before writing the index. This is not an MCP and does not add tool-schema tokens.
 
+## JobForge materialized facts
+
+Fact extraction policy lives in `templates/facts.json` and is built locally by `@razroo/iso-facts`. Use `job-forge facts:query --fact job.url`, `job-forge facts:has --fact application.status --key "company-role:acme:staff-engineer"`, and `job-forge facts:verify` to work with compact source-backed facts instead of rereading reports, tracker day files, TSVs, candidate JSON, scan history, and ledger events. Query, has, verify, and check rebuild `.jobforge-facts.json` on demand, so scaffolded projects need no setup. JobForge canonicalizes company/role and URL fact keys through `templates/canon.json` before writing the fact set. This is not an MCP and does not add prompt or tool-schema tokens.
+
 ## JobForge identity canonicalization
 
 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.

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`, `preflight`, `postflight`, `redact`, `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`, `index`, `facts`, `preflight`, `postflight`, `redact`, `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,7 @@ 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` |
+| Inspect local materialized facts | `npx job-forge facts:status` | `npm run facts: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 ...` |
 | Settle dispatch outcomes after a round | `npx job-forge postflight:status --plan batch/preflight-plan.json --outcomes batch/postflight-outcomes.json` | `npm run postflight:status -- --plan ... --outcomes ...` |
@@ -157,6 +158,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Check duplicate/status event without loading tracker files | `npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied` | `npm run ledger:has -- --company ...` |
 | Check/reuse cached JD content | `npx job-forge cache:has --url <url>` / `npx job-forge cache:get --url <url>` | `npm run cache:has -- --url ...` |
 | Query local artifact pointers | `npx job-forge index:query "Acme"` / `npx job-forge index:has --key company-role:acme:staff-engineer` | `npm run index:query -- Acme` |
+| Query local source-backed facts | `npx job-forge facts:query --fact job.url` / `npx job-forge facts:has --fact application.status --key company-role:acme:staff-engineer` | `npm run facts:query -- --fact job.url` |
 | Apply safe consumer migrations | `npx job-forge migrate:apply` | `npm run migrate:apply` |
 | Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
 | Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |

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, `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
 
@@ -91,8 +94,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 
 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 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].

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

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.30",
+  "version": "2.14.31",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -55,6 +55,13 @@
     "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",
     "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 +151,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",

package/scripts/facts.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatBuildResult,
+  formatCheckResult,
+  formatConfigSummary,
+  formatFacts,
+  formatVerifyResult,
+} from '@razroo/iso-facts';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  buildJobForgeFacts,
+  checkJobForgeFacts,
+  factsExist,
+  hasJobForgeFact,
+  jobForgeFactsConfigPath,
+  jobForgeFactsPath,
+  jobForgeFactsSummary,
+  queryJobForgeFacts,
+  readJobForgeFactsConfig,
+  verifyJobForgeFacts,
+} from '../lib/jobforge-facts.mjs';
+
+const USAGE = `job-forge facts - local deterministic fact materialization
+
+Usage:
+  job-forge facts:status [--json]
+  job-forge facts:build [--json]
+  job-forge facts:query [text] [--fact <fact>] [--key <key>] [--value <value>] [--source <path>] [--tag <tag>] [--limit N] [--no-rebuild] [--json]
+  job-forge facts:has [text] [--fact <fact>] [--key <key>] [--value <value>] [--source <path>] [--tag <tag>] [--no-rebuild] [--json]
+  job-forge facts:verify [--no-rebuild] [--json]
+  job-forge facts:check [--no-rebuild] [--json]
+  job-forge facts:explain [--json]
+  job-forge facts:path
+
+Default config is templates/facts.json. Default output is .jobforge-facts.json.
+Query, has, verify, and check rebuild facts by default so consumer projects need
+no manual setup. Use --no-rebuild to inspect the existing fact set only.`;
+
+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(jobForgeFactsPath(PROJECT_DIR));
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'build') {
+    build(opts);
+  } else if (cmd === 'query') {
+    query(opts);
+  } else if (cmd === 'has') {
+    has(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'check') {
+    check(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown facts 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,
+    rebuild: true,
+    query: {},
+    text: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--no-rebuild') {
+      opts.rebuild = false;
+    } else if (arg === '--rebuild') {
+      opts.rebuild = true;
+    } else if (arg === '--fact') {
+      opts.query.fact = valueAfter(args, ++i, '--fact');
+    } else if (arg.startsWith('--fact=')) {
+      opts.query.fact = arg.slice('--fact='.length);
+    } else if (arg === '--key') {
+      opts.query.key = valueAfter(args, ++i, '--key');
+    } else if (arg.startsWith('--key=')) {
+      opts.query.key = arg.slice('--key='.length);
+    } else if (arg === '--value') {
+      opts.query.value = valueAfter(args, ++i, '--value');
+    } else if (arg.startsWith('--value=')) {
+      opts.query.value = arg.slice('--value='.length);
+    } else if (arg === '--source') {
+      opts.query.source = valueAfter(args, ++i, '--source');
+    } else if (arg.startsWith('--source=')) {
+      opts.query.source = arg.slice('--source='.length);
+    } else if (arg === '--tag') {
+      opts.query.tag = valueAfter(args, ++i, '--tag');
+    } else if (arg.startsWith('--tag=')) {
+      opts.query.tag = arg.slice('--tag='.length);
+    } else if (arg === '--limit') {
+      opts.query.limit = parsePositiveInteger(valueAfter(args, ++i, '--limit'), '--limit');
+    } else if (arg.startsWith('--limit=')) {
+      opts.query.limit = parsePositiveInteger(arg.slice('--limit='.length), '--limit');
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown flag "${arg}"`);
+    } else {
+      opts.text.push(arg);
+    }
+  }
+
+  if (opts.text.length > 0) opts.query.text = opts.text.join(' ');
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parsePositiveInteger(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+  return parsed;
+}
+
+function status(opts) {
+  const summary = jobForgeFactsSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  if (!summary.exists) {
+    console.log(`facts: missing (${relativePath(summary.path)})`);
+    console.log('run: job-forge facts:build');
+    return;
+  }
+  const result = verifyJobForgeFacts({ rebuild: false }, PROJECT_DIR);
+  console.log(`facts:   ${relativePath(summary.path)}`);
+  console.log(`config:  ${relativePath(summary.config)}`);
+  console.log(`sources: ${summary.sources}`);
+  console.log(`files:   ${summary.files}`);
+  console.log(`facts:   ${summary.facts}`);
+  console.log(`verify:  ${result.ok ? 'PASS' : 'FAIL'} (${result.issues.length} issue(s))`);
+}
+
+function build(opts) {
+  const { factSet, out } = buildJobForgeFacts({}, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify({ out, stats: factSet.stats }, null, 2));
+    return;
+  }
+  console.log(formatBuildResult(factSet, out));
+}
+
+function query(opts) {
+  const facts = queryJobForgeFacts(opts.query, { rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(facts, null, 2));
+    return;
+  }
+  console.log(formatFacts(facts));
+}
+
+function has(opts) {
+  const hit = hasJobForgeFact(opts.query, { rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify({ hit, query: opts.query }, null, 2));
+  } else {
+    console.log(hit ? 'MATCH' : 'MISS');
+  }
+  process.exit(hit ? 0 : 1);
+}
+
+function verify(opts) {
+  if (!opts.rebuild && !factsExist(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeFactsPath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`facts: missing (${relativePath(jobForgeFactsPath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = verifyJobForgeFacts({ rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function check(opts) {
+  if (!opts.rebuild && !factsExist(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeFactsPath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`facts: missing (${relativePath(jobForgeFactsPath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = checkJobForgeFacts({ rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatCheckResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function explain(opts) {
+  const config = readJobForgeFactsConfig(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeFactsConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary(config));
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/templates/facts.json

@@ -0,0 +1,200 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "name": "reports",
+      "include": ["reports/*.md"],
+      "format": "text",
+      "rules": [
+        {
+          "fact": "job.url",
+          "pattern": "^\\*\\*URL:\\*\\*\\s*(?<url>https?://\\S+)",
+          "flags": "i",
+          "key": "url:{url}",
+          "value": "{url}",
+          "fields": {
+            "url": "{url}",
+            "report": "{source}"
+          },
+          "tags": ["report", "url"]
+        },
+        {
+          "fact": "job.score",
+          "pattern": "^\\*\\*Score:\\*\\*\\s*(?<score>[0-9.]+/5)",
+          "flags": "i",
+          "key": "report:{source}:score",
+          "value": "{score}",
+          "fields": {
+            "score": "{score}",
+            "report": "{source}"
+          },
+          "tags": ["report", "score"]
+        }
+      ]
+    },
+    {
+      "name": "application-day-files",
+      "include": ["data/applications/*.md"],
+      "format": "markdown-table",
+      "records": [
+        {
+          "fact": "application.status",
+          "key": "company-role:{Company|slug}:{Role|slug}",
+          "value": "{Status}",
+          "fields": {
+            "num": "{#}",
+            "date": "{Date}",
+            "company": "{Company}",
+            "role": "{Role}",
+            "score": "{Score}",
+            "status": "{Status}",
+            "pdf": "{PDF}",
+            "report": "{Report}",
+            "notes": "{Notes}"
+          },
+          "tags": ["tracker", "application"]
+        }
+      ]
+    },
+    {
+      "name": "application-single-file",
+      "include": ["data/applications.md", "applications.md"],
+      "format": "markdown-table",
+      "records": [
+        {
+          "fact": "application.status",
+          "key": "company-role:{Company|slug}:{Role|slug}",
+          "value": "{Status}",
+          "fields": {
+            "num": "{#}",
+            "date": "{Date}",
+            "company": "{Company}",
+            "role": "{Role}",
+            "score": "{Score}",
+            "status": "{Status}",
+            "pdf": "{PDF}",
+            "report": "{Report}",
+            "notes": "{Notes}"
+          },
+          "tags": ["tracker", "application"]
+        }
+      ]
+    },
+    {
+      "name": "tracker-additions",
+      "include": ["batch/tracker-additions/*.tsv", "batch/tracker-additions/merged/*.tsv"],
+      "format": "tsv",
+      "header": false,
+      "columns": ["num", "date", "company", "role", "statusOrScore", "scoreOrStatus", "pdf", "report", "notes"],
+      "records": [
+        {
+          "fact": "tracker.addition",
+          "key": "company-role:{company|slug}:{role|slug}",
+          "value": "{source}",
+          "fields": ["num", "date", "company", "role", "statusOrScore", "scoreOrStatus", "pdf", "report", "notes"],
+          "tags": ["tracker", "tsv"]
+        }
+      ]
+    },
+    {
+      "name": "pipeline",
+      "include": ["data/pipeline.md"],
+      "format": "text",
+      "rules": [
+        {
+          "fact": "job.url",
+          "pattern": "^\\s*-\\s*\\[(?<state>[ xX])\\]\\s+(?<url>https?://\\S+)",
+          "key": "url:{url}",
+          "value": "{state}",
+          "fields": {
+            "url": "{url}",
+            "state": "{state}",
+            "pipeline": "{source}"
+          },
+          "tags": ["pipeline", "url"]
+        }
+      ]
+    },
+    {
+      "name": "scan-history",
+      "include": ["data/scan-history.tsv"],
+      "format": "tsv",
+      "records": [
+        {
+          "fact": "job.url",
+          "key": "url:{url}",
+          "value": "{url}",
+          "fields": ["date", "company", "role", "url", "ats"],
+          "tags": ["scan", "url"]
+        }
+      ]
+    },
+    {
+      "name": "preflight-candidates-object",
+      "include": ["batch/preflight-candidates.json"],
+      "format": "json",
+      "records": [
+        {
+          "fact": "candidate.ready",
+          "path": "$.candidates[]",
+          "key": "{companyRoleKey}",
+          "value": "{url}",
+          "fields": {
+            "id": "{id}",
+            "company": "{company}",
+            "role": "{role}",
+            "companyRoleKey": "{companyRoleKey}",
+            "url": "{url}",
+            "score": "{score}",
+            "gateStatus": "{gate.status}",
+            "locationStatus": "{location.status}"
+          },
+          "tags": ["candidate", "preflight"]
+        }
+      ]
+    },
+    {
+      "name": "preflight-candidates-array",
+      "include": ["batch/preflight-candidates.json"],
+      "format": "json",
+      "records": [
+        {
+          "fact": "candidate.ready",
+          "path": "$[]",
+          "key": "{companyRoleKey}",
+          "value": "{url}",
+          "fields": {
+            "id": "{id}",
+            "company": "{company}",
+            "role": "{role}",
+            "companyRoleKey": "{companyRoleKey}",
+            "url": "{url}",
+            "score": "{score}",
+            "gateStatus": "{gate.status}",
+            "locationStatus": "{location.status}"
+          },
+          "tags": ["candidate", "preflight"]
+        }
+      ]
+    },
+    {
+      "name": "ledger",
+      "include": [".jobforge-ledger/*.jsonl"],
+      "format": "jsonl",
+      "records": [
+        {
+          "fact": "ledger.event",
+          "key": "{key}",
+          "value": "{type}",
+          "fields": {
+            "type": "{type}",
+            "key": "{key}",
+            "status": "{data.status}",
+            "source": "{source}"
+          },
+          "tags": ["ledger"]
+        }
+      ]
+    }
+  ]
+}

package/templates/migrations.json

@@ -33,6 +33,13 @@
             "index:has": "job-forge index:has",
             "index:query": "job-forge index:query",
             "index:explain": "job-forge index:explain",
+            "facts:build": "job-forge facts:build",
+            "facts:status": "job-forge facts:status",
+            "facts:verify": "job-forge facts:verify",
+            "facts:check": "job-forge facts:check",
+            "facts:has": "job-forge facts:has",
+            "facts:query": "job-forge facts:query",
+            "facts:explain": "job-forge facts:explain",
             "canon:normalize": "job-forge canon:normalize",
             "canon:key": "job-forge canon:key",
             "canon:compare": "job-forge canon:compare",
@@ -69,6 +76,7 @@
             ".jobforge-ledger/",
             ".jobforge-cache/",
             ".jobforge-index.json",
+            ".jobforge-facts.json",
             ".jobforge-redacted/",
             "batch/preflight-candidates.json",
             "batch/preflight-plan.json",

package/verify-pipeline.mjs

@@ -18,6 +18,7 @@
  * 9. Drift warning if states.yml ids differ from the built-in fallback list
  * 10. Ledger file verifies if .jobforge-ledger/events.jsonl exists
  * 11. Artifact index verifies if .jobforge-index.json exists
+ * 12. Fact set verifies if .jobforge-facts.json exists
  *
  * Run: node verify-pipeline.mjs   (from repo root; same as npm run verify)
  */
@@ -31,6 +32,7 @@ import {
 } from './tracker-lib.mjs';
 import { jobForgeLedgerPath, ledgerExists, verifyJobForgeLedger } from './lib/jobforge-ledger.mjs';
 import { indexExists, jobForgeIndexPath, verifyJobForgeIndex } from './lib/jobforge-index.mjs';
+import { factsExist, jobForgeFactsPath, verifyJobForgeFacts } from './lib/jobforge-facts.mjs';
 import {
   canonicalStatusValues,
   formatContractIssues,
@@ -171,6 +173,22 @@ function verifyIndexIfPresent() {
   }
 }
 
+function verifyFactsIfPresent() {
+  if (!factsExist(PROJECT_DIR)) {
+    ok('Fact set not initialized');
+    return;
+  }
+  const result = verifyJobForgeFacts({ rebuild: false }, PROJECT_DIR);
+  for (const issue of result.issues) {
+    const msg = `facts: ${issue.kind}: ${issue.message}`;
+    if (issue.severity === 'error') error(msg);
+    else warn(msg);
+  }
+  if (result.ok) {
+    ok(`Fact set valid (${result.facts} facts at ${relative(PROJECT_DIR, jobForgeFactsPath(PROJECT_DIR))})`);
+  }
+}
+
 // --- Read entries ---
 const { entries, source } = readAllEntries();
 
@@ -181,6 +199,7 @@ if (entries.length === 0) {
   verifyStatesYamlDrift();
   verifyLedgerIfPresent();
   verifyIndexIfPresent();
+  verifyFactsIfPresent();
   console.log('\n' + '='.repeat(50));
   console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);
   if (errors === 0 && warnings === 0) console.log('🟢 Pipeline is clean!');
@@ -317,6 +336,7 @@ if (boldScores === 0) ok('No bold in scores');
 verifyStatesYamlDrift();
 verifyLedgerIfPresent();
 verifyIndexIfPresent();
+verifyFactsIfPresent();
 
 console.log('\n' + '='.repeat(50));
 console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);