@forwardimpact/outpost 3.12.0 → 3.13.0

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

@@ -1,17 +1,20 @@
 ---
 name: req-assess
 description: >
-  Analyze interview transcripts against the agent-aligned engineering standard,
-  updating skill and behaviour ratings with observed evidence. Produces
-  per-interview assessments and panel briefs for subsequent interview stages.
+  Analyze interview transcripts against the agent-aligned engineering standard.
+  Update skill and behaviour ratings with observed evidence. Produces
+  per-interview assessments and panel briefs for later interview stages.
   Use when transcript files appear in a candidate's folder.
 ---
 
 # Assess Interview
 
+Write tier: `2-Confidential`
+Frontmatter: candidate (stamps `status`, `updated`)
+
 Analyze a candidate's interview transcripts. Update their skill and behaviour
 profile with **observed** (not claimed) evidence. Interview evidence is
-higher-fidelity than CV evidence — it confirms or contradicts the screening
+higher-fidelity than CV evidence. It confirms or contradicts the screening
 assessment.
 
 This is **Stage 2** of the three-stage hiring pipeline:
@@ -22,43 +25,46 @@ This is **Stage 2** of the three-stage hiring pipeline:
 
 ## Trigger
 
-- A new `transcript-*.md` file appears in `Knowledge/Candidates/{Name}/`.
+- A new `transcript-*.md` file appears in `2-Confidential/Candidates/{Name}/`.
 - The user asks to analyze an interview or debrief.
 - The user asks to prepare a panel brief.
-- The concierge agent processes a Anarlog interview recording.
+- The concierge agent processes an Anarlog interview recording.
 
 ## Prerequisites
 
 - `fit-pathway` CLI installed.
-- At least one transcript in `Knowledge/Candidates/{Name}/`.
-- `screening.md` should exist; if missing, run `req-screen` first (proceed
-  regardless).
+- At least one transcript in `2-Confidential/Candidates/{Name}/`.
+- `screening.md` should exist. If it is missing, run `req-screen` first.
+  Proceed regardless.
 
 ## Inputs
 
-- `Knowledge/Candidates/{Name}/transcript-{date}.md`.
-- `Knowledge/Candidates/{Name}/screening.md`.
-- `Knowledge/Candidates/{Name}/brief.md` — target role.
+- `2-Confidential/Candidates/{Name}/transcript-{date}.md`.
+- `2-Confidential/Candidates/{Name}/screening.md`.
+- `2-Confidential/Candidates/{Name}/brief.md` — target role.
 
 ## Outputs
 
-- `Knowledge/Candidates/{Name}/interview-{date}.md`.
-- `Knowledge/Candidates/{Name}/panel.md` — only when more interviews are
+- `2-Confidential/Candidates/{Name}/interview-{date}.md`.
+- `2-Confidential/Candidates/{Name}/panel.md` — only when more interviews are
   planned.
-- Updated `Knowledge/Candidates/{Name}/brief.md`.
+- Updated `2-Confidential/Candidates/{Name}/brief.md` — frontmatter `status`
+  and `updated` stamped.
 
 <do_confirm_checklist goal="Verify the assessment is grounded in transcript
 evidence">
 
-- [ ] Every skill re-rating cites a specific moment from the transcript.
-- [ ] Behaviour assessments reference observed actions, not claimed traits.
-- [ ] Level assessment uses standard progression criteria, not gut feel.
-- [ ] Interviewer observations are attributed by name.
-- [ ] Confirmed strengths and new concerns are distinguished.
-- [ ] Panel brief (if created) is written for non-technical readers and ties
-      suggested questions to remaining gaps.
-- [ ] Brief's Pipeline section, links, and Status are updated.
-- [ ] Gender field is **not** updated from interview observations.
+- [ ] Cite a specific moment from the transcript for every skill re-rating.
+- [ ] Base behaviour assessments on observed actions. Ignore claimed traits.
+- [ ] Assess the level with standard progression criteria. Ignore gut feel.
+- [ ] Attribute interviewer observations by name.
+- [ ] Distinguish confirmed strengths from new concerns.
+- [ ] Assessment prose about the candidate stays in the candidate's own
+      folder. Wider notes record only that the interview happened.
+- [ ] Write the panel brief (if created) for non-technical readers. Tie the
+      suggested questions to the remaining gaps.
+- [ ] Update the brief's Pipeline section, links, and Status.
+- [ ] **Never** update the Gender field from interview observations.
 
 </do_confirm_checklist>
 
