job-forge 2.0.1 → 2.0.3

package/.cursor/rules/main.mdc

@@ -14,9 +14,19 @@ The Hard Limits below are non-negotiable numeric rules. If you catch yourself ab
 3. **Always clean Geometra sessions before dispatching.** Before every round of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round. The disconnect is a no-op when the pool is empty.
 4. **Orchestrator does NOT fill forms.** This session MUST NOT call `geometra_fill_form`, `geometra_run_actions`, `geometra_pick_listbox_option`, or `geometra_fill_otp` when handling a multi-job request. If you need to, it means you MUST have delegated — `task` out the remaining work instead.
 5. **Re-dispatch only AFTER the previous subagent returns.** Never fire the same company's `task` twice while the first is still in-flight. Wait for the return value, then decide if a retry is warranted.
-6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `node merge-tracker.mjs` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `node merge-tracker.mjs` followed by `node verify-pipeline.mjs` before ending the session.
+6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `npx job-forge merge` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` followed by `npx job-forge verify` before ending the session.
+7. **Load-bearing facts passed to downstream subagents must come from a file, not from a prior subagent's prose.** A URL, score, email ID, confirmation page snippet, JD salary range, exact answer submitted to a form question, or any other specific value that a downstream subagent will act on MUST originate from one of:
+   - `data/pipeline.md` (URL inbox state)
+   - `data/scan-history.tsv` (scan provenance)
+   - `batch/scan-output-*.md` (scan-ranked candidates)
+   - A report file (`reports/{num}-*.md`) with authoritative headers (`**URL:**`, `**Score:**`, etc.)
+   - A TSV in `batch/tracker-additions/` (per-apply outcomes)
 
-Everything below is context and rationale. These six numbers are the rules.
+   **Not trustworthy by default**: anything quoted from a subagent's return message, any ID or score the orchestrator "remembers" from prose, any page-content snippet reproduced from a subagent's narrative. Subagents can hallucinate plausible-looking IDs, scores, and confirmation text. Before passing any such fact to another subagent, cross-check it exists in one of the authoritative files above, OR instruct the dispatching subagent to write its output to a structured file and re-read from that file.
+
+   **Why**: on 2026-04-18, a scan subagent returned 30 fabricated Greenhouse IDs in prose (correct role titles, plausible-looking invented IDs that didn't exist in the API). The orchestrator dispatched 30 downstream subagents that all hit 404s. Verification rules downstream (Hard Limit #6, API-first verify) caught the symptom. This rule prevents the *shape* of the bug — hallucinations propagating through prose handoffs — across all quantitative / identifier / specific-fact claims, not just URLs.
+
+Everything below is context and rationale. These seven numbers are the rules.
 
 ---
 
@@ -36,6 +46,8 @@ Whenever the user says any variation of "apply to N jobs", "process the pipeline
 
 **Exception:** evaluation-only or tracker-only work (no Geometra, no repeated tool calls) can proceed in a single session. The rule targets tool-heavy multi-step loops.
 
+**Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md`** to exclude location-incompatible candidates. Catches the common case where an evaluated role has the right role-shape but a deal-breaking location that profile.yml already rules out.
+
 ---
 
 ## Subagent Routing — which agent for which task
@@ -462,7 +474,7 @@ To check or modify MCP settings, edit `opencode.json` in the project root.
 - JDs in `jds/` (referenced as `local:jds/{file}` in pipeline.md)
 - Batch in `batch/` (gitignored except scripts and prompt)
 - Report numbering: sequential 3-digit zero-padded, max existing + 1
-- **RULE: After each batch of evaluations, run `node merge-tracker.mjs`** to merge tracker additions and avoid duplications.
+- **RULE: After each batch of evaluations, run `npx job-forge merge`** to merge tracker additions and avoid duplications.
 - **RULE: NEVER create new entries in applications.md if company+role already exists.** Update the existing entry.
 - **RULE: NEVER attribute commits to opencode (no `Co-Authored-By: opencode` or similar).** All commits must be attributed solely to the person making the commit (e.g., CharlieGreenman).
 
@@ -489,13 +501,13 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 
 ### Pipeline Integrity
 
-1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `merge-tracker.mjs` handles the merge.
+1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `npx job-forge merge` handles the merge.
 2. **YES you can edit day files in `data/applications/` to UPDATE status/notes of existing entries.**
 3. All reports MUST include `**URL:**` in the header (between Score and PDF).
 4. All statuses MUST be canonical (see `templates/states.yml`).
-5. Health check: `node verify-pipeline.mjs`
-6. Normalize statuses: `node normalize-statuses.mjs`
-7. Dedup: `node dedup-tracker.mjs`
+5. Health check: `npx job-forge verify`
+6. Normalize statuses: `npx job-forge normalize`
+7. Dedup: `npx job-forge dedup`
 
 ### Canonical States (applications day files)
 
@@ -511,6 +523,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 | `Offer` | Offer received |
 | `Rejected` | Rejected by company |
 | `Discarded` | Discarded by candidate or offer closed |
+| `Failed` | Submission attempted but blocked by portal (spam-filter, anti-bot, broken form). May be recoverable via manual retry. |
 | `SKIP` | Doesn't fit, don't apply |
 
 **RULES:**

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

