@forwardimpact/outpost 3.0.3

package/templates/.claude/skills/req-scan/references/state.md

@@ -0,0 +1,54 @@
+# State Script Reference
+
+`req-scan` uses `node scripts/state.mjs <command> [args]` for **all** state-file
+operations. Do **not** write bespoke scripts to update cursor, seen, prospects,
+failures, or log files.
+
+## Cursor (source rotation)
+
+```bash
+node scripts/state.mjs cursor list
+node scripts/state.mjs cursor get github_open_to_work
+node scripts/state.mjs cursor set github_open_to_work "2026-03-09T22:00:00Z" "UK-done_next:Europe"
+```
+
+## Seen (deduplication)
+
+```bash
+# exit 0 = seen, 1 = new
+node scripts/state.mjs seen check github_open_to_work mxmxmx333
+
+node scripts/state.mjs seen add github_open_to_work mxmxmx333
+node scripts/state.mjs seen batch github_open_to_work id1 id2 id3 id4
+```
+
+## Prospects
+
+```bash
+node scripts/state.mjs prospect add "Hasan Cam" github_open_to_work strong "J060-J070 platform"
+node scripts/state.mjs prospect list --limit 10
+node scripts/state.mjs prospect count
+```
+
+## Failures
+
+```bash
+# Source selection — skip if ≥ 3
+node scripts/state.mjs failure get mastodon_hachyderm
+
+node scripts/state.mjs failure increment mastodon_hachyderm
+node scripts/state.mjs failure reset github_open_to_work
+```
+
+## Logging
+
+```bash
+node scripts/state.mjs log-wake github_open_to_work "Primary query: 'open to work' location:UK — 30 results, 2 new prospects"
+node scripts/state.mjs log "Manual note about source rotation"
+```
+
+## Summary
+
+```bash
+node scripts/state.mjs summary
+```

package/templates/.claude/skills/req-scan/references/template.md

@@ -0,0 +1,36 @@
+# Prospect Note Template
+
+Reference for `req-scan` Step 4. Save to `knowledge/Prospects/{Name}.md`.
+
+```markdown
+# {Name}
+
+## Info
+**Source:** [{platform}]({permalink})
+**Date found:** {YYYY-MM-DD}
+**Location:** {location or "Not specified"}
+**Estimated level:** {J040–J110} (confidence: {high/medium/low})
+**Best track fit:** {forward_deployed / platform / either}
+**Match strength:** {strong / moderate}
+
+## Profile
+{2–4 sentences: who they are, what they do, why they match. Reference
+specific agent-aligned standard skill IDs in parentheses where possible.}
+
+## Agent-Aligned Standard Alignment
+**Matching skills:** {comma-separated skill IDs}
+**Key strengths:** {what stands out relative to the standard}
+**Gaps:** {notable missing skills for the estimated role}
+
+## Source Post
+> {Brief excerpt or summary of the original post — 2-3 lines max}
+
+## Notes
+{Additional observations: polymath signals, AI-tool usage, unusual
+background combinations, anything noteworthy for the user.}
+```
+
+## Naming
+
+Use the candidate's display name as given. If only a username is available, use
+the username. **Never fabricate real names.**