@@ -79,8 +85,8 @@ bunx fit-pathway skill {skill_id}
 bunx fit-pathway behaviour --list
 ```
 
-If screening recommended a different level than originally targeted (e.g. J100 →
-J090), load **both** for comparison.
+If screening recommended a level different from the original target (e.g. J100
+→ J090), load **both** for comparison.
 
 ### 3. Re-rate skills
 
@@ -90,8 +96,8 @@ moment, quote, or observation per change.
 
 ### 4. Re-rate behaviours
 
-Behaviours are better assessed in interviews than CVs — they describe how
-someone acts, not what they've done. Use the
+Interviews assess behaviours better than CVs. Behaviours describe how someone
+acts. They do not describe what someone did. Use the
 [behaviour signals](references/rubric.md#behaviour-signals) and the
 [behaviour maturity scale](references/rubric.md#behaviour-maturity-scale).
 
@@ -105,33 +111,35 @@ Apply the [level signals](references/rubric.md#level-signals).
 
 ### 6. Write the interview assessment
 
-Save to `Knowledge/Candidates/{Name}/interview-{date}.md` using
+Save to `2-Confidential/Candidates/{Name}/interview-{date}.md` with
 [references/interview-template.md](references/interview-template.md). Include
-only skills with new evidence — don't repeat the full matrix.
+only skills with new evidence. Do not repeat the full matrix.
 
 ### 7. Generate the panel brief (if applicable)
 
-When more interview stages are planned (panel, technical, etc.), pull question
+When you plan more interview stages (panel, technical, etc.), pull question
 candidates:
 
 ```bash
 bunx fit-pathway interview {discipline} {level} --track={track}
 ```
 
-Save `Knowledge/Candidates/{Name}/panel.md` using
-[references/panel-template.md](references/panel-template.md). Audience:
-next-stage interviewers, often non-engineers — explain without jargon and tie
-suggested questions to remaining gaps.
+Save `2-Confidential/Candidates/{Name}/panel.md` with
+[references/panel-template.md](references/panel-template.md). The audience is
+next-stage interviewers, often non-engineers. Explain without jargon. Tie the
+suggested questions to the remaining gaps.
 
 ### 8. Update the candidate brief
 
-Apply targeted Edit operations to `Knowledge/Candidates/{Name}/brief.md`:
+Apply targeted Edit operations to `2-Confidential/Candidates/{Name}/brief.md`:
 
 - Append a Pipeline entry with date, type, and outcome.
 - Add `## Interview Notes` if missing, with key observations.
 - Append `- [Interview Assessment](./interview-{date}.md)`.
 - Append `- [Panel Brief](./panel.md)` when one was created.
 - Update `Status` to reflect the current pipeline stage.
+- Stamp the frontmatter: set `updated` to the interview date and `status` to
+  the closest registry value (agents select from `registry.yaml`).
 
 Never rewrite the file. Never update the Gender field from interview
 observations.

package/templates/.claude/skills/req-assess/references/interview-template.md

@@ -1,8 +1,13 @@
 # Interview Assessment Template
 
 Reference template for `req-assess` Step 6. Save to
