monthly-close-control-plane 0.1.1__tar.gz

monthly_close_control_plane-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Keep this project in its narrow role: a local, deterministic review-pack generator. No contribution should give it authority to post journals, make payments, lodge returns, lock periods, send reports, or approve a close.
+
+## Data boundary
+
+- Use fabricated fixtures. Keep client trial balances, subledgers, workpapers, review packs, credentials, `.env` files, tokens and screenshots from a live accounting system out of the repository.
+- Put fabricated CSV fixtures under `examples/` and header-only schema references under `schemas/`. The `.gitignore` blocks ordinary CSV files outside those two directories.
+- Treat source CSV content and review notes as untrusted input. Keep the fail-closed validation and the spreadsheet-formula safeguards in place.
+
+## Local verification
+
+Python 3.10 or newer. The repository uses `uv` and commits its lock file.
+
+```bash
+uv lock --check
+uv sync --locked --all-extras
+uv run pytest
+uv build
+```
+
+For a behaviour change, add or update a focused test under `tests/`. Keep the output deterministic: no wall-clock timestamps, client identifiers or hidden state in a review pack.
+
+## Pull requests
+
+Explain which control or boundary your change affects, include the test result, and name any operational limitation that remains. Never present a review acknowledgement as an approved or completed close.
+
+For a potential security vulnerability, follow [SECURITY.md](SECURITY.md), and keep credentials, client data and exploit details out of the issue tracker.

monthly_close_control_plane-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Duguid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monthly_close_control_plane-0.1.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include SECURITY.md
+include CONTRIBUTING.md
+recursive-include docs *.md
+recursive-include examples *.csv *.json
+recursive-include schemas *.csv

