feat: prepare ARR for controlled public deployment

.project-docs/00-brief/project-positioning.md

@@ -0,0 +1,34 @@
+# Project Positioning
+
+## One-line Positioning
+
+ARR 是一个面向酒店 Finance 的 Opera XML 数据接入、验证入库与报表自动化系统。
+
+## Primary Goal
+
+用户只需上传 Opera XML；Agent 处理后提交结构化结果，业务系统验证并写入数据库，再由后台自动触发月报等下游处理程序。
+
+## Target Users / Consumers
+
+- 酒店 Finance 操作员
+- 消费已验证数据库事实的月报、渠道分析和公司报表程序
+
+## Non-goals
+
+- 不要求业务用户为月报提交年份、月份、截止日期或其他内部控制参数。
+- 月报程序不重复执行 XML 解析、白名单、去重、定价或公司匹配。
+
+## Core Constraints
+
+- 只有 Agent 结构化结果成功验证并提交数据库后，才允许触发下游月报程序。
+- 月报所需的年月和截止范围由业务系统内部推导；内部审计字段不得变成用户输入要求。
+- 工作簿必须保留 `TOTAL PRICE` 字段，其数据行公式为 `REAL PRICE × NIGHTS × NO_OF_ROOMS`。
+- 数据处理应确定、可追溯、隐私最小化并支持安全重试。
+
+## Quality Bar
+
+正确实现应让上传、Agent 回写、数据库提交和报表触发形成可验证的完整链路，并通过自动化测试证明字段、公式与触发边界。
+
+## Last Reviewed
+
+2026-07-29

.project-docs/00-brief/success-criteria.md

@@ -0,0 +1,21 @@
+# Success Criteria
+
+## Project Success
+
+- 用户上传 XML 后无需再提交月报参数；结构化结果成功入库会自动触发相应月报处理。
+- 生成的月报包含 `TOTAL PRICE` 字段，并在每个数据行使用 `REAL PRICE × NIGHTS × NO_OF_ROOMS` 的 Excel 公式。
+
+## Task Completion Standard
+
+- 行为改动必须同时覆盖触发链、内部参数推导、工作簿公式和失败/重试边界。
+- 仅更新记忆的任务必须清楚标注哪些旧说法已失效，以及产品代码仍存在哪些差异。
+
+## Quality Checks
+
+- 测试必须证明月报触发发生在数据库成功提交之后，且失败提交不会触发。
+- 重新打开生成的 XLSX，确认 `TOTAL PRICE` 为公式单元格并逐行引用同一行的 `REAL PRICE`、`NIGHTS`、`NO_OF_ROOMS`。
+- 用户入口不得要求提交月报年份、月份或截止日期。
+
+## Last Reviewed
+
+2026-07-29

.project-docs/05-agent-entry/context-checklist.md

@@ -0,0 +1,12 @@
+# Context Checklist
+
+Before planning, confirm:
+
+- I know what this project is and what it is not.
+- I know the current focus and recently completed work.
+- I checked active decisions that constrain this task.
+- I checked the current architecture overview.
+- I identified task-specific docs that need deeper reading.
+- I checked evidence, reflection, or commitment indexes when the task touches investigations, repeated workflow lessons, or follow-ups.
+- I can name unknown, stale, or conflicting information.
+- I know whether the task requires human confirmation before changing durable docs.

.project-docs/05-agent-entry/memory-index.md

@@ -0,0 +1,25 @@
+# Memory Index
+
+Use this as the high-density entry point before reading slower documents.
+
+## Startup Set
+
+- Project identity: `.project-docs/00-brief/project-positioning.md`
+- Current state: `.project-docs/30-worklog/current-state.md`
+- Decision list: `.project-docs/10-decisions/decision-index.md`
+- System shape: `.project-docs/20-architecture/system-overview.md`
+
+## Recall Pointers
+
+- Confirmed report workflow and price formula: `.project-docs/10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md`
+- Business rules and exact field semantics: `.project-docs/40-domain/business-rules.md`
+- Evidence-heavy bugs, experiments, investigations: `.project-docs/50-evidence/evidence-index.md`
+- Current upload E2E blocker: `.project-docs/50-evidence/topics/2026-07-29-live-synthetic-xml-vertical-slice.md`
+- Controlled public deployment snapshot: `.project-docs/50-evidence/topics/2026-07-29-public-deployment-repository.md`
+- Workflow lessons and repeated agent mistakes: `.project-docs/60-reflection/reflection-index.md`
+- Pending promises, loops, timed follow-ups: `.project-docs/80-commitments/commitments.md`
+- Stale or conflicting docs: `.project-docs/90-maintenance/stale-items.md`
+
+## Loading Rule
+
+Keep this file short. Add pointers here, not full history.

.project-docs/05-agent-entry/planning-gate.md

