aep-watch

Watch

自驱动的工作发现。/aep-watch 是一个持续运行／定时监控器：它从已配置的来源（缺陷跟踪器、错误流、遥测）获取数据，使用与 /aep-reflect 相同的分类器对每项发现进行分类，与待办事项去重，并将新的缺陷／改进故事写入 product-context.yaml——随后这些故事会流入 /aep-dispatch（或由 autopilot 接手），形成闭环，让系统持续发现工作，而无需人工手动运行 /aep-envision 或 /aep-reflect。

sources → [ /aep-watch: pull → classify → dedupe → write stories ] → product-context.yaml
                                                                          │
                                                                          ▼
                                                          /aep-dispatch  (or /aep-autopilot)

/aep-reflect 是你在发布后运行的人在回路分类器；/aep-watch 则是它的始终运行搭档——逻辑相同，无需人工提示每项发现——让闭环得以_持续_运行。它将内容写入 /aep-dispatch 读取的同一 stories 部分，因此发现的工作会重新进入 /aep-envision → /aep-map → /aep-dispatch → … → /aep-wrap → /aep-reflect 周期。

**会话：**仅限主工作区（与 /aep-autopilot 一样）——遵循编排器边界。
驱动方式：/loop <interval>（Claude Code）或 codex exec cron/launchd（Codex）。
**输入：**在 topology.routing.watch 中配置的来源。
**输出：**追加到 product-context.yaml 的 stories 部分中的新 bug / refinement 故事（或作为提案显示以供确认——见配置）。

---

编排器边界

/aep-watch 仅从主工作区运行，并且是编排器，而非执行器：/aep-autopilot 中说明的编排器边界同样适用于此处。它只读取：

• 已配置的来源（通过其 API／数据源——见步骤 1），
• product-context.yaml（用于去重和写入故事）。

如果某项发现需要代码调查，该调查会在故事分派后由工作区 Agent执行。

# Main workspace guard
pwd | grep -q '.feature-workspaces' && echo "ABORT: Run /aep-watch from main workspace only" && exit 1
[ -f product-context.yaml ] || echo "ABORT: Run /aep-envision and /aep-map first"

/aep-watch 启动的任何工作器（例如，用于获取并分类一批数据的低成本 CHECK 委派任务）在 Claude Code 上都是 native-bg-subagent，并受标准的启动后存活探测约束，具体参见 /aep-executor（scripts/spawn-liveness-probe.sh <name> <agent_id>）。如果探测失败，则终止该工作器并重试一次；如果重试也失败，则在本次监控会话中内联执行获取与分类（能力降级，但仍仅处理信号）。监控会话本身不会读取工作区代码。

---

配置

Watch 完全由 product-context.yaml 中的 topology.routing.watch 驱动。每个 sources[] 条目都会指定一个来源 type（其适配器和发现数据格式定义在 references/telemetry-ingestion.md 中）：

topology:
  routing:
    full_auto: false # master switch (see below)
    watch:
      sources: # source types + adapters: references/telemetry-ingestion.md
        - type: bug_tracker # github_issues | linear | jira | sentry | datadog | log_stream
          query: "is:open label:bug"
        - type: error_stream
          dsn: "<sentry/rollbar/...>"
        - type: telemetry
          metric: "error_rate"
          threshold: 0.02
        - type: dogfood_report # dogfood findings (local / post-deploy / standalone)
          glob: ".dev-workflow/dogfood-*.md" # default; see telemetry-ingestion.md adapter
        - type: distillation # layer distillations (proposal-only synthesis from /aep-wrap)
          glob: "lessons-learned/distillations/*.yaml" # default; see telemetry-ingestion.md adapter
      interval: 30m # poll cadence for the /loop or cron driver
      auto_create: false # write stories directly vs. surface proposals
      since: null # high-water mark — last ingested timestamp (watch maintains this)

确认策略（默认保守）：仅当 full_auto: true（总开关）或 watch.auto_create: true（单个监控的选择加入设置，范围小于总开关）时，才会自动创建故事。否则显示提案：将故事对象写入 topology.routing.watch 下的 watch_proposals 块并打印出来；在人工批准前（通过 /aep-reflect 或内联方式），不会有任何内容进入 stories 部分。在 full_auto: true 时，watch 会直接写入 stories，/aep-dispatch / /aep-autopilot 会在下一轮接手这些故事。

