modules/open-item-reconciliation/skills/open-item-reconciliation/SKILL.md

---
name: open-item-reconciliation
description: Use when a user has a population reported as open at a cut-off and wants Codex to determine which items are closed, partly closed, or still open from ledgers, journals, bank statements, payment orders, factoring or advance evidence, and compensation evidence, then produce reviewable Excel and Word workpapers. Do not use for direct bank-statement-to-journal matching; use journal-bank-reconciliation for that task. This is a Codex workflow plugin, not a standalone CLI.
---

## Output Location Rule

Never write run outputs inside this Git workspace or a published folder. Use
only the Studio Archive client/engagement run path described below; never
choose a sibling output folder.

# Open-item Reconciliation

## Jurisdiction and Geneva

For a CH-GE mandate, read `references/geneva.md` before the steps below. It specifies the Geneva input, source and output adaptations within this existing function. Choose governing jurisdiction independently of output language; the ordinary Italian path remains available for IT.


Use this skill when the starting population is a list of items reported as open
at a cut-off. Determine which items are closed, partly closed, or still open
from the available accounting evidence, then document residuals, exceptions,
and missing support. Ledgers, journals, bank statements, payment batches,
factoring or advance records, and compensation evidence support that test; they
do not replace the required open-item population.

If the starting population is instead the movements in a bank statement and
the task is to match them directly to journal or ledger entries, use
`journal-bank-reconciliation`.

The plugin is a **Codex workflow plugin**. Helper scripts are deterministic support code; Codex remains responsible for inspecting the folder, asking for missing assumptions, running the workflow, reviewing the output, and explaining limitations.

## Codex-Native Run UX

Before running helper scripts or write-heavy work, identify material choices that would change execution: problem framing, decision angle, risk appetite, scope boundaries, audience, evidence posture, mappings, cut-off, OCR, notification, or review assumptions. Reuse choices already established in the conversation or bound case records. Ask only for unresolved material choices and wait before their dependent work; continue independent authorized preparation. Generate choices from the actual inputs; do not offer named frameworks, regulators, document types, output packages, or issue categories unless the facts cue them or the user must supply a missing custom value. Do not infer missing required evidence, approval, or a material business decision. State routine provisional assumptions when the workflow permits them.

Default output policy: produce the richest normal package for the workflow. DOCX/Word, Excel/CSV, JSON audit, diagnostics, charts, packaged reports, review notes, and Codex-written review files are not choices to propose when they are natural outputs of that plugin; generate them whenever dependencies and source data permit. Ask only when an output is technically impossible, unsafe, or the user explicitly requests a reduced/debug run.

Currency: carry the currency evidenced by the source or confirmed for the engagement (including CHF). Never infer currency from output language or silently default to EUR. If unresolved, obtain the currency before computing or matching amounts. Keep different currencies separate; conversion requires an explicit reviewed rate, date and basis.

Keep progress and handoff concise. Use a checklist, Run Intake table, Decision
Table, or Artifact Card when it helps the user review complex work; their chat
format is optional. Preserve all required saved mappings, review decisions,
validation records, and artifacts. Resolve material choices before dependent
execution and continue independent authorized work while awaiting an answer.
Obtain authorization for external, destructive, or approval-sensitive actions
when not already given, and preserve workflow-specific approval gates.
At delivery, link outputs and state their purpose, review status, unresolved
items, and next action. Create `codex_run_review.md` when a durable review index
is useful; never edit plugin source or generated ZIPs during a user-data run.

## Beta Positioning

Present the plugin as one vertical professional workflow:

```text
Test a reported open-item population against ledger, bank, payment,
factoring/advance, and compensation evidence, then show which items are
closed, partly closed, or still open in reviewable Excel/Word workpapers.
```

Do not present it as a generic accounting chatbot, a standalone app, or an MCP/API service. The user experience should feel like a guided Codex run: inspect the folder, confirm assumptions, run deterministic helpers, review exceptions, and deliver workpapers with clear limitations.

## Source Rule

For development, the repo source is the only editable source:

```text
plugins/open-item-reconciliation
```

Do not edit downloaded plugin folders, ZIP contents, or Codex cache copies as source.

Filename and text keyword matches are source-role suggestions only. Before raw
ingestion, Codex must record one `reviewed_source_decisions` entry per current
source. Each entry contains the reviewed role, adapter family, reviewer
identity/date, accounting perimeter, cent-only monetary convention
(`reported_increment: "0.01"`), and `date.order` (`day_first` or
`month_first`). The v2 decision and one qualification carrying its
`reviewed_mapping_ref` are bound to exactly one current-byte source receipt.
Plain `reviewed_source_roles` or
`reviewed_source_adapters` maps are not authority. Ambiguous or unreviewed files
abstain and surface `needs_review`; unsupported layouts surface
`unsupported_source_layout` and emit no accounting rows. The legacy Italian
PDF/print-export parser may be named only inside this reviewed decision with
adapter `legacy_it_accounting_export_v1`; do not ask the user to edit plugin
files.

