job-forge 2.14.37 → 2.14.38

package/.opencode/instructions.md

@@ -0,0 +1,8 @@
+## OpenCode Addendum
+
+These notes apply only inside OpenCode sessions.
+
+- The OpenCode subagent dispatch primitive is `task`.
+- A `task` result that only returns a session id/title is a launch acknowledgement, not a completed application outcome.
+- Do not use `task` to poll status. Inspect tracker files, workflow artifacts, or `iso-trace` instead.
+- When JobForge says "dispatch" or "subagent" in the shared contract, map that to OpenCode `task` calls here.

package/README.md

@@ -74,11 +74,11 @@ JobForge turns opencode into a full job search command center. Instead of manual
 | **Deep Research** | Company research that feeds back into scores and interview prep |
 | **Smart LinkedIn Outreach** | Reads evaluation reports to craft targeted messages using top proof points |
 | **Portal Scanner** | 45+ companies pre-configured with fuzzy dedup for reposts |
-| **Batch Processing** | Parallel evaluation with `opencode run` workers, with honest verification flagging |
+| **Batch Processing** | Parallel evaluation with headless AI CLI workers (`opencode run` or `codex exec`), with honest verification flagging |
 | **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 + Score + Canon + Ledger + Capabilities + Context + Cache + Index + Facts + Timeline + Prioritize + Lineage + Preflight + Postflight + Redact + Migrate** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge score:*` computes/checks weighted offer scores, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, `job-forge facts:*` materializes source-backed job/application/candidate facts, `job-forge timeline:*` computes due/overdue follow-up actions, `job-forge prioritize:*` ranks local apply/follow-up candidates, `job-forge lineage:*` detects stale reports/PDFs after source changes, `job-forge preflight:*` plans bounded apply dispatch rounds from file-backed candidate facts, `job-forge postflight:*` settles dispatch outcomes/artifacts/post-steps, `job-forge redact:*` sanitizes local exports, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
+| **Trace + Telemetry + Guard + Contract + Score + Canon + Ledger + Capabilities + Context + Cache + Index + Facts + Timeline + Prioritize + Lineage + Preflight + Postflight + Redact + Migrate** | `job-forge trace:*` exposes local harness transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge score:*` computes/checks weighted offer scores, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, `job-forge facts:*` materializes source-backed job/application/candidate facts, `job-forge timeline:*` computes due/overdue follow-up actions, `job-forge prioritize:*` ranks local apply/follow-up candidates, `job-forge lineage:*` detects stale reports/PDFs after source changes, `job-forge preflight:*` plans bounded apply dispatch rounds from file-backed candidate facts, `job-forge postflight:*` settles dispatch outcomes/artifacts/post-steps, `job-forge redact:*` sanitizes local exports, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
 | **Token Cost Visibility** | `job-forge tokens --days 1` for per-session breakdown; `job-forge session-report --since-minutes 60 --log` to flag sessions over budget and append history to `data/token-usage.tsv`. Auto-logged after every batch run. |
 
 ## Usage

package/batch/README.md

@@ -1,6 +1,6 @@
 # Batch evaluation
 
