Bid Selection Memo

What it is

A synthetic portfolio demo that ingests a bid package, extracts cited requirements, reconciles addenda by version precedence, applies an explicit rules file and renders a cited memo. A server-side review gate refuses the consequential action until a reviewer approves. All documents and parties are invented.

What it does

• 82-second walkthrough video: ingestion to a cited HOLD memo; proceed is refused before approval.
• Outcome is computed only by the rules file over accepted facts; model claims must quote a whole sentence from the cited section.
• Version-precedence reconciliation keeps both citations when an addendum changes a requirement.
• Reviewed adversarially by two independent reviewers (OpenAI Codex and a separate Claude reviewer) in two rounds, per README.

The problem

An electrical bid package has a solicitation, addenda, a bid form and a scope narrative, and the deadline or cabling spec can change in a late addendum. A summarizing model can miss a bond gap or read an old version. This demo turns the package into a cited GO, HOLD or NO-GO memo that a person must approve before anything moves on.

Design decisions

• The outcome comes only from an explicit rules file over accepted facts, with no model in the decision. The tradeoff is that someone must write and maintain the rules.
• Later versions win over earlier ones by version number, not by arrival order, and both citations are kept. This handles an addendum that arrives last but also one that arrives out of order.
• A model claim is accepted only if its quote is a whole sentence of the cited section, and the value is parsed from that sentence by strict code. A model can add a HOLD but cannot remove a requirement the patterns recognise.
• Whether an unmet bond means HOLD or NO-GO is a contractor policy choice. The demo picks HOLD, and flipping one rule changes the result.

How it works

1. IngestReads each document with its ID, version and a SHA-256 hash.
2. ExtractorA rule-based extractor by default, or an optional model extractor, pulls requirements with a document, version, section and quoted sentence.
3. ReconcilerApplies version precedence and flags same-version conflicts.
4. Capability comparisonCompares requirements to the contractor profile for licenses, bonding and financial limits.
5. Rules engineMaps findings to GO, HOLD or NO-GO using the rules file, and lists fired and unfired rules.
6. Memo and review gateRenders a cited memo, and the server refuses Proceed until a reviewer approves with a rationale.

Security: enforced, simulated and known gaps

• Enforced in code: the review gate is checked server-side, including after a reset, with CSRF token and Origin checks, and Proceed is always refused against a NO-GO. The server binds to loopback only.
• Simulated: all documents, the project and the contractor are invented, and Proceed to bid prep is a stub that submits nothing.
• Known gaps: no sign-in, no audit log storage, review state is held in memory, no PDF or OCR input, and the model extractor has not been run against the live API in this repo.

What broke and how it was fixed

What broke

A literal citation did not make a parsed value correct. The text $4.2 million was read as $4, and a range was read as its lower bound.

How it was found

Two rounds of adversarial review, each by two reviewers (OpenAI Codex and a separate Claude reviewer), found these cases.

The fix

Values are now read only from one strict sentence format each, and anything else is flagged for a person as an unresolved item.

What guards it now

Each confirmed finding was reproduced as a failing test before it was fixed, which grew the suite from 31 to 125 tests.

Reference

399e1af

Where it runs

Runs locally on loopback with npm start. There is no hosted app. A walkthrough video is attached to the GitHub release.

Who did what

The owner conceived the product, architecture, specs and acceptance tests and directed the work. Coding agents (Claude, Codex, Gemini) did much of the implementation and review. The README credits Codex and a separate Claude reviewer for the review rounds. This is a synthetic portfolio demo, not client work.

Limits and honest status

• Synthetic portfolio demo; not a production system, a client specification or evidence of a customer deployment.
• No PDF or OCR parsing, no persistence (review state is in memory), no auth; 'proceed to bid prep' is a stub.
• The optional model extractor has not been exercised against the live API in this repo; the last fix was not re-reviewed independently.