job-forge 2.14.24 → 2.14.26

package/.cursor/rules/main.mdc

@@ -77,11 +77,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D13] Use `job-forge index:*` for deterministic artifact lookup when available. `index:has` and `index:query` rebuild `.jobforge-index.json` from `templates/index.json` on demand, covering reports, tracker day files, tracker TSVs, pipeline URLs, scan history, and ledger events without loading those growing files into prompt context.
   why: `iso-index` is not an MCP and adds no prompt/tool-schema tokens; it gives agents compact file/line pointers and duplicate prefilters before expensive reads or browser dispatches
 
+- [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
+
 ## 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]. Decide inline vs delegated work [D1].
+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].
 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].

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

@@ -78,6 +78,11 @@ Local artifact index (terminal, outside opencode):
   npx job-forge index:has --key "company-role:acme:staff-engineer"
   npx job-forge index:query "acme"
 
+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
+  npx job-forge migrate:check          # fail if migrations are pending
+
 Artifact contracts (terminal, outside opencode):
   npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
   npx job-forge tracker-line ... --write   # renders + validates tracker TSV locally

package/AGENTS.md

@@ -72,11 +72,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D13] Use `job-forge index:*` for deterministic artifact lookup when available. `index:has` and `index:query` rebuild `.jobforge-index.json` from `templates/index.json` on demand, covering reports, tracker day files, tracker TSVs, pipeline URLs, scan history, and ledger events without loading those growing files into prompt context.
   why: `iso-index` is not an MCP and adds no prompt/tool-schema tokens; it gives agents compact file/line pointers and duplicate prefilters before expensive reads or browser dispatches
 
+- [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
+
 ## 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]. Decide inline vs delegated work [D1].
+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].
 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].

package/CLAUDE.md

@@ -72,11 +72,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D13] Use `job-forge index:*` for deterministic artifact lookup when available. `index:has` and `index:query` rebuild `.jobforge-index.json` from `templates/index.json` on demand, covering reports, tracker day files, tracker TSVs, pipeline URLs, scan history, and ledger events without loading those growing files into prompt context.
   why: `iso-index` is not an MCP and adds no prompt/tool-schema tokens; it gives agents compact file/line pointers and duplicate prefilters before expensive reads or browser dispatches
 
+- [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
+
 ## 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]. Decide inline vs delegated work [D1].
+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].
 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].

package/README.md

@@ -31,13 +31,13 @@ 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`, `.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/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.
 
 Then fill in `cv.md`, `config/profile.yml`, and `portals.yml` with your personal data, paste a job URL into opencode, and JobForge evaluates + tracks it.
 
-**Upgrade later:** `npm run update-harness` (pulls latest `job-forge` from npm, re-syncs symlinks, prints the resolved version)
+**Upgrade later:** `npm run update-harness` (pulls latest `job-forge` from npm, re-syncs symlinks, applies safe consumer migrations, prints the resolved version)
 
 Full setup guide and alternative install paths (including contributing to the harness itself): **[docs/SETUP.md](docs/SETUP.md)**.
 