-The `batch/` folder holds the **parallel batch runner** for processing 10+ job URLs with headless `opencode run` workers. For how batch fits into the rest of JobForge, see [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
+The `batch/` folder holds the **parallel batch runner** for processing 10+ job URLs with headless AI CLI workers (`opencode run` or `codex exec`). For how batch fits into the rest of JobForge, see [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
 
 ## What ships in git
 
@@ -16,10 +16,11 @@ Per [`.gitignore`](../.gitignore): `batch-input.tsv`, `batch-state.tsv`, `logs/*
 
 The default runner uses `@razroo/iso-orchestrator` through
 `scripts/batch-orchestrator.mjs`. It persists bundle steps and events in
-`.jobforge-runs/`, caps worker fan-out with `workflow.forEach`, and serializes
-state/report-number writes while parallel bundles run. Use
-`JOBFORGE_LEGACY_BATCH_RUNNER=1 ./batch/batch-runner.sh` only to fall back to
-the old shell loop.
+`.jobforge-runs/`, caps worker fan-out with `workflow.forEach`, serializes
+state/report-number writes while parallel bundles run, and records worker
+leases/heartbeats for liveness inspection. Use `./batch/batch-runner.sh --runner codex`
+to switch the worker CLI, or `JOBFORGE_LEGACY_BATCH_RUNNER=1 ./batch/batch-runner.sh`
+only to fall back to the old shell loop.
 
 ## Input: `batch-input.tsv`
 
@@ -64,4 +65,4 @@ After a successful merge, each processed file is moved to **`batch/tracker-addit
 
 ## Prerequisites
 
-The runner expects the `opencode` CLI on `PATH` and a valid `batch-prompt.md`. It creates `reports/` and tracker paths when they do not exist; ensure your usual JobForge setup (`cv.md`, `config/profile.yml`, `portals.yml`) matches what `batch-prompt.md` assumes.
+The runner expects the selected worker CLI (`opencode` by default, `codex` when `--runner codex` is used) on `PATH` and a valid `batch-prompt.md`. It creates `reports/` and tracker paths when they do not exist; ensure your usual JobForge setup (`cv.md`, `config/profile.yml`, `portals.yml`) matches what `batch-prompt.md` assumes.

package/batch/batch-runner.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# job-forge batch runner — standalone orchestrator for opencode run workers
-# Reads batch-input.tsv, delegates each offer to an opencode run worker,
+# job-forge batch runner — standalone orchestrator for headless AI CLI workers
+# Reads batch-input.tsv, delegates each offer to a worker CLI invocation,
 # tracks state in batch-state.tsv for resumability.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

package/bin/create-job-forge.mjs

@@ -224,12 +224,15 @@ const opencodeCfg = {
   // Files listed here load into every session's cached prefix, so they're
   // cached once (on Anthropic) instead of Read-as-tool-call on every session.
   //   AGENTS.harness.md → symlink to node_modules/job-forge/AGENTS.md (harness rules)
+  //   .opencode/instructions.md → symlink to node_modules/job-forge/.opencode/instructions.md
+  //                              (OpenCode-only harness addendum)
   //   modes/_shared.md  → symlink into node_modules; canonical scoring model
   //   cv.md             → candidate's CV (personal, created during onboarding)
   //   templates/states.yml → canonical application states (validated by merge-tracker.mjs)
   // Ordering matters for cache prefix stability: put most-stable files first.
   instructions: [
     'AGENTS.harness.md',
+    '.opencode/instructions.md',
     'templates/states.yml',
     'modes/_shared.md',
     'cv.md',
@@ -285,7 +288,7 @@ write('AGENTS.md', `# AGENTS — ${name}
 
 Personal job search project using the [job-forge](https://github.com/razroo/JobForge) harness. The harness lives in \`node_modules/job-forge/\`; most files you need are accessible through symlinks at the project root.
 
-**How context loads in this project:** opencode auto-loads *this* file as the project-root AGENTS.md, and also loads \`AGENTS.harness.md\` via \`opencode.json:instructions\` — that second file is a symlink to \`node_modules/job-forge/AGENTS.md\` and carries the shared operational rules (Session Hygiene, OTP handling, batch best practices, scoring). Keep *this* file for personal overrides — anything you want to diverge from or add on top.
+**How context loads in this project:** opencode auto-loads *this* file as the project-root AGENTS.md, then loads \`AGENTS.harness.md\` plus \`.opencode/instructions.md\` via \`opencode.json:instructions\`. \`AGENTS.harness.md\` is the shared cross-harness contract; \`.opencode/instructions.md\` is reserved for OpenCode-only addenda. Keep *this* file for personal overrides — anything you want to diverge from or add on top.
 
 ---
 

package/bin/sync.mjs

@@ -20,7 +20,7 @@
  * whether the cwd contains the harness's own package.json with name=job-forge).
  */
 
-import { existsSync, lstatSync, readlinkSync, symlinkSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, lstatSync, readlinkSync, symlinkSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join, resolve, relative } from 'path';
 import { fileURLToPath } from 'url';
 import {
@@ -80,6 +80,7 @@ const links = [
 
   // OpenCode: skill router + subagent definitions. Users can override any
   // single subagent by replacing its symlink with a local file.
+  { src: '.opencode/instructions.md',      dst: '.opencode/instructions.md' },
   { src: '.opencode/skills/job-forge.md',  dst: '.opencode/skills/job-forge.md' },
   { src: '.opencode/agents',               dst: '.opencode/agents' },
 
@@ -154,6 +155,15 @@ for (const { src, dst } of links) {
   }
 }
 
+try {
+  if (ensureOpencodeInstructionRef()) {
+    created++;
+  }
+} catch (error) {
+  console.warn(`  warn: failed to patch opencode.json instructions: ${error instanceof Error ? error.message : String(error)}`);
+  warned++;
+}
+
 try {
   const migrationResult = applyConsumerMigrations();
   if (migrationResult?.changeCount > 0) {
@@ -166,6 +176,30 @@ try {
 
 console.log(`\njob-forge sync: ${created} created, ${skipped} up-to-date, ${warned} warnings (project: ${PROJECT_DIR})`);
 
+function ensureOpencodeInstructionRef() {
+  const configPath = join(PROJECT_DIR, 'opencode.json');
+  if (!existsSync(configPath)) return false;
+
+  const raw = readFileSync(configPath, 'utf8');
+  const config = JSON.parse(raw);
+  const current = Array.isArray(config.instructions)
+    ? config.instructions.slice()
+    : config.instructions
+      ? [config.instructions]
+      : [];
+  const required = '.opencode/instructions.md';
+  if (current.includes(required)) return false;
+
+  const next = current.slice();
+  const anchor = next.indexOf('AGENTS.harness.md');
+  if (anchor === -1) next.unshift(required);
+  else next.splice(anchor + 1, 0, required);
+  config.instructions = [...new Set(next)];
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  console.log(`  updated: opencode.json instructions += ${required}`);
+  return true;
+}
+
 function applyConsumerMigrations() {
   const skip = process.env.JOB_FORGE_SKIP_MIGRATIONS;
   if (skip === '1' || skip === 'true') return null;

package/docs/ARCHITECTURE.md

@@ -134,14 +134,14 @@ For customization (archetypes, weights, tone), start with `_shared.md` and [CUST
 The batch system processes multiple offers in parallel:
 
 ```
-batch-input.tsv    ->  batch-runner.sh  ->  N x opencode run workers
-(id, url, source, notes) (iso-orchestrator) (self-contained prompt)
+batch-input.tsv    ->  batch-runner.sh  ->  N x AI CLI workers
+(id, url, source, notes) (iso-orchestrator) (opencode run / codex exec)
                            |
                     batch-state.tsv + .jobforge-runs/
                     (progress + durable workflow record)
 ```
 
-Each worker is a headless opencode instance (`opencode run`) that receives the full `batch-prompt.md` as context. Workers produce:
+Each worker is a headless CLI agent (`opencode run` or `codex exec`) that receives the full `batch-prompt.md` context. Workers produce:
 - Report .md
 - PDF
 - Tracker TSV line
@@ -149,8 +149,9 @@ Each worker is a headless opencode instance (`opencode run`) that receives the f
 The orchestrator manages parallelism, state, retries, and resume. The default
 runner delegates to `scripts/batch-orchestrator.mjs`, which uses
 `@razroo/iso-orchestrator` for bounded bundle fan-out, idempotent bundle steps,
-and mutexed report-number/state writes. Set `JOBFORGE_LEGACY_BATCH_RUNNER=1`
-only if you need the old shell loop.
+mutexed report-number/state writes, and worker leases/heartbeats. Pass
+`--runner codex` to use Codex workers instead of OpenCode. Set
+`JOBFORGE_LEGACY_BATCH_RUNNER=1` only if you need the old shell loop.
 
 **Local batch artifacts:** `batch/batch-input.tsv`, `batch/batch-state.tsv`, `batch/logs/`, `batch/tracker-additions/*.tsv`, and `.jobforge-runs/` are created when you run the runner; they are gitignored (with `.gitkeep` in `batch/logs/` and `batch/tracker-additions/`). A fresh clone ships `batch/batch-runner.sh` and `batch/batch-prompt.md` only until you add an input file — see [`batch/README.md`](../batch/README.md) and `batch/batch-runner.sh --help` for the TSV layout and workflow.
 
@@ -247,9 +248,9 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `generate-pdf.mjs` | `npx job-forge pdf` | Renders HTML to PDF via Geometra MCP (`geometra_generate_pdf`) or standalone Playwright/Chromium (`npx job-forge pdf <input.html> <output.pdf>`) |
 | `cv-sync-check.mjs` | `npx job-forge sync-check` | Setup lint: `cv.md` + `config/profile.yml`, hardcoded-metric scan on `modes/_shared.md` and `batch/batch-prompt.md`, optional `article-digest.md` freshness |
 | `scripts/token-usage-report.mjs` | `npx job-forge tokens` | Per-session opencode token/cost report from the SQLite DB |
-| `scripts/trace.mjs` | `npx job-forge trace:list` / `trace:stats` / `trace:show` | Local transcript observability via `@razroo/iso-trace`; common commands default to OpenCode sessions for the consumer project |
-| `scripts/telemetry.mjs` | `npx job-forge telemetry:status` / `telemetry:show` | JobForge operational telemetry derived from OpenCode traces plus tracker TSV state |
-| `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@razroo/iso-guard` policy audits over local OpenCode traces |
+| `scripts/trace.mjs` | `npx job-forge trace:list` / `trace:stats` / `trace:show` | Local transcript observability via `@razroo/iso-trace`; common commands default to project-local sessions across supported harnesses |
+| `scripts/telemetry.mjs` | `npx job-forge telemetry:status` / `telemetry:show` | JobForge operational telemetry derived from normalized local traces plus tracker TSV state |
+| `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@razroo/iso-guard` policy audits over local normalized traces (with OpenCode `task` rules still available where relevant) |
 | `scripts/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@razroo/iso-ledger` state over tracker, TSV, and pipeline files |
 | `scripts/capabilities.mjs` | `npx job-forge capabilities:check` / `capabilities:explain` | Deterministic `@razroo/iso-capabilities` role boundary checks for tools, MCPs, commands, filesystem, and network access |
 | `scripts/cache.mjs` | `npx job-forge cache:has` / `cache:get` / `cache:put` | Deterministic `@razroo/iso-cache` JD and artifact reuse keyed by stable job/url inputs |

package/docs/CUSTOMIZATION.md

@@ -100,7 +100,7 @@ Some forks use a **single** `data/applications.md` instead. That is fine if you
 
 To inspect real agent sessions locally (tool mix, redundant fetches, Geometra churn) without uploading transcripts, use the `job-forge trace:*` commands. JobForge depends on Razroo's [`@razroo/iso-trace`](https://github.com/razroo/iso/tree/main/packages/iso-trace), so consumer projects do not need to install it separately.
 
-Common commands default to OpenCode sessions for the current project and use a 7-day window:
+Common commands default to sessions for the current project and use a 7-day window:
 
 ```bash
 npx job-forge trace:list
@@ -114,7 +114,7 @@ For raw iso-trace commands, use `npx job-forge trace sources`, `npx job-forge tr
 
 ## JobForge telemetry
 
-Trace is the raw transcript view. Telemetry is the JobForge operational view: it summarizes task dispatches, child session outcomes, provider errors, policy issues, and pending tracker TSVs.
+Trace is the raw transcript view. Telemetry is the JobForge operational view: it summarizes dispatches, child session outcomes, provider errors, policy issues, and pending tracker TSVs.
 
 ```bash
 npx job-forge telemetry:list
@@ -123,7 +123,7 @@ npx job-forge telemetry:show <session-id-or-prefix>
 npx job-forge telemetry:watch
 ```
 
-Telemetry is also local-only and passive. It reads OpenCode's SQLite DB and files under `batch/tracker-additions/`; agents do not need to remember to emit custom events.
+Telemetry is also local-only and passive. It reads normalized local harness traces plus files under `batch/tracker-additions/`; agents do not need to remember to emit custom events.
 
 ## JobForge ledger
 
@@ -196,7 +196,7 @@ Consumer-project migrations live in `templates/migrations.json` and are applied
 
 ## 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.
+Guard audits run deterministic `@razroo/iso-guard` policies over the same local traces. The default policy lives at `templates/guards/jobforge-baseline.yaml` and checks rules that are reliable from transcript data, including max two OpenCode `task` dispatches per assistant message, no task-status polling via `task`, no raw proxy configuration in task prompts, and no child session task recursion.
 
 ```bash
 npx job-forge guard:audit
@@ -204,13 +204,13 @@ npx job-forge guard:audit <session-id-or-prefix>
 npx job-forge guard:explain
 ```
 
-Use `--policy <path>` to audit with a custom policy. This does not add prompt, token, or MCP overhead; JobForge converts local trace rows into guard events inside the CLI process.
+Use `--policy <path>` to audit with a custom policy. This does not add prompt, token, or MCP overhead; JobForge converts local normalized trace events into guard events inside the CLI process.
 
 **Where Claude Code writes JSONL:** `~/.claude/projects/<encoded-cwd>/*.jsonl`.
 
 **Direct CLI fallback:** `npx -y @razroo/iso-trace@latest stats --source "$HOME/.claude/projects/<encoded-dir>/<session>.jsonl"`
 
-**Performance:** `iso-trace list --cwd /path/to/repo` walks all of `~/.claude/projects` before filtering; on large machines prefer `stats --source <one.jsonl>` or the library's `discoverSessions({ roots: ["<one encoded project dir>"] })` (see the iso-trace README).
+**Performance:** JobForge narrows discovery to project-local roots where possible, but raw `iso-trace list --cwd /path/to/repo` may still walk large transcript trees on busy machines. Prefer `stats --source <one.jsonl>` or project-scoped roots when you need direct `iso-trace` usage.
 
 ## States (templates/states.yml)
 

package/iso/instructions.opencode.md

@@ -0,0 +1,8 @@
+## OpenCode Addendum
+
+These notes apply only inside OpenCode sessions.
+
+- The OpenCode subagent dispatch primitive is `task`.
+- A `task` result that only returns a session id/title is a launch acknowledgement, not a completed application outcome.
+- Do not use `task` to poll status. Inspect tracker files, workflow artifacts, or `iso-trace` instead.
+- When JobForge says "dispatch" or "subagent" in the shared contract, map that to OpenCode `task` calls here.