feat: owner 控制与可观测性——pause/abort + TUI 视图 + log 分级（ADR-0013 PR-B）

[randypanding]

基于 #11（PR-A）——请先合并 #11，本 PR base 会自动跟上 main。

解决什么

"可观测性建立起来：有人直接 TUI 查看，有通过询问 agent 查询了解；任务可以暂停、终止；log 需要清晰。"（ADR-0013 系列 PR-B）

核心设计：可观测与控制是一体两面

同一事件流的读端（TUI 视图 / agent 代读）与写端（控制动词），同一入口（TUI/interface-gateway）。不新建设施——分开建设会出现"看得到的状态控不了、控了的动作看不到"。

变更

1. observability.yaml（新建）

• 三原则：read_only（视图无写凭据，写=落事件）/ attention_first（默认页是"等你决策的队列"不是日志流）/ provenance（回答必附 trace_id 引用）
• TUI 六视图：attention（默认）/ now / wave / budget / backlog / trace——视图=事件流的物化查询，声明即规格
• log 三级受众：owner（为什么/卡在哪/花多少）/ 机制（相位+判决理由）/ 审计（全量）——同一事件流三个投影，不是三套日志
• ask 检索：researcher as_tool，与 TUI 同源同投影（结构保证一致）；查不到就说查不到——hallucinated status 比没有 status 危险

2. owner_control（flows.yaml 新节）

• pause：停表停预算（wall_clock 不计暂停时间——owner 思考不应烧卡的时间预算；usd 已花照记，沉没成本是真实的）；执行态（building/verify）才可暂停
• abort：不可逆，reason 必填（每个废动作都该有死因）；reason_routing 三路善后：need_gone→作废 / spec_wrong→退 backlog 接 escape 回路（归因 planner 产卡质量）/ superseded→关联新卡
• 不变式：控制动词=事件不是凭据（TUI 无数据层写凭据）；注意力账本零新增（账本管"系统等 owner"，owner 主动出手不入账）；abort_rate 归因路由准确率而非 builder

3. team-collaboration 对齐

卡生命周期 +paused/aborted 状态（owner_control_ref 单一真源）；event_producers +card.paused/resumed/aborted（owner 经平台通道）；services +tui 机制注册（fail-closed——机制必须有主）；interface_gateway duty 扩展（ask 路由+控制入站）

验证

validate OK + simulate 12 场景全通 + 语义链核对（六视图/三事件有主/tui 注册/状态扩展）。

系列后续：PR-C 场景声明化 + 模拟器引擎化 + CT scenario 链接（测试底层方法统一）。

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ce31fc8-7f56-475f-8aa7-07e0ec40ba70

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Add event-sourced owner controls and observability views

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Defines event-backed TUI views, audience-specific logs, and provenance-aware agent queries.
• Adds owner pause, resume, and abort semantics with lifecycle and budget rules.
• Registers control events, TUI ownership, and gateway responsibilities across collaboration
 standards.

Diagram

sequenceDiagram
  actor Owner
  participant Entry as TUI / Gateway
  participant Researcher
  participant Materializer
  participant Events as Event Stream
  participant Platform as Platform Channel
  Owner->>Entry: View, ask, or control
  alt Read projection
    Entry->>Materializer: Query view or log
    Materializer->>Events: Read events
    Events-->>Materializer: Event history
    Materializer-->>Entry: Materialized projection
    Entry->>Researcher: Route ask request
    Researcher->>Events: Retrieve cited events
    Events-->>Researcher: Traceable evidence
    Researcher-->>Entry: Referenced answer
  else Control card
    Entry->>Platform: Publish control command
    Platform->>Events: Append card event
    Events-->>Materializer: Refresh projection
    Materializer-->>Entry: Updated card state
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Separate observability backend

• ➕ Could provide specialized indexing, retention, and query performance.
• ➕ Would isolate operational telemetry workloads from the primary event stream.
• ➖ Introduces a second source whose state can diverge from card controls.
• ➖ Requires synchronization infrastructure and more complex provenance guarantees.