@@ -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** | `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, and `job-forge index:*` queries compact source pointers without MCP/tool-schema overhead. |
+| **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. |
 | **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
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, 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
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, 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
+│   ├── migrate.mjs               # iso-migrate-backed consumer-project migrations
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish
 ├── tracker-lib.mjs / merge-tracker.mjs / dedup-tracker.mjs / verify-pipeline.mjs

package/bin/create-job-forge.mjs

@@ -124,11 +124,33 @@ const consumerPkg = {
     'ledger:verify': 'job-forge ledger:verify',
     'ledger:has': 'job-forge ledger:has',
     'ledger:query': 'job-forge ledger:query',
+    'capabilities:list': 'job-forge capabilities:list',
+    'capabilities:explain': 'job-forge capabilities:explain',
+    'capabilities:check': 'job-forge capabilities:check',
+    'capabilities:render': 'job-forge capabilities:render',
+    'context:list': 'job-forge context:list',
+    'context:explain': 'job-forge context:explain',
+    'context:plan': 'job-forge context:plan',
+    'context:check': 'job-forge context:check',
+    'context:render': 'job-forge context:render',
+    'cache:key': 'job-forge cache:key',
+    'cache:has': 'job-forge cache:has',
+    'cache:get': 'job-forge cache:get',
+    'cache:put': 'job-forge cache:put',
+    'cache:status': 'job-forge cache:status',
+    'cache:list': 'job-forge cache:list',
+    'cache:verify': 'job-forge cache:verify',
+    'cache:prune': 'job-forge cache:prune',
     'index:build': 'job-forge index:build',
     'index:status': 'job-forge index:status',
     'index:verify': 'job-forge index:verify',
     'index:has': 'job-forge index:has',
     'index:query': 'job-forge index:query',
+    'index:explain': 'job-forge index:explain',
+    'migrate:plan': 'job-forge migrate:plan',
+    'migrate:apply': 'job-forge migrate:apply',
+    'migrate:check': 'job-forge migrate:check',
+    'migrate:explain': 'job-forge migrate:explain',
     // One command to pull the latest harness and any locally-pinned MCP
     // packages. npm update is a no-op on packages not in package.json, so
     // listing @razroo/gmail-mcp + @geometra/mcp is safe for consumers that
@@ -230,6 +252,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:*\` |
+| 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 |
 | CV | \`cv.md\` (project root) | Markdown, source of truth |
@@ -379,6 +402,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 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
+ *   migrate:*      Apply deterministic consumer-project migrations via iso-migrate
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -127,6 +128,14 @@ const indexAliases = {
   'index:path': 'path',
 };
 
+const migrateAliases = {
+  'migrate:plan': 'plan',
+  'migrate:apply': 'apply',
+  'migrate:check': 'check',
+  'migrate:explain': 'explain',
+  'migrate:path': 'path',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -177,6 +186,10 @@ 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
+  migrate:plan            Preview deterministic consumer-project migrations
+  migrate:apply           Apply deterministic consumer-project migrations
+  migrate:check           Fail if migrations are pending
+  migrate:explain         Show the active migration policy
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -215,6 +228,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 migrate:check
+  job-forge migrate:apply
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -344,6 +359,21 @@ if (cmd === 'index' || indexAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'migrate' || migrateAliases[cmd]) {
+  const migrateArgs = cmd === 'migrate'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [migrateAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/migrate.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...migrateArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 const rel = commands[cmd];
 if (!rel) {
   console.error(`Unknown command: ${cmd}\n`);

package/bin/sync.mjs

@@ -23,6 +23,11 @@
 import { existsSync, lstatSync, readlinkSync, symlinkSync, mkdirSync, readFileSync } from 'fs';
 import { dirname, join, resolve, relative } from 'path';
 import { fileURLToPath } from 'url';
+import {
+  loadMigrationConfig,
+  parseJson,
+  runMigrations,
+} from '@razroo/iso-migrate';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -149,4 +154,29 @@ for (const { src, dst } of links) {
   }
 }
 
+try {
+  const migrationResult = applyConsumerMigrations();
+  if (migrationResult?.changeCount > 0) {
+    console.log(`\njob-forge migrate: applied ${migrationResult.changeCount} change(s)`);
+  }
+} catch (error) {
+  console.warn(`\n  warn: job-forge migrations skipped: ${error instanceof Error ? error.message : String(error)}`);
+  warned++;
+}
+
 console.log(`\njob-forge sync: ${created} created, ${skipped} up-to-date, ${warned} warnings (project: ${PROJECT_DIR})`);
+
+function applyConsumerMigrations() {
+  const skip = process.env.JOB_FORGE_SKIP_MIGRATIONS;
+  if (skip === '1' || skip === 'true') return null;
+  if (!existsSync(join(PROJECT_DIR, 'package.json'))) return null;
+
+  const configPath = process.env.JOB_FORGE_MIGRATIONS_CONFIG || join(PKG_ROOT, 'templates', 'migrations.json');
+  if (!existsSync(configPath)) return null;
+
+  const config = loadMigrationConfig(parseJson(readFileSync(configPath, 'utf8'), configPath));
+  return runMigrations(config, {
+    root: PROJECT_DIR,
+    dryRun: false,
+  });
+}

package/docs/ARCHITECTURE.md

@@ -48,7 +48,7 @@ The skill router (`.opencode/skills/job-forge.md`) loads mode and data files on
 
 **Multi-harness support.** Because `iso/` is the single source of truth, publishing ships config for OpenCode, Cursor, Claude Code, and Codex in one tarball. Consumers run any of `opencode`, `cursor`, `claude`, or `codex` in the project and each picks up the shared MCP config + instructions via the symlinks above.
 
-**Upgrading** the harness in a consumer project is `npm run update-harness` — pulls the latest `job-forge` from npm, refreshes pinned MCPs, re-runs symlink sync, and prints the resolved version.
+**Upgrading** the harness in a consumer project is `npm run update-harness` — pulls the latest `job-forge` from npm, refreshes pinned MCPs, re-runs symlink sync, applies safe consumer migrations, and prints the resolved version.
 
 ## System Overview
 
@@ -165,6 +165,7 @@ data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/p
 jds/*.md                 →  Saved job descriptions referenced from the pipeline (`local:jds/{file}`)
 templates/states.yml     →  Canonical status values
 templates/context.json    →  Deterministic mode/reference context bundle policy
+templates/migrations.json → Safe consumer-project upgrade policy
 templates/cv-template.html → PDF generation template
 examples/*.md            →  Fictional layouts only (not read by scripts; see examples/README.md)
 ```
