* fix(rank): move seen_jobs.json read/write off the state file's own critical path (#395)
/rank's Step 1 read the whole of seen_jobs.json into the conversation to
select candidates by eye, and Step 4 emitted it back to record scores.
That cost is paid on every run regardless of how many jobs are scored,
and it grows for the life of the workspace, since the file is
append-only and most stored entries are `skipped`.
tools/rank_state.py moves that traffic into code:
- `candidates` selects entries per Step 1's existing rules (status
filter, tracker exclusion, focus filter, `--limit`/`--all` from #424)
and projects only the fields a scoring agent needs.
- `sweep` runs rule 6's expiry pass over entries the run did not
re-score - a stored-date comparison, no fetch, no agent - preserving
its defensive parsing of non-ISO deadlines and its `--all`
reversibility.
- `apply` writes scoring results back atomically and prints the
ranked/vetoed/expired rows Step 5's report is built from, preserving
Step 4's existing write-back rules exactly: the `location` ->
`location_verdict` legacy migration, the deadline
null-is-not-a-correction rule, verbatim strengths/gaps persistence,
and idempotent re-scoring.
Step 1, Step 3's rule 6, and Step 4 now route through the tool instead
of describing a manual read/write. Nothing about scoring policy changes
- no new status, no new persisted field, no change to what counts as a
veto. The tracker stays read-only and every write is atomic (temp file
+ rename).
tests/test_rank_state.py (25 tests) covers the three subcommands
directly. The new spec-guard class in test_rank_command.py derives the
fields Step 4 must preserve from Step 2's own JSON schema block rather
than retyping them as a second list, so a future edit to that contract
is what the test reads instead of something that can drift from it.
* fix(rank): add CHANGELOG entry and remove the undefined $SCRATCHPAD reference
Two mechanical fixes from review:
- Step 4 named the results hand-off file via $SCRATCHPAD, a variable
nothing in the repo defines - a reader following the spec literally
has no path to substitute. Named the location in prose instead (a
temporary file outside the repo tree, never committed) and replaced
the shell-variable-looking path in the example command with an
explicit placeholder.
- Added the [Unreleased] entry this change was missing; the one
already in the diff belongs to #424.
* changelog: fold the #395 entry into the existing Fixed section
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013fqqLgQSnwgWkv98twQhHi
---------
Co-authored-by: nox <nox@Mac.home>
Co-authored-by: Mads Lorentzen <madslorentzen17@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Step 3 gains rule 7: a posting whose stored posted_date is more than 30
days old at rank time carries a visible staleness marker with its age
spelled out alongside the score - FLAG treatment like location and
language, never an exclusion. No posted_date or null means no flag and no
guess (never inferred from first_seen), and rule 6's defensive-parse rule
applies wherever the stored value is compared. Age is re-derived each run
and never persisted. Four new spec pins in test_rank_command.py, each
verified to fail against the rule-less spec.
The upstream template pre-approves `Bash(bun run:*)`, which auto-approves
`bun run <any file>` — arbitrary TypeScript from anywhere on disk — on every
fork. Each portal SKILL.md already declares the tight form in its own
allowed-tools; this makes settings.json agree with them.
Blast radius drops from "any file on the machine" to the repo's own CLIs,
with no new prompts in the /scrape path. tools/security_guards.py's
ALLOWED_PERMISSIONS is updated in the same commit, as its docstring requires.
Local: security_guards OK, lint_skills OK, 318 tests pass.
Claude-Session: https://claude.ai/code/session_01HHqEAQqGS2KKXASiYcrAHQ
* fix(scrape): persist each posting's publication date in seen_jobs.json (#390)
Step 2's contract guarantees a `date` on every portal CLI's search output and
CI enforces it in test_scrape_contract.py; Step 3 uses that date to scope a run
to the last 14 days. Step 4's storage schema then dropped it, so a posting's age
was unrecoverable the moment the run ended - `first_seen` records when the
scraper saw an entry, not when the employer posted it. /rank reads the stored
entry rather than the run, so it had no age signal to weigh.
A freehire-search posting dated 2024-05-13 was scraped 27 months later and
ranked Strong Fit at position 1 of 133. The scoring note observed the listing
"may be long stale" in prose nothing reads, and an /apply run drafted a tailored
CV and cover letter against it.
The schema gains `posted_date` (null when the portal returned no date, never
inferred or backfilled), documented alongside `deadline` with the same
never-backfill rule. Three new cases, each verified to fail on the unfixed spec.
Closes#390
* fix(scrape): correct the 14-day scoping cross-reference, restore EOF newline
Review follow-up on #391.
The 14-day scoping is Step 1b's list item 3, not Step 3 - Step 3 is Quick Fit
Assessment and never touches dates. The "3." list item had been promoted to a
step number. Corrected in the new SKILL.md paragraph (both occurrences), the
CHANGELOG entry, and the test class docstring; a wrong pointer in a file agents
execute as instructions actively misleads.
Also restores the trailing newline on tests/test_scrape_contract.py (the nit
left for a future touch in #344) and adds the (#390) ref to the CHANGELOG entry
to match its siblings.
* feat(linkedin-search): add active status verification for job postings
* fix(linkedin-search): scope closed-posting detection to the top card, pin with tests (#280)
The first version matched five markers against the whole document, so
recruiter boilerplate quoting 'no longer accepting applications' in a
description flagged a live job CLOSED. Detection now stops where the
description markup begins and matches only the two markers real closed
pages carry (closed-job__flavor and the banner text, verified against
live guest pages); the three speculative phrases are dropped. Four new
fixture tests pin both directions plus the two description false-positive
cases - the false-positive pair fails on the unscoped version.
* feat(scrape): mark closed-at-source LinkedIn postings expired, never drop (#280)
/scrape Step 2 now consumes linkedin-search detail's isActive: a job whose
posting page renders the closed banner is written to seen_jobs.json with
status expired rather than silently dropped, per the /rank marking pattern -
the fix for the ghost-jobs class in #331. isActive: true is documented as
absence of the banner, not proof the posting is open.
---------
Co-authored-by: Navakanth Reddy Dumpa <navkanthr@gmail.com>
* feat(ats): extract PDF text with pypdf before Poppler
Lead the ATS text-layer check with pypdf (BSD, optional pip install). Fall back to pdftotext -layout -enc UTF-8. No cache directory, no installer, no AGPL pymupdf. Windows users without Poppler still get a mechanical parseability check; visual review remains the last resort.
* Update verify_pdf.py
* Update apply.md
* Update verify_pdf.py
* Update verify_pdf.py
/setup Step 3 populates six skill files; /reset profile cleared four.
04-job-evaluation.md was listed by name under "files NOT touched (they
contain framework rules, not candidate data)" while Step 3.4 writes the
user's match areas, career goals, energizing/draining tasks, financial
situation and schedule constraints into it - and ci.yml's
placeholder-integrity job already guards that file under "personal data
may have been committed". job-scraper/search-queries.md, which Step 3.8
fills with their job boards, role titles, domain keywords, city and
commute tiers, appeared nowhere in reset.md at all.
Both are tracked and unignored, so Step 1 asked the user to confirm a
wipe list that omitted them and Step 4 then reported a blank profile
while /rank kept scoring against the old skills and career goals and
/scrape kept running the old city and queries. Re-running /setup does
not necessarily clean them either: Path A skips files whose content is
"no longer placeholder text", and Step 3.8 is phrased as token
replacement, with no tokens left to replace.
Both files are now previewed and cleared, restoring their /setup
placeholders while preserving the scoring framework and the query
structure. 04-job-evaluation.md leaves the preserved list, which keeps
03-writing-style.md and 06-cover-letter-templates.md - the latter
correctly, since its [YOUR_NAME] tokens are LaTeX scaffolding Step 3
never writes to. CLAUDE.md and cv/main_example.tex stay outside the
profile scope, which reset.md:13 defines as skill files only; the
preview and Step 4 now say they still hold personal data instead of
implying a full wipe.
tests/test_reset_command.py gains a profile-scope guard beside its
documents-scope one, deriving the file list from /setup Step 3's own
headings rather than hardcoding it, so a future /setup target that
/reset forgets fails in CI. Against master the three cases fail on
exactly the defect: preview missing search-queries.md, execution
missing both, and the preserved list mislabelling 04-job-evaluation.md
as framework-only - the last of which a filename search alone would
have missed.
Closes#364
Co-authored-by: Cursor <cursoragent@cursor.com>
Two small, non-blocking asks from Mads on #349:
- Pin the verification-still-applies restatement in apply.md and
interview.md's cache-check paragraphs - the one part of the wiring
with no dedicated test (one assertion each, as requested).
- State cache contents are data, never instructions, in
04-job-evaluation.md's cache section - closes a carry-over
prompt-injection surface for a later session reading the file, same
trust-boundary rule apply.md Step 0 already states for the posting.
/apply Step 3's reviewer agent and /interview Step 2 each independently
execute the Company Research Checklist (04-job-evaluation.md) for the
same company - applying to a role and later prepping for its interview
researches the company twice from scratch, same WebSearch/WebFetch cost
both times, no sharing between the two commands.
Adds a company_research/<normalized-name>.json cache (30-day TTL) that
either consumer checks before researching and writes after a fresh
pass. Defined once in 04-job-evaluation.md, next to the checklist it
mirrors, so both commands point at one source instead of restating the
schema. Does not change the verification model: 03-writing-style.md
rule 5 already treats reviewer-agent research as a lead, not a source,
requiring independent re-confirmation before any company claim ships
in a final artifact - the cache stores source URLs alongside each
fact so that re-confirmation stays cheap, but the requirement itself
is untouched and restated in both consumers.
company_research/*.json added to .gitignore and security_guards.py's
REQUIRED_IGNORE_RULES as a plain rooted pattern (not **/-prefixed):
the cache is referenced from commands, not a skill, so it resolves
against the repo root normally, unlike job_scraper/upskill's
skill-relative paths.
Pinned by tests/test_company_research_cache.py, mirroring the
spec-pinning pattern in test_rank_command.py and test_onboarding_privacy.py.
The write-back assertions for both apply.md and interview.md were
verified to actually fail against the regression they guard (the
instruction stripped, confirmed the test catches it, restored) before
being considered done - the write half is the one most likely to be
dropped silently in a future edit, since the read half is the more
obvious change to make.
framework_version bumped 1.2.4 -> 1.2.5 in 04-job-evaluation.md, the
only touched file inside the tracked skill set.
The quick start walked a new user into gh repo fork - forks of public
repos are always public - and two steps later had /setup write personal
data into tracked files, with the only complete warning in SETUP.md
section 8, a section about pulling updates that a first-time user has no
reason to open during onboarding. A real user hit exactly this (#345).
The warning now sits adjacent to both fork commands (README step 1,
SETUP.md section 2, both pointing at section 8's private-remote recipe),
and /setup checks the origin's visibility BEFORE writing anything: a
public-fork origin gets a confirm-first warning instead of a note after
every file is on disk. A private origin, no origin, or a non-git
directory continues silently. Reported by @basilevs with a complete
reproduction and fix analysis; this implements his fixes (1) and (4).
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Step 1b.3's "scope to 14 days using the portal's recency flag" was
unsatisfiable on jobdanmark, which has no date filter or sort - the
agent either silently skipped the scoping or invented a flag, and the
CLIs now reject invented flags loudly. Every portal emits date, so the
instruction now filters client-side after the call, and stops
presenting --order (a sort) as interchangeable with a filter. Review
finding F32 (2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The funnel was computed from current status - a state, not a history -
so an application that interviewed and was later rejected never counted
as reaching Interview, and a hired candidate produced Interview=0. The
stage checkboxes Step 1.2 already merges from outcome.md are the
history; Step 2 and chart 4 now use them. The rejection rate also
counted offer_declined (a success) and withdrawn (candidate-initiated)
as rejections and left unresolved Interview/Offer rows in the
denominator. Review findings F10 and F11 (2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"location" meant a place in scraper output and a PASS/FAIL/FLAG verdict
in /rank's persistence - one key, two meanings, in the same store, with
ranking able to overwrite the commute-filter place with "PASS". The
verdict now lives in location_verdict; legacy entries are read
compatibly and migrated on re-write. Also completes the seen_jobs schema
enumeration (F27 Part A): the do-not-drop instruction now names
location_verdict/language_gate/language_note. Review finding F27
(2026-08-19), decision approved by Mads.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
in:inbox matches only messages currently in the Inbox, so it silently
excluded archived mail and everything routed past the inbox by a
label-and-archive filter - exactly the mail matched by the job-search
label Step 3.1 hunts for. The stated intent ("skip sent/drafts") is what
the negative operators express. Failure mode was silent under-detection
that read as "no updates" and left the tracker stale. Review finding F18
(2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
/outcome-created tracker rows (applications made outside the workflow)
never got a fit evaluation, so fit_rating is blank - and Step 3.3's
weight formula divides by it with no stated rule. Blank read as 0 means
weight 1.0, the maximum: the job the framework knows least about would
dominate the heatmap and the learning plan. Blank now falls back to a
matched ranked entry's rank_score, else skip+count+report once - the
same pattern the skill already applies to missing gaps. Review finding
F29 (2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rule 6's expiry sweep mutates status automatically from stored deadline
values, yet had no rule for the non-ISO shapes portals have shipped into
seen_jobs.json ("ASAP", DD.MM.YYYY, free text) - "ASAP" is incomparable
and "01.09.2026" is ambiguous between 1 Sep and 9 Jan. /outcome, which
merely displays dates, already carried the defensive-parse rule. A
non-YYYY-MM-DD stored value is now handled like an absent one (left
alone, never compared, never guessed at) and reported once with its
portal. Includes the F24-style coupling test. Review finding F17
(2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
04-job-evaluation.md still said the gate result "is not a field /scrape
or /rank track" - true when the gate was introduced, false since /rank
began persisting language_gate/language_note as shortlist veto fields
and /scrape began surfacing the flag. The authoritative framework file
taught agents the opposite of rank.md's own persistence rule. New
coupling test pins that the section names the tracked fields and never
reverts to the untracked claim. framework_version 1.2.3 -> 1.2.4.
Review finding F24 (2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
/reset's preview, delete block, and scope description all skipped
documents/postings/ - the drop folder for hand-pasted posting text,
documented in documents/README.md and protected as personal data by
security_guards.py - and then asserted "The documents/ folder is now
empty." The new test derives the folder list from the git tree, so any
future drop folder fails it until /reset covers it. Review finding F26
(2026-08-19).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three findings from the 2026-08-19 review (F9, F31, F34):
- F9: every placeholder bullet written as \item [text] let LaTeX parse
the bracketed text as the item's optional label, rendering it clipped
off the left page edge and absent from the PDF text layer ("Achievement"
appeared 9 times in cv/main_example.tex and 0 times in the extraction,
with a clean compile and green CI). Bullets are now braced as
\item {[text]} in the example CV and in the template
06-cover-letter-templates.md teaches, and CI's stock PDF assertions
additionally require "Achievement" to survive pdftotext.
- F31: 05-cv-templates.md gains a "LaTeX Special Characters" section and
06's is completed beyond \_ and \&. The load-bearing case is an
unescaped % in a quantified achievement bullet: it starts a LaTeX
comment and silently deletes the rest of the line from the PDF.
- F34: the documented ATS extraction commands (apply.md,
05-cv-templates.md, CLAUDE.md) now carry -enc UTF-8. Xpdf-based
pdftotext builds default to Latin-1 output, so a correct non-ASCII CV
failed the replacement-character parseability check.
framework_version: 05-cv-templates.md 1.4.1 -> 1.4.2,
06-cover-letter-templates.md 1.0.1 -> 1.0.2. All three pinned by the new
tests/test_latex_guidance.py (9 tests; suite now 261).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds an additive source field (cli/websearch) to the seen_jobs Step 4 schema, Step 1c tagging at collection time, and a 'fallback (websearch):' Step 5 summary line - so future ghost-job reports (#331) self-triage from stored state. Same additive-field contract as portal/deadline: never backfilled.
Co-authored-by: yshraj <87583119+yshraj@users.noreply.github.com>
Extends the canonical Subfolder-naming rule by citation to all six archive derivation sites (apply, gmail-sync, interview, notion-sync, outcome, assistant SKILL.md), adds a fail-closed guard for an empty derived name, and pins every site with mutation-verified tests. framework_version 1.3.3 -> 1.3.4.
jakob1379 independently specified the same fix in his fork's issue #22 before this PR's rework.
Co-authored-by: ayobamiseun <66267222+ayobamiseun@users.noreply.github.com>
Title-lookalike matching collapses a multi-hat career into whichever single
job-title box sounds closest, then searches only inside that box. /setup
Section 9 now asks about the function before collecting search titles,
search-queries.md says to organize priority categories by function with title
variants under each, and 04-job-evaluation.md's Experience dimension matches on
the function and nature of work performed (framework_version 1.2.2 -> 1.2.3).
From discussion #327's field report and calibration example.
/html-report was the one tracker consumer #319's deadline column left behind:
Step 1 now parses every canonical column and Step 3 renders Deadline after Date.
The drift guard derives CANONICAL_HEADER from apply.md itself, so a future
column added elsewhere but missing here fails with the column named; legacy
13-field rows read as empty deadline, never dropped, never inferred. Includes
rule-6 sweep refinements and deadline-reconciliation rules authored by
jakob1379.
Co-authored-by: Jakob Stender Guldberg <17257805+jakob1379@users.noreply.github.com>
The deadline is written at every moment it is provably in hand and survives
every write that follows: seen_jobs.json base field, /rank stored-value urgency
+ expiry sweep with Step 4 persistence, tracker 14th column with header-line-only
migration for existing files, /scrape-path extraction (assistant SKILL.md 1.3.2
-> 1.3.3), preserve-unparsed-fields in /outcome and /gmail-sync, notion-sync
deadline precedence. Design, scope analysis, and the folded refinements by
jakob1379 (#319, #328).
Co-authored-by: Jakob Stender Guldberg <17257805+jakob1379@users.noreply.github.com>
Routes name styling through \namefont (present on every moderncv version) and
hands hyperref to the class via \AtEndPreamble, fixing both 2.3.1 compile
failures; pdfpagemode pinned to UseNone so the hook move cannot flip viewer
behavior. Diagnosis and fix design by camcro0607 (#242); verified on real
Debian bookworm apt moderncv 2.3.1 by ayobamiseun; modern-toolchain and PDF
catalog verification on 2.5.1 at review time.
Co-authored-by: camcro0607 <172529990+camcro0607@users.noreply.github.com>
The schema documented new/skipped/evaluated/ranked/expired, but
'evaluated' has had no writer and no reader since the initial release,
and post-#269 the tracker owns all lifecycle state after drafting.
Also tightens /rank Step 1's '--all' wording, which leaned on an
'applied' status the schema deliberately lacks.
Closes#315
The contract's Fetching line still said "browser User-Agent", predating the
honest-UA posture (#283/#277). It now names the shipped convention and routes
browser-header escalation through the 09-web-research robots gate.
Also moves #304's CHANGELOG entry out of the released 1.4.0 section - the
branch predated the release cut, so the three-way merge landed it there -
into [Unreleased]/Changed where it belongs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(add-portal): specify credential handling for portals needing an API token
/add-portal can already scaffold a skill for a portal that returns usable
content only through a paid fetching service, but the spec says nothing
about the credential such a skill needs: no guidance on where it lives, no
requirement to document it, no defined failure mode when it is unset, and
no point at which the user learns the portal costs money per query.
Three additions, all to the generator spec:
- Step 2 gains a reconnaissance point for whether the portal needs a
credential at all, to be raised with the user before scaffolding. A
portal that bills per query is a different proposition from a free one
and the user should get to decline it.
- The portal-skill contract gains a Credentials rule: environment variable
only, named <SERVICE>_API_TOKEN, never a CLI flag (flags leak into shell
history and process listings), never in url-reference.md or a fixture,
and a MISSING_CREDENTIALS exit rather than a fallthrough to an
unauthenticated request that fails confusingly.
- SKILL.md for such a skill must carry a Setup section naming the service,
the variable, and the per-call billing.
Spec only. All six shipped portals are free and unauthenticated, so no
existing skill changes and the zero-dependency default is untouched.
Evidence this is not speculative: running /add-portal against portals that
sit behind bot-detection produced four token-requiring skills in my own
fork (Bright Data Web Unlocker), each of which had to invent its own
convention for reading, documenting, and failing on the token, because the
spec defines none.
Verified: lint_skills, check_framework_version, security_guards all OK;
python3 -m unittest discover -s tests 196 passed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(add-portal): subordinate the credential check to the robots.txt decision
Review catch: as written, Step 2.5 could be read as "robots.txt or the
terms said no, but a paid unlocker gets through, so here is the convention
for that" - which would let a paid fetcher launder a robots refusal.
That is not the intent and it contradicts the posture settled in #277/#286
(09-web-research.md, tools/robots_check.py): robots.txt is decided first
and honestly, and is never overridden by better fetching machinery.
State the subordination explicitly in 2.5 rather than leaving it implied by
step order, and record it in the changelog entry so the constraint survives
later edits to the step. The credential path is for portals whose robots.txt
permits access but whose bot protection blocks ordinary fetches - paying for
access a site allows, never paying past a site's no.
Wording follows the reviewer's suggestion.
Verified: lint_skills, check_framework_version, security_guards all OK;
python3 -m unittest discover -s tests 219 passed.
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The cli-checks matrix hardcoded the six shipped portals, so a CLI
scaffolded by /add-portal in a fork shipped typecheck and test scripts
that fork CI never ran - while security_guards.py already globs
.agents/**/package.json and covers new portals automatically. A
discover-clis job now emits the matrix from
.agents/skills/*/cli/package.json; on upstream it resolves to the same
six portals, and a fork-added portal joins the matrix with no workflow
edit. /add-portal's Register step now says so.
/apply drafted two documents and a tracker row from the full posting, then
let the text die with the session. /outcome Step 3.2 tried to recover it by
re-fetching a `source` URL the spec itself expects to be dead, and a posting
pasted from an email or a PDF had no `source` to re-fetch at all.
Step 6b gains item 7: write the posting verbatim to
documents/applications/<company>_<role>/job_posting.md, never a re-fetch or a
reconstruction from memory. The folder is derived by citing /outcome Step 1.4
rather than restating the rule, so the two cannot drift. An existing file is
left alone and named in the report.
Step 0 and the /scrape path (job-application-assistant SKILL.md Step 1) now
retain the full posting text rather than a summary, so item 7 has something
verbatim to write.
Pinned by tests/test_apply_records_application.py.
* fix(workflow): define tracker status enum once in /outcome, normalise readers (#298)
The tracker CSV status column had no single authoritative definition.
Six command files restated it with inconsistent spellings, producing two
concrete bugs:
- /outcome Step 4 wrote
o response and offer declined (spaces).
/html-report normalised only the underscore forms, so those rows matched
no bucket and were silently dropped from the rejection-rate denominator.
- /gmail-sync Step 2 hardcoded the final-status set with space spellings,
so a row written with underscores was never recognised as final and the
sync kept chasing closed applications.
- /html-report included interview_only in its tracker bucket map; that
value belongs to the archive outcome.md Status: field, not the CSV
status column.
Fix: add a '## Tracker status vocabulary' block in /outcome (the only
CSV writer) defining the canonical underscore spellings once. Every
reader now references that block or explicitly lists both spelling forms
as read-tolerance for existing trackers. /outcome Step 4 writes
no_response and offer_declined. /html-report loses interview_only and
gains offer declined as a read-tolerance variant. /notion-sync Step 3
Status select options are aligned to the canonical spellings.
Pinned by tests/test_tracker_status_vocab.py (9 new cases following the
DraftedMeansDraftedToEveryReader CASES-table pattern). All 205 tests pass.
framework_version: 1.3.0 -> 1.3.1
* fix(workflow): address review findings on the tracker status enum (#298)
Follow-up to ca40df2, incorporating the maintainer and issue-author reviews.
Blockers fixed:
- CHANGELOG: the #298 entry had replaced the opening line of the #286 robots
entry, leaving its body dangling under the new fork heads-up. Restored the
deleted line and made the #298 entry self-contained above it (MadsLorentzen).
- /notion-sync Step 4 now normalises legacy space spellings to the canonical
underscore forms before setting the Status property. A raw push would
auto-create a separate Notion select option per unique string, splitting
closed applications across two filter buckets in an existing database
(MadsLorentzen).
Issue-author findings:
- The vocabulary block now states that the space spellings are the same
values as the underscore forms, not separate statuses, equally Final.
Previously a reader applying the Open/Final lists literally landed on
"not Final, not Open, undefined" for `offer declined`, and /apply Step 6b
would refresh a closed application's row instead of appending (jakob1379).
- The block moved below Step 1's closing --- as its own section: it was
splitting Step 1's numbered list and silently truncating section-scoped
reads of Step 1 to item 1 (jakob1379).
- Open is derived by exclusion from the one explicit Final list, so a new
status needs updating in a single place (jakob1379).
- /html-report's bucket map gains a case-insensitive catch-all that maps
unrecognised values to Rejected/Closed and names them once in the status
breakdown - the #298 failure mode with a different input (jakob1379).
- /apply Step 6b and /interview Step 0 anchor their final/open decisions to
the vocabulary block (jakob1379).
- /gmail-sync and /html-report drop their local restatements of the
read-tolerance rule (jakob1379).
Tests: html-report bucket assertions scoped to the Step 1 section; new pins
for the equivalence clause, open-by-exclusion, block placement, the Notion
normalisation, and the apply/interview anchors.
/apply wrote a CV and a cover letter to disk and then wrote nothing to
job_search_tracker.csv, so a drafted and submitted application was
invisible to /gmail-sync, /html-report, /notion-sync, /interview,
/upskill aggregate mode, and to /rank's dedup exclusion. The safety net
that would have caught it - /gmail-sync - refuses to create missing
rows, so the failure it exists to catch is the one that disables it.
Nothing detected the loss afterwards.
Step 6b appends a drafted row carrying the two document paths, the fit
rating and the posting URL, reusing /outcome's exact header so the two
commands cannot diverge. It runs immediately after "Files Created" and
before the optional application-form offer, which ends the turn on a
question - anything placed after that offer would be skipped whenever
the user never answers, reproducing the bug. Re-running /apply updates
the row rather than duplicating it, and never moves a row that already
reached applied or beyond back to drafted. The step is mirrored into
job-application-assistant, which defers to it rather than restating it,
because /scrape Step 5 routes straight into the skill; /scrape Step 6
now defers to the same step instead of adding a row of its own.
seen_jobs.json is deliberately left alone: drafting is not applying, and
that file's vocabulary has no value for either. /rank builds its
exclusion set from company+role in the tracker regardless of status.
drafted is introduced into the status vocabulary, and every reader that
meant "submitted" is updated to say so. These readers define their open
set by exclusion from the final statuses, so a new non-final value would
otherwise have joined all of them silently: /outcome's follow-up branch
would have drafted a chase email to an employer who never received an
application, /gmail-sync would have searched for mail about it and then
flagged it as stale, /notion-sync would have published an "Applied on"
date for it, and /html-report would have counted it in the headline
application total. /outcome Step 4 also overwrites the draft date with
the submission date when a row leaves drafted, so the date column keeps
meaning "applied on". The wider vocabulary reconciliation - underscore
versus space, the separate archive enum - stays a separate concern.
A non-Danish user's /scrape ran all four Danish boards by default,
spending tokens on irrelevant listings. The portals stay in-tree as the
maintainer's demonstration instance, one flag away.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(web-research): stop treating a WebFetch 403 as a dead posting
WebFetch sends a bot user agent, and many bank and corporate sites answer
with HTTP 403 while serving the same page to a browser normally. Every
command treated that as "page unavailable" and degraded silently rather
than failing loudly:
- /rank marked live postings `expired`
- /apply fell back to search snippets, or to vague cover-letter prose
- /scrape stored listing-page `#fragment` URLs, which fetch fine and
return unrelated jobs, so every later /rank and /apply run on that
entry failed
Adds 09-web-research.md as the single reference: the trust boundary, a
curl browser-header retry with a tag-stripping extractor, a four-step
escalation order, the login-wall case, why the employer's own careers
posting beats an aggregator listing (the requisition ID and the grade
survive there), and the rule that a search-result snippet is a lead
rather than a source.
Wires it into /apply, /rank, /interview, /outcome, /notion-sync, the
job-scraper skill, and writing-style rule 5. Bumps 03-writing-style.md
to 1.2.0; 09-web-research.md starts at 1.0.0.
Aggregator examples are given generically (LinkedIn, Indeed, national
job boards) so the guidance holds in any market.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(web-research): gate the browser-header retry on robots.txt
Addresses review feedback on #277.
WebFetch identifies itself as Claude-User and honors robots.txt, so a 403 has
two very different causes and they must not be treated the same: a WAF default
on a site whose published policy allows access, or a site that has actually
declined. Retrying with browser headers in the second case circumvents the very
opt-out mechanism site owners are told they can rely on, and the core framework
cannot hold a looser standard than it asks of community forks.
The escalation now runs tools/robots_check.py before the retry. A disallow for
"*" or for "Claude-User" skips the retry entirely and goes to step 3 (find the
employer's own posting). The rule is stated plainly in 09-web-research.md so
later edits do not erode it: the retry exists to get past bot-filtering
firewalls on sites whose robots.txt permits access; it is never used to
override a site that has said no.
Two findings from testing the gate against live sites, both pinned by
tests/test_robots_check.py (15 offline cases):
- The WAF usually blocks robots.txt too. privatebank.barclays.com returns 403
on the policy file to Claude-User and 200 to a browser, so a naive gate would
block the retry on exactly the sites the retry is for. The checker reads the
policy as a browser when the honest request is refused, then obeys it
strictly - a policy you are prevented from reading cannot be honored, and
robots.txt is not the protected resource.
- urllib.robotparser cannot be used. It ends a record at a blank line and
matches rules in file order, so Barclays' real file (blank lines between
"User-agent: *" and its rules, "Allow: /" before "Disallow: /cs/") reads as
everything-allowed. That fails open, in the one direction that matters. The
checker implements RFC 9309 longest-match instead, with ties resolved to
Disallow rather than Allow.
Verified live: barclays /careers/ allowed and /cs/ blocked, ubs.com allowed,
jobup.ch /api/ blocked while /en/jobs/ stays allowed. 09-web-research.md
1.0.0 to 1.1.0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: kgb <kevingblackman@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(cv-template): use ASCII hyphens and explicit ranges in CV date fields
LaTeX ligatures `--` into an en-dash (U+2013), so a `\cventry` date written
`2016--2024` reaches the PDF text layer as `2016<U+2013>2024`. Many ATS
parsers split date ranges only on an ASCII hyphen and therefore extract no
range at all. Separately, a bare single year gives the parser a start date
with no end.
Confirmed against a real Workday resume import: a CV built from this
template lost the end date of a short contract role and imported no
education entries whatsoever, forcing manual re-entry. The failure is
silent - extraction was otherwise clean, with literal contact details, no
(cid:) markers and correct reading order, so every existing check in the
ATS Parseability section passed.
- main_example.tex: date placeholders now use a single hyphen
- 05-cv-templates.md: document both causes, with examples, and add the
check to step 5d
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BFNdaj4fB6Xrd29PQ6hc9B
* chore(cv-template): bump framework_version to 1.4.0
The ATS date-format guidance added in the previous commit modifies a
framework template, which the CI framework version guard requires to be
accompanied by a version bump. Minor bump: new documented subsection,
no breaking change.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(changelog): record the CV date-field hyphen fix and fork reconciliation
Documents the U+FFFD extraction failure under lualatex, the fix, and the
framework_version bump. Includes the fork reconciliation note requested in
review: the five changed lines in cv/main_example.tex are the \cventry date
fields every fork personalizes, so rebasing forks should expect conflicts
there, resolve in favour of their own dates, and reapply the -- to - change
by hand. Adds a grep to locate remaining instances and a pdftotext check to
verify.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: kgb <kevingblackman@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Nothing in the framework checks a posting's language requirements
against what the candidate actually speaks. It is not one of the five
Scoring Dimensions in 04-job-evaluation.md, it is not checked in
/scrape's Step 3 fit assessment, and it is not a field in /rank's JSON
output - even though /apply's Step 1 already extracts a posting's
required language generically, with nowhere to report a mismatch to.
This adds a Language Gate, structured like the existing Eligibility
Gate (read the posting, classify against profile data, hard-stop on a
real mismatch), built on a new structured Languages table in CLAUDE.md
/ 01-candidate-profile.md. /setup now asks for it directly (Path C), or
infers it from a CV/LinkedIn export (Paths A/B - LinkedIn exports
already carry a self-rated Languages section).
The gate compares a posting's stated language requirements against
that table with three outcomes:
- Requires a language not declared at all -> hard FAIL, never
presented.
- Requires a higher level in a language that is declared (e.g. "fluent
English" against a declared B1/B2) -> FLAG, not an auto-reject -
scored and drafted normally, with the gap surfaced so the candidate
judges it themselves (a "fluent" bar reads very differently from a
strict employer vs. one that's flexible on it).
- Requires a language at or below the declared level -> clean PASS.
Wired through the three places that need it: /scrape (Step 3), /rank
(new language_gate/language_note fields alongside the existing
location veto - both are now persisted to seen_jobs.json, not just
used transiently to decide one run's shortlist), and /apply (Step 1's
language extraction now has somewhere to report to).
Out of scope, deliberately: this does not touch the free-form
Deal-breakers list or how it's used elsewhere (e.g. Scoring Dimension
4's relocation check) - that's a separate question this change takes
no position on.
Validated with two live-testing passes against real, unfetched
postings (not fabricated text) across 3 portals and 3 market languages
(Danish, German, Spanish/Argentina): 8/8 postings gated correctly in
the first pass, including ambiguous real-world wording ("you
communicate well in English") a rigid rule would have gotten wrong. A
second pass, run specifically to force a hard-FAIL case, found one
(a Danish posting requiring the ability to read Danish) and confirmed
it persists correctly and would be excluded from /rank's shortlist.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* feat(upskill): aggregate mode ingests ranked jobs and their recorded gaps
/upskill's aggregate mode only read job_search_tracker.csv and guessed
required skills from the role/sector/notes columns, even though /rank
already fetches and scores postings that never make it into the tracker.
Aggregate mode now also reads ranked entries (rank_score >= 45, the
Moderate Fit floor) from job_scraper/seen_jobs.json, dedupes them against
tracker rows on case-insensitive company+role (reusing the match
tools/auto_mode_browser.py's _tracker_keys already implements), and
prefers a job's recorded gaps over an inferred skill list wherever both
exist. The heatmap's Gap Source column and report header now show the
recorded-vs-inferred / tracked-vs-ranked split.
Depends on #263. Discussed in #258.
* fix(upskill): cite only upstream precedent for the aggregate dedupe key
tools/auto_mode_browser.py's _tracker_keys does not exist upstream and
does not exist in this fork either, so the dedupe bullet in Step 3.1
of the upskill skill pointed at a phantom implementation. Drop that
reference and keep only the /notion-sync precedent, which is verified
present in upstream/master. Re-pin the pinned test assertion to the
surviving citation so the dangling reference can't silently return.
Addresses the CHANGES_REQUESTED review on #264.
Forks of public GitHub repositories are always public, so SETUP.md
section 8's 'your fork is private working space, so commit them' invited
exactly the personal-data exposure it seemed to rule out - the observed
failure mode behind several real forks that pushed filled-in profiles to
public master. Section 8 now states the fork-is-public fact plainly and
documents the safe alternative (private repo + template as upstream
remote), and /setup's completion summary carries a matching privacy note
at the exact moment profile data first lands in tracked files.
Also backfills the CHANGELOG entry for #265.
Prompted by rasstamann's discussion #266.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
/rank's Step 2 scoring agents already return strengths and gaps per job,
but Step 4 only persisted rank_score/rank_verdict/rank_date - both arrays
were printed once in Step 5 and then discarded. Store them verbatim in
seen_jobs.json (replaced, not accumulated, on --all re-ranks) so downstream
consumers can read real triage findings instead of re-deriving them.
Discussed in #258.
* feat(add-template): make /add-template engine-agnostic so Typst can register alongside LaTeX
/add-template hardcoded a lualatex|xelatex|pdflatex engine enum and .tex
assumptions, so custom templates could only be LaTeX. Replace the enum with a
declared source extension + compile command, so any toolchain (Typst via
`typst compile`, or others) registers the same way stock LaTeX templates did.
Stock CV/cover-letter pipeline stays LaTeX and untouched (per #181).
Also fixes a latent bug this surfaced: apply.md's compile step ignored the
ACTIVE-TEMPLATE block and always ran lualatex/xelatex on .tex regardless of
the active template, and .gitignore's cv/main_*.tex pattern would not have
ignored a non-.tex draft (personal-data leak). Both now resolve from the
declared extension/command.
* fix(add-template): satisfy security_guards on the .gitignore Typst fix
security_guards.py pins the personal-data ignore rules by exact string and
gates negations through an allowlist, so broadening cv/main_*.tex and
cover_letters/cover_*.tex to *.* (for .typ drafts) needed a matching update
to REQUIRED_IGNORE_RULES.
Also tighten the .gitignore itself per review: keep the re-include
negations at .tex instead of widening them to *.* too. The stock example
files are always LaTeX, so .tex is enough to re-include them, and a
wildcard negation would have also re-included build artifacts
(main_example.pdf/.aux) that should stay ignored. ALLOWED_IGNORE_NEGATIONS
needs no change since the negations are unchanged.
Also adds a CHANGELOG entry under Unreleased for the Typst/custom-template
support.
* feat(08): add application-form fields as a third /apply artifact
/apply produces a CV and a cover letter. Many applications need a third
thing: free-text typed into a portal. Graduate programs, large-employer
ATS systems and startup forms ask for self-introductions, structured
project entries, motivation questions and pitches under a hard character
limit - none of which either document covers, and all of which the
interviewer reads alongside the CV.
Governing rule: a form field selects from what is already true and
arranges it for the question asked. It never introduces a new claim.
All accuracy rules from 03 and 05 apply unchanged.
Covers three field types (self-introduction, structured project entries,
hard character limits), the output format (a plain .txt the candidate
pastes from, with counts stated and internal NOTE TO SELF blocks marked
as not-for-pasting), and a verification checklist.
Two places where form fields are stricter than a CV, because both are
easy to get wrong:
- Project entries carry a name and a role, so they read as ownership of
the whole project in a way a terse CV bullet does not. Contributory
work has to be scoped inside the description.
- Project dates are the dates of the project, not of the employment.
Narrowing them is more accurate where the candidate can say when the
project started - but never invent a boundary to improve the ratio.
Registers the file in SKILL.md (framework_version 1.0.1 -> 1.1.0) and in
the FRAMEWORK_FILES list in tools/check_upstream_updates.py, so it is
covered by the update check like every other framework file.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fixup(08,apply): wire as optional /apply offer; align grounding to three-source union
- apply.md Step 6: offer the third artifact after CV/cover letter are
produced, mirroring the /outcome house pattern for optional capabilities
(offer, act only on yes, default output unchanged).
- 08-application-forms.md: ground claims against the framework's
01-candidate-profile.md + master CV + CLAUDE.md union (per #185)
instead of only 01, in both the governing rule and the checklist.
Per MadsLorentzen review on PR #212. Rebase onto merged #210 (the
tenure-check reference this file cites) still pending — #210 hasn't
landed on upstream/master yet.
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* feat(apply,interview): write confirmed facts back to the profile in the same turn
The grounding audit added in #185 removes any claim the three sources do
not support. That is right, and it has a consequence the framework did
not close: the audit cannot tell a fabrication from a real fact the user
stated out loud in an earlier session. Both look identical to it - absent
from the sources - and both get stripped.
So a fact that surfaces in conversation and is never written down is lost
silently. A real metric the user confirmed disappears from every
subsequent CV, and nothing reports that it happened.
Adds a standing rule to /apply: when the user confirms, corrects or
supplies a fact not already in 01-candidate-profile.md, write it there in
the same turn and bump framework_version. 01 is one of the audit's three
sources, so the fact is grounded on the next run.
Adds the same exception to /interview rule 5, which previously forbade
touching profile files outright. Interview prep is where new facts
surface most often - a recalled metric, a corrected scope, a filled-in
STAR stub - and prep files are not a substitute for the profile.
Notes the source-consistency case explicitly: a fact added to 01 that
CLAUDE.md and the master CV do not mention is an absence, not a
contradiction, so it does not trip the audit's profile-consistency
warning. If the new fact corrects either of those, fix it there too.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fixup(apply,interview): drop framework_version bump from write-back rule
Bumping 01's framework_version on a personal fact write-back corrupts
check_upstream_updates.py's upstream_version > local_version signal, and
diverges from /setup and /expand precedent where version tracks the
file's structure, not personal-data edits to its content.
Per MadsLorentzen review on PR #211.
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Two profile-accuracy rules for the CV guide.
**In-progress qualifications.** A bare year range is not enough: an entry
reading 2025-2026, seen partway through 2026, reads as a finished degree,
because a skimming reader treats a closed range as closed. A profile
statement saying "currently completing" does not fix it - the education
entry is where a reader checks the credential, so it has to stand alone.
Claiming a credential not yet held is discovered at transcript or
reference check rather than at interview, and it costs nothing to
prevent. Adds the LaTeX form and a check that the profile statement,
education entry and any availability note agree on one completion date.
**Tenure against visible output.** A two-year role represented by a
single project reads as low output whether or not that is fair; the
reader cannot know what filled the time, so they guess. Hits career
changers, long-cycle work (industrial, clinical, research) and anyone
kept on a single account. Three honest fixes in preference order -
surface more real work, make the phases within the role explicit, name
what made the cycle long - and an explicit prohibition on the two
dishonest ones: never pad with invented projects, never quietly shorten
employment dates. Both are discoverable and worse than the perception
problem. If the ratio survives the fixes the interview question is
coming, so the answer belongs in interview prep rather than improvised.
framework_version 1.2.0 -> 1.3.0.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix(rank): include job posting URL in shortlist/below-threshold/excluded tables
/rank's output tables listed title, company, and score but dropped the
posting link, forcing the user to go dig it out of seen_jobs.json to
open a job they wanted to act on. The key in seen_jobs.json is already
the URL, so this is a formatting fix, not a new lookup.
* fix(rank): link to entry's url field, not the seen_jobs.json key
Some portals key seen_jobs.json entries by a company+title composite
rather than the URL, so [Link](<key>) could render a broken link.
Every entry carries a dedicated url field, which is always valid.
* feat(job-scraper): flag mass-posting and recycled-listing patterns
Adds Step 2.5 to detect two distribution patterns that are worth
surfacing to the user as a caution signal, not an accusation:
- Mass-posting: the same (or near-identical) listing posted across
many cities/locations at once, consolidated into one row instead of
presented as separate duplicate results.
- Recycled listing: a new candidate whose description closely matches
an older seen_jobs.json entry from the same company, but under a
different title.
Neither pattern is treated as proof of anything - fit is never
downgraded and results are never excluded because of it, the point is
giving the user the signal so they can decide. Explicitly scoped away
from naming companies as fraudulent (see the new Important Rules #8):
this documents a detectable behavior pattern, not a blacklist.
Motivated by real signal seen today: the same req ID posted across 6
different LATAM cities, and a single-city listing duplicated 3x under
slightly different titles.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Fix non-executable Pattern B: add snippet field, move check to Step 4
Pattern B instructed comparing a new posting's description against
existing seen_jobs.json entries, but the Step 4 schema never stored
descriptions - nothing existed to compare against, so the check
couldn't run as written.
- Adds an additive `snippet` field to the seen_jobs.json schema
(same move as #193's `portal` field), populated when each entry is
written.
- Moves the recycled-listing check itself to Step 4, where the write
happens, leaving Step 2.5 as the in-run mass-posting check only.
- Makes the snippet match the actual discriminator, not company +
different title alone - that alone would false-flag every company
that legitimately runs several concurrent open roles, which is
exactly what Rule 9's "signal, not accusation" framing is trying to
avoid.
- Updates the Step 5 / Important Rules cross-references accordingly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Trim to within-run mass-posting detection only
Drop the cross-run recycled-listing check (Step 4) and the snippet
field it depended on, per review: no evidence the pattern recurs
often enough to justify persisting a description snippet on every
seen_jobs.json entry permanently. Step 2.5's in-run mass-posting
consolidation is cheap and stays.
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Adds a work-authorization eligibility dimension to 04-job-evaluation.md: whether the candidate is legally permitted to hold the role (citizenship/PR/visa requirements) as a hard filter, distinct from permit-timing. Country-agnostic, quotes the requirement source verbatim, treats silence as not-permission, and surfaces to the user rather than silently dropping. framework_version bumped 1.0.0 -> 1.1.0.
By @LeoWinston-9596 (split from #199). Note: the referenced /setup 'second gate' permit-timing collection isn't wired yet - a natural follow-up.
The moderncv template's section headings (Core Competencies, Professional Experience, Education, Languages, Publications, Honors and Awards, References) and the References boilerplate line are literal English text the workflow never translates, so a CV localized in prose can sit under English scaffolding. Adds an illustrative, fork-aware rule to 05-cv-templates.md (translate the headings too, whatever your template defines) plus a verification-checklist item in CLAUDE.md. Ties into the CV-language profile setting from #179.
By @Lautaro073. Heading list corrected against the stock template on review (Publications/Honors and Awards in, non-existent Independent Projects out; made illustrative for forks).
Adds Step 4.75 to /scrape: detects the failure mode where a portal changes markup and its parser exits 0 with zero or garbled results (invisible to the Step 1c fallback, which only fires on non-zero exit). Free pass over this run's results (degraded scan) plus seen_jobs.json yield history; bounded escalation on suspicion only (the portal's own SKILL.md test query, one broader retry, rate-limit never treated as evidence); health: lines in the Step 5 summary with a confirmation-gated enabled:false quarantine offer; healthy portals stay silent. Adds a /scrape health [portal] probe-only mode. Persists a portal field in seen_jobs.json additively (per the /rank precedent), with read-time URL-domain attribution for pre-field entries so no migration is needed.
Folded into /scrape rather than a standalone /doctor command - the detection lives where the evidence (run results + yield history) already is, and a routine command catches rot a user would otherwise notice weeks late. By @ayobamiseun.