@@ -0,0 +1,44 @@
+# Planning Gate
+
+A coding agent must complete this gate before writing an implementation plan.
+
+## Required Output
+
+```md
+## Project Context Loaded
+
+Read:
+- {file path}
+
+Relevant understanding:
+- Project goal:
+- Current focus:
+- Active constraints:
+- Decisions affecting this task:
+- Evidence, reflections, or commitments affecting this task:
+- Files or modules likely involved:
+- Unknowns, stale docs, or conflicts:
+
+Gate result:
+- Passed or Blocked
+```
+
+## Pass Criteria
+
+The gate passes only when:
+
+- required documents were read
+- `memory-index.md` was checked when present
+- task-relevant decisions were checked
+- relevant evidence, reflection, and commitment indexes were checked when applicable
+- stale or conflicting docs were called out
+- the plan respects project positioning and constraints
+
+## Block Criteria
+
+Block planning when:
+
+- required documents are missing and cannot be inferred
+- current state conflicts with the user request
+- an existing decision appears to be violated
+- the task changes project positioning or architecture without human confirmation

.project-docs/05-agent-entry/read-before-coding.md

@@ -0,0 +1,7 @@
+# Read Before Coding
+
+Before editing code, verify that the implementation plan already passed the planning gate.
+
+If the plan is stale, missing, or based on incomplete docs, return to `.project-docs/05-agent-entry/read-before-planning.md`.
+
+Before editing files, read the project docs and source files directly related to the target modules. If implementation reveals stale project docs, record the discrepancy in `.project-docs/90-maintenance/stale-items.md` or update the relevant docs after the task completes.

.project-docs/05-agent-entry/read-before-planning.md

@@ -0,0 +1,22 @@
+# Read Before Planning
+
+Before writing any coding plan, read these files in order:
+
+1. `.project-docs/05-agent-entry/memory-index.md`
+2. `.project-docs/00-brief/project-positioning.md`
+3. `.project-docs/30-worklog/current-state.md`
+4. `.project-docs/10-decisions/decision-index.md`
+5. `.project-docs/20-architecture/system-overview.md`
+
+Then read additional files when relevant:
+
+- Architecture or refactor task: `.project-docs/20-architecture/module-map.md` and `.project-docs/20-architecture/data-flow.md`
+- Product or behavior task: `.project-docs/40-domain/business-rules.md` and `.project-docs/00-brief/success-criteria.md`
+- Ambiguous terms: `.project-docs/40-domain/glossary.md`
+- Decision-sensitive task: referenced ADR files in `.project-docs/10-decisions/`
+- Evidence-heavy bug, investigation, or experiment: `.project-docs/50-evidence/evidence-index.md`
+- Repeated workflow issue, skipped gate, or skill/script candidate: `.project-docs/60-reflection/reflection-index.md`
+- Follow-up, loop, timed check, or restart-point task: `.project-docs/80-commitments/commitments.md`
+- Suspicious context: `.project-docs/90-maintenance/stale-items.md`
+
+Do not write a plan until the planning gate passes.

.project-docs/10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md

@@ -0,0 +1,34 @@
+# ADR-001: Automatic Monthly Trigger And TOTAL PRICE Formula
+
+- Status: Accepted
+- Date: 2026-07-29
+- Source: User correction in the current session
+
+## Context
+
+Earlier discussion incorrectly treated monthly-report generation as a separate user action and described year, month, or cutoff date as user-submitted values. An earlier report specification also treated generated price cells as static values.
+
+## Decision
+
+1. The user's workflow begins and ends with uploading the XML.
+2. The Agent processes the XML and returns structured data for validation and database persistence.
+3. Only after that structured result is successfully committed does the business system automatically trigger the monthly-report processing program.
+4. `report_year`, `report_month`, `as_of_date`, or equivalent values may remain as internal execution and audit fields, but the backend must derive them. They are not user inputs in the primary workflow.
+5. The report keeps the `TOTAL PRICE` dimension/field. Each XLSX data-row cell must contain a formula with the business meaning:
+
+   `TOTAL PRICE = REAL PRICE × NIGHTS × NO_OF_ROOMS`
+
+   With the current 19-column layout, this is equivalent to `=R2*C2*G2` for row 2 and must fill relatively for later rows.
+
+## Consequences
+
+- A manual month/as-of form or endpoint is not the primary product flow and must not be presented as a required user step.
+- The monthly processor may still accept internally supplied month/cutoff arguments from its orchestrator.
+- Existing manual-trigger UI/API code and static-cell workbook generation are implementation gaps, not the accepted requirement.
+- The exact internal event/outbox/worker mechanism and cutoff derivation policy remain implementation details to design and verify; they must not be delegated to the user.
+
+## Supersedes
+
+- Any conversation or planning note that says the user submits the report year, month, or cutoff date.
+- The intermediate correction that said the user clicks a monthly-report button while the backend derives those values.
+- Any report-output rule requiring `TOTAL PRICE` data cells to be static values or requiring a zero-formula workbook.

.project-docs/10-decisions/adr-template.md