@@ -178,6 +179,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)
+- 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:*`)
 
@@ -224,8 +226,9 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `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/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 |
-| `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project (also runs as `postinstall`) |
+| `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project and applies safe migrations (also runs as `postinstall`) |
 | `bin/create-job-forge.mjs` | `npx create-job-forge <dir>` | Scaffolds a new personal project |
 
 All scripts resolve the consumer project dir via `process.env.JOB_FORGE_PROJECT || process.cwd()`, so running the CLI from anywhere in the consumer project Just Works.

package/docs/CUSTOMIZATION.md

@@ -154,6 +154,10 @@ Mode/reference context bundles live in `templates/context.json` and are planned
 
 Artifact lookup policy lives in `templates/index.json` and is built locally by `@razroo/iso-index`. Use `job-forge index:has --key "company-role:acme:staff-engineer"` as a cheap duplicate/source prefilter, `job-forge index:query "acme"` to get compact source path/line pointers, and `job-forge index:verify` to validate `.jobforge-index.json`. Query, has, and verify rebuild the index on demand, so scaffolded projects need no setup. This is not an MCP and does not add tool-schema tokens.
 
+## JobForge consumer migrations
+
+Consumer-project migrations live in `templates/migrations.json` and are applied locally by `@razroo/iso-migrate`. `job-forge sync` applies safe migrations automatically after refreshing symlinks; use `JOB_FORGE_SKIP_MIGRATIONS=1` to opt out. Use `job-forge migrate:plan`, `job-forge migrate:apply`, and `job-forge migrate:check` to inspect or enforce script/gitignore drift explicitly. This is not an MCP and does not add prompt or tool-schema tokens.
+
 ## JobForge guard audits
 
 Guard audits run deterministic `@razroo/iso-guard` policies over the same local OpenCode traces. The default policy lives at `templates/guards/jobforge-baseline.yaml` and checks rules that are reliable from transcript data, including max two task dispatches per assistant message, no task-status polling via `task`, no raw proxy configuration in task prompts, and no child session task recursion.

