job-forge 2.14.26 → 2.14.27

package/.cursor/rules/main.mdc

@@ -12,7 +12,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. Use `npx job-forge canon:key company-role --company "..." --role "..."` when deriving a stable duplicate key; do not invent slugs in prose. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -80,12 +80,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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
 
+- [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
+  why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
-3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], index/ledger prefilter when useful [D8, D13], dedupe [H2], location filter [D5], 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 canonical identity keys for duplicate checks [D15]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
+4. Prepare Geometra dispatches: cleanup [H3], canon/index/ledger prefilter when useful [D8, D13, D15], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

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

@@ -78,6 +78,10 @@ Local artifact index (terminal, outside opencode):
   npx job-forge index:has --key "company-role:acme:staff-engineer"
   npx job-forge index:query "acme"
 
+Identity keys (terminal, outside opencode):
+  npx job-forge canon:key company-role --company "Acme" --role "Staff Engineer"
+  npx job-forge canon:compare company "OpenAI, Inc." "Open AI"
+
 Consumer migrations (terminal, outside opencode):
   npx job-forge migrate:plan           # preview package.json/.gitignore drift
   npx job-forge migrate:apply          # apply safe harness upgrade migrations
@@ -168,11 +172,13 @@ Step 1  — Enumerate candidates
   - Build ordered list: candidates = [job_1, job_2, ..., job_N]
 
 Step 2  — Dedup against already-applied
-  - Run npx job-forge index:has --key "company-role:<company-slug>:<role-slug>"
-    as a fast local artifact prefilter when company+role is known. It rebuilds
-    .jobforge-index.json on demand from templates/index.json. A hit means the
-    role has already appeared in tracker files or tracker TSVs and can be
-    dropped before dispatch.
+  - Derive the stable key with npx job-forge canon:key company-role --company
+    "<company>" --role "<role>" when company+role is known.
+  - Run npx job-forge index:has --key "<canon-key>" as a fast local artifact
+    prefilter. It rebuilds .jobforge-index.json on demand from
+    templates/index.json and canonicalizes indexed company/role records through
+    templates/canon.json. A hit means the role has already appeared in tracker
+    files or tracker TSVs and can be dropped before dispatch.
   - If .jobforge-ledger/events.jsonl exists, use npx job-forge ledger:has as a
     fast prefilter for obvious company+role Applied duplicates. A ledger match
     can be dropped before dispatch without loading tracker files into context.

package/AGENTS.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. Use `npx job-forge canon:key company-role --company "..." --role "..."` when deriving a stable duplicate key; do not invent slugs in prose. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -75,12 +75,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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
 
+- [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
+  why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
-3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], index/ledger prefilter when useful [D8, D13], dedupe [H2], location filter [D5], 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 canonical identity keys for duplicate checks [D15]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
+4. Prepare Geometra dispatches: cleanup [H3], canon/index/ledger prefilter when useful [D8, D13, D15], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. Use `npx job-forge canon:key company-role --company "..." --role "..."` when deriving a stable duplicate key; do not invent slugs in prose. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -75,12 +75,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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
 
+- [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
+  why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
-3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], index/ledger prefilter when useful [D8, D13], dedupe [H2], location filter [D5], 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 canonical identity keys for duplicate checks [D15]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
+4. Prepare Geometra dispatches: cleanup [H3], canon/index/ledger prefilter when useful [D8, D13, D15], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/README.md

@@ -31,7 +31,7 @@ The scaffolded `opencode.json` already has three MCPs wired up — they launch a
 - **Gmail** — reads replies from recruiters
 - **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with `python3 -m pip install "state-trace[mcp]"`; the MCP command is `state-trace-mcp`.
 
-JobForge also keeps MCP-free local workflow state: `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, and `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`. None of these add always-on prompt or tool-schema tokens.
+JobForge also keeps MCP-free local workflow state: `templates/canon.json` defines URL/company/role identity keys via `@razroo/iso-canon`, `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, and `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`. None of these add always-on prompt or tool-schema tokens.
 
 `npm install` also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run `opencode`, `cursor`, `claude`, or `codex` in the same project and each picks up the shared MCP config and instructions.
 
@@ -78,7 +78,7 @@ JobForge turns opencode into a full job search command center. Instead of manual
 | **Durable Batch Orchestration** | `batch-runner.sh` uses `@razroo/iso-orchestrator` for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in `.jobforge-runs/`. |
 | **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
 | **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to `opencode-go/deepseek-v4-flash` so application runs avoid overloaded free-model pools. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