-`Knowledge/Candidates/{Name}/interview-{date}.md`. Include only skills the
-interview produced new evidence for — don't repeat the full matrix.
+`2-Confidential/Candidates/{Name}/interview-{date}.md`. Include only skills the
+interview produced new evidence for. Do not repeat the full matrix.
+
+Interview-outcome prose about the candidate lives only in the candidate's own
+folder. A wider note (an interviewer's People note, a project note) records
+only that the interview happened. Interviewer names may appear here; write no
+assessment of the interviewers.
 
 ```markdown
 # Interview Assessment — {Full Name}

package/templates/.claude/skills/req-assess/references/panel-template.md

@@ -1,8 +1,13 @@
 # Panel Brief Template
 
 Reference template for `req-assess` Step 7. Save to
-`Knowledge/Candidates/{Name}/panel.md`. Audience: **next-stage interviewers,
-often non-engineers** — explain without jargon, focus on behaviours and scope.
+`2-Confidential/Candidates/{Name}/panel.md`. The audience is **next-stage
+interviewers, often non-engineers**. Explain without jargon. Focus on
+behaviours and scope.
+
+The brief goes to the panel as an export. The note keeps its tier. Assessment
+prose about the candidate stays in this folder; never copy it into panel
+members' People notes.
 
 ```markdown
 # Panel Brief — {Full Name}

package/templates/.claude/skills/req-assess/references/rubric.md

@@ -13,17 +13,17 @@ Reference data for `req-assess` Steps 1, 3, 4, and 5.
 | **Behaviour observations**    | How the candidate acted under pressure, with others       |
 | **Self-identified strengths** | What the candidate claims they're good at                 |
 | **Self-identified gaps**      | What the candidate acknowledges as growth areas           |
-| **Red flags**                 | Contradictions with CV, concerning patterns               |
+| **Red flags**                 | Contradictions with CV, patterns of concern               |
 | **Interviewer feedback**      | Direct quotes or observations from interviewers           |
 | **Level signals**             | Autonomy, scope, complexity demonstrated in responses     |
 | **Track signals**             | Business immersion vs. platform thinking in their answers |
 
 ## Skill re-rating
 
-**Interview evidence outranks CV evidence.** A candidate who claimed
-`practitioner` but demonstrated `foundational` should be re-rated. The reverse
-also applies. Every re-rating cites a specific moment, quote, or observation
-from the transcript — "seemed strong" is not evidence.
+**Interview evidence outranks CV evidence.** Re-rate a candidate who claimed
+`practitioner` but demonstrated `foundational`. The reverse also applies. Every
+re-rating cites a specific moment, quote, or observation from the transcript.
+The phrase "seemed strong" is not evidence.
 
 | Interview evidence                          | Rating adjustment                     |
 | ------------------------------------------- | ------------------------------------- |
@@ -36,13 +36,13 @@ from the transcript — "seemed strong" is not evidence.
 
 ## Behaviour signals
 
-| Behaviour                  | Interview evidence                                             |
-| -------------------------- | -------------------------------------------------------------- |
-| Own the Outcome            | Takes responsibility, doesn't deflect, drives to resolution    |
-| Think in Systems           | Considers second-order effects, trade-offs, system boundaries  |
-| Communicate with Precision | Clear explanations, appropriate detail, listens actively       |
-| Be Polymath Oriented       | Draws on diverse knowledge, makes unexpected connections       |
-| Don't Lose Your Curiosity  | Asks good questions, explores alternatives, admits not knowing |
+| Behaviour                  | Interview evidence                                                       |
+| -------------------------- | ------------------------------------------------------------------------ |
+| Own the Outcome            | Takes responsibility, doesn't deflect, drives to resolution              |
+| Think in Systems           | Considers second-order effects, trade-offs, system boundaries            |
+| Communicate with Precision | Clear explanations, appropriate detail, listens actively                 |
+| Be Polymath Oriented       | Draws on diverse knowledge, makes unexpected connections                 |
+| Don't Lose Your Curiosity  | Asks good questions, explores alternatives, admits what they do not know |
 
 ## Behaviour maturity scale
 
@@ -59,7 +59,7 @@ from the transcript — "seemed strong" is not evidence.
 | Interview signal                                          | Implication                    |
 | --------------------------------------------------------- | ------------------------------ |
 | Needed guidance to structure their approach               | Level may be lower than est.   |
-| Self-directed; sound trade-offs independently             | Level estimate confirmed       |
+| Self-directed, made sound trade-offs independently        | Level estimate confirmed       |
 | Mentored or coached others during the exercise            | Level may be higher than est.  |
 | Struggled with complexity appropriate to the target level | Downgrade                      |
 | Interviewer explicitly suggested a different level        | Strong signal — weight heavily |

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

@@ -0,0 +1,164 @@
+---
+name: req-bundle
+description: >
+  Split a Workday CV-bundle PDF into per-candidate CV.pdf files under
+  2-Confidential/Candidates/. Reads the PDF outline (one bookmark per candidate) to
+  find each candidate's page range, matches it to the requisition roster so
+  folder names agree with req-workday, and extracts each CV losslessly. Use
+  when the user provides a Workday CV bundle (a large combined resume PDF, often
+  split into `_N_of_M` parts) and asks to split, unbundle, or extract individual
+  CVs — run this before req-workday imports the roster.
+---
+
+# Workday CV Bundle Split
+
+Write tier: `2-Confidential`
+Frontmatter: none (writes CV assets into candidate folders)
+
+Split a Workday CV-**bundle** PDF — one combined file holding every applicant's
+attachments — into per-candidate
+`2-Confidential/Candidates/{Clean Name}/CV.pdf`.
+
+This is the **PDF companion** to `req-workday`. `req-workday` imports the roster
+from the `.xlsx` (briefs + `CV.md` from embedded resume text); `req-bundle`
+attaches the real binary CV. Run `req-bundle` **first** so the folders it
+creates carry canonical names that `req-workday` then enriches — no duplicate
+folders.
+
+**How the split works.** Workday bundles have
+**no per-candidate separator page** and the name printed on a CV often differs
+from the roster name, so text-based splitting is unreliable. The one dependable
+delimiter is the **PDF outline**: exactly one flat bookmark per candidate, its
+destination being that candidate's first page. Candidate *i* = pages
+`[bookmark(i), bookmark(i+1) − 1]`; the last runs to EOF; the leading Table of
+Contents (before the first bookmark) is skipped. Multiple attachments for one
+candidate sit under one bookmark, so the range captures them all.
+`split-bundle.mjs` reads the outline with `pdfjs-dist` (`getOutline` +
+`getPageIndex`) and extracts each range losslessly with `pdf-lib` (`copyPages`).
+Full anatomy: [references/pdf-structure.md](references/pdf-structure.md).
+
+## Trigger
+
+- The user provides a Workday CV bundle PDF (a large combined resume export),
+  possibly split into `..._1_of_N.pdf … _N_of_N.pdf` parts.
+- The user asks to split, unbundle, or extract individual CVs from a Workday
+  export before importing candidates.
+
+## Prerequisites
+
+- PDF libraries for the split (`bun`/`node`), installed via the standard guard:
+  `bun pm ls pdfjs-dist 2>/dev/null || bun install pdfjs-dist` and
+  `bun pm ls pdf-lib 2>/dev/null || bun install pdf-lib`.
+- The `req-workday` parser dependencies, since the roster is produced by
+  `parse-workday.mjs` (see [../req-workday/SKILL.md](../req-workday/SKILL.md)):
+  `read-excel-file` and `fflate`.
+
+## Inputs
+
+- One or more bundle PDF paths (pass **all** parts of a multi-part export).
+- The requisition `.xlsx` (same req as the bundle) — parsed by
+  `req-workday`'s `parse-workday.mjs` into the roster JSON this script consumes,
+  so folder names are identical to what `req-workday` will create.
+
+## Outputs
+
+- `2-Confidential/Candidates/{Clean Name}/CV.pdf` — the candidate's extracted CV
+  (created only after the dry-run manifest is reviewed and confirmed).
+- A JSON manifest at `$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json`
+  — the reviewable mapping of every bookmark (page range, matched name, status).
+- Never overwrites an existing `CV.pdf`; a second CV for the same person is
+  staged as `CV-workday.pdf` / `CV-dup-N.pdf` and flagged for review.
+
+<do_confirm_checklist goal="Verify the split is complete, correctly named, and non-destructive">
+
+- [ ] Bundle page/bookmark counts sanity-checked; all parts of a multi-part
+      export passed together.
+- [ ] Roster parsed from the matching `.xlsx`; bookmark count reconciled against
+      roster count.
+- [ ] Dry-run manifest reviewed **before** any write; every `unmatched` bookmark
+      resolved to a candidate (or explicitly left staged).
+- [ ] Folder names equal the roster `cleanName` (annotation stripped) so they
+      match what `req-workday` produces.
+- [ ] Collisions (duplicate applications) and pre-existing `CV.pdf` files
+      handled without overwrite (`CV-dup-N.pdf` / `CV-workday.pdf`), each
+      flagged.
+- [ ] After commit, output CV count reconciles with matched bookmarks; a few
+      PDFs spot-opened to confirm the right, complete candidate.
+
+</do_confirm_checklist>
+
+## Procedure
+
+### 1. Set up
+
+Confirm the bundle PDF path(s) and the matching `.xlsx` (glob on the req number,
+not the timestamp — parts can carry different timestamps). Resolve `$HOME`
+(never pass a literal `~` to write tools). Ensure dependencies:
+
+```bash
+bun pm ls pdfjs-dist 2>/dev/null || bun install pdfjs-dist
+bun pm ls pdf-lib 2>/dev/null || bun install pdf-lib
+```
+
+### 2. Parse the roster
+
+Produce the canonical candidate list with `req-workday`'s parser (the single
+source of truth for `cleanName`s), saving the JSON for the split step:
+
+```bash
+node .claude/skills/req-workday/scripts/parse-workday.mjs "<path-to-requisition.xlsx>" --summary
+node .claude/skills/req-workday/scripts/parse-workday.mjs "<path-to-requisition.xlsx>" \
+  > "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json"
+```
+
+### 3. Dry-run the split
+
+Compute the mapping and manifest **without writing** any PDF. Pass every part of
+a multi-part bundle in one invocation:
+
+```bash
+node .claude/skills/req-bundle/scripts/split-bundle.mjs \
+  "<bundle_1_of_N.pdf>" "<bundle_2_of_N.pdf>" ... \
+  --roster "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json" \
+  --candidates-dir 2-Confidential/Candidates \
+  --manifest "$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json" \
+  --dry-run
+```
+
+The script prints a summary (bookmarks, matched, unmatched, collisions,
+existing-CV, roster-without-bookmark) and writes the full manifest. Matching
+rules and edge cases: [references/matching.md](references/matching.md).
+
+### 4. Reconcile and resolve
+
+Review the manifest. Confirm `bookmarks_total` reconciles with the roster count
+(expect a near-exact match). For each `unmatched` bookmark, use its `hints`
+(nearest roster names by shared tokens) to identify the candidate; note the
+correct `cleanName`. Investigate any `roster_unmatched_names` (applicants with
+no CV in the bundle — usually withdrawn/no-attachment). Do not proceed while
+unexpected mismatches remain unexplained.
+
+### 5. Confirm, then commit
+
+Summarize for the user: N CVs to write, M unmatched, K collisions/existing.
+**Get explicit confirmation** before writing. Re-run without `--dry-run` (same
+roster JSON) to create folders and write the CVs:
+
+```bash
+node .claude/skills/req-bundle/scripts/split-bundle.mjs \
+  "<bundle parts...>" \
+  --roster "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json" \
+  --candidates-dir 2-Confidential/Candidates \
+  --manifest "$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json"
+```
+
+For bookmarks that were `unmatched` but you resolved by hand in Step 4, move the
+staged file into the correct `2-Confidential/Candidates/{Clean Name}/CV.pdf`, or
+add the missing name variant and re-run — never hand-edit PDFs.
+
+### 6. Hand off and report
+
+Point `req-workday` at the same `.xlsx` to build briefs/`CV.md` and link the CV
+under each brief's `## CV` section. Flag every candidate that now has a `CV.pdf`
+for `req-screen`. Report `Split {matched}/{bookmarks_total} CVs for {Req ID}`,
+and list any unmatched bookmarks or roster applicants without a CV.

