Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions standards/flows.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -84,3 +84,33 @@ maintain_loop:
executor: stewardship 提请(curator)→ delivery_squad 以 backlog 为波次范围组建
acceptance: pre_approved(复绿即验收——intent-routing maintain;security 级升 owner_ratify)
metrics: [backlog_aging_p50/p95, deferred_count, maintenance_wave_count] # metrics-aggregator 周报

# ---- G. owner 控制(ADR-0014 PR-B:任务暂停/终止——控制动词=事件不是凭据)----
owner_control:
entry: TUI 控制面板 / interface-gateway(observability.control_surface——同一入口)
scope: 卡级(波级冻结已有 wave.frozen——scheduler 预算熔断;owner 控制不重复波级)
verbs:
pause:
semantics: 停表停预算——wall_clock 不计暂停时间(诚实不惩罚的延伸:
owner 暂停思考不应烧掉卡的时间预算);usd 已花照记(沉没成本是真实的)
target_states: [building, verify] # 执行态才可暂停;drafting/ratified 本就未走表
event: "card.paused(producer: owner 经平台通道——observability 同模式)"
resume: 回原相位,走表恢复;暂停时长记入卡时间线(trace 可见)
abort:
semantics: 不可逆终止;reason 必填(落事件——无 reason 的 abort 不可接受:
组织的每个废动作都该有死因,否则 retro 无从归因)
target_states: 卡生命周期的任何非终态(终态=merged/archived/aborted)
reason_routing: # reason 决定善后,不是人决定
need_gone: 需求消失 → 卡 archived(作废);无善后
spec_wrong: 规格错了 → 产 escape 类 finding 退 backlog(卡回炉——接 escape 回路:
Comment on lines +102 to +105

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

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

规格错误是 planner 产卡质量问题,amendment_rate 归因)
superseded: 被更新意图取代 → 关联新卡 id 落事件,原卡 archived
event: "card.aborted(producer: owner 经平台通道)"
invariants:
- "控制动词是事件不是凭据:owner 经 TUI/interface-gateway 落 card.* 事件,
平台执行——TUI 无数据层写凭据(observability.read_only)"
- "注意力账本不新增阻塞点:账本管『系统等 owner』;owner 主动出手(pause/abort)
不入账本——反向的『owner 等系统响应』由 feedback_loop 保证(视图即时反映)"
- "abort 后预算对账:已耗 usd 记账不退(沉没成本入 metrics——abort_rate 高是
intent 质量信号,归因 interface-gateway 路由准确率而非 builder)"
metrics: [pause_count, pause_duration_p95, abort_rate(by reason_routing)]
73 changes: 73 additions & 0 deletions standards/observability.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
version: 1

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

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

# ============================================================================
# Observability —— 可观测性(ADR-0014 PR-B)
# ============================================================================
# 前提:事件流已是唯一事实源(append-only + 哈希链 + trace_id 贯穿
# intent→卡→run→判决→事件——flows.yaml event_integrity)。
# 因此可观测性【不是新建设施】,是同一数据流的两个读端投影:
# 读端 1 = 人直读(TUI 视图)
# 读端 2 = agent 代读(ask 意图 → researcher as_tool 检索)
# 控制动词(pause/resume/abort)是同一接口的写端——但写的是事件不是数据。
#
# 一体两面原则:可观测(读)与控制(写)共用同一事件流与同一入口
# (TUI/interface-gateway)——分开建设会出现"看得到的状态控不了、控了的动作看不到"。
# ============================================================================

principles:
- read_only: 一切视图只读(TUI/查询接口无数据层写凭据——写=落事件,经平台通道;
与 channels.semantics 同源:write=发布事件,非 datastore 直写)
- attention_first: 视图按注意力组织,不按系统内部结构组织——默认页是
"等你决策的队列",不是调试器式日志流
- provenance: 一切回答/视图数据附 trace_id 或 card_id 引用(无引用的回答=断言,
禁止——同 findings sources minItems:1 原则)

# ---- 读端 1:TUI 视图目录(人直读;视图=事件流的物化查询,声明即规格)----
views:
attention: # 默认页:系统在等我什么
query: "owner 阻塞点队列(attention-ledger 全量)+ 各项 SLA 倒计时 + 默认动作预览"
why: owner 打开 TUI 的第一问是"需要我吗",不是"系统在干嘛"
now: # 活跃团队与卡
query: "active teams + in-flight cards + 各卡当前相位(team-collaboration flow.phases)"
wave: # 波次相位图
query: "波次相位图上每张卡的位置 + 相位停留时长 + 阻塞在哪(等判决/等预算/等依赖)"
budget: # 预算燃烧
query: "团队包络/卡预算的已耗/剩余 + 熔断距离 + overhead_pool 余量"
backlog: # 维护回路健康度
query: "backlog 堆积 + aging p50/p95 + deferred 条目及其到期条件(flows maintain_loop)"
trace: # 全链时间线(输入 trace_id 或 card_id)
query: "intent→卡→run→判决→合并→发布 全事件时间线(唯一审计入口;哈希链可验证)"