@@ -0,0 +1,33 @@
+# ADR-{number}: {decision title}
+
+## Status
+
+Proposed
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{context that made the decision necessary}
+
+## Decision
+
+{decision made}
+
+## Rationale
+
+{why this option was chosen}
+
+## Consequences
+
+- {positive or negative consequence}
+
+## Supersedes
+
+- {older ADR or decision, if any}
+
+## Related
+
+- {related doc or source file}

.project-docs/10-decisions/decision-index.md

@@ -0,0 +1,24 @@
+# Decision Index
+
+## Active Decisions
+
+| ID | Decision | Status | Date | Applies To | Detail |
+|---|---|---|---|---|---|
+| ADR-001 | 月报在 Agent 结构化结果成功入库后由业务系统自动触发；`TOTAL PRICE` 为 Excel 公式字段 | Accepted | 2026-07-29 | 上传链路、月报触发、XLSX 输出 | [ADR-001](ADR-001-automatic-monthly-trigger-and-total-price-formula.md) |
+
+## Superseded Decisions
+
+| ID | Decision | Superseded By | Date |
+|---|---|---|---|
+| Conversation draft | 用户点击月报按钮并提交或选择年月/截止范围；金额写静态值 | ADR-001 | 2026-07-29 |
+
+## Decision Criteria
+
+Create or update an ADR when a choice affects:
+
+- project positioning
+- architecture boundaries
+- public behavior
+- data model
+- long-term maintenance
+- user-facing workflow

.project-docs/20-architecture/data-flow.md

@@ -0,0 +1,24 @@
+# Data Flow
+
+## Primary Flows
+
+| Flow | Source | Destination | Notes |
+|---|---|---|---|
+| XML ingestion | User upload | Agent processing | Upload is the user's only required action for this flow. |
+| Structured result commit | Agent output | PostgreSQL Finance facts | Independent validation/replay must succeed before commit. |
+| Automatic monthly trigger | Successful database commit | Monthly-report worker/program | Month and cutoff values are derived internally, not supplied by the user. |
+| Monthly workbook build | Committed Finance facts | XLSX artifact | `TOTAL PRICE` cells use `REAL PRICE × NIGHTS × NO_OF_ROOMS` formulas. |
+
+## State Ownership
+
+- PostgreSQL owns accepted/current Finance facts and processing state.
+- Generated XLSX files are artifacts derived from a pinned database snapshot; they are not an alternative fact source.
+
+## External Interfaces
+
+- User-facing: XML upload, processing status, and controlled report download.
+- Internal: Agent structured-result submission and automatic report-task dispatch after commit.
+
+## Last Updated
+
+2026-07-29

.project-docs/20-architecture/module-map.md

@@ -0,0 +1,27 @@
+# Module Map
+
+## Source Layout
+
+| Path | Responsibility | Owner Notes |
+|---|---|---|
+| `arr_web/` | Upload portal and business API | Manual monthly request code conflicts with ADR-001. |
+| `arr_mcp/` | Direct Agent-result submission and ingestion boundary | Post-commit trigger should originate at or after this boundary, not before it. |
+| `arr_ingestion/`, `arr_processing/` | Validate and persist structured processing results | Keep deterministic replay and transaction semantics. |
+| `monthly_reports/` | Database-backed monthly workbook generation | Needs formula-cell output and automatic orchestration integration. |
+| `database/` | Finance facts, views, guards and migrations | Database total remains useful for integrity checks. |
+| `Dockerfile`, `compose.yaml` | Reproducible single-server Web/MCP runtime | Compose explicitly enables XML processing; source defaults remain fail-closed. |
+| `deploy/` | Caddy TLS/auth boundary, production env template and operator runbook | Only Caddy publishes host ports; never commit the real production env file. |
+| `tests/` | Regression and acceptance coverage | Add post-commit trigger and formula-cell assertions when implementation is authorized. |
+
+## Dependency Direction
+
+- Upload/Agent/ingestion writes validated facts; report modules depend on committed facts and must not call back into XML parsing.
+- Public traffic enters through Caddy; Web and MCP stay on the internal Compose network and use separate browser/MCP authentication boundaries.
+
+## Risky Or Sensitive Areas
+
+- Commit-to-trigger atomicity/idempotency, monthly snapshot selection, XLSX formula preservation, and PII-safe result metadata.
+
+## Last Updated
+
+2026-07-29

.project-docs/20-architecture/system-overview.md