2. Direct card-state mutation API

• ➕ Provides a simpler command implementation and immediate state updates.
• ➕ Avoids event replay when resolving current card state.
• ➖ Weakens auditability and bypasses append-only event invariants.
• ➖ Requires write credentials in the owner-facing control layer.
• ➖ Makes controls harder to correlate with traces and projected views.

Recommendation: Retain the PR’s unified event-sourced approach because the repository already treats the event stream as its source of truth. It preserves auditability and guarantees that controls, TUI views, logs, and agent answers converge; a derived search index can be added later if projection performance becomes limiting.

Files changed (3) +123 / -2

Enhancement (3) +123 / -2

flows.yamlDefine owner pause, resume, and abort semantics +30/-0

Define owner pause, resume, and abort semantics

• Adds card-level owner controls through the shared TUI and gateway entry. Specifies pause accounting, irreversible abort reason routing, event-only mutation, attribution rules, and control metrics.

standards/flows.yaml

observability.yamlSpecify event-backed observability and control surfaces +73/-0

Specify event-backed observability and control surfaces

• Introduces observability principles, six TUI views, three audience-oriented log projections, and provenance-required agent retrieval. Defines the shared control channel and assigns projection responsibilities to existing mechanisms.

standards/observability.yaml

team-collaboration.yamlRegister TUI services and owner control lifecycle events +20/-2

Register TUI services and owner control lifecycle events

• Extends gateway duties, registers the TUI mechanism, and assigns producers for pause, resume, and abort events. Adds paused and aborted card states while retaining owner-control semantics in flows.yaml as the single source of truth.

standards/team-collaboration.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (0) 📜 Skill insights (0)

1. TUI mechanism lacks trust profile 🐞 Bug ⛨ Security

Description

The new services.tui is a state-affecting mechanism that forwards owner control events, but no
tui mechanism profile defines its implementation, capabilities, or trust boundaries. This defeats
the repository's fail-closed mechanism-registration model and leaves the control surface without an
enforceable authority declaration.

Code

standards/team-collaboration.yaml[R120-123]

+  tui:                               # owner 直读视图与控制面板（ADR-0013 PR-B）
+    kind: mechanism
+    duty: 事件流→视图物化（六视图目录 observability.views）+ 控制动词入站转发
+      （写事件非写状态——read_only 原则）

Relevance

●●● Strong

The repository accepts fail-closed trust and permission declarations; an unprofiled state-affecting
mechanism violates that established pattern.

PR-#3
PR-#5

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR registers tui as a mechanism service and references mechanism:tui, while the mechanism
profiles end without any tui entry. The simulator explicitly describes mechanism profiles as trust
declarations but validates only four pre-existing service names.

standards/team-collaboration.yaml[120-126]
standards/observability.yaml[69-73]
standards/archetype-profiles.yaml[380-432]
scripts/simulate-wave.py[499-520]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new TUI service and `mechanism:tui` reference have no matching mechanism profile. Consequently its read access and event-publication authority are not constrained by the standard capability vocabulary.

## Issue Context
Other mechanism services have profiles with implementation, mission, capabilities, and trust declarations. The trust-chain simulator checks only an older hard-coded set of four services, so it misses the new service.

## Fix Focus Areas
- standards/team-collaboration.yaml[120-126]
- standards/observability.yaml[69-73]
- standards/archetype-profiles.yaml[380-432]
- scripts/simulate-wave.py[499-520]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Ask schema rejects requests 🐞 Bug ≡ Correctness

Description

ask_retrieval sends query-in objects to the researcher, but the researcher's strict tool
contract accepts question-in, whose required fields and property names differ. Ask requests using
the declared schema will therefore fail validation before retrieval and also omit the required
trace_id.

Code

standards/observability.yaml[R51-54]

