diff --git a/standards/flows.yaml b/standards/flows.yaml index 88f0f19..756a796 100644 --- a/standards/flows.yaml +++ b/standards/flows.yaml @@ -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 回路: + 规格错误是 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)] diff --git a/standards/observability.yaml b/standards/observability.yaml new file mode 100644 index 0000000..2b2854c --- /dev/null +++ b/standards/observability.yaml @@ -0,0 +1,73 @@ +version: 1 +# ============================================================================ +# 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/事件引用;查不到就说查不到(禁编造—— + 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(事件流→视图物化;周报同源) diff --git a/standards/team-collaboration.yaml b/standards/team-collaboration.yaml index 04a4427..be8dba3 100644 --- a/standards/team-collaboration.yaml +++ b/standards/team-collaboration.yaml @@ -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 @@ -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: "实现是否满足卡意图(不只是过测试)", @@ -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 任何字段