package/templates/.claude/skills/req-bundle/references/matching.md

@@ -0,0 +1,70 @@
+# Matching bookmarks to the roster, and edge cases
+
+How `split-bundle.mjs` maps each PDF bookmark to a canonical candidate folder,
+and how it handles duplicates, existing files, and misses. The goal: folder
+names identical to what `req-workday` produces, and **never** a destructive
+overwrite.
+
+## Why match at all
+
+The bookmark title is a clean name, but folder names must equal the roster
+`cleanName` — the applicant name from the `.xlsx` `Candidates` sheet with any
+trailing annotation (`(Internal)`, `(Prior Worker)`, …) stripped. That
+`cleanName` comes **directly from `req-workday`'s `parse-workday.mjs`** (the
+single source of truth this skill consumes as JSON), so the two skills agree by
+construction and never create duplicate folders. So: bookmark title → (match) →
+roster `cleanName` → folder.
+
+## Normalization (both sides)
+
+Before comparing, each name is folded with `normalize()`:
+
+1. Remove parentheticals — `(ΝΙΚΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ)`, `(Internal)`, `(Referral)`.
+2. Remove bare annotation tokens — internal / referral / prior worker /
+   external.
+3. Strip diacritics (NFKD) — `Geraño` → `gerano`.
+4. Lowercase, keep `[a-z0-9 ]`, collapse whitespace.
+
+## Match methods (conservative, deterministic)
+
+Applied in order; the method is recorded in the manifest:
+
+1. **`exact`** — normalized strings equal.
+2. **`token-set`** — same set of tokens regardless of order (handles
+   "First Last" ↔ "Last First" and dropped middle names).
+3. **`unmatched`** — no confident match. The script does **not** guess by
+   subset/Levenshtein (that risks merging two different "David …"s). Instead it
+   attaches `hints`: the nearest roster names by shared-token count, for a human
+   to resolve.
+
+## Edge cases & how the script handles them
+
+- **Duplicate applications (collisions).** The same person appears under two
+  bookmarks (e.g. across two parts of a multi-part bundle). Both resolve to one
+  folder. The first writes `CV.pdf`; the next becomes `CV-dup-2.pdf` (then
+  `-3`, …) with status `collision`. Review whether it's a true duplicate (keep
+  one) or a distinct newer packet (rename intentionally). Never silently
+  overwrite.
+- **Pre-existing `CV.pdf`.** A candidate who already arrived via email
+  (`req-track`) may already have `CV.pdf`. The script writes `CV-workday.pdf`
+  with status `existing-cv` and flags it, so the richer existing artifact is
+  preserved. Decide per candidate which to keep.
+- **Unmatched bookmark.** Staged in a folder named from the sanitized bookmark
+  title, status `unmatched`, with `hints`. Resolve by identifying the right
+  `cleanName` and moving the staged `CV.pdf` into that folder, or by adding the
+  missing name variant and re-running. A genuinely stray bookmark (someone not
+  on the roster) is worth flagging to the user.
+- **Roster applicant with no bookmark** (`roster_unmatched_names`). Applied but
+  no CV in the bundle — usually withdrawn or never attached a resume. Expected;
+  just report it. Not an error.
+- **No outline** (`no-outline` status for a file). The PDF has no bookmarks —
+  it is not a standard Workday bundle, or the outline was stripped. Do not
+  attempt a blind page-count split; stop and tell the user.
+
+## Reconciliation checklist
+
+- `bookmarks_total` ≈ roster count (small gaps explained by
+  `roster_unmatched_names`).
+- `unmatched_bookmarks` == 0 after Step 4 resolution (or each is explained).
+- `matched` + resolved unmatched == CVs you expect to write.
+- Known repeat applicants line up with the reported `collisions`.

