job-forge 2.0.0

package/bin/create-job-forge.mjs

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * create-job-forge — Scaffold a new job-forge personal project.
+ *
+ * Usage:
+ *   npx create-job-forge <dir>            # scaffold into <dir>
+ *   npx create-job-forge .                # scaffold into cwd
+ *   npx create-job-forge <dir> --force    # overwrite existing files
+ *
+ * Creates the minimum a consumer needs:
+ *   package.json           with job-forge as a dependency
+ *   opencode.json          thin config enabling MCPs + states.yml instruction
+ *   config/profile.yml     copied from profile.example.yml
+ *   cv.md                  stub for the user to fill in
+ *   portals.yml            copied from templates/portals.example.yml
+ *   data/                  empty dir for tracker/pipeline/scan history
+ *   reports/               empty dir for generated reports
+ *   .gitignore             excludes personal data from sharing
+ *   README.md              setup instructions
+ *
+ * After scaffold, prompts the user to run `npm install`, which triggers the
+ * postinstall symlink sync.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, readFileSync } from 'fs';
+import { dirname, join, resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+const args = process.argv.slice(2);
+const FORCE = args.includes('--force');
+const HELP = args.includes('--help') || args.includes('-h');
+const positional = args.filter(a => !a.startsWith('--'));
+
+if (HELP || positional.length === 0) {
+  console.log(`create-job-forge — scaffold a new job-forge personal project
+
+Usage:
+  npx create-job-forge <dir> [--force]
+
+Examples:
+  npx create-job-forge my-job-search
+  npx create-job-forge .
+  npx create-job-forge existing-project --force
+
+Flags:
+  --force   Overwrite files that already exist
+  --help    Show this message
+
+After scaffolding, cd into the directory and run:
+  npm install                # pulls the harness and creates symlinks
+  # Edit cv.md, config/profile.yml, portals.yml with your personal data
+  opencode                   # start the TUI
+`);
+  process.exit(HELP ? 0 : 1);
+}
+
+const targetDir = resolve(positional[0]);
+const name = basename(targetDir);
+
+console.log(`\nScaffolding job-forge project in ${targetDir}\n`);
+
+if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+
+function write(rel, content, { overwrite = FORCE } = {}) {
+  const abs = join(targetDir, rel);
+  if (existsSync(abs) && !overwrite) {
+    console.log(`  skip: ${rel} (exists)`);
+    return;
+  }
+  const parent = dirname(abs);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+  writeFileSync(abs, content, 'utf-8');
+  console.log(`  create: ${rel}`);
+}
+
+function copy(srcRel, dstRel, { overwrite = FORCE } = {}) {
+  const abs = join(targetDir, dstRel);
+  const src = join(PKG_ROOT, srcRel);
+  if (!existsSync(src)) {
+    console.log(`  skip: ${dstRel} (template ${srcRel} not found)`);
+    return;
+  }
+  if (existsSync(abs) && !overwrite) {
+    console.log(`  skip: ${dstRel} (exists)`);
+    return;
+  }
+  const parent = dirname(abs);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+  copyFileSync(src, abs);
+  console.log(`  create: ${dstRel}`);
+}
+
+// ---------- package.json ----------
+
+const consumerPkg = {
+  name,
+  version: '0.1.0',
+  private: true,
+  scripts: {
+    sync: 'job-forge sync',
+    merge: 'job-forge merge',
+    verify: 'job-forge verify',
+    dedup: 'job-forge dedup',
+    normalize: 'job-forge normalize',
+    pdf: 'job-forge pdf',
+    'sync-check': 'job-forge sync-check',
+    tokens: 'job-forge tokens',
+    'tokens:today': 'job-forge tokens --days 1',
+    'tokens:log': 'job-forge tokens --days 1 --append',
+    // One command to pull the latest harness, companion plugin, 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 invoke them via `npx -y` without pinning.
+    'update-harness': 'npm update job-forge @razroo/opencode-model-fallback @razroo/gmail-mcp @geometra/mcp && job-forge sync && node -e "console.log(\'✅ harness at\', require(\'./package-lock.json\').packages[\'node_modules/job-forge\'].resolved)"',
+  },
+  dependencies: {
+    'job-forge': 'github:razroo/JobForge',
+    // Model-fallback plugin: rotates agents through their fallback_models
+    // chain on rate-limit / 5xx errors so a rate-limited free-tier model
+    // doesn't wedge the whole flow. The chains live upstream in each
+    // agent's MD frontmatter (`.opencode/agents/*.md` in the harness);
+    // consumers can override individual chains by adding their own
+    // agent.<name>.fallback_models block to opencode.json. Requires
+    // 0.3.1+ for the frontmatter-merge path.
+    '@razroo/opencode-model-fallback': '^0.3.1',
+  },
+  engines: { node: '>=18' },
+};
+write('package.json', JSON.stringify(consumerPkg, null, 2) + '\n');
+
+// ---------- opencode.json ----------
+
+const opencodeCfg = {
+  $schema: 'https://opencode.ai/config.json',
+  // Model-fallback plugin: on rate-limit / 5xx / known provider errors,
+  // rotates the agent's model to the next entry in its fallback_models
+  // chain (see `agent` below) and replays the request. Without this, a
+  // rate-limited free-tier model wedges the whole subagent flow.
+  plugin: ['@razroo/opencode-model-fallback'],
+  // Files listed here load into every session's cached prefix, so they're
+  // cached once (on Anthropic) instead of Read-as-tool-call on every session.
+  //   AGENTS.harness.md → symlink to node_modules/job-forge/AGENTS.md (harness rules)
+  //   modes/_shared.md  → symlink into node_modules; canonical scoring model
+  //   cv.md             → candidate's CV (personal, created during onboarding)
+  //   templates/states.yml → canonical application states (validated by merge-tracker.mjs)
+  // Ordering matters for cache prefix stability: put most-stable files first.
+  instructions: [
+    'AGENTS.harness.md',
+    'templates/states.yml',
+    'modes/_shared.md',
+    'cv.md',
+  ],
+  mcp: {
+    geometra: {
+      type: 'local',
+      command: ['npx', '-y', '@geometra/mcp'],
+      enabled: true,
+    },
+    gmail: {
+      type: 'local',
+      command: ['npx', '-y', '@razroo/gmail-mcp'],
+      enabled: true,
+      // @razroo/gmail-mcp >=1.7.9 honors DISABLE_HTTP=true to skip its
+      // Streamable HTTP listener. Opencode uses stdio transport, so
+      // the HTTP server is unused and its port (default 3000) only
+      // causes EADDRINUSE conflicts with other local processes.
+      environment: { DISABLE_HTTP: 'true' },
+    },
+  },
+  // Restrict the primary orchestrator to dispatching only the three harness
+  // subagents. Prevents accidental self-calls or unregistered agents.
+  // Override locally in opencode.json if you add project-specific agents.
+  permission: {
+    task: {
+      'general-free': 'allow',
+      'general-paid': 'allow',
+      'glm-minimal': 'allow',
+    },
+  },
+  // Tool-surface trimming — opencode ships every MCP tool's schema in every
+  // request unless disabled. The harness uses ~10 of Geometra's ~30 tools
+  // and ~4 of Gmail's. Disable all at the root level and re-enable the
+  // specific ones needed per agent in .opencode/agents/<name>.md. Saves
+  // ~2-3K tokens per request in the orchestrator's context window.
+  tools: {
+    'geometra_*': false,
+    'gmail_*': false,
+  },
+};
+write('opencode.json', JSON.stringify(opencodeCfg, null, 2) + '\n');
+
+// ---------- AGENTS.md (auto-loaded by opencode on every session) ----------
+//
+// This file is intentionally thin. The harness's operational rules (Session
+// Hygiene, OTP handling, batch best practices, scoring) live in
+// node_modules/job-forge/AGENTS.md and load via opencode.json:instructions →
+// AGENTS.harness.md (symlink created by sync.mjs). Keep *this* file for
+// personal overrides.
+
+write('AGENTS.md', `# AGENTS — ${name}
+
+Personal job search project using the [job-forge](https://github.com/razroo/JobForge) harness. The harness lives in \`node_modules/job-forge/\`; most files you need are accessible through symlinks at the project root.
+
+**How context loads in this project:** opencode auto-loads *this* file as the project-root AGENTS.md, and also loads \`AGENTS.harness.md\` via \`opencode.json:instructions\` — that second file is a symlink to \`node_modules/job-forge/AGENTS.md\` and carries the shared operational rules (Session Hygiene, OTP handling, batch best practices, scoring). Keep *this* file for personal overrides — anything you want to diverge from or add on top.
+
+---
+
+## Project Layout — start here
+
+Before doing any work, remember where things live in *this* project:
+
+| What | Where | Notes |
+|------|-------|-------|
+| 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\` |
+| 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 |
+| Proof points | \`article-digest.md\` | Optional, at project root |
+| Skill modes | \`modes/\` (symlink) | \`.md\` files, one per skill. Read \`modes/_shared.md\` for scoring and \`modes/{mode}.md\` for the mode. |
+| Skill router | \`.opencode/skills/job-forge.md\` (symlink) | How \`/job-forge <mode>\` dispatches |
+| Batch prompt template | \`batch/batch-prompt.md\` (symlink) | Used by \`batch/batch-runner.sh\` |
+| Batch runner | \`batch/batch-runner.sh\` (symlink) | Parallel \`opencode run\` orchestrator |
+| Batch input / state | \`batch/batch-input.tsv\`, \`batch/batch-state.tsv\` | Personal data |
+| Generated reports | \`reports/{###}-{company-slug}-{YYYY-MM-DD}.md\` | Gitignored |
+| Generated PDFs | \`output/\` | Gitignored |
+| Templates | \`templates/\` (symlink) | \`cv-template.html\`, \`portals.example.yml\`, \`states.yml\` |
+| Harness rules | \`AGENTS.harness.md\` (symlink) | Shared operational guide, loaded via \`opencode.json:instructions\` |
+| Harness source | \`node_modules/job-forge/\` | Read this for harness internals |
+
+**\`modes/\`, \`templates/\`, \`.opencode/skills/job-forge.md\`, \`batch/batch-prompt.md\`, \`batch/batch-runner.sh\`, \`batch/README.md\`, and \`AGENTS.harness.md\` are all symlinks into \`node_modules/job-forge/\`.** Symlinks behave like real files for Read/Glob/Grep — no need to chase them into \`node_modules\` unless you want to see their real path.
+
+When the user says something like "apply to N jobs", the candidates to apply to are either:
+1. Entries in \`data/applications/*.md\` with status **Evaluated** (already scored, ready to submit)
+2. URLs in \`data/pipeline.md\` that haven't been evaluated yet
+
+Check both. Read today's day file (\`data/applications/$(date +%Y-%m-%d).md\`) plus the latest few day files for recent Evaluated entries.
+
+---
+
+## Personal additions
+
+(Add project-specific rules below — model preferences, Geometra quirks, overrides to harness defaults, etc. Shared operational rules live in \`AGENTS.harness.md\`.)
+`);
+
+// ---------- Personal files (from templates) ----------
+
+copy('config/profile.example.yml', 'config/profile.yml');
+copy('templates/portals.example.yml', 'portals.yml');
+
+// ---------- CV stub ----------
+
+write('cv.md', `# Your Name
+
+your.email@example.com · +1 (XXX) XXX-XXXX · City, Country
+[LinkedIn](https://linkedin.com/in/you) · [GitHub](https://github.com/you)
+
+## Summary
+
+(One-paragraph pitch about who you are, what you've built, and what you're looking for.)
+
+## Experience
+
+### Current Company — Title
+*Dates*
+
+- Bullet describing impact with a metric.
+- Bullet describing impact with a metric.
+
+## Skills
+
+(Comma-separated list grouped by category.)
+
+## Education
+
+Degree, Institution, Year
+`);
+
+// ---------- Empty personal dirs ----------
+
+for (const dir of ['data', 'data/applications', 'reports', 'batch/tracker-additions']) {
+  const abs = join(targetDir, dir);
+  if (!existsSync(abs)) {
+    mkdirSync(abs, { recursive: true });
+    writeFileSync(join(abs, '.gitkeep'), '', 'utf-8');
+    console.log(`  create: ${dir}/`);
+  }
+}
+
+// ---------- .gitignore ----------
+
+write('.gitignore', `# Personal data (your job search — don't share)
+cv.md
+article-digest.md
+portals.yml
+config/profile.yml
+data/applications/
+!data/applications/.gitkeep
+data/applications.md
+data/pipeline.md
+data/scan-history.tsv
+data/token-usage.tsv
+reports/
+!reports/.gitkeep
+batch/batch-state.tsv
+batch/batch-state.tsv.bak
+batch/batch-input.tsv
+batch/tracker-additions/
+!batch/tracker-additions/.gitkeep
+batch/logs/
+
+# Harness symlinks (regenerated by npm install)
+/modes
+/templates
+/.cursor/mcp.json
+/.opencode/skills/job-forge.md
+/.opencode/agents
+/batch/batch-prompt.md
+/batch/batch-runner.sh
+/batch/README.md
+/AGENTS.harness.md
+
+# Standard
+node_modules/
+.DS_Store
+*.log
+`);
+
+// ---------- README ----------
+
+write('README.md', `# ${name}
+
+Personal job search project using the [job-forge](https://github.com/razroo/JobForge) harness.
+
+## Setup
+
+\`\`\`bash
+npm install           # pulls the harness and creates symlinks to modes/, templates/, etc.
+\`\`\`
+
+Then fill in:
+
+- \`cv.md\` — your CV in markdown
+- \`config/profile.yml\` — your identity and target roles
+- \`portals.yml\` — companies you want to scan
+
+## Updating the harness
+
+\`\`\`bash
+npm update job-forge       # pulls the latest from razroo/JobForge
+job-forge sync             # re-run if symlinks drift
+\`\`\`
+
+## Common commands
+
+\`\`\`bash
+job-forge merge            # merge batch/tracker-additions/*.tsv into the tracker
+job-forge verify           # verify pipeline integrity
+job-forge pdf cv.md out.pdf
+job-forge tokens --days 1  # per-session opencode token usage
+\`\`\`
+`);
+
+console.log(`
+Done. Next steps:
+
+  cd ${targetDir}
+  npm install
+  # edit cv.md, config/profile.yml, portals.yml
+  opencode
+`);

package/bin/job-forge.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * job-forge — CLI dispatcher for the job-forge harness.
+ *
+ * Runs the .mjs scripts shipped in this package against the consumer's cwd.
+ * All scripts resolve the project dir via `process.env.JOB_FORGE_PROJECT ||
+ * process.cwd()`, so running this bin from a consumer project Just Works.
+ *
+ * Usage:
+ *   job-forge <command> [args...]
+ *
+ * Commands:
+ *   merge          Run merge-tracker.mjs
+ *   dedup          Run dedup-tracker.mjs
+ *   verify         Run verify-pipeline.mjs
+ *   normalize      Run normalize-statuses.mjs
+ *   pdf            Run generate-pdf.mjs
+ *   sync-check     Run cv-sync-check.mjs
+ *   tokens         Run scripts/token-usage-report.mjs
+ *   sync           Re-run the harness symlink sync (bin/sync.mjs)
+ *   help, --help   Show this message
+ */
+
+import { spawnSync } from 'child_process';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+const commands = {
+  merge:        'merge-tracker.mjs',
+  dedup:        'dedup-tracker.mjs',
+  verify:       'verify-pipeline.mjs',
+  normalize:    'normalize-statuses.mjs',
+  pdf:          'generate-pdf.mjs',
+  'sync-check': 'cv-sync-check.mjs',
+  tokens:       'scripts/token-usage-report.mjs',
+  sync:         'bin/sync.mjs',
+  // Deterministic helpers — agents call these instead of deriving values
+  // themselves, which saves thinking + Bash + verify tokens per invocation.
+  'next-num':       'scripts/next-num.mjs',
+  slugify:          'scripts/slugify.mjs',
+  today:            'scripts/today.mjs',
+  'tracker-line':   'scripts/tracker-line.mjs',
+  // Auto-visibility into cost: run at end of session or batch to log usage
+  // and warn on >$budget sessions. No opencode lifecycle hook exists, so
+  // this is the closest to a SessionEnd trigger — wire it into your
+  // shell wrapper around `opencode`, or into batch-runner.sh (already done).
+  'session-report':       'scripts/session-report.mjs',
+  'render-report-header': 'scripts/render-report-header.mjs',
+};
+
+const [, , cmd, ...rest] = process.argv;
+
+function printHelp() {
+  console.log(`job-forge — CLI for the job-forge harness
+
+Usage:
+  job-forge <command> [args...]
+
+Commands:
+  merge          Merge batch/tracker-additions/*.tsv into the tracker
+  dedup          Remove duplicate entries from the tracker
+  verify         Verify pipeline integrity (reports, URLs, dedup)
+  normalize      Normalize status values across the tracker
+  pdf            Generate ATS-optimized CV PDF from cv.md
+  sync-check     Lint: verify cv.md and profile.yml are filled in
+  tokens         Show opencode token usage and cost by session/day
+  sync           Re-create harness symlinks in the current project
+
+Deterministic helpers (prefer these over LLM-derived values):
+  next-num       Print next sequential report number (e.g. 521)
+  slugify NAME   Convert a company/role name to a filename-safe slug
+  today          Print today's date in YYYY-MM-DD
+  tracker-line   Emit a 9-col TSV row for batch/tracker-additions/
+
+Cost visibility:
+  session-report        Summarize recent session costs, warn on >budget sessions
+                        (e.g. job-forge session-report --since-minutes 60 --log)
+
+Report assembly:
+  render-report-header  Given a score JSON on stdin, print the canonical
+                        report header + "## Score" section. Agents append
+                        Blocks A-F after this instead of re-emitting the
+                        standard boilerplate every evaluation.
+
+Pass --help after a command to see its own flags, e.g.:
+  job-forge merge --help
+  job-forge tokens --days 1
+  job-forge slugify "Anthropic, PBC"
+
+Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
+}
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+const rel = commands[cmd];
+if (!rel) {
+  console.error(`Unknown command: ${cmd}\n`);
+  printHelp();
+  process.exit(2);
+}
+
+const scriptPath = join(PKG_ROOT, rel);
+if (!existsSync(scriptPath)) {
+  console.error(`Internal error: script ${rel} not found at ${scriptPath}`);
+  process.exit(2);
+}
+
+const result = spawnSync(process.execPath, [scriptPath, ...rest], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(result.status ?? 1);

package/bin/sync.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * sync.mjs — Create/refresh harness symlinks in the consumer's project.
+ *
+ * When job-forge is installed as an npm dependency, opencode / cursor /
+ * claude code / codex need to see certain files at the *consumer project
+ * root* (not inside node_modules). All of these are generated at publish
+ * time by iso-harness from the harness's iso/ source; this script mirrors
+ * them into the consumer's layout via symlinks.
+ *
+ * This script creates symlinks to the harness copies. Idempotent:
+ *   - If the symlink already points to the harness, skip.
+ *   - If a real file/dir exists at the target (user customized), warn and skip.
+ *   - Otherwise create the symlink.
+ *
+ * Invoked automatically by `postinstall` in the package, or manually via
+ * `npx job-forge sync`.
+ *
+ * Skipped when running inside the harness repo itself (detected by checking
+ * whether the cwd contains the harness's own package.json with name=job-forge).
+ */
+
+import { existsSync, lstatSync, readlinkSync, symlinkSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join, resolve, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+// Resolve the consumer's project root. During npm install, INIT_CWD is the
+// directory from which npm install was run (the consumer project).
+// Fallback to cwd.
+const PROJECT_DIR = process.env.INIT_CWD || process.env.JOB_FORGE_PROJECT || process.cwd();
+
+// Skip if we're inside the harness itself (avoid self-symlinking during dev).
+const pkgJsonPath = join(PROJECT_DIR, 'package.json');
+if (existsSync(pkgJsonPath)) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    if (pkg.name === 'job-forge' && PROJECT_DIR === PKG_ROOT) {
+      console.log('job-forge sync: skipping (running inside harness repo).');
+      process.exit(0);
+    }
+  } catch { /* ignore */ }
+}
+
+if (PROJECT_DIR === PKG_ROOT) {
+  console.log('job-forge sync: skipping (PROJECT_DIR == PKG_ROOT).');
+  process.exit(0);
+}
+
+// ---------- Symlink plan ----------
+
+// Each entry: { source (inside harness), target (inside consumer project) }
+const links = [
+  // Cursor: MCP servers + always-apply rule (harness-level). Consumers can
+  // add their own rules in .cursor/rules/ alongside this one.
+  { src: '.cursor/mcp.json',               dst: '.cursor/mcp.json' },
+  { src: '.cursor/rules/main.mdc',         dst: '.cursor/rules/main.mdc' },
+
+  // Claude Code: MCP config (.mcp.json is what claude-code reads for
+  // project-scoped MCP). No subagents/commands emitted because iso/agents/
+  // and iso/commands/ are flagged claude: skip.
+  { src: '.mcp.json',                      dst: '.mcp.json' },
+
+  // Codex: MCP config.
+  { src: '.codex/config.toml',             dst: '.codex/config.toml' },
+
+  // OpenCode: skill router + subagent definitions. Users can override any
+  // single subagent by replacing its symlink with a local file.
+  { src: '.opencode/skills/job-forge.md',  dst: '.opencode/skills/job-forge.md' },
+  { src: '.opencode/agents',               dst: '.opencode/agents' },
+
+  // Shared content directories referenced by opencode.json instructions +
+  // skill router (Read's modes/{mode}.md, etc).
+  { src: 'modes',                          dst: 'modes' },
+  { src: 'templates',                      dst: 'templates' },
+  { src: 'batch/batch-prompt.md',          dst: 'batch/batch-prompt.md' },
+  { src: 'batch/batch-runner.sh',          dst: 'batch/batch-runner.sh' },
+  { src: 'batch/README.md',                dst: 'batch/README.md' },
+
+  // Top-level instructions surfaced at project root with a `.harness`
+  // suffix so the consumer's own AGENTS.md / CLAUDE.md stay fully personal.
+  // The consumer's opencode.json / CLAUDE.md / AGENTS.md references the
+  // .harness.md variants to pull in shared context.
+  { src: 'AGENTS.md',                      dst: 'AGENTS.harness.md' },
+  { src: 'CLAUDE.md',                      dst: 'CLAUDE.harness.md' },
+];
+
+let created = 0, skipped = 0, warned = 0;
+
+for (const { src, dst } of links) {
+  const absSrc = join(PKG_ROOT, src);
+  const absDst = join(PROJECT_DIR, dst);
+
+  if (!existsSync(absSrc)) {
+    console.warn(`  skip: ${src} not found in harness`);
+    continue;
+  }
+
+  // Ensure parent dir exists
+  const parent = dirname(absDst);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+
+  // Check current state of target
+  let stat = null;
+  try { stat = lstatSync(absDst); } catch {}
+
+  if (stat) {
+    if (stat.isSymbolicLink()) {
+      const current = readlinkSync(absDst);
+      const expected = relative(dirname(absDst), absSrc);
+      if (current === expected || resolve(dirname(absDst), current) === absSrc) {
+        skipped++;
+        continue;
+      }
+      // Points elsewhere — user may have pinned to a different version
+      console.warn(`  warn: ${dst} is a symlink pointing elsewhere (${current}) — leaving alone`);
+      warned++;
+      continue;
+    }
+    // Real file/dir exists
+    console.warn(`  warn: ${dst} already exists as a real file/dir — leaving alone`);
+    warned++;
+    continue;
+  }
+
+  // Create symlink (relative, so the project remains portable)
+  const relSrc = relative(dirname(absDst), absSrc);
+  const type = lstatSync(absSrc).isDirectory() ? 'dir' : 'file';
+  try {
+    symlinkSync(relSrc, absDst, type);
+    console.log(`  linked: ${dst} → ${relSrc}`);
+    created++;
+  } catch (e) {
+    console.error(`  error: failed to symlink ${dst}: ${e.message}`);
+    warned++;
+  }
+}
+
+console.log(`\njob-forge sync: ${created} created, ${skipped} up-to-date, ${warned} warnings (project: ${PROJECT_DIR})`);