git:20261020.506ff63 to git:20261023.ce73717

- description: Personal career log repo — raw records of past work, projects and achievements, plus the user's target direction. Use to log a milestone (PR merged, phase shipped, hard bug solved, feedback received), consolidate a finished experience, check how well the user fits a job posting, tailor a resume and form answers to a posting or a target role, prepare for an interview, find skill gaps, write a cover letter / bio / application answer, rank employers (career fair, job list), import old resumes or web sources, or audit the log for gaps. When a milestone lands in any project, offer to log it.

- At the start of each session, `git -C <root> pull --ff-only --prune`: the user may work from more than one clone, and another machine may have pushed. Then look for unmerged data branches (*Commits* below), wherever they were started: `git -C <root> branch -a --list "data/*" "origin/data/*"` (the pull has just fetched the other machine's, and pruned the ones it deleted), and `git -C <root> worktree list`. For each branch found, `gh pr list --head <branch>` shows whether it has a pull request; one without is work still in progress on another machine. If there is one, tell the user before starting: its changes are not on the default branch yet, so this session would not see them, and editing the same files here would conflict with it. Merge it, close it or continue on it, as the user decides.

- It stores **raw material**: facts about what happened, recorded richly enough that nobody has to remember them again. Every resume bullet, cover letter, bio or interview answer is an **output** derived from the raw material, never the other way round.

- ## Settings

- Settings are the lines in `direction.md` that decide what a mode does for this user: the target roles (§ Target roles, ranked), the lines under Constraints (work authorisation and any other hard constraint), the sorting order under Employer preferences, each target's line under What to emphasise, the Writing preferences for applications (the record language among them) and *Bulk changes as pull requests*. Each is in one of four states:

- - **unanswered:** its line is a `GAP:` with no *skipped* note, or there is no line;

- - **skipped:** the user was asked at the point of need and declined: `GAP: <question> (skipped, user, YYYY-MM-DD)`;

- - **default:** the Template's value, marked `(default; change it here)` (the record language, *Bulk changes as pull requests*), or writing.md for a writing preference never stated; it counts as answered;

- - **answered:** a value with its source, `(user, YYYY-MM-DD)`. "None" is an answer, and an answer is final: a mode does not ask a follow-up about something the answer leaves out, it flags it instead. A value from an imported document is not an answer yet: it is written as `GAP: confirm: <value> (<source>)` and is unanswered, with that value as the proposed answer. The target roles are judged by their section, not one line: answered when § Target roles, ranked holds at least one role the user confirmed, `(user, YYYY-MM-DD)` (a ranked list, under one source or one per role, or the bold line filled in), unanswered while it holds only the `GAP:` line with no *skipped* note, or nothing. A role found in an import (a resume's objective, an old chat) is a value from an imported document: it goes in as `GAP: confirm: <role> (<source>)` under the bold line, which stays, so the round or the mode that needs it asks the user to confirm. Recording a confirmed role removes the bold `GAP:` line.

- **At the point of need.** A mode that needs an unanswered setting asks once, records the answer (*Direction upkeep*) or, when the user declines, marks the line skipped, and goes on. A skipped setting is not asked again unless the user brings it up; the mode goes on as its own file says for a setting with no answer. No mode waits on a setting. `fit`, `write`, `rank` and `interview` say where they ask.

- **A new Log.** A Log made from the Template ships its settings unanswered: `direction.md › First-session setup` says *Settings round: not offered yet*, and the settings with no safe default (the target roles, work authorisation, the sorting order) are bold-labelled `GAP:` lines. While that line says *not offered yet*, offer the round once the session's start check is done, unless the request is `log` (keep that one quick and offer next session):

- - in one numbered round, every bold-labelled setting line under Target roles, Constraints and Employer preferences that is unanswered (not other gaps the Log holds), then the record language and *Bulk changes as pull requests*, each with a recommended answer and the option to skip;

- - record each answer in its line. A `GAP:` line skipped here stays unanswered, so the mode that first needs it asks once more; a default skipped here keeps its default;

- - set the line to *Settings round: offered YYYY-MM-DD*, commit and push, then go on with the request. If the push is rejected (another clone pushed first, perhaps its own round), run `git -C <root> fetch` and `git -C <root> merge origin/<default>`; where both sides changed a setting line, ask the user which answer stands, keep the earlier round date, resolve any other conflict as *Commits* says (keep both sides' facts with their sources), then commit the merge and push.

- | `direction.md` | Target roles ranked, employer preferences, constraints, emphasis by target, languages, the user's own writing preferences, repo workflow switches |

- | `entries/<YYYY-MM>-<slug>.md` | One file per experience. Template: `entries/_template.md` |

- | `outputs/applications/<YYYY-MM-DD>-<company>-<role>/` | One folder per application: posting, resume (`.tex` and the `.pdf` as sent), answers, provenance, interview packs. Frozen once sent; later interview packs and notes are added beside it |

- | `outputs/resumes/<target>.md` / `.tex` / `.pdf` | One file set per general or target resume version (`general`, `ai-infra`, `backend-infra`, ...), no date: the approved text with its provenance table, the source and the built PDF. Overwritten in place; git history holds the old versions. A version sent outside an application is recorded in `applications.md` as a commit hash ([Sent versions](#sent-versions)) |

- | `tools/` | `setup.sh` / `setup.ps1` (TinyTeX, TeX packages, poppler), `resume.py` (build and layout-check a resume), `tex-packages.txt`, `export-template.sh` (build the shareable Template), `chat_export.py` (screen and extract AI chat-history exports, see [modes/import-chats.md](modes/import-chats.md)), `tests/` (its tests and anonymised fixtures). How to use the resume tools: [latex.md](latex.md) |

- - **Provenance.** Every fact in an entry carries its source: a link (commit, PR, issue, doc), a file path, a source key (below), or `(user, YYYY-MM-DD)` when the user stated it. Every number also records how it was measured and its caveat (CI overlap, single run, estimate). An output (a resume, report or application answer) is never the source of a fact: cite what its provenance table cites. Only a wording under `## Past phrasings` cites the output or old resume it appeared in, and so does a side of a conflict that quotes an output's wording.

- - **Current truth only.** Entries, `profile.md`, `direction.md` and `stories.md` hold what is true now, because every mode reads them. When a fact changes, rewrite it in place; never append a newer version below the old one, or leave notes such as "superseded" or "moved to". This is about the record, not the work: an earlier design, a dead end or a replaced component is a fact about the project and stays where a decision or lesson needs it. History lives elsewhere: git keeps old versions, each output's provenance table says which entries it used, `sources/import-log.md` records imports, and `applications.md` records events. New facts the user gives in any mode go, the same session, into the section of the entry (or file) they belong to, with their source; `log` is the exception and adds them to `## Pending`. A `Settled:` line under `## Conflicts` is a current rule (which wording is wrong), not history. Any mode in which the user or the evidence resolves a conflict collapses it to its `Settled:` line, as [consolidate](modes/consolidate.md) step 2 says. Evidence settles what is true, including that both sides are (the both-right form). When true wordings compete and an output must pick one, or the pick depends on context, the choice is the user's, and the conflict stays open until they make it. Approving an output is not a ruling on a conflict, unless the user, when approving, ruled on that conflict by name.

- - **Drafts are leads.** Only the user's own words count as `(user, …)`: what they say in this session, or a prompt they wrote in an imported chat. Text an AI wrote (a chat answer, a polished application answer, a generated README) is a lead to verify, never a fact; its numbers and claims get checked against the entries before use, and unsupported ones go under `## Conflicts` in a form `entries/_template.md` gives. A conclusion you draw from the user's words is tagged `(interpretation, not stated)`. So is a rule taken from a playbook or report the agent wrote: cite the user's statement behind it, or ask them.

- - **Direction upkeep.** Whenever the user states a preference, a target, a constraint or a reaction to a company, record it in `direction.md` with its source, the same session. A new answer replaces the line it changes; a withdrawn item stays only as a one-line rule when it could otherwise come back (`<skill>: withdrawn, do not use`). A lesson from one event is kept as the rule it teaches for the next one, not as the event's story, in the section it changes; a career-fair lesson (which employers to visit first, queues, entry times) goes under Employer preferences, which `rank` reads before the next fair. A short sourced account of how the user came to their current direction, kept as the story they tell ("why this path"), is current truth, not a replaced answer. Fairs, recruiter contacts and applications without a folder in `outputs/applications/` go into `applications.md`.

- - **Visibility.** `visibility: nda` entries stay detailed in the log; outputs generalise them (no internal system names, no unpublished numbers).

- - **Languages.** The user may talk in any language. Log files are written in the record language set in `direction.md › Writing preferences for applications` (English when unset). Each output is written in the language the user asks for, or the one `direction.md` gives for that kind of output. The user's own words are quoted in their original language, with a translation in brackets when the record language differs.

- - **Commits.** Commit with the repo-local git identity (`git -C <root> config --local user.email`). If no local identity is set, stop and ask the user: the global one may belong to someone else. Never force-push the default branch: other clones pull it with `--ff-only`. Where a commit goes depends on its size:

- - **Bulk data changes** are any import, and any other mode run that rewrites more than one entry (a consolidate over several entries, the fixes after an audit). Updating the `## Past phrasings` of the entries a `write` used does not count.

- - **Small data changes** are everything else: a pending line, interview notes, an application row, a gap or two answered, a direction update. Commit them to the default branch and push, after every mode that writes.

- - **With the data-branch flow on** (*opt-in*, below), a bulk change works on a branch in its own worktree, started from the default branch whatever `<root>` has checked out. `<default>` is the default branch's name, from `git -C <root> symbolic-ref --short refs/remotes/origin/HEAD` (minus `origin/`; if it is unset, `git -C <root> remote set-head origin --auto` first). Run `git -C <root> fetch`, then `git -C <root> worktree add --no-track .worktrees/<topic> -b data/<topic> origin/<default>`; `--no-track` keeps the branch from tracking the default branch, so a push can never land there. Worktrees go in `.worktrees/`, or where the agent's own tooling puts them (Claude Code: `.claude/worktrees/`); both are ignored, and the start check's `git worktree list` finds them anywhere. Call the worktree's path `<wt>` and the root resolved above `<main>`; for the rest of the session the worktree is `<root>`, and every write of the session goes there, small ones included, so nothing is split between the branch and the default branch. Ignored files are not in the worktree: raw exports stay in `<main>/sources/inbox/` and are read from there. Commit and push the branch after every mode that writes (the first time `git -C <root> push -u origin data/<topic>`, then `git -C <root> push`), so the work is backed up and the other machine can see it.

- - **When the session's work is done,** open a pull request (`gh pr create`, no issue needed) whose body lists what changed per file and what was left out, and ask the user to review the diff. If GitHub reports a conflict (the default branch moved meanwhile), run `git -C <root> fetch` and `git -C <root> merge origin/<default>` in the worktree, resolve each conflict by keeping both sides' facts with their sources (ask the user where two facts contradict), push, and show the user the resolution.

- - **Merge only on the user's yes:** `gh pr merge <n> --merge`, without `--delete-branch` (the branch is still checked out in the worktree). Then, in `<main>`: `git pull --ff-only`, `git worktree remove <wt>`, `git branch -d data/<topic>`, `git push origin --delete data/<topic>`. If `worktree remove` refuses because files are left in the worktree, show the user `git -C <wt> status` and use `--force` only on their yes. Before the user switches machines, the pull request is merged or closed.

- - **The data-branch flow is opt-in.** It applies only when `direction.md › Repo workflow` sets *Bulk changes as pull requests* to on, and `gh` and a GitHub remote are available. Otherwise, the default, bulk data changes go to the default branch like small ones, with no worktree: wherever a mode says to start the `data/` worktree, skip it, and read `<main>` and `<wt>` in any mode as `<root>`. The user turns it on or off by saying so (*Direction upkeep*).

- - **Names appended to `.export-deny`** during a bulk session are committed in `<main>` to the default branch and pushed at once, not on the data branch, so a Template export from the default branch never scans with an old list.

- Every resume an employer received must be recoverable exactly as sent.

-

- - **Through an application:** its folder in `outputs/applications/` keeps the `.tex` and `.pdf`, and is not edited after sending.

- - **Outside one** (a career fair, a recruiter email): record the commit, not a copy. Take the last commit that touched the target's files before the version was sent (`git -C <root> log -1 --format=%H -- outputs/resumes/<target>.*`), with its work committed first. In the `applications.md` row write `[<target> @ <short hash>](<permalink>)`, where the permalink is `https://github.com/<owner>/<repo>/blob/<full hash>/outputs/resumes/<target>.pdf`, with `<owner>/<repo>` read from `git -C <root> remote get-url origin` (both `https://github.com/<owner>/<repo>.git` and `git@github.com:<owner>/<repo>.git`). If origin is not on GitHub, or there is no remote, write the bare short hash.

- - **Through the user's own application tool** (`direction.md › Tools the user already uses`): no row, since the tool already records each application. The user keeps the target's file name (`<target>.pdf`) when uploading, so the tool shows which version went. To recover it, take the application's date and time from the tool, then the last commit that touched the target before it: `git -C <root> log -1 --format=%H --before=<date and time> -- outputs/resumes/<target>.*`. If the tool shows only a date and the target changed that day, ask the user which version went.

- - The hash is the source of truth; the link is a convenience. To read the sent version, take the file path from the permalink (the part after `/blob/<hash>/`), which stays right when a target is later renamed or moved, and swap `.pdf` for `.tex`: `git -C <root> show <hash>:<path>.tex`. A row with a bare hash and no link: `git -C <root> show <hash>:outputs/resumes/<target>.tex`, and if that path is missing at the hash, `git -C <root> show --stat <hash>` lists what the commit touched.

- Drafts are never committed: they are built under `.build/` ([latex.md](latex.md#the-loop)) and copied into `outputs/` only when the user approves them.

- The log may be cloned on macOS, Windows or Linux. Commands in this skill are written for macOS and Linux. On Windows, run them in PowerShell (the agent's shell tool, or a PowerShell window); Git Bash also works. In both, write `py -3` for `python3`: the `python3` alias that the Python install manager adds cannot see `%APPDATA%\TinyTeX`, so `tools/resume.py` would fall back to another TeX or report none. Write paths with forward slashes; Python and git accept them on both. Build output goes to the ignored `.build/`, so nothing machine-specific gets committed. When the current machine lacks a tool, the skill link or the git identity, run the missing step of [SETUP.md](../../SETUP.md) and its check, after telling the user what it will install.

- Keys for this log's own imports (a chat export, a profile page) are defined in `sources/keys.md`. Add a row there whenever a new source folder or a new chat extract appears (`sources/resumes/` needs none: its generic key is above).

- | **write** | The user needs an output: a resume tailored to a job posting ("apply to <URL>", "make a resume for <URL>") or a target role, form answers, cover letter, bio, pitch | [modes/write.md](modes/write.md) |

- | **rank** | The user has a list of employers (career fair, job board) to sort | [modes/rank.md](modes/rank.md) |