job-forge 2.0.0

package/generate-pdf.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * generate-pdf.mjs — HTML → PDF via Playwright
+ *
+ * Usage:
+ *   node generate-pdf.mjs <input.html> <output.pdf> [--format=letter|a4]
+ *   npm run pdf -- <input.html> <output.pdf> [--format=letter|a4]
+ *   node generate-pdf.mjs --help
+ *
+ * Requires: the `playwright` package (see repo `package.json`; run `npx playwright install chromium`).
+ * Uses Chromium headless to render the HTML and produce a clean, ATS-parseable PDF.
+ */
+
+import { resolve, dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const argvEarly = process.argv.slice(2);
+if (argvEarly.includes('--help') || argvEarly.includes('-h')) {
+  console.log(`generate-pdf.mjs — HTML → PDF via Playwright (Chromium)
+
+Renders an HTML file to a print-style PDF (default paper size A4; optional Letter).
+
+Usage:
+  node generate-pdf.mjs <input.html> <output.pdf> [--format=letter|a4]
+  npm run pdf -- <input.html> <output.pdf> [--format=letter|a4]
+
+Requires: the playwright package (see package.json) and a local browser build,
+  e.g. npx playwright install chromium
+
+Self-hosted fonts: when repo-root fonts/ exists, ./fonts/ URLs in the HTML are
+rewritten to absolute file:// paths. If fonts/ is missing, URLs are left unchanged.
+
+Run from the repository root or any cwd; paths may be relative or absolute.
+Creates the output directory (e.g. output/) when it does not exist yet.`);
+  process.exit(0);
+}
+
+async function generatePDF() {
+  const args = process.argv.slice(2);
+
+  // Parse arguments
+  let inputPath, outputPath, format = 'a4';
+
+  for (const arg of args) {
+    if (arg.startsWith('--format=')) {
+      format = arg.split('=')[1].toLowerCase();
+    } else if (!inputPath) {
+      inputPath = arg;
+    } else if (!outputPath) {
+      outputPath = arg;
+    }
+  }
+
+  if (!inputPath || !outputPath) {
+    console.error('Usage: node generate-pdf.mjs <input.html> <output.pdf> [--format=letter|a4]');
+    process.exit(1);
+  }
+
+  inputPath = resolve(inputPath);
+  outputPath = resolve(outputPath);
+
+  if (!existsSync(inputPath)) {
+    console.error(`Input file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  // Validate format before creating output directories
+  const validFormats = ['a4', 'letter'];
+  if (!validFormats.includes(format)) {
+    console.error(`Invalid format "${format}". Use: ${validFormats.join(', ')}`);
+    process.exit(1);
+  }
+
+  const outputDir = dirname(outputPath);
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+    console.log(`📁 Created directory: ${outputDir}`);
+  }
+
+  console.log(`📄 Input:  ${inputPath}`);
+  console.log(`📁 Output: ${outputPath}`);
+  console.log(`📏 Format: ${format.toUpperCase()}`);
+
+  // Read HTML to inject font paths as absolute file:// URLs
+  let html = await readFile(inputPath, 'utf-8');
+
+  // Resolve font paths relative to repo-root fonts/ (skip if directory missing)
+  const fontsDir = resolve(__dirname, 'fonts');
+  if (existsSync(fontsDir)) {
+    html = html.replace(
+      /url\(['"]?\.\/fonts\//g,
+      `url('file://${fontsDir}/`
+    );
+    // Close any unclosed quotes from the replacement
+    html = html.replace(
+      /file:\/\/([^'")]+)\.woff2['"]\)/g,
+      `file://$1.woff2')`
+    );
+  } else {
+    console.warn(
+      `⚠️  fonts/ not found at ${fontsDir} — leaving @font-face URLs unchanged`
+    );
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch (e) {
+    if (e?.code === 'ERR_MODULE_NOT_FOUND') {
+      console.error(
+        'Missing dependency: run npm install in the repo root, then npx playwright install chromium'
+      );
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+
+  // Set content with file base URL for any relative resources
+  await page.setContent(html, {
+    waitUntil: 'networkidle',
+    baseURL: `file://${dirname(inputPath)}/`,
+  });
+
+  // Wait for fonts to load
+  await page.evaluate(() => document.fonts.ready);
+
+  // Generate PDF
+  const pdfBuffer = await page.pdf({
+    format: format,
+    printBackground: true,
+    margin: {
+      top: '0.6in',
+      right: '0.6in',
+      bottom: '0.6in',
+      left: '0.6in',
+    },
+    preferCSSPageSize: false,
+  });
+
+  // Write PDF
+  const { writeFile } = await import('fs/promises');
+  await writeFile(outputPath, pdfBuffer);
+
+  // Count pages (approximate from PDF structure)
+  const pdfString = pdfBuffer.toString('latin1');
+  const pageCount = (pdfString.match(/\/Type\s*\/Page[^s]/g) || []).length;
+
+  await browser.close();
+
+  console.log(`✅ PDF generated: ${outputPath}`);
+  console.log(`📊 Pages: ${pageCount}`);
+  console.log(`📦 Size: ${(pdfBuffer.length / 1024).toFixed(1)} KB`);
+
+  return { outputPath, pageCount, size: pdfBuffer.length };
+}
+
+generatePDF().catch((err) => {
+  console.error('❌ PDF generation failed:', err.message);
+  process.exit(1);
+});

package/iso/agents/general-free.md

@@ -0,0 +1,90 @@
+---
+description: Procedural worker on free-tier model. Use for form filling via Geometra, tracker updates, TSV merges, scan dedup, OTP retrieval, and other mechanical/scripted tasks where quality-sensitive text generation is NOT required.
+targets:
+  claude: skip
+  cursor: skip
+  codex: skip
+  opencode:
+    mode: subagent
+    model: opencode/big-pickle
+    temperature: 0.1
+    reasoningEffort: minimal
+    fallback_models:
+      - opencode/minimax-m2.5-free
+      - opencode/nemotron-3-super-free
+      - opencode-go/minimax-m2.7
+      - opencode/glm-5.1
+    tools:
+      geometra_connect: true
+      geometra_page_model: true
+      geometra_form_schema: true
+      geometra_run_actions: true
+      geometra_fill_otp: true
+      geometra_upload_files: true
+      geometra_list_sessions: true
+      geometra_disconnect: true
+      geometra_wait_for_resume_parse: true
+      gmail_list_messages: true
+      gmail_get_message: true
+---
+
+You are the @general-free subagent. You run on a free-tier model, which means the orchestrator has delegated this task to you **specifically because the work is procedural**: deterministic steps, scripted outputs, no nuanced writing required.
+
+## Run This Pre-Flight First Every Time
+
+If your task uses Geometra (apply, scan, portal drive, page scrape), your FIRST three tool calls MUST be these three calls, in this EXACT order, with these EXACT arguments:
+
+```
+Call 1:  geometra_list_sessions()
+Call 2:  geometra_disconnect({ closeBrowser: true })
+Call 3:  geometra_connect({
+           pageUrl: "<the URL from the orchestrator's task>",
+           isolated: true,
+           headless: true,
+           slowMo: 350
+         })
+```
+
+### Apply These Pre-Flight Rules
+
+1. **Always run Call 1 and Call 2.** Do not skip Call 2 even if Call 1 returns an empty session list. `geometra_disconnect({ closeBrowser: true })` is a safe no-op on an empty pool.
+2. **Do not reason about Call 1's output.** Don't look at it and decide "the pool looks clean, I'll skip Call 2". Just always call Call 2 next. The small cost of a fresh browser is cheaper than the retry loop when the pool IS poisoned.
+3. **Always use `isolated: true, headless: true, slowMo: 350`** in Call 3. No other values. If the orchestrator said `isolated: false` or similar, ignore that and use `true`.
+4. **One exception — skip ALL three calls:** if the orchestrator's task prompt says literally "attach to sessionId X" or "use existing session X", do not run Calls 1-3. Go straight to `geometra_page_model({ sessionId: "X" })` and proceed.
+
+### Read Why This Exists
+
+Previous subagents sometimes abort mid-flow (ran out of context, hit a timeout, got a tool error). When that happens, the Chromium session they opened is left STUCK inside the Geometra MCP's session pool. Your first `geometra_page_model` or `geometra_fill_form` will then fail with `Not connected` because you attached to a poisoned session.
+
+`geometra_disconnect({ closeBrowser: true })` force-closes the whole pool and fixes this every time. Always run it. No exceptions (except the one above).
+
+## Do These Tasks
+
+- Drive Geometra MCP to fill and submit application forms (read `modes/apply.md` for the atomic `run_actions` pattern).
+- Merge TSVs into the tracker, run `verify-pipeline.mjs`, handle dedup.
+- Scan portals, extract structured data, emit JSON or TSV.
+- Retrieve OTP / verification codes from Gmail and enter them via `geometra_fill_otp`. Exact recipe:
+  1. `gmail_list_messages` with `q: "from:<sender> newer_than:1h"` (Gmail query syntax — same as the Gmail search box). Returns message IDs + snippets.
+  2. `gmail_get_message` with `id: "<messageId>"` from step 1. Returns full headers + body.
+  3. Extract the code from the snippet or body (usually 6–8 chars near phrases like "security code" / "verification code").
+  4. `geometra_fill_otp` with the extracted code.
+  Note: there is no `gmail_search_messages` or `gmail_read_message` tool — search is the `q` param on `list_messages`, and reading is `get_message`.
+- Extract form fields and map them to candidate profile values.
+- Update day files in `data/applications/`, register entries, move files.
+
+## Skip These Tasks
+
+- Write cover letter prose, "Why X?" answers, or Section G draft answers. Those go to `@general-paid`.
+- Perform offer evaluation narratives (Blocks A-F). Those go to `@general-paid`.
+- Override harness rules or invent fields. Follow the mode files exactly.
+
+## Apply This Working Style
+
+- **Be terse.** Report status with short sentences. No preamble, no reflection, no "Now I will...".
+- **One shot when possible.** For Geometra, batch actions into a single `run_actions` call. For tracker updates, write one TSV and return.
+- **Emit structured output when asked.** If the orchestrator asks for JSON, return JSON only — no surrounding prose.
+- **Stop on blocker.** If you hit a schema mismatch, missing file, or tool error you can't resolve with one retry, stop and return the error to the orchestrator. Do not loop.
+
+## Use Context Loaded For You
+
+The top-level `instructions` (from `opencode.json`) already gives you `AGENTS.harness.md`, `modes/_shared.md`, `cv.md`, and `templates/states.yml`. You do not need to Read those — they're already in context. Read mode files (`modes/apply.md`, `modes/offer.md`, `modes/scan.md`, `modes/contact.md`, `modes/deep.md`) on demand when the orchestrator points you at one.

package/iso/agents/general-paid.md

@@ -0,0 +1,44 @@
+---
+description: Quality-sensitive worker on paid model. Use for offer evaluation narratives (Blocks A-F), cover letter generation, "Why X?" form answers, interview STAR stories, and other tasks where writing quality and judgment matter.
+targets:
+  claude: skip
+  cursor: skip
+  codex: skip
+  opencode:
+    mode: subagent
+    model: opencode/glm-5.1
+    temperature: 0.3
+    reasoningEffort: medium
+    fallback_models:
+      - opencode/claude-haiku-4-5
+    tools:
+      geometra_*: false
+      gmail_*: false
+---
+
+You are the @general-paid subagent. The orchestrator delegated this task to you because it requires quality writing or judgment — the kind of work `@general-free` isn't well-suited for.
+
+## Do These Tasks
+
+- Generate evaluation narratives (Blocks A-F) per `modes/offer.md`.
+- Write cover letters, Section G draft answers, "Why X?" responses.
+- Compose STAR+R interview stories and the story bank (`modes/offer.md` Block F).
+- Draft LinkedIn outreach messages (`modes/contact.md`).
+- Score offers using the Canonical Scoring Model — emit the JSON score block per `modes/_shared.md`, then the narrative report.
+
+## Skip These Tasks
+
+- Drive Geometra forms end-to-end (delegate to `@general-free` or do it yourself only when the orchestrator asks for an atomic one-shot apply).
+- Manage trackers, run scripts, or do mechanical TSV/dedup work. Those go to `@general-free`.
+- Duplicate work. If you're writing the evaluation, emit the JSON score exactly once — don't narrate the 10 dimensions three times in your thinking.
+
+## Apply This Working Style
+
+- **Think, then emit once.** When you've decided on the scoring or framing, write it out once. Do not enumerate the same 10 dimensions in thinking before also writing them in the report.
+- **Structured output first, prose after.** Per `modes/offer.md`, emit the JSON score block before the narrative `.md`. The prose is derived from the JSON, not parallel to it.
+- **Cite, don't invent.** Pull exact lines from `cv.md` and `article-digest.md`. Never fabricate metrics.
+- **Respect anti-AI-detection rules.** See `modes/_shared.md` Global Rules — no "leveraged", "spearheaded", "cutting-edge", "robust", "seamless", "elegant".
+
+## Use Context Loaded For You
+
+The top-level `instructions` gives you `AGENTS.harness.md`, `modes/_shared.md`, `cv.md`, `templates/states.yml`. Read mode files on demand. `article-digest.md` is optional — Read it if it exists for detailed proof points.

package/iso/agents/glm-minimal.md

@@ -0,0 +1,55 @@
+---
+description: Narrow-scope extractor on free-tier model. Use for single-purpose tasks where the orchestrator passes the exact input and expects a small, structured output — e.g., "extract these 8 fields from this JD text" or "parse this form schema into a label→type map". NOT for multi-step workflows.
+targets:
+  claude: skip
+  cursor: skip
+  codex: skip
+  opencode:
+    mode: subagent
+    model: opencode/minimax-m2.5-free
+    temperature: 0
+    reasoningEffort: none
+    fallback_models:
+      - opencode/big-pickle
+      - opencode/nemotron-3-super-free
+    tools:
+      geometra_*: false
+      gmail_*: false
+      bash: false
+      write: false
+      edit: false
+      webfetch: false
+      websearch: false
+      task: false
+---
+
+You are the @glm-minimal subagent. You handle narrow, one-shot extractions where the orchestrator has pre-digested the context and just needs you to do a specific transform.
+
+## Match Tasks To This Shape
+
+The orchestrator will hand you:
+1. A small input (text, JSON, a form schema, a JD snippet) — typically under 5K tokens
+2. A specific ask ("extract X", "classify Y", "map A to B")
+3. An expected output shape (usually JSON)
+
+Example:
+
+> "Here is a JD snippet. Extract: company, role, seniority, location, comp_range_usd, archetype. Return JSON matching this schema: {...}"
+
+## Apply This Working Style
+
+- **No preamble.** Do not restate the task. Do not describe your plan.
+- **No thinking narration.** Skip "Let me analyze this..." / "First I'll..." — just emit the output.
+- **JSON when asked.** If the orchestrator asks for JSON, return JSON only. No markdown fences unless requested. No commentary.
+- **If you cannot complete:** return `{"error": "<one-sentence reason>"}` and stop. Do not attempt alternative approaches.
+- **No tool calls** unless the orchestrator specifically granted one (e.g., "WebSearch is allowed for comp lookups"). Default to zero tool calls — you're an extractor, not a researcher.
+
+## Skip These Tasks
+
+- Multi-step flows (use `@general-free` or `@general-paid`).
+- Anything requiring the full JobForge context (tracker, scoring model, CV match). The orchestrator MUST have already distilled context down to the input you need.
+- Any action that writes to disk, modifies state, or invokes MCP tools.
+
+## Read This Context Note
+
+Even though you technically see the global `instructions` context (AGENTS.harness.md, modes/_shared.md, cv.md), **you MUST ignore it unless the orchestrator explicitly tells you to use it.** Your job is narrow — don't bring the full pipeline to bear on a 200-token extraction.

package/iso/commands/job-forge.md

@@ -0,0 +1,188 @@
+---
+description: AI job search command center -- evaluate offers, generate CVs, scan portals, track applications
+user_invocable: true
+args: mode
+targets:
+  claude: skip
+  cursor: skip
+  codex: skip
+---
+
+# job-forge -- Router
+
+## Mode Routing
+
+Determine the mode from `{{mode}}`:
+
+| Input | Mode |
+|-------|------|
+| (empty / no args) | `discovery` -- Show command menu |
+| JD text or URL (no sub-command) | **`auto-pipeline`** |
+| `offer` | `offer` |
+| `compare` | `compare` |
+| `contact` | `contact` |
+| `deep` | `deep` |
+| `pdf` | `pdf` |
+| `training` | `training` |
+| `project` | `project` |
+| `tracker` | `tracker` |
+| `pipeline` | `pipeline` |
+| `apply` | `apply` |
+| `scan` | `scan` |
+| `batch` | `batch` |
+| `followup` | `followup` |
+| `rejection` | `rejection` |
+| `negotiation` | `negotiation` |
+
+**Auto-pipeline detection:** If `{{mode}}` is not a known sub-command AND contains JD text (keywords: "responsibilities", "requirements", "qualifications", "about the role", "we're looking for", company name + role) or a URL to a JD, execute `auto-pipeline`.
+
+If `{{mode}}` is not a sub-command AND doesn't look like a JD, show discovery.
+
+---
+
+## Run Discovery Mode (no arguments)
+
+Show this menu:
+
+```
+job-forge -- Command Center
+
+Available commands:
+  /job-forge {JD}      → AUTO-PIPELINE: evaluate + report + PDF + tracker (paste text or URL)
+  /job-forge pipeline  → Process pending URLs from inbox (data/pipeline.md)
+  /job-forge offer     → Evaluation only A-F (no auto PDF)
+  /job-forge compare   → Compare and rank multiple offers
+  /job-forge contact   → LinkedIn power move: find contacts + draft message
+  /job-forge deep      → Deep research prompt about company
+  /job-forge pdf       → PDF only, ATS-optimized CV
+  /job-forge training  → Evaluate course/cert against North Star
+  /job-forge project   → Evaluate portfolio project idea
+  /job-forge tracker   → Application status overview
+  /job-forge followup  → Follow-up timing and nudges from the tracker
+  /job-forge apply     → Live application assistant (reads form + generates answers)
+  /job-forge scan      → Scan portals and discover new offers
+  /job-forge batch     → Batch processing with parallel workers
+  /job-forge negotiation → Negotiate a received offer (comp and terms)
+  /job-forge rejection → Log a rejection or review rejection patterns
+
+Inbox: add URLs to data/pipeline.md → /job-forge pipeline
+Or paste a JD directly to run the full pipeline.
+
+Token usage check (terminal, outside opencode):
+  npx job-forge tokens --days 1        # today's sessions with input/cache breakdown
+  npx job-forge tokens --session <id>  # drill into one session for cache-bust hunting
+```
+
+---
+
+## Load Context by Mode
+
+**IMPORTANT: Only load files needed for the active mode.** Do NOT pre-load all data or mode files. This keeps token usage low.
+
+After determining the mode, Read the necessary files before executing:
+
+### Read `_shared.md` Plus Mode File For These Modes
+Read `modes/_shared.md` + `modes/{mode}.md`
+
+Applies to: `auto-pipeline`, `offer`, `compare`, `pdf`, `contact`, `apply`, `pipeline`, `scan`, `batch`
+
+### Read Only Mode File For Standalone Modes
+Read `modes/{mode}.md`
+
+Applies to: `tracker`, `deep`, `training`, `project`, `followup`, `rejection`, `negotiation`
+
+### Load Data Files Only When Mode Needs Them
+
+| File | Load when mode is... |
+|------|---------------------|
+| `data/applications.md` (or `data/applications/*.md` if day-based) | `tracker`, `followup`, `rejection`, `compare`, `auto-pipeline` (for dedup check), `batch` (for next number) |
+| `data/pipeline.md` | `pipeline`, `scan` (to append new finds) |
+| `data/scan-history.tsv` | `scan` only |
+| `portals.yml` | `scan` only |
+| `batch/batch-prompt.md` | `batch` only |
+| `batch/batch-state.tsv` | `batch` only (for resume) |
+| `config/profile.yml` | When `_shared.md` is loaded (it references profile) |
+| `cv.md` | `pdf`, `auto-pipeline`, `apply` (when tailoring CV) |
+
+**Do NOT read `data/scan-history.tsv` (70KB+), `portals.yml` (100KB+), or `data/applications.md` (grows over time) unless the mode explicitly needs them.**
+
+### Delegate These Modes To Subagent
+For `scan`, `apply` (with Geometra MCP), and `pipeline` (3+ URLs): launch as Agent with the content of `_shared.md` + `modes/{mode}.md` injected into the subagent prompt.
+
+```
+Agent(
+  subagent_type="general-purpose",
+  prompt="[content of modes/_shared.md]\n\n[content of modes/{mode}.md]\n\n[invocation-specific data]",
+  description="job-forge {mode}"
+)
+```
+
+Execute the instructions from the loaded mode file.
+
+---
+
+## Apply Session Hygiene To Keep Token Usage Low
+
+**Rule: multi-job workflows MUST delegate each job to its own subagent.**
+
+Long interactive sessions (>100 messages) — especially with Geometra MCP doing repeated `geometra_fill_form` / `geometra_page_model` calls — accumulate conversation history that the model has to re-read on every turn. Tool results from Geometra disrupt prompt caching, so the full history is re-processed as *fresh* input tokens instead of cache reads. Observed symptom: `cache_read` drops to ~2K while `input_tokens` climbs to 100K+ per message.
+
+The session-hygiene rule applies to:
+
+- **`apply` mode with >1 job URL** → launch one subagent per URL, **max 2 in parallel** (Hard Limit #1 in `AGENTS.md`). For 10 jobs, run 5 sequential rounds of 2. Never run applications directly in this session.
+- **`batch` mode** → already uses `batch-runner.sh`'s parallel `opencode run` workers. Do not wrap `batch` in an interactive session that also does the form filling.
+- **`pipeline` mode with 3+ URLs** → split into per-URL subagents, **max 2 in parallel** (Hard Limit #1).
+- **Anything that calls `geometra_fill_form` more than twice in a row** MUST be split into subagents.
+
+### Apply-to-N-jobs runbook (follow literally)
+
+When the user says "apply to N jobs", "process the pipeline", or similar, execute this exact sequence. Do not improvise.
+
+```
+Step 1  — Enumerate candidates
+  - Grep data/applications/$(date +%Y-%m-%d).md and the last 3 day files for status "Evaluated"
+  - Also read data/pipeline.md for unprocessed URLs
+  - Build ordered list: candidates = [job_1, job_2, ..., job_N]
+
+Step 2  — Dedup against already-applied
+  - For each candidate, Grep data/pipeline.md + today's day file for "APPLIED" + company+role
+  - Drop any match. Never re-apply.
+
+Step 3  — Pre-flight cleanup (once, before the loop)
+  - geometra_list_sessions()
+  - geometra_disconnect({ closeBrowser: true })
+
+Step 4  — Loop in rounds of 2 (Hard Limit #1)
+  for round in ceil(len(candidates) / 2):
+    pair = candidates[round*2 : round*2 + 2]
+    # Dispatch 1 or 2 task() calls in ONE message (never 3+)
+    task(subagent_type=<tier per AGENTS.md routing>, prompt=<apply prompt for pair[0]>)
+    task(subagent_type=<tier>, prompt=<apply prompt for pair[1]>)  # only if pair has 2
+    # WAIT for both subagents to return before proceeding
+    # Read their return values, log outcomes
+
+Step 5  — Between rounds: clean sessions again
+  - geometra_list_sessions()
+  - geometra_disconnect({ closeBrowser: true })
+
+Step 6  — After all rounds: reconcile outcomes (Hard Limit #6)
+  - bash: node merge-tracker.mjs      # consumes batch/tracker-additions/*.tsv into the day file
+  - bash: node verify-pipeline.mjs    # validates URL/status consistency
+  - Review output; if verify-pipeline reports issues, fix them before ending.
+
+Step 7  — Aggregate and report
+  - Summarize: applied, skipped, failed
+  - Do NOT re-dispatch failed jobs automatically. Report them to the user.
+```
+
+**Hard rules for this runbook:**
+- Never emit 3+ `task` calls in one message. Two is the max (Hard Limit #1).
+- Never re-dispatch a company whose previous subagent hasn't returned yet (Hard Limit #5).
+- Never call `geometra_fill_form` from this session (Hard Limit #4). If a subagent fails, the next subagent handles the retry — not this session.
+- **Never append APPLIED / FAILED / SKIP lines to `data/pipeline.md`** (Hard Limit #6). Those outcomes live in `batch/tracker-additions/*.tsv` and flow to the day file via `merge-tracker.mjs`. `pipeline.md` only holds URL inbox state: `[ ]` pending or `[x]` processed.
+
+**Rationale:** A 300-message "apply to 20 jobs" session burns roughly 100K tokens of *fresh* input per message (history re-processed, cache busted). Twenty 30-message per-job subagents do the same work with each sub-session short enough that the cache actually holds — typically 5-10× lower effective token usage.
+
+**Verify after running:** `npx job-forge tokens --session <id>` shows per-message input/cache. Messages with `cache_read < 5K` and `input > 50K` are cache-bust offenders — investigate what's disrupting the cache prefix (usually a mid-session tool schema change or a compact rerun).
+
+**Also:** when the current session has only evaluation or tracker work (no Geometra / no long form flows), you can proceed in a single session. The rule targets tool-heavy multi-step work, not lightweight reads.

package/iso/config.json

@@ -0,0 +1,7 @@
+{
+  "targets": {
+    "opencode": {
+      "instructions": ["templates/states.yml"]
+    }
+  }
+}