Skip to content

PROJECT-SCOPE.md

Latest commit

 

History

History
126 lines (98 loc) · 5.25 KB

PROJECT-SCOPE.md

File metadata and controls

126 lines (98 loc) · 5.25 KB
Raw

Project Scope

Last reviewed: 2026-07-22. Base branch: main.

This file is a plain-language map of the project as it exists on main. It does not replace the README, roadmap, audit docs, or source comments. It points to them so a reviewer can see the whole shape without reading every file first.

What This Project Is

Outcome Receipts creates grounded reports from service data. It connects narrative claims, charts, definitions, comparisons, and provenance so readers can trace where each number came from.

Package metadata checked in this pass:

  • Python package outcome-receipts for Python >=3.12.

Who It Serves

  • Nonprofits writing grant, board, or impact reports from service CSVs.
  • Funders and reviewers who want numbers tied back to definitions and source data.
  • Maintainers building no-model reporting workflows with verifiable outputs.

What It Covers

  • A Python library and CLI for report config, drafting, charts, comparisons, provenance, trace, and verification.
  • A digest-pinned, non-root container for the same offline CLI.
  • Examples for board, grant, and housing reports.
  • Docs for roadmap, user research, decisions, audits, and I18N.
  • Evaluation reports and tests for definitions, grounding, traces, reports, and verification.
  • Config-driven receipts that can be checked after generation.
  • Six bounded evidence workflows for restatement, migration, requirement change, contract milestones, partner rollup, and equity review.
  • Published 1.0 contracts for report specs, receipts manifests, and workflow artifacts.

How It Is Put Together

  • src/outcome_receipts/ contains the deterministic metric engine (engine.py), the receipt and spec models (models.py), the fail-closed grounding gate (grounding.py), config loading, the template drafter, charts, period comparison, provenance, the trace view, report export, the hash-chained export ledger (ledger.py), the spec scaffolder, report and workflow verification (verify.py, workflows.py), the eval harness, and the CLI.
  • examples/ contains small report inputs.
  • docs/adr/ is the canonical decision log; docs/decisions/ preserves the pre-migration grounding, templates, comparison, and trace choices.
  • eval/ contains report material.
  • tests/ checks the report and verification behavior.

Observed source and operations surfaces:

  • Makefile
  • eval/
  • pyproject.toml
  • src/

GitHub workflow files checked:

  • .github/workflows/ci.yml
  • .github/workflows/release.yml

Trust Boundaries

  • Every number in a report must trace to a receipt (the exact query, row count, and a hash of the data slice). The grounding gate is fail-closed: a number without a receipt blocks the export instead of passing through.
  • No number comes from a model. The deterministic engine computes every figure; the optional drafting seam (v0.3, off by default) only writes prose around already-receipted figures.
  • Verification is part of the output contract: receipts verify re-derives every figure from the spec and cited data, while receipts verify-workflow validates workflow versions, relationships, digests, aggregate-only fields, and receipt-composed lineage. Each export appends to a hash-chained ledger so the reporting history is tamper-evident.
  • A derived workflow value is labeled receipt_composed; it cannot be mistaken for a row-backed receipt. Rollups verify every partner bundle and reject suppressed inputs.

Outside This Scope

  • It does not decide whether a program worked.
  • It cannot fix bad source data or missing definitions.
  • Human sign-off is still needed before sending a report to funders or a board.

Docs And Evidence Checked

The repository inventory is enforced by scripts/check_conformance.py, schema tests, generated-artifact drift checks, and source hygiene checks. Vendored provider licenses, dependency folders, and generated caches are excluded.

Primary docs checked:

  • CHANGELOG.md
  • CITATION.cff
  • CLAUDE.md
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • LICENSE
  • NOTICE
  • README.md
  • SECURITY.md
  • docs/I18N.md
  • docs/RESEARCH-ROADMAP.md
  • docs/RESPONSIBLE-TECH-AUDITS.md
  • docs/ROADMAP.md
  • docs/THREAT-MODEL.md
  • docs/USER-RESEARCH.md
  • docs/decisions/0000-record-architecture-decisions.md
  • docs/decisions/0001-engine-receipts-grounding.md
  • docs/decisions/0002-templates-charts-comparison.md
  • docs/decisions/0003-definitions-provenance-trace-verify.md
  • docs/decisions/0004-hash-chained-export-ledger.md
  • eval/report.md

Representative test files checked:

  • tests/test_charts.py
  • tests/test_comparison.py
  • tests/test_config_sections.py
  • tests/test_data_checks.py
  • tests/test_definition.py
  • tests/test_draft_and_config.py
  • tests/test_engine.py
  • tests/test_evaluate.py
  • tests/test_grounded_sections.py
  • tests/test_grounding_gate.py
  • tests/test_grounding_locale.py
  • tests/test_kind.py
  • tests/test_ledger.py
  • tests/test_provenance.py
  • tests/test_report_sections.py
  • tests/test_scaffold.py
  • tests/test_trace.py
  • tests/test_verify.py

Validation Notes

Validation is the complete make verify gate: lint, strict typing, tests and coverage, documentation/source hygiene, localization, security scans, accessibility, generated cards and eval, compatibility fixtures, and locked-down container verification.