-| **Trace + Telemetry + Guard + Contract + Ledger + Capabilities + Context + Cache + Index + Migrate** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
+| **Trace + Telemetry + Guard + Contract + Canon + Ledger + Capabilities + Context + Cache + Index + Migrate** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
 | **Token Cost Visibility** | `job-forge tokens --days 1` for per-session breakdown; `job-forge session-report --since-minutes 60 --log` to flag sessions over budget and append history to `data/token-usage.tsv`. Auto-logged after every batch run. |
 
 ## Usage
@@ -164,7 +164,7 @@ my-search/
 ├── .opencode/skills/job-forge.md # → skill router
 ├── .opencode/agents/             # → @general-free, @general-paid, @glm-minimal
 ├── modes/                        # → _shared.md + skill modes
-├── templates/                    # → states.yml, portals.example.yml, cv-template.html, capabilities.json, context.json, index.json, migrations.json
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, capabilities.json, context.json, index.json, migrations.json
 ├── batch/batch-prompt.md         # → batch worker prompt
 ├── batch/batch-runner.sh         # → parallel orchestrator
 │
@@ -190,7 +190,7 @@ JobForge/
 │   ├── sync.mjs                  # postinstall: creates symlinks in consumer project
 │   └── create-job-forge.mjs      # scaffolder
 ├── modes/                        # _shared.md + 16 skill modes
-├── templates/                    # cv-template.html, portals.example.yml, states.yml, capabilities.json, context.json, migrations.json
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, capabilities.json, context.json, migrations.json
 ├── config/profile.example.yml    # template for consumer's profile.yml
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
@@ -201,6 +201,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
+│   ├── canon.mjs                 # iso-canon-backed identity normalization CLI
 │   ├── migrate.mjs               # iso-migrate-backed consumer-project migrations
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish

package/bin/create-job-forge.mjs