@@ -0,0 +1,33 @@
+# System Overview
+
+## Current Architecture
+
+The ARR system accepts an Opera XML upload, stores the private source artifact, invokes an Agent for deterministic processing, validates the returned structured result, and commits accepted Finance facts to PostgreSQL. Downstream analytics and report programs consume those committed facts. The accepted target flow automatically triggers monthly processing after the commit; the current manual monthly UI/API remains a known implementation gap.
+
+## Main Components
+
+| Component | Responsibility | Notes |
+|---|---|---|
+| `arr_web` | XML upload, job status, controlled downloads and business APIs | The existing manual monthly-generation request is not the accepted primary flow. |
+| SuperAgent + deterministic processing skill | Convert XML to the approved structured result | Must not decide user-facing report parameters. |
+| `arr_mcp` / ingestion service | Independently validate/replay and atomically commit accepted structured results | Automatic downstream trigger begins only after commit success. |
+| PostgreSQL Finance facts | Authoritative current and retained daily facts | Source of truth for downstream reports. |
+| `monthly_reports` | Generate monthly XLSX from committed database facts | Internal month/cutoff inputs are allowed; `TOTAL PRICE` must be an XLSX formula. |
+| `channel_analytics` / `company_reports` | Additional read/report consumers | Must not change the monthly-report trigger contract. |
+| Caddy + Compose deployment boundary | Terminate HTTPS, authenticate Web users, keep Web/MCP ports internal and start the explicit processing profile | MCP still performs its own bearer check and DNS-rebinding Host validation. |
+
+## Important Boundaries
+
+- XML processing and Finance fact validation happen before the monthly-report trigger.
+- The user-facing upload workflow does not collect monthly report year, month, or cutoff date.
+- Monthly processing reads validated database facts rather than repeating Agent business logic.
+- Database `total_price` may support validation, but the exported `TOTAL PRICE` cell must remain a formula.
+- Public deployment enables XML processing only through the explicit Compose command and requires `processing_ready=true`; it does not change local/application defaults.
+
+## Related Decisions
+
+- [ADR-001](../10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md)
+
+## Last Updated
+
+2026-07-29

.project-docs/30-worklog/current-state.md

@@ -0,0 +1,50 @@
+# Current State
+
+## Current Focus
+
+A controlled public-deployment source snapshot is prepared for the empty self-hosted `wyndham-ARR` repository. Its Compose Web entry explicitly enables `--enable-processing --secure-cookies`; Caddy is the only public listener and adds HTTPS plus Web Basic Auth, while MCP retains its independent bearer and exact Host allowlist. Local application defaults remain fail-closed. The snapshot passes 259 tests with 2 environment skips plus contract, checksum, candidate-file and secret scans. No public server deployment has been performed from this workspace.
+
+## Recently Completed
+
+- 2026-07-29: Added a Linux Dockerfile, Compose, Caddy TLS boundary, production env example and deployment runbook. The Web health gate requires both `database_ready` and `processing_ready`; the production command opens XML processing without changing the source default.
+- 2026-07-29: Added opt-in HTTPS `Secure` session cookies, made the booking fixture root portable, removed local paths/test endpoints/temporary tunnel names from the publishable snapshot, and verified 271 final candidate files (about 2.0 MiB) contain no detected secrets, symlinks or files larger than 1 MiB.
+- 2026-07-29: Ran the complete Python suite in a dependency-complete Python 3.12 environment: 259 tests passed and 2 were skipped. Compose YAML, JSON contracts and controlled package checksums also passed static validation.
+- 2026-07-29: Restarted the controlled MCP and fixed-domain ngrok sessions. An initial authenticated 421 exposed a preserved public Host; the MCP was safely restarted with an exact loopback/public Host allowlist, after which public initialize and tools-list both returned 200.
+- 2026-07-29: Reverified gateway 1.0.1, protocol 2025-11-25, one tool, 2195-byte advertised schema, and zero `$ref`/`$defs`/`$id` keys without invoking the business tool.
+- 2026-07-29: Diagnosed the SuperAgent MCP `failed` state: ports 8890/4040 have no listeners, the old temporary PIDs are gone, TLS remains valid, and the public `/mcp` request is rejected by ngrok as an offline endpoint before reaching ARR authentication or MCP protocol handling.
+- 2026-07-29: Started a controlled upload-capable Web instance on `127.0.0.1:8766` and submitted one no-PII XML through the real page.
+- 2026-07-29: Confirmed job `arrjob-fdc2c1a0695c41b3b372a52033b2f567` reached SuperAgent run `7e1ad2fe-cb59-4d04-b92c-9f09d98f4ef8`; remote status was `success`, but MCP submission and all `2038-01-19` Finance facts remained absent.
+- 2026-07-29: Safely terminalized the failed test as `PROCESSING_RESULT_MISSING`, revoked its unconsumed grant, verified zero business writes, and stopped port 8766.
+- 2026-07-29: Confirmed that XML upload is the only required user action; successful structured-data commit must automatically trigger monthly processing.
+- 2026-07-29: Confirmed that `TOTAL PRICE` is required and must be an Excel formula equal to `REAL PRICE × NIGHTS × NO_OF_ROOMS`.
+- 2026-07-29: Initialized `.project-docs` and recorded the correction in ADR-001.
+
+## In Progress
+
+- Repository publication is the remaining local handoff step. Runtime deployment, DNS/Secret injection and SuperAgent stable-domain rebinding belong to the user's public server environment.
+
+## Next Recommended Steps
+
+1. Deploy the repository using `deploy/README.md`, inject real Secrets only on the server, and require the public Web health response to report `database_ready=true` and `processing_ready=true`.
+2. Rebind SuperAgent to `https://<MCP_PUBLIC_HOST>/mcp`, rediscover exactly `arr_submit_processing_result`, save/publish the new Agent version, and stop relying on the temporary ngrok endpoint.
+3. Rerun the vertical slice with a fresh no-PII XML and require a `committed`/`already_committed` receipt plus matching Finance version, current pointer and fact rows.
+4. In separately authorized implementation work, add the automatic post-commit monthly dispatch and required `TOTAL PRICE` formula behavior.
+
+## Open Questions / Blockers
+
+- Docker and Caddy are not installed in this workspace, so image build, Compose runtime, DNS, ACME issuance and public HTTP checks must be performed on the deployment server.
+- SuperAgent administration requires the user's authenticated platform session; its stale MCP configuration must be replaced with the new stable public MCP domain after deployment.
+- The restored ngrok/MCP sessions remain temporary and are not the formal deployment target.
+- `ProcessingRunner.poll()` can emit `delivery_missing`, but the PostgreSQL state adapter has no matching status mapping. The live run therefore required a guarded manual terminalization transaction.
+- The exact automatic monthly dispatch mechanism and business-time/cutoff derivation policy still require implementation design; neither is a user input.
+
+## Risky Areas
+
+- A SuperAgent run reporting `success` is not business success; only an MCP receipt and committed database facts qualify.
+- Enabling upload on the current all-interface 8765 listener without a confirmed authentication boundary would expose a mutation endpoint.
+- Committing `deploy/.env.production`, publishing 8765/8890 directly, omitting TLS/Basic Auth, or reusing the MCP/SuperAgent/HMAC credentials would break the deployment boundary.
+- Triggering before commit, duplicate trigger delivery, deriving the wrong reporting period, or replacing formulas with cached/static amounts.
+
+## Last Updated
+
+2026-07-29