package/templates/.claude/skills/req-scan/scripts/state.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env bun
+/**
+ * Manage head-hunter agent state files.
+ *
+ * Provides atomic operations on the 5 state files used by the head-hunter agent:
+ *   cursor.tsv   — source rotation state (source, last_checked, position)
+ *   seen.tsv     — deduplication index (source, id, date)
+ *   prospects.tsv — prospect index (name, source, date, strength, level)
+ *   failures.tsv — consecutive failure counts (source, count)
+ *   log.md       — append-only activity log
+ *
+ * Usage:
+ *   node scripts/state.mjs cursor get <source>
+ *   node scripts/state.mjs cursor set <source> <timestamp> <position>
+ *   node scripts/state.mjs seen check <source> <id>
+ *   node scripts/state.mjs seen add <source> <id> [<date>]
+ *   node scripts/state.mjs prospect add <name> <source> <strength> <level>
+ *   node scripts/state.mjs prospect list [--limit N]
+ *   node scripts/state.mjs failure get <source>
+ *   node scripts/state.mjs failure increment <source>
+ *   node scripts/state.mjs failure reset <source>
+ *   node scripts/state.mjs log <message>
+ *   node scripts/state.mjs log-wake <source> <summary>
+ *   node scripts/state.mjs summary
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+const STATE_DIR = join(HOME, ".cache/fit/outpost/head-hunter");
+
+const PATHS = {
+  cursor: join(STATE_DIR, "cursor.tsv"),
+  seen: join(STATE_DIR, "seen.tsv"),
+  prospects: join(STATE_DIR, "prospects.tsv"),
+  failures: join(STATE_DIR, "failures.tsv"),
+  log: join(STATE_DIR, "log.md"),
+};
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`state — manage head-hunter agent state
+
+Usage:
+  node scripts/state.mjs <command> [args]
+
+Cursor commands (source rotation):
+  cursor get <source>                         Get current cursor for source
+  cursor set <source> <timestamp> <position>  Update cursor position
+  cursor list                                 List all cursors
+
+Seen commands (deduplication):
+  seen check <source> <id>                    Check if ID was already seen (exit 0=seen, 1=new)
+  seen add <source> <id> [<date>]             Mark ID as seen (date defaults to today)
+  seen batch <source> <id1> <id2> ...         Mark multiple IDs as seen
+
+Prospect commands:
+  prospect add <name> <source> <strength> <level>  Add a new prospect
+  prospect list [--limit N]                         List recent prospects
+  prospect count                                    Count total prospects
+
+Failure commands:
+  failure get <source>                        Get failure count for source
+  failure increment <source>                  Increment failure count
+  failure reset <source>                      Reset failure count to 0
+
+Log commands:
+  log <message>                               Append raw text to log.md
+  log-wake <source> <summary>                 Append a formatted wake cycle entry
+
+Summary:
+  summary                                     Print state overview
+
+State dir: ~/.cache/fit/outpost/head-hunter/`);
+  process.exit(0);
+}
+
+// --- Ensure state directory exists ---
+
+mkdirSync(STATE_DIR, { recursive: true });
+
+// --- File helpers ---
+
+function readTsv(file) {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((l) => l.trim());
+}
+
+function writeTsv(file, lines) {
+  writeFileSync(file, lines.join("\n") + (lines.length ? "\n" : ""));
+}
+
+function appendTsv(file, line) {
+  appendFileSync(file, line + "\n");
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// --- Cursor operations ---
+
+function cursorGet(source) {
+  const lines = readTsv(PATHS.cursor);
+  const line = lines.find((l) => l.startsWith(source + "\t"));
+  if (!line) {
+    console.log(`No cursor for source: ${source}`);
+    return null;
+  }
+  const [, timestamp, position] = line.split("\t");
+  console.log(`${source}\t${timestamp}\t${position}`);
+  return { source, timestamp, position };
+}
+
+function cursorSet(source, timestamp, position) {
+  const lines = readTsv(PATHS.cursor);
+  const newLine = `${source}\t${timestamp}\t${position}`;
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    lines[idx] = newLine;
+  } else {
+    lines.push(newLine);
+  }
+  writeTsv(PATHS.cursor, lines);
+  console.log(`Cursor updated: ${newLine}`);
+}
+
+function cursorList() {
+  const lines = readTsv(PATHS.cursor);
+  if (lines.length === 0) {
+    console.log("No cursors.");
+    return;
+  }
+  for (const line of lines) {
+    console.log(line);
+  }
+}
+
+// --- Seen operations ---
+
+function seenCheck(source, id) {
+  const lines = readTsv(PATHS.seen);
+  const found = lines.some((l) => {
+    const parts = l.split("\t");
+    return parts[0] === source && parts[1] === id;
+  });
+  if (found) {
+    console.log(`SEEN: ${source}\t${id}`);
+    process.exit(0);
+  } else {
+    console.log(`NEW: ${source}\t${id}`);
+    process.exit(1);
+  }
+}
+
+function seenAdd(source, id, date) {
+  appendTsv(PATHS.seen, `${source}\t${id}\t${date || today()}`);
+  console.log(`Marked seen: ${source}\t${id}\t${date || today()}`);
+}
+
+function seenBatch(source, ids) {
+  const d = today();
+  const lines = ids.map((id) => `${source}\t${id}\t${d}`);
+  appendFileSync(PATHS.seen, lines.join("\n") + "\n");
+  console.log(`Marked ${ids.length} IDs as seen for ${source}`);
+}
+
+// --- Prospect operations ---
+
+function prospectAdd(name, source, strength, level) {
+  const d = today();
+  appendTsv(PATHS.prospects, `${name}\t${source}\t${d}\t${strength}\t${level}`);
+  console.log(`Prospect added: ${name} (${strength}, ${level})`);
+}
+
+function prospectList(limit) {
+  const lines = readTsv(PATHS.prospects);
+  if (lines.length === 0) {
+    console.log("No prospects.");
+    return;
+  }
+  // Show most recent first
+  const display = lines.slice(-limit).reverse();
+  for (const line of display) {
+    console.log(line);
+  }
+  if (lines.length > limit) {
+    console.log(`\n... ${lines.length - limit} more (${lines.length} total)`);
+  }
+}
+
+function prospectCount() {
+  const lines = readTsv(PATHS.prospects);
+  console.log(lines.length);
+}
+
+// --- Failure operations ---
+
+function failureGet(source) {
+  const lines = readTsv(PATHS.failures);
+  const line = lines.find((l) => l.startsWith(source + "\t"));
+  if (!line) {
+    console.log(`0`);
+    return 0;
+  }
+  const count = parseInt(line.split("\t")[1], 10) || 0;
+  console.log(`${count}`);
+  return count;
+}
+
+function failureIncrement(source) {
+  const lines = readTsv(PATHS.failures);
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    const count = parseInt(lines[idx].split("\t")[1], 10) || 0;
+    lines[idx] = `${source}\t${count + 1}`;
+  } else {
+    lines.push(`${source}\t1`);
+  }
+  writeTsv(PATHS.failures, lines);
+  const newCount = parseInt(
+    lines.find((l) => l.startsWith(source + "\t")).split("\t")[1],
+    10,
+  );
+  console.log(`Failures for ${source}: ${newCount}`);
+  if (newCount >= 3) {
+    console.log(
+      `WARNING: ${source} has ${newCount} consecutive failures (suspended at ≥3)`,
+    );
+  }
+}
+
+function failureReset(source) {
+  const lines = readTsv(PATHS.failures);
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    lines[idx] = `${source}\t0`;
+    writeTsv(PATHS.failures, lines);
+  }
+  console.log(`Failures reset for ${source}`);
+}
+
+// --- Log operations ---
+
+function logAppend(message) {
+  appendFileSync(PATHS.log, message + "\n");
+  console.log("Log entry appended.");
+}
+
+function logWake(source, summary) {
+  const timestamp = new Date().toISOString().slice(0, 16).replace("T", " ");
+  const entry = `\n## ${today()} ${timestamp.slice(11)} — Wake (${source})\n\n${summary}\n\n---\n`;
+  appendFileSync(PATHS.log, entry);
+  console.log(`Wake cycle logged for ${source}`);
+}
+
+// --- Summary ---
+
+function summary() {
+  const cursors = readTsv(PATHS.cursor);
+  const seen = readTsv(PATHS.seen);
+  const prospects = readTsv(PATHS.prospects);
+  const failures = readTsv(PATHS.failures);
+
+  console.log("=== Head-Hunter State Summary ===\n");
+
+  console.log(`Sources: ${cursors.length}`);
+  for (const line of cursors) {
+    const [source, timestamp, position] = line.split("\t");
+    const failLine = failures.find((l) => l.startsWith(source + "\t"));
+    const failCount = failLine ? parseInt(failLine.split("\t")[1], 10) : 0;
+    const status = failCount >= 3 ? " [SUSPENDED]" : "";
+    console.log(`  ${source}: last=${timestamp}, pos=${position}${status}`);
+  }
+
+  console.log(`\nSeen: ${seen.length} entries`);
+  console.log(`Prospects: ${prospects.length} total`);
+
+  // Strength breakdown
+  const byStrength = {};
+  for (const line of prospects) {
+    const strength = line.split("\t")[3] || "unknown";
+    byStrength[strength] = (byStrength[strength] || 0) + 1;
+  }
+  for (const [k, v] of Object.entries(byStrength)) {
+    console.log(`  ${k}: ${v}`);
+  }
+
+  // Recent prospects (last 5)
+  if (prospects.length > 0) {
+    console.log("\nRecent prospects:");
+    for (const line of prospects.slice(-5)) {
+      const [name, source, date, strength, level] = line.split("\t");
+      console.log(
+        `  ${date} | ${name} | ${strength} | ${level} | via ${source}`,
+      );
+    }
+  }
+}
+
+// --- CLI Router ---
+
+const cliArgs = process.argv.slice(2);
+const cmd = cliArgs[0];
+const sub = cliArgs[1];
+
+switch (cmd) {
+  case "cursor":
+    if (sub === "get" && cliArgs[2]) cursorGet(cliArgs[2]);
+    else if (sub === "set" && cliArgs[2] && cliArgs[3] && cliArgs[4])
+      cursorSet(cliArgs[2], cliArgs[3], cliArgs[4]);
+    else if (sub === "list") cursorList();
+    else {
+      console.error(
+        "Usage: cursor get|set|list <source> [<timestamp> <position>]",
+      );
+      process.exit(1);
+    }
+    break;
+
+  case "seen":
+    if (sub === "check" && cliArgs[2] && cliArgs[3])
+      seenCheck(cliArgs[2], cliArgs[3]);
+    else if (sub === "add" && cliArgs[2] && cliArgs[3])
+      seenAdd(cliArgs[2], cliArgs[3], cliArgs[4]);
+    else if (sub === "batch" && cliArgs[2] && cliArgs.length > 3)
+      seenBatch(cliArgs[2], cliArgs.slice(3));
+    else {
+      console.error("Usage: seen check|add|batch <source> <id> [...]");
+      process.exit(1);
+    }
+    break;
+
+  case "prospect":
+    if (sub === "add" && cliArgs[2] && cliArgs[3] && cliArgs[4] && cliArgs[5])
+      prospectAdd(cliArgs[2], cliArgs[3], cliArgs[4], cliArgs[5]);
+    else if (sub === "list") {
+      const lIdx = cliArgs.indexOf("--limit");
+      const lim = lIdx !== -1 ? parseInt(cliArgs[lIdx + 1], 10) || 10 : 10;
+      prospectList(lim);
+    } else if (sub === "count") prospectCount();
+    else {
+      console.error(
+        "Usage: prospect add|list|count <name> <source> <strength> <level>",
+      );
+      process.exit(1);
+    }
+    break;
+
+  case "failure":
+    if (sub === "get" && cliArgs[2]) failureGet(cliArgs[2]);
+    else if (sub === "increment" && cliArgs[2]) failureIncrement(cliArgs[2]);
+    else if (sub === "reset" && cliArgs[2]) failureReset(cliArgs[2]);
+    else {
+      console.error("Usage: failure get|increment|reset <source>");
+      process.exit(1);
+    }
+    break;
+
+  case "log":
+    if (cliArgs.length >= 2) logAppend(cliArgs.slice(1).join(" "));
+    else {
+      console.error("Usage: log <message>");
+      process.exit(1);
+    }
+    break;
+
+  case "log-wake":
+    if (cliArgs[1] && cliArgs.length >= 3)
+      logWake(cliArgs[1], cliArgs.slice(2).join(" "));
+    else {
+      console.error("Usage: log-wake <source> <summary>");
+      process.exit(1);
+    }
+    break;
+
+  case "summary":
+    summary();
+    break;
+
+  default:
+    console.error(
+      "Unknown command. Run with --help for usage.\n" +
+        "Commands: cursor, seen, prospect, failure, log, log-wake, summary",
+    );
+    process.exit(1);
+}

package/templates/.claude/skills/req-screen/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: req-screen
+description: >
+  Screen candidate CVs against the agent-aligned engineering standard to decide
+  whether to invest interview time. Produces a structured screening assessment
+  with interview/pass recommendation and suggested interview focus areas.
+  Use when the user asks to evaluate a CV or when a new CV is detected.
+---
+
+# Screen CV
+
+Screen a candidate's CV against the agent-aligned engineering standard defined
+in `fit-pathway`. The single question this skill answers: **is this candidate
+worth interviewing?** Every assessment is grounded in the standard — no
+subjective impressions.
+
+This is **Stage 1** of a three-stage hiring pipeline:
+
+1. **Screen CV** (this skill) — CV arrives → interview or pass.
+2. `req-assess` — interview transcript arrives → updated evidence.
+3. `req-decide` — all stages complete → hire / don't hire.
+
+## Trigger
+
+- A new CV is added to `knowledge/Candidates/{Name}/`.
+- A CV appears in `~/Downloads/` and is associated with a candidate.
+- The user asks to screen, evaluate, or assess a CV.
+- The user asks "is this person worth interviewing?".
+
+## Prerequisites
+
+- `fit-pathway` CLI installed (`bunx fit-pathway` works).
+- A CV file (PDF or DOCX) on the filesystem.
+- Optionally a target role: `{discipline} {level} --track={track}`.
+
+## Inputs
+
+- CV file path (e.g. `knowledge/Candidates/{Name}/CV.pdf`).
+- Target role (optional).
+- Existing `knowledge/Candidates/{Name}/brief.md`, if any.
+- `knowledge/Roles/*.md` matching the candidate's `Req` (provides `Level`,
+  `Discipline`, `Hiring manager`, `Domain lead`).
+
+## Outputs
+
+- `knowledge/Candidates/{Name}/screening.md` — structured assessment.
+- Updated `knowledge/Candidates/{Name}/brief.md` — skills + summary enriched.
+
+<do_confirm_checklist goal="Verify the screening is grounded and
+decision-rule-compliant">
+
+- [ ] Every claim cites CV evidence or marks "Not evidenced".
+- [ ] Two-level scepticism applied; vague phrases didn't earn levels.
+- [ ] "Not evidenced" skills are counted as gaps in the recommendation.
+- [ ] Recommendation follows the decision rules and threshold rule — match % and
+      gap count verified before picking a tier.
+- [ ] "Interview with focus areas" used only for strong candidates with a named
+      concern — not as a soft "maybe".
+- [ ] Output file is exactly `screening.md`; any misnamed prior file deleted.
+- [ ] `brief.md` links the screening as `[CV Screening](./screening.md)` and
+      Skills/Summary updated via targeted edits.
+- [ ] Gender set only from explicit pronouns/titles.
+- [ ] Recommendation header carries the advisory-only banner.
+
+</do_confirm_checklist>
+
+## Procedure
+
+### 1. Read the CV
+
+Extract the fields listed in
+[references/rubric.md](references/rubric.md#what-to-extract-from-the-cv).
+
+### 2. Anchor the target role
+
+If `brief.md` carries a `Req`, look up the matching Role file:
+
+```bash
+ls knowledge/Roles/ | grep "{req_number}"
+cat "knowledge/Roles/{matching file}"
+```
+
+Use the Role's `Level` and `Discipline` as the target unless the user specified
+a different target. Capture `Hiring manager` and `Domain lead` for the screening
+header.
+
+If no target is available, estimate one using the level heuristics in
+[references/rubric.md](references/rubric.md#level-estimation-heuristics).
+
+### 3. Load the standard
+
+```bash
+bunx fit-pathway job {discipline} {level} --track={track}
+bunx fit-pathway job {discipline} {level} --track={track} --skills
+bunx fit-pathway track forward_deployed
+bunx fit-pathway track platform
+```
+
+### 4. Map CV → standard skills
+
+For each skill in the target job, assess the candidate's likely proficiency.
+Look up nuance with `bunx fit-pathway skill {skill_id}`. Use the proficiency
+mapping and the scepticism rule in
+[references/rubric.md](references/rubric.md#proficiency-mapping).
+
+### 5. Assess behaviours
+
+```bash
+bunx fit-pathway behaviour --list
+```
+
+Map CV evidence using the behaviour signals in
+[references/rubric.md](references/rubric.md#behaviour-signals).
+
+### 6. Classify gaps and strengths
+
+Optional progression context:
+
+```bash
+bunx fit-pathway progress {discipline} {level} --track={track}
+```
+
+Classify each skill per
+[references/rubric.md](references/rubric.md#skill-alignment-classification).
+Pick the recommendation using the decision rules and threshold rule in
+[references/rubric.md](references/rubric.md#recommendation-decision-rules).
+
+### 7. Write the screening
+
+Save to `knowledge/Candidates/{Name}/screening.md` using the template in
+[references/template.md](references/template.md). Include the **Suggested
+Interview Questions** when the recommendation is "Interview" or "Interview with
+focus areas":
+
+```bash
+bunx fit-pathway interview {discipline} {level} --track={track}
+```
+
+Pick 3–5 questions most relevant to the gaps; note which gap each targets.
+
+### 8. Enrich the brief
+
+If `brief.md` exists, apply targeted edits:
+
+- Add or update `## Skills` with agent-aligned standard skill IDs.
+- Update `## Summary` if the CV provides better context.
+- Set `**Gender:**` only when explicitly stated and not already set.
+- Append `- [CV Screening](./screening.md)` if missing.
+
+If no brief exists, tell the user to run `req-track` first to build the
+candidate profile from email threads.