Milestones

Goal: create and verify a fresh development environment using the same Conda workflow as the computer-vision course, installing only what ScanReady needs.

Result: passed September 26.

• Python 3.11 environment named scanready, with pinned OpenCV, NumPy, Pillow, pypdfium2, pandas, Matplotlib, Streamlit, PyYAML and pytest.
• All imports verified in one process; pip check clean.
• TensorFlow, Keras and YOLO, which appear elsewhere in the course, were deliberately left out. This project is classical OpenCV and the offline bundle had to stay small.
• Later packaging work changed two versions (OpenCV 4.6.0.66 and pypdfium2 4.30.0), the newest releases with wheels for both Intel and Apple Silicon Macs.

Goal: a deterministic, testable intake and analysis engine for JPEG, PNG and first-page PDF input that returns one fixed outcome for every accepted document.

Result: complete, built test-first.

• Files are identified by their contents, not their extension. Corrupt, encrypted, oversized and unsupported files fail with readable messages instead of crashes.
• The original file is never changed. PDFs are analyzed on page 1 only, at up to 200 DPI.
• Six checks run on every document. All thresholds live in one config file, thresholds.yaml.
• Decision rule: any failure that can’t be fixed means RETRY CAPTURE; any fixable failure means READY AFTER CORRECTION; otherwise READY. Warnings never change the outcome.
• An independent review found six issues. Each got a failing test first, then a fix. Sprint gate: 26 tests passing.

Goal: turn the analysis engine into a complete local app with evidence overlays, safe corrections, re-checks and a Streamlit interface.

Result: complete and verified.

• Corrections (deskew, lighting, contrast) are offered only for failures that can be fixed. They always work on a copy.
• Straightening uses a larger canvas so no content is cut off.
• The app previews the image, shows one decision banner and all six checks, and puts the original and corrected images side by side.
• Corrected pages download as a new PNG. An uploaded PDF is never modified.
• A completion review found six gaps, all fixed. Sprint gate: 41 tests passing. A 12-megapixel image analyzed in 0.11 seconds, against a 10-second limit.

Goal: build an auditable dataset pipeline, tune only on calibration data, and report honest held-out performance against the project’s acceptance bar.

Result: pipeline complete; the evaluation fell short of the bar, and that’s disclosed.

• Raw files are never changed. Normalized copies are stripped of EXIF and GPS metadata.
• Images are split by source page, so no page appears in both the calibration and held-out sets. The calibration code cannot open held-out data.
• Real data arrived as 200 public Kaggle scans and 22 phone photos. Calibration exposed false alarms for glare, crop and contrast. Each fix got its own regression test.
• The public scans are clean, so the held-out set had no labeled defect examples. The final evaluation is 47 scans at 61.7% accuracy, against an 80% target. Nothing was tuned on held-out results.

Goal: a launcher, setup scripts and a release builder that produce one self-contained zip that runs offline.

Result: complete.

• First run installs into a private .runtime folder. Later runs reuse it only if its lock hashes still match.
• No administrator rights, and no changes to PATH, the registry or shell profiles.
• Bundled Python runtimes and wheels for Windows x64, macOS Intel, macOS Apple Silicon and Linux x86_64, each pinned by SHA-256.
• The release builder works from an explicit list of allowed files. It rejects missing, extra or unsafe files, symlinks, image metadata and oversized archives.
• Verified on Windows: a first run creates the runtime, and a second run reuses it and shuts down cleanly.

Goal: settle the open questions blocking release, then build a candidate.

A review by Astra (a GPT-6 model, run through the Codex VS Code extension) turned the open items into eight recorded decisions, D1–D8:

• disclose the data shortfall rather than invent labels;
• keep generated image variants unscored;
• defer a detector redesign;
• use a separately named population of 184 eligible scans (137 calibration, 47 held-out);
• build an honestly labeled candidate rather than claim qualification.

Tasks A1–A7 then ran one per worker round, each recorded in the progress log. They covered truthful generation, a real correctable demo, a calibration baseline, the evaluation population, the held-out report, documentation, and the build and verification of the archive.

For A7, Codex built and verified the development archive, then hit a usage limit before recording its work. Claude Opus 5.5 picked up from the files, re-verified the archive and closed out the task.

Goal: fix what hands-on UI testing turned up, then rebuild for a real deployment test.

The hands-on test confirmed that all three demos, straightening, downloads, JPG, PNG and PDF uploads, and the Evaluation Results tab worked. It also found problems to fix:

• Evidence overlay: lines overlapped, labels collided, and the text was hard to read. Rebuilt with measured spacing, a readable font, white text on a dark panel and coloured PASS/WARN/FAIL tags, plus a test that catches overlaps.
• Corrections: a correction that doesn’t improve its own check is now skipped and explained. A “What changed” list flags anything that got worse.
• Advisories: sideways pages get a note and a rotate button. Non-document images get a note. Neither changes the verdict.

Deployment test (A8), on Windows 11 Pro and macOS: setup, launch, all three demos, correction and download, PNG, single- and multi-page PDF (first page only), and oversized-file rejection.

Goal: polish what ships, rebuild, and confirm the exact file being submitted.

• Decision D9: the evaluation shortfall was accepted as the documented cut line. Results are labeled “Evaluated with disclosed shortfalls”, with the failure list still visible. Adding 3,292 more clean scans was considered and declined: it would add no defect examples.
• Example evidence images added to the results. A macOS browser-launch fix. Future work reorganized.
• Final gates: 178 automated tests passing (6 platform skips), self-test, all three demos, a smoke test, and a 48-point audit of the archive.
• Final archive: 489 files. Re-tested on Windows and macOS before submission on September 28.