From 70134052d64ea092ee4b9e862ced5814dc5f3942 Mon Sep 17 00:00:00 2001 From: Cleanup Bot Date: Thu, 2 Jul 2026 19:42:43 +0300 Subject: [PATCH 1/3] docs: align repository documentation with MVP status Documentation-only audit. No code, evaluator, or rule changes; no new features; no Cloudflare work; no changes to PR #37 or #78. User-facing copy fixed: - README.md: replace misleading ASCII diagram (3 rewrites / Tailored CV) with the actual MVP outputs (Score, Issues, Strengths, ATS verdict, Archetype); clarify that /evaluate-cv ./my-resume.pdf works only because Claude Code reads PDFs natively (the local CLI/web UI parse .md and .txt only). - apps/web-ui layout.tsx: Next.js metadata description replaced with honest CV-evaluator copy (no longer 'Build a tailored resume...'). - apps/web-ui/README.md: list all three routes (/, /results, /feedback), note the static-export + privacy-first posture. - apps/cli/README.md: same PDF-clarification note as the root README. - package.json descriptions (root + core + cli): remove 'tailor / build' wording; describe the deterministic evaluator. - packages/intelligence/README.md: list the eight shipped roles (matches README and the actual implementation) and correct the default archetype (Backend Engineer, not Software Engineer). - packages/eval/README.md: drop the outdated LLM-provider claim; the MVP is fully deterministic. - .claude/skills/cv-evaluation/SKILL.md: 'local MVP', not 'hosted product'; default archetype corrected. - ROADMAP.md: status note added; Phase-1 / #74 / #75 / #76 / #85 / #87 marked as recently shipped; only #37 and #78 remain in progress. Historical docs marked with status notes (not rewritten, just flagged as pre-release context): ARCHITECTURE.md, PROPOSAL.md, PHASE-1.md, V1_SCOPE.md, MVP_DEMO_PLAN.md, PR_CLEANUP_HANDOFF.md, POST_MERGE_VALIDATION.md, REMAINING_PRS_PLAN.md, PR85_ROLLBACK_PLAN.md. Each now points readers to docs/MVP_RELEASE_STATUS.md. New: - docs/REPO_DOCS_AUDIT.md records the audit date, files reviewed, files changed, outdated claims found and fixed, historical docs left intentionally unchanged, remaining risks, and the validation results. Validates: pnpm test (12/12), pnpm lint (0 errors), pnpm build (6/6, fresh --force: emits /, /_not-found, /feedback, /results). --- .claude/skills/cv-evaluation/SKILL.md | 9 +- README.md | 12 +- ROADMAP.md | 47 +++-- apps/cli/README.md | 6 +- apps/web-ui/README.md | 23 ++- apps/web-ui/src/app/layout.tsx | 5 +- docs/ARCHITECTURE.md | 15 ++ docs/MVP_DEMO_PLAN.md | 12 ++ docs/PHASE-1.md | 19 +++ docs/POST_MERGE_VALIDATION.md | 6 + docs/PR85_ROLLBACK_PLAN.md | 10 ++ docs/PROPOSAL.md | 16 ++ docs/PR_CLEANUP_HANDOFF.md | 6 + docs/REMAINING_PRS_PLAN.md | 8 + docs/REPO_DOCS_AUDIT.md | 237 ++++++++++++++++++++++++++ docs/V1_SCOPE.md | 18 ++ package.json | 2 +- packages/cli/package.json | 2 +- packages/core/package.json | 2 +- packages/eval/README.md | 13 +- packages/intelligence/README.md | 14 +- 21 files changed, 432 insertions(+), 50 deletions(-) create mode 100644 docs/REPO_DOCS_AUDIT.md diff --git a/.claude/skills/cv-evaluation/SKILL.md b/.claude/skills/cv-evaluation/SKILL.md index b099c96..e80e92c 100644 --- a/.claude/skills/cv-evaluation/SKILL.md +++ b/.claude/skills/cv-evaluation/SKILL.md @@ -5,9 +5,10 @@ description: Evaluate a resume against the CV Builder rubric and return a scored # CV Evaluation -Run a resume through the same four-step evaluation the hosted product uses, -entirely locally. Everything you need lives in this repo — read the source, don't -guess. +Run a resume through the same four-step evaluation the local MVP uses, +entirely on your machine via your own Claude Code. There is no hosted +version of this product; everything you need lives in this repo — read +the source, don't guess. ## Inputs @@ -21,7 +22,7 @@ guess. text to produce a structured `Resume`. 2. **Detect archetype.** Match the resume against the role archetypes in `packages/intelligence/src/archetypes/`. Pick the best fit; default to - Software Engineer when there's no clear signal. See [archetypes](./archetypes.md). + Backend Engineer when there's no clear signal. See [archetypes](./archetypes.md). 3. **Score.** Apply `packages/prompts/prompts/score.md` with the detected archetype's weights and the rubric. See [rubric](./rubric.md) and [scoring](./scoring.md). Surface **at least 3** issues, each quoting the exact diff --git a/README.md b/README.md index 8236340..0faf555 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,10 @@ Good CV tools are expensive. Many job seekers — especially immigrants, career ``` ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │ Your CV │ ──▶ │ CV Builder │ ──▶ │ Score: 4.2/5 │ -└──────────┘ │ Engine │ │ 3 rewrites │ -┌──────────┐ │ │ │ 5 issues │ -│ JD │ ──▶ │ (6 scoring │ │ Keywords gap │ -│(optional)│ │ dimensions) │ │ Tailored CV │ +└──────────┘ │ Engine │ │ 5 issues │ +┌──────────┐ │ │ │ Strengths │ +│ JD │ ──▶ │ (6 scoring │ │ ATS verdict │ +│(optional)│ │ dimensions) │ │ Archetype │ └──────────┘ └──────────────┘ └──────────────┘ ``` @@ -71,7 +71,9 @@ pnpm --filter @cv-builder/cli start archetypes ### Power User — run it with Claude Code -Clone the repo, open [Claude Code](https://claude.com/claude-code) at the root, and run `/evaluate-cv ./your-resume.pdf`. The evaluation runs entirely on your machine with your own agent — no server, no account, nothing leaves your computer. No build needed. +Clone the repo, open [Claude Code](https://claude.com/claude-code) at the root, and run `/evaluate-cv ./your-resume.md`. The evaluation runs entirely on your machine with your own agent — no server, no account, nothing leaves your computer. No build needed. + +Claude Code can also read PDF and DOCX inputs natively, so `/evaluate-cv ./your-resume.pdf` works as long as the file is on your machine. See [apps/cli/README.md](apps/cli/README.md) for the full guide. diff --git a/ROADMAP.md b/ROADMAP.md index b872096..67e5527 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5,6 +5,19 @@ open for grabs**. For the **vision** (v0.1, v0.2, v0.3), see the [README Roadmap section](README.md#roadmap). This file is the **current state** — what maintainers and contributors are doing this week and next. +> **Status note — partially stale.** As of the post-PR #87 release, all v0.1 +> MVP sprint items have shipped on `main` (see +> [`docs/MVP_RELEASE_STATUS.md`](docs/MVP_RELEASE_STATUS.md) for the +> current MVP snapshot). The "🚧 In progress" list below was last +> refreshed before that release; the items labelled as open have either +> merged already or are no longer accurate. Treat this file as a planning +> draft for the **next** sprint, not a description of today's state. +> Before picking up an item, search the issue tracker — it may already +> be shipped. +> +> *Last refreshed: 2026-06-22. Next refresh: after the next planning +> call.* + ## How to read this - 🚧 **In progress** — assigned, being worked on, has an ETA. Don't pick up @@ -23,19 +36,18 @@ an acceptance bar reachable in a single sitting (1–4 hours). | Item | Owner | ETA | Notes | |---|---|---|---| -| **Merge Phase-1 stack** — PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68), [#69](https://github.com/TechImmigrants/cv-builder/pull/69), [#70](https://github.com/TechImmigrants/cv-builder/pull/70), [#71](https://github.com/TechImmigrants/cv-builder/pull/71), [#72](https://github.com/TechImmigrants/cv-builder/pull/72), [#73](https://github.com/TechImmigrants/cv-builder/pull/73) | @saharpak | **ASAP** | Open since 2026-06-07. Currently the single biggest contributor-experience blocker — new contributors cloning `main` get a different product than what's documented. **Reviewer help urgently wanted — see below.** | -| CV/JD input screen with file upload — PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76) | unassigned | TBD | Two-column input screen. Depends on Phase-1 merge. | -| CodeRabbit config expansion — PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75) | unassigned | TBD | Per-package review guidance. | -| Rule: flag outdated technologies — PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74) | unassigned | TBD | Resolves issue [#53](https://github.com/TechImmigrants/cv-builder/issues/53). | -| CI: web UI deploy previews on Cloudflare Pages — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. | +| **CI: web UI deploy previews to Cloudflare Pages** — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. Requires `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repo secrets. Tracked but out of this audit's scope. | +| **CLI: color output** — PR [#37](https://github.com/TechImmigrants/cv-builder/pull/37) | unassigned | TBD | Author needs to rebase against post-merge `main`; CLI was refactored after PR #37 opened. Tracked but out of this audit's scope. | -> ### ⚠️ Reviewer help wanted on Phase-1 PRs +> ### ✅ Recently shipped (post-merge on `main`) > -> The bottleneck isn't writing code — it's review bandwidth. If you have -> **TypeScript + zod** experience and can review one of #68–#73, comment on -> the PR. A 30-minute review from someone other than the maintainer unblocks -> the entire stack and signals to the rest of the contributor base that the -> project is moving. +> Phase-1 stack (PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68)–[#73](https://github.com/TechImmigrants/cv-builder/pull/73)), +> CV/JD input screen (PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76)), +> CodeRabbit config expansion (PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75)), +> outdated-technology rule (PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74)), +> no-code contribution paths and the MVP demo polish (PR [#85](https://github.com/TechImmigrants/cv-builder/pull/85), +> PR [#87](https://github.com/TechImmigrants/cv-builder/pull/87)). +> Full validation in [`docs/MVP_RELEASE_STATUS.md`](docs/MVP_RELEASE_STATUS.md). --- @@ -55,9 +67,9 @@ scope. **Comment "I'll take this" on the issue to claim.** | Rule: flag outdated technologies | S | [#53](https://github.com/TechImmigrants/cv-builder/issues/53) | `good first issue`, `rules`. **PR #74 already in flight — check before starting.** | | Add per-dimension feedback strings to evaluator | S | [#48](https://github.com/TechImmigrants/cv-builder/issues/48) | `enhancement`, `core`. | | Fix: flag missing contact information | S | [#55](https://github.com/TechImmigrants/cv-builder/pull/55) | `core`. PR already open — needs review. | -| New archetype: **AI Engineer** | M | (open issue) | Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md). Top priority for the 2026 market. | -| New archetype: **AI Product Manager** | M | (open issue) | Top priority for the 2026 market. | -| New archetypes: Backend / Frontend / DevOps | M each | (open issue) | Currently advertised in README but unimplemented. | +| New archetype: **AI Engineer** | M | (open issue) | **Already shipped** as of the MVP — see README "Supported Role Archetypes". Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md) to suggest more roles. | +| New archetype: **AI Product Manager** | M | (open issue) | **Already shipped** as of the MVP — see README "Supported Role Archetypes". | +| New archetypes: Backend / Frontend / DevOps / QA / Data Engineer | M each | (open issue) | **Already shipped** as of the MVP. README lists eight built-in roles. | | Land CONTRIBUTING.md "no-code" section | S | (open issue) | The draft this file came from. | | Write `docs/faq.md` ("I got a bad score, what now?") | S | (open issue) | | | Write `docs/cli-troubleshooting.md` | S | (open issue) | | @@ -85,9 +97,10 @@ scope. **Comment "I'll take this" on the issue to claim.** - **Suggest new items** — open an issue with the relevant label. - **Push a 🅿️ Parked item** — if you think something should be un-parked, open an issue with the `roadmap` label and the rationale. -- **Help review Phase-1 PRs** — the single highest-leverage thing a - TypeScript-comfortable contributor can do this week. +- **Help with the v0.2 backlog** — that's where the meaningful contributor + work lives now that v0.1 has shipped. --- -*Last updated: 2026-06-22* +*Last updated: 2026-07-02 (post-MVP release). The previous "Last updated" +date of 2026-06-22 predates the MVP release and is no longer accurate.* diff --git a/apps/cli/README.md b/apps/cli/README.md index 2ab0fc7..a48c23b 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -19,15 +19,17 @@ tests or the web app.) Then, inside Claude Code: ```text -/evaluate-cv ./my-resume.pdf +/evaluate-cv ./my-resume.md ``` Optionally add a job description as keyword context: ```text -/evaluate-cv ./my-resume.pdf --jd ./job.md +/evaluate-cv ./my-resume.md --jd ./job.md ``` +Claude Code can read PDF and DOCX inputs natively, so `/evaluate-cv ./my-resume.pdf` also works as long as the file is on your machine. The local web UI and CLI in this repo parse `.md` and `.txt` only — see [docs/LOCAL_DEMO.md](../../docs/LOCAL_DEMO.md). + No resume handy? Run `/setup-profile` and it'll help you assemble one. ## What you get diff --git a/apps/web-ui/README.md b/apps/web-ui/README.md index 4cd6eeb..f444350 100644 --- a/apps/web-ui/README.md +++ b/apps/web-ui/README.md @@ -1,9 +1,18 @@ # CV Builder Web -This package contains the Next.js web app for **CV Builder**. +This package contains the Next.js web app for **CV Builder** — a privacy-first +local-only CV evaluator. The web UI runs the deterministic evaluator +(`@cv-builder/core`) entirely in the browser; nothing is sent to a server. -The current homepage is a simple landing screen for the product and replaces the -default generated Next.js starter content. +This is the **community MVP**: it scores an existing resume, it does not +generate, tailor, or rewrite one. PDF parsing, hosted deployment, and rewrite +suggestions are out of scope for this surface and tracked on the roadmap. + +## Routes (static export) + +- `/` — paste a CV (and optional JD), click Evaluate +- `/results` — score, per-dimension bars, archetype, ATS verdict, issues, strengths +- `/feedback` — community feedback guide with an anonymisation checklist ## Local development @@ -20,12 +29,14 @@ Then open [http://localhost:3000](http://localhost:3000). | Command | Purpose | | ------------ | -------------------------- | | `pnpm dev` | Start the local dev server | -| `pnpm build` | Build the production app | +| `pnpm build` | Build the production app (static export) | | `pnpm start` | Run the production build | | `pnpm lint` | Run lint checks | ## Main files -- `src/app/layout.tsx` - app shell and metadata -- `src/app/page.tsx` - homepage +- `src/app/layout.tsx` - app shell, theme provider, and metadata +- `src/app/page.tsx` - homepage (paste form) +- `src/app/results/page.tsx` - evaluation results view +- `src/app/feedback/page.tsx` - feedback guide - `src/app/globals.css` - global styles diff --git a/apps/web-ui/src/app/layout.tsx b/apps/web-ui/src/app/layout.tsx index 9573d38..d0cd20c 100644 --- a/apps/web-ui/src/app/layout.tsx +++ b/apps/web-ui/src/app/layout.tsx @@ -14,8 +14,9 @@ const geistMono = Geist_Mono({ }); export const metadata: Metadata = { - title: "CV Builder", - description: "Build a tailored resume...", + title: "CV Builder — local MVP", + description: + "Privacy-first CV evaluator for tech professionals. Paste a resume, get a 0–5 score across six dimensions with prioritised fixes. Runs entirely in your browser; nothing is uploaded.", }; export default function RootLayout({ children }: { children: React.ReactNode }) { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 77d7e56..92cfa84 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,5 +1,20 @@ # Architecture +> **Status note — historical / aspirational document.** This file describes +> the proposed v2 architecture (Fastify server, Telegram bot, LLM adapter +> package, ingestion package, templates package, Tolgee i18n). It pre-dates +> the MVP shipped on `main` as of the post-PR #87 release. +> +> The current MVP is a **deterministic, locally-running CV evaluator**. It +> ships `packages/{schemas,intelligence,prompts,core,cli,eval}` and +> `apps/{cli,web-ui}` only — no `server`, no `telegram` app, no `llm`, +> `ingestion`, or `templates` package. PDF parsing, hosted deployment, and +> rewriting are explicitly out of scope for this MVP. +> +> For the **current** product status, validation results, what is and is not +> ready, read [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat +> this file as design context, not a description of the deployed product. + ## Layout ``` diff --git a/docs/MVP_DEMO_PLAN.md b/docs/MVP_DEMO_PLAN.md index d47e518..2e92f80 100644 --- a/docs/MVP_DEMO_PLAN.md +++ b/docs/MVP_DEMO_PLAN.md @@ -3,6 +3,18 @@ > Goal: prepare the current CV Builder for a simple public demo. > Source: post-merge `main` at `6170aef`. PRs #37 and #78 not in scope. +> **Status note — historical document.** This was the demo-readiness audit +> written before the polish in PR #87 landed. Some items in the +> "Current limitations" section below (misleading home copy, results page +> missing issues, empty-state, FileUpload alert, visual bars, Node version +> drift) were fixed in PR #87 and follow-up commits. The "demo is +> local-only ready / cannot be shared publicly without deploying" verdict +> still holds for the v0.1 release. +> +> For the **current** product status, validation results, and what is and +> is not ready, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). + ## What currently works ### Web UI (`apps/web-ui/`) diff --git a/docs/PHASE-1.md b/docs/PHASE-1.md index bd6b19e..3466f74 100644 --- a/docs/PHASE-1.md +++ b/docs/PHASE-1.md @@ -4,6 +4,25 @@ **Target:** Ship MVP within 3 weeks of team alignment call **Status:** Planning +> **Status note — historical document.** This is the original Phase 1 plan. +> It was written before the MVP shipped. It describes `packages/llm`, +> `packages/ingestion`, `packages/templates`, an `apps/server` (Fastify), an +> `apps/telegram` bot, Tolgee i18n, and a hosted mode with rate limits — +> none of which exist in the MVP that actually shipped on `main`. +> +> The shipped MVP is a **deterministic, locally-running CV evaluator** with +> `packages/{schemas,intelligence,prompts,core,cli,eval}` and +> `apps/{cli,web-ui}` only. The success criteria in this doc (Telegram bot, +> hosted public URL, EN + FA locales, 3 evaluations/day rate limit) were +> deferred. PDF parsing, hosted deployment, and rewriting are explicitly +> out of scope. +> +> For the **current** product status, validation results, and what is and +> is not ready, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat this file +> as the original planning document, not a description of the deployed +> product. + --- ## What We're Building diff --git a/docs/POST_MERGE_VALIDATION.md b/docs/POST_MERGE_VALIDATION.md index bbf7774..8175e9b 100644 --- a/docs/POST_MERGE_VALIDATION.md +++ b/docs/POST_MERGE_VALIDATION.md @@ -3,6 +3,12 @@ > Generated immediately after PR #85 merged into `main`. > All validation was run on the post-merge `main` branch. +> **Status note — historical document.** This is the post-merge validation +> report from PR #85, the 14-PR integration that put MVP foundations on +> `main`. For the **current** post-merge status and validation results +> after PR #87, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). + ## Merge commit | Item | Value | diff --git a/docs/PR85_ROLLBACK_PLAN.md b/docs/PR85_ROLLBACK_PLAN.md index 0cc8002..4073ac6 100644 --- a/docs/PR85_ROLLBACK_PLAN.md +++ b/docs/PR85_ROLLBACK_PLAN.md @@ -1,5 +1,15 @@ # PR #85 Rollback Plan +> **Status note — historical document.** This is the rollback plan drafted +> before PR #85 (the 14-PR MVP integration) merged into `main`. The merge +> was successful and permanent — every subsequent release-readiness check +> passed. The safety tag `pre-pr85-main-backup-20260702` remains on +> `origin` as a permanent rollback point. You do not need to act on this +> doc unless you spot a regression pointing to that merge. +> +> For the **current** product status, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). + ## Pre-merge state captured - Tag: `pre-pr85-main-backup-20260702` diff --git a/docs/PROPOSAL.md b/docs/PROPOSAL.md index 6345d44..7df9733 100644 --- a/docs/PROPOSAL.md +++ b/docs/PROPOSAL.md @@ -1,5 +1,21 @@ # Proposal — CV Builder v2 +> **Status note — historical / aspirational document.** This file is the +> original v2 proposal written before the MVP shipped. It describes +> `packages/llm`, `packages/ingestion`, `packages/templates`, an +> `apps/server` (Fastify), an `apps/telegram` bot, and Tolgee i18n — none +> of which exist in the current MVP on `main`. +> +> The current MVP is a **deterministic, locally-running CV evaluator** that +> ships `packages/{schemas,intelligence,prompts,core,cli,eval}` and +> `apps/{cli,web-ui}` only. There is no hosted tier, no Telegram surface, +> and no LLM adapter in this repo. +> +> For the **current** product status, validation results, and what is and +> is not ready, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat this file +> as a historical design note, not a description of the deployed product. + ## Goal A TypeScript-only, monorepo CV evaluator and builder. v1 ships **evaluation**: paste a resume + JD, get a typed, evidence-grounded score against a role archetype. diff --git a/docs/PR_CLEANUP_HANDOFF.md b/docs/PR_CLEANUP_HANDOFF.md index c83275c..61819dc 100644 --- a/docs/PR_CLEANUP_HANDOFF.md +++ b/docs/PR_CLEANUP_HANDOFF.md @@ -4,6 +4,12 @@ > This document is the single source of truth for what happened, why, and > what the next maintainer should know. +> **Status note — historical document.** This is the report from the +> post-PR #85 cleanup phase (the 14-PR integration that landed MVP +> foundations on `main` and was finalised by PR #87's MVP release +> polish). It is kept for context. For the **current** product status, +> read [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). + ## TL;DR - 20 open PRs reviewed diff --git a/docs/REMAINING_PRS_PLAN.md b/docs/REMAINING_PRS_PLAN.md index 9407a1c..2593258 100644 --- a/docs/REMAINING_PRS_PLAN.md +++ b/docs/REMAINING_PRS_PLAN.md @@ -4,6 +4,14 @@ > Sourced from `gh pr view`, `gh pr diff`, and test merges against the > post-merge `main` at `5b59014`. +> **Status note — historical document.** This is the action plan for +> PR #37 (CLI color) and PR #78 (Cloudflare Pages previews) drafted +> immediately after PR #85 merged. The factual state of those two PRs as +> of today is the same — both remain OPEN and are intentionally +> untouched. For the **current** product status and what's still tracked +> as out-of-scope (hosted deployment, CLI cosmetic enhancements), read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). + ## TL;DR | PR | Title | State | Verdict | Handled by | diff --git a/docs/REPO_DOCS_AUDIT.md b/docs/REPO_DOCS_AUDIT.md new file mode 100644 index 0000000..9fa7ef5 --- /dev/null +++ b/docs/REPO_DOCS_AUDIT.md @@ -0,0 +1,237 @@ +# Repository Documentation & Consistency Audit + +> Documentation-only audit. No code, evaluator, or rule changes. No +> new features. No Cloudflare work. No changes to PR #37 or #78. + +## Audit date + +2026-07-02, against `main` at `4e43a3c` (post-PR #87 merge + +`docs/MVP_RELEASE_STATUS.md`). + +## Current repo status + +- **Product:** Privacy-first, locally-running CV evaluator. Deterministic + scoring. Six dimensions, eight archetypes, web UI + CLI + eval harness + + power-user Claude Code pack. No hosted version. No LLM adapter in this + repo. No PDF parsing. No rewriting / tailoring / export. +- **PRs merged:** PR #85 (PR cleanup integration), PR #87 (MVP release + readiness polish + docs). +- **PRs still open:** #37 (CLI color output, stale — author needs to + rebase) and #78 (Cloudflare Pages previews, needs maintainer secrets). + Both **intentionally not touched** in this audit. +- **Source of truth for "what the product does today":** + `docs/MVP_RELEASE_STATUS.md`. + +## Files reviewed + +### User-facing + +- `README.md` +- `ROADMAP.md` +- `CONTRIBUTING.md` +- `apps/web-ui/src/app/page.tsx` +- `apps/web-ui/src/app/layout.tsx` (Next.js metadata) +- `apps/web-ui/src/app/results/page.tsx` +- `apps/web-ui/src/app/feedback/page.tsx` +- `apps/web-ui/src/app/components/FileUpload.tsx` +- `apps/web-ui/README.md` +- `apps/cli/README.md` +- `packages/core/README.md` (none — checked `package.json` only) +- `packages/core/package.json` +- `packages/intelligence/README.md` +- `packages/eval/README.md` +- `packages/prompts/README.md` +- `packages/schemas/README.md` +- `packages/cli/package.json` + +### Docs + +- `docs/ARCHITECTURE.md` +- `docs/COMMUNITY_ANNOUNCEMENT.md` +- `docs/FEEDBACK_GUIDE.md` +- `docs/ISSUES_SEED.md` +- `docs/LOCAL_DEMO.md` +- `docs/MVP_DEMO_PLAN.md` +- `docs/MVP_RELEASE_STATUS.md` +- `docs/PHASE-1.md` +- `docs/POST_MERGE_VALIDATION.md` +- `docs/PR85_ROLLBACK_PLAN.md` +- `docs/PROPOSAL.md` +- `docs/PR_CLEANUP_HANDOFF.md` +- `docs/REMAINING_PRS_PLAN.md` +- `docs/V1_SCOPE.md` +- `docs/WINDOWS_SETUP.md` + +### Issue / PR templates + +- `.github/ISSUE_TEMPLATE/bug_report.md` +- `.github/ISSUE_TEMPLATE/feature_request.md` +- `.github/ISSUE_TEMPLATE/new_archetype.md` +- `.github/ISSUE_TEMPLATE/new_rule.md` +- `.github/PULL_REQUEST_TEMPLATE.md` + +### Skills / Claude Code surface + +- `.claude/skills/cv-evaluation/SKILL.md` +- `.claude/welcome.sh` (not modified — no misleading claims) + +### Repo metadata + +- Root `package.json` + +## Files changed + +| File | Type of change | +|---|---| +| `README.md` | ASCII diagram replaced with honest output description; Power User section clarified PDF handling | +| `ROADMAP.md` | Status note added; "🚧 In progress" updated to reflect post-merge reality; "Up next" archetype entries flagged as already shipped; "Reviewer help wanted on Phase-1 PRs" replaced with "Recently shipped"; "Last updated" corrected | +| `apps/web-ui/src/app/layout.tsx` | Next.js metadata description replaced ("Build a tailored resume..." → honest evaluator description) | +| `apps/web-ui/README.md` | Added routes section (`/`, `/results`, `/feedback`); added static-export + privacy clarification; expanded main-files list | +| `apps/cli/README.md` | Clarified that `/evaluate-cv ./my-resume.pdf` works only because Claude Code reads PDFs natively; the local web UI / CLI parse `.md` and `.txt` only | +| `package.json` (root) | `description` field replaced; "CV builder... tailored resume" → honest CV-evaluator description | +| `packages/core/package.json` | `description` field: "evaluation and tailoring engine" → "deterministic CV evaluation engine" | +| `packages/cli/package.json` | `description` field: "evaluate and tailor your CV" → "evaluate a CV from the terminal and print a colour-coded score, dimensions, issues, and ATS verdict" | +| `packages/intelligence/README.md` | Archetype list corrected: "Ships Software Engineer, Product Manager, Data & ML Engineer" → "Ships eight roles out of the box: AI Product Manager, AI Engineer, ML Engineer, Backend Engineer, Frontend Engineer, QA / Test Engineer, DevOps / SRE, Data Engineer." Default archetype (when no signal) corrected: Software Engineer → Backend Engineer | +| `packages/eval/README.md` | Removed outdated claim about an "LLM-produced `EvalResult`"; clarified that the MVP is fully deterministic and scoring quality is asserted by the core engine's rule-coverage tests | +| `.claude/skills/cv-evaluation/SKILL.md` | "the hosted product" → "the local MVP" (no hosted version exists); default archetype fixed (Software Engineer → Backend Engineer) | +| `docs/ARCHITECTURE.md` | Status note added — historical / aspirational document; Fastify / Telegram / llm / ingestion / templates / Tolgee don't exist in the shipped MVP | +| `docs/PROPOSAL.md` | Status note added — historical / aspirational; same reasons | +| `docs/PHASE-1.md` | Status note added — historical planning doc; success criteria (Telegram bot, hosted public URL, EN+FA locales, rate limits) were deferred | +| `docs/V1_SCOPE.md` | Status note added — historical / aspirational | +| `docs/MVP_DEMO_PLAN.md` | Status note added — pre-PR-87 audit; some items were fixed in PR #87 and follow-up commits | +| `docs/PR_CLEANUP_HANDOFF.md` | Status note added — historical context from the post-PR #85 cleanup phase | +| `docs/POST_MERGE_VALIDATION.md` | Status note added — historical validation report from PR #85 | +| `docs/REMAINING_PRS_PLAN.md` | Status note added — historical action plan for #37 and #78 (still open) | +| `docs/PR85_ROLLBACK_PLAN.md` | Status note added — historical rollback plan; merge was successful, tag remains on origin as a permanent rollback point | +| `docs/REPO_DOCS_AUDIT.md` | **New** — this file | + +## Outdated claims found and fixed + +### A. Misleading product framing (CV generation / tailoring / rewriting) + +| Location | Before | After | +|---|---|---| +| Root `package.json` description | "Open source CV builder for tech professionals. Paste a job description, get a tailored resume." | "Open source, privacy-first CV evaluator for tech professionals. Score an existing resume across six dimensions and get prioritised issues to fix. Runs locally — no hosted version, no telemetry." | +| `packages/core/package.json` description | "CV evaluation and tailoring engine" | "Deterministic CV evaluation engine — six-dimension rubric, archetype detection, issue and strength reporting" | +| `packages/cli/package.json` description | "CV Builder CLI — evaluate and tailor your CV from the terminal" | "CV Builder CLI — evaluate a CV from the terminal and print a colour-coded score, dimensions, issues, and ATS verdict" | +| `apps/web-ui/src/app/layout.tsx` Next.js metadata | `description: "Build a tailored resume..."` | Honest evaluator description | +| `README.md` ASCII diagram | "3 rewrites / Keywords gap / Tailored CV" outputs | "Issues / Strengths / ATS verdict / Archetype" — the actual MVP outputs | +| `apps/cli/README.md` | `/evaluate-cv ./my-resume.pdf` examples without context | Same examples plus an explicit note: Claude Code reads PDFs natively, the local web UI / CLI parse `.md` and `.txt` only | + +### B. Inaccurate counts and defaults + +| Location | Before | After | +|---|---|---| +| `packages/intelligence/README.md` | "Ships Software Engineer, Product Manager, Data & ML Engineer" (3 roles) | Lists the eight roles actually shipped in the MVP | +| `packages/intelligence/README.md` | "default to Software Engineer when there's no signal" | "default to Backend Engineer when there's no signal" (matches the actual evaluator) | +| `.claude/skills/cv-evaluation/SKILL.md` | "default to Software Engineer" | "default to Backend Engineer" | +| `ROADMAP.md` "🚧 In progress" | Phase-1 stack PRs #68–#73, #74, #75, #76 listed as in-progress | All four marked as ✅ Recently shipped; only #37 and #78 remain (tracked but out of scope) | +| `ROADMAP.md` "Up next" | "AI Engineer / AI Product Manager / Backend / Frontend / DevOps: Currently advertised in README but unimplemented" | All five marked as already shipped; the README lists eight built-in roles | + +### C. Aspirational architecture described as shipped + +| Location | Issue | Fix | +|---|---|---| +| `docs/ARCHITECTURE.md` | Describes TanStack Query, Tolgee, Fastify server, Telegram bot, `packages/llm`, `packages/ingestion`, `packages/templates` — none of which exist in the shipped MVP | Added prominent status note pointing to `docs/MVP_RELEASE_STATUS.md` | +| `docs/PROPOSAL.md` | Same aspirational architecture | Status note added | +| `docs/PHASE-1.md` | Success criteria reference Telegram bot, hosted public URL, EN + FA locales, 3 evaluations/day rate limit — all deferred | Status note added | +| `docs/V1_SCOPE.md` | Lists `packages/llm`, `packages/ingestion`, `packages/templates`, `apps/server`, `apps/telegram`, Tolgee | Status note added | +| `.claude/skills/cv-evaluation/SKILL.md` | "Run a resume through the same four-step evaluation the hosted product uses" — no hosted product exists | "Run a resume through the same four-step evaluation the local MVP uses" | + +### D. LLM adapter that doesn't exist + +| Location | Before | After | +|---|---|---| +| `packages/eval/README.md` | "Scoring quality (the LLM-produced `EvalResult`) is out of scope — that needs a provider adapter, which is a separate surface." | The MVP is fully deterministic. There is no LLM provider adapter in this repo. Scoring quality is asserted by the core engine's rule-coverage tests. | + +## Historical docs left intentionally unchanged + +These describe a previous state of the project. Their facts are +correct for the moment they were written. Rather than rewriting them +out of context, we added a status note pointing readers to the current +snapshot: + +- `docs/PR_CLEANUP_HANDOFF.md` — post-PR #85 cleanup report +- `docs/POST_MERGE_VALIDATION.md` — post-PR #85 validation report +- `docs/PR85_ROLLBACK_PLAN.md` — pre-PR #85 rollback plan (tag remains + on origin as a permanent safety point) +- `docs/REMAINING_PRS_PLAN.md` — action plan for #37 and #78 +- `docs/MVP_DEMO_PLAN.md` — pre-PR #87 demo-readiness audit +- `docs/ISSUES_SEED.md` — original seed list of starter issues; many + are now shipped + +The status notes are minimal blockquotes at the top of each file with +a one-paragraph explanation and a pointer to +`docs/MVP_RELEASE_STATUS.md`. + +## Remaining documentation risks + +These are gaps the audit did not close. They are flagged for a future +human-led pass: + +1. **`ROADMAP.md` "🎯 Up next"** — even after the cleanup, this section + still mixes a few items that may have already shipped (per-dimension + feedback strings, GitHub Actions lint workflow, example CVs, generic + summary / action verb / outdated-tech rules). Confirm against the + issue tracker and the actual codebase before claiming them. +2. **`docs/ISSUES_SEED.md`** — pre-PR #85 list. Many issues are now + obsolete or superseded by merged PRs. Not touched in this audit + because it is a planning seed, not a user-facing doc. +3. **`docs/MVP_DEMO_PLAN.md`** — still mentions "Node 22+" at line 56 + in the prereqs section. The audit added a status note rather than + editing the historical body. If you want a non-historical, accurate + prereq, link to `docs/LOCAL_DEMO.md`. +4. **`apps/web-ui/README.md` "Main files"** — still missing + `src/app/components/EvaluateForm.tsx`, `Header.tsx`, + `ScoreCard.tsx`, `ThemeToggle.tsx`, and `lib/evaluation-storage.ts`. + Left as-is for now; not user-visible. +5. **`CONTRIBUTING.md`** — doesn't mention the `docs/repo-consistency-audit` + branch / `REPO_DOCS_AUDIT.md` workflow. If you do another audit + pass, add a short subsection under "Development Workflow". +6. **`research/sources.md`** — out of audit scope but worth a periodic + review; some of the original "Last updated: May 2026" stats may + need refresh. +7. **`packages/prompts/README.md`** — describes the three Phase 1 + prompts (extract, score, validate-claims). The MVP has a + deterministic core engine, but the prompt pack is still the surface + the power-user skill uses. Not edited, but the doc could be clearer + about which surface is which. + +## Validation + +Run on this branch (`docs/repo-consistency-audit`) at the time of the +audit: + +| Command | Result | +|---|---| +| `pnpm test` | 12 / 12 tasks successful | +| `pnpm lint` | 0 errors. One pre-existing `biome.json` `linter.recommended` deprecation notice (unrelated) | +| `pnpm build` | 6 / 6 packages built. Web emits `/`, `/_not-found`, `/feedback`, `/results` as static | + +No code changes were made in this audit. Only docs, README copy, +package.json `description` fields, the Next.js metadata, and one +status note on the Claude Code skill. Validation passes because no +evaluator behavior, rule, or build surface was touched. + +## PR #37 and #78 confirmation + +- **PR #37** (CLI color output) — **not touched**. The package.json + description for `@cv-builder/cli` was updated to remove the + misleading "tailor" wording; the CLI's source code, behaviour, and + the branch it sits on were not modified. +- **PR #78** (Cloudflare Pages previews) — **not touched**. No + workflow files, no Cloudflare secrets, no `apps/web-ui/next.config.ts` + changes. The only Cloudflare-related copy edit is the `apps/web-ui/README.md` + routes section, which now correctly lists `/`, `/results`, `/feedback` + as static-export routes (it did not mention the routes at all before). + +## Recommended next docs step + +If you want one follow-up commit after this lands: + +- Have a maintainer eyeball `ROADMAP.md` "Up next" against the issue + tracker and either close obsolete items or replace the table with + the v0.2 backlog. That is the single highest-leverage doc edit + remaining. + +Everything else is stable enough to share publicly with contributors. \ No newline at end of file diff --git a/docs/V1_SCOPE.md b/docs/V1_SCOPE.md index 18194f2..4cadaa0 100644 --- a/docs/V1_SCOPE.md +++ b/docs/V1_SCOPE.md @@ -1,5 +1,23 @@ # V1 Scope +> **Status note — historical / aspirational document.** This is the +> original v1 scope written before the MVP shipped. It lists +> `packages/llm`, `packages/ingestion`, `packages/templates`, +> `apps/server`, `apps/telegram`, and Tolgee wiring — none of which exist +> in the MVP that actually shipped on `main`. +> +> The shipped MVP is a **deterministic, locally-running CV evaluator** +> with `packages/{schemas,intelligence,prompts,core,cli,eval}` and +> `apps/{cli,web-ui}` only. PDF export, hosted server, LLM provider +> adapters, and Tolgee i18n are explicitly out of scope and tracked on the +> roadmap (`ROADMAP.md`). +> +> For the **current** product status, validation results, and what is and +> is not ready, read +> [`docs/MVP_RELEASE_STATUS.md`](./MVP_RELEASE_STATUS.md). Treat this file +> as the original scope document, not a description of the deployed +> product. + ## In scope - `packages/schemas` — Resume, JobDescription, Archetype, EvalResult, Claim, Issue diff --git a/package.json b/package.json index f4c2ae5..d00b3e2 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "cv-builder", "version": "0.1.0", "private": true, - "description": "Open source CV builder for tech professionals. Paste a job description, get a tailored resume.", + "description": "Open source, privacy-first CV evaluator for tech professionals. Score an existing resume across six dimensions and get prioritised issues to fix. Runs locally — no hosted version, no telemetry.", "scripts": { "build": "turbo build", "dev": "turbo dev", diff --git a/packages/cli/package.json b/packages/cli/package.json index 268d091..47dfe6c 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,7 +1,7 @@ { "name": "@cv-builder/cli", "version": "0.1.0", - "description": "CV Builder CLI — evaluate and tailor your CV from the terminal", + "description": "CV Builder CLI — evaluate a CV from the terminal and print a colour-coded score, dimensions, issues, and ATS verdict", "type": "module", "bin": { "cv-builder": "./dist/cli.js" diff --git a/packages/core/package.json b/packages/core/package.json index c3240b0..82f8128 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,7 +1,7 @@ { "name": "@cv-builder/core", "version": "0.1.0", - "description": "CV evaluation and tailoring engine", + "description": "Deterministic CV evaluation engine — six-dimension rubric, archetype detection, issue and strength reporting", "type": "module", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/packages/eval/README.md b/packages/eval/README.md index 109036b..401595e 100644 --- a/packages/eval/README.md +++ b/packages/eval/README.md @@ -7,11 +7,14 @@ Each fixture is a folder under `fixtures/`: - `resume.md` — the input resume - `jd.md` — optional job description (keyword context) -- `expected.json` — `{ archetype, atsCompatible }` +- `expected.json` — `{ archetype, atsCompatible }` and, for some fixtures, + expected `issues[]` / `strengths[]` shapes The harness asserts, without any LLM, that for every fixture the detected -archetype and ATS read match what's expected, and that the resume parses against -the schema. A change that breaks archetype detection or the ATS check fails here. +archetype, ATS verdict, and rule firings match what's expected, and that the +resume parses against the schema. A change that breaks archetype detection or +the ATS check fails here. -Scoring *quality* (the LLM-produced `EvalResult`) is out of scope — that needs a -provider adapter, which is a separate surface. +This MVP is fully deterministic — there is no LLM provider adapter in this repo. +The scoring quality of an `EvaluationResult` is asserted by the rule-coverage +checks in the core engine's tests, not by an external model. diff --git a/packages/intelligence/README.md b/packages/intelligence/README.md index 0998cd6..bd5f6ab 100644 --- a/packages/intelligence/README.md +++ b/packages/intelligence/README.md @@ -1,16 +1,18 @@ # @cv-builder/intelligence -The scoring brain the prompts and skill reference: the fixed rubric, the role -archetypes, and the validator specs. +The scoring brain the web UI, CLI, and skill reference: the fixed rubric, the +role archetypes, and the validator specs. - **Rubric v1** — six dimensions (Shipped Evidence, Quantified Impact, Tech/Tool Visibility, ATS Compatibility, Keyword Match, Public Proof) with 0–5 anchors, tagged `RUBRIC_VERSION`. - **Archetypes** — role config (keywords, dimension weights, action verbs, - anti-patterns). Ships Software Engineer, Product Manager, Data & ML Engineer. - Add one by dropping a file in `src/archetypes/` and registering it. + anti-patterns). Ships eight roles out of the box: AI Product Manager, AI + Engineer, ML Engineer, Backend Engineer, Frontend Engineer, QA / Test + Engineer, DevOps / SRE, and Data Engineer. Add one by dropping a file in + `src/archetypes/` and registering it. - **Validators** — `checkAtsCompatibility()` plus the ATS and claim rule sets - the prompts encode. + the evaluator encodes. `detectArchetype(resumeText)` picks the best-matching archetype, falling back to -Software Engineer when there's no signal. +Backend Engineer when there's no signal. From 5ba50adc02f39d6ec858f5b925e099c071722f07 Mon Sep 17 00:00:00 2001 From: Cleanup Bot Date: Thu, 2 Jul 2026 20:01:17 +0300 Subject: [PATCH 2/3] docs: fix remaining Node version reference docs/MVP_DEMO_PLAN.md still said 'Node 22+' in the prereqs section, which conflicts with the actual repo metadata (Node >= 20.0.0 in package.json) and with the authoritative setup guide in docs/LOCAL_DEMO.md. Replace the prereqs with a short pointer to LOCAL_DEMO.md plus a one-line accurate summary, so this historical demo-readiness doc no longer contradicts current setup instructions. docs/REPO_DOCS_AUDIT.md: remove the corresponding entry from the 'remaining documentation risks' list, fix the resulting item numbering, and add a note recording that the Node-version item was resolved before merge. No code, evaluator, or rule changes. No new features. PR #37 and PR #78 untouched. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6 (fresh --force, emits /, /_not-found, /feedback, /results). --- docs/MVP_DEMO_PLAN.md | 5 +++-- docs/REPO_DOCS_AUDIT.md | 17 +++++++++-------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/MVP_DEMO_PLAN.md b/docs/MVP_DEMO_PLAN.md index 2e92f80..e39554f 100644 --- a/docs/MVP_DEMO_PLAN.md +++ b/docs/MVP_DEMO_PLAN.md @@ -63,8 +63,9 @@ ### Prereqs -- Node 22+ (matches the GitHub Actions workflow) -- pnpm 9.15+ (`npm install -g pnpm@9.15.0`) +See [docs/LOCAL_DEMO.md](./LOCAL_DEMO.md) for the current setup guide. +Quick version: Node.js 20 or newer (matches `package.json`), pnpm 9.15+, +`pnpm install`, then `pnpm dev`. ### One-time setup diff --git a/docs/REPO_DOCS_AUDIT.md b/docs/REPO_DOCS_AUDIT.md index 9fa7ef5..8ed6927 100644 --- a/docs/REPO_DOCS_AUDIT.md +++ b/docs/REPO_DOCS_AUDIT.md @@ -177,26 +177,27 @@ human-led pass: 2. **`docs/ISSUES_SEED.md`** — pre-PR #85 list. Many issues are now obsolete or superseded by merged PRs. Not touched in this audit because it is a planning seed, not a user-facing doc. -3. **`docs/MVP_DEMO_PLAN.md`** — still mentions "Node 22+" at line 56 - in the prereqs section. The audit added a status note rather than - editing the historical body. If you want a non-historical, accurate - prereq, link to `docs/LOCAL_DEMO.md`. -4. **`apps/web-ui/README.md` "Main files"** — still missing +3. **`apps/web-ui/README.md` "Main files"** — still missing `src/app/components/EvaluateForm.tsx`, `Header.tsx`, `ScoreCard.tsx`, `ThemeToggle.tsx`, and `lib/evaluation-storage.ts`. Left as-is for now; not user-visible. -5. **`CONTRIBUTING.md`** — doesn't mention the `docs/repo-consistency-audit` +4. **`CONTRIBUTING.md`** — doesn't mention the `docs/repo-consistency-audit` branch / `REPO_DOCS_AUDIT.md` workflow. If you do another audit pass, add a short subsection under "Development Workflow". -6. **`research/sources.md`** — out of audit scope but worth a periodic +5. **`research/sources.md`** — out of audit scope but worth a periodic review; some of the original "Last updated: May 2026" stats may need refresh. -7. **`packages/prompts/README.md`** — describes the three Phase 1 +6. **`packages/prompts/README.md`** — describes the three Phase 1 prompts (extract, score, validate-claims). The MVP has a deterministic core engine, but the prompt pack is still the surface the power-user skill uses. Not edited, but the doc could be clearer about which surface is which. +> **Note (post-audit fix):** the previous item 3 — the "Node 22+" line +> in `docs/MVP_DEMO_PLAN.md` — was resolved before merge. The prereqs +> section now points to `docs/LOCAL_DEMO.md` as the authoritative local +> setup guide and notes Node 20 or newer. + ## Validation Run on this branch (`docs/repo-consistency-audit`) at the time of the From 9c865b7317940aabd5f67cb4971de877edeb9664 Mon Sep 17 00:00:00 2001 From: Cleanup Bot Date: Thu, 2 Jul 2026 21:56:09 +0300 Subject: [PATCH 3/3] docs: address remaining CodeRabbit comments on PR #88 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two unresolved CodeRabbit comments fixed in this commit: 1. README.md — replace hard-coded '5 issues' in the evaluator diagram with the non-fixed wording 'Issues'. evaluate() returns a variable-length issues array; a fixed count would drift as scoring changes. The other diagram labels (Score, Strengths, ATS verdict, Archetype) are kept as-is because they describe deterministic outputs that do not vary in count. 2. packages/intelligence/README.md — the previous audit pass claimed this package ships eight roles and falls back to Backend Engineer. But packages/intelligence/src/archetypes/index.ts registers only three archetypes (Software Engineer, Product Manager, Data & ML Engineer) and DEFAULT_ARCHETYPE is softwareEngineer. Update the README to reflect the actual registry. Add a note clarifying that @cv-builder/core has a separate, broader legacy/runtime registry (7 roles) used by the CLI and Web UI, and that unifying the two registries is a follow-up — see docs/ARCHETYPE_GAP_AUDIT.md. docs/REPO_DOCS_AUDIT.md updated to record that the packages/intelligence/README.md archetype-inventory row was corrected in two steps (the audit pass incorrectly bumped the package claim to 8; this commit brings it back to 3 and adds the @cv-builder/core note). No code changes. No new features. PR #37 and PR #78 untouched. Docs only. Validates: pnpm test 12/12, pnpm lint 0 errors, pnpm build 6/6. --- README.md | 2 +- docs/REPO_DOCS_AUDIT.md | 8 ++++---- packages/intelligence/README.md | 18 +++++++++++++----- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0faf555..89eb6b0 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Good CV tools are expensive. Many job seekers — especially immigrants, career ``` ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │ Your CV │ ──▶ │ CV Builder │ ──▶ │ Score: 4.2/5 │ -└──────────┘ │ Engine │ │ 5 issues │ +└──────────┘ │ Engine │ │ Issues │ ┌──────────┐ │ │ │ Strengths │ │ JD │ ──▶ │ (6 scoring │ │ ATS verdict │ │(optional)│ │ dimensions) │ │ Archetype │ diff --git a/docs/REPO_DOCS_AUDIT.md b/docs/REPO_DOCS_AUDIT.md index 8ed6927..0df17be 100644 --- a/docs/REPO_DOCS_AUDIT.md +++ b/docs/REPO_DOCS_AUDIT.md @@ -91,7 +91,7 @@ | `package.json` (root) | `description` field replaced; "CV builder... tailored resume" → honest CV-evaluator description | | `packages/core/package.json` | `description` field: "evaluation and tailoring engine" → "deterministic CV evaluation engine" | | `packages/cli/package.json` | `description` field: "evaluate and tailor your CV" → "evaluate a CV from the terminal and print a colour-coded score, dimensions, issues, and ATS verdict" | -| `packages/intelligence/README.md` | Archetype list corrected: "Ships Software Engineer, Product Manager, Data & ML Engineer" → "Ships eight roles out of the box: AI Product Manager, AI Engineer, ML Engineer, Backend Engineer, Frontend Engineer, QA / Test Engineer, DevOps / SRE, Data Engineer." Default archetype (when no signal) corrected: Software Engineer → Backend Engineer | +| `packages/intelligence/README.md` | Archetype list corrected: "Ships Software Engineer, Product Manager, Data & ML Engineer" (3 roles) → accurately reflects the package's own registry (3 roles: Software Engineer, Product Manager, Data & ML Engineer) with a note pointing to `@cv-builder/core`'s separate, broader legacy/runtime registry (7 roles). Default archetype (when no signal) corrected: Software Engineer → Backend Engineer (initial pass) → corrected back to Software Engineer to match this package's actual `DEFAULT_ARCHETYPE`. See `packages/intelligence/src/archetypes/index.ts`. | | `packages/eval/README.md` | Removed outdated claim about an "LLM-produced `EvalResult`"; clarified that the MVP is fully deterministic and scoring quality is asserted by the core engine's rule-coverage tests | | `.claude/skills/cv-evaluation/SKILL.md` | "the hosted product" → "the local MVP" (no hosted version exists); default archetype fixed (Software Engineer → Backend Engineer) | | `docs/ARCHITECTURE.md` | Status note added — historical / aspirational document; Fastify / Telegram / llm / ingestion / templates / Tolgee don't exist in the shipped MVP | @@ -122,9 +122,9 @@ | Location | Before | After | |---|---|---| -| `packages/intelligence/README.md` | "Ships Software Engineer, Product Manager, Data & ML Engineer" (3 roles) | Lists the eight roles actually shipped in the MVP | -| `packages/intelligence/README.md` | "default to Software Engineer when there's no signal" | "default to Backend Engineer when there's no signal" (matches the actual evaluator) | -| `.claude/skills/cv-evaluation/SKILL.md` | "default to Software Engineer" | "default to Backend Engineer" | +| `packages/intelligence/README.md` | "Ships Software Engineer, Product Manager, Data & ML Engineer" (3 roles) — this is what the package's own registry actually contains | The README now matches the package's own runtime registry (3 roles: Software Engineer, Product Manager, Data & ML Engineer). A clarifying note was added pointing to `@cv-builder/core`'s separate, broader legacy/runtime registry (7 roles), so the file is no longer confusable with the user-facing archetype list in the root README. | +| `packages/intelligence/README.md` | "default to Software Engineer when there's no signal" | Matches `DEFAULT_ARCHETYPE` in `packages/intelligence/src/archetypes/index.ts` (Software Engineer). | +| `.claude/skills/cv-evaluation/SKILL.md` | "default to Software Engineer" | "default to Backend Engineer" (the skill consumes `@cv-builder/core`, whose `DEFAULT_ARCHETYPE` is Backend Engineer — different system) | | `ROADMAP.md` "🚧 In progress" | Phase-1 stack PRs #68–#73, #74, #75, #76 listed as in-progress | All four marked as ✅ Recently shipped; only #37 and #78 remain (tracked but out of scope) | | `ROADMAP.md` "Up next" | "AI Engineer / AI Product Manager / Backend / Frontend / DevOps: Currently advertised in README but unimplemented" | All five marked as already shipped; the README lists eight built-in roles | diff --git a/packages/intelligence/README.md b/packages/intelligence/README.md index bd5f6ab..e60dc21 100644 --- a/packages/intelligence/README.md +++ b/packages/intelligence/README.md @@ -7,12 +7,20 @@ role archetypes, and the validator specs. Visibility, ATS Compatibility, Keyword Match, Public Proof) with 0–5 anchors, tagged `RUBRIC_VERSION`. - **Archetypes** — role config (keywords, dimension weights, action verbs, - anti-patterns). Ships eight roles out of the box: AI Product Manager, AI - Engineer, ML Engineer, Backend Engineer, Frontend Engineer, QA / Test - Engineer, DevOps / SRE, and Data Engineer. Add one by dropping a file in - `src/archetypes/` and registering it. + anti-patterns). This package ships three roles out of the box: Software + Engineer, Product Manager, and Data & ML Engineer. Add one by dropping a + file in `src/archetypes/` and registering it. - **Validators** — `checkAtsCompatibility()` plus the ATS and claim rule sets the evaluator encodes. `detectArchetype(resumeText)` picks the best-matching archetype, falling back to -Backend Engineer when there's no signal. +Software Engineer when there's no signal. + +> **Note on the broader role list.** This package's registry is a focused, +> schema-versioned trio used by the prompt pack and the eval fixtures. The +> MVP's user-facing CLI and Web UI are driven by `@cv-builder/core`, which +> carries a separate, broader legacy/runtime archetype registry (seven +> roles, including AI Product Manager, AI Engineer, Backend, Frontend, QA, +> DevOps / SRE, and Data Engineer). Unifying the two registries into a +> single source of truth is a follow-up — see +> [`docs/ARCHETYPE_GAP_AUDIT.md`](../../docs/ARCHETYPE_GAP_AUDIT.md).