Scaffold repo for implementation handoff

- README: orientation, doc map, target package layout (pointers only, no duplicated architecture content) - CLAUDE.md: agent operating manual — invariants as code-review rules, conventions, do-not list, task reading order - ROADMAP: M1-M5 with verifiable acceptance criteria, phase-2 fence - GLOSSARY: canonical Chinese-term → code-name mapping - docs/adr/: eight ADRs recording settled decisions and rejected alternatives - docs/open-questions.md: consolidated TODO(业务) tracker by owner and blocking milestone - .gitignore; untrack .DS_Store Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr 🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh
2026-09-01 21:13:00 -04:00 · 2026-09-01 21:13:00 -04:00 · 80835138e9
commit 80835138e9
parent 26c3b13dbd
15 changed files with 503 additions and 0 deletions
--- a/.DS_Store
+++ b/.DS_Store
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,22 @@
+# OS
+.DS_Store
+
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.*
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Mastra / build
+.mastra/
+
+# Eval run artifacts (archived runs live in object storage, not git)
+packages/evals/reports/runs/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,74 @@
+# CLAUDE.md — agent operating manual
+
+Design docs live in `docs/` (00–13, Chinese). They are the specification; this
+file distills what is **binding** when writing code. When code and docs conflict,
+docs win — or write an ADR changing the doc first.
+
+## Current phase
+
+Docs complete, implementation not started. Build order is ROADMAP.md (M1→M5).
+Do not start a milestone's work before its predecessor's acceptance criteria are
+testable, and do not build phase-2 items (edge control links, federation,
+interaction/load-control agents) unless explicitly asked.
+
+## Hard rules (from docs/01 invariants — treat as review criteria)
+
+1. **LLM never computes numbers.** Any numeric field in a `Proposal` payload must
+   be a `{toolCallId, path}` reference into recorded tool-call lineage,
+   dereferenced by the assembler. If you find yourself parsing a number out of
+   LLM text into a payload, stop — that's the architecture's one forbidden move.
+2. **No LLM in any control path.** Nothing under `services/` or the execution
+   path may import or await an LLM call. Periodic workflows must run with the
+   LLM backend down (invariant I6 — there is a test for this).
+3. **External effects only via `(Proposal, ExecutionPermit)`.** Gateways/adapters
+   never accept a bare plan. Permits are short-lived and revocable.
+4. **AI cannot approve.** No code path may transition a Proposal to
+   APPROVED/AUTHORIZED without either a matched envelope + passing checks, or a
+   human `resume()` with an approver identity distinct from the origination chain.
+5. **Everything auditable.** State transitions, tool calls, approvals, permits,
+   and gateway receipts are event-sourced. Snapshots referenced by lineage are
+   immutable.
+6. **Schemas live in `packages/domain` only.** Python models are generated from
+   `contracts/*.schema.json` — never hand-edit generated files, never define a
+   business object schema anywhere else.
+
+## Conventions
+
+- **Naming**: use the canonical code names in GLOSSARY.md. Do not invent new
+  English names for domain terms that already have one.
+- **Language**: architecture docs Chinese; code, identifiers, comments, commit
+  messages, ADRs English.
+- **Data representation** (docs/11 §3.3): money/energy/prices as fixed-point
+  decimal **strings**; units in field names (`power_mw`, `price_yuan_per_mwh`);
+  timestamps ISO8601 UTC; market intervals as `{date, interval_index}` with
+  `interval_minutes` explicit; all IDs strings; enums UPPER_SNAKE string literals.
+- **Mastra**: do not trust memorized APIs — check `node_modules/@mastra/*/dist/docs/`
+  (or the mastra skill) against the installed version before writing framework code.
+- **Testing floor**: every invariant above has at least one automated test;
+  schema changes run golden-fixture validation on both TS and Python sides;
+  policy pack changes require their rule tests green.
+
+## Do not
+
+- Do not invent business parameters (market deadlines, envelope bounds, loss
+  budgets, buffer coefficients). Check `docs/open-questions.md`; if a needed
+  parameter is listed there, wire it as named config with a placeholder value
+  and a `// OPEN-QUESTION:` comment, and say so in your summary.
+- Do not relitigate decisions recorded in `docs/adr/`. If a decision must
+  change, propose a superseding ADR.
+- Do not create root-level summary docs that duplicate `docs/` content
+  (no architecture.md / tech-stack.md — README points to the sources of truth).
+- Do not add a sixth agent, merge the safety chain into business workflows, or
+  bypass the proposal lifecycle for "internal" effects — these were considered
+  and rejected (see ADRs 0005–0007).
+
+## Reading order for common tasks
+
+| Task | Read first |
+|---|---|
+| Domain schemas / contracts | docs/11, docs/00 §4, GLOSSARY.md |
+| Runtime, workflows, agents | docs/09, docs/02 |
+| Safety chain, approvals, permits | docs/03, docs/01 invariants |
+| Skill services (Python) | docs/05 §1–2, docs/11 §3 |
+| Anything touching money or bids | docs/07 (scenario), docs/13 §1 |
+| Eval harness | docs/12 |
--- a/GLOSSARY.md
+++ b/GLOSSARY.md
@ -0,0 +1,68 @@
+# GLOSSARY — 术语 → canonical code names
+
+Docs are Chinese, code is English. **Use these exact names**; do not coin
+alternatives. Columns: term, code name (type/identifier), meaning, defining doc.
+
+## Core business objects
+
+| 中文 | Code name | Meaning | Doc |
+|---|---|---|---|
+| 建议 | `Proposal` | Any action the AI wants taken; carries digest + lineage | 03 |
+| 运行包络（授权） | `Envelope` | Pre-approved autonomy bounds (authority, downward) | 03 |
+| 灵活性包络（能力） | `FlexibilityEnvelope` | Adjustable capability report (capability, upward; federation artifact) | 04/10 |
+| 执行许可 | `ExecutionPermit` | Short-lived revocable execution credential | 03 |
+| 审批 | `Approval` | Human decision bound to a proposal digest + validity window | 03 |
+| 持仓账本 | `PositionLedger` / `PositionUpdate` | Shared per-timescale position & constraint cascade | 00/04 |
+| 运营工单 | `DecisionCase` | Operator's unit of accountability (one objective/owner/deadline) | 02 |
+| 政策包 | `PolicyPack` | Versioned, tested, executable rule bundle | 05 |
+| 态势报告 | `SituationReport` | Analysis agent output: state, anomalies, risk | 02 |
+| 资源画像 | `ResourceProfile` | Capacity, constraints, reliability score | 02 |
+| 预测集 | `ForecastBundle` | Curves + quantile intervals + model version | 05 |
+| 承诺 | `Commitment` | User or inter-province delivery commitment | 10 |
+| 执行回执 / 执行报告 | `ExecutionReceipt` / `ExecutionReport` | Idempotent effect receipt / execution outcome | 04 |
+| 复盘结论 | `ReviewFinding` | Structured lesson from review, written back to memory | 02 |
+| 调度指令 | `DispatchOrder` | Post-permit decomposed instruction | 04 |
+| 结算 | `Settlement` | Settlement facts from metering | 06 |
+
+## Processes & components
+
+| 中文 | Code name | Meaning | Doc |
+|---|---|---|---|
+| 可信执行链 | safety chain, `proposal-lifecycle` workflow | Rule check → simulation → gate → permit → release | 03 |
+| 规则校核 | rule check, `PolicyEnginePort` | Deterministic compliance/constraint validation | 03/11 |
+| 仿真验证 | simulation, `SimulationPort` | Revenue backtest (bids) / power-balance (control) | 03 |
+| 现势复核 | fresh-state check, `FRESH_CHECK` | Pre-release re-verification; failure → `STALE` | 03 |
+| 包络检查 | envelope gate, `EnvelopePort.match` | Within-bounds → auto-approve | 03 |
+| 授权 | `AuthorityPort.authorize` | Issues ExecutionPermit | 11 |
+| 复盘 | review (not "replay", not "retrospective" in code) | D+1 deviation attribution loop | 02 |
+| 血缘 | lineage | Tool-call provenance attached to proposals | 03/09 |
+| 事件信封 | `EventEnvelope` | Typed event wrapper with schemaVersion/causation | 11 |
+| 认知平面 / 控制平面 | cognitive plane / control plane | Slow LLM loop / fast deterministic loop | 00 |
+| 聚合单元 | `AggregationUnit` | VPP aggregation layer between province and sites | 04 |
+| 边缘控制终端 | edge terminal | Second-level local closed loop | 04 |
+| 熔断 | circuit breaker / kill switch (L0–L4) | Graduated shutdown hierarchy | 13 |
+| 影子运行 | shadow run/mode | Full loop, simulated external effects | 08 |
+
+## Market & domain terms
+
+| 中文 | Code name / abbrev | Meaning |
+|---|---|---|
+| 虚拟电厂 | VPP | Virtual power plant |
+| 现货市场 | spot market | Hubei electricity spot market |
+| 日前 / 日内 / 实时 | `DAY_AHEAD` / `INTRADAY` / `REALTIME` | Timescale enum values (also `ANNUAL`, `MONTHLY`) |
+| 申报 | bid (submission: declaration) | Market bid/declaration; `Proposal{type: BID}` |
+| 出清 / 中标 | clearing / award | Market clearing result |
+| 96 点 | 96 intervals | 15-min intervals per day; `{date, interval_index}` |
+| 需求响应 | DR, demand response | |
+| 辅助服务 / 调频 | ancillary services / frequency regulation | |
+| 可调资源 / 可调负荷 | flexible resource / flexible load | Adjustable capacity |
+| 可中断负荷 | interruptible load | Contracted curtailable load |
+| 邀约 / 履约 | invitation / fulfillment | User solicitation; commitment delivery |
+| 基线 | baseline | DR measurement baseline |
+| 偏差考核 | deviation assessment | Penalty regime for plan-vs-actual gaps |
+| 代理购电 | proxy purchase / retail agency | Buying on behalf of contracted users |
+| 源网荷储 | source-grid-load-storage | Coordinated optimization scope |
+| 光明电力大模型 | GuangMing power LLM (`guangming` adapter id) | State Grid's foundation model |
+| 等保 | MLPS | Multi-Level Protection Scheme (security compliance) |
+| 电科院 | EPRI (Hubei) | State Grid Hubei Electric Power Research Institute |
+| 3060 平台 | legacy `3060` platform | Existing platform being overlaid (docs/06 §4) |
--- a/README.md
+++ b/README.md
@ -0,0 +1,57 @@
+# VPP AI Platform · 虚拟电厂多时空协同智能运营平台
+
+AI-assisted operations platform for a virtual power plant (VPP) in Hubei, China:
+five LLM agents propose market bids, resource dispatch, and load-control plans;
+a deterministic safety chain (rule check → simulation → envelope/human approval →
+execution permit) governs everything before any external effect. **The LLM never
+computes numbers and never touches the second-level control loop.**
+
+**Status: architecture/design phase.** No implementation code yet. The design is
+complete and internally consistent (docs 00–13); implementation follows
+[ROADMAP.md](ROADMAP.md), starting with M1.
+
+## Orientation
+
+| You are… | Start with |
+|---|---|
+| A coding agent about to implement | [CLAUDE.md](CLAUDE.md), then docs/00, 01, 09, 11 |
+| New to the project | [docs/00-overview.md](docs/00-overview.md) → [docs/07-scenario-walkthrough.md](docs/07-scenario-walkthrough.md) (the end-to-end reference scenario) |
+| Reviewing the business case | [proposal.md](proposal.md) (申报材料, source of requirements) |
+| Looking for a settled decision | [docs/adr/](docs/adr/) |
+| Wondering what's still undecided | [docs/open-questions.md](docs/open-questions.md) |
+
+## Document map (docs are in Chinese; implementation-facing files in English)
+
+| Doc | Content |
+|---|---|
+| [00-overview](docs/00-overview.md) | System context, two-plane architecture, business objects |
+| [01-principles](docs/01-principles.md) | 9 principles + 8 hard invariants (binding for all code) |
+| [02-cognitive-plane](docs/02-cognitive-plane.md) | Five agents, Runtime, memory, Case Desk |
+| [03-safety-chain](docs/03-safety-chain.md) | Proposal state machine, envelopes, permits, staleness |
+| [04-control-plane](docs/04-control-plane.md) | Execution engine, edge autonomy, time/space cascades |
+| [05-skills-and-data](docs/05-skills-and-data.md) | Skill contracts, five-store data layer, policy packs |
+| [06-integration](docs/06-integration.md) | External system boundaries and degraded channels |
+| [07-scenario-walkthrough](docs/07-scenario-walkthrough.md) | Day-ahead spot bidding, D-1 → D → D+1 |
+| [08-implementation](docs/08-implementation.md) | Stack, LLM abstraction, deployment, milestones |
+| [09-runtime-implementation](docs/09-runtime-implementation.md) | Runtime on Mastra: workflows, suspend/resume, lineage |
+| [10-federation](docs/10-federation.md) | Cross-province boundary: signed artifacts only |
+| [11-contracts](docs/11-contracts.md) | Ports, canonical objects, TS↔Python contract pipeline |
+| [12-evaluation](docs/12-evaluation.md) | Four-layer evals, change gates, KPI definitions |
+| [13-risks-failure-modes](docs/13-risks-failure-modes.md) | FMEA, top-5 risks, kill-switch hierarchy |
+
+Supporting: [brainstorming.md](brainstorming.md) is an independent peer review
+whose findings were integrated (see docs/01 invariants note);
+[GLOSSARY.md](GLOSSARY.md) maps Chinese domain terms to canonical code names.
+
+## Target repository layout (from docs/09 §7)
+
+```
+packages/
+├── domain/       # zod schemas — single source of truth for all business objects
+├── runtime/      # Mastra instance, workflows, agents, tool registry, triggers
+├── services/     # deterministic services: policy engine, envelopes, ledger, authority
+├── adapters/     # anti-corruption layers: trading platform, dispatch, metering
+├── evals/        # eval harness, datasets, judges (docs/12 §5)
+└── skills-py/    # Python skill services (forecasting, MILP optimization, simulation)
+contracts/        # generated JSON Schema + golden fixtures (cross-language contract)
+```
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -0,0 +1,91 @@
+# ROADMAP
+
+Phase 1 (系统研发与省内能力落地, 2025.12–2026.5) as five milestones. Each has
+acceptance criteria a coding agent can verify. Sequencing rationale: M1–M3 need
+no external-party scheduling; the demo-able bidding loop lands earliest
+(docs/08 §4). Phase 2 items are listed but **not to be built yet**.
+
+## M1 — Data foundation & contracts
+
+Deliverables:
+- `packages/domain`: zod schemas for the 07-scenario object set — `Proposal`
+  (+digest), `Approval`, `ExecutionPermit`, `Envelope`, `PositionLedger`/`PositionUpdate`,
+  `ForecastBundle`, `SituationReport`, `ResourceProfile`, `DecisionCase`, `EventEnvelope`.
+- `contracts/`: JSON Schema export pipeline + golden fixtures; pydantic codegen
+  wired for `skills-py`; dual-side contract tests in CI.
+- Ingestion pipeline skeleton: time-series store + relational store + snapshot
+  store (immutable, checksummed); data-quality gate stub.
+- Ledger service v1: read with version, append, per-timescale views.
+
+Accept when: golden fixtures validate identically in TS and Python CI; a ledger
+constraint-cascade test passes (monthly position bounds a day-ahead write);
+snapshots are content-addressed and immutable.
+
+## M2 — Skills v1 & eval baseline
+
+Deliverables:
+- `skills-py`: load forecast, PV forecast, price forecast (all with quantile
+  intervals), bid-optimization MILP, report generator. HTTP/JSON per contracts.
+- `packages/evals`: harness + L2 baselines (MAPE, interval coverage, backtest
+  revenue vs naive/hindsight bounds) on historical data.
+
+Accept when: forecasts return calibrated quantiles (coverage test); MILP output
+respects ledger constraints in property tests; eval runs are reproducible and
+archived; baseline report exists for each skill.
+
+## M3 — Runtime, two agents, safety chain, Case Desk
+
+Deliverables:
+- `packages/runtime`: Mastra instance; trigger service (cron/event/manual);
+  router agent with template-enum output; `registerSkill` lineage wrapper;
+  outbox event bus.
+- Workflows: `day-ahead-situation`, `day-ahead-bid`, `proposal-lifecycle`
+  (rule check → simulation → envelope gate with suspend/resume → fresh check →
+  permit → release).
+- `packages/services`: policy engine v1 (+ first Hubei policy pack, from
+  open-questions once confirmed), envelope service, authority service (permits),
+  audit/lineage assembly.
+- Case Desk v1: approval inbox (resume endpoint), case view, lineage expansion.
+- Bid release path = file export for manual upload (degraded channel by design).
+
+Accept when: docs/07 timeline 06:00→08:30 runs end-to-end on historical data;
+all eight invariant tests pass (incl. LLM-down degraded run and AI-self-approval
+rejection); a suspended approval survives process restart; permit expiry blocks
+a late release.
+
+## M4 — Resource agent, envelopes live, review loop
+
+Deliverables:
+- Resource dispatch agent + potential-assessment skill + award-decomposition flow.
+- Envelope model end-to-end: bounded auto-approval, deviation-streak suspension,
+  envelope re-approval workflow.
+- Review (复盘) workflow: ledger plan-vs-actual per timescale, attribution,
+  `ReviewFinding` writebacks (semantic memory, reliability scores, envelope
+  recommendations).
+- AI insight cards embedded in existing business pages (read-only projections).
+
+Accept when: docs/07 D-1 16:00 and D+1 sections run; a ReviewFinding measurably
+updates a ResourceProfile reliability score; envelope suspension triggers on a
+seeded deviation streak.
+
+## M5 — Shadow run (phase-1 acceptance form)
+
+Deliverables:
+- Full loop on live data, all external effects simulated (bids generated, not
+  submitted; commands to a simulation gateway).
+- Daily shadow-vs-human-vs-hindsight comparison report; KPI dashboard per
+  docs/12 §4 definitions.
+- Loss circuit-breaker, abnormal-day protocol, kill-switch L0–L2 implemented
+  and drilled once.
+
+Accept when: 20+ consecutive shadow days with complete lineage; KPI report
+auto-generated; one envelope-widening recommendation produced from shadow data
+(not acted on — that's a phase-2 governance step).
+
+## Phase 2 (do not build in phase 1)
+
+Interaction-service & load-control agents; edge control links (real protocols);
+trading-platform programmatic submission; dispatch/metering live interfaces;
+federation gateway (build `FlexibilityEnvelope` schema in M1 — the three
+no-rework reservations of docs/10 §5 are in scope for phase 1 schemas only);
+controlled live bidding → gradual envelope widening.
--- a/docs/adr/0001-typescript-mastra-core-python-skills.md
+++ b/docs/adr/0001-typescript-mastra-core-python-skills.md
@ -0,0 +1,16 @@
+# ADR-0001: TypeScript + Mastra core, Python skills
+
+**Status**: accepted · 2026-09
+
+**Context**: Runtime needs durable workflows with suspend/resume (hours-long
+approvals), typed tool contracts, agent primitives. Forecasting/MILP/simulation
+need the Python ecosystem and suit the partner teams (WHU, EPRI).
+
+**Decision**: Agent runtime, workflows, domain schemas, deterministic services
+in TypeScript on Mastra. All numeric/ML skills as Python HTTP services.
+
+**Alternatives**: Python end-to-end (LangGraph) — weaker typed contracts,
+one team owns everything; Java/Spring core — heavier, slower iteration.
+
+**Consequences**: Cross-language contract pipeline required (ADR-0002).
+Mastra APIs must be verified against installed version (evolves fast).
--- a/docs/adr/0002-zod-schema-source-of-truth.md
+++ b/docs/adr/0002-zod-schema-source-of-truth.md
@ -0,0 +1,20 @@
+# ADR-0002: zod as schema source of truth
+
+**Status**: accepted · 2026-09
+
+**Context**: Business objects cross TS runtime ↔ Python skills; schema drift
+between languages is the classic failure. Someone must own the truth.
+
+**Decision**: Hand-written zod schemas in `packages/domain` are the only
+source. Build exports JSON Schema to `contracts/` (committed, versioned);
+pydantic models are generated from those (never hand-edited). Golden fixtures
+validated by both CIs. Data representation rules in docs/11 §3.3 are part of
+the contract (decimal strings for money, units in field names, etc.).
+
+**Alternatives**: Hand-written JSON Schema as neutral source (revisit if
+Python-side partners need co-ownership — the contracts/ layer stays identical);
+protobuf/gRPC (rejected: call volume doesn't need it, lineage snapshots should
+be human-readable, partner onboarding cost).
+
+**Consequences**: Python teams depend only on `contracts/`, never on TS
+internals — org boundary = code boundary.
--- a/docs/adr/0003-provider-abstracted-llm.md
+++ b/docs/adr/0003-provider-abstracted-llm.md
@ -0,0 +1,16 @@
+# ADR-0003: Provider-abstracted LLM
+
+**Status**: accepted · 2026-09
+
+**Context**: Production mandates 光明电力大模型 (on-prem, spec unknown at design
+time); development can't wait for access.
+
+**Decision**: All LLM calls go through a capability-oriented abstraction with a
+model router: commercial API in dev, local open model in preprod, GuangMing
+adapter in prod. Conservative assumptions until spec arrives: OpenAI-compatible,
+8K context, no native tool calling (degrade to prompt+JSON+retry). Backend swap
+is gated by the L1 eval suite plus L4 shadow comparison (docs/12 §3), not judgment.
+
+**Consequences**: No vendor-specific features in agent code; prompts and tool
+definitions maintained provider-portable; phase-1 acceptance must not depend on
+GuangMing access (docs/13 §7).
--- a/docs/adr/0004-postgres-outbox-before-kafka.md
+++ b/docs/adr/0004-postgres-outbox-before-kafka.md
@ -0,0 +1,15 @@
+# ADR-0004: Postgres transactional outbox first, Kafka later
+
+**Status**: accepted · 2026-09
+
+**Context**: Event bus carries business objects (P4) and is the audit backbone
+(P5). Phase-1 volume is bid-frequency, not telemetry-frequency.
+
+**Decision**: Phase 1 uses a Postgres transactional outbox (business write +
+event in one transaction) with polling/LISTEN consumers, behind a thin bus
+interface. Phase 2 relays the outbox into Kafka when telemetry-scale events
+arrive; consumer interface unchanged.
+
+**Consequences**: Exactly-once-ish semantics via same-DB transactionality in
+phase 1; events reconcile trivially against business data. Bus abstraction must
+not leak Postgres specifics.
--- a/docs/adr/0005-single-proposal-lifecycle-workflow.md
+++ b/docs/adr/0005-single-proposal-lifecycle-workflow.md
@ -0,0 +1,17 @@
+# ADR-0005: Safety chain as one proposal-lifecycle workflow
+
+**Status**: accepted · 2026-09
+
+**Context**: Every proposal type (bid, invitation, control plan, dispatch plan)
+must pass rule check → simulation → envelope gate → fresh check → permit.
+
+**Decision**: One `proposal-lifecycle` workflow implements the state machine for
+all types. Business workflows end by submitting a Proposal; the lifecycle
+workflow takes over. Approval resume, timeout escalation, and audit target this
+single code path.
+
+**Alternatives**: Inline safety steps in each business workflow — rejected:
+five slightly-divergent safety chains are how audit gaps are born.
+
+**Consequences**: Type-specific behavior (which simulation, which policy pack)
+is data/config on the Proposal, not workflow structure.
--- a/docs/adr/0006-envelope-tiered-autonomy.md
+++ b/docs/adr/0006-envelope-tiered-autonomy.md
@ -0,0 +1,17 @@
+# ADR-0006: Envelope-based tiered autonomy
+
+**Status**: accepted · 2026-09
+
+**Context**: Per-action human approval contradicts the ≤3-min decision KPI and
+daily bidding cadence; full autonomy contradicts the mandate that AI never
+directly controls.
+
+**Decision**: Humans approve *envelopes* (policy-level bounds with validity
+windows, multi-level approval); in-envelope actions auto-pass after rule check +
+simulation; out-of-envelope or simulation-flagged actions escalate to humans.
+Envelopes start empty and widen only on L4 shadow/online evidence (docs/12 §3);
+deviation streaks auto-suspend them. Precedent: AGC regulation-band delegation.
+
+**Consequences**: Autonomy growth is itself auditable. Approval queue shrinks to
+genuine anomalies — also the main countermeasure to approval complacency
+(docs/13 §3).
--- a/docs/adr/0007-review-is-workflow-not-sixth-agent.md
+++ b/docs/adr/0007-review-is-workflow-not-sixth-agent.md
@ -0,0 +1,15 @@
+# ADR-0007: Review (复盘) is a workflow, not a sixth agent
+
+**Status**: accepted · 2026-09
+
+**Context**: The proposal alternates between five agents and six business stages
+(review appearing as a sixth agent in some slides).
+
+**Decision**: Review is a cross-agent workflow template led by the analysis
+agent, triggered by metering-data arrival. Its authoritative inputs are the
+ledger and event log; its outputs are `ReviewFinding` writebacks (semantic
+memory, reliability scores, envelope recommendations).
+
+**Rationale**: Review is an analysis task; a dedicated agent would duplicate the
+analysis agent's role. Agent names are product personas, not service boundaries
+(peer review §4.1).
--- a/docs/adr/0008-cases-for-humans-workflows-for-machines.md
+++ b/docs/adr/0008-cases-for-humans-workflows-for-machines.md
@ -0,0 +1,16 @@
+# ADR-0008: Cases for humans, workflows for machines
+
+**Status**: accepted · 2026-09
+
+**Context**: Operators need a unit of accountability; the runtime needs a unit
+of execution. Conflating them makes both worse (peer review, Alternative C).
+
+**Decision**: `DecisionCase` (one objective, owner, deadline, completion
+contract) is the operator-facing aggregation; workflows are internal execution.
+A case references the products of several workflows via `case_id`. Dashboards,
+approval inboxes, and reports are projections over cases + ledger + event log,
+not standalone feature silos.
+
+**Consequences**: UI work targets case views; a case must never become an
+unbounded container (enforced: one objective per case, mandatory completion
+contract).
--- a/docs/open-questions.md
+++ b/docs/open-questions.md
@ -0,0 +1,59 @@
+# Open Questions — 业务参数与待决事项清单
+
+Consolidates every `TODO(业务)` scattered in docs 03/07/12/13 plus unresolved
+items from the peer review (brainstorming.md §16). **Coding agents: never invent
+values for items on this list** — wire named config with placeholder + an
+`// OPEN-QUESTION:` comment (see CLAUDE.md).
+
+## A. 湖北市场参数（owner: 运营/交易团队 · blocks M3 policy pack + 07 篇定稿）
+
+| # | Question | Config key (suggested) |
+|---|---|---|
+| A1 | 日前申报窗口开启/截止时间；出清发布时间 | `market.da.window` |
+| A2 | 代理购电申报与虚拟电厂申报是否同一通道/分开建模 | `market.channels` |
+| A3 | 日内市场机制（是否开、频次、截止） | `market.intraday` |
+| A4 | 偏差考核规则：偏差带、考核价格机制（→ MILP 目标函数与风险口径） | `market.deviation` |
+| A5 | 中长期持仓对日前申报的约束形式（分解曲线偏差带） | `ledger.da_bounds` |
+
+## B. 包络与风控参数（owner: 运营团队 · blocks M4 envelopes + M5 breakers）
+
+| # | Question | Config key |
+|---|---|---|
+| B1 | 申报包络：价格边界的基准（预测值?历史分位?）与初始容差 | `envelope.bid.*` |
+| B2 | 控制包络：分资源类型的单点削减上限与恢复速率 | `envelope.control.*` |
+| B3 | 包络审批层级 L1/L2/L3 对应岗位/会签流程 | `approval.levels` |
+| B4 | 包络挂起条件：连续 N 次偏差超阈的 N 与阈值 | `envelope.suspension` |
+| B5 | 单日亏损预算（L2 熔断阈值） | `breaker.daily_loss_budget` |
+| B6 | 承诺缓冲系数 k 初值 | `bidding.commitment_buffer` |
+| B7 | 极端日协议触发的气象条件 | `abnormal_day.triggers` |
+| B8 | 各级熔断（L0–L4）授权岗位与恢复条件 | `breaker.authority` |
+| B9 | 演习样本制度：频率与考核挂钩方式 | — (制度非配置) |
+
+## C. KPI 口径（owner: 运营 + 验收双方 · blocks M5 dashboard）
+
+| # | Question |
+|---|---|
+| C1 | docs/12 §4 全表口径确认，尤其「综合市场收益提升 15%」的对照基线定义与冻结 |
+| C2 | 预测误差 8% 的统计层级（聚合级?分用户?）与光伏口径（nRMSE?） |
+
+## D. 外部依赖（owner: PMO/省间协同组 · blocks phase 2, start engagement in phase 1）
+
+| # | Question |
+|---|---|
+| D1 | 光明电力大模型接口规格：协议、上下文、工具调用、部署位置、网络分区（ADR-0003 假设待证实） |
+| D2 | 交易平台程序化申报接口协议与联调排期 |
+| D3 | 调度/负荷管理、计量结算接口协议与排期 |
+| D4 | 省级↔聚合单元↔边缘现有协议与时延保证（peer review Q6） |
+| D5 | 首批转为政策包的湖北规则清单（peer review Q7） |
+
+## E. 治理决策（owner: 项目领导小组）
+
+| # | Question |
+|---|---|
+| E1 | 一期验收形态确认：影子运行（推荐，见 ROADMAP M5）vs 受控实报（peer review Q3） |
+| E2 | 既有 3060 平台各实体的 source-of-truth 矩阵签认（docs/11 §2 表为草案） |
+| E3 | 边缘断连策略的「安全曲线」定义权与更新流程 |
+
+---
+*Process*: when an item is answered, move the value into config/docs, mark the
+row `✓ resolved <date> → <where recorded>`, and keep the row for audit.