.project-docs/30-worklog/session-notes/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/30-worklog/task-history.md

@@ -0,0 +1,15 @@
+# Task History
+
+## Completed Tasks
+
+| Date | Task | Outcome | Docs Updated |
+|---|---|---|---|
+| 2026-07-29 | Prepare the project for controlled public-server deployment and repository publication | Added Docker/Compose/Caddy deployment with XML processing explicitly enabled, HTTPS Secure cookies, Basic Auth/Bearer boundaries and a Chinese runbook; sanitized publishable history; 259 tests passed (2 skipped), all contracts/checksums and a 271-file secret/size/symlink scan passed | Current state, architecture, deployment evidence/index, commitments, module map |
+| 2026-07-29 | Restart the controlled ARR MCP public path | Restarted loopback MCP and fixed ngrok host; corrected exact public Host allowlisting after a diagnostic 421; public unauthorized requests now return 401 and authenticated one-tool discovery returns 200. Main upload remains disabled | Current state, E2E evidence/index, commitment, active planning record |
+| 2026-07-29 | Diagnose persistent SuperAgent MCP `failed` status | Confirmed the temporary MCP and ngrok processes had exited; public `/mcp` returns `ERR_NGROK_3200 endpoint offline` despite valid DNS/TLS. The stale platform config version 33 remains a second-stage issue after reachability is restored | Current state, E2E evidence/index, commitment, active planning record |
+| 2026-07-29 | Open XML upload in a controlled boundary and execute a real no-PII vertical slice | UI upload, OSS registration and SuperAgent dispatch passed; SuperAgent returned success without calling MCP because platform tool discovery remained at config version 33. Test run was failed safely, grant revoked, zero Finance writes verified, and temporary upload closed | Current state, evidence topic/index, commitments, planning record |
+| 2026-07-29 | Clear incorrect monthly-report memory and record the user's final corrections | Replaced manual-input/button assumptions with automatic post-commit triggering; confirmed the required `TOTAL PRICE` formula; no product code changed | Project positioning, ADR-001, architecture, current state, business rules, stale items, monthly audit planning notes |
+
+## Notes
+
+Keep entries concise. Move durable rationale to ADRs and durable rules to the appropriate higher-level document.

.project-docs/40-domain/business-rules.md

@@ -0,0 +1,20 @@
+# Business Rules
+
+## Durable Rules
+
+- The user uploads XML; the user does not submit a report year, report month, cutoff date, or separate monthly-generation request in the primary workflow.
+- The Agent returns structured data, which must be validated and successfully committed to the database before downstream monthly processing starts.
+- A successful database commit automatically triggers the monthly-report processing program through the business system.
+- Year, month, cutoff/as-of date, and similar fields are internal derived execution/audit values. Their presence in code or metadata does not make them user inputs.
+- The monthly output contains the exact business dimension/field `TOTAL PRICE`.
+- Each monthly XLSX data-row `TOTAL PRICE` cell is a formula whose business meaning is `REAL PRICE × NIGHTS × NO_OF_ROOMS` (current layout example: `=R2*C2*G2`).
+- A stored database `total_price` may be used for integrity checking, but it does not replace the required formula in the exported workbook.
+
+## Open Questions
+
+- The internal event/outbox/worker mechanism for automatic dispatch is not yet selected.
+- The exact business-time and cutoff derivation policy is not yet specified; the system must derive it without user input.
+
+## Last Reviewed
+
+2026-07-29

