# fix-md

**Repository Path**: simplelove520/fix-md

## Basic Information

- **Project Name**: fix-md
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# md-repair v6 (Audited Beta)

This directory contains the implemented and independently audited v6 formatter/recovery package. The v5-compatible formatter is stable; the optional v6 recovery path uses exact PDF word coordinates first and a local `wordfreq` Beam-DP segmenter only when a healthy PDF has no exact proposal for a candidate.

The current package is intentionally versioned `6.0.0-beta.1` and is **not release-ready**. Automated safety and performance gates pass, but strict automatic coverage is below the approved threshold and the required human review has not been completed. See `AUDIT_REPORT.md` and `work/md_v6/final_manifest.json`.

## Start here

1. Read `AGENTS.md` for authority, path mapping and hard safety boundaries.
2. Read `AUDIT_REPORT.md` for repaired defects, current evidence and remaining blockers.
3. Use `outputs/fix_md_v6_release_closure_implementation_plan.md` for the next developer work package.
4. Read the approved design and original plan under `outputs/` before changing behavior.
5. Use the commands below to reproduce the current result.

The architecture and implementation documents are intentionally preserved without path edits so their approved hashes remain verifiable. `AGENTS.md` maps their original absolute paths to this package.

## Inventory

| Path | Purpose | Modification policy |
|---|---|---|
| `outputs/fix_md_v5.py` | Backward-compatible v5 facade | Keep under 80 lines and preserve public symbols/defaults |
| `outputs/fix_md_v6.py` | v6 CLI entry point | Recovery behavior is explicit and fail-closed |
| `src/md_repair/` | Modular implementation | Core, recovery, ports and adapters follow the approved dependency direction |
| `tests/` | Unit, contract, architecture and integration tests | Current test inventory is derived into the final manifest |
| `outputs/fix_md_v6_architecture_design.md` | Approved architecture/PDF-first specification | Do not modify without human approval |
| `outputs/fix_md_v6_implementation_plan.md` | Developer-ready 17-task TDD plan | Treat interfaces and gates as fixed |
| `outputs/fix_md_v6_release_closure_implementation_plan.md` | 12-task plan for coverage, calibration, final review and release | Execute in order; experiments stay report-only until promoted |
| `outputs/fix_md_v5_design.md` | v5 compatibility behavior specification | Read-only reference |
| `outputs/fix_md_v5_implementation_plan.md` | Historical v5 implementation decisions | Read-only reference; v6 plan takes precedence |
| `work/md_v5_tests/test_fix_md_v5.py` | Portable 49-test legacy suite | Preserve as regression suite |
| `work/md_v5_tests/run_corpus_acceptance.py` | Portable full-book acceptance harness | Preserve gates; extend only as directed by v6 plan |
| `work/md_v5_tests/` | Golden outputs, candidate reports and historical evidence | Historical files are context, not current proof |
| `inputs/AI Engineering/AI Engineering.md` | Authoritative Markdown input | Never modify |
| `inputs/AI Engineering/images/` | 227 source images required by corpus gates | Never modify |
| `inputs/AI Engineering.pdf` | Authoritative 535-page PDF for coordinate recovery | Never modify |
| `reference/fix_md_v3.py` | Historical implementation baseline | Never modify |
| `VERIFIED_BASELINE.json` | Machine-readable verified hashes and metrics | Recheck before implementation |
| `work/md_v6/` | Current machine-readable corpus/performance/review evidence | Historical files are not proof until regenerated |
| `MANIFEST.sha256` | Integrity manifest for packaged files | Regenerate after intentional package updates |

## Reproduce the current verification

```bash
cd /Users/simplelove/Documents/AI/Code/md-repair-v6-handoff
shasum -a 256 -c MANIFEST.sha256
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m unittest -q work/md_v5_tests/test_fix_md_v5.py
.venv/bin/python work/md_v5_tests/run_corpus_acceptance.py
PYTHONPATH=src .venv/bin/python tests/corpus/run_recovery_acceptance.py
PYTHONPATH=src .venv/bin/python tests/corpus/benchmark_recovery.py
.venv/bin/python tests/corpus/generate_final_manifest.py
```

Expected current results:

- all manifest entries report `OK`;
- all 81 v6 tests pass;
- 49 legacy tests pass;
- the v5 corpus output ends with `ALL CORPUS GATES PASSED`;
- golden output SHA-256 is `38b978f923fe7f8fd6f301b39cc0f135f4caf2549aaf00e5708615aa1c3b8ce7`.
- v6 recovery acceptance exits 1 because the two coverage gates and human-review gate remain unmet;
- the performance harness passes with current measured peak RSS below 2 GiB;
- the generated final manifest remains `release_ready=false`.

## Important design facts

- `[pageN]` closes PDF page N; text after it and before `[pageN+1]` belongs to page N+1.
- Protected-region masks must preserve exact length and newlines so absolute offsets stay valid.
- PDF exact alignment is primary. `wordfreq` Beam-DP is candidate-level fallback only after healthy PDF alignment produces no approved proposal.
- Fuzzy PDF results and uncalibrated lexical proposals are report-only.
- Runtime external-model token use must remain zero.
- Architecture migration must preserve v5 output byte-for-byte before any recovery feature is added.

## Current audited measurements

- Python: 3.9.6
- v5 unit tests: 49/49 passing
- v6 test inventory: 81 passing
- source PDF: 535 pages
- images: 227 preserved and resolved
- HTML tables: 56 byte-identical
- recovery candidates: 12,210
- strict PDF automatic proposals: 6,680 (54.7%; required 80%)
- wordfreq automatic proposals: 0; calibrated policy is safely disabled
- combined automatic coverage: 54.7% (required 85%)
- full recovery benchmark: 218.137s; peak RSS 889,241,600 bytes
- human coordinate review: missing; use `work/md_v6/pdf_review_sample.json` and copy `work/md_v6/pdf_review_results.template.json` only after a real review
- v5 golden output: `38b978f923fe7f8fd6f301b39cc0f135f4caf2549aaf00e5708615aa1c3b8ce7`

Do not rename the template to `pdf_review_results.json` or fill passing counts without actually checking all sampled proposals against the PDF coordinates.