@@ -147,6 +147,10 @@ const consumerPkg = {
     'index:has': 'job-forge index:has',
     'index:query': 'job-forge index:query',
     'index:explain': 'job-forge index:explain',
+    'canon:normalize': 'job-forge canon:normalize',
+    'canon:key': 'job-forge canon:key',
+    'canon:compare': 'job-forge canon:compare',
+    'canon:explain': 'job-forge canon:explain',
     'migrate:plan': 'job-forge migrate:plan',
     'migrate:apply': 'job-forge migrate:apply',
     'migrate:check': 'job-forge migrate:check',
@@ -252,6 +256,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:*\` |
+| Identity canonicalization | \`templates/canon.json\` | Stable URL/company/role keys; use \`job-forge canon:*\` |
 | Consumer migrations | \`templates/migrations.json\` | Safe script/gitignore upgrades; use \`job-forge migrate:*\` |
 | Scanner config | \`portals.yml\` (project root) | Company configs |
 | Profile / identity | \`config/profile.yml\` | Candidate name, email, target roles |
@@ -402,6 +407,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 canon:key company-role --company "Acme, Inc." --role "Senior SWE"
 job-forge migrate:check    # verify consumer package scripts/gitignore are current
 job-forge pdf cv.md out.pdf
 job-forge tokens --days 1  # per-session opencode token usage

package/bin/job-forge.mjs

@@ -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
+ *   canon:*        Compute deterministic identity keys via iso-canon
  *   migrate:*      Apply deterministic consumer-project migrations via iso-migrate
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
@@ -128,6 +129,14 @@ const indexAliases = {
   'index:path': 'path',
 };
 
+const canonAliases = {
+  'canon:normalize': 'normalize',
+  'canon:key': 'key',
+  'canon:compare': 'compare',
+  'canon:explain': 'explain',
+  'canon:path': 'path',
+};
+
 const migrateAliases = {
   'migrate:plan': 'plan',
   'migrate:apply': 'apply',
@@ -186,6 +195,9 @@ 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
+  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
   migrate:plan            Preview deterministic consumer-project migrations
   migrate:apply           Apply deterministic consumer-project migrations
   migrate:check           Fail if migrations are pending
@@ -228,6 +240,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 canon:key company-role --company "Acme, Inc." --role "Senior SWE - Remote US"
+  job-forge canon:compare company "OpenAI, Inc." "Open AI"
   job-forge migrate:check
   job-forge migrate:apply
 
@@ -359,6 +373,21 @@ if (cmd === 'index' || indexAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'canon' || canonAliases[cmd]) {
+  const canonArgs = cmd === 'canon'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [canonAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/canon.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...canonArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 if (cmd === 'migrate' || migrateAliases[cmd]) {
   const migrateArgs = cmd === 'migrate'
     ? (rest.length === 0 ? ['help'] : rest)

package/docs/ARCHITECTURE.md

@@ -164,6 +164,7 @@ data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/p
 .jobforge-index.json     →  Deterministic artifact lookup index built from templates/index.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/migrations.json → Safe consumer-project upgrade policy
 templates/cv-template.html → PDF generation template
@@ -179,6 +180,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)
+- Canon: `templates/canon.json` (identity rules inspected with `job-forge canon:*`)
 - Migrations: `templates/migrations.json` (applied by `job-forge sync` and inspectable with `job-forge migrate:*`)
 - Capabilities: `templates/capabilities.json` (role boundary policy inspected with `job-forge capabilities:*`)
 - Context: `templates/context.json` (mode/reference file bundles inspected with `job-forge context:*`)
@@ -225,6 +227,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/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/migrate.mjs` | `npx job-forge migrate:plan` / `migrate:apply` / `migrate:check` | Deterministic `@razroo/iso-migrate` consumer-project upgrades for scripts and generated-artifact ignores |
 | `tracker-lib.mjs` | _(library)_ | Shared helpers for reading/writing day-based tracker files — imported by merge/dedup/verify/normalize |

package/docs/CUSTOMIZATION.md

@@ -152,7 +152,11 @@ Mode/reference context bundles live in `templates/context.json` and are planned
 
 ## JobForge artifact index
 
-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. This is not an MCP and does not add tool-schema tokens.
+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 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.
 
 ## JobForge consumer migrations
 

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`, `context`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
+| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `canon`, `context`, `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

@@ -126,6 +126,8 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Pipeline health check | `npx job-forge verify` | `npm run verify` |
 | Merge `batch/tracker-additions/*.tsv` into the tracker | `npx job-forge merge` | `npm run merge` |
 | Inspect tracker row contract | `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` | _(none)_ |
+| Derive canonical company/role key | `npx job-forge canon:key company-role --company "Acme" --role "Staff Engineer"` | `npm run canon:key -- company-role --company ...` |
+| Compare identity values | `npx job-forge canon:compare company "OpenAI, Inc." "Open AI"` | `npm run canon:compare -- company ...` |
 | Inspect role capabilities | `npx job-forge capabilities:explain general-free` | `npm run capabilities:explain -- general-free` |
 | 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` |

package/iso/commands/job-forge.md

@@ -81,6 +81,10 @@ Local artifact index (terminal, outside opencode):
   npx job-forge index:has --key "company-role:acme:staff-engineer"
   npx job-forge index:query "acme"
 
+Identity keys (terminal, outside opencode):
+  npx job-forge canon:key company-role --company "Acme" --role "Staff Engineer"
+  npx job-forge canon:compare company "OpenAI, Inc." "Open AI"
+
 Consumer migrations (terminal, outside opencode):
   npx job-forge migrate:plan           # preview package.json/.gitignore drift
   npx job-forge migrate:apply          # apply safe harness upgrade migrations
@@ -171,11 +175,13 @@ Step 1  — Enumerate candidates
   - Build ordered list: candidates = [job_1, job_2, ..., job_N]
 
 Step 2  — Dedup against already-applied
-  - Run npx job-forge index:has --key "company-role:<company-slug>:<role-slug>"
-    as a fast local artifact prefilter when company+role is known. It rebuilds
-    .jobforge-index.json on demand from templates/index.json. A hit means the
-    role has already appeared in tracker files or tracker TSVs and can be
-    dropped before dispatch.
+  - Derive the stable key with npx job-forge canon:key company-role --company
+    "<company>" --role "<role>" when company+role is known.
+  - Run npx job-forge index:has --key "<canon-key>" as a fast local artifact
+    prefilter. It rebuilds .jobforge-index.json on demand from
+    templates/index.json and canonicalizes indexed company/role records through
+    templates/canon.json. A hit means the role has already appeared in tracker
+    files or tracker TSVs and can be dropped before dispatch.
   - If .jobforge-ledger/events.jsonl exists, use npx job-forge ledger:has as a
     fast prefilter for obvious company+role Applied duplicates. A ledger match
     can be dropped before dispatch without loading tracker files into context.

package/iso/instructions.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. Use `npx job-forge canon:key company-role --company "..." --role "..."` when deriving a stable duplicate key; do not invent slugs in prose. `npx job-forge index:has --key "company-role:..."` may be used first as a fast local artifact prefilter; it rebuilds `.jobforge-index.json` on demand from `templates/index.json`, and a company+role hit is enough to drop an obvious duplicate before dispatch. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may also be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the index or ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -75,12 +75,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [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
 
+- [D15] Treat `templates/canon.json` as the source of truth for URL/company/role identity keys. Use `npx job-forge canon:key ...` or `npx job-forge canon:compare ...` before broad duplicate checks when a stable key or same/possible/different decision is useful.
+  why: `iso-canon` is not an MCP and adds no prompt/tool-schema tokens; it centralizes duplicate-key rules so agents do not repeatedly derive inconsistent slugs for aliases, suffixes, remote/location noise, or tracking URLs
+
 ## Procedure
 
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
-3. Read the active mode file [D3]. Use context bundle checks when changing context loads [D11]. Check cached artifacts before URL/JD refetches [D12]. Use artifact index lookups before broad file reads when they can answer the question [D13]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], index/ledger prefilter when useful [D8, D13], dedupe [H2], location filter [D5], 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 canonical identity keys for duplicate checks [D15]. Use migration checks for harness drift [D14]. Decide inline vs delegated work [D1].
+4. Prepare Geometra dispatches: cleanup [H3], canon/index/ledger prefilter when useful [D8, D13, D15], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/lib/jobforge-cache.mjs

@@ -10,6 +10,7 @@ import {
   resolveCacheDir,
   verifyCache,
 } from '@razroo/iso-cache';
+import { canonicalizeJobForgeUrl } from './jobforge-canon.mjs';
 
 export const CACHE_DIR = '.jobforge-cache';
 export const JD_CACHE_NAMESPACE = 'jobforge.jd';
@@ -96,10 +97,14 @@ export function normalizeJobUrl(url) {
   const text = String(url || '').trim();
   if (!text) throw new Error('url is required');
   try {
-    const parsed = new URL(text);
-    parsed.hash = '';
-    return parsed.toString();
+    return canonicalizeJobForgeUrl(text).canonical;
   } catch {
-    return text;
+    try {
+      const parsed = new URL(text);
+      parsed.hash = '';
+      return parsed.toString();
+    } catch {
+      return text;
+    }
   }
 }

package/lib/jobforge-canon.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  canonicalizeCompany,
+  canonicalizeCompanyRole,
+  canonicalizeEntity,
+  canonicalizeRole,
+  canonicalizeUrl,
+  compareCanon,
+  loadCanonConfig,
+  parseJson,
+  resolveProfile,
+} from '@razroo/iso-canon';
+
+export const CANON_CONFIG_FILE = 'templates/canon.json';
+export const CANON_PROFILE = 'jobforge';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeCanonConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_CANON_CONFIG || join(projectDir, CANON_CONFIG_FILE);
+}
+
+export function readJobForgeCanonConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeCanonConfigPath(projectDir);
+  return loadCanonConfig(parseJson(readFileSync(path, 'utf8'), path), path);
+}
+
+export function jobForgeCanonProfile(projectDir = resolveProjectDir()) {
+  return resolveProfile(readJobForgeCanonConfig(projectDir), process.env.JOB_FORGE_CANON_PROFILE || CANON_PROFILE);
+}
+
+export function canonicalizeJobForgeUrl(url, projectDir = resolveProjectDir()) {
+  return canonicalizeUrl(url, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeCompany(company, projectDir = resolveProjectDir()) {
+  return canonicalizeCompany(company, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeRole(role, projectDir = resolveProjectDir()) {
+  return canonicalizeRole(role, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeCompanyRole(company, role, projectDir = resolveProjectDir()) {
+  return canonicalizeCompanyRole(company, role, jobForgeCanonProfile(projectDir));
+}
+
+export function canonicalizeJobForgeEntity(type, input, projectDir = resolveProjectDir()) {
+  return canonicalizeEntity(type, input, jobForgeCanonProfile(projectDir));
+}
+
+export function compareJobForgeCanon(type, left, right, projectDir = resolveProjectDir()) {
+  return compareCanon(type, left, right, jobForgeCanonProfile(projectDir));
+}
+
+export function jobForgeUrlKey(url, projectDir = resolveProjectDir()) {
+  return canonicalizeJobForgeUrl(url, projectDir).key;
+}
+
+export function jobForgeCompanyRoleKey(company, role, projectDir = resolveProjectDir()) {
+  return canonicalizeJobForgeCompanyRole(company, role, projectDir).key;
+}
+
+export function jobForgeApplicationSubject(company, role, projectDir = resolveProjectDir()) {
+  const companyKey = canonicalizeJobForgeCompany(company, projectDir).key.slice('company:'.length);
+  const roleKey = canonicalizeJobForgeRole(role, projectDir).key.slice('role:'.length);
+  return `application:${companyKey}:${roleKey}`;
+}
+
+export function legacyCompanyRoleKey(company, role) {
+  return `company-role:${legacySlugPart(company)}:${legacySlugPart(role)}`;
+}
+
+export function legacyUrlKey(url) {
+  return `url:${String(url || '').trim()}`;
+}
+
+export function legacySlugPart(value) {
+  const slug = String(value || 'unknown')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'unknown';
+}

package/lib/jobforge-index.mjs

@@ -6,8 +6,15 @@ import {
   loadIndexConfig,
   parseJson,
   queryIndex,
+  recordId,
   verifyIndex,
 } from '@razroo/iso-index';
+import {
+  jobForgeCompanyRoleKey,
+  jobForgeUrlKey,
+  legacyCompanyRoleKey,
+  legacyUrlKey,
+} from './jobforge-canon.mjs';
 
 export const INDEX_FILE = '.jobforge-index.json';
 export const INDEX_CONFIG_FILE = 'templates/index.json';
@@ -35,7 +42,7 @@ export function readJobForgeIndexConfig(projectDir = resolveProjectDir()) {
 
 export function buildJobForgeIndex(options = {}, projectDir = resolveProjectDir()) {
   const config = readJobForgeIndexConfig(projectDir);
-  const index = buildIndex(config, { root: projectDir });
+  const index = canonicalizeJobForgeIndex(buildIndex(config, { root: projectDir }), projectDir);
   const out = options.out || jobForgeIndexPath(projectDir);
   if (options.write !== false) {
     writeFileSync(out, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
@@ -90,3 +97,72 @@ export function jobForgeIndexSummary(projectDir = resolveProjectDir()) {
     configHash: index.configHash,
   };
 }
+
+function canonicalizeJobForgeIndex(index, projectDir) {
+  const records = (index.records || []).map((record) => canonicalizeJobForgeIndexRecord(record, projectDir));
+  records.sort(compareRecords);
+  return {
+    ...index,
+    records,
+    stats: {
+      ...(index.stats || {}),
+      records: records.length,
+    },
+  };
+}
+
+function canonicalizeJobForgeIndexRecord(record, projectDir) {
+  const key = canonicalIndexKey(record, projectDir);
+  if (key === record.key) return record;
+  const updated = { ...record, key };
+  return { ...updated, id: recordId(updated) };
+}
+
+function canonicalIndexKey(record, projectDir) {
+  if (isCompanyRoleRecord(record)) {
+    const { company, role } = companyRoleFields(record);
+    if (company && role) return safeCompanyRoleKey(company, role, projectDir);
+  }
+  if (isUrlRecord(record)) {
+    const url = record.fields?.url;
+    if (url) return safeUrlKey(url, projectDir);
+  }
+  return record.key;
+}
+
+function isCompanyRoleRecord(record) {
+  return record.kind === 'jobforge.application' || record.kind === 'jobforge.tracker-addition';
+}
+
+function companyRoleFields(record) {
+  const fields = record.fields || {};
+  return {
+    company: fields.company || fields.Company,
+    role: fields.role || fields.Role,
+  };
+}
+
+function isUrlRecord(record) {
+  return record.kind === 'jobforge.report.url' || record.kind === 'jobforge.pipeline.url' || record.kind === 'jobforge.scan.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 compareRecords(a, b) {
+  return `${a.kind}\0${a.key}\0${a.source?.path || ''}\0${a.source?.line || ''}\0${a.id}`
+    .localeCompare(`${b.kind}\0${b.key}\0${b.source?.path || ''}\0${b.source?.line || ''}\0${b.id}`);
+}

package/lib/jobforge-ledger.mjs

@@ -8,6 +8,16 @@ import {
   readLedger,
   verifyLedger,
 } from '@razroo/iso-ledger';
+import {
+  jobForgeApplicationSubject,
+  jobForgeCompanyRoleKey,
+  jobForgeUrlKey,
+  legacyCompanyRoleKey,
+  legacySlugPart,
+  legacyUrlKey,
+} from './jobforge-canon.mjs';
+
+export { legacyCompanyRoleKey, legacyUrlKey };
 
 export const LEDGER_DIR = '.jobforge-ledger';
 export const LEDGER_FILE = 'events.jsonl';
@@ -89,7 +99,7 @@ export function recordTrackerMergeResult(addition, options = {}) {
 
 export function buildApplicationEvent(type, app, options = {}) {
   const projectDir = resolveProjectDir(options.projectDir);
-  const key = companyRoleKey(app.company, app.role);
+  const key = companyRoleKey(app.company, app.role, projectDir);
   const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : '';
   const idempotencyParts = [
     options.idempotencyPrefix || type,
@@ -104,7 +114,7 @@ export function buildApplicationEvent(type, app, options = {}) {
   return {
     type,
     key,
-    subject: applicationSubject(app.company, app.role),
+    subject: applicationSubject(app.company, app.role, projectDir),
     idempotencyKey: idempotencyParts.join(':'),
     data: compactObject({
       num: numberOrString(app.num),
@@ -128,7 +138,7 @@ export function buildApplicationEvent(type, app, options = {}) {
 
 export function buildPipelineEvent(item, options = {}) {
   const projectDir = resolveProjectDir(options.projectDir);
-  const key = item.url ? urlKey(item.url) : `pipeline:${item.lineNumber || 'unknown'}`;
+  const key = item.url ? urlKey(item.url, projectDir) : `pipeline:${item.lineNumber || 'unknown'}`;
   const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : 'data/pipeline.md';
   const state = item.checked ? 'processed' : 'pending';
 
@@ -154,25 +164,33 @@ export function buildPipelineEvent(item, options = {}) {
   };
 }
 
-export function companyRoleKey(company, role) {
-  return `company-role:${slugPart(company)}:${slugPart(role)}`;
+export function companyRoleKey(company, role, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeCompanyRoleKey(company, role, projectDir);
+  } catch {
+    return legacyCompanyRoleKey(company, role);
+  }
 }
 
-export function applicationSubject(company, role) {
-  return `application:${slugPart(company)}:${slugPart(role)}`;
+export function applicationSubject(company, role, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeApplicationSubject(company, role, projectDir);
+  } catch {
+    const key = legacyCompanyRoleKey(company, role).slice('company-role:'.length);
+    return `application:${key}`;
+  }
 }
 
-export function urlKey(url) {
-  return `url:${String(url || '').trim()}`;
+export function urlKey(url, projectDir = resolveProjectDir()) {
+  try {
+    return jobForgeUrlKey(url, projectDir);
+  } catch {
+    return legacyUrlKey(url);
+  }
 }
 
 export function slugPart(value) {
-  const slug = String(value || 'unknown')
-    .toLowerCase()
-    .replace(/&/g, ' and ')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return slug || 'unknown';
+  return legacySlugPart(value);
 }
 
 function relativePath(projectDir, value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.26",
+  "version": "2.14.27",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -55,6 +55,10 @@
     "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",
+    "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",
+    "canon:explain": "node bin/job-forge.mjs canon:explain",
     "migrate:plan": "node bin/job-forge.mjs migrate:plan",
     "migrate:apply": "node bin/job-forge.mjs migrate:apply",
     "migrate:check": "node bin/job-forge.mjs migrate:check",
@@ -127,6 +131,7 @@
   "dependencies": {
     "@razroo/iso-capabilities": "^0.1.0",
     "@razroo/iso-cache": "^0.1.0",
+    "@razroo/iso-canon": "^0.1.0",
     "@razroo/iso-context": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",

package/scripts/canon.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatCanonResult,
+  formatCompareResult,
+  formatConfigSummary,
+} from '@razroo/iso-canon';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  canonicalizeJobForgeEntity,
+  compareJobForgeCanon,
+  jobForgeCanonConfigPath,
+  jobForgeCanonProfile,
+} from '../lib/jobforge-canon.mjs';
+
+const USAGE = `job-forge canon - deterministic identity keys for JobForge
+
+Usage:
+  job-forge canon:normalize <url|company|role> <value> [--json]
+  job-forge canon:normalize company-role --company <name> --role <title> [--json]
+  job-forge canon:key <url|company|role> <value> [--json]
+  job-forge canon:key company-role --company <name> --role <title> [--json]
+  job-forge canon:compare <url|company|role> <left> <right> [--json]
+  job-forge canon:compare company-role --left-company <name> --left-role <title> --right-company <name> --right-role <title> [--json]
+  job-forge canon:explain [--json]
+  job-forge canon:path
+
+The policy is templates/canon.json. These commands are local, model-free, and
+use the same keys that JobForge ledger/cache helpers use internally.`;
+
+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(jobForgeCanonConfigPath(PROJECT_DIR));
+  } else if (cmd === 'normalize') {
+    normalize(opts, false);
+  } else if (cmd === 'key') {
+    normalize(opts, true);
+  } else if (cmd === 'compare') {
+    compare(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown canon 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,
+    values: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--company') {
+      opts.company = valueAfter(args, ++i, '--company');
+    } else if (arg.startsWith('--company=')) {
+      opts.company = arg.slice('--company='.length);
+    } else if (arg === '--role') {
+      opts.role = valueAfter(args, ++i, '--role');
+    } else if (arg.startsWith('--role=')) {
+      opts.role = arg.slice('--role='.length);
+    } else if (arg === '--left-company') {
+      opts.leftCompany = valueAfter(args, ++i, '--left-company');
+    } else if (arg.startsWith('--left-company=')) {
+      opts.leftCompany = arg.slice('--left-company='.length);
+    } else if (arg === '--left-role') {
+      opts.leftRole = valueAfter(args, ++i, '--left-role');
+    } else if (arg.startsWith('--left-role=')) {
+      opts.leftRole = arg.slice('--left-role='.length);
+    } else if (arg === '--right-company') {
+      opts.rightCompany = valueAfter(args, ++i, '--right-company');
+    } else if (arg.startsWith('--right-company=')) {
+      opts.rightCompany = arg.slice('--right-company='.length);
+    } else if (arg === '--right-role') {
+      opts.rightRole = valueAfter(args, ++i, '--right-role');
+    } else if (arg.startsWith('--right-role=')) {
+      opts.rightRole = arg.slice('--right-role='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown flag "${arg}"`);
+    } else {
+      opts.values.push(arg);
+    }
+  }
+
+  return opts;
+}
+
+function normalize(opts, keyOnly) {
+  const type = parseType(opts.values.shift(), keyOnly ? 'key' : 'normalize');
+  const input = normalizeInput(type, opts);
+  const result = canonicalizeJobForgeEntity(type, input, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (keyOnly) {
+    console.log(result.key);
+  } else {
+    console.log(formatCanonResult(result));
+  }
+}
+
+function compare(opts) {
+  const type = parseType(opts.values.shift(), 'compare');
+  const [left, right] = compareInputs(type, opts);
+  const result = compareJobForgeCanon(type, left, right, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatCompareResult(result));
+}
+
+function explain(opts) {
+  const profile = jobForgeCanonProfile(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(profile, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeCanonConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary({ version: 1, profiles: [profile] }));
+}
+
+function normalizeInput(type, opts) {
+  if (type === 'company-role') {
+    if (!opts.company || !opts.role) throw new Error('company-role requires --company and --role');
+    return { company: opts.company, role: opts.role };
+  }
+  if (opts.values.length !== 1) throw new Error(`${type}: provide exactly one value; quote values containing spaces`);
+  return opts.values[0];
+}
+
+function compareInputs(type, opts) {
+  if (type === 'company-role') {
+    if (!opts.leftCompany || !opts.leftRole || !opts.rightCompany || !opts.rightRole) {
+      throw new Error('company-role compare requires --left-company, --left-role, --right-company, and --right-role');
+    }
+    return [
+      { company: opts.leftCompany, role: opts.leftRole },
+      { company: opts.rightCompany, role: opts.rightRole },
+    ];
+  }
+  if (opts.values.length !== 2) throw new Error(`${type}: provide exactly two values; quote values containing spaces`);
+  return [opts.values[0], opts.values[1]];
+}
+
+function parseType(value, command) {
+  if (value === 'url' || value === 'company' || value === 'role' || value === 'company-role') return value;
+  throw new Error(`${command}: expected type url, company, role, or company-role`);
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/scripts/ledger.mjs

@@ -16,6 +16,8 @@ import {
   jobForgeLedgerPath,
   jobForgeLedgerSummary,
   ledgerExists,
+  legacyCompanyRoleKey,
+  legacyUrlKey,
   readJobForgeLedger,
   urlKey,
   verifyJobForgeLedger,
@@ -201,8 +203,9 @@ function verify(opts) {
 }
 
 function has(opts) {
-  const filters = queryFilters(opts);
-  const events = queryEvents(readJobForgeLedger(PROJECT_DIR), filters);
+  const filters = queryFilterCandidates(opts);
+  const ledger = readJobForgeLedger(PROJECT_DIR);
+  const events = uniqueEvents(filters.flatMap((filter) => queryEvents(ledger, filter)));
   if (opts.json) {
     console.log(JSON.stringify({ match: events.length > 0, count: events.length, filters }, null, 2));
   } else if (events.length > 0) {
@@ -237,6 +240,28 @@ function queryFilters(opts) {
   return filters;
 }
 
+function queryFilterCandidates(opts) {
+  const primary = queryFilters(opts);
+  const candidates = [primary];
+  const legacy = { ...primary };
+  if (opts.url) legacy.key = legacyUrlKey(opts.url);
+  if (opts.company || opts.role) legacy.key = legacyCompanyRoleKey(opts.company, opts.role);
+  if (legacy.key && legacy.key !== primary.key) candidates.push(legacy);
+  return candidates;
+}
+
+function uniqueEvents(events) {
+  const seen = new Set();
+  const out = [];
+  for (const event of events) {
+    const id = event.id || event.idempotencyKey || JSON.stringify(event);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(event);
+  }
+  return out;
+}
+
 function collectProjectEvents() {
   const events = [];
   const { entries } = readAllEntries();

package/templates/canon.json

@@ -0,0 +1,65 @@
+{
+  "version": 1,
+  "profiles": [
+    {
+      "name": "jobforge",
+      "url": {
+        "dropHash": true,
+        "stripWww": true,
+        "stripQueryParams": [
+          "utm_*",
+          "gh_src",
+          "source",
+          "ref",
+          "referrer",
+          "lever-source",
+          "ashby_jid"
+        ]
+      },
+      "company": {
+        "aliases": {
+          "open ai": "openai",
+          "anthropic pbc": "anthropic",
+          "google llc": "google",
+          "meta platforms": "meta"
+        },
+        "suffixes": [
+          "inc",
+          "incorporated",
+          "llc",
+          "ltd",
+          "limited",
+          "corp",
+          "corporation",
+          "company",
+          "co",
+          "pbc",
+          "plc"
+        ]
+      },
+      "role": {
+        "aliases": {
+          "fdse": "forward deployed software engineer",
+          "fullstack": "full stack",
+          "ml": "machine learning",
+          "sr": "senior",
+          "swe": "software engineer"
+        },
+        "stopWords": [
+          "hybrid",
+          "new york",
+          "onsite",
+          "remote",
+          "san francisco",
+          "united states",
+          "usa",
+          "us"
+        ]
+      },
+      "match": {
+        "strong": 0.92,
+        "possible": 0.78
+      }
+    }
+  ]
+}

package/templates/capabilities.json

@@ -13,6 +13,7 @@
           "npx job-forge context:*",
           "npx job-forge cache:*",
           "npx job-forge index:*",
+          "npx job-forge canon:*",
           "rg *"
         ],
         "deny": [
@@ -60,7 +61,8 @@
           "npx job-forge ledger:*",
           "npx job-forge capabilities:*",
           "npx job-forge cache:*",
-          "npx job-forge index:*"
+          "npx job-forge index:*",
+          "npx job-forge canon:*"
         ],
         "deny": [
           "task *"
@@ -100,6 +102,7 @@
       "commands": {
         "allow": [
           "npx job-forge slugify *",
+          "npx job-forge canon:*",
           "npx job-forge today",
           "npx job-forge next-num"
         ]

package/templates/migrations.json

@@ -33,6 +33,10 @@
             "index:has": "job-forge index:has",
             "index:query": "job-forge index:query",
             "index:explain": "job-forge index:explain",
+            "canon:normalize": "job-forge canon:normalize",
+            "canon:key": "job-forge canon:key",
+            "canon:compare": "job-forge canon:compare",
+            "canon:explain": "job-forge canon:explain",
             "migrate:plan": "job-forge migrate:plan",
             "migrate:apply": "job-forge migrate:apply",
             "migrate:check": "job-forge migrate:check",