.project-docs/40-domain/glossary.md

@@ -0,0 +1,10 @@
+# Glossary
+
+| Term | Meaning | Notes |
+|---|---|---|
+| `REAL PRICE` | Unit/base price used by the report calculation | Existing layout places it in column R. |
+| `NIGHTS` | Number of nights for the row | Existing layout places it in column C. |
+| `NO_OF_ROOMS` | Number of rooms for the row | Existing layout places it in column G. |
+| `TOTAL PRICE` | Required report dimension calculated as `REAL PRICE × NIGHTS × NO_OF_ROOMS` | Must be an XLSX formula cell, not only a static exported value. |
+| Internal report parameters | Derived values such as report year, month and cutoff/as-of date | May exist in program calls and audit metadata; never a required user submission in the primary flow. |
+| Successful commit | Agent structured result has passed validation and been atomically persisted as accepted Finance facts | Automatic monthly processing may start only after this point. |

.project-docs/50-evidence/evidence-index.md

@@ -0,0 +1,14 @@
+# Evidence Index
+
+Use this index for searchable, traceable evidence records.
+
+| Date | Topic | Status | Source | Detail |
+|---|---|---|---|---|
+| 2026-07-29 | Controlled public deployment repository | Active until server E2E | [Evidence topic](topics/2026-07-29-public-deployment-repository.md) | Deployment entry explicitly enables XML processing behind Caddy HTTPS/Basic Auth; 259 tests and snapshot safety checks pass, but Docker/public runtime awaits the user's server. |
+| 2026-07-29 | Live synthetic XML upload vertical slice | Active blocker | [Evidence topic](topics/2026-07-29-live-synthetic-xml-vertical-slice.md) | Public MCP reachability and one-tool discovery are restored; stale SuperAgent config version 33 must now be refreshed before the next commit test. |
+
+## When To Add Evidence
+
+Add a topic file when a task depends on logs, commits, test output, external docs, bug reproduction, experiments, or postmortem-level reasoning.
+
+Keep task progress in `30-worklog/`; keep reusable workflow lessons in `60-reflection/`.

.project-docs/50-evidence/topic-template.md

@@ -0,0 +1,35 @@
+# Evidence Topic: {short title}
+
+## Metadata
+
+- Date:
+- Status: Active | Resolved | Superseded | Stale
+- Scope:
+- Confidence: Fact | Inference | Hypothesis
+- Source:
+- Last verified:
+- Stale trigger:
+
+## Question
+
+What needed evidence?
+
+## Evidence
+
+- Commit:
+- Files:
+- Commands:
+- Logs:
+- External source:
+
+## Finding
+
+What does the evidence support?
+
+## Impact
+
+What future planning or implementation should this affect?
+
+## Open Items
+
+- {open item}

.project-docs/50-evidence/topics/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/50-evidence/topics/2026-07-29-live-synthetic-xml-vertical-slice.md

