job-forge 2.14.20 → 2.14.22

package/.cursor/rules/main.mdc

@@ -30,7 +30,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H6] Application outcomes flow through `batch/tracker-additions/*.tsv`, not `data/pipeline.md`. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` then `npx job-forge verify` before ending the session.
   why: `pipeline.md` is the URL inbox (`[ ]` pending → `[x]` processed); `data/applications/YYYY-MM-DD.md` is the outcome log; the TSV pathway is the only safe bridge because `merge` handles column order and duplicate detection
 
-- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
+- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
 - [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
@@ -71,11 +71,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
   why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
 
+- [D12] Use `job-forge cache:*` for deterministic local artifact reuse when available. For URL inputs, check `npx job-forge cache:has --url "..."` / `cache:get` before browser or network JD fetches; after a successful fetch, store the exact JD text with `npx job-forge cache:put --url "..." --ttl 14d --input @file` when it is already on disk.
+  why: `iso-cache` is not an MCP and adds no prompt/tool-schema tokens; it avoids repeated JD fetch/render passes and lets future sessions reuse stable content from `.jobforge-cache/`
+
 ## 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]; 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]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], 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/AGENTS.md

@@ -25,7 +25,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H6] Application outcomes flow through `batch/tracker-additions/*.tsv`, not `data/pipeline.md`. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` then `npx job-forge verify` before ending the session.
   why: `pipeline.md` is the URL inbox (`[ ]` pending → `[x]` processed); `data/applications/YYYY-MM-DD.md` is the outcome log; the TSV pathway is the only safe bridge because `merge` handles column order and duplicate detection
 
-- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
+- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
 - [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
@@ -66,11 +66,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
   why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
 
+- [D12] Use `job-forge cache:*` for deterministic local artifact reuse when available. For URL inputs, check `npx job-forge cache:has --url "..."` / `cache:get` before browser or network JD fetches; after a successful fetch, store the exact JD text with `npx job-forge cache:put --url "..." --ttl 14d --input @file` when it is already on disk.
+  why: `iso-cache` is not an MCP and adds no prompt/tool-schema tokens; it avoids repeated JD fetch/render passes and lets future sessions reuse stable content from `.jobforge-cache/`
+
 ## 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]; 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]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], 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

@@ -25,7 +25,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H6] Application outcomes flow through `batch/tracker-additions/*.tsv`, not `data/pipeline.md`. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` then `npx job-forge verify` before ending the session.
   why: `pipeline.md` is the URL inbox (`[ ]` pending → `[x]` processed); `data/applications/YYYY-MM-DD.md` is the outcome log; the TSV pathway is the only safe bridge because `merge` handles column order and duplicate detection
 
-- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
+- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
 - [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
@@ -66,11 +66,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
   why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
 
+- [D12] Use `job-forge cache:*` for deterministic local artifact reuse when available. For URL inputs, check `npx job-forge cache:has --url "..."` / `cache:get` before browser or network JD fetches; after a successful fetch, store the exact JD text with `npx job-forge cache:put --url "..." --ttl 14d --input @file` when it is already on disk.
+  why: `iso-cache` is not an MCP and adds no prompt/tool-schema tokens; it avoids repeated JD fetch/render passes and lets future sessions reuse stable content from `.jobforge-cache/`
+
 ## 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]; 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]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], 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,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`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. 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`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, and `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`. 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** | `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, and `job-forge context:*` plans mode/reference context bundles without MCP/tool-schema overhead. |
+| **Trace + Telemetry + Guard + Contract + Ledger + Capabilities + Context + Cache** | `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, and `job-forge cache:*` reuses fetched JD/artifact content 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
@@ -146,6 +146,7 @@ my-search/
 ├── config/profile.yml            # your identity, target roles (personal)
 ├── data/                         # applications, pipeline, scan history (personal, gitignored)
 ├── .jobforge-ledger/              # append-only local workflow events (personal, gitignored)
+├── .jobforge-cache/               # content-addressed local JD/artifact cache (personal, gitignored)
 ├── reports/                      # generated evaluation reports (personal, gitignored)
 ├── batch/{batch-input,batch-state}.tsv, tracker-additions/, logs/   # personal
 ├── .jobforge-runs/                # durable batch workflow records (generated)
@@ -197,6 +198,7 @@ JobForge/
 │   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
 │   ├── capabilities.mjs          # iso-capabilities-backed role policy CLI
 │   ├── context.mjs               # iso-context-backed context bundle CLI
+│   ├── cache.mjs                 # iso-cache-backed local artifact cache CLI
 │   ├── 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/job-forge.mjs

@@ -23,6 +23,7 @@
  *   ledger:*       Query local deterministic workflow state via iso-ledger
  *   capabilities:* Query role capability policy via iso-capabilities
  *   context:*      Query/render deterministic context bundles via iso-context
+ *   cache:*        Reuse local deterministic artifacts via iso-cache
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -103,6 +104,18 @@ const contextAliases = {
   'context:path': 'path',
 };
 
+const cacheAliases = {
+  'cache:key': 'key',
+  'cache:status': 'status',
+  'cache:has': 'has',
+  'cache:get': 'get',
+  'cache:put': 'put',
+  'cache:list': 'list',
+  'cache:verify': 'verify',
+  'cache:prune': 'prune',
+  'cache:path': 'path',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -142,6 +155,12 @@ Commands:
   context:plan            Estimate files/tokens for one context bundle
   context:check           Fail if a context bundle exceeds its budget
   context:render          Render context bundle content as markdown/json
+  cache:status            Show local artifact cache status
+  cache:key               Print deterministic cache key for a job URL
+  cache:has               Check whether a job URL or cache key is cached
+  cache:get               Read cached JD/artifact content
+  cache:put               Store JD/artifact content
+  cache:verify            Validate local artifact cache integrity
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -175,6 +194,9 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge capabilities:check general-free --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write
   job-forge context:plan apply
   job-forge context:check apply --budget 23000
+  job-forge cache:has --url https://example.test/jobs/123
+  job-forge cache:get --url https://example.test/jobs/123
+  job-forge cache:put --url https://example.test/jobs/123 --input @jds/example.md
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -274,6 +296,21 @@ if (cmd === 'context' || contextAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'cache' || cacheAliases[cmd]) {
+  const cacheArgs = cmd === 'cache'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [cacheAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/cache.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...cacheArgs], {
+    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/docs/SETUP.md

@@ -128,6 +128,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Inspect tracker row contract | `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` | _(none)_ |
 | 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` |
 | 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` |
@@ -144,6 +145,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Show local workflow ledger status | `npx job-forge ledger:status` | `npm run ledger:status` |
 | Rebuild local workflow ledger from tracker/pipeline files | `npx job-forge ledger:rebuild` | `npm run ledger:rebuild` |
 | 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 ...` |
 | Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
 | Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |
 

package/iso/instructions.md

@@ -25,7 +25,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H6] Application outcomes flow through `batch/tracker-additions/*.tsv`, not `data/pipeline.md`. After any multi-apply run, the orchestrator MUST run `npx job-forge merge` then `npx job-forge verify` before ending the session.
   why: `pipeline.md` is the URL inbox (`[ ]` pending → `[x]` processed); `data/applications/YYYY-MM-DD.md` is the outcome log; the TSV pathway is the only safe bridge because `merge` handles column order and duplicate detection
 
-- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`.
+- [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
 - [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
@@ -66,11 +66,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
   why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
 
+- [D12] Use `job-forge cache:*` for deterministic local artifact reuse when available. For URL inputs, check `npx job-forge cache:has --url "..."` / `cache:get` before browser or network JD fetches; after a successful fetch, store the exact JD text with `npx job-forge cache:put --url "..." --ttl 14d --input @file` when it is already on disk.
+  why: `iso-cache` is not an MCP and adds no prompt/tool-schema tokens; it avoids repeated JD fetch/render passes and lets future sessions reuse stable content from `.jobforge-cache/`
+
 ## 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]; 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]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], 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-cache.mjs

@@ -0,0 +1,105 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import {
+  cacheKey,
+  hasCacheEntry,
+  listCacheEntries,
+  pruneCache,
+  putCacheEntry,
+  readCacheContent,
+  resolveCacheDir,
+  verifyCache,
+} from '@razroo/iso-cache';
+
+export const CACHE_DIR = '.jobforge-cache';
+export const JD_CACHE_NAMESPACE = 'jobforge.jd';
+export const JD_CACHE_VERSION = '1';
+export const JD_CACHE_KIND = 'jd';
+export const DEFAULT_JD_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeCacheDir(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_CACHE || join(projectDir, CACHE_DIR);
+}
+
+export function jobForgeCacheSummary(projectDir = resolveProjectDir()) {
+  const root = resolveCacheDir(jobForgeCacheDir(projectDir));
+  const entries = listCacheEntries(root, { includeExpired: true });
+  return {
+    root,
+    exists: existsSync(root),
+    entries: entries.length,
+    active: entries.filter((entry) => !entry.expiresAt || new Date(entry.expiresAt).getTime() > Date.now()).length,
+  };
+}
+
+export function jobDescriptionCacheKey(url) {
+  return cacheKey({
+    namespace: JD_CACHE_NAMESPACE,
+    version: JD_CACHE_VERSION,
+    parts: { url: normalizeJobUrl(url) },
+  });
+}
+
+export function putJobDescriptionCache(url, content, options = {}, projectDir = resolveProjectDir()) {
+  const normalizedUrl = normalizeJobUrl(url);
+  return putCacheEntry(
+    jobForgeCacheDir(projectDir),
+    jobDescriptionCacheKey(normalizedUrl),
+    content,
+    {
+      kind: options.kind || JD_CACHE_KIND,
+      contentType: options.contentType || 'text/markdown',
+      ttlMs: options.expiresAt ? undefined : (options.ttlMs ?? DEFAULT_JD_TTL_MS),
+      expiresAt: options.expiresAt,
+      metadata: {
+        url: normalizedUrl,
+        source: options.source || 'job-forge',
+        ...(options.metadata || {}),
+      },
+    },
+  );
+}
+
+export function readJobDescriptionCache(url, options = {}, projectDir = resolveProjectDir()) {
+  return readCacheContent(jobForgeCacheDir(projectDir), jobDescriptionCacheKey(url), options);
+}
+
+export function hasJobDescriptionCache(url, options = {}, projectDir = resolveProjectDir()) {
+  return hasCacheEntry(jobForgeCacheDir(projectDir), jobDescriptionCacheKey(url), options);
+}
+
+export function readJobForgeCache(key, options = {}, projectDir = resolveProjectDir()) {
+  return readCacheContent(jobForgeCacheDir(projectDir), key, options);
+}
+
+export function putJobForgeCache(key, content, options = {}, projectDir = resolveProjectDir()) {
+  return putCacheEntry(jobForgeCacheDir(projectDir), key, content, options);
+}
+
+export function listJobForgeCache(options = {}, projectDir = resolveProjectDir()) {
+  return listCacheEntries(jobForgeCacheDir(projectDir), options);
+}
+
+export function verifyJobForgeCache(projectDir = resolveProjectDir()) {
+  return verifyCache(jobForgeCacheDir(projectDir));
+}
+
+export function pruneJobForgeCache(options = {}, projectDir = resolveProjectDir()) {
+  return pruneCache(jobForgeCacheDir(projectDir), options);
+}
+
+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();
+  } catch {
+    return text;
+  }
+}

package/modes/auto-pipeline.md

@@ -21,7 +21,9 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 
 **If the input is JD text** (not a URL): use it directly, no fetching needed.
 
-**Local artifacts before Step 0 methods:** Grep `reports/` for the URL or stable company+role slug; if a report already embeds the full JD, Read it and skip network fetch entirely. If the pipeline row or `jds/` references `local:jds/{file}`, Read that file first. This stacks with the rule above: one fetch per URL per session, and **zero** if the JD is already on disk.
+**Local artifacts before Step 0 methods:** Grep `reports/` for the URL or stable company+role slug; if a report already embeds the full JD, Read it and skip network fetch entirely. If the pipeline row or `jds/` references `local:jds/{file}`, Read that file first. For URL inputs, run `npx job-forge cache:has --url "{url}"` and then `npx job-forge cache:get --url "{url}"` on a hit; cached JD text is authoritative local content and avoids a browser/network fetch. This stacks with the rule above: one fetch per URL per session, and **zero** if the JD is already on disk or in `.jobforge-cache/`.
+
+**Cache after a successful fetch:** If the JD text is written to `jds/` or embedded in a report, store that exact text with `npx job-forge cache:put --url "{url}" --ttl 14d --input @path/to/jd.md`. Do not refetch just to populate the cache.
 
 ## Step 1 — Run Evaluation A-F
 Execute exactly as in the `offer` mode (read `modes/offer.md` for all blocks A-F).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.20",
+  "version": "2.14.22",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -41,6 +41,14 @@
     "context:plan": "node bin/job-forge.mjs context:plan",
     "context:check": "node bin/job-forge.mjs context:check",
     "context:render": "node bin/job-forge.mjs context:render",
+    "cache:key": "node bin/job-forge.mjs cache:key",
+    "cache:has": "node bin/job-forge.mjs cache:has",
+    "cache:get": "node bin/job-forge.mjs cache:get",
+    "cache:put": "node bin/job-forge.mjs cache:put",
+    "cache:status": "node bin/job-forge.mjs cache:status",
+    "cache:list": "node bin/job-forge.mjs cache:list",
+    "cache:verify": "node bin/job-forge.mjs cache:verify",
+    "cache:prune": "node bin/job-forge.mjs cache:prune",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -58,7 +66,9 @@
     "bin/",
     "iso/",
     "models.yaml",
-    ".claude/",
+    ".claude/settings.json",
+    ".claude/iso-route.resolved.json",
+    ".claude/agents/",
     ".cursor/mcp.json",
     ".cursor/rules/",
     ".cursor/iso-route.md",
@@ -106,6 +116,7 @@
   },
   "dependencies": {
     "@razroo/iso-capabilities": "^0.1.0",
+    "@razroo/iso-cache": "^0.1.0",
     "@razroo/iso-context": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",

package/scripts/cache.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'fs';
+import {
+  formatCacheEntries,
+  formatPruneResult,
+  formatVerifyResult,
+} from '@razroo/iso-cache';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  DEFAULT_JD_TTL_MS,
+  JD_CACHE_KIND,
+  jobDescriptionCacheKey,
+  jobForgeCacheDir,
+  jobForgeCacheSummary,
+  listJobForgeCache,
+  pruneJobForgeCache,
+  putJobDescriptionCache,
+  putJobForgeCache,
+  readJobDescriptionCache,
+  readJobForgeCache,
+  verifyJobForgeCache,
+} from '../lib/jobforge-cache.mjs';
+
+const USAGE = `job-forge cache - local deterministic artifact cache
+
+Usage:
+  job-forge cache:key --url <url> [--json]
+  job-forge cache:status [--json]
+  job-forge cache:has (--url <url> | --key <key>) [--allow-expired] [--json]
+  job-forge cache:get (--url <url> | --key <key>) [--allow-expired] [--output <file>] [--json]
+  job-forge cache:put (--url <url> | --key <key>) --input <text|@file|-> [--ttl 14d] [--kind <kind>] [--content-type <type>] [--meta <json|@file>] [--json]
+  job-forge cache:list [--kind <kind>] [--include-expired] [--json]
+  job-forge cache:verify [--json]
+  job-forge cache:prune [--expired] [--dry-run] [--json]
+  job-forge cache:path
+
+Default path is .jobforge-cache/ unless JOB_FORGE_CACHE is set. This is local
+project state, not an MCP and not prompt context.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeCacheDir(PROJECT_DIR));
+  } else if (cmd === 'key') {
+    key(opts);
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'has') {
+    has(opts);
+  } else if (cmd === 'get') {
+    get(opts);
+  } else if (cmd === 'put') {
+    put(opts);
+  } else if (cmd === 'list') {
+    list(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'prune') {
+    prune(opts);
+  } else {
+    console.error(`unknown cache 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,
+    allowExpired: false,
+    includeExpired: false,
+    dryRun: false,
+    expired: false,
+    ttlMs: DEFAULT_JD_TTL_MS,
+    metadata: {},
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--url') {
+      opts.url = valueAfter(args, ++i, '--url');
+    } else if (arg.startsWith('--url=')) {
+      opts.url = arg.slice('--url='.length);
+    } else if (arg === '--key') {
+      opts.key = valueAfter(args, ++i, '--key');
+    } else if (arg.startsWith('--key=')) {
+      opts.key = arg.slice('--key='.length);
+    } else if (arg === '--input') {
+      opts.input = valueAfter(args, ++i, '--input');
+    } else if (arg.startsWith('--input=')) {
+      opts.input = arg.slice('--input='.length);
+    } else if (arg === '--output') {
+      opts.output = valueAfter(args, ++i, '--output');
+    } else if (arg.startsWith('--output=')) {
+      opts.output = arg.slice('--output='.length);
+    } else if (arg === '--kind') {
+      opts.kind = valueAfter(args, ++i, '--kind');
+    } else if (arg.startsWith('--kind=')) {
+      opts.kind = arg.slice('--kind='.length);
+    } else if (arg === '--content-type') {
+      opts.contentType = valueAfter(args, ++i, '--content-type');
+    } else if (arg.startsWith('--content-type=')) {
+      opts.contentType = arg.slice('--content-type='.length);
+    } else if (arg === '--ttl') {
+      opts.ttlMs = parseDuration(valueAfter(args, ++i, '--ttl'));
+    } else if (arg.startsWith('--ttl=')) {
+      opts.ttlMs = parseDuration(arg.slice('--ttl='.length));
+    } else if (arg === '--expires-at') {
+      opts.expiresAt = valueAfter(args, ++i, '--expires-at');
+      opts.ttlMs = undefined;
+    } else if (arg.startsWith('--expires-at=')) {
+      opts.expiresAt = arg.slice('--expires-at='.length);
+      opts.ttlMs = undefined;
+    } else if (arg === '--meta') {
+      opts.metadata = parseMetadata(valueAfter(args, ++i, '--meta'));
+    } else if (arg.startsWith('--meta=')) {
+      opts.metadata = parseMetadata(arg.slice('--meta='.length));
+    } else if (arg === '--allow-expired') {
+      opts.allowExpired = true;
+    } else if (arg === '--include-expired') {
+      opts.includeExpired = true;
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true;
+    } else if (arg === '--expired') {
+      opts.expired = true;
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function key(opts) {
+  const keyValue = keyFromOptions(opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ key: keyValue, url: opts.url || null }, null, 2));
+    return;
+  }
+  console.log(keyValue);
+}
+
+function status(opts) {
+  const summary = jobForgeCacheSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(`cache:   ${summary.root}`);
+  console.log(`exists:  ${summary.exists ? 'yes' : 'no'}`);
+  console.log(`entries: ${summary.active} active, ${summary.entries - summary.active} expired`);
+}
+
+function has(opts) {
+  const hit = read(opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ hit: Boolean(hit?.hit), stale: Boolean(hit?.stale), key: keyFromOptions(opts) }, null, 2));
+  } else {
+    console.log(hit?.hit ? `HIT${hit.stale ? ' stale' : ''}` : 'MISS');
+  }
+  process.exit(hit?.hit ? 0 : 1);
+}
+
+function get(opts) {
+  const hit = read(opts);
+  if (!hit?.hit || hit.content === undefined) {
+    if (opts.json) {
+      console.log(JSON.stringify({ hit: false, stale: Boolean(hit?.stale), key: keyFromOptions(opts) }, null, 2));
+    } else {
+      console.log('MISS');
+    }
+    process.exit(1);
+  }
+  if (opts.output) {
+    writeFileSync(opts.output, hit.content, 'utf8');
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ hit: true, stale: hit.stale, entry: hit.entry, content: opts.output ? undefined : hit.content }, null, 2));
+  } else if (opts.output) {
+    console.log(`WROTE ${opts.output}`);
+  } else {
+    process.stdout.write(hit.content);
+    if (!hit.content.endsWith('\n')) process.stdout.write('\n');
+  }
+}
+
+function put(opts) {
+  if (!opts.input) throw new Error('cache:put requires --input <text|@file|->');
+  const content = readInput(opts.input);
+  const entry = opts.url
+    ? putJobDescriptionCache(opts.url, content, {
+      kind: opts.kind || JD_CACHE_KIND,
+      contentType: opts.contentType,
+      ttlMs: opts.ttlMs,
+      expiresAt: opts.expiresAt,
+      metadata: opts.metadata,
+    }, PROJECT_DIR)
+    : putJobForgeCache(requiredKey(opts), content, {
+      kind: opts.kind,
+      contentType: opts.contentType,
+      ttlMs: opts.expiresAt ? undefined : opts.ttlMs,
+      expiresAt: opts.expiresAt,
+      metadata: opts.metadata,
+    }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(entry, null, 2));
+    return;
+  }
+  console.log(`STORED ${entry.key} ${entry.contentHash}`);
+}
+
+function list(opts) {
+  const entries = listJobForgeCache({
+    kind: opts.kind,
+    includeExpired: opts.includeExpired,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  console.log(formatCacheEntries(entries));
+}
+
+function verify(opts) {
+  const result = verifyJobForgeCache(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function prune(opts) {
+  const result = pruneJobForgeCache({
+    expired: opts.expired || undefined,
+    dryRun: opts.dryRun,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatPruneResult(result));
+}
+
+function read(opts) {
+  if (opts.url) {
+    return readJobDescriptionCache(opts.url, { allowExpired: opts.allowExpired }, PROJECT_DIR);
+  }
+  return readJobForgeCache(requiredKey(opts), { allowExpired: opts.allowExpired }, PROJECT_DIR);
+}
+
+function keyFromOptions(opts) {
+  if (opts.url) return jobDescriptionCacheKey(opts.url);
+  return requiredKey(opts);
+}
+
+function requiredKey(opts) {
+  if (!opts.key) throw new Error('expected --url or --key');
+  return opts.key;
+}
+
+function readInput(input) {
+  if (input === '-') return readFileSync(0, 'utf8');
+  if (input.startsWith('@')) return readFileSync(input.slice(1), 'utf8');
+  return input;
+}
+
+function parseMetadata(raw) {
+  const text = raw.startsWith('@') ? readFileSync(raw.slice(1), 'utf8') : raw;
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--meta must be a JSON object');
+  }
+  return parsed;
+}
+
+function parseDuration(raw) {
+  const match = /^(\d+)(ms|s|m|h|d)?$/.exec(String(raw).trim());
+  if (!match) throw new Error('--ttl must be a duration like 14d, 2h, 30m, 10s, or 500ms');
+  const value = Number(match[1]);
+  const unit = match[2] || 'ms';
+  const multipliers = {
+    ms: 1,
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+  return value * multipliers[unit];
+}

package/templates/capabilities.json

@@ -11,6 +11,7 @@
           "npx job-forge ledger:*",
           "npx job-forge capabilities:*",
           "npx job-forge context:*",
+          "npx job-forge cache:*",
           "rg *"
         ],
         "deny": [
@@ -56,7 +57,8 @@
           "npx job-forge merge",
           "npx job-forge verify",
           "npx job-forge ledger:*",
-          "npx job-forge capabilities:*"
+          "npx job-forge capabilities:*",
+          "npx job-forge cache:*"
         ],
         "deny": [
           "task *"

package/templates/context.json

@@ -9,11 +9,20 @@
       "description": "Shared JobForge orchestration contract.",
       "tokenBudget": 4000,
       "files": [
+        {
+          "path": "AGENTS.harness.md",
+          "maxTokens": 3500,
+          "required": false,
+          "notes": [
+            "Consumer-project symlink to the shared harness contract."
+          ]
+        },
         {
           "path": "iso/instructions.md",
           "maxTokens": 3500,
+          "required": false,
           "notes": [
-            "Shared contract; mode/reference files should be selected through narrower bundles."
+            "Harness-source fallback; mode/reference files should be selected through narrower bundles."
           ]
         }
       ]