AI says “done.” Deliverable Guard proves what actually passed.
Deliverable Guard turns user-approved acceptance rules into local, deterministic evidence for AI-generated office files. It catches missing files, cross-document ID conflicts, accidental source edits, unsafe ZIP submissions and broken Office/PDF structure—without uploading documents or asking an LLM to judge itself.
Most document tools answer “can this file be parsed?” Deliverable Guard answers “did the Agent satisfy the task, stay inside the allowed edit scope, and produce mutually consistent deliverables?”
- Acceptance contract: generated rules cannot run as a contract until a user confirms them.
- Cross-file discovery: finds repeated IDs, names, emails, phones, dates and amounts, then surfaces conflicts with hashes and locations.
- Protected sources: proves which input files changed and which remained byte-identical.
- Repair protocol: failed checks can emit machine-readable suggestions while the tool remains read-only.
- Evidence first: every verdict can be traced to files, locators, excerpts and SHA-256 values.
Deliverable Guard is an experimental local-only CLI and localhost UI. It is deliberately read-only: it reports evidence and never edits or submits user files.
- Required and forbidden files
- Required text in Markdown, text, DOCX, XLSX and PPTX
- PPTX slide counts and OpenXML package relationship validation
- Safe ZIP submission extraction and checking
- Required changes and required non-changes between source and output trees
- Regular-expression extraction with expected values
- Cross-file value consistency, including XLSX cell selectors
- Reliable PDF integrity, encryption, page-count and text checks through pinned
pypdf - SHA-256 evidence plus JSON and standalone HTML reports
- No runtime network calls, telemetry, LLM, macros or formula execution
This is a technical probe, not a compliance, accounting or factual-correctness guarantee.
git clone https://github.com/Crystal0101/deliverable-guard.git
cd deliverable-guard
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/deliverable-guard check \
--source examples/demo/source \
--output examples/demo/output \
--spec examples/demo/guard.toml \
--report-dir build/demo-reportThe demo intentionally returns exit code 1: it proves that a cross-file application-ID conflict was detected. See the complete three-minute walkthrough.
Install directly with pipx without cloning:
pipx install git+https://github.com/Crystal0101/deliverable-guard.gitStart a new rule file and inspect available checks:
deliverable-guard init
deliverable-guard explain
deliverable-guard explain same_value
deliverable-guard compare old-report.json new-report.json
deliverable-guard templates
deliverable-guard init --template presentation-pack-cn
deliverable-guard serve
deliverable-guard discover --output path/to/deliverables --report discovery.json --spec-output suggested.toml
deliverable-guard confirm suggested.toml --output contract.lock.json --confirmed-by "your-name"
deliverable-guard check --source source --output output --spec suggested.toml --contract-lock contract.lock.jsonserve starts a localhost-only, no-upload web interface at http://127.0.0.1:8765/.
Exit codes: 0 all checks pass; 1 at least one check fails or needs review; 2 invalid input/configuration.
discover deterministically finds repeated application IDs, applicant names, emails, phones, dates and amounts across supported files. It emits evidence-backed candidates and a draft TOML spec. confirm records an explicit reviewer identity, timestamp and SHA-256 binding in a separate lock file. Contract checks reject a missing, stale or tampered lock.
Failed deterministic checks may include a versioned, machine-readable repair object in JSON and HTML reports. It identifies the target, locator, precondition hash, allowed paths, expected/actual values and protected reference files; Deliverable Guard never applies the repair itself.
Add --privacy-mode to check or check-package before sharing a report. It removes absolute paths, excerpts, extracted values and reviewer identity while preserving verdicts, counts and evidence hashes.
Rules use Python 3.11's built-in TOML parser.
version = 1
[[checks]]
id = "report-present"
type = "required_file"
path = "report.docx"
[[checks]]
id = "contains-title"
type = "text_contains"
path = "report.docx"
value = "项目总结"
[[checks]]
id = "amount-cell"
type = "value_equals"
path = "summary.xlsx"
sheet = "汇总"
cell = "B2"
expected = "128.50"
[[checks]]
id = "same-applicant"
type = "same_value"
left = { path = "application.md", pattern = 'Applicant:\s*(.+)' }
right = { path = "profile.docx", pattern = 'Applicant:\s*(.+)' }
[[checks]]
id = "pdf-pages"
type = "pdf_pages"
path = "attachment.pdf"
min = 1
max = 3Paths must be relative and may not escape the output directory. Symlinks are not followed.
The formal configuration contract is available at schema/guard-spec.schema.json. Confirmation locks and repair suggestions are documented by schema/contract-lock.schema.json and schema/repair.schema.json.
- Scanned PDFs without an extractable text layer return
REVIEW; OCR is not included. - DOCX text extraction reads visible paragraph/table XML but does not render layout.
- XLSX formulas are inspected as stored formulas/cached values and never executed.
- PPTX text, slide count and OpenXML structure are supported, but visual layout is not rendered.
- Old binary
.doc/.xls, WPS-specific formats, OFD and OCR are out of the current scope.
Implemented today: deterministic checks, cross-file value comparison, source protection, evidence reports, safe ZIP input, Office/PDF readers, built-in templates and a localhost UI.
Planned rather than implemented: natural-language contract generation, automatic Agent repair, OCR and rendered-layout inspection. The discover command produces deterministic field candidates; it does not make semantic or factual judgments.