Every `reviewer_ref` is an unsigned, unauthenticated, untrusted label. Its
canonical syntax and sealed bytes do not prove the reviewer's identity or
authorization.

## Core Principle

Deterministic code is the authority for row-level classifications.

Codex/model review is a quality-control layer. It may find issues, identify missed patterns, or propose rule changes, but it must not silently override deterministic results. If review finds a material error, fix the deterministic rule, rerun, and regenerate outputs.

## Required Questions

Ask only what is needed. If not obvious, ask for:

- input folder;
- year or cut-off date;
- working language and source-document language;
- which file is the population reported as open at the cut-off;
- which files are ledgers, journals, bank statements, payment orders, factoring/operator evidence, or compensation support;
- whether post-cut-off events are excluded;
- whether payment orders are only bridge documents or can be treated as evidence;
- whether compensation requires bank evidence or documented accounting support is sufficient.

Default factoring treatment: when a factor/operator or pro-soluto bridge is tied
deterministically to a bank-statement payment from the bank files provided, treat
that as closing evidence. Do not run a second conservative pass that disables
factoring/advance closure merely because the user did not explicitly confirm
the default. Ask only when the user wants factoring/advance references to be
treated as non-closing, or when the link to the bank statement is ambiguous.
Treat that request as a stricter-than-default factoring treatment.

Do not ask the user to edit JSON, YAML, or plugin files.

## First Run Onboarding

For a beta user's first run, guide the work in this order:

1. Confirm the input folder and inventory the available files.
2. Confirm period, cut-off date, working language, and source-document language.
3. Identify the population to reconcile and map source roles for evidence files.
4. Confirm evidence assumptions only when not inferable: post-cut-off events, payment orders, and compensation support. Use the default factoring/advance treatment unless the user explicitly asks for a stricter pass.
5. Run `python scripts/check_dependencies.py` from the plugin directory before helper scripts; add `--requirements requirements-ocr.txt` only when scanned PDFs or OCR are needed.
6. Run extraction/reconciliation and write Excel, Word, JSON audit artifacts, and review rows.
7. Summarize exceptions, missing evidence, review sample status, and concrete next steps.

Expected delivery artifacts are:

- `riconciliazione_audit.xlsx`;
- `scheda_operativa_commercialista.xlsx`;
- `relazione_riconciliazione_audit.docx`;
- `assurance_final_outputs/reconciliation_results.json` as the versioned
  canonical machine-readable record. Its `source_processing` and `analyses`
  sections contain the schedules rendered in the workbook; do not create one
  standalone JSON file per schedule;
- `source_pages.json`;
- `run_intake.json`, `review_payload.json`, `ui_decisions.json`, and
  `final_artifacts.json` for browser/widget review handoff;
- `artifact_card.md` as the mandatory visible handoff card for every normal
  run;
- `review_ui.html` as a standalone local fallback when the local browser server
  cannot start or the browser cannot be opened;
- Codex review rows in the workbook;
- targeted missing-evidence requests when the user needs an operational follow-up pack.
- `prepared_records.json`, `assurance_receipts.json`, `assurance_gates.json`,
  `final_output_inventory.json`, and the exact `assurance_final_outputs/`
  boundary for replayable mechanical assurance.

Skipped sources, unsupported layouts, and parser failures must be visible as
review items, on the workbook's `Source processing issues` sheet, and in
`source_processing.extraction_errors` in the canonical record.

## Client folder gate

Every raw-input run must be bound to one exact Studio Archive client folder.
Do not infer the client from a person's name, a filename, an engagement label,
or the contents of an accounting file.

1. Call `studio_archive_status`, select one exact client and engagement, and
   refresh first if Studio Archive reports changed top-level scopes.
2. Import the reviewed sources into that engagement, then call
   `prepare_studio_client_workflow` with workflow ID `open-item-reconciliation`.
   Pass its returned `client_engagement_path` unchanged as
   `--client-engagement` to `raw_input_runner.py`.