package/templates/.claude/skills/req-bundle/references/pdf-structure.md

@@ -0,0 +1,74 @@
+# Workday CV Bundle — PDF anatomy
+
+What a Workday "Download resumes / attachments" bundle looks like, and why the
+PDF outline is the only reliable way to split it.
+
+## The shape of a bundle
+
+- A bundle is **one PDF that concatenates every applicant's attachments** — CV,
+  and often a cover letter and certificates too — back to back.
+- **Front matter:** page 1 (and sometimes 2–3) is a whole-bundle **Table of
+  Contents** titled with the req, e.g. `4951493 - Principal Software Engineer`,
+  listing `Candidate Name | Candidate ID | Attachments`. The TOC has **no page
+  numbers** in its extracted text, so it is not a usable split key — skip it.
+- **No per-candidate separator/cover page.** Each candidate's first attachment
+  begins directly on its own page. The TOC is the only inserted page.
+
+## The delimiter: the PDF outline (bookmarks)
+
+Every bundle carries a **flat, depth-0 PDF outline with exactly one bookmark per
+candidate**. The bookmark's destination is that candidate's **first page**, and
+its title is the **clean candidate name** (no `(Internal)` / `(Referral)`
+suffix). This is the split key:
+
+- Candidate *i* → pages `[bookmark(i).page, bookmark(i+1).page − 1]`.
+- Last candidate → `[bookmark(last).page, EOF]`.
+- A candidate's **multiple attachments are all under their single bookmark**, so
+  the page range captures the cover letter + CV + certs together. (This is fine
+  — a hiring manager wants the whole packet; `req-screen` reads the CV within.)
+- Bookmark counts match roster counts exactly (verified live: 75↔75 on a
+  single-part export; 366↔366 across the four parts of a large export).
+
+`split-bundle.mjs` reads this via `pdfjs-dist`: `doc.getOutline()` for the
+items, then `doc.getPageIndex(dest[0])` (resolving named destinations through
+`doc.getDestination()` first) to turn each bookmark into a 0-based page index,
+then sorts by page. Page ranges are extracted losslessly with `pdf-lib`
+(`copyPages`).
+
+## What NOT to rely on
+
+- **Separator-page detection** — there are none.
+- **Name text at the top of a page** — a CV's printed name is the candidate's
+  own styling and often differs from the roster name (bookmark "Vivian Chen" →
+  CV reads "Wei-Ling (Vivian) Chen, PhD"). Match the **bookmark title**, not
+  page text.
+- **Page-text extraction** — unnecessary and unreliable for boundary detection:
+  the outline gives exact boundaries and the `.xlsx` already carries the resume
+  text.
+
+## Multi-part bundles (`_1_of_N` … `_N_of_N`)
+
+When a req has many applicants, Workday emits several PDFs. Key facts:
+
+- **Each part is self-contained:** its own TOC, its own ~100-candidate subset in
+  its own internal order (parts are *not* sequential slices of one ordering).
+- **No candidate spans a part boundary** — every part's first bookmark is a
+  fresh candidate after its TOC, and its last candidate is fully contained.
+- Therefore **process each part independently** and union the results; pass all
+  parts to `split-bundle.mjs` in one call.
+- A person may legitimately appear in two parts (a genuine duplicate
+  application). That surfaces as a **collision** in the manifest (same folder
+  targeted twice) — handled per [matching.md](matching.md), not stitched.
+
+## Observed reference numbers (live exports)
+
+| Bundle                                   | Pages | Bookmarks |
+| ---------------------------------------- | ----- | --------- |
+| Principal SWE req (single file)           | 215   | 75        |
+| Sr. Director req `_1_of_4`                | 321   | 100       |
+| Sr. Director req `_2_of_4`                | 314   | 100       |
+| Sr. Director req `_3_of_4`                | 278   | 100       |
+| Sr. Director req `_4_of_4`                | 213   | 66        |
+
+Note: one part's filename carried a slightly different timestamp than its
+siblings — glob on the req number, not the timestamp.