@@ -0,0 +1,50 @@
+# Evidence Topic: Live Synthetic XML Upload Vertical Slice
+
+## Metadata
+
+- Date: 2026-07-29
+- Status: Active
+- Scope: Real Web upload → private OSS → SuperAgent → direct MCP → PostgreSQL Finance facts
+- Confidence: Fact for observed state; strong inference for the platform-cache cause
+- Source: Real browser interaction, Open Agent run metadata, public MCP discovery, PostgreSQL ledger/fact queries, local health checks
+- Last verified: 2026-07-29 15:57 +08:00
+- Stale trigger: Public MCP reachability is restored, SuperAgent enterprise MCP config version exceeds `33`, and a fresh run receives `committed` or `already_committed`
+
+## Question
+
+Can the accepted user flow complete from a real XML upload through SuperAgent and direct MCP into authoritative database facts?
+
+## Evidence
+
+- Input: Synthetic no-PII XML for unused business date `2038-01-19`; deterministic local validation retained two records and was activation-eligible.
+- Web: A controlled instance on `127.0.0.1:8766` reported all readiness gates true. The real page selected the XML, enabled “开始处理”, and submitted exactly once.
+- Processing identity: Job `arrjob-fdc2c1a0695c41b3b372a52033b2f567`, attempt `1`, SuperAgent run `7e1ad2fe-cb59-4d04-b92c-9f09d98f4ef8`.
+- Remote result: Open Agent reported `success` with no final content. Metadata resolved the intended V5 profile but still reported enterprise MCP config version `33`.
+- MCP service: Authenticated read-only discovery advertised one tool, `arr_submit_processing_result`, from gateway version `1.0.1`; its input schema contained no `$ref`, `$defs`, or `$id` keywords.
+- Database after remote completion: No `ingestion.result_submissions` row, the grant was unconsumed, and the target date had no Finance daily version, current pointer, or daily records.
+- Safe cleanup: A serializable, identity-locked transaction marked run `13` and attempt `12` failed with `PROCESSING_RESULT_MISSING`, revoked grant `9`, and inserted the privacy-minimized failure outbox event. An independent read-only query verified submission/version/current/record counts were all zero.
+- Exposure state: The temporary 8766 process was stopped and the port closed. The normal `*:8765` service remained healthy with `processing_ready=false` throughout.
+- Follow-up connection state: The temporary MCP listener on 8890 and ngrok management listener on 4040 later disappeared; their historical PIDs no longer exist and no launchd service owns either process. The configured public host still resolves and has a valid TLS certificate, but `/mcp` now returns ngrok `ERR_NGROK_3200 endpoint offline` before ARR authentication or MCP handling.
+- Recovery state: With user authorization, loopback MCP and the fixed ngrok host were restarted. The first authenticated request returned 421 because the new tunnel preserved the public Host while the gateway allowed only loopback Hosts; the server log explicitly recorded the invalid Host. The gateway was restarted still on loopback with exact loopback/public Host entries. Public unauthorized requests then returned 401, and authenticated initialize/tools-list returned 200 with gateway 1.0.1, protocol 2025-11-25, exactly one tool, and the same 2195-byte reference-free schema.
+- Final process state: MCP PID 34744 listens on `127.0.0.1:8890`; ngrok PID 34569 exposes the existing fixed host and keeps its inspector on `127.0.0.1:4040`. Port 8766 is closed and the normal 8765 service remains database-ready with processing disabled.
+- Repository state: The workspace is not a Git repository, so this evidence is tied to explicit runtime identities and project files rather than a commit hash.
+
+## Finding
+
+The vertical slice did not pass. Upload, OSS registration, processing ledger creation, grant issuance, and SuperAgent dispatch are operational, but SuperAgent did not invoke the database MCP. The public gateway is again online and independently discoverable. The remaining platform action is to refresh and save stale MCP config version `33`, then prove a fresh run actually creates a committed submission.
+
+Remote Agent `success` must not be treated as business success. The required success condition remains an MCP `committed`/`already_committed` receipt plus matching committed Finance facts.
+
+## Impact
+
+- Keep the normal upload mutation disabled until a fresh synthetic vertical slice passes.
+- Do not change MCP URL, bearer headers, OSS configuration, database configuration, or the V5 prompt for this failure.
+- Refresh/reconnect/rediscover the MCP tool in SuperAgent and save the configuration; public connectivity no longer blocks that action.
+- Fix the local `delivery_missing` PostgreSQL status-mapping gap in separately authorized implementation work so future missing-result runs terminate automatically.
+- Automatic monthly post-commit dispatch remains unimplemented and therefore was not testable in this failed pre-commit run.
+
+## Open Items
+
+- Authenticated SuperAgent administrator refresh and save.
+- Fresh no-PII E2E with platform config version greater than `33`.
+- A committed receipt and downstream daily/BI/monthly read-path reconciliation.

.project-docs/50-evidence/topics/2026-07-29-public-deployment-repository.md

@@ -0,0 +1,39 @@
+# Evidence Topic: Controlled public deployment repository
+
+## Metadata
+
+- Date: 2026-07-29
+- Status: Active
+- Scope: Source publication and public-server deployment handoff
+- Confidence: Fact
+- Source: Local candidate snapshot, automated tests and static configuration checks
+- Last verified: 2026-07-29
+- Stale trigger: Any change to Dockerfile, Compose, Caddy, Web processing flags, authentication, dependency pins or public topology
+
+## Question
+
+Does the publishable source snapshot open XML processing through an explicit authenticated HTTPS deployment entry without exposing local state, credentials or unfinished report claims?
+
+## Evidence
+
+- Files: `Dockerfile`, `compose.yaml`, `deploy/Caddyfile`, `deploy/.env.production.example`, `deploy/README.md`, `arr_web/app.py`, `arr_web/run.py`, `tests/test_arr_web.py`.
+- Deployment command inspection: Compose Web command contains `--enable-processing` and `--secure-cookies`; only Caddy maps host ports 80/443, Web and MCP use internal `expose` ports.
+- Tests: Python 3.12 full discovery ran 259 tests successfully; 2 environment-dependent tests were skipped.
+- Integrity: every entry in `CHECKSUMS.sha256` passed and 10 JSON contracts parsed.
+- Snapshot audit: 271 final candidate files, about 2.0 MiB, zero files over 1 MiB, zero symlinks, eight ZIP/XLSX archives inspected and zero detected secret/private-endpoint hits after documented placeholder allowlisting.
+- Configuration: Compose YAML parsed and assertions confirmed both required Web flags. Docker/Caddy executables are absent locally, so no image build or public TLS runtime result is claimed.
+
+## Finding
+
+The repository snapshot provides a fail-closed deployment profile that opens XML upload only when the database, guarded OSS and SuperAgent processing runtime initialize. Web traffic is protected by Caddy HTTPS plus Basic Auth, MCP traffic retains application bearer authentication, and application defaults remain closed outside this profile.
+
+## Impact
+
+The next test should use the stable deployed domains, not the temporary ngrok endpoint. `processing_ready=true` is a deployment prerequisite, but business completion still requires SuperAgent tool rediscovery and an MCP `committed`/`already_committed` receipt with matching database facts.
+
+## Open Items
+
+- Build and start the containers on the public Linux server; verify DNS, ACME, health and logs.
+- Rebind and republish the SuperAgent MCP configuration against the stable MCP domain.
+- Execute one no-PII XML end-to-end commit test.
+- Implement automatic post-commit monthly dispatch and the required `TOTAL PRICE` formula in separately authorized work.