3. Start that run before executing the helper. The portable context fixes the
   execution inputs as `Vera/engagements/<engagement-id>/runs/<run-id>/inputs`
   and the only permitted output path as the sibling `outputs` directory in
   the selected customer folder. Never substitute a freely chosen directory.
   When the host also requires run-level disclosure artifacts, pass
   `--output-subdirectory reconciliation` for a new run and every regeneration.
   This uses only the fixed `outputs/reconciliation/` child for the exact native
   assurance package; retain disclosures in the owning `outputs/` directory.
   Open review and validate assurance against the returned native output path.
   Declare every file in both locations when finalizing the owning archive run.
4. Stop when the context, input receipt, execution copy, lifecycle, or customer
   manifest is stale or edited. Do not copy, merge, or relabel another
   customer's files to make validation pass.

Completed review rows must come from the current run's applied review decisions.
Regenerate with those exact rows and the externally retained predecessor
checkpoint. A `PASS` row copied from an earlier run is not authority for replacement
sources, even when the invoice record ID is unchanged. Import replacement evidence
as a new controlled input and review the resulting run again; retain the earlier
source and result separately. For an explicitly requested replacement, include the
prior run ID, old and new input IDs, and the reason for re-review in the new run
`purpose`; Studio Archive preserves and exposes that sealed purpose with its input
manifest. Do not infer replacement relationships from filenames alone.

Call `finalize_studio_client_workflow` after the last output write and declare
every physical file with a stable artifact ID, relative path, concrete purpose,
audience, and media type. Review that closed declaration, then call
`complete_studio_client_workflow`; record `failed` or explicitly cancel an
abandoned run instead of treating a partial directory as a result.

The same client/engagement context must appear in `run_intake.json`,
`review_payload.json`, `run_manifest.json`, `prepared_records.json`, the
canonical reconciliation record, and `assurance_receipts.json`. The portable
folder binding intentionally excludes email addresses, legal names, tax
identifiers, document content, and mailbox content.

## Browser Review UI And MCP Widget

The primary review handoff is a local browser page backed by
`scripts/review_server.py`. After a run writes
`run_intake.json`, `review_payload.json`, `ui_decisions.json`, and
`final_artifacts.json`, Codex must create and surface `artifact_card.md`, then
open the local browser review server before final delivery. This is a
completion gate for normal runs, not optional narration, and Codex must not ask
whether to open the review surface.

Required handoff sequence:

1. Read `artifact_card.md` and `final_artifacts.json` from the output folder.
2. Start the browser review server from the plugin directory:
   `python -I -B scripts/review_server.py <output-folder>`.
3. The server opens the system browser by default on `127.0.0.1`; tell the
   reviewer the exact localhost URL and the `artifact_card.md` path in chat.
4. Use the browser page to save/apply accepted, edited, rejected, unclear, or
   requested-document decisions. The local server persists `ui_decisions.json`,
   `applied_decisions.json`, and updated `final_artifacts.json`.
5. Only after the browser surface is opened and the handoff is explicit should
   Codex report the workpapers and explain review status to the user.

Review actions cannot waive a failed deterministic check. Failed checks,
skipped required review items, and pending required review items keep
`final_artifacts.json` out of `final_ready` until the underlying run is
corrected and regenerated.
For an assured run, every applied review decision is newer than the prior seal.
Keep it blocked until native outputs are regenerated and
`validate_assurance_run` freshly replays the new seal and exact output
inventory.
On the first apply, retain the exact predecessor seal, professional review,
final reconciliation, review payload, ordered item-record mapping, applied
decisions/effects, rederived successor review, and deterministic transition
receipt in the same copy-on-write transaction. Also retain the complete
validated predecessor run under `predecessor_run/` and freshly replay that
snapshot before accepting the successor. The selected predecessor evidence
must equal its snapshot counterpart, and the predecessor seal's run date,
prepared assumptions and receipts, material values, gates, final inventory,
and exact run tree must all revalidate. A successor is invalid if that
content-addressed history is missing, changed, expanded, reordered,
contradictory, or path-forged.
Before that first apply, retain the predecessor seal's 64-hex
`content_sha256` through a separate review channel. Supply it explicitly as
`expected_predecessor_checkpoint` on browser/MCP apply, on the successor
workflow rebuild, and on successor validation. Never infer or copy this value
from the candidate successor tree. Missing or unequal checkpoints fail without
changing the output tree. Checkpoint provenance remains the responsibility of
the separate channel; digest equality does not authenticate a reviewer.
That replay also enforces the fixed ordered 25-file implementation contract,
including its pre-import bootstrap and every cache entry, plus the exact
physical file-and-directory closure at the run and final-output boundaries.
MCP terminal readiness must use the same complete replay and invokes Python
with isolated, bytecode-disabled flags.
The bootstrap is the only supported loader for the five non-`.py` retained
internal source units under `scripts/retained_sources/`; ordinary direct import
of those internal modules is unsupported. Public workflow entrypoints remain
the supported execution surface. The boundary does not attest arbitrary code
already running as the same operating-system user or the host's launcher
selection.