@@ -163,8 +163,8 @@ Step 5  — Between rounds: clean sessions again
   - geometra_disconnect({ closeBrowser: true })
 
 Step 6  — After all rounds: reconcile outcomes (Hard Limit #6)
-  - bash: node merge-tracker.mjs      # consumes batch/tracker-additions/*.tsv into the day file
-  - bash: node verify-pipeline.mjs    # validates URL/status consistency
+  - bash: npx job-forge merge      # consumes batch/tracker-additions/*.tsv into the day file
+  - bash: npx job-forge verify     # validates URL/status consistency
   - Review output; if verify-pipeline reports issues, fix them before ending.
 
 Step 7  — Aggregate and report

package/AGENTS.md

@@ -9,9 +9,19 @@ The Hard Limits below are non-negotiable numeric rules. If you catch yourself ab
 3. **Always clean Geometra sessions before dispatching.** Before every round of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round. The disconnect is a no-op when the pool is empty.
 4. **Orchestrator does NOT fill forms.** This session MUST NOT call `geometra_fill_form`, `geometra_run_actions`, `geometra_pick_listbox_option`, or `geometra_fill_otp` when handling a multi-job request. If you need to, it means you MUST have delegated — `task` out the remaining work instead.
 5. **Re-dispatch only AFTER the previous subagent returns.** Never fire the same company's `task` twice while the first is still in-flight. Wait for the return value, then decide if a retry is warranted.
-6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `node merge-tracker.mjs` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `node merge-tracker.mjs` followed by `node verify-pipeline.mjs` before ending the session.
+6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `npx job-forge merge` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` followed by `npx job-forge verify` before ending the session.
+7. **Load-bearing facts passed to downstream subagents must come from a file, not from a prior subagent's prose.** A URL, score, email ID, confirmation page snippet, JD salary range, exact answer submitted to a form question, or any other specific value that a downstream subagent will act on MUST originate from one of:
+   - `data/pipeline.md` (URL inbox state)
+   - `data/scan-history.tsv` (scan provenance)
+   - `batch/scan-output-*.md` (scan-ranked candidates)
+   - A report file (`reports/{num}-*.md`) with authoritative headers (`**URL:**`, `**Score:**`, etc.)
+   - A TSV in `batch/tracker-additions/` (per-apply outcomes)
 
-Everything below is context and rationale. These six numbers are the rules.
+   **Not trustworthy by default**: anything quoted from a subagent's return message, any ID or score the orchestrator "remembers" from prose, any page-content snippet reproduced from a subagent's narrative. Subagents can hallucinate plausible-looking IDs, scores, and confirmation text. Before passing any such fact to another subagent, cross-check it exists in one of the authoritative files above, OR instruct the dispatching subagent to write its output to a structured file and re-read from that file.
+
+   **Why**: on 2026-04-18, a scan subagent returned 30 fabricated Greenhouse IDs in prose (correct role titles, plausible-looking invented IDs that didn't exist in the API). The orchestrator dispatched 30 downstream subagents that all hit 404s. Verification rules downstream (Hard Limit #6, API-first verify) caught the symptom. This rule prevents the *shape* of the bug — hallucinations propagating through prose handoffs — across all quantitative / identifier / specific-fact claims, not just URLs.
+
+Everything below is context and rationale. These seven numbers are the rules.
 
 ---
 
@@ -31,6 +41,8 @@ Whenever the user says any variation of "apply to N jobs", "process the pipeline
 
 **Exception:** evaluation-only or tracker-only work (no Geometra, no repeated tool calls) can proceed in a single session. The rule targets tool-heavy multi-step loops.
 
+**Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md`** to exclude location-incompatible candidates. Catches the common case where an evaluated role has the right role-shape but a deal-breaking location that profile.yml already rules out.
+
 ---
 
 ## Subagent Routing — which agent for which task
@@ -457,7 +469,7 @@ To check or modify MCP settings, edit `opencode.json` in the project root.
 - JDs in `jds/` (referenced as `local:jds/{file}` in pipeline.md)
 - Batch in `batch/` (gitignored except scripts and prompt)
 - Report numbering: sequential 3-digit zero-padded, max existing + 1
-- **RULE: After each batch of evaluations, run `node merge-tracker.mjs`** to merge tracker additions and avoid duplications.
+- **RULE: After each batch of evaluations, run `npx job-forge merge`** to merge tracker additions and avoid duplications.
 - **RULE: NEVER create new entries in applications.md if company+role already exists.** Update the existing entry.
 - **RULE: NEVER attribute commits to opencode (no `Co-Authored-By: opencode` or similar).** All commits must be attributed solely to the person making the commit (e.g., CharlieGreenman).
 
@@ -484,13 +496,13 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 
 ### Pipeline Integrity
 
-1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `merge-tracker.mjs` handles the merge.
+1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `npx job-forge merge` handles the merge.
 2. **YES you can edit day files in `data/applications/` to UPDATE status/notes of existing entries.**
 3. All reports MUST include `**URL:**` in the header (between Score and PDF).
 4. All statuses MUST be canonical (see `templates/states.yml`).
-5. Health check: `node verify-pipeline.mjs`
-6. Normalize statuses: `node normalize-statuses.mjs`
-7. Dedup: `node dedup-tracker.mjs`
+5. Health check: `npx job-forge verify`
+6. Normalize statuses: `npx job-forge normalize`
+7. Dedup: `npx job-forge dedup`
 
 ### Canonical States (applications day files)
 
@@ -506,6 +518,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 | `Offer` | Offer received |
 | `Rejected` | Rejected by company |
 | `Discarded` | Discarded by candidate or offer closed |
+| `Failed` | Submission attempted but blocked by portal (spam-filter, anti-bot, broken form). May be recoverable via manual retry. |
 | `SKIP` | Doesn't fit, don't apply |
 
 **RULES:**

package/CLAUDE.md

@@ -9,9 +9,19 @@ The Hard Limits below are non-negotiable numeric rules. If you catch yourself ab
 3. **Always clean Geometra sessions before dispatching.** Before every round of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round. The disconnect is a no-op when the pool is empty.
 4. **Orchestrator does NOT fill forms.** This session MUST NOT call `geometra_fill_form`, `geometra_run_actions`, `geometra_pick_listbox_option`, or `geometra_fill_otp` when handling a multi-job request. If you need to, it means you MUST have delegated — `task` out the remaining work instead.
 5. **Re-dispatch only AFTER the previous subagent returns.** Never fire the same company's `task` twice while the first is still in-flight. Wait for the return value, then decide if a retry is warranted.
-6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `node merge-tracker.mjs` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `node merge-tracker.mjs` followed by `node verify-pipeline.mjs` before ending the session.
+6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `npx job-forge merge` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` followed by `npx job-forge verify` before ending the session.
+7. **Load-bearing facts passed to downstream subagents must come from a file, not from a prior subagent's prose.** A URL, score, email ID, confirmation page snippet, JD salary range, exact answer submitted to a form question, or any other specific value that a downstream subagent will act on MUST originate from one of:
+   - `data/pipeline.md` (URL inbox state)
+   - `data/scan-history.tsv` (scan provenance)
+   - `batch/scan-output-*.md` (scan-ranked candidates)
+   - A report file (`reports/{num}-*.md`) with authoritative headers (`**URL:**`, `**Score:**`, etc.)
+   - A TSV in `batch/tracker-additions/` (per-apply outcomes)
 
-Everything below is context and rationale. These six numbers are the rules.
+   **Not trustworthy by default**: anything quoted from a subagent's return message, any ID or score the orchestrator "remembers" from prose, any page-content snippet reproduced from a subagent's narrative. Subagents can hallucinate plausible-looking IDs, scores, and confirmation text. Before passing any such fact to another subagent, cross-check it exists in one of the authoritative files above, OR instruct the dispatching subagent to write its output to a structured file and re-read from that file.
+
+   **Why**: on 2026-04-18, a scan subagent returned 30 fabricated Greenhouse IDs in prose (correct role titles, plausible-looking invented IDs that didn't exist in the API). The orchestrator dispatched 30 downstream subagents that all hit 404s. Verification rules downstream (Hard Limit #6, API-first verify) caught the symptom. This rule prevents the *shape* of the bug — hallucinations propagating through prose handoffs — across all quantitative / identifier / specific-fact claims, not just URLs.
+
+Everything below is context and rationale. These seven numbers are the rules.
 
 ---
 
@@ -31,6 +41,8 @@ Whenever the user says any variation of "apply to N jobs", "process the pipeline
 
 **Exception:** evaluation-only or tracker-only work (no Geometra, no repeated tool calls) can proceed in a single session. The rule targets tool-heavy multi-step loops.
 
+**Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md`** to exclude location-incompatible candidates. Catches the common case where an evaluated role has the right role-shape but a deal-breaking location that profile.yml already rules out.
+
 ---
 
 ## Subagent Routing — which agent for which task
@@ -457,7 +469,7 @@ To check or modify MCP settings, edit `opencode.json` in the project root.
 - JDs in `jds/` (referenced as `local:jds/{file}` in pipeline.md)
 - Batch in `batch/` (gitignored except scripts and prompt)
 - Report numbering: sequential 3-digit zero-padded, max existing + 1
-- **RULE: After each batch of evaluations, run `node merge-tracker.mjs`** to merge tracker additions and avoid duplications.
+- **RULE: After each batch of evaluations, run `npx job-forge merge`** to merge tracker additions and avoid duplications.
 - **RULE: NEVER create new entries in applications.md if company+role already exists.** Update the existing entry.
 - **RULE: NEVER attribute commits to opencode (no `Co-Authored-By: opencode` or similar).** All commits must be attributed solely to the person making the commit (e.g., CharlieGreenman).
 
@@ -484,13 +496,13 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 
 ### Pipeline Integrity
 
-1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `merge-tracker.mjs` handles the merge.
+1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `npx job-forge merge` handles the merge.
 2. **YES you can edit day files in `data/applications/` to UPDATE status/notes of existing entries.**
 3. All reports MUST include `**URL:**` in the header (between Score and PDF).
 4. All statuses MUST be canonical (see `templates/states.yml`).
-5. Health check: `node verify-pipeline.mjs`
-6. Normalize statuses: `node normalize-statuses.mjs`
-7. Dedup: `node dedup-tracker.mjs`
+5. Health check: `npx job-forge verify`
+6. Normalize statuses: `npx job-forge normalize`
+7. Dedup: `npx job-forge dedup`
 
 ### Canonical States (applications day files)
 
@@ -506,6 +518,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 | `Offer` | Offer received |
 | `Rejected` | Rejected by company |
 | `Discarded` | Discarded by candidate or offer closed |
+| `Failed` | Submission attempted but blocked by portal (spam-filter, anti-bot, broken form). May be recoverable via manual retry. |
 | `SKIP` | Doesn't fit, don't apply |
 
 **RULES:**

package/batch/README.md

@@ -51,7 +51,7 @@ npm run merge
 npm run verify   # optional: pipeline health after merge (report links, statuses, pending TSVs)
 ```
 
-(`node merge-tracker.mjs` — same as `npm run merge`; see [CONTRIBUTING.md](../CONTRIBUTING.md#development).)
+(`npx job-forge merge` — same as `npm run merge`; see [CONTRIBUTING.md](../CONTRIBUTING.md#development).)
 
 After a successful merge, each processed file is moved to **`batch/tracker-additions/merged/`** (created on first merge when the directory does not yet exist). `npm run verify` only looks for `*.tsv` files in the **top level** of `batch/tracker-additions/`, so rows already merged and archived under `merged/` do not trigger the “pending TSVs” warning.
 

package/batch/batch-prompt.md

@@ -243,7 +243,7 @@ Where `{company-slug}` is the company name in lowercase, no spaces, with hyphens
 12. Write HTML to `/tmp/cv-candidate-{company-slug}.html`
 13. Run:
 ```bash
-node generate-pdf.mjs \
+npx job-forge pdf \
   /tmp/cv-candidate-{company-slug}.html \
   output/cv-candidate-{company-slug}-{{DATE}}.pdf \
   --format={letter|a4}

package/config/profile.example.yml

@@ -65,3 +65,24 @@ location:
   visa_status: "No sponsorship needed"
   # For remote roles outside your country:
   # onsite_availability: "1 week/month in any city"
+
+# Structured location constraints — consumed by the Apply Preflight location
+# filter in modes/apply.md. The prose fields above (compensation.location_flexibility,
+# location.*) remain for human readability and LLM narrative context; the fields
+# below govern automated, deterministic compatibility checks before dispatching
+# an apply subagent.
+#
+# City names are lowercase, hyphenated (e.g. "san-francisco", "new-york").
+# Country codes are ISO-3166 alpha-2 uppercase (e.g. "US", "CA", "GB").
+location_constraints:
+  remote_us: true                      # open to US-remote roles
+  remote_global: false                 # open to non-US remote (visa / timezone permitting)
+  hybrid_cities:                       # cities where hybrid N-days-in-office is acceptable
+    - san-francisco
+  blocked_cities:                      # cities that are a hard No for relocation (even if hybrid)
+    - new-york
+    - london
+  authorized_countries:                # countries where the candidate has right-to-work
+    - US
+  requires_visa_sponsorship: false     # true → roles in non-authorized countries are blocked unless
+                                       # the JD explicitly mentions visa sponsorship

package/iso/commands/job-forge.md

@@ -166,8 +166,8 @@ Step 5  — Between rounds: clean sessions again
   - geometra_disconnect({ closeBrowser: true })
 
 Step 6  — After all rounds: reconcile outcomes (Hard Limit #6)
-  - bash: node merge-tracker.mjs      # consumes batch/tracker-additions/*.tsv into the day file
-  - bash: node verify-pipeline.mjs    # validates URL/status consistency
+  - bash: npx job-forge merge      # consumes batch/tracker-additions/*.tsv into the day file
+  - bash: npx job-forge verify     # validates URL/status consistency
   - Review output; if verify-pipeline reports issues, fix them before ending.
 
 Step 7  — Aggregate and report

package/iso/instructions.md

@@ -9,9 +9,19 @@ The Hard Limits below are non-negotiable numeric rules. If you catch yourself ab
 3. **Always clean Geometra sessions before dispatching.** Before every round of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round. The disconnect is a no-op when the pool is empty.
 4. **Orchestrator does NOT fill forms.** This session MUST NOT call `geometra_fill_form`, `geometra_run_actions`, `geometra_pick_listbox_option`, or `geometra_fill_otp` when handling a multi-job request. If you need to, it means you MUST have delegated — `task` out the remaining work instead.
 5. **Re-dispatch only AFTER the previous subagent returns.** Never fire the same company's `task` twice while the first is still in-flight. Wait for the return value, then decide if a retry is warranted.
-6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `node merge-tracker.mjs` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `node merge-tracker.mjs` followed by `node verify-pipeline.mjs` before ending the session.
+6. **Application outcomes flow through TSVs, not `data/pipeline.md`.** When a subagent returns APPLIED / FAILED / SKIP, the outcome goes to `batch/tracker-additions/{num}-{slug}.tsv`. `npx job-forge merge` then consumes the TSVs into the correct `data/applications/YYYY-MM-DD.md` day file. `data/pipeline.md` only tracks URL inbox state (`[ ]` pending → `[x]` processed). **NEVER append APPLIED / FAILED status lines to `pipeline.md`** — that's the day file's job, via the TSV pathway. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` followed by `npx job-forge verify` before ending the session.
+7. **Load-bearing facts passed to downstream subagents must come from a file, not from a prior subagent's prose.** A URL, score, email ID, confirmation page snippet, JD salary range, exact answer submitted to a form question, or any other specific value that a downstream subagent will act on MUST originate from one of:
+   - `data/pipeline.md` (URL inbox state)
+   - `data/scan-history.tsv` (scan provenance)
+   - `batch/scan-output-*.md` (scan-ranked candidates)
+   - A report file (`reports/{num}-*.md`) with authoritative headers (`**URL:**`, `**Score:**`, etc.)
+   - A TSV in `batch/tracker-additions/` (per-apply outcomes)
 
-Everything below is context and rationale. These six numbers are the rules.
+   **Not trustworthy by default**: anything quoted from a subagent's return message, any ID or score the orchestrator "remembers" from prose, any page-content snippet reproduced from a subagent's narrative. Subagents can hallucinate plausible-looking IDs, scores, and confirmation text. Before passing any such fact to another subagent, cross-check it exists in one of the authoritative files above, OR instruct the dispatching subagent to write its output to a structured file and re-read from that file.
+
+   **Why**: on 2026-04-18, a scan subagent returned 30 fabricated Greenhouse IDs in prose (correct role titles, plausible-looking invented IDs that didn't exist in the API). The orchestrator dispatched 30 downstream subagents that all hit 404s. Verification rules downstream (Hard Limit #6, API-first verify) caught the symptom. This rule prevents the *shape* of the bug — hallucinations propagating through prose handoffs — across all quantitative / identifier / specific-fact claims, not just URLs.
+
+Everything below is context and rationale. These seven numbers are the rules.
 
 ---
 
@@ -31,6 +41,8 @@ Whenever the user says any variation of "apply to N jobs", "process the pipeline
 
 **Exception:** evaluation-only or tracker-only work (no Geometra, no repeated tool calls) can proceed in a single session. The rule targets tool-heavy multi-step loops.
 
+**Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md`** to exclude location-incompatible candidates. Catches the common case where an evaluated role has the right role-shape but a deal-breaking location that profile.yml already rules out.
+
 ---
 
 ## Subagent Routing — which agent for which task
@@ -457,7 +469,7 @@ To check or modify MCP settings, edit `opencode.json` in the project root.
 - JDs in `jds/` (referenced as `local:jds/{file}` in pipeline.md)
 - Batch in `batch/` (gitignored except scripts and prompt)
 - Report numbering: sequential 3-digit zero-padded, max existing + 1
-- **RULE: After each batch of evaluations, run `node merge-tracker.mjs`** to merge tracker additions and avoid duplications.
+- **RULE: After each batch of evaluations, run `npx job-forge merge`** to merge tracker additions and avoid duplications.
 - **RULE: NEVER create new entries in applications.md if company+role already exists.** Update the existing entry.
 - **RULE: NEVER attribute commits to opencode (no `Co-Authored-By: opencode` or similar).** All commits must be attributed solely to the person making the commit (e.g., CharlieGreenman).
 
@@ -484,13 +496,13 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 
 ### Pipeline Integrity
 
-1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `merge-tracker.mjs` handles the merge.
+1. **NEVER edit day files in `data/applications/` to ADD new entries** -- Write TSV in `batch/tracker-additions/` and `npx job-forge merge` handles the merge.
 2. **YES you can edit day files in `data/applications/` to UPDATE status/notes of existing entries.**
 3. All reports MUST include `**URL:**` in the header (between Score and PDF).
 4. All statuses MUST be canonical (see `templates/states.yml`).
-5. Health check: `node verify-pipeline.mjs`
-6. Normalize statuses: `node normalize-statuses.mjs`
-7. Dedup: `node dedup-tracker.mjs`
+5. Health check: `npx job-forge verify`
+6. Normalize statuses: `npx job-forge normalize`
+7. Dedup: `npx job-forge dedup`
 
 ### Canonical States (applications day files)
 
@@ -506,6 +518,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 | `Offer` | Offer received |
 | `Rejected` | Rejected by company |
 | `Discarded` | Discarded by candidate or offer closed |
+| `Failed` | Submission attempted but blocked by portal (spam-filter, anti-bot, broken form). May be recoverable via manual retry. |
 | `SKIP` | Doesn't fit, don't apply |
 
 **RULES:**

package/lib/canonical-states.mjs

@@ -0,0 +1,116 @@
+/**
+ * canonical-states.mjs — single source of truth for JobForge canonical states.
+ *
+ * `templates/states.yml` is the authoritative list. This module reads it
+ * (when available) and provides a hardcoded fallback that MUST stay in sync
+ * with the YAML for the belt-and-suspenders case where the file is missing.
+ *
+ * Consumers:
+ *   - merge-tracker.mjs          — validation + TSV column-swap heuristic
+ *   - normalize-statuses.mjs     — canonical list for direct matching
+ *
+ * The dashboard (Go) currently duplicates this list in
+ *   dashboard/internal/ui/screens/pipeline.go  (statusOptions, statusGroupOrder, statusLabel)
+ *   dashboard/internal/data/career.go          (NormalizeStatus, StatusPriority)
+ * Full codegen from YAML on the Go side is a follow-up; for now those
+ * copies carry KEEP IN SYNC comments.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Fallback canonical labels, in display order matching templates/states.yml.
+ * Used when the YAML file can't be read. Keep in sync with the YAML.
+ */
+export const DEFAULT_STATES = [
+  'Evaluated',
+  'Applied',
+  'Responded',
+  'Contacted',
+  'Interview',
+  'Offer',
+  'Rejected',
+  'Discarded',
+  'Failed',
+  'SKIP',
+];
+
+/**
+ * Extra tokens the column-swap heuristic recognises as "this column looks
+ * like a status". Canonical labels plus historical aliases the tracker has
+ * been known to emit (duplicate/repost/hold). Kept here so that both
+ * merge-tracker.mjs and any future consumer see the same alias set.
+ */
+const STATUS_DETECT_EXTRAS = ['duplicate', 'repost', 'hold'];
+
+/**
+ * Parse `templates/states.yml` and return the ordered list of canonical
+ * labels. Returns null when the file is missing or contains no labels,
+ * so callers can fall back to DEFAULT_STATES.
+ *
+ * The parser intentionally uses a line-regex rather than pulling in a
+ * YAML dependency — job-forge has no runtime YAML parser and we don't
+ * want to add one just for this.
+ *
+ * @param {string} repoRoot - repo root where `templates/states.yml` lives.
+ *                            Also checks `states.yml` at the root as a legacy fallback.
+ * @returns {string[] | null}
+ */
+export function loadCanonicalStates(repoRoot) {
+  const candidates = [
+    join(repoRoot, 'templates/states.yml'),
+    join(repoRoot, 'states.yml'),
+  ];
+
+  for (const filePath of candidates) {
+    if (!existsSync(filePath)) continue;
+    let text;
+    try {
+      text = readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+    const labels = [];
+    for (const line of text.split('\n')) {
+      const m = line.match(/^\s+label:\s*(.+)$/);
+      if (!m) continue;
+      const v = m[1].trim().replace(/^['"]|['"]$/g, '');
+      if (v) labels.push(v);
+    }
+    if (labels.length > 0) return labels;
+  }
+  return null;
+}
+
+/**
+ * Build the case-insensitive "does this column look like a status?" regex
+ * used by merge-tracker.mjs to detect swapped status/score columns in
+ * legacy TSVs.
+ *
+ * Matches at the start of the column text, case-insensitive. Includes the
+ * canonical labels plus alias tokens (duplicate/repost/hold) that have
+ * historically appeared in the status column.
+ *
+ * @param {string[]} states - canonical labels (typically the output of
+ *                            loadCanonicalStates, or DEFAULT_STATES).
+ * @returns {RegExp}
+ */
+export function buildStatusDetectionRegex(states) {
+  const tokens = [
+    ...states.map((s) => s.toLowerCase()),
+    ...STATUS_DETECT_EXTRAS,
+  ];
+  // Dedupe while preserving order.
+  const seen = new Set();
+  const unique = [];
+  for (const t of tokens) {
+    if (!seen.has(t)) {
+      seen.add(t);
+      unique.push(t);
+    }
+  }
+  // Escape regex-special chars just in case a label ever contains one.
+  const escaped = unique.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`^(${escaped.join('|')})`, 'i');
+}

package/merge-tracker.mjs

@@ -26,6 +26,9 @@ import {
   usesDayFiles, ensureDayDir, getHeader, formatAppLine, parseAppLine,
   readAllEntries, writeToDayFiles, listDayFiles, dayFilePath,
 } from './tracker-lib.mjs';
+import {
+  DEFAULT_STATES, loadCanonicalStates, buildStatusDetectionRegex,
+} from './lib/canonical-states.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const MERGED_DIR = join(ADDITIONS_DIR, 'merged');
@@ -54,26 +57,8 @@ Run from the repository root.`);
   process.exit(0);
 }
 
-const STATES_FILE = existsSync(join(PROJECT_DIR, 'templates/states.yml'))
-  ? join(PROJECT_DIR, 'templates/states.yml')
-  : join(PROJECT_DIR, 'states.yml');
-
-function loadCanonicalLabelsFromStatesYaml(filePath) {
-  if (!existsSync(filePath)) return null;
-  const text = readFileSync(filePath, 'utf-8');
-  const labels = [];
-  for (const line of text.split('\n')) {
-    const m = line.match(/^\s+label:\s*(.+)$/);
-    if (!m) continue;
-    let v = m[1].trim().replace(/^['"]|['"]$/g, '');
-    if (v) labels.push(v);
-  }
-  return labels.length > 0 ? labels : null;
-}
-
-const CANONICAL_STATES = loadCanonicalLabelsFromStatesYaml(STATES_FILE) || [
-  'Evaluated', 'Applied', 'Contacted', 'Responded', 'Interview', 'Offer', 'Rejected', 'Discarded', 'SKIP',
-];
+const CANONICAL_STATES = loadCanonicalStates(PROJECT_DIR) || DEFAULT_STATES;
+const STATUS_DETECT_RE = buildStatusDetectionRegex(CANONICAL_STATES);
 
 function validateStatus(status) {
   const clean = status.replace(/\*\*/g, '').replace(/\s+\d{4}-\d{2}-\d{2}.*$/, '').trim();
@@ -156,8 +141,8 @@ function parseTsvContent(content, filename) {
     const col5 = parts[5].trim();
     const col4LooksLikeScore = /^\d+\.?\d*\/5$/.test(col4) || col4 === 'N/A' || col4 === 'DUP';
     const col5LooksLikeScore = /^\d+\.?\d*\/5$/.test(col5) || col5 === 'N/A' || col5 === 'DUP';
-    const col4LooksLikeStatus = /^(evaluated|applied|contacted|responded|interview|offer|rejected|discarded|skip|duplicate|repost|hold)/i.test(col4);
-    const col5LooksLikeStatus = /^(evaluated|applied|contacted|responded|interview|offer|rejected|discarded|skip|duplicate|repost|hold)/i.test(col5);
+    const col4LooksLikeStatus = STATUS_DETECT_RE.test(col4);
+    const col5LooksLikeStatus = STATUS_DETECT_RE.test(col5);
 
     let statusCol, scoreCol;
     if (col4LooksLikeStatus && !col4LooksLikeScore) {

package/modes/_shared.md

@@ -247,7 +247,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 
 0. **Cover letter:** If the form has an option to attach or write a cover letter, ALWAYS include one. Generate PDF with the same visual design as the CV. Content: JD quotes mapped to proof points, links to relevant case studies. 1 page max.
 1. Read cv.md and article-digest.md (if exists) before evaluating any offer
-1b. **First evaluation of each session:** Run `node cv-sync-check.mjs` with Bash. If it reports warnings, notify the candidate before continuing
+1b. **First evaluation of each session:** Run `npx job-forge sync-check` with Bash. If it reports warnings, notify the candidate before continuing
 2. Detect the role archetype and adapt framing
 3. Cite exact lines from CV when matching
 4. Use WebSearch for comp and company data
@@ -269,4 +269,4 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 | Read | cv.md, article-digest.md, cv-template.html |
 | Write | Temporary HTML for PDF, day files in `data/applications/YYYY-MM-DD.md`, reports .md |
 | Edit | Update tracker |
-| Bash | `node generate-pdf.mjs` |
+| Bash | `npx job-forge pdf` |

package/modes/apply.md

@@ -10,6 +10,54 @@ Interactive mode for when the candidate is filling out an application form in Ch
 
 For a single application interactively, carry on in the current session — the rule targets multi-job loops.
 
+## Apply Preflight — Location Filter (orchestrator runs before dispatch)
+
+Before dispatching any batch of apply subagents, cross-check each candidate's location against `config/profile.yml`. **Prefer the structured `location_constraints` block** (deterministic match). Fall back to the prose `location.*` / `compensation.location_flexibility` fields only when `location_constraints` is absent (legacy profiles).
+
+### Preferred path — structured `location_constraints` (deterministic)
+
+1. Read `config/profile.yml → location_constraints`. If present, use the structured fields:
+
+   ```yaml
+   location_constraints:
+     remote_us: true | false
+     remote_global: true | false
+     hybrid_cities: [san-francisco, ...]
+     blocked_cities: [new-york, ...]
+     authorized_countries: [US, ...]       # ISO-3166 alpha-2
+     requires_visa_sponsorship: true | false
+   ```
+
+2. For each candidate, open its evaluation report (`reports/{num}-*.md`) and read the Location / Block A content. Extract: `mode ∈ {remote, hybrid, onsite}`, `city` (lowercase hyphenated), `country` (ISO-3166 alpha-2 when derivable).
+
+3. Apply the filter (decision table):
+
+   | Role shape | Rule | Outcome |
+   |---|---|---|
+   | Remote, country ∈ authorized_countries (typically US) | `remote_us == true` → COMPATIBLE | dispatch |
+   | Remote, country ∉ authorized_countries | `remote_global == true` AND (`requires_visa_sponsorship == false` OR JD mentions sponsorship) → COMPATIBLE | dispatch / else skip |
+   | Hybrid, `city ∈ hybrid_cities` | COMPATIBLE | dispatch |
+   | Hybrid or Onsite, `city ∈ blocked_cities` | INCOMPATIBLE | mark `Discarded`, note `location mismatch: blocked_city=X` |
+   | Hybrid or Onsite, `city` not in `hybrid_cities` and not in `blocked_cities` | INCOMPATIBLE by default (hybrid is opt-in per city) | mark `Discarded`, note `location mismatch: city=X not in hybrid_cities` |
+   | Location unclear / ambiguous | dispatch with a prompt flag instructing the apply subagent to verify the JD location first and Discard early if confirmed incompatible | dispatch-with-flag |
+
+4. Country/visa: if `requires_visa_sponsorship == false` AND `country ∉ authorized_countries` AND the JD does NOT explicitly offer sponsorship → INCOMPATIBLE, do NOT dispatch.
+
+### Fallback path — prose fields (legacy profiles with no `location_constraints`)
+
+When `location_constraints` is absent, use the prose fields:
+
+1. Read `config/profile.yml` for `location` (country, city), `compensation.location_flexibility`, and `visa_status`.
+2. For each candidate, open its evaluation report (`reports/{num}-*.md`) and read the Location / Block A content.
+3. Apply the filter:
+   - If the report says "Remote (US)" / "Remote" / "fully remote" — COMPATIBLE, dispatch.
+   - If the report says "Hybrid N days in {city}" AND {city} matches `location.city` OR `location_flexibility` says "open to hybrid in {city}" — COMPATIBLE, dispatch.
+   - If the report says "Hybrid" or "Onsite" at a city NOT in the profile's location set AND `location_flexibility` says Remote-preferred — INCOMPATIBLE, do NOT dispatch. Mark the tracker entry `Discarded` directly with note `location mismatch: profile=X, role=Y`.
+   - If unclear or ambiguous — dispatch with a prompt flag telling the apply subagent to verify the JD location first and Discard early if confirmed incompatible.
+4. Country/visa: if `visa_status: "No sponsorship needed"` and the role is outside the authorized country — INCOMPATIBLE, do NOT dispatch.
+
+**Why**: on 2026-04-18, 5 of 7 candidates dispatched for apply turned out location-incompatible. Each burned an apply-subagent round. The prose-field path reached the right call but cost interpretation cycles per dispatch; the structured path is O(1) field lookup and removes LLM-interpretation risk.
+
 ### Run this multi-job apply runbook literally when N > 1
 
 ```
@@ -24,8 +72,8 @@ Step 4  — For round in ceil(N/2):
             # WAIT for both returns. Do not proceed until both done.
 Step 5  — Between rounds: geometra_list_sessions() + geometra_disconnect({closeBrowser: true})
 Step 6  — Reconcile outcomes (Hard Limit #6):
-            bash: node merge-tracker.mjs       # TSVs → day file
-            bash: node verify-pipeline.mjs     # validate
+            bash: npx job-forge merge       # TSVs → day file
+            bash: npx job-forge verify      # validate
 Step 7  — Summarize outcomes; do NOT auto-retry failures.
 ```
 
@@ -33,7 +81,7 @@ If a subagent fails, report it in the summary and let the user decide whether to
 
 **Outcome routing (Hard Limit #6 in `AGENTS.md`):**
 - Subagents write `batch/tracker-additions/{num}-{slug}.tsv` — one TSV per job.
-- Orchestrator runs `node merge-tracker.mjs` once at the end to consume TSVs into the right day file.
+- Orchestrator runs `npx job-forge merge` once at the end to consume TSVs into the right day file.
 - **Do NOT** append APPLIED / FAILED / SKIP lines to `data/pipeline.md` — that file is the URL inbox only.
 
 ## Verify these requirements
@@ -214,13 +262,28 @@ Specific portals — Workday "parse my resume", iCIMS multi-step, SAP SuccessFac
 Check for an OTP gate after the candidate (or Geometra) submits — the major portals (Greenhouse, Workday, Lever, Ashby) gate submission behind an email verification code. When an OTP step appears, do this.
 
 1. **Do NOT stop and ask the candidate to paste the code manually.** Use the Gmail MCP.
-2. Wait ~5-10 seconds for the email, then `gmail_list_messages` with a sender-scoped recency query (e.g. `from:greenhouse newer_than:10m`).
-3. `gmail_get_message` on the most recent match, extract the code from the body.
-4. `geometra_fill_otp` to enter it, then submit.
+2. **Pick the Gmail sender query from the ATS recorded at scan time.** The scan subagent records the ATS type in `batch/scan-output-{YYYY-MM-DD}.md` (`ats` column) and in `data/pipeline.md` (`| ats={type}` suffix). Read that value first — do NOT re-infer the ATS from the URL host when it's already recorded.
+3. Map the `ats` value to the Gmail sender query (table below). Wait ~5-10 seconds for the email, then call `gmail_list_messages` with the matching query.
+4. `gmail_get_message` on the most recent match, extract the code from the body.
+5. `geometra_fill_otp` to enter it, then submit.
+
+**ATS → Gmail sender query lookup** (use the `ats` value recorded at scan time):
+
+| `ats` value | `q` for `gmail_list_messages` |
+|-------------|-------------------------------|
+| `greenhouse` | `from:greenhouse newer_than:10m` |
+| `workday`    | `from:myworkday newer_than:10m` |
+| `lever`      | `from:lever newer_than:10m` |
+| `ashby`      | `from:ashby newer_than:10m` |
+| `workable`   | `from:workable newer_than:10m` |
+| `builtin`    | `from:builtin newer_than:10m` |
+| `custom` / `unknown` / missing | `newer_than:10m subject:(verify OR code OR confirm)` |
+
+**Fallback when `ats` is missing** (legacy pipeline entries with no `| ats=` suffix, or scan-output without an `ats` column): infer from the URL host — `*.greenhouse.io` → `greenhouse`; `jobs.ashbyhq.com` → `ashby`; `jobs.lever.co` → `lever`; `*.myworkdayjobs.com` → `workday`; `apply.workable.com` / `jobs.workable.com` → `workable`; `builtin.com` → `builtin`; otherwise use the generic `verify OR code OR confirm` subject query.
 
 **Before reporting the submission as failed, always check Gmail.** A "submit did nothing" outcome usually means a silent OTP step — not a real failure.
 
-Full sender-to-query table and fallback patterns: see "OTP Handling via Gmail MCP" in `AGENTS.md`.
+Full OTP recipe and fallback patterns: see "OTP Handling via Gmail MCP" in `AGENTS.md`.
 
 ## Step 7 — Update outcomes after submission
 
@@ -240,7 +303,7 @@ The row exists. You are UPDATING an existing entry, which is allowed (Pipeline I
 The row does NOT exist yet. You MUST go through the TSV pathway (Hard Limit #6 + Pipeline Integrity rule #1):
 
 1. Write `batch/tracker-additions/{num}-{slug}.tsv` with the canonical 9-column format (see "TSV Format for Tracker Additions" in `AGENTS.md`)
-2. At the end of the apply run, the orchestrator calls `node merge-tracker.mjs`, which inserts the row into today's day file
+2. At the end of the apply run, the orchestrator calls `npx job-forge merge`, which inserts the row into today's day file
 3. Do NOT manually add a row to the day file. Do NOT append an `APPLIED` line to `data/pipeline.md`.
 
 ### Apply to both cases

package/modes/auto-pipeline.md

@@ -8,9 +8,12 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 
 **Pick exactly one method, in this priority order:**
 
-1. **Geometra MCP (preferred):** Most job portals (Lever, Ashby, Greenhouse, Workday) are SPAs. Use `geometra_connect` + `geometra_page_model` to render and read the JD. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
-2. **WebFetch (only if Geometra is unavailable OR returned only a shell with no JD text):** For static pages (ZipRecruiter, WeLoveProduct, company career pages).
-3. **WebSearch (only if methods 1 AND 2 both failed):** Search for the role title + company on secondary portals that index the JD in static HTML.
+1. **Greenhouse JSON API (first try, if the URL is Greenhouse-backed):** If the pipeline.md entry carries `| gh={slug}/{id}` OR the URL host matches `*.greenhouse.io` / a known Greenhouse customer front-end (`*.pinterestcareers.com`, `okta.com/company/careers/opportunity/*`, `samsara.com/company/careers/roles/*`, `zoominfo.com/careers?gh_jid=*`, `collibra.com/.../?gh_jid=*`, `careers.toasttab.com/jobs?gh_jid=*`, `careers.airbnb.com/positions/*?gh_jid=*`, `coinbase.com/careers/positions/*?gh_jid=*`, `instacart.careers/job/?gh_jid=*`), extract `slug` and `id` and WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` is the authoritative JD. 404 = genuinely closed (mark CLOSED and stop). **If 200, STOP — do not fall back to Geometra or WebFetch of the front-end.** The API is faster, cheaper (no Geometra session), and never returns a bot-shell.
+2. **Geometra MCP:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `geometra_connect` + `geometra_page_model` to render and read the JD. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
+3. **WebFetch (only if Geometra is unavailable OR returned only a shell with no JD text):** For static pages (ZipRecruiter, WeLoveProduct, company career pages).
+4. **WebSearch (only if methods 1–3 all failed):** Search for the role title + company on secondary portals that index the JD in static HTML.
+
+**Do NOT mark a Greenhouse-sourced offer CLOSED based on a WebFetch shell or a 403 from a customer-skinned careers domain.** Pinterest, Okta, Samsara, ZoomInfo, Collibra, Toast, Airbnb, Coinbase, Instacart all serve bot-hostile fronts. The Greenhouse JSON API (step 1) is the ground truth for their offer state. A previous scan run fed 60 live Greenhouse URLs through WebFetch-only verification and 100% of them were wrongly marked CLOSED; if you see a high stale rate, you are skipping step 1.
 
 **Rule:** Each URL gets fetched at most once per session. If you already have the JD text in context — from Geometra, a previous WebFetch, or pasted by the candidate — do not fetch again.
 

package/modes/pdf.md

@@ -17,7 +17,7 @@
 11. Inject keywords naturally into existing achievements (NEVER fabricate)
 12. Generate complete HTML from template + personalized content
 13. Write HTML to `/tmp/cv-candidate-{company}.html`
-14. Run: `node generate-pdf.mjs /tmp/cv-candidate-{company}.html output/cv-candidate-{company}-{YYYY-MM-DD}.pdf --format={letter|a4}`
+14. Run: `npx job-forge pdf /tmp/cv-candidate-{company}.html output/cv-candidate-{company}-{YYYY-MM-DD}.pdf --format={letter|a4}`
 15. Report: PDF path, page count, keyword coverage %
 
 ## Apply these ATS rules for clean parsing

package/modes/pipeline.md

@@ -33,9 +33,10 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 
 ## Detect JD From URL
 
-1. **Geometra MCP (preferred):** `geometra_connect` + `geometra_page_model`. Works with all SPAs, uses fewer tokens than raw DOM snapshots.
-2. **WebFetch (fallback):** For static pages or when Geometra is not available.
-3. **WebSearch (last resort):** Search on secondary portals that index the JD.
+1. **Greenhouse JSON API (FIRST, when the entry has `| gh={slug}/{id}` OR the host looks Greenhouse-backed):** WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` = LIVE, use it as the JD; 404 = genuinely CLOSED (mark `- [!]` and continue). Bot-hostile customer fronts (`pinterestcareers.com`, `okta.com`, `samsara.com`, `zoominfo.com`, `collibra.com`, `careers.toasttab.com`, `careers.airbnb.com`, `coinbase.com`, `instacart.careers`, `careers.toasttab.com`) MUST be verified via this API first — WebFetch/Geometra of those domains returns a shell or 403 and causes false CLOSED marks.
+2. **Geometra MCP:** `geometra_connect` + `geometra_page_model`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), uses fewer tokens than raw DOM snapshots.
+3. **WebFetch (fallback):** For static pages or when Geometra is not available.
+4. **WebSearch (last resort):** Search on secondary portals that index the JD.
 
 **Special cases:**
 - **LinkedIn**: May require login → mark `[!]` and ask the user to paste the text
@@ -52,7 +53,7 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 
 Before processing any URL, verify sync:
 ```bash
-node cv-sync-check.mjs
+npx job-forge sync-check
 ```
 If there is a desynchronization, warn the user before continuing.
 
@@ -71,8 +72,8 @@ Step 3  — For round in ceil(N/2):
             # WAIT for both returns before the next round.
 Step 4  — Between rounds: geometra_list_sessions() + geometra_disconnect({closeBrowser: true})
 Step 5  — Reconcile outcomes (Hard Limit #6):
-            bash: node merge-tracker.mjs      # TSVs → correct day file
-            bash: node verify-pipeline.mjs    # validate URL/status consistency
+            bash: npx job-forge merge      # TSVs → correct day file
+            bash: npx job-forge verify     # validate URL/status consistency
 Step 6  — Display summary table; flag any verify-pipeline errors.
 ```
 

package/modes/scan.md

@@ -68,8 +68,12 @@ The levels are additive — all are executed, results are merged and deduplicate
 5. **Level 2 — Greenhouse APIs** (WebFetch can batch freely — it's cheap and doesn't use Geometra sessions):
    For each company in `tracked_companies` with `api:` defined and `enabled: true`:
    a. WebFetch the API URL → JSON with job list
-   b. For each job extract: `{title, url, company}`
-   c. Accumulate in candidates list (dedup with Level 1)
+   b. For each job extract: `{title, url, company, gh_slug, gh_id, updated_at}`
+      - **`url`**: ALWAYS record the canonical Greenhouse URL: `https://job-boards.greenhouse.io/{gh_slug}/jobs/{gh_id}`. Do **NOT** use `absolute_url` when it points to a customer-skinned front-end (e.g. `pinterestcareers.com/jobs/?gh_jid=N`, `okta.com/company/careers/opportunity/N`, `samsara.com/company/careers/roles/N`, `zoominfo.com/careers?gh_jid=N`, `collibra.com/.../?gh_jid=N`, `careers.toasttab.com/jobs?gh_jid=N`, `careers.airbnb.com/positions/N`, `coinbase.com/careers/positions/N`, `instacart.careers/job/?gh_jid=N`, `pinterestcareers.com/jobs/?gh_jid=N`). These customer front-ends return shells or 403 to bots and cause downstream WebFetch-based verification to wrongly mark the role CLOSED.
+      - **`gh_slug`**: the Greenhouse board slug (from the API URL that was fetched).
+      - **`gh_id`**: `jobs[].id` from the API response.
+      - **`updated_at`**: `jobs[].updated_at` — record for staleness detection (skip if older than 90 days, flag if older than 30).
+   c. Accumulate in candidates list (dedup with Level 1). The pipeline.md entry MUST carry `| gh={gh_slug}/{gh_id}` at the end of the metadata so downstream evaluators can fall back to `https://boards-api.greenhouse.io/v1/boards/{gh_slug}/jobs/{gh_id}` when the canonical URL renders as a shell.
 
 6. **Level 3 — WebSearch queries** (WebSearch is parallel-safe; batch freely):
    For each query in `search_queries` with `enabled: true`:
@@ -102,7 +106,10 @@ The levels are additive — all are executed, results are merged and deduplicate
    - When a fuzzy match is found but the URL is new, log it as `skipped_repost` (not `skipped_dup`) with a note referencing the original entry number.
 
 8. **For each new offer that passes filters**:
-   a. Add to `pipeline.md` section "Pending": `- [ ] {url} | {company} | {title}`
+   a. Add to `pipeline.md` section "Pending": `- [ ] {url} | {company} | {title} | ats={ats}` — the `| ats={type}` suffix is REQUIRED for every entry (values: `greenhouse`, `ashby`, `workable`, `lever`, `workday`, `builtin`, `custom`, `unknown`). When the offer came from the Greenhouse API (Level 2), ALSO append `| gh={gh_slug}/{gh_id}` so downstream verification can hit the JSON endpoint. Example entries:
+      - `- [ ] https://job-boards.greenhouse.io/webflow/jobs/7689676 | Webflow | Lead AI Engineer | ats=greenhouse | gh=webflow/7689676`
+      - `- [ ] https://jobs.ashbyhq.com/everai/abc-123 | EverAI | Senior AI PM | ats=ashby`
+      - `- [ ] https://jobs.lever.co/temporal/xyz | Temporal | Product Manager - AI | ats=lever`
    b. Record in `scan-history.tsv`: `{url}\t{date}\t{query_name}\t{title}\t{company}\tadded`
 
 9. **Offers filtered by title**: record in `scan-history.tsv` with status `skipped_title`
@@ -137,6 +144,36 @@ https://...	2026-02-10	Greenhouse — SA	Junior Dev	BigCo	skipped_title
 https://...	2026-02-10	Ashby — AI PM	SA AI	OldCo	skipped_dup
 ```
 
+## Structured Output — Required for Downstream Dispatch
+
+Scan mode MUST write its ranked candidate list to a file, not just return it in prose. Downstream subagents (evaluators, applyers) must read URLs from this file, not from the scan subagent's return message. This prevents any hallucinated URL or ID from propagating.
+
+**File location**: `batch/scan-output-{YYYY-MM-DD}.md`
+
+**Format**: one markdown table per scan run, ordered by archetype-fit rank:
+
+| rank | company | ats | role | gh_slug | gh_id | url | updated_at |
+|------|---------|-----|------|---------|-------|-----|------------|
+| 1    | Webflow | greenhouse | Lead AI Engineer | webflow | 7689676 | https://job-boards.greenhouse.io/webflow/jobs/7689676 | 2026-04-14 |
+| 2    | EverAI  | ashby      | Senior AI PM     | -       | -       | https://jobs.ashbyhq.com/everai/abc-123 | 2026-04-15 |
+| ... | ... | ... | ... | ... | ... | ... | ... |
+
+**`ats` values** (one of): `greenhouse`, `ashby`, `workable`, `lever`, `workday`, `builtin`, `custom`, `unknown`. Every row MUST populate this column — it's what the apply subagent uses to pick the correct Gmail OTP sender query.
+
+Every row MUST have:
+- `ats` — the ATS platform hosting the posting. Inferred from the canonical URL host (e.g. `boards-api.greenhouse.io` / `job-boards.greenhouse.io` → `greenhouse`; `jobs.ashbyhq.com` → `ashby`; `jobs.lever.co` → `lever`; `myworkdayjobs.com` / `.wd5.myworkdayjobs.com` → `workday`; `apply.workable.com` / `jobs.workable.com` → `workable`; `builtin.com/jobs/` → `builtin`; company-own domains → `custom`; anything indeterminate → `unknown`).
+- `url` in canonical form. For Greenhouse use `https://job-boards.greenhouse.io/{gh_slug}/jobs/{gh_id}` (matching the suffix in `data/pipeline.md`). For other ATSes use the platform's native URL (do not rewrite).
+- `updated_at` in `YYYY-MM-DD` form (the most recent `updated_at` in the API response, or scan date when the source has no such field).
+
+Additional columns — REQUIRED when available, `-` (dash) when not applicable:
+- `gh_slug`, `gh_id` — Greenhouse-only. Copied verbatim from the Greenhouse API response (not reconstructed). For non-Greenhouse rows, emit `-` in both columns; `ats` + `url` are sufficient.
+
+The scan subagent's return message MUST:
+- Reference the file path (so orchestrators know where to read)
+- Omit the ranked URL list from prose entirely (summary counts only)
+
+**Rationale**: in a prior run, a scan subagent returned correct IDs in `scan-history.tsv` but hallucinated plausible-looking fake IDs in its prose-form top-30 list. The orchestrator trusted prose and dispatched 30 downstream subagents against fake URLs. File-based handoff prevents this class of error. Recording `ats` at scan time (rather than having the apply subagent infer it from the URL host) saves downstream re-parsing and keeps the OTP sender lookup deterministic.
+
 ## Output Summary
 
 ```
@@ -148,12 +185,27 @@ Filtered by title: N relevant
 Duplicates: N (already evaluated or in pipeline)
 New added to pipeline.md: N
 
-  + {company} | {title} | {query_name}
-  ...
-
-→ Run /job-forge pipeline to evaluate the new offers.
+NEXT STEP RECOMMENDATION:
+- Structured candidate list written to: batch/scan-output-{YYYY-MM-DD}.md
+- Downstream subagents MUST read URLs from that file, not from this return message
+- Run /job-forge pipeline to evaluate the new offers.
 ```
 
+## Verify Before Marking CLOSED (downstream rule)
+
+**DO NOT mark a Greenhouse offer CLOSED based on a WebFetch/Geometra result alone.** Customer-skinned careers pages (`pinterestcareers.com`, `okta.com`, `samsara.com`, `zoominfo.com`, `collibra.com`, `careers.toasttab.com`, `careers.airbnb.com`, `coinbase.com`, `instacart.careers`, etc.) serve bot-hostile shells — a 403, a navbar-only response, or a client-side-only render. WebFetch sees "no JD" and mis-classifies as CLOSED.
+
+**Correct verification order for any Greenhouse-sourced URL** (identified by a `| gh={slug}/{id}` suffix in `pipeline.md` or a `boards-api.greenhouse.io` / `job-boards.greenhouse.io` / `boards.greenhouse.io` host):
+
+1. Try `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. This is the authoritative source.
+   - **200 + JSON with `title` and `content`** → offer is LIVE. Use the JSON content as the JD. Do not mark CLOSED.
+   - **404** → offer is genuinely closed. Mark CLOSED.
+   - **Other non-2xx** → treat as transient (network/rate-limit); retry once. If still failing, mark `**Verification: unconfirmed**` and continue evaluation from whatever text is available. Do NOT mark CLOSED.
+2. Only then fall back to WebFetch of the canonical `job-boards.greenhouse.io/{slug}/jobs/{id}` URL.
+3. Only then fall back to Geometra on the same canonical URL.
+
+**Rule of thumb:** Greenhouse postings with valid `gh_slug`/`gh_id` should be verified via the API first. A WebFetch failure on a customer-skinned domain is NOT evidence the role is closed.
+
 ## Update careers_url
 
 Each company in `tracked_companies` MUST have a `careers_url` — the direct URL to its job listings page. The stored URL avoids searching for it every time.

package/normalize-statuses.mjs

@@ -7,7 +7,7 @@
  *   - Single-file: data/applications.md or applications.md (legacy)
  *
  * Maps all non-canonical statuses to canonical ones per templates/states.yml:
- *   Evaluated, Applied, Responded, Contacted, Interview, Offer, Rejected, Discarded, SKIP
+ *   Evaluated, Applied, Responded, Contacted, Interview, Offer, Rejected, Discarded, Failed, SKIP
  *
  * Also strips markdown bold (**) and dates from the status field,
  * moving DUPLICADO info to the notes column.
@@ -23,6 +23,9 @@ import {
   usesDayFiles, ensureDayDir, parseAppLine, formatAppLine,
   readAllEntries, writeToDayFiles, listDayFiles,
 } from './tracker-lib.mjs';
+import { DEFAULT_STATES, loadCanonicalStates } from './lib/canonical-states.mjs';
+
+const CANONICAL_STATES = loadCanonicalStates(PROJECT_DIR) || DEFAULT_STATES;
 
 const DRY_RUN = process.argv.includes('--dry-run');
 
@@ -61,11 +64,7 @@ function normalizeStatus(raw) {
 
   if (s === '—' || s === '-' || s === '') return { status: 'Discarded' };
 
-  const canonical = [
-    'Evaluated', 'Applied', 'Contacted', 'Responded', 'Interview',
-    'Offer', 'Rejected', 'Discarded', 'SKIP',
-  ];
-  for (const c of canonical) {
+  for (const c of CANONICAL_STATES) {
     if (lower === c.toLowerCase()) return { status: c };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
     "batch/batch-runner.sh",
     "batch/README.md",
     "docs/",
+    "lib/",
     "tracker-lib.mjs",
     "merge-tracker.mjs",
     "dedup-tracker.mjs",

package/templates/states.yml

@@ -55,6 +55,12 @@ states:
     description: Discarded by candidate or offer closed
     dashboard_group: discarded
 
+  - id: failed
+    label: Failed
+    aliases: []
+    description: Submission attempted but blocked by portal (spam-filter, anti-bot, broken form). May be recoverable via manual retry.
+    dashboard_group: failed
+
   - id: skip
     label: SKIP
     aliases: [skip]