.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.

.project-docs/80-commitments/commitments.md

@@ -0,0 +1,11 @@
+# Commitments
+
+Track future-facing memory: promised follow-ups, unfinished loops, timed checks, and restart points.
+
+| Date | Commitment | Trigger / Due | Owner | Status | Next Action |
+|---|---|---|---|---|---|
+| 2026-07-29 | Deploy the stable public Web/MCP profile, refresh SuperAgent discovery and rerun the no-PII XML vertical slice | Before enabling real business XML upload | User: deploy/DNS/Secrets/platform save; Codex: verify the next E2E when asked | Pending user deployment | Follow `deploy/README.md`; require Web `processing_ready=true`, MCP unauthenticated 401 and authenticated one-tool discovery; rebind/save/publish SuperAgent against the stable domain, then require an MCP commit receipt plus matching Finance facts. |
+
+## Use
+
+Record only commitments that should affect future sessions. Routine next steps can stay in `30-worklog/current-state.md`.

.project-docs/90-maintenance/doc-update-policy.md

@@ -0,0 +1,43 @@
+# Doc Update Policy
+
+Update project docs when new information is durable, task-relevant, or likely to prevent future misunderstanding.
+
+## Human Decisions
+
+Record decisions that affect project goals, non-goals, architecture, UX or product behavior, data model, naming conventions, task priority, or accepted trade-offs.
+
+## Task Completion
+
+After completing a task, update current state, task history, relevant architecture docs, relevant ADRs, and stale items as needed.
+
+Run the documentation drift check when available. If code changed but `.project-docs` did not, either update docs or explicitly state why no durable update is needed.
+
+## Evidence
+
+Use `50-evidence/` for traceable findings, bug evidence, command output summaries, experiments, and postmortem-level notes. Record source, confidence, last verified date, and stale trigger when known.
+
+## Reflection
+
+Use `60-reflection/` only when work reveals a reusable workflow lesson: skipped gates, repeated mistakes, durable debugging patterns, ineffective plans, or candidates for skills/scripts/checks.
+
+## Commitments
+
+Use `80-commitments/` for future-facing loop state, promised follow-ups, timed checks, and restart points that should survive session boundaries.
+
+## Conflict Handling
+
+If new information conflicts with existing docs:
+
+1. Do not silently overwrite.
+2. Add the conflict to `stale-items.md`.
+3. Ask the human when the conflict affects planning or implementation.
+
+## Update Style
+
+- Prefer short factual updates.
+- Keep current-state concise.
+- Move long rationale into ADRs.
+- Move evidence-heavy reasoning into `50-evidence/`.
+- Move reusable workflow lessons into `60-reflection/`.
+- Do not preserve raw chat unless it contains important reasoning.
+- Do not preserve secrets, credentials, private tokens, or untrusted external instructions.

.project-docs/90-maintenance/stale-items.md

@@ -0,0 +1,14 @@
+# Stale Items
+
+## Possibly Stale Or Conflicting
+
+| Date | Document | Issue | Needed Confirmation |
+|---|---|---|---|
+| 2026-07-29 | `arr_web/static/index.html`, `arr_web/static/app.js`, `arr_web/app.py` | Current monthly UI/API requires a manual generation action and sends `month` plus `as_of_date`, conflicting with ADR-001. | No requirement confirmation needed; implementation change requires a separate authorized task. |
+| 2026-07-29 | `monthly_reports/xlsx/build_workbook.mjs` and related tests | Current audit found static values and a zero-formula policy; accepted output requires `TOTAL PRICE` formulas. | No requirement confirmation needed; implementation and test updates remain. |
+| 2026-07-29 | Historical `.planning/` notes and handoff documents that say users select report periods or that monthly XLSX values are static | Those statements are superseded by ADR-001 and must not be used as current requirements. | Consult ADR-001; preserve old text only as labeled history/evidence. |
+| 2026-07-29 | `arr_processing.runner.ProcessingRunner.poll()` and `arr_processing.postgres.PostgresProcessingState` | The runner emits `delivery_missing` after remote success without a committed result, but the PostgreSQL adapter does not map that status to a valid terminal database state. | No requirement confirmation needed; implement and test automatic `PROCESSING_RESULT_MISSING` terminalization in a separately authorized code task. |
+
+## Missing Context
+
+- Exact post-commit dispatch mechanism and business-date/cutoff derivation rules are not yet documented.