The MCP validate/render tools remain useful as an optional integrated Codex
surface. Load them with `tool_search` when needed, call
`validate_open_item_reconciliation_review` with `review_payload_path`, not an
inline copy of the private JSON. Validation returns a non-identifying case
index and an opaque four-hour review reference. Pass only that reference to
`render_open_item_reconciliation_review`; the server sends the complete payload to
the widget through component-only metadata, not model-visible structured
content. Use `get_open_item_reconciliation_case_context` for no more than 25
specifically selected cases at a time. Its deterministic post-mapping
projection removes empty values, unmapped columns, physical source locators,
workflow IDs, write targets, and duplicate facts. Exact document, invoice,
movement, and reference values remain off by default; request them only when
the selected accounting judgment requires exact identity. This is
purpose-limited routing, not anonymization or pseudonymization of the
professional case data: selected case context can still contain real names,
descriptions, dates, amounts, and other professional facts. When decisions are collected, call
`save_open_item_reconciliation_decisions` to persist `ui_decisions.json`, then
`apply_open_item_reconciliation_decisions` to write `applied_decisions.json` and
update `final_artifacts.json`. MCP render is no longer the primary normal-run
handoff when the browser review server is available.

For every model-led run, pass local output paths to MCP instead of inlining JSON
objects: `run_intake_path`, `review_payload_path`, `ui_decisions_path`, and
`final_artifacts_path`. The MCP server reads those JSON files from the run
output folder, validates them, and rejects path combinations outside that run
folder.

Do not treat `review_ui.html`, Markdown summaries, file links, or `file://`
URLs as equivalent to the browser review server. Use `review_ui.html` only when
the local server cannot start or the browser cannot be opened; the static file
can show/copy/download JSON but cannot persist decisions by itself. If both the
server and static HTML are unavailable, fall back to a markdown review summary
from a locally prepared projection of only the specifically selected cases;
do not read the complete `review_payload.json` into model context. Apply the
same field exclusions and exact-identifier rule as
`get_open_item_reconciliation_case_context`. The complete payload remains
available to the human reviewer in the local browser, workbook review sheet,
and `codex_review_packet.json`. Do not build a separate ad hoc HTML page for
one-off setup choices; use chat or, when this conversation is in Plan mode and
the tool is available, native Plan-mode choices for small intake decisions.

## Starter Prompt Bank

Load `references/starter-prompts.md` for beta-facing prompt examples. Keep this `SKILL.md` focused on routing, guardrails, first-run flow, dependency checks, deterministic workflow ownership, feedback, and packaging.

## Evidence Standards, Data, And Checks

Load `references/evidence-and-checks.md` when deciding evidence strength, canonical fields, source roles, or deterministic accounting checks.

Load `references/workflow-reference.md` for the exact source-decision contract,
receipt replay points, gate meanings, and promotion rules.

Core rule: row-level classifications must be supported by deterministic evidence and preserved source references. Candidate allocations and aggregate roll-forward checks may guide review, but they must not close individual rows unless a deterministic rule connects row-level evidence.

## Deterministic Run

Before running extraction or reconciliation helpers, check the plugin runtime dependencies from the plugin directory:

```bash
python scripts/check_dependencies.py
```

If scanned PDFs or OCR are needed, also check optional OCR dependencies:

```bash
python scripts/check_dependencies.py --requirements requirements-ocr.txt
```

If dependencies are missing, install from the declared requirement file when the environment allows it. If installation is not available or requires approval, tell the user in non-technical language which capability is missing and what permission or package set is needed. Do not fail silently and do not continue into a partial run that will produce unreliable output.

`run_intake.json` records a `dependency_check` object automatically when the
run intake is written. It includes status, timestamp, checked requirement
files, and missing packages. If OCR/scanned-PDF support is requested through run
assumptions, the intake check includes `requirements-ocr.txt`.

The deterministic workflow should:

1. inventory source files and capture full current-byte receipts;
2. record/replay one v2 reviewed source, perimeter, adapter, cent-only money,
   and date-order decision plus one mapping-bound qualification per source;
   suggestions never authorize parsing;
3. extract only sources with qualified adapters and abstain on ambiguous money,
   floats, or unsupported layouts;
4. normalize rows to exact decimal text and the reviewed entity, party,
   currency, unit, direction, and allocation perimeter;
5. replay source, decision, qualification, bounded record/value locators, and
   implementation receipts, then atomically seal `prepared_records.json`;