+ask_retrieval:
+  carrier: researcher as_tool（单次往返，无卡无队）
+  input_schema: registry/schemas/query-in.json
+  contract: 回答必须附 trace_id/card_id/事件引用；查不到就说查不到（禁编造——

Relevance

●●● Strong

Strict contract/schema consistency findings are accepted; this mismatch also omits a required field
and deterministically breaks requests.

PR-#5

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new ask path names researcher as its carrier but selects the web-search tool schema. The
registered researcher has strict output/input contracts and accepts only question-in, which
rejects query and requires both question and trace_id.

standards/observability.yaml[51-56]
registry/agents/researcher-code.yaml[31-41]
registry/schemas/query-in.json[7-17]
registry/schemas/question-in.json[7-24]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The observability ask path declares `query-in.json`, while the researcher as-tool contract requires `question-in.json`. Their required fields are incompatible, so requests cannot pass the researcher's strict input validation.

## Issue Context
`query-in` requires `query`; `question-in` requires `question` and `trace_id`. The latter is also necessary for the observability provenance contract.

## Fix Focus Areas
- standards/observability.yaml[51-56]
- registry/agents/researcher-code.yaml[37-41]
- registry/schemas/question-in.json[7-24]
- registry/schemas/query-in.json[7-17]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Abort terminal state conflicts 🐞 Bug ≡ Correctness

Description

Abort is declared irreversible with aborted as a terminal lifecycle state, but need_gone and
superseded route the same card to the separate terminal state archived. Implementers cannot
determine whether card.aborted ends in aborted, transitions again to archived, or never uses
the newly added aborted state.

Code

standards/flows.yaml[R102-105]

+      target_states: 卡生命周期的任何非终态（终态=merged/archived/aborted）
+      reason_routing:                  # reason 决定善后，不是人决定
+        need_gone: 需求消失 → 卡 archived(作废)；无善后
+        spec_wrong: 规格错了 → 产 escape 类 finding 退 backlog（卡回炉——接 escape 回路：

Relevance

●● Moderate

Semantic lifecycle ambiguity is plausible, but no close historical precedent establishes acceptance
for this exact terminal-state design.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The owner-control contract names aborted among terminal states, then sends two abort reasons to
archived. The lifecycle separately registers both states and explicitly labels aborted as the
owner-controlled terminal state, without defining an aborted → archived transition.

standards/flows.yaml[99-108]
standards/team-collaboration.yaml[295-303]
standards/team-collaboration.yaml[271-273]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The abort contract defines `aborted` as terminal while two reason routes set the original card to `archived`, which is independently terminal. The resulting state transition is ambiguous.

## Issue Context
The lifecycle lists `archived` and `aborted` as distinct states and describes `aborted` as owner termination. Clarify whether all aborts finish in `aborted` with reason-specific side effects, or formally define any subsequent archival transitions and their events.

## Fix Focus Areas
- standards/flows.yaml[99-108]
- standards/team-collaboration.yaml[295-303]
- standards/team-collaboration.yaml[271-273]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Observability standard bypasses validation 🐞 Bug ☼ Reliability

Description

standards/observability.yaml is not loaded by scripts/validate.py, so invalid YAML or broken
observability declarations can merge while CI remains green. The simulator also never consumes it,
despite the PR treating its views and control channel as executable specifications.

Code

standards/observability.yaml[1]

+version: 1

Relevance

●●● Strong

PR #5 explicitly accepted adding every standards YAML to validate.py, directly matching this
validation-bypass finding.

PR-#5

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The validator's complete standard parsing tuple contains four files and omits the newly added
observability file. This repeats the previously accepted failure mode where a standards YAML was
outside the validation load set.

standards/observability.yaml[1-73]
scripts/validate.py[75-85]
PR-#5

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The newly introduced observability standard is absent from the validator's standard-file parsing list and from relevant semantic checks. CI therefore does not protect this standard from syntax errors or dangling mechanism/schema references.