package/docs/SETUP.md

@@ -130,6 +130,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Inspect context bundle budget | `npx job-forge context:plan apply` | `npm run context:plan -- apply` |
 | Inspect local JD/artifact cache | `npx job-forge cache:status` | `npm run cache:status` |
 | Inspect local artifact index | `npx job-forge index:status` | `npm run index:status` |
+| Inspect pending consumer migrations | `npx job-forge migrate:plan` | `npm run migrate:plan` |
 | Map status column to canonical labels | `npx job-forge normalize` | `npm run normalize` |
 | Merge duplicate company/role rows | `npx job-forge dedup` | `npm run dedup` |
 | Generate ATS-optimized CV PDF | `npx job-forge pdf` | `npm run pdf` |
@@ -148,6 +149,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Check duplicate/status event without loading tracker files | `npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied` | `npm run ledger:has -- --company ...` |
 | Check/reuse cached JD content | `npx job-forge cache:has --url <url>` / `npx job-forge cache:get --url <url>` | `npm run cache:has -- --url ...` |
 | Query local artifact pointers | `npx job-forge index:query "Acme"` / `npx job-forge index:has --key company-role:acme:staff-engineer` | `npm run index:query -- Acme` |
+| Apply safe consumer migrations | `npx job-forge migrate:apply` | `npm run migrate:apply` |
 | Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
 | Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |
 

package/iso/commands/job-forge.md

@@ -81,6 +81,11 @@ Local artifact index (terminal, outside opencode):
   npx job-forge index:has --key "company-role:acme:staff-engineer"
   npx job-forge index:query "acme"
 
+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
+  npx job-forge migrate:check          # fail if migrations are pending
+
 Artifact contracts (terminal, outside opencode):
   npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
   npx job-forge tracker-line ... --write   # renders + validates tracker TSV locally

package/iso/instructions.md

@@ -72,11 +72,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D13] Use `job-forge index:*` for deterministic artifact lookup when available. `index:has` and `index:query` rebuild `.jobforge-index.json` from `templates/index.json` on demand, covering reports, tracker day files, tracker TSVs, pipeline URLs, scan history, and ledger events without loading those growing files into prompt context.
   why: `iso-index` is not an MCP and adds no prompt/tool-schema tokens; it gives agents compact file/line pointers and duplicate prefilters before expensive reads or browser dispatches
 
+- [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
+
 ## 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]. Decide inline vs delegated work [D1].
+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].
 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].

