feat: prepare ARR for controlled public deployment

.project-docs/60-reflection/cases/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/60-reflection/cases/2026-07-29-internal-parameters-are-not-user-inputs.md

@@ -0,0 +1,38 @@
+# Reflection: Internal Parameters Are Not User Inputs
+
+## Trigger
+
+The user corrected two successive workflow descriptions: first, year/month/cutoff values were incorrectly treated as user submissions; then a monthly-report button was still incorrectly retained as a separate user action.
+
+## Expected Behavior
+
+Trace the complete business event chain before designing the interaction boundary: XML upload → Agent structured result → successful database commit → automatic monthly-report dispatch.
+
+## Actual Behavior
+
+Internal `RunRequest` fields and an existing manual endpoint were mistaken for the intended user workflow.
+
+## Root Cause
+
+- Unclear ownership
+- Stale docs
+- Conflation of an internal execution contract with a user-facing product contract
+
+## Evidence
+
+- Files: `.planning/monthly_reports_database_audit/findings.md`, `arr_web/app.py`, `arr_web/static/app.js`
+- Session/thread: user correction on 2026-07-29
+- Docs involved: ADR-001 and `.project-docs/40-domain/business-rules.md`
+
+## Lesson
+
+When a report program accepts year, month, or as-of values internally, do not infer that a person supplies them. Establish who initiates the business event, where values are derived, and which boundary owns the trigger before proposing UI or API behavior.
+
+## Action
+
+- Update docs
+- Add the confirmed boundary to the durable business rules and architecture decision.
+
+## Promotion
+
+Promoted to ADR-001, the business-rules document, architecture data flow, and stale-item tracking.

.project-docs/60-reflection/cases/2026-07-29-remote-success-is-not-a-database-commit.md

@@ -0,0 +1,42 @@
+# Reflection: Remote Agent Success Is Not a Database Commit
+
+## Trigger
+
+Two direct-MCP vertical-slice runs reached a remote SuperAgent `success` state without creating an MCP submission or committed Finance facts.
+
+## Expected Behavior
+
+End-to-end acceptance should require all authoritative signals: an MCP `committed`/`already_committed` receipt, consumed one-time grant, accepted processing state, and matching Finance version/current/fact rows.
+
+## Actual Behavior
+
+The remote orchestration platform considered the run complete even though its cached MCP tool state prevented the business submission. The local processing state also lacked an automatic database mapping for the runner's `delivery_missing` outcome.
+
+## Root Cause
+
+- Weak gate
+- Stale external tool discovery
+- Missing terminal-state mapping
+
+## Evidence
+
+- Files: `.project-docs/50-evidence/topics/2026-07-29-live-synthetic-xml-vertical-slice.md`, `arr_processing/runner.py`, `arr_processing/postgres.py`
+- Session/thread: live no-PII upload test on 2026-07-29
+- Command output: remote status `success`; submission/version/current/record counts all zero; protected cleanup ended as `PROCESSING_RESULT_MISSING`
+- Docs involved: current state, evidence index, commitments, stale items
+
+## Lesson
+
+Treat orchestration status as a progress signal, not the system-of-record outcome. Every live test must cross-check the one-time grant, MCP submission ledger, processing terminal state, Finance facts, and downstream current pointer before reporting success or enabling a mutation endpoint.
+
+When remote completion lacks a business result, revoke any remaining grant and terminalize the exact run under identity locks; never leave a late submission path open.
+
+## Action
+
+- Update docs
+- Add check/eval
+- Record the missing automatic terminal-state mapping for separate implementation.
+
+## Promotion
+
+Promoted to the live E2E evidence record, current-state risk, future commitment, and stale-item tracking. No new product ADR is required.

.project-docs/60-reflection/reflection-index.md

@@ -0,0 +1,14 @@
+# Reflection Index
+
+Use this index for second-order workflow lessons.
+
+| Date | Reflection | Trigger | Action | Detail |
+|---|---|---|---|---|
+| 2026-07-29 | Remote Agent success is not a database commit | Repeated live runs ended remotely without an MCP submission | Add a multi-signal acceptance gate and preserve failed-run cleanup evidence | [Case](cases/2026-07-29-remote-success-is-not-a-database-commit.md) |
+| 2026-07-29 | Internal parameters are not user inputs | Human correction of the monthly-report workflow | Update docs and promote the boundary to ADR-001 | [Case](cases/2026-07-29-internal-parameters-are-not-user-inputs.md) |
+
+## When To Reflect
+
+Create a reflection only when work reveals a reusable lesson: skipped gates, repeated mistakes, durable debugging patterns, ineffective plans, human corrections, or candidates for new scripts or skills.
+
+Routine task completion belongs in `30-worklog/task-history.md`.

.project-docs/60-reflection/reflection-template.md

@@ -0,0 +1,54 @@
+# Reflection: {short title}
+
+## Trigger
+
+What happened?
+
+## Expected Behavior
+
+What should the agent or workflow have done?
+
+## Actual Behavior
+
+What happened instead?
+
+## Root Cause
+
+Classify the cause:
+
+- Missing trigger
+- Weak gate
+- Stale docs
+- Unclear ownership
+- Missing script
+- Human decision not promoted
+- Agent ignored context
+- Other:
+
+## Evidence
+
+- Commit:
+- Files:
+- Session/thread:
+- Command output:
+- Docs involved:
+
+## Lesson
+
+What should future agents learn?
+
+## Action
+
+Choose one:
+
+- Update docs
+- Update gate
+- Create script
+- Create/update skill
+- Add check/eval
+- Ask human to decide
+- No action
+
+## Promotion
+
+Should this become a rule, ADR, architecture note, task-history entry, skill change, or script?

.project-docs/60-reflection/skill-candidates.md

@@ -0,0 +1,10 @@
+# Skill Candidates
+
+Track repeated workflow lessons that may deserve a reusable skill, script, or stronger gate.
+
+| Date | Candidate | Evidence | Proposed Action | Status |
+|---|---|---|---|---|
+
+## Promotion Rule
+
+If the same reflection pattern appears repeatedly or prevents a serious mistake, propose a skill update, new skill, script, or deterministic check.