---

Watch 循环

每次轮询都会运行相同的四步流程。幂等——如果没有新的来源数据，重复运行不会产生新故事（去重和 since 高水位标记可确保这一点）。

⓪ PRECHECK  → verify the /aep-map telemetry binding is complete (coverage_check)
① PULL      → fetch new findings from each configured source (since high-water mark)
② CLASSIFY  → run each finding through the /aep-reflect Step 2 classifier
③ DEDUPE    → drop findings that already map to an existing story
④ WRITE     → create bug/refinement stories (or surface proposals)

步骤 0：前置条件 — 验证映射绑定

/aep-watch 会使用遥测来源，因此请先确认 /aep-map 确实已将它们 绑定，以便在监控范围内没有任何内容时明确报告。对监控所需的信号运行 coverage_check()（references/telemetry-ingestion.md §1.5 中的辅助函数）： 每个 topology.routing.watch.sources[] 条目（以及它所依赖的任何 metric/error_stream）都必须解析到一个已接入且包含 metric_map 的 topology.routing.telemetry_sources 条目。

• 已覆盖 → 继续执行步骤 1。
• 未覆盖（来源为空，或所引用的指标没有 metric_map）→ 报告缺口，而不是覆盖情况。显示： "telemetry binding incomplete for <missing> — run /aep-map (Telemetry Binding step) before /aep-watch can ingest it"，跳过未覆盖的来源；如果没有任何来源已覆盖，则用该消息终止本轮。缺少绑定会阻止执行；绝不会静默地什么也不做。

**后置条件：**每个已覆盖的来源都能解析到一个已接入且包含 metric_map 的 telemetry_sources 条目（文件 glob 来源 dogfood_report/distillation 可自描述，不受此限制），否则本轮已显示绑定不完整的消息。

步骤 1：从来源拉取

对于 watch.sources 中的每个条目，拉取自 watch.since 以来创建或更新的发现，并将每条发现简化为发现记录；使用 references/telemetry-ingestion.md 中按来源划分的适配器（→ /aep-watch 发现记录；Dogfood-report 适配器；Distillation 适配器），这些适配器定义了发现的 结构。只有在本轮成功完成后，才将 watch.since 更新为最新的 last_seen （本轮失败时会重新拉取，而不会丢弃发现）。

• **文件 glob 来源（dogfood_report、distillation）**不带每项时间戳， 因此 watch.since 不会因它们而推进；每轮重新扫描 glob 不会造成问题， 因为步骤 3 会根据各适配器稳定的 external_id（dogfood:<report>:<hash> / distillation:<layer>:<hash>）进行去重。由于可自描述，这两种来源都不受步骤 0 的 coverage_check 限制。
• **distillation 额外规则：**映射到 process（skill_amendments）的条目 绝不会自动创建为故事 — 无论 full_auto/auto_create 如何设置，都会作为 拟议修订呈现给人工审核。

**后置条件：**每个已配置的来源都产生了零条或多条发现记录；本轮成功完成前， watch.since 保持不变。

步骤 2：对每条发现进行分类

使用与 /aep-reflect 步骤 2 完全相同的分类器对每条发现进行分类 （bug / refinement / discovery / opportunity shift / process）— 应用 /aep-reflect 的“对每条观察进行分类”（规范的 5 类逻辑；若有更改，也只在该处更改）。

Watch 只会对能够安全转化为工作的两类发现自主采取行动：bug → 创建 bug 故事（步骤 4）；refinement → 在下一层创建 refinement 故事（步骤 4）。 Discovery、opportunity shift、calibration 和 process 类发现无论 full_auto 如何设置，都绝不会自动创建；它们会改变产品意图或工作流，因此 始终会通过 /aep-reflect 呈现给人工处理；opportunity shift 会升级处理，因为它会改变押注。

步骤 3：与现有故事去重

创建任何内容之前，请对照 product-context.yaml 中当前的 stories 部分 （以及现有的 watch_proposals）检查发现。遇到以下情况时跳过该发现：

