# Persistence and Resume State

Use this whenever a bullet is locked, resume content changes, or a resume is
finalized.

## Contents

1. Store semantics
2. Approval loop
3. Resume states
4. Commands
5. Finalization contract

## 1. Store semantics

Keep two distinct stores:

- `resume_vault.json`: explicitly approved, reusable achievements and their
  wording history. Treat this as canonical.
- `resume_library_db.json`: generated search corpus from all resume Markdown,
  including drafts. Treat this as discovery material, not approval evidence.

Never infer approval from a bullet's presence in a tailored resume or the broad
library.

The approved vault may contain experience or Additional-section project
bullets. The `content-approved` state gate continues to require exact approval
for Professional Experience bullets; approved project wording is persisted for
reuse but does not change that gate.

## 2. Approval loop

After the user explicitly locks a bullet:

1. Choose a stable achievement ID describing the underlying accomplishment,
   not the target company.
2. Record the approved text, employer, role, section, source resume, evidence
   note, metrics, and target-recognizable signal.
3. Upsert the achievement into `resume_vault.json`.
4. If replacing an approved wording, retain the previous wording in history
   and identify the superseded achievement or version.
5. Rebuild the broad index so the approved status is visible during retrieval.

Do not persist speculative alternatives, unverified facts, or generated
candidates.

## 3. Resume states

Track each source resume in `resume_workflow_state.json`:

```text
draft -> content-approved -> rendered-final
```

- `draft`: content is changing or at least one current bullet is not approved.
- `content-approved`: every current experience bullet exactly matches an
  approved vault wording; the source hash is recorded.
- `rendered-final`: DOCX/PDF and completion-log entry exist, QA has passed, and
  their hashes correspond to the approved source hash.

Any content edit invalidates `content-approved` and `rendered-final`.
Formatting-only renderer changes require new export hashes but do not require
reapproving unchanged bullet text.

## 4. Commands

Initialize the stores:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . init
```

Approve or update a locked bullet:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . approve \
  --id <stable-achievement-id> \
  --text "<approved bullet>" \
  --company "<employer>" \
  --role "<role>" \
  --section "Professional Experience" \
  --source "resumes/<path>.md" \
  --evidence "<short provenance note>" \
  --metric "<verified metric>" \
  --target-signal "<recognized capability or outcome>"
```

Mark a changed resume draft:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . mark-draft --resume "resumes/<path>.md"
```

Require every current experience bullet to be approved:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . content-approved --resume "resumes/<path>.md"
```

Inspect effective state and detect hash drift:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . status --resume "resumes/<path>.md"
```

Record a verified final:

```bash
.venv/bin/python skills/resume-system/scripts/resume_bank.py \
  --repo-root . finalize \
  --resume "resumes/<path>.md" \
  --docx "final resumes/<path>.docx" \
  --pdf "final resumes/<path>.pdf" \
  --completion-log "resumes/resume_completion_log.md"
```

## 5. Finalization contract

Before `finalize`:

1. Obtain explicit approval of the assembled Markdown.
2. Run `content-approved`.
3. Render and complete layout plus visual QA.
4. Update the completion log with the current facts and exports.
5. Run `finalize`; it verifies source-state integrity, export existence, and
   completion-log linkage, rebuilds the broad index, and records hashes.

Do not claim a resume is current-final when `status` reports drift.