monthly_close_control_plane-0.1.1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: monthly-close-control-plane
+Version: 0.1.1
+Summary: A review-first monthly close control pack for validated trial-balance exports
+Author: Ryan Duguid
+License-Expression: MIT
+Keywords: accounting,month-end-close,reconciliation,xero,controls
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Monthly Close Control Plane
+
+[![tests](https://github.com/ryanduguid/monthly-close-control-plane/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/monthly-close-control-plane/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+A small, **review-first** monthly-close control pack for a validated trial-balance export. It turns current and prior period trial balances into deterministic integrity checks, variance exceptions, reconciliation exceptions, and a human-review pack.
+
+It is intentionally narrow:
+
+```text
+Validated trial-balance export
+            |
+            v
+Exact control gates and variance checks
+            |
+            v
+Explicit exception queue
+            |
+            v
+Human review and workpaper acknowledgement
+```
+
+The first MVP accepts the canonical CSV written by [xero-trial-balance-export](https://github.com/ryanduguid/xero-trial-balance-export). Each file must contain exactly one tenant and one report date; current and prior files must name the same tenant, and the prior date must be earlier. It does **not** connect to Xero, store OAuth tokens, write journals, make payments, lodge BAS, lock a period, distribute a client report, or claim that a close has been approved.
+
+## Why this exists
+
+A close can be technically balanced and still need review. This tool keeps the evidence visible:
+
+- Exact `Decimal` arithmetic for money controls, never binary floating point.
+- Schema, duplicate-key, date, and numeric gates fail closed.
+- Current-period and YTD debits must exactly equal credits.
+- Material YTD variances, new/missing accounts, account metadata changes, unmapped accounts, and supplied subledger differences become explicit exceptions.
+- A YTD variance is raised only when it clears both the absolute and the percentage threshold, with one carve-out: an account whose prior YTD balance is nil has no percentage change to compute, so the absolute threshold decides alone. Those exceptions name the absolute threshold only and leave `percentage_change` blank, rather than reporting that a percentage test passed that never ran.
+- Output has only `PASS`, `REVIEW`, and `BLOCKED` states. A reviewer, not the tool, decides whether a close is acceptable.
+- Source SHA-256 digests travel with the generated review pack so its source files can be identified later. Each digest is calculated from the same immutable byte snapshot the loader parses, so a file replaced during a run cannot be misidentified as the source of the calculations.
+- Spreadsheet-facing CSV text beginning with `=` is always neutralised with a leading apostrophe. `+`, `-` and `@` are neutralised unless the rest of the value is a plain identifier (word characters and dots, and not an A1-style cell reference), so an account code like `-1000` or an ID like `@123` stays joinable in Excel and Power BI, while `-A1` is quoted. That pass-through is narrow by construction, not a test for everything a spreadsheet can evaluate: `+unsafe` still passes through and reads as a defined name rather than as text, which costs display fidelity in that cell and calls nothing. Every payload that reaches outside the sheet carries a character the identifier test rejects. Text rendered into `close-summary.md` (reviewer-note text and every exception table cell) is flattened onto one line, and its backslashes are escaped before its pipes so that neither a pipe nor a backslash shielding one can add a cell and shift the columns a reviewer reads.
+- `exceptions.csv` is written with a UTF-8 byte-order mark, matching the canonical input files, so a spreadsheet reads non-ASCII entity and account names correctly.
+- The three pack files are staged beside their destinations and moved into place only once all three have been written. If one cannot be replaced (a reviewer holding `exceptions.csv` open is the usual cause), the files already moved are rolled back to the content they replaced, so the previous pack survives whole instead of half describing one trial balance and half describing another. A failed run never deletes a pack file it did not write. Run one export at a time into a given `--output` directory; concurrent runs are not serialised.
+- Amounts are rendered with at least two decimal places and never fewer than the value carries. A percentage is rendered with at least two places and always enough to show its leading significant digit, so neither a tolerance finer than one cent nor a threshold finer than a hundredth of a percent is flattened to `0.00`.
+
+## Quick demo
+
+The repository contains fabricated data only. Do not commit client trial balances, workpapers, exports, or credentials.
+
+```bash
+python -m pip install -e ".[dev]"
+
+close-control review \
+  --current examples/current_trial_balance.csv \
+  --prior examples/prior_trial_balance.csv \
+  --mapping examples/account_mapping.csv \
+  --subledger examples/subledger_balances.csv \
+  --absolute-threshold 10000 \
+  --percentage-threshold 0.10 \
+  --reconciliation-tolerance 0.01 \
+  --review-note examples/review_note.json \
+  --output outputs/demo
+```
+
+The demo exits `2` because its deliberately fabricated exceptions need human review. It writes:
+
+- `close-summary.md`: a concise, deterministic review pack.
+- `exceptions.csv`: filterable exception detail for Excel or Power BI.
+- `close-review-pack.json`: structured evidence, thresholds, source hashes, and any supplied review acknowledgement.
+
+Use exit code `0` only for an all-`PASS` pack, `2` for `REVIEW` or `BLOCKED`, and `1` for a malformed file, an invalid command configuration, or an `--output` path that cannot be written.
+
+## Canonical trial-balance contract
+
+The initial input is the ten-column, normalised trial-balance schema from `xero-trial-balance-export`:
+
+```text
+ReportDate,Tenant,Section,AccountID,AccountName,AccountCode,Debit,Credit,YTDDebit,YTDCredit
+```
+
+`Tenant` plus `AccountID` is the control key. `AccountCode` and `AccountName` are display attributes, not stable identifiers. The loader rejects unknown/missing columns, duplicate control keys, malformed ISO dates, empty identifiers, and malformed monetary values.
+
+The current-period `Debit`/`Credit` pair represents movement. `YTDDebit`/`YTDCredit` represents the position used for variance comparison. All values are read as exact decimals.
+
+## Optional mapping and reconciliation inputs
+
+An account mapping is a two-column CSV:
+
+```text
+AccountID,ReviewGroup
+```
+
+Any current TB account that is missing from a supplied mapping remains in the pack as a `REVIEW` exception. The mapping is a review label; it does not transform source numbers.
+
+An optional subledger CSV must have:
+
+```text
+Tenant,AccountID,SubledgerBalance
+```
+
+`SubledgerBalance` must use the same signed convention as `YTDDebit - YTDCredit`: debit balances positive; credit balances negative. Each supplied subledger row is compared only with the matching current TB account. A missing GL account, or a difference beyond `--reconciliation-tolerance`, requires review.
+
+## Human acknowledgement
+
+If a reviewer wants the pack to record that it was read, supply a separate JSON file:
+
+```json
+{
+  "reviewer_initials": "RD",
+  "reviewed_on": "2026-08-08",
+  "comment": "Reviewed demo exceptions; no client close was approved by this example."
+}
+```
+
+`reviewed_on` must not be earlier than the current `ReportDate`. A note dated before the period it claims to review is rejected as a malformed input: the run stops with exit `1` and writes no pack.
+
+An acknowledgement is evidence of a human action only. It **never** changes `REVIEW` or `BLOCKED` to `PASS`, and it never asserts that a period has been closed.
+
+## Data and operational boundaries
+
+- Use a separate, access-controlled working directory for client source files and outputs.
+- Keep this checkout limited to fabricated fixtures. Its `.gitignore` blocks CSVs outside `examples/` and `schemas/`, and blocks all three generated pack files by name wherever `--output` points them, including inside those two fixture directories.
+- Produce the source CSV through a read-only export workflow. Live Xero OAuth, token storage, and client authorisation are deliberately outside this MVP.
+- Do not use this as tax, financial, audit, or legal advice. It is a configurable review aid that requires professional judgement.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+The test suite covers schema gates, exact balancing, variance and metadata exceptions, mapping and subledger checks, deterministic pack generation, acknowledgement parsing, and the command-line exit contract.
+
+Continuous integration verifies the committed `uv.lock`, runs the test suite on Python 3.10, 3.11, 3.12, and 3.13, then builds and smoke-tests the wheel with the fabricated demo. CodeQL scans the Python source, and Dependabot is configured to propose updates for `uv` dependencies and pinned GitHub Actions. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local verification and data-handling requirements.
+
+## Roadmap
+
+The next layers are deliberately separated from the control engine:
+
+1. A safe, read-only Xero AI review gateway with a defined query allowlist, redaction boundary, source evidence, and no mutation tools.
+2. A tax-change impact monitor that records authoritative source versions, produces drafts for human review, and never turns legislation changes into an automatic client conclusion.
+
+See [docs/follow-on-safety-layers.md](docs/follow-on-safety-layers.md) for the intended boundary contracts.
+
+Built with AI assistance (Claude); design, review, and testing by the author.
+
+MIT licensed.

monthly_close_control_plane-0.1.1/README.md

@@ -0,0 +1,143 @@
+# Monthly Close Control Plane
+
+[![tests](https://github.com/ryanduguid/monthly-close-control-plane/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/monthly-close-control-plane/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+A small, **review-first** monthly-close control pack for a validated trial-balance export. It turns current and prior period trial balances into deterministic integrity checks, variance exceptions, reconciliation exceptions, and a human-review pack.
+
+It is intentionally narrow:
+
+```text
+Validated trial-balance export
+            |
+            v
+Exact control gates and variance checks
+            |
+            v
+Explicit exception queue
+            |
+            v
+Human review and workpaper acknowledgement
+```
+
+The first MVP accepts the canonical CSV written by [xero-trial-balance-export](https://github.com/ryanduguid/xero-trial-balance-export). Each file must contain exactly one tenant and one report date; current and prior files must name the same tenant, and the prior date must be earlier. It does **not** connect to Xero, store OAuth tokens, write journals, make payments, lodge BAS, lock a period, distribute a client report, or claim that a close has been approved.
+
+## Why this exists
+
+A close can be technically balanced and still need review. This tool keeps the evidence visible:
+
+- Exact `Decimal` arithmetic for money controls, never binary floating point.
+- Schema, duplicate-key, date, and numeric gates fail closed.
+- Current-period and YTD debits must exactly equal credits.
+- Material YTD variances, new/missing accounts, account metadata changes, unmapped accounts, and supplied subledger differences become explicit exceptions.
+- A YTD variance is raised only when it clears both the absolute and the percentage threshold, with one carve-out: an account whose prior YTD balance is nil has no percentage change to compute, so the absolute threshold decides alone. Those exceptions name the absolute threshold only and leave `percentage_change` blank, rather than reporting that a percentage test passed that never ran.
+- Output has only `PASS`, `REVIEW`, and `BLOCKED` states. A reviewer, not the tool, decides whether a close is acceptable.
+- Source SHA-256 digests travel with the generated review pack so its source files can be identified later. Each digest is calculated from the same immutable byte snapshot the loader parses, so a file replaced during a run cannot be misidentified as the source of the calculations.
+- Spreadsheet-facing CSV text beginning with `=` is always neutralised with a leading apostrophe. `+`, `-` and `@` are neutralised unless the rest of the value is a plain identifier (word characters and dots, and not an A1-style cell reference), so an account code like `-1000` or an ID like `@123` stays joinable in Excel and Power BI, while `-A1` is quoted. That pass-through is narrow by construction, not a test for everything a spreadsheet can evaluate: `+unsafe` still passes through and reads as a defined name rather than as text, which costs display fidelity in that cell and calls nothing. Every payload that reaches outside the sheet carries a character the identifier test rejects. Text rendered into `close-summary.md` (reviewer-note text and every exception table cell) is flattened onto one line, and its backslashes are escaped before its pipes so that neither a pipe nor a backslash shielding one can add a cell and shift the columns a reviewer reads.
+- `exceptions.csv` is written with a UTF-8 byte-order mark, matching the canonical input files, so a spreadsheet reads non-ASCII entity and account names correctly.
+- The three pack files are staged beside their destinations and moved into place only once all three have been written. If one cannot be replaced (a reviewer holding `exceptions.csv` open is the usual cause), the files already moved are rolled back to the content they replaced, so the previous pack survives whole instead of half describing one trial balance and half describing another. A failed run never deletes a pack file it did not write. Run one export at a time into a given `--output` directory; concurrent runs are not serialised.
+- Amounts are rendered with at least two decimal places and never fewer than the value carries. A percentage is rendered with at least two places and always enough to show its leading significant digit, so neither a tolerance finer than one cent nor a threshold finer than a hundredth of a percent is flattened to `0.00`.
+
+## Quick demo
+
+The repository contains fabricated data only. Do not commit client trial balances, workpapers, exports, or credentials.
+
+```bash
+python -m pip install -e ".[dev]"
+
+close-control review \
+  --current examples/current_trial_balance.csv \
+  --prior examples/prior_trial_balance.csv \
+  --mapping examples/account_mapping.csv \
+  --subledger examples/subledger_balances.csv \
+  --absolute-threshold 10000 \
+  --percentage-threshold 0.10 \
+  --reconciliation-tolerance 0.01 \
+  --review-note examples/review_note.json \
+  --output outputs/demo
+```
+
+The demo exits `2` because its deliberately fabricated exceptions need human review. It writes:
+
+- `close-summary.md`: a concise, deterministic review pack.
+- `exceptions.csv`: filterable exception detail for Excel or Power BI.
+- `close-review-pack.json`: structured evidence, thresholds, source hashes, and any supplied review acknowledgement.
+
+Use exit code `0` only for an all-`PASS` pack, `2` for `REVIEW` or `BLOCKED`, and `1` for a malformed file, an invalid command configuration, or an `--output` path that cannot be written.
+
+## Canonical trial-balance contract
+
+The initial input is the ten-column, normalised trial-balance schema from `xero-trial-balance-export`:
+
+```text
+ReportDate,Tenant,Section,AccountID,AccountName,AccountCode,Debit,Credit,YTDDebit,YTDCredit
+```
+
+`Tenant` plus `AccountID` is the control key. `AccountCode` and `AccountName` are display attributes, not stable identifiers. The loader rejects unknown/missing columns, duplicate control keys, malformed ISO dates, empty identifiers, and malformed monetary values.
+
+The current-period `Debit`/`Credit` pair represents movement. `YTDDebit`/`YTDCredit` represents the position used for variance comparison. All values are read as exact decimals.
+
+## Optional mapping and reconciliation inputs
+
+An account mapping is a two-column CSV:
+
+```text
+AccountID,ReviewGroup
+```
+
+Any current TB account that is missing from a supplied mapping remains in the pack as a `REVIEW` exception. The mapping is a review label; it does not transform source numbers.
+
+An optional subledger CSV must have:
+
+```text
+Tenant,AccountID,SubledgerBalance
+```
+
+`SubledgerBalance` must use the same signed convention as `YTDDebit - YTDCredit`: debit balances positive; credit balances negative. Each supplied subledger row is compared only with the matching current TB account. A missing GL account, or a difference beyond `--reconciliation-tolerance`, requires review.
+
+## Human acknowledgement
+
+If a reviewer wants the pack to record that it was read, supply a separate JSON file:
+
+```json
+{
+  "reviewer_initials": "RD",
+  "reviewed_on": "2026-08-08",
+  "comment": "Reviewed demo exceptions; no client close was approved by this example."
+}
+```
+
+`reviewed_on` must not be earlier than the current `ReportDate`. A note dated before the period it claims to review is rejected as a malformed input: the run stops with exit `1` and writes no pack.
+
+An acknowledgement is evidence of a human action only. It **never** changes `REVIEW` or `BLOCKED` to `PASS`, and it never asserts that a period has been closed.
+
+## Data and operational boundaries
+
+- Use a separate, access-controlled working directory for client source files and outputs.
+- Keep this checkout limited to fabricated fixtures. Its `.gitignore` blocks CSVs outside `examples/` and `schemas/`, and blocks all three generated pack files by name wherever `--output` points them, including inside those two fixture directories.
+- Produce the source CSV through a read-only export workflow. Live Xero OAuth, token storage, and client authorisation are deliberately outside this MVP.
+- Do not use this as tax, financial, audit, or legal advice. It is a configurable review aid that requires professional judgement.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+The test suite covers schema gates, exact balancing, variance and metadata exceptions, mapping and subledger checks, deterministic pack generation, acknowledgement parsing, and the command-line exit contract.
+
+Continuous integration verifies the committed `uv.lock`, runs the test suite on Python 3.10, 3.11, 3.12, and 3.13, then builds and smoke-tests the wheel with the fabricated demo. CodeQL scans the Python source, and Dependabot is configured to propose updates for `uv` dependencies and pinned GitHub Actions. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local verification and data-handling requirements.
+
+## Roadmap
+
+The next layers are deliberately separated from the control engine:
+
+1. A safe, read-only Xero AI review gateway with a defined query allowlist, redaction boundary, source evidence, and no mutation tools.
+2. A tax-change impact monitor that records authoritative source versions, produces drafts for human review, and never turns legislation changes into an automatic client conclusion.
+
+See [docs/follow-on-safety-layers.md](docs/follow-on-safety-layers.md) for the intended boundary contracts.
+
+Built with AI assistance (Claude); design, review, and testing by the author.
+
+MIT licensed.

monthly_close_control_plane-0.1.1/SECURITY.md

@@ -0,0 +1,22 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the latest version on the default branch.
+
+## Reporting a vulnerability
+
+Please use this repository's private vulnerability-reporting feature. Do not
+open a public issue for a suspected security vulnerability. Include a clear
+description, reproduction steps, impact, and any suggested mitigation.
+
+We will acknowledge a valid report within seven days and will coordinate a fix
+and disclosure timeline with the reporter.
+
+## Data boundary
+
+This repository ships fabricated fixtures only. It deliberately has no Xero credential, API client, MCP server, LLM client, journal-posting path, payment path, BAS/lodgment path, email path, or period-locking path.
+
+Do not commit client trial balances, subledgers, workpapers, credentials, `.env` files, or generated review packs. The `examples/` folder (fabricated fixtures) and the `schemas/` folder (header-only schema references) are the only places CSVs belong in this source tree. Use a separate access-controlled working location for real data.
+
+The optional review note records a human acknowledgement only. It does not approve a close or replace professional judgement.

monthly_close_control_plane-0.1.1/closecontrol/__init__.py

@@ -0,0 +1,5 @@
+"""Review-first controls for a monthly trial-balance close."""
+
+from .engine import CloseReviewPack, review_close
+
+__all__ = ["CloseReviewPack", "review_close"]

monthly_close_control_plane-0.1.1/closecontrol/cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+
+from .engine import review_close
+from .errors import ControlInputError
+from .report import PACK_FILE_NAMES as _PACK_FILE_NAMES, write_review_pack
+
+
+def _non_negative_decimal(value: str) -> Decimal:
+    try:
+        result = Decimal(value)
+    except InvalidOperation as exc:
+        raise argparse.ArgumentTypeError(f"not a decimal: {value!r}") from exc
+    if not result.is_finite() or result < 0:
+        raise argparse.ArgumentTypeError("must be a finite non-negative decimal")
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Create a review-first monthly close control pack from validated trial-balance exports.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    review = commands.add_parser("review", help="run integrity, variance, mapping, and optional reconciliation controls")
+    review.add_argument("--current", required=True, type=Path, help="current-period canonical trial-balance CSV")
+    review.add_argument("--prior", required=True, type=Path, help="prior-period canonical trial-balance CSV")
+    review.add_argument("--mapping", type=Path, help="optional AccountID,ReviewGroup mapping CSV")
+    review.add_argument("--subledger", type=Path, help="optional Tenant,AccountID,SubledgerBalance CSV")
+    review.add_argument("--review-note", type=Path, help="optional human acknowledgement JSON")
+    review.add_argument("--output", required=True, type=Path, help="directory for the generated review pack")
+    review.add_argument("--absolute-threshold", type=_non_negative_decimal, default=Decimal("1000"), help="minimum absolute YTD variance for review")
+    review.add_argument("--percentage-threshold", type=_non_negative_decimal, default=Decimal("0.10"), help="minimum proportional YTD variance for review, e.g. 0.10")
+    review.add_argument("--reconciliation-tolerance", type=_non_negative_decimal, default=Decimal("0.01"), help="maximum permitted GL/subledger difference")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # argparse exits with 2 on usage errors, but this tool's exit contract
+        # reserves 2 for a pack needing review; remap usage errors to 1.
+        # --help and -h exit with 0 and must keep doing so, so re-raise
+        # anything that is not a usage error.
+        if exc.code == 2:
+            return 1
+        raise
+    if args.command != "review":  # pragma: no cover - argparse currently has one subcommand.
+        parser.error("unknown command")
+    # write_review_pack replaces its three destinations and deletes what it
+    # parked aside. If a source file IS one of those destinations, that source
+    # is destroyed and the pack still records a source_sha256 for it, so the
+    # provenance chain points at evidence that no longer exists. Refuse before
+    # anything is read or written. resolve() so case, "." segments and symlinks
+    # normalise to one key; the destinations need not exist yet.
+    destinations = {(args.output / name).resolve() for name in _PACK_FILE_NAMES}
+    for flag, source in (
+        ("--current", args.current),
+        ("--prior", args.prior),
+        ("--mapping", args.mapping),
+        ("--subledger", args.subledger),
+        ("--review-note", args.review_note),
+    ):
+        if source is not None and source.resolve() in destinations:
+            print(
+                f"close-control: output error: {flag} {source} is inside --output and "
+                f"shares a generated pack file name; the run would destroy it.",
+                file=sys.stderr,
+            )
+            return 1
+    try:
+        pack = review_close(
+            current_path=args.current,
+            prior_path=args.prior,
+            mapping_path=args.mapping,
+            subledger_path=args.subledger,
+            acknowledgement_path=args.review_note,
+            absolute_threshold=args.absolute_threshold,
+            percentage_threshold=args.percentage_threshold,
+            reconciliation_tolerance=args.reconciliation_tolerance,
+        )
+    except (ControlInputError, ValueError) as exc:
+        print(f"close-control: input error: {exc}", file=sys.stderr)
+        return 1
+    try:
+        outputs = write_review_pack(pack, args.output)
+    except (OSError, ValueError) as exc:
+        # An unusable --output is a caller error, not a crash: report it on the
+        # same failure path as a malformed input instead of a raw traceback.
+        # ValueError covers a render that cannot be encoded, which is not an
+        # OSError and used to escape as a traceback.
+        print(f"close-control: output error: {exc}", file=sys.stderr)
+        return 1
+    print(f"close-control: {pack.status}; {len(pack.exceptions)} exception(s)")
+    for name, path in outputs.items():
+        print(f"  {name}: {path}")
+    return 0 if pack.status == "PASS" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())