• 某个故事已记录此 source + external_id（watch 会在其创建的每个故事上标记 watch_origin: { source, external_id }），或
• 某个未结故事的 title/描述明确涵盖相同问题 （相同的错误特征、相同的端点、相同的指标）。

如果匹配的故事已为 completed/closed，且问题已再次出现（在 completed_at 之后有新的发生记录），请添加备注，并将其作为回归 呈现给人工处理——问题再次出现是旧工作的新信息，而不是新工作。

**后置条件：**每个保留的发现都没有匹配的未结故事，也没有先前的 watch_origin.{source, external_id}。

步骤 4：编写故事（或呈现提案）

为每个保留的缺陷 / 改进发现编写一个故事：

- id: "watch-<source>-<external_id>"
  title: "<finding title>"
  description: "<finding detail> (auto-discovered by /aep-watch from <source>)"
  type: bug # or refinement
  status: pending
  priority: high # bugs: high; tune by count/severity (see below)
  layer: <active_layer> # bug → current layer; refinement → next layer
  module: <best-effort or unset> # leave unset if the source doesn't localize it
  watch_origin:
    source: "<source>"
    external_id: "<external_id>"
    discovered_at: "<ISO8601>"

优先级 / 层级规则（与 /aep-reflect 保持一致）：

• 缺陷 → priority: high、status: pending，位于当前/活动层 （当 count 或严重程度较高时，升级为 critical，例如影响众多用户的崩溃 / 超过阈值的 error_rate）。
• 改进 → 在下一层设为 status: pending。
• 如果来源无法确定 module / files_affected，则不设置这些字段； dispatch 的就绪度评分会先将这类项目路由到 /aep-design。

然后，根据确认策略（Config）：

• 自动创建（full_auto: true 或 watch.auto_create: true）：将故事追加到 stories 部分——普通的待处理故事会由 /aep-dispatch 评分，并由 /aep-autopilot 在下一次运行时接手。
• 呈现（默认）：将故事对象追加到 topology.routing.watch.watch_proposals 并打印出来；人工运行 /aep-reflect（或内联确认），将提案提升到 stories 中。

验证 + 提交（与 reflect/dispatch 使用相同的防护措施——运行 references/yaml-guardrails.md 中的验证命令）：

npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"
# Resolve $BASE (integration branch) per /aep-git-ref "Integration Branch".
git pull --ff-only origin "$BASE"
git add product-context.yaml
git commit -m "chore: watch — auto-discovered N stories from <sources>"
git push origin "$BASE"

追加一条 changelog 记录（type: watch），总结已摄取、分类、去重的发现，以及已创建与已提议的项目。后置条件： npx js-yaml product-context.yaml 以退出码 0 结束，且提交已推送到 $BASE。

---

驱动器

/aep-watch 是一个持续/定时监控器，使用与 /aep-autopilot 相同的驱动器矩阵： 使用 executor detect() 解析主机的驱动器，并依据 /aep-executor 中的 references/backends.md 选择驱动器 × 后端矩阵，间隔采用 watch.interval。

• Claude Code — /loop <interval>（长时间运行，处于会话中）：/loop 30m /aep-watch tick。 会话会保持运行，因此任何派生的 CHECK delegate 都是与会话绑定的 native-bg-subagent。
• Codex — codex exec cron/launchd（临时运行，由操作系统调度）：在外部安排 /aep-watch tick（使用 launchd StartInterval、cron，或 while … sleep 循环），每次运行一个低开销的一次性任务，并使用由操作系统绑定的工作进程 （codex-exec）。AEP 会打印代码片段；不会安装调度器。

/aep-watch tick 运行四步循环的一轮，然后退出。/aep-watch stop 会取消驱动器（取消 /loop，或移除 cron/launchd 任务）。

---

交叉引用

• /aep-reflect — 步骤 2 分类器（缺陷 / 改进 / 发现 / …）， 在此复用；它是 watch 的人工参与对应机制。
• references/telemetry-ingestion.md — 步骤 1 使用的发现记录 + 各来源适配器 （与 /aep-reflect 步骤 1 共用）。
• /aep-dispatch — 处理 watch 创建的故事（评分、就绪度、WIP）。
• /aep-autopilot — watch 对照的编排器模式、驱动器矩阵、存活探测和 主工作区边界；会在下一次运行时接手 watch 创建的故事。