@gafj/gafj 0.1.1

package/README.md

@@ -0,0 +1,99 @@
+# gafj
+
+GAF-J, the local campaign engine. One SQLite file on your PC, one ingest door for generated text, your own AI subscription. The architecture plan is at `../docs/career-engine-plan.md`; this folder is its implementation, built phase by phase.
+
+Status: phases 1 through 6 built and tested (82 public tests on the synthetic candidates, 7 private calibration tests on the operator's set, 24 tests under `../functions/test` including the phase 7 relay against fakes); phase 7 is written but not deployed, per the plan's separate go decision. Nothing below has been run on the operator's Windows PC yet except the phase 1 import. What exists:
+
+- `core/schema.sql` schema version 1 (plan section K); `core/migrations/002-profile.sql` adds `candidate.profile_json`
+- `core/scoring.js` verbatim from the Firebase function, with three text helpers added to its exports
+- `core/kb_import.js` legacy knowledge base to accomplishment rows: metric cleanup, outcome keys, verbs, duration and tenure claims, and the fixture rule for per-dimension review state (a dimension is confirmed only when a fixture line exercises it on that record)
+- `core/rules/*.md` the engine rules per document kind, candidate-neutral; `core/rules/index.js` versions them
+- `core/schemas/` the output schemas in a small schema language (string classes, claim-bearing fields, counts) with a JSON Schema export
+- `core/provenance.js` the claim check: every claim resolves to a cited record's confirmed dimensions or to this application's interviews, documents, and people
+- `core/validators/` the ledger as seven functions: `no_dashes`, `no_derived_tenure`, `highlight_body_match`, `metric_pairing`, `verb_ladder`, `style_config`, `no_confabulated_history`. Style rules warn or block per kind and house settings; integrity rules always block
+- `core/house_rules.js` style settings with opt-in allowances; `core/text.js` figure extraction and identifier stripping
+- `core/tracker_map.js` tracker rows to store shapes; `store/import_tracker.js` idempotent import with a rounds manifest for what the tracker holds as prose
+- `store/` open with the documented PRAGMA order, migrations under a lock, `withTx` with BUSY retry, append-only events with actors, IANA zone check, home folder with a sync-folder warning, snapshot, xlsx export, backup and restore, `context.js` (the slice and application universe a check runs against), `ingest.js` (the only door onto the document table; three attempts per run then stop), `review.js` (confirm, edit, drop a dimension; bumps the kb revision)
+- `core/generators/` the packet builders: `serialize.js` (one record, confirmed dimensions only, bounded), `slice.js` (precedence: pinned, then evidence-cited, then the top five by rankEvidence per category at weight 7 or above under a byte budget; a required set that overflows fails closed), `excerpt.js` (title, location, comp, evidence lines, a bounded body window; never the raw text), `packet.js` (one semantic packet per operation: rules, context, slice with ids, output JSON Schema; refuses without frozen scoring; prep-family packets carry this application's facts only)
+- `bridge/paste.js` the paste route: the packet as one text file with the run handle at the top
+- `store/packets.js` gathers the facts and opens the run (ai_run pending with packet hash and kb ids; ingest uses those ids as the slice); `store/scoring.js` the scoring contract (`proposeFromScan`, `freezeScoring`: verbatim evidence or rejected, evidence ranked with scoring.js unchanged, weighted mean, verdict, evidence hash, supersedes); `store/render.js` Markdown export of a passed document with the round and people from the store
+- `mcp/` the stdio MCP server (phase 3) on `@modelcontextprotocol/server` 2.0.0: read tools (`campaign_snapshot`, `list_interviews`, `list_postings`, `get_posting`, `get_scoring`, `list_accomplishments`, `get_person`, `get_<op>_packet`), the one door (`save_document`, isError when blocked, stop after three attempts), and the proposal tools through `store/proposals.js` (`store_posting` proposed and idempotent, `propose_categories`, `kb_gap_request`, `propose_accomplishment`, `export_tracker_xlsx`). Nothing on the wire confirms, schedules, sends, or applies
+- `http/` the local server (phase 4): 127.0.0.1 only, Host check, session cookie on every /api call (HttpOnly, SameSite=Strict, minted from a single-use launch nonce), Origin and JSON checks on mutations, 1 MB body cap, CSP with no remote scripts, SSE change feed on `/api/events` polled from the event log so MCP writes show up too. `store/transitions.js` holds the UI-only state machines (section M); `store/reads.js` the screen read models
+- `ui/` Preact and htm vendored as one file (`ui/vendor/preact.mjs`), no build step: dashboard (screen 1), application (3), interview hub (4), document view with print CSS, and the packet modal with the form-based repair editor (7)
+- Phase 5: screens 2 (postings: paste, store and scan locally, edit and freeze categories, log the application), 5 (knowledge base: gaps to answer, pending rows to confirm or dismiss, imported dimensions to review, search), 6 (settings: route, providers with write-only keys, house rules per kind, thresholds including the export folder, backup and restore test). `store/kb.js` holds the only confirm path after import; `store/settings.js` the config writes; `core/practice.js` and `store/practice.js` the drill workbook with planted anomalies, an AnswerKey tab, and a Solution tab, written with exceljs. The four paper moments run as scripts in `test/moments.test.js`
+- Phase 6: `bridge/byo_key.js` and `bridge/providers/{anthropic,openai_compatible,gemini}.js`, fetch only, https unless loopback, no redirects, keys scrubbed from every error; `POST /api/run/:op` runs a packet through the active provider and straight into the door
+- Phase 5b, onboarding (plan section U): `core/parsers.js` extracts text from docx (mammoth), pdf (unpdf text layer), md, and txt under caps (raw size, docx entries and inflated bytes, PDF pages, timeout); an empty result is stored and shown as a failure with the "OCR is not in v1" message. `core/schemas/extract.js` and `core/rules/extract.md` define the extraction packet; `store/onboarding.js` is propose_from_source: every factual atom must be a verbatim excerpt of its source at the span it cites or the draft is rejected whole, pending rows carry batch, source, attempt, and excerpts, dedup suggests groups (same employer, overlapping dates, a shared figure) and the candidate merges or keeps separate by a click, style is proposed from the sources and never imposed. MCP adds `list_sources`, `get_extract_packet`, `save_extraction`. The synthetic one-resume candidate goes from upload to a confirmed knowledge base and then through the resume door in `test/onboarding.test.js`
+- Roadmap close-out (plan sections O, Q, U, and phase 7 as code): `test/hostile.test.js` is the hostile corpus against both doors (malformed and truncated JSON, fences, arrays and primitives at the top, nulls and objects for arrays, unknown and smuggled fields, 2 MB bodies, 100k-deep nesting, `__proto__` and `constructor` keys, terminal escapes, spans outside or shifted against the source, homoglyphs, a fourth attempt), plus an `npm pack --dry-run` test that every shipped file is on the whitelist and none is a fixture, a database, or a log; `core/extract.js` caps content at 1 MB and nesting at 64 levels and rejects `__proto__` at any depth; the schema validator refuses control characters and looks fields up as own properties (a `constructor` key used to pass as known). `store/log.js` is the operational log at `HOME/logs/gafj.jsonl`, keys fixed to `ts, level, event, entity, entity_id, actor, ms, status`, values cut at 200 characters, rotated past 10 MB with three kept; `serve` writes one line per request (method, path shape, status, ms; launch nonces collapsed) and never a body. `store/kb.js listHoles` computes the questions the records themselves raise (a record with no confirmed figure; an ownership verb at the top tier with no scope figure) with a prefilled draft; the answer lands pending with `replaces`, and confirming it extends that record's confirmed dimensions instead of adding a twin (screen 5, "Holes"). Phase 7 as code, not deployed: `../functions/relay/` (ledger, Stripe signature and event-id idempotency, operation endpoints with every cloud dependency injected, `functions/test/relay.test.js` runs the stop gate against fakes) and the local half `bridge/credits.js` with the relay url and sign-in token in config.json (masked on read), `POST /api/run/:op` on the credits route, `GET /api/credits/balance`, and the Credits card on screen 6
+- Discovery, the shakedown after upload (plan U): `discover` is a candidate-level op (schema v3 rebuilds `ai_run` for it; `store/migrate.js` now runs the documented foreign-keys-off recipe with `foreign_key_check` before commit). `core/rules/discover.md` and `core/schemas/discover.js`: the AI reads the confirmed records, thinnest first with the engine's holes and every prior question in context, and returns questions only, each tied to a record id in the slice. `store/discover.js` is the door: a question about a record outside the packet is refused whole, duplicates drop, twelve open at most, three attempts then stop, and a new round is refused while questions are open. The candidate answers on screen 5 ("Discovery"); the answer is a pending row with `replaces`, so confirming it extends the record. `store/reply.js` picks the door by the run's operation for the UI, the CLI (`gafj packet discover`, `gafj ingest --run`), byo_key and credits runs; MCP adds `get_discover_packet`, `save_discovery`, `list_questions`.
+- Bullet register (screen 6): `house_rules.bullet_register` is `result_first` (default, RAS), `action_first`, or `posting`; it travels in the resume packet's HOUSE RULES and `core/rules/resume.md` says what each means. Same facts, same claims, same gate; only word order.
+- Backup folder (screen 6): `config.backup_dir`, meant for a synced folder (Drive, OneDrive, Dropbox); `store/backup_dir.js` writes dated consistent copies there (`gafj backup`, the Back up now button, and one a day at `serve` start), keeps the newest 14, never prunes a pre-restore copy, and refuses the data folder itself. The live store never goes to a synced folder.
+- Hosted tier (plan W, gates 2 and 4 as code): `http/hosted.js` runs the same routes, screens, and doors behind a Google sign-in with one store per user under `<root>/tenants/<uid>/`; the session names the uid, the uid names the folder, and no query spans tenants (`test/hosted.test.js` drives every parameterized route as user B with user A's ids and expects 404 and no leaked text). Provider keys, MCP config, and the restore test are 404 for hosted users; the model is reached through the relay with a service key and the uid (`x-gafj-service`, `x-gafj-uid`; the relay's second auth path), never a stored user token. `/account/export` streams a restorable backup, `/account/delete` removes the folder and every session. `http/identity.js` verifies Firebase ID tokens with node:crypto against Google's JWK set, no SDK. `ui/hosted/signin.html` is the one page with a loosened CSP (Firebase Auth from gstatic). `gafj serve-hosted` is configured by environment only; `deploy/hosted/` holds the Dockerfile and fly.toml; `functions/relay/deploy.js` builds the relay with Firebase Admin, Stripe, and the Anthropic SDK and `functions/index.js` exports it as `relay`. Nothing is deployed; `docs/operator-setup.md` is the list of what only the operator can do.
+- `bin/cli.js`: `migrate`, `import`, `snapshot`, `review`, `lint`, `list`, `score-freeze`, `packet`, `ingest`, `render`, `export`, `backup`, `restore`, `mcp`, `print-mcp-config`, `serve`, `url`, `rotate-token`, `install-startup`, `allow-host`, `init`, `onboard`; every other command names its phase and exits
+
+Onboarding another candidate, phase 5b:
+
+```
+gafj init --name "Priya Natarajan"          a fresh candidate and an open batch (GAFJ_HOME picks the folder)
+gafj onboard add resume.docx old-resume.pdf notes.md
+gafj onboard packet --source <id>           an extraction packet to paste into any chat
+gafj onboard ingest --run <run> --file reply.json
+gafj onboard dedup                          suggested duplicate groups; gafj onboard merge <group> [--keep <pending id>]
+gafj review                                 or the knowledge base screen: confirm, edit, drop, each beside its excerpt
+```
+
+The paste loop, phase 2:
+
+```
+gafj list postings                         ids and whether scoring is frozen
+gafj score-freeze --posting-id <id> --from-scan --propose-only   writes a categories file to edit
+gafj score-freeze --posting-id <id> --categories <file> [--scores <file>]
+gafj list interviews
+gafj packet prep --interview-id <id>       writes packets/packet-prep-<run>.md; paste it into any chat
+gafj ingest --run <run> --file reply.json  blocks name the field, the span, and the nearest records; three attempts then stop
+gafj render --document <id>                Markdown of a passed document under documents/
+```
+
+The UI, phase 4:
+
+```
+gafj serve                 starts the local server (serve.lock holds pid and port), prints a launch URL, opens the browser
+gafj url                   a fresh launch URL for the running server (each one works once)
+gafj install-startup       registers serve at login (schtasks on Windows, launchd on macOS, a systemd user unit elsewhere); --print shows the commands only
+```
+
+On your phone (same store, same screens, over your own private network):
+
+```
+1. Install Tailscale on the PC and the phone, same account (free personal plan).
+2. On the PC:   tailscale serve --bg http://127.0.0.1:7311     (your gafj port; prints a name like gafj-pc.tail1234.ts.net)
+3.              gafj allow-host gafj-pc.tail1234.ts.net        then restart gafj serve
+4.              gafj url --host gafj-pc.tail1234.ts.net --qr   scan the code with the phone, or type the link once
+5. On the phone: Chrome or Safari, share or menu, "Add to Home Screen" / "Install app".
+```
+
+Tailscale terminates HTTPS on the PC and forwards to the loopback server, so nothing is exposed to the internet and the phone is a real installed app with a Secure cookie. Only hosts on the allow list are answered; every other Host header is still refused. The PC must be on for the phone to work: the store never leaves it.
+
+Connecting Claude Desktop or Claude Code, phase 3:
+
+```
+gafj print-mcp-config      prints the Desktop snippet and the Claude Code command with absolute paths (never npx)
+```
+
+A tracker-imported scoring row is frozen with no categories; packets for it rank the slice against the posting text instead, and `score-freeze --from-scan` replaces it when you want categories.
+
+One deviation from the plan text: the highlight check (ledger rule 2) uses the shipped scoring function's semantics, a figure key match in the body or a different figure from the same record, rather than a phrase match. The phrase rule blocked every live resume; the key rule catches the missing-evidence case the rule exists for.
+
+Private calibration gate (needs the candidate's own files, never committed):
+
+```
+GAFJ_FIXTURES_PRIVATE=<folder> GAFJ_KB_DIR=<folder with accomplishments.json> npm run test:private
+```
+
+Run the tests:
+
+```
+cd gafj
+npm test
+```
+
+Node 24 or newer. Dependencies: `exceljs` (tracker import and export), `@modelcontextprotocol/server` and `zod` (the MCP server), `preact` and `htm` (vendored into `ui/vendor`; the browser never loads from node_modules), `mammoth` and `unpdf` (text extraction for onboarding). `@modelcontextprotocol/client` is a dev dependency for the stdio test. Never put candidate data in this folder; real fixtures live outside the repository (see `GAFJ_FIXTURES_PRIVATE` in the plan).