## Issue Context
A prior accepted review established that new standard YAML files must be loaded by `validate.py` so parse failures cannot escape CI.

## Fix Focus Areas
- standards/observability.yaml[1-73]
- scripts/validate.py[75-85]
- scripts/simulate-wave.py[499-520]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 7 rules

Review mode: ⚖️ Balanced: This is a cross-file behavioral contract change affecting owner controls, lifecycle states, event routing, and observability projections; it carries real correctness risk, but the logic is cohesive enough for one careful review rather than redundant passes.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Ask schema rejects requests 🐞 Bug ≡ Correctness

ask_retrieval sends query-in objects to the researcher, but the researcher's strict tool
contract accepts question-in, whose required fields and property names differ. Ask requests using
the declared schema will therefore fail validation before retrieval and also omit the required
trace_id.

Agent Prompt

## Issue description
The observability ask path declares `query-in.json`, while the researcher as-tool contract requires `question-in.json`. Their required fields are incompatible, so requests cannot pass the researcher's strict input validation.

## Issue Context
`query-in` requires `query`; `question-in` requires `question` and `trace_id`. The latter is also necessary for the observability provenance contract.

## Fix Focus Areas
- standards/observability.yaml[51-56]
- registry/agents/researcher-code.yaml[37-41]
- registry/schemas/question-in.json[7-24]
- registry/schemas/query-in.json[7-17]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Tui mechanism lacks trust profile 🐞 Bug ⛨ Security

The new services.tui is a state-affecting mechanism that forwards owner control events, but no
tui mechanism profile defines its implementation, capabilities, or trust boundaries. This defeats
the repository's fail-closed mechanism-registration model and leaves the control surface without an
enforceable authority declaration.

Agent Prompt

## Issue description
The new TUI service and `mechanism:tui` reference have no matching mechanism profile. Consequently its read access and event-publication authority are not constrained by the standard capability vocabulary.

## Issue Context
Other mechanism services have profiles with implementation, mission, capabilities, and trust declarations. The trust-chain simulator checks only an older hard-coded set of four services, so it misses the new service.

## Fix Focus Areas
- standards/team-collaboration.yaml[120-126]
- standards/observability.yaml[69-73]
- standards/archetype-profiles.yaml[380-432]
- scripts/simulate-wave.py[499-520]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

3. Observability standard bypasses validation 🐞 Bug ☼ Reliability

standards/observability.yaml is not loaded by scripts/validate.py, so invalid YAML or broken
observability declarations can merge while CI remains green. The simulator also never consumes it,
despite the PR treating its views and control channel as executable specifications.

Agent Prompt

## Issue description
The newly introduced observability standard is absent from the validator's standard-file parsing list and from relevant semantic checks. CI therefore does not protect this standard from syntax errors or dangling mechanism/schema references.

## Issue Context
A prior accepted review established that new standard YAML files must be loaded by `validate.py` so parse failures cannot escape CI.

## Fix Focus Areas
- standards/observability.yaml[1-73]
- scripts/validate.py[75-85]
- scripts/simulate-wave.py[499-520]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

4. Abort terminal state conflicts 🐞 Bug ≡ Correctness

Abort is declared irreversible with aborted as a terminal lifecycle state, but need_gone and
superseded route the same card to the separate terminal state archived. Implementers cannot
determine whether card.aborted ends in aborted, transitions again to archived, or never uses
the newly added aborted state.

Agent Prompt

## Issue description
The abort contract defines `aborted` as terminal while two reason routes set the original card to `archived`, which is independently terminal. The resulting state transition is ambiguous.

## Issue Context
The lifecycle lists `archived` and `aborted` as distinct states and describes `aborted` as owner termination. Clarify whether all aborts finish in `aborted` with reason-specific side effects, or formally define any subsequent archival transitions and their events.

## Fix Focus Areas
- standards/flows.yaml[99-108]
- standards/team-collaboration.yaml[295-303]
- standards/team-collaboration.yaml[271-273]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools