# Manual Invoice project guidance

## Scope

Build reproducible, reviewable manual billing workflows. Keep business rules, data retrieval, calculations, and documents as separate versioned layers.

## Required behavior

- Never commit, print, or copy credential contents. Use Google Application Default Credentials for BigQuery.
- Keep M1 BigQuery access read-only. Use named parameters, dry runs, partition filters, and maximum bytes billed.
- Allow BigQuery Job Project inference from ADC when configuration is empty, but always record the actual project used for billing and audit.
- Treat BigQuery location as a per-query property. Allow automatic inference for table-backed queries, but record the resolved job location and never join datasets from different locations in one query.
- Save SQL, query hashes, BigQuery Job IDs, normalized schemas, and validation results for every run.
- Treat `cases/*/schemas/` as the contract between queries and calculations.
- Do not modify `cases/*/calculation/` when only the SQL or data source changes.
- Modify or regenerate calculation code only after an explicit user request, then increment its version and compare old and new results.
- Use `Decimal` or exact warehouse numeric types for money. Never use binary floating point for invoice amounts.
- Never overwrite a reviewed run; create a new run directory.
- Generated documents must copy totals from `result.json`, not recompute them in prose.
- After rendering a report, ask about Feishu publication only when `lark-cli` is installed. Require explicit confirmation and a user-provided document link; default to append mode and save a redacted publication receipt before bundle generation.
- Finish every completed reconciliation workflow with a private bundle outside the plugin directory. Include the Markdown report, raw evidence, normalized inputs, calculation code, result, validation, lineage, and SHA-256 manifest.
- Reject secrets and symlinks from reconciliation bundles. Use directory mode `0700` and file mode `0600`.
- When only an O11Y cluster ID is available, use `resolve_o11y_cluster.py` before asking for provider, region, or deploy type. Ask only after Clinic and the bounded nutshell GS scan both fail.
- Run billing PromQL through `query_o11y_metrics.py`; persist cluster context, raw response, normalized samples, and redacted metadata.
- Detect system CLIs with `bootstrap_system_tools.py --check`. Obtain a tool selection, generate and display `--plan --tools`, then obtain a separate final confirmation before running `--yes --tools`. Selection alone is never approval. Never install system packages during plugin load or SessionStart.

## Verification

Run these checks after relevant changes:

```bash
python -m compileall skills/manual-invoice/scripts
python skills/manual-invoice/scripts/configure.py --help
python skills/manual-invoice/scripts/bootstrap_system_tools.py --help
python skills/manual-invoice/scripts/bootstrap_system_tools.py --check
python skills/manual-invoice/scripts/bootstrap_system_tools.py --plan --tools aws,google-cloud-cli
python skills/manual-invoice/scripts/bootstrap.py --help
python skills/manual-invoice/scripts/test_bigquery.py --help
python skills/manual-invoice/scripts/bq_catalog.py --help
python skills/manual-invoice/scripts/bq_validate.py --help
python skills/manual-invoice/scripts/query_bigquery.py --help
python skills/manual-invoice/scripts/resolve_user_unit_cost_grouping.py --help
python skills/manual-invoice/scripts/calculate_user_unit_cost.py --help
python -m unittest discover -s skills/manual-invoice/tests -p 'test_*.py'
python skills/manual-invoice/scripts/install_o11y_skills.py --check
python skills/manual-invoice/scripts/test_o11y.py --help
python skills/manual-invoice/scripts/query_o11y_loki.py --help
python skills/manual-invoice/scripts/resolve_o11y_cluster.py --help
python skills/manual-invoice/scripts/query_o11y_metrics.py --help
python skills/manual-invoice/scripts/publish_report_to_lark.py --help
python skills/manual-invoice/scripts/build_reconciliation_bundle.py --help
bash -n skills/manual-invoice/scripts/o11y_runtime.sh
```

Validate the skill and plugin with their Codex validators before handoff.