Adds a consolidated invariant layer (INV-1..INV-5) so that context-isolated
implementers (e.g. parallel isolated subagents holding only one subsystem
slice) cannot violate global rules they cannot see in their slice.
- INV-1: session-DB state columns written only by event projection, with an
authoritative table→event map and explicit heartbeat/ui_state exemptions.
This is the rule the O2 finding violated; centralizing it prevents recurrence.
- INV-2: cross-DB writes use outbox + single writer.
- INV-3: side effects only through ToolRegistry → PermissionEngine.
- INV-4: one-way import/dependency direction.
- INV-5: EventBus is transport, never a source of truth.
Each affected subsystem chapter (§5/§7/§8/§9/§11) now opens with an
"Applicable invariants (§18.6)" pointer so the constraint travels with the
slice. Pure documentation consolidation of already-frozen rules; zero change
to contracts, events, schema, or runtime semantics.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
An Opus-perspective semantic re-audit (reading state-machine semantics,
event-sourcing invariants, and baseline together rather than grep-style
structural checks) surfaced two issues the prior seven rounds missed.
O2 [P1] §5.4 + §20.4: removed the event-less `starting → running` status
transition. The prior R1-02 fix eliminated the same-event atomicity error
but left a second status-machine arc that (a) has no basis in baseline
(event-registry §3 says agent.started inserts status = running OR starting,
with no second transition) and (b) had WorkerManager UPDATE agents.status
directly, bypassing the event log and violating runtime-semantics §3
(all same-session domain updates go through BEGIN→insert events row→
project→COMMIT). agents.status is now written only by agent.* projection;
worker.ready handshake is clarified as a live IPC signal, not a status write.
O1 [P2] §5.4: MemoryRepository (an orphan name appearing exactly once,
never defined in §4.3/§11.3/contracts/code-view) corrected to
LearnedMemoryStore, matching §11.3 and the §21.3 traceability matrix.
Detailed design re-frozen with these corrections.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Seven rounds of multi-model review across five models (DeepSeek, MIMO 2.5 Pro,
GPT-5.5 Pro, Opus 4.7, Opus 4.8) with zero remaining P0/P1/P2 findings.
Coverage final: contracts 100%, events (55 durable + 7 ephemeral) 100%,
DB schema (16+1+2 tables) 100%, state machines (6 of 6) 100%, forbidden
edges (10 of 10) enforced, UML class diagrams (8 of 8) verified.
§23 checklist now split into design-verified (all checked) and
implementation-entry gates (to verify as code is written).
Frozen. Proceed to implementation.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Independent full-scope audits by Opus 4.8 (R6) and DeepSeek V4 Pro (R7)
converged on the same four P2 findings. This commit closes all four:
F1 §10.2: EvidenceStore.list_for_task() → list_for_entity("task", task_id)
The fictional method list_for_task() was not in contracts §14. Now uses
the real contract method list_for_entity() with task as entity_type.
F5 §16.1: DoctorService.check_capability() changed from public (+) to
private (-) with a clarifying comment. Only run() is in contracts §19.
F2 §22.7: Context and Compaction class diagram now shows the internal
dependency edges ContextAssembler ..> EvidenceStore (L6) and
ContextAssembler ..> SessionStore (L7/L8), matching §10.2.
F3 §22.4: Tool and Permission class diagram now shows ToolRegistry -->
ToolDefinition (registers) and ToolRegistry --> ToolExecutor (invokes),
matching §9.1.
Also adds the two full-scope review reports that identified these findings.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Independent regression audit (Opus 4.7) verified P1×4 + P2×9 fixes were
closed but found that three of the P2 fixes had introduced new baseline
violations and two had minor errors. This commit closes all five.
R-series fixes (in system-detailed-design.md):
- R1-01 §10.2: L2 Safety source no longer names a fictional
PermissionEngine.current_profile() method. The L2 row now describes
the active permission profile sources (~/.air/permissions.yaml +
project permission config) without inventing a contract method,
honoring DD §0 "no new public contracts."
- R1-02 §5.4 Table A: agent.started projection no longer claims a
two-step "starting → running" update within a single event commit
(which would violate event atomicity). The row now matches
event-registry §3: a single status (starting or running) at emission
time, with the follow-up transition handled by WorkerManager per the
state machine in §20.4.
- R1-03 §18.4 + §5.4 Table B: removed the non-baseline phase: intent |
committed payload-field extension from memory.promoted and
debug.record.created. Outbox semantics now follow the baseline model:
owning store performs the external write first, then ingests a single
durable completion event whose payload matches event-registry §3
exactly. Any future intent/commit split must go through an ADR plus
payload version bump.
- R2-01 §7.5: corrected workspace responsibility cross-reference from
"overview §10.5" (Direct mode) to "overview §10.3" (Scheduler state
machine, which actually covers workspace assignment and merge).
- R2-02 §3: resolved self-contradiction in the contracts file-set
decision. The 16 files are now stated as mandatory with default
inlining of all overview §4 symbol groups for V1.0.0 Alpha; any
future split is explicitly out of scope until an ADR is added.
Also adds opus4.7详细设计与UML审查.md documenting the regression
findings, baseline-evidence trails, and recommended fixes that drove
these changes.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Apply all remaining P2-level repairs identified by the four-model
cross-review (DeepSeek, MIMO 2.5 Pro, GPT-5.5 Pro, Opus 4.8) and
verify by regression:
- P2-01 Architecture Designer gate sequence: add a dedicated §19.4
sequence diagram covering trigger → impact assessment → result
class (silent_continue/requires_user_confirmation/requires_replan/
reject_or_escalate) → doc update via ToolRegistry → Scheduler
consumption. Renumber Debug knowledge capture to §19.5.
- P2-02 CLI catalog command class ownership: replace the prose
inventory with an explicit class-to-subcommand table covering
RunCommand, InitCommand, DoctorCommand, ProviderCommand,
E2ECommand, ReleaseCommand, ResumeCommand, CompactCommand,
HistoryCommand, SessionListCommand, RestoreCommand.
- P2-03 agent.started projection wording: clarify the two-step
domain update (starting upon spawn intent, running on handshake
ack within the same event commit) and what carries the final
state row at commit time.
- P2-04 WorkspaceManager vs. Scheduler responsibility split: add a
policy/mechanism responsibility matrix to §7.5 making Scheduler
the sole policy owner (strategy choice, conflict resolution) and
WorkspaceManager the sole mechanism owner (materialize, merge,
cleanup, lifecycle events).
- P2-05 EventStore.project boundary wording: split §5.4 into Table A
(pure projection inside events_session.db transaction) and Table B
(projection intent + post-commit outbox/compensation by owning
service), removing the “write external DB via owner” phrasing from
the in-transaction projection table.
- P2-06 memory.promoted two-phase semantics: rewrite §18.4 to
document the intent vs. committed phases with payload markers,
retry behaviour, and parity with debug.record.created.
- P2-07 docs task type closure: add a TaskType → WorkerRole mapping
table in §8.3 and a design decision recording that `docs` is a
formal TaskType handled by ExecutorRole with docs-scoped
TaskScope.write_area; events and verification follow the execute
pipeline with type='docs' as the domain-level differentiator.
- P2-08 AgentType vs. runtime roles: add a top-level table in §2
pinning AgentType to worker child-process roles only and naming
the runtime-resident roles (main, architecture_designer,
scheduler) plus their prompt sources and LLM-use flags.
- P2-09 contracts package file set: replace the IMPL note in §3 with
a frozen file-set decision plus an overview §4 symbol-group →
code-view §3 file mapping; new files require an ADR.
Regression confirms: §19 sequence count is now 5; §17 CLI table
covers every catalog command; §5.4 splits projection vs. outbox;
§18.4 documents memory.promoted phase semantics; §8.3 lists docs
under ExecutorRole; §2 names runtime roles; §3 freezes the contracts
file set.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Apply repairs identified by the four-model cross-review (DeepSeek,
MIMO 2.5 Pro, GPT-5.5 Pro, Opus 4.8) and verify by regression:
- P1-01 Worker exit codes: align overview §11 and detailed-design §8.1
with baselineV1 §8 (0 protocol-level completion / 1 uncaught exception
/ 2 startup or protocol error / 3 permission error / 4 parent cancelled
/ 5 hard timeout killed). Record that task outcomes are reported via
WorkerResult.status, not exit codes.
- P1-02 PromptLayerLevel enum: add "safety" to interface-contracts §16
so the enum fully covers prompt-layering-v1 §2 L0-L9 (plus
system_debug applied within L9).
- P1-03 EventStore.project error handling: document in detailed-design
§5.3 that a project() exception rolls back the full transaction,
suppresses EventBus.publish(), returns AirError{kind:"system_error"},
and triggers referential_check() on FK-off inconsistencies.
- P1-04 PromptLayerLoader completeness: record in detailed-design §10.2
that PromptLayerLoader only owns L0/L1/L3/L5 while ContextAssembler
composes L2/L4/L6/L7/L8/L9 from PermissionEngine, TaskSpec,
SessionStore, and ToolRegistry sources; clarify runtime-role prompts.
Regression confirms baselineV1, overview, and detailed-design now share
identical exit code semantics, the PromptLayerLevel enum covers all ten
layers, EventStore error semantics are explicit, and the PromptLayer
loading responsibility split is fully documented.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