package/lib/jobforge-migrate.mjs

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  loadMigrationConfig,
+  parseJson,
+  runMigrations,
+} from '@razroo/iso-migrate';
+
+export const MIGRATION_CONFIG_FILE = 'templates/migrations.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeMigrationConfigPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_MIGRATIONS_CONFIG || join(projectDir, MIGRATION_CONFIG_FILE);
+}
+
+export function migrationConfigExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeMigrationConfigPath(projectDir));
+}
+
+export function readJobForgeMigrationConfig(projectDir = resolveProjectDir()) {
+  const path = jobForgeMigrationConfigPath(projectDir);
+  return loadMigrationConfig(parseJson(readFileSync(path, 'utf8'), path));
+}
+
+export function runJobForgeMigrations(options = {}, projectDir = resolveProjectDir()) {
+  return runMigrations(readJobForgeMigrationConfig(projectDir), {
+    root: options.root || projectDir,
+    dryRun: options.dryRun,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.24",
+  "version": "2.14.26",
   "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",
+    "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",
+    "migrate:explain": "node bin/job-forge.mjs migrate:explain",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -128,6 +132,7 @@
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-index": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",
+    "@razroo/iso-migrate": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"

package/scripts/migrate.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatConfigSummary,
+  formatMigrationResult,
+} from '@razroo/iso-migrate';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  jobForgeMigrationConfigPath,
+  readJobForgeMigrationConfig,
+  runJobForgeMigrations,
+} from '../lib/jobforge-migrate.mjs';
+
+const USAGE = `job-forge migrate - deterministic consumer-project migrations
+
+Usage:
+  job-forge migrate:plan [--json]
+  job-forge migrate:apply [--json]
+  job-forge migrate:check [--json]
+  job-forge migrate:explain [--json]
+  job-forge migrate:path
+
+The policy is templates/migrations.json. Sync applies these migrations
+automatically unless JOB_FORGE_SKIP_MIGRATIONS=1 is set.`;
+
+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(jobForgeMigrationConfigPath(PROJECT_DIR));
+  } else if (cmd === 'plan') {
+    run('plan', opts);
+  } else if (cmd === 'apply') {
+    run('apply', opts);
+  } else if (cmd === 'check') {
+    const result = run('check', opts);
+    process.exit(result.changed ? 1 : 0);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown migrate command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = { json: false, help: false };
+  for (const arg of args) {
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw new Error(`unknown flag "${arg}"`);
+  }
+  return opts;
+}
+
+function run(mode, opts) {
+  const result = runJobForgeMigrations({ dryRun: mode !== 'apply' }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatMigrationResult(result, mode));
+  }
+  return result;
+}
+
+function explain(opts) {
+  const config = readJobForgeMigrationConfig(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeMigrationConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary(config));
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/templates/index.json

@@ -46,7 +46,7 @@
         },
         {
           "kind": "jobforge.report-ref",
-          "key": "{Report}",
+          "key": "report-ref:{source}:{line}",
           "value": "{Company} - {Role}",
           "fields": {
             "company": "{Company}",

package/templates/migrations.json

@@ -0,0 +1,63 @@
+{
+  "version": 1,
+  "migrations": [
+    {
+      "id": "jobforge-managed-scripts",
+      "description": "Expose JobForge's deterministic consumer-project helper commands.",
+      "operations": [
+        {
+          "type": "json-merge",
+          "path": "package.json",
+          "pointer": "/scripts",
+          "value": {
+            "capabilities:list": "job-forge capabilities:list",
+            "capabilities:explain": "job-forge capabilities:explain",
+            "capabilities:check": "job-forge capabilities:check",
+            "capabilities:render": "job-forge capabilities:render",
+            "context:list": "job-forge context:list",
+            "context:explain": "job-forge context:explain",
+            "context:plan": "job-forge context:plan",
+            "context:check": "job-forge context:check",
+            "context:render": "job-forge context:render",
+            "cache:key": "job-forge cache:key",
+            "cache:has": "job-forge cache:has",
+            "cache:get": "job-forge cache:get",
+            "cache:put": "job-forge cache:put",
+            "cache:status": "job-forge cache:status",
+            "cache:list": "job-forge cache:list",
+            "cache:verify": "job-forge cache:verify",
+            "cache:prune": "job-forge cache:prune",
+            "index:build": "job-forge index:build",
+            "index:status": "job-forge index:status",
+            "index:verify": "job-forge index:verify",
+            "index:has": "job-forge index:has",
+            "index:query": "job-forge index:query",
+            "index:explain": "job-forge index:explain",
+            "migrate:plan": "job-forge migrate:plan",
+            "migrate:apply": "job-forge migrate:apply",
+            "migrate:check": "job-forge migrate:check",
+            "migrate:explain": "job-forge migrate:explain"
+          }
+        }
+      ]
+    },
+    {
+      "id": "jobforge-generated-ignores",
+      "description": "Keep generated JobForge runtime artifacts out of consumer git state.",
+      "operations": [
+        {
+          "type": "ensure-lines",
+          "path": ".gitignore",
+          "create": true,
+          "after": "# Generated",
+          "lines": [
+            ".jobforge-runs/",
+            ".jobforge-ledger/",
+            ".jobforge-cache/",
+            ".jobforge-index.json"
+          ]
+        }
+      ]
+    }
+  ]
+}