# ---- log 分级:log 不是独立产物,是事件流的受众投影 ----
logs:
audience_owner: # 默认:为什么/卡在哪/花了多少(决策所需最小集)
content: [阻塞点, 相位停留原因, 预算异常, 判决摘要, 维护回路异常]
audience_mechanism: # 机制运转:相位转换 + 判决理由 + 重试/熔断
content: [phase_transitions, verdict_with_rationale, retries, circuit_breaks]
audience_audit: # 全量(append-only 事件流本体;不裁剪不摘要)
content: [all_events]
rule: 三个受众是同一事件流的三个投影,不是三套日志——分级只发生在读端

# ---- 读端 2:agent 代读(ask 意图——intent-routing.intents.ask)----
ask_retrieval:
carrier: researcher as_tool(单次往返,无卡无队)
input_schema: registry/schemas/query-in.json
contract: 回答必须附 trace_id/card_id/事件引用;查不到就说查不到(禁编造——
Comment on lines +51 to +54

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

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

hallucinated status 比没有 status 危险:owner 据此决策)
equivalence: 与 TUI 同源同投影——agent 回答与 TUI 视图对同一问题必然一致(同读一事件流)

# ---- 写端:owner 控制动词(可观测的一体两面)----
# 语义详 flows.yaml#owner_control;此处只声明通道契约。
control_surface:
entry: TUI 控制面板 / interface-gateway(同一入口——视图上看得见的卡才可控制)
verbs: [pause, resume, abort]
channel: 控制动词=事件(card.paused / card.resumed / card.aborted),owner 经平台
通道落事件——TUI 无数据层写凭据(read_only 原则的唯一例外路径:写事件而非写状态,
与 escape_found 同模式:owner 意志经平台落事件,不持凭据)
feedback_loop: 控制动词落事件后,视图立即反映(同源投影的即时性是控制可信的前提
——按下暂停却看不到暂停,等于没暂停)

# ---- 实现位(机制型,非 agent 职责)----
implementation:
tui: mechanism:tui(read-only 通道——stewardship channels 已声明 tui)
query_api: mechanism:interface-gateway(ask 检索路由 + 控制动词入站)
materializer: mechanism:metrics-aggregator(事件流→视图物化;周报同源)
22 changes: 20 additions & 2 deletions standards/team-collaboration.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,18 @@ seats: # 座位:占实体成员位(= archetype
services: # 共享服务:跨队、按需实例化、不占团队成员位
interface_gateway: # 组织级意图入口(常驻——archetype-profiles 机制原型实例)
kind: mechanism
duty: 人类输入→脱敏→intent schema 校验→路由(新工作→planner;在途→scheduler)
duty: 人类输入→脱敏→intent schema 校验→路由(新工作→planner;在途→scheduler);
ask 意图检索路由(observability.ask_retrieval);owner 控制动词入站
(card.paused/resumed/aborted——flows#owner_control)
owner_involvement: none(NL→intent 薄 LLM 层必须过 schema)
availability: organization-level(不属任何单队——一切意图经此入境)
tui: # owner 直读视图与控制面板(ADR-0014 PR-B)
kind: mechanism
duty: 事件流→视图物化(六视图目录 observability.views)+ 控制动词入站转发
(写事件非写状态——read_only 原则)
data_source: 事件流唯一事实源(与 ask_retrieval 同源同投影——回答一致性由结构保证)
owner_involvement: none(视图物化是确定性投影,无判断位)
availability: organization-level(常驻;stewardship channels 已声明 tui)
card_gate: # 卡批准=机制输出(不是人的动作,不是 planner 自批)
kind: mechanism
output_event: cards.ratified
Expand Down Expand Up @@ -259,6 +268,9 @@ flow: # 波次相位状态机(simulate-wave.py
pr.merged: platform(git 事件带外——builder 退场条件)
wave.frozen: mechanism:scheduler(预算熔断/整波冻结——builder 退场条件)
incident.sev_alert: platform(告警接入带外——incident_cell 组队事件)
card.paused: owner(经 TUI/interface-gateway 平台通道——flows#owner_control)
card.resumed: owner(经平台通道——同上)
card.aborted: owner(经平台通道——reason 必填,reason_routing 决定善后)
verdict_layers: # 三层判决(review≠判卷——判卷是 verifier 机制)
gate: {type: mechanism, covers: "CI/holdout/mutation/contract_conformance", output: pass/fail+evidence}
review: {type: seat(test_author), question: "实现是否满足卡意图(不只是过测试)",
Expand All @@ -281,8 +293,14 @@ artifacts: # 制品=一切跨阶段/跨团队传递的
rule: 对机制检索的每个候选 ADR/skill 逐项 applies / not_applicable(理由)
forbidden: planner 自行声明"无相关 ADR"(自证不存在=仪式化入口)
lifecycle: # 卡的生命周期(amendment 并入此处,不再独立成节)
states: [drafting, testability_review, ratified, building, verify, merged, archived]
states: [drafting, testability_review, ratified, building, verify, paused, merged,
archived, aborted]
# paused=owner 暂停(building/verify 进入,resume 回原相位——语义 flows.yaml#owner_control)
# aborted=owner 终止终态(reason 必填,reason_routing 决定善后)
ratified_by: "service:card_gate(见 PART 2——机制输出)"
owner_control_ref: flows.yaml#owner_control(暂停/终止语义单一真源——此
处仅列状态;控制动词=事件(card.paused/card.resumed/card.aborted),owner
经平台通道落事件,TUI 无数据层写凭据)
amendment:
initiator: [builder, test_author] # amendment_request 为 artifact(见下 amendment_request),非消息
forbidden: builder 直写 card 任何字段
Expand Down