job-forge 2.14.15 → 2.14.16

package/.cursor/rules/main.mdc

@@ -12,7 +12,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -24,7 +24,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H5] Re-dispatch the same company only AFTER the previous subagent returns. Never fire the same `task` twice while the first is still in flight.
   why: two in-flight subagents for the same URL race on Geometra sessions and on tracker TSV writes, corrupting state and sometimes double-submitting
 
-- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, or `iso-trace`) rather than spawning a "check task status" subagent.
+- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, or `iso-trace`) rather than spawning a "check task status" subagent.
   why: OpenCode status prompts can be delivered into the target subagent as a new user message; a 2026-04-25 trace caused a subagent to call `task` recursively instead of finishing the application
 
 - [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.
@@ -59,12 +59,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
+- [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
+  why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
+
 ## 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]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

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

@@ -68,6 +68,10 @@ 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
+
+Local workflow ledger (terminal, outside opencode):
+  npx job-forge ledger:status          # .jobforge-ledger/events.jsonl summary
+  npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
 ```
 
 ---
@@ -142,6 +146,9 @@ Step 1  — Enumerate candidates
   - Build ordered list: candidates = [job_1, job_2, ..., job_N]
 
 Step 2  — Dedup against already-applied
+  - If .jobforge-ledger/events.jsonl exists, use npx job-forge ledger:has as a
+    fast prefilter for obvious company+role Applied duplicates. A ledger match
+    can be dropped before dispatch without loading tracker files into context.
   - For each candidate, grep all four sources for URL and company+role:
     data/pipeline.md, data/applications/*.md, batch/tracker-additions/*.tsv,
     batch/tracker-additions/merged/*.tsv

package/AGENTS.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -19,7 +19,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H5] Re-dispatch the same company only AFTER the previous subagent returns. Never fire the same `task` twice while the first is still in flight.
   why: two in-flight subagents for the same URL race on Geometra sessions and on tracker TSV writes, corrupting state and sometimes double-submitting
 
-- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, or `iso-trace`) rather than spawning a "check task status" subagent.
+- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, or `iso-trace`) rather than spawning a "check task status" subagent.
   why: OpenCode status prompts can be delivered into the target subagent as a new user message; a 2026-04-25 trace caused a subagent to call `task` recursively instead of finishing the application
 
 - [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.
@@ -54,12 +54,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
+- [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
+  why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
+
 ## 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]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -19,7 +19,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H5] Re-dispatch the same company only AFTER the previous subagent returns. Never fire the same `task` twice while the first is still in flight.
   why: two in-flight subagents for the same URL race on Geometra sessions and on tracker TSV writes, corrupting state and sometimes double-submitting
 
-- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, or `iso-trace`) rather than spawning a "check task status" subagent.
+- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, or `iso-trace`) rather than spawning a "check task status" subagent.
   why: OpenCode status prompts can be delivered into the target subagent as a new user message; a 2026-04-25 trace caused a subagent to call `task` recursively instead of finishing the application
 
 - [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.
@@ -54,12 +54,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
+- [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
+  why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
+
 ## 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]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/README.md

@@ -31,6 +31,8 @@ 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 an MCP-free local workflow ledger at `.jobforge-ledger/events.jsonl` when you use `job-forge ledger:*`, `tracker-line --write`, or `merge`. This is deterministic state for duplicate/status checks; it does not add 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.
@@ -76,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** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, and `job-forge guard:*` audits deterministic JobForge policy rules with `@razroo/iso-guard`. |
+| **Trace + Telemetry + Guard + Ledger** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, and `job-forge ledger:*` queries append-only workflow state without MCP/token 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
@@ -143,6 +145,7 @@ my-search/
 ├── portals.yml                   # companies to scan (personal)
 ├── config/profile.yml            # your identity, target roles (personal)
 ├── data/                         # applications, pipeline, scan history (personal, gitignored)
+├── .jobforge-ledger/              # append-only local workflow events (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)
@@ -190,6 +193,7 @@ JobForge/
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
 │   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
+│   ├── ledger.mjs                # iso-ledger-backed workflow-state 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/create-job-forge.mjs

@@ -119,6 +119,11 @@ const consumerPkg = {
     'telemetry:watch': 'job-forge telemetry:watch',
     'guard:audit': 'job-forge guard:audit',
     'guard:explain': 'job-forge guard:explain',
+    'ledger:status': 'job-forge ledger:status',
+    'ledger:rebuild': 'job-forge ledger:rebuild',
+    'ledger:verify': 'job-forge ledger:verify',
+    'ledger:has': 'job-forge ledger:has',
+    'ledger:query': 'job-forge ledger:query',
     // 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
@@ -128,7 +133,7 @@ const consumerPkg = {
   dependencies: {
     'job-forge': '^2.0.0',
   },
-  engines: { node: '>=18' },
+  engines: { node: '>=20.6.0' },
 };
 write('package.json', JSON.stringify(consumerPkg, null, 2) + '\n');
 
@@ -218,6 +223,7 @@ Before doing any work, remember where things live in *this* project:
 | Application tracker | \`data/applications/YYYY-MM-DD.md\` | **Day-based**. One markdown table per day. **There is NO \`applications.md\` — do not look for it.** |
 | Inbox of pending URLs | \`data/pipeline.md\` | The queue for \`/job-forge pipeline\` |
 | 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:*\` |
 | 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 |
@@ -305,6 +311,7 @@ data/applications.md
 data/pipeline.md
 data/scan-history.tsv
 data/token-usage.tsv
+.jobforge-ledger/
 reports/
 !reports/.gitkeep
 batch/batch-state.tsv
@@ -361,6 +368,7 @@ job-forge sync             # re-run if symlinks drift
 \`\`\`bash
 job-forge merge            # merge batch/tracker-additions/*.tsv into the tracker
 job-forge verify           # verify pipeline integrity
+job-forge ledger:status    # local deterministic workflow ledger status
 job-forge pdf cv.md out.pdf
 job-forge tokens --days 1  # per-session opencode token usage
 \`\`\`

package/bin/job-forge.mjs

@@ -20,6 +20,7 @@
  *   trace:*        Inspect local agent transcripts via iso-trace
  *   telemetry:*    Summarize JobForge pipeline status from traces + tracker files
  *   guard:*        Audit JobForge trace policy with iso-guard
+ *   ledger:*       Query local deterministic workflow state via iso-ledger
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -74,6 +75,15 @@ const guardAliases = {
   'guard:explain': 'explain',
 };
 
+const ledgerAliases = {
+  'ledger:status': 'status',
+  'ledger:rebuild': 'rebuild',
+  'ledger:verify': 'verify',
+  'ledger:has': 'has',
+  'ledger:query': 'query',
+  'ledger:path': 'path',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -100,6 +110,10 @@ Commands:
   telemetry:watch   Watch latest run status
   guard:audit        Audit latest/local trace policy with iso-guard
   guard:explain      Show the active iso-guard policy
+  ledger:status      Show local workflow ledger status
+  ledger:rebuild     Rebuild .jobforge-ledger/events.jsonl from tracker/pipeline files
+  ledger:has         Check URL or company+role state without loading tracker files
+  ledger:verify      Validate the local workflow ledger
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -128,6 +142,7 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge telemetry:show ses_...
   job-forge guard:audit
   job-forge guard:explain
+  job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -182,6 +197,21 @@ if (cmd === 'guard' || guardAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'ledger' || ledgerAliases[cmd]) {
+  const ledgerArgs = cmd === 'ledger'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [ledgerAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/ledger.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...ledgerArgs], {
+    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/ARCHITECTURE.md

@@ -17,6 +17,7 @@ my-search/
 ├── config/profile.yml                # personal
 ├── portals.yml                       # personal
 ├── data/                             # personal (gitignored)
+├── .jobforge-ledger/                  # local workflow events (personal, gitignored)
 ├── reports/                          # personal (gitignored)
 ├── AGENTS.md                         # personal overrides (opencode + codex)
 ├── CLAUDE.md                         # personal overrides (Claude Code); @-imports CLAUDE.harness.md
@@ -159,6 +160,7 @@ article-digest.md        →  Proof points for matching
 config/profile.yml       →  Candidate identity
 portals.yml              →  Scanner configuration
 data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/pipeline.md)
+.jobforge-ledger/events.jsonl → Append-only workflow events for cheap local duplicate/status checks
 jds/*.md                 →  Saved job descriptions referenced from the pipeline (`local:jds/{file}`)
 templates/states.yml     →  Canonical status values
 templates/cv-template.html → PDF generation template
@@ -172,10 +174,11 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 - Reports: `{###}-{company-slug}-{YYYY-MM-DD}.md` (3-digit zero-padded)
 - PDFs: `cv-candidate-{company-slug}-{YYYY-MM-DD}.pdf`
 - Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`)
+- Ledger: `.jobforge-ledger/events.jsonl` (created by `job-forge ledger:rebuild`, `tracker-line --write`, or `merge`; gitignored personal state)
 
 ## Pipeline Integrity
 
-From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
+From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
 
 **`verify-pipeline.mjs` checks (same order as the script header):**
 
@@ -187,6 +190,7 @@ From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify
 6. No unmerged `batch/tracker-additions/*.tsv` files (warns if any remain).
 7. Score column has no markdown bold.
 8. Warn when state ids in `templates/states.yml` drift from the script’s built-in fallback list (or when the file exists but ids failed to parse).
+9. Validate `.jobforge-ledger/events.jsonl` when present.
 
 When the tracker file is missing, checks 1–5 and 7 are skipped; checks 6 and 8 still run.
 
@@ -210,6 +214,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `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/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@razroo/iso-ledger` state over tracker, TSV, and pipeline files |
 | `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/create-job-forge.mjs` | `npx create-job-forge <dir>` | Scaffolds a new personal project |

package/docs/CUSTOMIZATION.md

@@ -125,6 +125,19 @@ 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.
 
+## JobForge ledger
+
+The ledger is append-only local workflow state backed by `@razroo/iso-ledger`. It is not an MCP and does not add prompt, tool-schema, or state-trace tokens. Use it when you want a cheap deterministic check before loading growing tracker files:
+
+```bash
+npx job-forge ledger:rebuild
+npx job-forge ledger:status
+npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
+npx job-forge ledger:verify
+```
+
+`tracker-line --write` records tracker-addition events, `merge` records add/update/skip outcomes, and `ledger:rebuild` backfills events from `data/applications/`, `batch/tracker-additions/`, `batch/tracker-additions/merged/`, and `data/pipeline.md`.
+
 ## 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/README.md

@@ -31,7 +31,7 @@ The harness exposes a single CLI (`job-forge`) installed as a `bin` entry. In a
 
 | What you need | Where to read |
 |---------------|---------------|
-| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
+| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
 | What each harness `.mjs` script does. | [ARCHITECTURE.md — Pipeline integrity](ARCHITECTURE.md#pipeline-integrity) and the scripts table underneath. |
 | Batch runner, TSV layout, and `batch/tracker-additions/` merge flow. | [batch/README.md](../batch/README.md). |
 | PR gate for harness contributions (`npm run verify` + `npm run build:dashboard`). | [CONTRIBUTING.md — Development](../CONTRIBUTING.md#development). |

package/docs/SETUP.md

@@ -138,6 +138,9 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Show one JobForge run by session id/prefix | `npx job-forge telemetry:show <id>` | `npm run telemetry:show -- <id>` |
 | Audit latest JobForge trace policy | `npx job-forge guard:audit` | `npm run guard:audit` |
 | Show the active guard policy | `npx job-forge guard:explain` | `npm run guard:explain` |
+| 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 ...` |
 | 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

@@ -71,6 +71,10 @@ 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
+
+Local workflow ledger (terminal, outside opencode):
+  npx job-forge ledger:status          # .jobforge-ledger/events.jsonl summary
+  npx job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
 ```
 
 ---
@@ -145,6 +149,9 @@ Step 1  — Enumerate candidates
   - Build ordered list: candidates = [job_1, job_2, ..., job_N]
 
 Step 2  — Dedup against already-applied
+  - If .jobforge-ledger/events.jsonl exists, use npx job-forge ledger:has as a
+    fast prefilter for obvious company+role Applied duplicates. A ledger match
+    can be dropped before dispatch without loading tracker files into context.
   - For each candidate, grep all four sources for URL and company+role:
     data/pipeline.md, data/applications/*.md, batch/tracker-additions/*.tsv,
     batch/tracker-additions/merged/*.tsv

package/iso/instructions.md

@@ -7,7 +7,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H1] Max 2 parallel `task` dispatches per message. For N jobs, run `ceil(N/2)` sequential rounds of 2. A round is not complete until both subagents return a final outcome (`APPLIED`, `APPLY FAILED`, `SKIP`, `Discarded`, or a written TSV path). A `task` tool result that only gives a session id / title is a launch acknowledgement, not completion. Applies in all modes, for all user phrasings ("urgent", "apply to 10 jobs now").
   why: each subagent requires post-cleanup and racing more than 2 reliably loses at least one result. On 2026-04-25 the orchestrator launched round 2 while round 1 had only returned task ids, leaving four application subagents in flight and losing two provider recoveries
 
-- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
+- [H2] Max 1 application per company+role. Before every `apply` dispatch, grep all four sources for the URL and for `company+role`: `data/pipeline.md`, all `data/applications/*.md` day files, `batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`. If `.jobforge-ledger/events.jsonl` exists, `npx job-forge ledger:has --company "..." --role "..." --status Applied` may be used as a fast prefilter; a match is enough to drop that duplicate before dispatch. For candidates not rejected by the ledger, the four-source grep is still mandatory. If any source shows APPLIED / Applied, skip the dispatch and pick a replacement from the remaining candidate list. Do not count duplicates toward a requested "apply to N jobs" total, and do not delegate obvious duplicates just so a subagent can return SKIP.
   why: 2026-04 same-day batch collision — when two batches target the same role, `npx job-forge merge` updates the existing day-file row rather than appending, so grepping day files alone misses earlier-batch applies; merged/*.tsv is the only place the breadcrumb remains
 
 - [H3] Before every batch of `task` dispatches that will use Geometra, call `geometra_list_sessions` then `geometra_disconnect({closeBrowser: true})`. Every round, no exceptions. Name this cleanup as an explicit "step 0" in your first-response plan for any multi-apply request — it is the most frequently skipped guardrail in practice, and skipping it produces cascade "Not connected" failures on the next dispatch.
@@ -19,7 +19,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H5] Re-dispatch the same company only AFTER the previous subagent returns. Never fire the same `task` twice while the first is still in flight.
   why: two in-flight subagents for the same URL race on Geometra sessions and on tracker TSV writes, corrupting state and sometimes double-submitting
 
-- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, or `iso-trace`) rather than spawning a "check task status" subagent.
+- [H5b] Do not use `task` to poll task status. If OpenCode returns a task/session id without a final result, record the id, stop dispatching new rounds, and tell the user the round is still in flight. When the user asks to check later, inspect authoritative files (`batch/tracker-additions/*.tsv`, `batch/tracker-additions/merged/*.tsv`, day files, `.jobforge-ledger/events.jsonl`, or `iso-trace`) rather than spawning a "check task status" subagent.
   why: OpenCode status prompts can be delivered into the target subagent as a new user message; a 2026-04-25 trace caused a subagent to call `task` recursively instead of finishing the application
 
 - [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.
@@ -54,12 +54,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
+- [D8] Use `job-forge ledger:*` for cheap local workflow-state checks when available. `iso-ledger` is not an MCP and adds no prompt/tool schema tokens; it records tracker TSV writes, merge outcomes, rebuilt tracker snapshots, and pipeline items in `.jobforge-ledger/events.jsonl`.
+  why: state-trace remains working memory, while iso-ledger is deterministic append-only workflow truth that can answer duplicate/status questions without loading growing markdown/TSV files into the model context
+
 ## 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]; decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].

package/lib/jobforge-ledger.mjs

@@ -0,0 +1,214 @@
+import { existsSync } from 'fs';
+import { isAbsolute, join, relative } from 'path';
+import {
+  appendEvent,
+  hasEvent,
+  materializeLedger,
+  queryEvents,
+  readLedger,
+  verifyLedger,
+} from '@razroo/iso-ledger';
+
+export const LEDGER_DIR = '.jobforge-ledger';
+export const LEDGER_FILE = 'events.jsonl';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeLedgerPath(projectDir = resolveProjectDir()) {
+  return process.env.JOB_FORGE_LEDGER || join(projectDir, LEDGER_DIR, LEDGER_FILE);
+}
+
+export function jobForgeLedgerOptions(projectDir = resolveProjectDir()) {
+  return { path: jobForgeLedgerPath(projectDir) };
+}
+
+export function ledgerExists(projectDir = resolveProjectDir()) {
+  return existsSync(jobForgeLedgerPath(projectDir));
+}
+
+export function readJobForgeLedger(projectDir = resolveProjectDir()) {
+  if (!ledgerExists(projectDir)) return [];
+  return readLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function verifyJobForgeLedger(projectDir = resolveProjectDir()) {
+  return verifyLedger(jobForgeLedgerOptions(projectDir));
+}
+
+export function queryJobForgeLedger(options = {}, projectDir = resolveProjectDir()) {
+  return queryEvents(readJobForgeLedger(projectDir), options);
+}
+
+export function hasJobForgeEvent(options = {}, projectDir = resolveProjectDir()) {
+  return hasEvent(readJobForgeLedger(projectDir), options);
+}
+
+export function jobForgeLedgerSummary(projectDir = resolveProjectDir()) {
+  const events = readJobForgeLedger(projectDir);
+  const materialized = materializeLedger(events);
+  return {
+    path: jobForgeLedgerPath(projectDir),
+    exists: ledgerExists(projectDir),
+    events: events.length,
+    entities: materialized.entityCount,
+    latest: events.at(-1) || null,
+  };
+}
+
+export function appendJobForgeEvent(input, projectDir = resolveProjectDir()) {
+  return appendEvent(jobForgeLedgerOptions(projectDir), input);
+}
+
+export function recordTrackerAdditionWritten(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  return appendJobForgeEvent(buildApplicationEvent('jobforge.tracker_addition.written', addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: 'tracker-addition-written',
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function recordTrackerMergeResult(addition, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const outcome = options.outcome || 'processed';
+  return appendJobForgeEvent(buildApplicationEvent(`jobforge.tracker_merge.${outcome}`, addition, {
+    projectDir,
+    sourceFile: options.sourceFile,
+    idempotencyPrefix: `tracker-merge-${outcome}`,
+    data: {
+      outcome,
+      duplicateNum: jsonValue(options.duplicateNum),
+      reason: jsonValue(options.reason),
+    },
+    meta: options.meta,
+  }), projectDir);
+}
+
+export function buildApplicationEvent(type, app, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = companyRoleKey(app.company, app.role);
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : '';
+  const idempotencyParts = [
+    options.idempotencyPrefix || type,
+    sourceFile,
+    app.num,
+    app.date,
+    key,
+    app.status,
+    app.score,
+  ].filter((value) => value !== undefined && value !== null && String(value).length > 0);
+
+  return {
+    type,
+    key,
+    subject: applicationSubject(app.company, app.role),
+    idempotencyKey: idempotencyParts.join(':'),
+    data: compactObject({
+      num: numberOrString(app.num),
+      date: stringOrEmpty(app.date),
+      company: stringOrEmpty(app.company),
+      role: stringOrEmpty(app.role),
+      score: stringOrEmpty(app.score),
+      status: stringOrEmpty(app.status),
+      pdf: stringOrEmpty(app.pdf),
+      report: stringOrEmpty(app.report),
+      notes: stringOrEmpty(app.notes),
+      sourceFile,
+      ...compactObject(options.data || {}),
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function buildPipelineEvent(item, options = {}) {
+  const projectDir = resolveProjectDir(options.projectDir);
+  const key = item.url ? urlKey(item.url) : `pipeline:${item.lineNumber || 'unknown'}`;
+  const sourceFile = options.sourceFile ? relativePath(projectDir, options.sourceFile) : 'data/pipeline.md';
+  const state = item.checked ? 'processed' : 'pending';
+
+  return {
+    type: 'jobforge.pipeline.item',
+    key,
+    subject: key,
+    idempotencyKey: `pipeline:${state}:${item.url || item.lineNumber || item.line || 'unknown'}`,
+    data: compactObject({
+      state,
+      checked: Boolean(item.checked),
+      url: stringOrEmpty(item.url),
+      company: stringOrEmpty(item.company),
+      role: stringOrEmpty(item.role),
+      line: stringOrEmpty(item.line),
+      lineNumber: numberOrString(item.lineNumber),
+      sourceFile,
+    }),
+    meta: compactObject({
+      source: 'job-forge',
+      ...compactObject(options.meta || {}),
+    }),
+  };
+}
+
+export function companyRoleKey(company, role) {
+  return `company-role:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function applicationSubject(company, role) {
+  return `application:${slugPart(company)}:${slugPart(role)}`;
+}
+
+export function urlKey(url) {
+  return `url:${String(url || '').trim()}`;
+}
+
+export function slugPart(value) {
+  const slug = String(value || 'unknown')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'unknown';
+}
+
+function relativePath(projectDir, value) {
+  const text = String(value || '');
+  if (!text) return '';
+  const rel = relative(projectDir, text);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replace(/\\/g, '/');
+  return text.replace(/\\/g, '/');
+}
+
+function compactObject(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj || {})) {
+    const clean = jsonValue(value);
+    if (clean !== undefined) out[key] = clean;
+  }
+  return out;
+}
+
+function jsonValue(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.map(jsonValue).filter((item) => item !== undefined);
+  if (typeof value === 'object') return compactObject(value);
+  return String(value);
+}
+
+function stringOrEmpty(value) {
+  if (value === undefined || value === null) return undefined;
+  const text = String(value);
+  return text.length > 0 ? text : undefined;
+}
+
+function numberOrString(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && String(value).trim() !== '' ? number : String(value);
+}

package/merge-tracker.mjs

@@ -29,6 +29,7 @@ import {
 import {
   DEFAULT_STATES, loadCanonicalStates, buildStatusDetectionRegex,
 } from './lib/canonical-states.mjs';
+import { recordTrackerMergeResult } from './lib/jobforge-ledger.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const MERGED_DIR = join(ADDITIONS_DIR, 'merged');
@@ -288,6 +289,7 @@ let added = 0;
 let updated = 0;
 let skipped = 0;
 const newEntries = [];
+const ledgerRecords = [];
 
 for (const file of tsvFiles) {
   const content = readFileSync(join(ADDITIONS_DIR, file), 'utf-8').trim();
@@ -359,12 +361,15 @@ for (const file of tsvFiles) {
         }
       }
       updated++;
+      ledgerRecords.push({ addition, outcome: 'updated', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason });
     } else if (statusRegresses) {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} status ${duplicate.status} outranks new ${addition.status})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'status-regression' });
     } else {
       console.log(`⏭️  Skip: ${addition.company} — ${addition.role} (existing #${duplicate.num} ${oldScore} >= new ${newScore})`);
       skipped++;
+      ledgerRecords.push({ addition, outcome: 'skipped', sourceFile: join(ADDITIONS_DIR, file), duplicateNum: duplicate.num, reason: 'no-improvement' });
     }
   } else {
     const entryNum = addition.num > maxNum ? addition.num : ++maxNum;
@@ -376,6 +381,7 @@ for (const file of tsvFiles) {
     });
     added++;
     console.log(`➕ Add #${entryNum}: ${addition.company} — ${addition.role} (${addition.score})`);
+    ledgerRecords.push({ addition: { ...addition, num: entryNum }, outcome: 'added', sourceFile: join(ADDITIONS_DIR, file), reason: 'new-entry' });
   }
 }
 
@@ -410,6 +416,23 @@ if (!DRY_RUN) {
     renameSync(join(ADDITIONS_DIR, file), join(MERGED_DIR, file));
   }
   console.log(`\n✅ Moved ${tsvFiles.length} TSVs to merged/`);
+
+  let ledgerEvents = 0;
+  for (const record of ledgerRecords) {
+    try {
+      const result = recordTrackerMergeResult(record.addition, {
+        projectDir: PROJECT_DIR,
+        sourceFile: record.sourceFile,
+        outcome: record.outcome,
+        duplicateNum: record.duplicateNum,
+        reason: record.reason,
+      });
+      if (result.appended) ledgerEvents++;
+    } catch (error) {
+      console.warn(`⚠️  Could not append ledger event for ${record.sourceFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.log(`🧾 Ledger: ${ledgerEvents} event(s) appended`);
 }
 
 console.log(`\n📊 Summary: +${added} added, 🔄${updated} updated, ⏭️${skipped} skipped`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.15",
+  "version": "2.14.16",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -27,6 +27,11 @@
     "telemetry:watch": "node bin/job-forge.mjs telemetry:watch",
     "guard:audit": "node bin/job-forge.mjs guard:audit",
     "guard:explain": "node bin/job-forge.mjs guard:explain",
+    "ledger:status": "node bin/job-forge.mjs ledger:status",
+    "ledger:rebuild": "node bin/job-forge.mjs ledger:rebuild",
+    "ledger:verify": "node bin/job-forge.mjs ledger:verify",
+    "ledger:has": "node bin/job-forge.mjs ledger:has",
+    "ledger:query": "node bin/job-forge.mjs ledger:query",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -92,6 +97,7 @@
   },
   "dependencies": {
     "@razroo/iso-guard": "^0.1.0",
+    "@razroo/iso-ledger": "^0.1.0",
     "@razroo/iso-orchestrator": "^0.1.0",
     "@razroo/iso-trace": "^0.4.0",
     "playwright": "^1.58.1"

package/scripts/ledger.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'fs';
+import { dirname, join } from 'path';
+import {
+  formatEvents,
+  formatVerifyResult,
+  queryEvents,
+} from '@razroo/iso-ledger';
+import { PROJECT_DIR, readAllEntries } from '../tracker-lib.mjs';
+import {
+  appendJobForgeEvent,
+  buildApplicationEvent,
+  buildPipelineEvent,
+  companyRoleKey,
+  jobForgeLedgerPath,
+  jobForgeLedgerSummary,
+  ledgerExists,
+  readJobForgeLedger,
+  urlKey,
+  verifyJobForgeLedger,
+} from '../lib/jobforge-ledger.mjs';
+
+const USAGE = `job-forge ledger - local deterministic workflow state
+
+Usage:
+  job-forge ledger:status [--json]
+  job-forge ledger:rebuild [--reset] [--json]
+  job-forge ledger:verify [--json]
+  job-forge ledger:has --url <url> [--json]
+  job-forge ledger:has --company <name> --role <role> [--status Applied] [--json]
+  job-forge ledger:query [--type <type>] [--key <key>] [--where field=value] [--limit N] [--json]
+  job-forge ledger:path
+
+The ledger is stored at .jobforge-ledger/events.jsonl by default. It is local
+personal workflow 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(jobForgeLedgerPath(PROJECT_DIR));
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'rebuild') {
+    rebuild(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'has') {
+    has(opts);
+  } else if (cmd === 'query') {
+    query(opts);
+  } else {
+    console.error(`unknown ledger 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 = { where: {}, json: false, reset: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--reset') {
+      opts.reset = 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 === '--company') {
+      opts.company = valueAfter(args, ++i, '--company');
+    } else if (arg.startsWith('--company=')) {
+      opts.company = arg.slice('--company='.length);
+    } else if (arg === '--role') {
+      opts.role = valueAfter(args, ++i, '--role');
+    } else if (arg.startsWith('--role=')) {
+      opts.role = arg.slice('--role='.length);
+    } else if (arg === '--status') {
+      opts.status = valueAfter(args, ++i, '--status');
+    } else if (arg.startsWith('--status=')) {
+      opts.status = arg.slice('--status='.length);
+    } else if (arg === '--type') {
+      opts.type = valueAfter(args, ++i, '--type');
+    } else if (arg.startsWith('--type=')) {
+      opts.type = arg.slice('--type='.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 === '--where') {
+      addWhere(opts.where, valueAfter(args, ++i, '--where'));
+    } else if (arg.startsWith('--where=')) {
+      addWhere(opts.where, arg.slice('--where='.length));
+    } else if (arg === '--limit') {
+      opts.limit = Number(valueAfter(args, ++i, '--limit'));
+    } else if (arg.startsWith('--limit=')) {
+      opts.limit = Number(arg.slice('--limit='.length));
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+  if (opts.status) opts.where.status = opts.status;
+  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 addWhere(where, raw) {
+  const index = raw.indexOf('=');
+  if (index <= 0) throw new Error('--where must be field=value');
+  where[raw.slice(0, index)] = parsePrimitive(raw.slice(index + 1));
+}
+
+function parsePrimitive(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  const number = Number(value);
+  return Number.isFinite(number) && value.trim() !== '' ? number : value;
+}
+
+function status(opts) {
+  const summary = jobForgeLedgerSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  if (!summary.exists) {
+    console.log(`ledger: missing (${relativeLedgerPath()})`);
+    console.log('run: job-forge ledger:rebuild');
+    return;
+  }
+  const verifyResult = verifyJobForgeLedger(PROJECT_DIR);
+  console.log(`ledger:   ${relativeLedgerPath()}`);
+  console.log(`events:   ${summary.events}`);
+  console.log(`entities: ${summary.entities}`);
+  console.log(`verify:   ${verifyResult.ok ? 'PASS' : 'FAIL'} (${verifyResult.errors} errors, ${verifyResult.warnings} warnings)`);
+  if (summary.latest) {
+    console.log(`latest:   ${summary.latest.type} @ ${summary.latest.at}`);
+  }
+}
+
+function rebuild(opts) {
+  const ledgerPath = jobForgeLedgerPath(PROJECT_DIR);
+  if (opts.reset && existsSync(ledgerPath)) rmSync(ledgerPath);
+  mkdirSync(dirname(ledgerPath), { recursive: true });
+
+  const results = [];
+  for (const event of collectProjectEvents()) {
+    results.push(appendJobForgeEvent(event, PROJECT_DIR));
+  }
+
+  const summary = {
+    path: ledgerPath,
+    eventsSeen: results.length,
+    appended: results.filter((result) => result.appended).length,
+    deduped: results.filter((result) => !result.appended).length,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(`ledger: ${relativeLedgerPath()}`);
+  console.log(`events: ${summary.appended} appended, ${summary.deduped} already present`);
+}
+
+function verify(opts) {
+  if (!ledgerExists(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeLedgerPath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`ledger: missing (${relativeLedgerPath()})`);
+    }
+    return;
+  }
+  const result = verifyJobForgeLedger(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.errors > 0 ? 1 : 0);
+}
+
+function has(opts) {
+  const filters = queryFilters(opts);
+  const events = queryEvents(readJobForgeLedger(PROJECT_DIR), filters);
+  if (opts.json) {
+    console.log(JSON.stringify({ match: events.length > 0, count: events.length, filters }, null, 2));
+  } else if (events.length > 0) {
+    console.log(`MATCH (${events.length} event(s))`);
+  } else {
+    console.log('MISS');
+  }
+  process.exit(events.length > 0 ? 0 : 1);
+}
+
+function query(opts) {
+  const filters = queryFilters(opts);
+  const events = queryEvents(readJobForgeLedger(PROJECT_DIR), filters);
+  if (opts.json) {
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+  console.log(formatEvents(events));
+}
+
+function queryFilters(opts) {
+  const filters = {};
+  if (opts.type) filters.type = opts.type;
+  if (opts.key) filters.key = opts.key;
+  if (opts.url) filters.key = urlKey(opts.url);
+  if (opts.company || opts.role) {
+    if (!opts.company || !opts.role) throw new Error('--company and --role must be provided together');
+    filters.key = companyRoleKey(opts.company, opts.role);
+  }
+  if (Object.keys(opts.where || {}).length > 0) filters.where = opts.where;
+  if (Number.isFinite(opts.limit) && opts.limit > 0) filters.limit = opts.limit;
+  return filters;
+}
+
+function collectProjectEvents() {
+  const events = [];
+  const { entries } = readAllEntries();
+  for (const entry of entries) {
+    events.push(buildApplicationEvent('jobforge.application.tracker', entry, {
+      projectDir: PROJECT_DIR,
+      sourceFile: entry._sourceFile,
+      idempotencyPrefix: 'tracker-entry',
+    }));
+  }
+
+  for (const item of collectTrackerTsvs('batch/tracker-additions', 'pending')) {
+    events.push(buildApplicationEvent(`jobforge.tracker_addition.${item.state}`, item.addition, {
+      projectDir: PROJECT_DIR,
+      sourceFile: item.path,
+      idempotencyPrefix: `tracker-addition-${item.state}`,
+      data: { state: item.state },
+    }));
+  }
+
+  for (const item of collectTrackerTsvs('batch/tracker-additions/merged', 'merged')) {
+    events.push(buildApplicationEvent(`jobforge.tracker_addition.${item.state}`, item.addition, {
+      projectDir: PROJECT_DIR,
+      sourceFile: item.path,
+      idempotencyPrefix: `tracker-addition-${item.state}`,
+      data: { state: item.state },
+    }));
+  }
+
+  for (const item of collectPipelineItems()) {
+    events.push(buildPipelineEvent(item, {
+      projectDir: PROJECT_DIR,
+      sourceFile: join(PROJECT_DIR, 'data', 'pipeline.md'),
+    }));
+  }
+
+  return events;
+}
+
+function collectTrackerTsvs(relDir, state) {
+  const dir = join(PROJECT_DIR, relDir);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const out = [];
+  for (const name of readdirSync(dir).filter((file) => file.endsWith('.tsv')).sort()) {
+    const path = join(dir, name);
+    const addition = parseTsvContent(readFileSync(path, 'utf8'), name);
+    if (addition) out.push({ path, state, addition });
+  }
+  return out;
+}
+
+function parseTsvContent(content, filename) {
+  const text = content.trim();
+  if (!text) return null;
+  let parts;
+  if (text.startsWith('|')) {
+    parts = text.split('|').map((part) => part.trim()).filter(Boolean);
+    if (parts.length < 8) return null;
+    return {
+      num: parts[0],
+      date: parts[1],
+      company: parts[2],
+      role: parts[3],
+      score: parts[4],
+      status: parts[5],
+      pdf: parts[6],
+      report: parts[7],
+      notes: parts[8] || '',
+    };
+  }
+
+  parts = text.split('\t');
+  if (parts.length < 8) return null;
+  const col4 = parts[4].trim();
+  const col5 = parts[5].trim();
+  const col4LooksLikeScore = looksLikeScore(col4);
+  const col5LooksLikeScore = looksLikeScore(col5);
+  return {
+    num: parts[0],
+    date: parts[1],
+    company: parts[2],
+    role: parts[3],
+    status: col4LooksLikeScore && !col5LooksLikeScore ? col5 : col4,
+    score: col4LooksLikeScore && !col5LooksLikeScore ? col4 : col5,
+    pdf: parts[6],
+    report: parts[7],
+    notes: parts[8] || '',
+    sourceFile: filename,
+  };
+}
+
+function looksLikeScore(value) {
+  return /^\d+\.?\d*\/5$/.test(value) || value === 'N/A' || value === 'DUP';
+}
+
+function collectPipelineItems() {
+  const path = join(PROJECT_DIR, 'data', 'pipeline.md');
+  if (!existsSync(path)) return [];
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const out = [];
+  lines.forEach((line, index) => {
+    const match = line.match(/^\s*-\s*\[([ xX])\]\s+([^|#\s]+)(.*)$/);
+    if (!match) return;
+    const rest = match[3] || '';
+    const fields = rest.split('|').map((field) => field.trim()).filter(Boolean);
+    out.push({
+      checked: match[1].toLowerCase() === 'x',
+      url: match[2].trim(),
+      company: fields[0] || '',
+      role: fields[1] || '',
+      line,
+      lineNumber: index + 1,
+    });
+  });
+  return out;
+}
+
+function relativeLedgerPath() {
+  return jobForgeLedgerPath(PROJECT_DIR).replace(`${PROJECT_DIR}/`, '');
+}

package/scripts/telemetry.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from 'child_process';
 import { existsSync, readdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import { defaultOpenCodeDbPath, findSessionById, parseSinceCutoff } from '@razroo/iso-trace';
+import { jobForgeLedgerSummary } from '../lib/jobforge-ledger.mjs';
 
 const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
 const DEFAULT_SINCE = '24h';
@@ -485,9 +486,21 @@ function sessionStatus({ taskCalls, children, childOutcomes, childProviderErrors
 function trackerStatus(projectDir) {
   const pendingDir = join(projectDir, 'batch', 'tracker-additions');
   const mergedDir = join(pendingDir, 'merged');
+  let ledger;
+  try {
+    ledger = jobForgeLedgerSummary(projectDir);
+  } catch (error) {
+    ledger = {
+      exists: true,
+      events: 0,
+      entities: 0,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
   return {
     pending: listTsv(pendingDir),
     mergedCount: listTsv(mergedDir).length,
+    ledger,
   };
 }
 
@@ -636,6 +649,7 @@ function printStatus(telemetry) {
   console.log(`tasks:     ${telemetry.tasks.total} (${telemetry.tasks.statusPolls} status-poll, ${telemetry.tasks.running} running)`);
   console.log(`children:  ${telemetry.children.withOutcomes}/${telemetry.children.total} with outcomes`);
   console.log(`tracker:   ${telemetry.tracker.pending.length} pending TSVs, ${telemetry.tracker.mergedCount} merged TSVs`);
+  console.log(`ledger:    ${telemetry.tracker.ledger.error ? `error: ${telemetry.tracker.ledger.error}` : telemetry.tracker.ledger.exists ? `${telemetry.tracker.ledger.events} events` : 'missing'}`);
   console.log(`models:    ${telemetry.models.slice(0, 3).map(modelLabel).join(', ') || 'none'}`);
   console.log(`errors:    ${telemetry.providerErrors.length} root, ${telemetry.children.providerErrors} child provider errors, ${telemetry.children.toolErrors} child tool errors`);
   console.log(`issues:    ${telemetry.policyIssues.length}`);

package/scripts/tracker-line.mjs

@@ -24,6 +24,7 @@
 
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
+import { recordTrackerAdditionWritten } from '../lib/jobforge-ledger.mjs';
 
 const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
 
@@ -61,6 +62,13 @@ if (write) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const path = join(dir, `${num}.tsv`);
   writeFileSync(path, line + '\n', 'utf-8');
+  try {
+    recordTrackerAdditionWritten({
+      num, date, company, role, status, score: scoreField, pdf, report: reportLink, notes,
+    }, { projectDir: PROJECT_DIR, sourceFile: path });
+  } catch (error) {
+    console.warn(`warning: could not append tracker-line ledger event: ${error instanceof Error ? error.message : String(error)}`);
+  }
   console.log(path);
 } else {
   console.log(line);

package/verify-pipeline.mjs

@@ -15,6 +15,7 @@
  * 6. No pending TSVs in tracker-additions/ (runs even when tracker file is missing)
  * 7. No markdown bold in score column
  * 8. Drift warning if states.yml ids differ from the built-in fallback list
+ * 9. Ledger file verifies if .jobforge-ledger/events.jsonl exists
  *
  * Run: node verify-pipeline.mjs   (from repo root; same as npm run verify)
  */
@@ -26,6 +27,7 @@ import {
   PROJECT_DIR, DATA_APPS_DIR, DATA_APPS_FILE, ROOT_APPS_FILE,
   usesDayFiles, readAllEntries, listDayFiles, dayFilePath,
 } from './tracker-lib.mjs';
+import { jobForgeLedgerPath, ledgerExists, verifyJobForgeLedger } from './lib/jobforge-ledger.mjs';
 
 const ADDITIONS_DIR = join(PROJECT_DIR, 'batch/tracker-additions');
 const STATES_FILE = existsSync(join(PROJECT_DIR, 'templates/states.yml'))
@@ -127,6 +129,23 @@ function verifyStatesYamlDrift() {
   }
 }
 
+function verifyLedgerIfPresent() {
+  if (!ledgerExists(PROJECT_DIR)) {
+    ok('Ledger not initialized');
+    return;
+  }
+  const result = verifyJobForgeLedger(PROJECT_DIR);
+  for (const issue of result.issues) {
+    const prefix = issue.line ? `ledger line ${issue.line}` : 'ledger';
+    const msg = `${prefix}: ${issue.code}: ${issue.message}`;
+    if (issue.severity === 'error') error(msg);
+    else warn(msg);
+  }
+  if (result.errors === 0) {
+    ok(`Ledger valid (${result.eventCount} events at ${relative(PROJECT_DIR, jobForgeLedgerPath(PROJECT_DIR))})`);
+  }
+}
+
 // --- Read entries ---
 const { entries, source } = readAllEntries();
 
@@ -135,6 +154,7 @@ if (entries.length === 0) {
   console.log('   This is normal for a fresh setup.\n');
   checkPendingTrackerAdditions();
   verifyStatesYamlDrift();
+  verifyLedgerIfPresent();
   console.log('\n' + '='.repeat(50));
   console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);
   if (errors === 0 && warnings === 0) console.log('🟢 Pipeline is clean!');
@@ -254,6 +274,7 @@ for (const e of entries) {
 if (boldScores === 0) ok('No bold in scores');
 
 verifyStatesYamlDrift();
+verifyLedgerIfPresent();
 
 console.log('\n' + '='.repeat(50));
 console.log(`📊 Pipeline Health: ${errors} errors, ${warnings} warnings`);