tor-to-proposal 2.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "tor-to-proposal",
+  "owner": {
+    "name": "Omar Farooq"
+  },
+  "plugins": [
+    {
+      "name": "tor-to-proposal",
+      "source": "./",
+      "description": "ToR + CV in -> verified bid pack out: bid screen, consolidated questionnaire, tailored CV, cover letter lint, honest pricing, financial proposal, evaluation simulator, form filling, PDF packaging with a final honesty audit."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "tor-to-proposal",
+  "description": "The bid tool that refuses to lie \u2014 turns a ToR + CV into a complete, verified bid pack: cover letter, tailored CV, technical response, financial proposal, submission checklist. Skills + slash commands + MCP tools.",
+  "version": "2.0.0",
+  "author": {
+    "name": "Omar Farooq"
+  },
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Farooq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# tor-to-proposal
+
+**The bid tool that refuses to lie.**
+
+ToR + CV in → **verified bid pack out** — customized cover letter, tailored CV,
+technical response, financial proposal, submission checklist — as PDFs, in
+minutes, for UN / NGO / government consultants.
+
+It does **not** write your evidence for you. Your track record wins bids; this
+tool guarantees your bid is complete, compliant, honestly priced, verified
+against the client's scoring grid, and audited **on the final rendered bytes**
+before you submit.
+
+## Why it exists
+
+Every factual claim in any output must trace to a page in the source ToR, a
+user-supplied input, or a cited external source — otherwise it stays `[FILL]`.
+The tailored CV is proven line-by-line against your master CV. Pricing runs
+only on numbers you confirm. The app never fabricates rates, experience,
+dates, names or client facts. In a domain where one invented fact means
+disqualification (and vendor blacklisting), that is the feature, not a
+limitation.
+
+## Install — one command, once
+
+```bash
+npx tor-to-proposal init
+```
+
+That sets up your consultant profile (name, credentials, rates, master CV) at
+`~/.tor-to-proposal/profile.json`. Then use it with any AI assistant (Claude
+Desktop / Claude Code / Codex / ChatGPT) via the MCP server at
+`mcp/server.mjs`, or install the agent skill:
+
+```bash
+npx skills add ahaomar/tor-to-proposal   # agent users
+```
+
+Local-first: no network calls carry your documents. The only optional outbound
+step is market-rate research you run yourself.
+
+## The workflow — ToR + CV in, bid pack out
+
+```bash
+tor-to-proposal bid-pack start  --tor tor.pdf --cv cv.txt --dir mybid/  # screen + gaps + draft CV
+tor-to-proposal bid-pack apply  --answers answers.json --dir mybid/    # your answers -> pricing + financials
+tor-to-proposal bid-pack pack   --dir mybid/                           # verify + checklist + zip
+```
+
+With an assistant, you never run these — you say *"run a bid pack on this
+folder"* and answer **one consolidated questionnaire**.
+
+| Phase | What happens | You decide |
+| --- | --- | --- |
+| 1. Intake | ToR structured: deadline, effort, evaluation grid, compliance matrix, bid screen. CV gap analysis (MATCH / **GAP — do not claim**). Tailored CV drafted from your master CV. | Go / no-go |
+| 2. The one questionnaire | Every open item — pricing, availability, validity, missing evidence — in a single numbered list. `apply` turns answers into pricing + the financial proposal. | All of it |
+| 3. Drafts | Cover letter (lint-gated), technical response per scored criterion (coverage-simulated), tailored CV (anchor-verified), financial proposal (formulas visible). | Review |
+| 4. Pack | Every rendered PDF/docx/xlsx is **re-extracted and re-audited**; pack/ + submission-checklist.md + deadline.ics + zip. Stale packs are removed on failure. | Submit |
+
+The agent-facing master workflow lives in [SKILL.md](SKILL.md). Every stage is
+also directly runnable: `tor-to-proposal <command> --help` (17 commands).
+
+## Guides
+
+| Guide | For |
+| --- | --- |
+| [docs/USER-GUIDE.md](docs/USER-GUIDE.md) | Non-technical consultants — plain-language, step-by-step, what you'll see at every step |
+| [docs/PROMPT-GUIDE.md](docs/PROMPT-GUIDE.md) | Agent users — setup for Claude/ChatGPT/Codex/any agent + a copy-paste prompt library for each phase |
+| [docs/TECHNICAL-GUIDE.md](docs/TECHNICAL-GUIDE.md) | Developers / IT — architecture, CLI reference, data contracts, MCP/plugin internals, extension points |
+
+## Trust
+
+- Local-first. Nothing about your bid leaves your machine.
+- Honesty gates are mechanical, not aspirational: cover-letter lint,
+  CV anchor lint, pricing gate, simulator, template-filler (client's formulas
+  never touched), and a final audit that runs on the rendered bytes.
+- `pricing.md` / `pricing.json` contain your floor math — the pack builder
+  never includes them in what you submit.
+
+## Development
+
+```bash
+npm install
+npm test     # 39 tests: extract, pricing, rates, cv-gap, cover-letter lint,
+             # simulator, template-filler (docx+xlsx), audit, profile,
+             # cv-tailor build/lint, financial proposal (md+xlsx), render
+             # round-trip, bid-pack start/apply/pack, MCP handshake
+```
+
+Node ≥ 18. Dependencies (all local, all pure JS): `unpdf`, `mammoth`,
+`exceljs`, `adm-zip`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Design spec: [tor-to-proposal-build-spec.md](tor-to-proposal-build-spec.md).

package/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: tor-to-proposal
+description: >
+  Turn UN / NGO / government Terms of Reference (ToR), solicitations, RFPs and
+  job descriptions into a complete, verified bid pack — customized cover letter,
+  tailored CV, technical response, financial proposal, submission checklist —
+  as PDF/docx/xlsx in minutes. MUST BE USED when the user mentions a ToR,
+  tender, solicitation, RFP, RFQ, IC/SSA consultancy, UNGM bid,
+  UNDP/UNOPS/UNICEF/World Bank/USAID assignment, wants a go/no-go bid decision,
+  a compliance matrix, a cover letter for a consultancy, CV tailoring against a
+  ToR, consultancy pricing/day rates, evaluation-criteria scoring of a draft,
+  or a pre-submission audit of a proposal. Covers: bid screen, consolidated
+  questionnaire, CV gap analysis + tailoring, cover letter lint, market rate
+  benchmarking, pricing model, financial proposal, client dossier, evaluation
+  simulator, filling the client's own docx/xlsx forms, PDF packaging with a
+  final honesty audit.
+---
+
+# tor-to-proposal — the bid tool that refuses to lie
+
+You (the agent) draft. The tools verify. Nothing ships that a tool has not
+gated. Every claim traces to the ToR (p.X), a user input, or a cited source —
+otherwise it stays `[FILL]`.
+
+## The product: ToR + CV in → bid pack out
+
+The default experience is the **bid pack**. One ToR, one CV, one consolidated
+questionnaire, one verified, zipped submission folder:
+
+```
+<bid-dir>/pack/  Cover-Letter.pdf · CV.pdf · Technical-Proposal.pdf ·
+                 Financial-Proposal.pdf|xlsx · submission-checklist.md ·
+                 deadline.ics · audit passed on the final bytes
+```
+
+## Bootstrap (once per machine)
+
+```bash
+npx tor-to-proposal init     # preferred: profile wizard (name, rates, master CV)
+# — or, from a clone:
+cd <this-skill-directory> && npm install
+```
+
+All processing is local. No network calls are made with the user's documents.
+The only optional outbound step is market-rate research the user approves.
+
+## Non-negotiable rules (enforced by the tools, restated for you)
+
+1. **CITATION** — every factual claim traces to `[[PAGE n]]` / `(p.X)` from the
+   ToR, a user input, or a cited source (URL + access date). Otherwise `[FILL]`.
+2. **NO INVENTION** — never fabricate rates, experience, dates, names, client
+   facts. Tools compute; the user decides. The tailored CV may only reorder and
+   rephrase the master CV — `cv-tailor lint` proves it line by line.
+3. **CLIENT TEMPLATE WINS** — outputs restructure into the client's own forms
+   via `template-filler`, never the reverse.
+4. **HONESTY (pricing)** — numbers only from the user's confirmed inputs
+   (their profile answer, or this bid's answers.json). Never gut-feel.
+5. **NO FALSE PRECISION** — simulator output is coverage arithmetic, never a
+   predicted evaluator score.
+
+If a step would force you to violate a rule, stop and tell the user what input
+is missing.
+
+## The bid pack conversation (default workflow)
+
+Paths assume `--dir <bid-dir>` (default `bid/`); artifacts live in
+`<bid-dir>/out/`. Read the ToR first; never quote it from memory.
+
+### Phase 1 — Intake (all mechanical steps, one command)
+
+```bash
+node bin/bid-pack.mjs start --tor <tor.(pdf|docx|txt)> --cv <cv.(pdf|docx|txt)> --dir <bid-dir>
+```
+
+Runs pdf-extract → extract (bid screen, compliance matrix) → cv-gap →
+cv-tailor build, then writes **`out/questions.md`**. Exit 2 on a scanned PDF →
+OCR first; never improvise page numbers.
+
+**Present the bid screen to the user** (deadline, effort, scoring, red flags).
+Go/no-go is THEIR call. If no-go: stop and say so.
+
+### Phase 2 — The ONE questionnaire (no scattered questions, ever)
+
+`out/questions.md` consolidates every open decision: pricing, availability,
+validity, draft `[FILL]`s, CV evidence. **Put all of them to the user in one
+message**, grouped. Never drip-feed questions and never answer one for the
+user. Then:
+
+```bash
+# write the answers verbatim:
+node bin/bid-pack.mjs apply --answers answers.json --dir <bid-dir>
+```
+
+`apply` runs pricing on the user's confirmed numbers, renders the financial
+proposal, records CV evidence + fill answers, and regenerates the open list.
+Repeat until `0 still open`.
+
+### Phase 3 — Draft all four documents (you draft, tools gate)
+
+Write drafts to `<bid-dir>/` as `cover-letter.md`, `technical-proposal.md`
+(`cv-tailored.md` already exists from Phase 1; edit it only with master-CV
+material or user evidence answers).
+
+- **Cover letter** — structure in `assets/templates.md` (≤1 page: reference
+  block → understanding from Background/Objectives → fit mapped to JD
+  competencies → compliance declarations → availability). Then loop:
+  `node bin/cover-letter.mjs lint --draft <bid-dir>/cover-letter.md --cv <cv.txt> --gap <bid-dir>/out/cv-gap-report.md` until PASS.
+- **Technical response** — one section per scored criterion, highest weight
+  first, in the client's vocabulary. Extract sub-elements verbatim into
+  `sub-elements.json`, then loop:
+  `node bin/simulator.mjs --extract <bid-dir>/out/tor-extract.json --response <bid-dir>/technical-proposal.md --sub-elements sub-elements.json` until at-risk ≈ 0.
+  Present it as coverage arithmetic — never as a predicted score.
+- **Tailored CV** — verify:
+  `node bin/cv-tailor.mjs lint --cv <bid-dir>/out/cv-tailored.md --master <master-cv> --gap <bid-dir>/out/cv-gap-report.md --evidence <bid-dir>/out/cv-evidence.json`
+  GAP rows are never claimed; unanchored lines fail until the user supplies
+  evidence via the questionnaire.
+- **Financial proposal** — already rendered by `apply` from pricing.json
+  (md + xlsx, formulas visible). If the client supplied their own form:
+  `template-filler.mjs map/fill/check` restructures INTO it.
+
+### Phase 4 — Render, package, deliver
+
+Render each final document to PDF with your own document tooling (typography:
+`references/render-specs.md`). If no document tooling is available, add
+`--fallback-pdf` to the command below and the built-in renderer will produce
+plain, valid PDFs. Then:
+
+```bash
+node bin/bid-pack.mjs pack --dir <bid-dir>
+```
+
+`pack` re-extracts the text from every rendered PDF/docx/xlsx and **re-runs the
+full audit on those bytes** — the gate applies to what the client will read.
+On pass it builds `pack/`, `submission-checklist.md`, `deadline.ics` and the
+zip. On fail it removes any stale pack so nothing half-finished can be
+submitted. Deliver the pack folder + checklist to the user.
+
+### After submission (opt-in, builds the moat)
+
+Record the bid under `library/bids/<ref-no>/` per `library/SCHEMA.md`
+(outcome + client feedback verbatim + rate band). This corpus is what makes
+rate bands real data instead of guesses.
+
+## Reference files — read on demand
+
+- `references/render-specs.md` — typography/structure for the four final PDFs.
+- `references/review-rules.md` — before showing the user any draft (checklist +
+  banned superlatives).
+- `references/pricing-standards.md` — before discussing rates (conventions,
+  loading/contingency norms).
+- `references/packs/<donor>.md` — when the client is UNDP, World Bank, EU-PRAG
+  or USAID: where their rules live, what to verify in the ToR.
+- `assets/templates.md` — letter, technical response, compliance rows, CV
+  bullet upgrade, clarification questions.
+
+## Advanced — step-by-step mode
+
+Every stage is still directly runnable (and exposed via MCP):
+
+```bash
+node bin/pdf-extract.mjs tor.pdf --out tor.txt            # 0. page-tagged text
+node bin/extract.mjs --tor tor.txt --out-dir out          # 1. screen + matrix
+node bin/dossier.mjs --client "UNOPS" --sector "M&E"      # 2. client intel
+node bin/cv-gap.mjs --tor tor.txt --cv cv.txt             # 3. MATCH / GAP
+node bin/market-rates.mjs scaffold --title "<t + ref>"    # 4a. research scaffold
+node bin/market-rates.mjs position --your-rate 450 ...    # 4b. band position
+node bin/pricing-model.mjs --base 400 --basis day ...     # 5. ⛔ gated on user
+node bin/cover-letter.mjs lint --draft letter.md --cv cv.txt  # 6. gate
+node bin/simulator.mjs --extract ... --response ...       # 7. coverage gate
+node bin/template-filler.mjs map|fill|check               # 8. client's forms
+node bin/audit.mjs --proposal final.md --matrix out/compliance-matrix.md  # 9. gate
+node bin/cv-tailor.mjs build | lint                       # CV generate/verify
+node bin/financial-proposal.mjs --pricing ... --extract ...   # financial doc
+node bin/render.mjs input.md --out output.pdf             # fallback PDFs
+node bin/package.mjs --dir <bid-dir> [--fallback-pdf]     # verify + zip
+node bin/profile.mjs init | set | get | path | erase      # consultant profile
+```
+
+`node bin/tor-to-proposal.mjs <command> --help` documents every one.
+
+## What you must never do
+
+- Quote a ToR requirement without its page.
+- Fill a `[FILL]` with anything the user did not supply or approve.
+- Mention a GAP skill anywhere in the proposal or tailored CV.
+- Ask the user ten small questions when one consolidated questionnaire exists.
+- Let an unaudited draft leave the session marked "ready to submit".
+- Present simulator output as a predicted evaluation score.
+- Build the pack while any verification fails — `pack` won't let you either.

package/assets/templates.md

@@ -0,0 +1,74 @@
+# Structure templates
+
+Formats the agent drafts into. `[FILL]` marks where user evidence is required;
+nothing else may occupy a `[FILL]` slot.
+
+## Cover letter (≤1 page — lint-enforced)
+
+```
+Dear [contact name/committee, p.X],
+
+RE: [exact assignment title] — Reference: [exact ref no.] (p.X)
+Deadline acknowledged: [submission deadline] (p.X)
+
+[UNDERSTANDING — 2 sentences, facts only from Background/Objectives, each tagged (p.X).]
+
+[FIT — one block per core competency from the JD:]
+Requirement (p.X): “[verbatim requirement]”
+[FILL: your matching evidence — quantified, traceable to CV §]
+
+[COMPLIANCE — validity per ToR (p.X); acceptance of GCCs / no-deviation clause (p.X);
+ registration status if required (p.X).]
+
+[AVAILABILITY per start date (p.X) + contact block.]
+
+Sincerely,
+[Name exactly as in CV + credentials]
+```
+
+## Technical response — one section per scored criterion
+
+```
+## [n]. [Criterion label, verbatim from the ToR evaluation grid] (p.X, [weight] pts)
+
+[Direct answer to every sub-element of this criterion, in the client's vocabulary.
+Each factual statement about the assignment carries (p.X); each statement about
+your experience carries [FILL] or CV-traceable evidence.]
+
+[Where the methodology is asked for: approach → steps → how each ToR
+ deliverable (p.X) is produced → quality control → sustainability.]
+```
+
+Ordering rule: highest weight first (unless the client's template fixes its own
+order — then their order wins and template-filler maps sections into it).
+
+## Compliance matrix row (generated by extract.mjs; complete each before audit)
+
+```
+| Requirement (verbatim, p.X) | p.X | Our response (2–3 lines / [FILL]) | Owner | Complete |
+```
+
+## CV bullet upgrade pattern (cv-gap suggestions follow this shape)
+
+```
+Before: “Responsible for M&E activities in the region.”
+After:  “[FILL: n] years leading M&E for [client names], covering [FILL: n]
+         evaluations in [FILL: countries]; produced [FILL: deliverable] used by
+         [FILL: client] for [FILL: decision].”   (numbers user-supplied only)
+```
+
+Terminology mirroring: if the ToR says "results framework", the CV bullet says
+"results framework" — not "logframe", not "M&E plan".
+
+## Clarification questions (send before the cutoff date, p.X)
+
+```
+Subject: Request for clarification — [ref no.] — [title]
+
+Q1. [Ambiguity in the ToR, quoted (p.X)] — please confirm whether [interpretation A or B].
+Q2. [Gap between deliverables (p.X) and effort estimate (p.X)] — please confirm the expected effort split.
+Q3. [Financial form field with no stated basis (p.X)] — please confirm whether [X] is included.
+```
+
+Every question must quote the ToR line it refers to. Never ask what the ToR
+already answers — that signals you did not read it.

package/bin/audit.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// audit: the pre-submission hard-fail gate. [FILL] leftovers, incomplete compliance
+// matrix, claim-shaped sentences with no trace. Exit 1 = do not submit yet.
+import { basename as path0 } from 'node:path';
+import { parseArgs, readText, writeOut, helpText } from './lib.mjs';
+
+const HELP = helpText('audit', [
+  'Usage: node bin/audit.mjs --proposal final.md --matrix compliance-matrix.md',
+  '            [--extras file.md ...] [--report audit-report.md]',
+  '',
+  'Hard fails: [FILL] remaining; matrix rows not Complete.',
+  'Review list: claim-shaped sentences (achievement verb + number) without',
+  '[[PAGE n]] / p.X / [FILL] / user-input / http trace.',
+]);
+
+const args = parseArgs(process.argv.slice(2));
+if (args.__help || !args.proposal) {
+  process.stdout.write(HELP);
+  process.exit(args.__help ? 0 : 1);
+}
+const files = [args.proposal, ...(args.extras ? [].concat(args.extras) : [])];
+const hard = [];
+const review = [];
+
+for (const file of files) {
+  const text = readText(file, 'proposal file');
+  const fills = [...text.matchAll(/\[FILL[^\]]*\]/g)];
+  if (fills.length) hard.push(`${path0(file)}: ${fills.length} [FILL] placeholder(s) remain — resolve every one before submission`);
+
+  const sentences = text
+    .split('\n')
+    .filter((l) => !l.trim().startsWith('#') && !l.trim().startsWith('|'))
+    .join(' ')
+    .split(/(?<=[.!?])\s+/);
+  sentences.forEach((s) => {
+    const clean = s.replace(/\s+/g, ' ').trim();
+    if (clean.length < 20 || clean.startsWith('|') || clean.startsWith('#')) return;
+    const claimish = /\b(led|delivered|managed|implemented|achieved|reduced|increased|trained|designed|coordinated|produced|authored|advised)\b/i.test(clean) && /\d|%/.test(clean);
+    if (!claimish) return;
+    if (/\[\[PAGE \d+\]\]|\bp\.\s?\d+\b|https?:\/\/|\[FILL|user[- ]input|\(user/i.test(clean)) return;
+    review.push(`${path0(file)}: “${clean.slice(0, 140)}${clean.length > 140 ? '…' : ''}” — claim-shaped, no trace (add [[PAGE n]], (p.X), source URL, or mark as user-input fact)`);
+  });
+}
+
+if (args.matrix) {
+  const matrix = readText(args.matrix, '--matrix');
+  const rows = matrix.split('\n').filter((l) => l.trim().startsWith('|') && !/^\|\s*[-:\s|]+\|/.test(l) && !/requirement/i.test(l.split('|')[1] ?? ''));
+  let incomplete = 0;
+  for (const r of rows) {
+    const cells = r.split('|').map((c) => c.trim());
+    const status = cells[cells.length - 2]; // last cell before trailing empty from split
+    if (status && !/^complete$/i.test(status) && cells.length > 3) incomplete++;
+  }
+  if (incomplete) hard.push(`${path0(args.matrix)}: ${incomplete} row(s) not marked Complete`);
+}
+
+const report = `# Audit report\n\n${hard.length ? `## HARD FAILS — do not submit\n${hard.map((h) => '- ' + h).join('\n')}` : '## HARD FAILS — none'}\n\n## Review list (citation-rule lint, human judgement required)\n${review.length ? review.map((r) => '- ' + r).join('\n') : 'none — no untraceable claim-shaped sentences found'}\n\nGate: fix every hard fail. Work the review list: each flagged sentence needs a page tag, a source, or removal.\n`;
+writeOut(args.report || 'audit-report.md', report);
+process.stdout.write(report);
+if (hard.length) process.exit(1);