6. classify rows and build exact allocation/conservation ledgers, preserving
   non-zero residuals;
7. produce workpapers, diagnostics, an exact one-row-per-record review set, and
   record-aware material-value addresses for every declared Excel/Word/JSON;
8. publish only the declared regular files into `assurance_final_outputs/`,
   receipt every ordinary single-link file, reject symlinks/hardlinks/special
   files, and replay declared-versus-physical equality;
9. write independent assurance gates. Pending/failed professional review blocks
   reporting; publication remains withheld as a separate action. Build and
   replay final controls in staging before transactional promotion.

The raw runner does not interpret arbitrary CSV or arbitrary spreadsheet
layouts. Such a source requires a qualified adapter or reviewed external
preparation; do not coerce it through a similar-looking parser.

When extracting long PDFs, enable `verbose_extraction` and set
`pdf_progress_every_pages` when the default cadence is too sparse. The runner
emits file-start, page-progress, OCR page, cache-hit, and file-done progress
messages so the reviewer can see which PDF is consuming time.

For generic runs, pass `scope_year` and `cutoff_date` through assumptions when the work is period-specific. Do not rely on a hidden default year.

Useful helper scripts include:

- `scripts/raw_input_runner.py`: client-bound input-folder orchestration; its
  CLI requires the exact Studio Archive `--client-engagement` context and
  `--assumptions-json`;
- `scripts/reconciliation_workflow.py`: normalized-row reconciliation and native output orchestration;
- `scripts/audit_assurance.py`: isolated validation, predecessor capture/retention, and assurance replay commands;
- `scripts/build_review_sample.py`: post-run selection of a small reviewer-friendly sample, with Italian operational wording and a Markdown request draft.
- `scripts/build_missing_evidence_requests.py`: post-run workbook of targeted missing-evidence requests that distinguishes evidence already acquired from the exact missing item per row, using localized operational labels instead of internal status/rule codes.

Run every secondary helper with the same still-running portable context; each
helper rejects an input or persistent output outside that run:

```bash
python -I -B scripts/audit_assurance.py \
  --client-engagement <customer-run>/context.json \
  validate-run-json <client-run-output>
python scripts/build_review_sample.py <client-run-output>/riconciliazione_audit.xlsx \
  --client-engagement <customer-run>/context.json
python scripts/build_missing_evidence_requests.py <client-run-output>/riconciliazione_audit.xlsx \
  --client-engagement <customer-run>/context.json
```

Normalization/matching and workpaper-output internals are retained source units
loaded by the validated entrypoints; do not import or execute them directly.

## Review, Outputs, Locales, And Wording

Load `references/review-and-outputs.md` when producing workpapers, reviewing deterministic classifications, or preparing operational follow-up requests.

Load `references/locales-and-wording.md` when choosing language settings or writing localized evidence requests.

Before delivery, Codex must review the deterministic output, preserve limitations, and avoid exposing internal status/rule labels in client-facing requests.

## Plugin Improvement Feedback

At the end of every completed or blocked plugin run, after reporting the
deliverables, briefly identify concrete improvements that would have made this
plugin run better. Base suggestions on the actual session, such as missing
inputs, brittle extraction, unclear assumptions, output gaps, installation
friction, or repeated manual steps.

Keep the improvement note local to chat or run artifacts. Do not submit it to
Mparanza automatically. When this workflow runs through Vera, use Vera's
consent-based Plugin Improvement Feedback process for any transmission.

## Packaging

After changing this plugin source, use the repo-local `plugin-release` workflow:

```bash
.venv/bin/python scripts/build_codex_plugin_zip.py open-item-reconciliation
.venv/bin/python scripts/build_codex_plugin_zip.py open-item-reconciliation --check
.venv/bin/python -m pytest tests/plugins/test_codex_plugin_packages.py
```

Do not patch the downloadable ZIP manually.

## Cowork execution contract

For journal-sampling, open-item-reconciliation, journal-bank-reconciliation,
concordato-plan-review, report-builder and check-entries only, optional cache
cleanup is available from the installed Vera root:

```bash
python3 modules/<module>/scripts/implementation_bootstrap.py --repair
```

For a standalone module, use `python3 scripts/implementation_bootstrap.py --repair`
from its root. This validates the implementation first, then removes only regular,
single-link `__pycache__/*.pyc` files under that module's own `vendor` tree. It
leaves directories, other files, symlinks and shared vendor trees untouched.
If `validate_implementation_tree` ever fails with a file/directory-contract
mismatch, do not delete or modify files inside the installed plugin tree by hand
and do not bypass a sandbox/permission rejection to do so. Stop and report the
exact error instead.