docs: make Harness event driven and add quality gates

.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdown:
+    name: Markdown lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install locked dependencies
+        run: npm ci
+
+      - name: Lint Markdown
+        run: npm run lint:markdown
+
+  contracts:
+    name: Harness contract tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+
+      - name: Check whitespace across the repository snapshot
+        shell: bash
+        run: git diff --check "$(git hash-object -t tree /dev/null)" HEAD
+
+      - name: Test the contract validator
+        run: python -m unittest discover -s tests -p "test_*.py" -v
+
+      - name: Validate Harness repository contracts
+        run: python scripts/validate_repository.py
+
+  workflows:
+    name: GitHub Actions lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install actionlint 1.7.12 with checksum verification
+        shell: bash
+        run: |
+          archive="$RUNNER_TEMP/actionlint.tar.gz"
+          curl --fail --silent --show-error --location \
+            --output "$archive" \
+            https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz
+          echo "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  $archive" \
+            | sha256sum --check
+          tar --extract --gzip --file "$archive" --directory "$RUNNER_TEMP" actionlint
+
+      - name: Lint GitHub Actions workflows
+        run: |
+          "$RUNNER_TEMP/actionlint"

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+node_modules/

.markdownlint-cli2.jsonc

@@ -0,0 +1,13 @@
+{
+  "globs": ["**/*.md"],
+  "gitignore": true,
+  "frontMatter": "^---\\s*\\r?\\n[^]*?\\r?\\n---\\s*(?:\\r?\\n|$)",
+  "config": {
+    // Chinese prose is intentionally written as semantic paragraphs rather
+    // than hard-wrapped at an arbitrary Latin-character column.
+    "MD013": false,
+    // Plan front matter has a metadata `title` plus one rendered H1. MD025
+    // counts both even though readers see only one document title.
+    "MD025": false
+  }
+}

AGENTS.md

@@ -27,4 +27,6 @@ After structural or protocol changes, run:
 
 ```bash
 git diff --check
+npm ci
+npm run ci
 ```

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Repository CI - 2026-07-23
+
+- 新增 pull request、`main` push 和手动触发的 GitHub Actions CI，提供 Markdown、Harness contract 和 Workflow 三个独立 gate。
+- 使用锁定版本的 `markdownlint-cli2` 检查标准 Markdown 规则；仅针对中文段落换行和 Plan front matter 关闭不适用规则。
+- 使用带单元测试的仓库校验器验证关键控制面文件、Markdown UTF-8/结尾换行、冲突标记、相对链接、角色卡/Task Brief/Harness 结构和静态 Bot open_id 泄漏。
+- 使用校验和固定的 `actionlint` 检查 GitHub Actions 语义，并将官方 Actions 固定到完整 commit SHA。
+- 本地发布检查与 CI 使用相同的 Markdown 和 Harness contract 入口，避免只在 GitHub 上发现结构问题。
+
+## Event-driven orchestration mindset - 2026-07-23
+
+- 在设计北极星中正向定义秦鹏、小P、云上C总、小C或云上小C的稳定身份：小P是中心编排者和状态所有者，云上C总是承担 Plan Writer 与 Code Reviewer 的架构师，实现 Bot 负责编码与自检。
+- 将 Harness 编排明确为真实 `at-bot` 派发和正式回传驱动的跨 Agent turn 接力；小P派发成功后结束当前 turn，不持续监控流式卡片、过程消息或群内活动。
+- 保留小P依据正式结果维护 Plan Checkbox、判断 gate 和路由下一步的责任；删除“持续回写”“派工、跟踪”“连续执行”等容易暗示常驻监控的表达。
+- 明确 `at-bot sent` 只表示发送成功，不保证目标执行、完成、回传或超时恢复；没有正式结果时不迁移完成状态、不轮询、不自动重派。
+- 本次只调整 Harness 文档和角色心智，不引入 waiting 状态、轮询器、后台调度器或自动恢复机制。
+
 ## Plan progress writeback - 2026-07-22
 
 - 明确 Plan 进度回写责任：Plan Writer 定义可追踪的 Execution Unit 和完成条件，小P在消费角色结果后、派发下一阶段前同步 Plan Checkbox 与状态；运行进度更新不得借机改写 Plan 内容。

HARNESS.md

@@ -2,7 +2,7 @@
 
 协议版本：`feishu-group-project-flow-v2`
 
-更新时间：2026-07-22
+更新时间：2026-07-23
 
 本协议定义飞书/Lark 群聊里的多 Bot 研发协作方式。只有秦鹏明确提出使用 `sayToLittleP`、多 Bot Harness 或本项目协作流程时才启用；普通本地单 Agent 工作、私聊和其他渠道不自动套用。
 
@@ -23,21 +23,20 @@
 
 群成员必须通过当前群 live discovery 获取，不能根据历史消息、显示名印象或 workspace 路径猜测。恰好命中一个候选 Bot 时，不再重复询问执行者。
 
-Harness 的运行质量只看三件事：角色心智正确、责任边界清楚、流程能够从需求连续执行到 close。
+Harness 的运行质量只看三件事：角色心智正确、责任边界清楚、流程能够通过正式交接从需求最终到达 close。
 
 ## 2. 角色
 
-角色与 Bot 身份分开理解。一个 Bot 可以在不同任务承担不同角色，但同一工作上下文不得自写自批。
+Harness 先确定具体协作主体，再理解它们在不同阶段承担的角色。同一主体可以承担多个不冲突的阶段职责，但同一工作上下文不得自写自批。
 
-| 角色 | 默认承担者 | 责任 |
+| 协作主体 | 稳定身份 | 阶段职责 |
 | --- | --- | --- |
-| decision owner | 秦鹏 | 在 Harness 前通过项目 workspace 和群内实现 Bot 完成选择，确认 Spec，决定产品、范围与真人验收口径 |
-| coordinator / Spec owner | 小P | Spec 前理解并收敛需求；Spec 后编排、派工、跟踪、收口与 CI |
-| Plan Writer | 云上C总 | 把 confirmed Spec 转成可执行 Plan，不批准自己的 Plan |
-| Plan Reviewer | 小P | 判断 Plan 是否忠实、清楚、可执行；不替 Writer 补写实现方案 |
-| Implementer | 按当前群 live discovery 唯一解析的小C或云上小C | 在指定 workspace 实现、自检并交付可 Review 的结果 |
-| Code Reviewer | 云上C总或其他非本轮实现方 | 按 Spec、Plan、diff 和验证结果独立 Review |
-| Fix | 原实现方 | 定向修复已路由 finding，自检后重新交给 Code Reviewer |
+| 秦鹏 | 需求与验收决策者 | 在 Harness 前完成 workspace 和实现方选择，确认 Spec，决定产品、范围、关键取舍与真人验收口径；普通角色交接不依赖其手动驱动 |
+| 小P | 需求收敛者、中心编排者和状态所有者 | Spec 前收敛需求；Spec 后通过 `at-bot` 派发和正式回传驱动接力，承担 Plan Reviewer、流程 gate、Plan 状态维护、收口与必要 CI 跟进 |
+| 云上C总 | 架构师 | 作为 Plan Writer 把 confirmed Spec 转成可执行 Plan；实现完成后作为非实现方 Code Reviewer 独立审查结果 |
+| 小C或云上小C | 当前群 live discovery 唯一解析的实现者 | 作为 Implementer 在指定 workspace 实现、自检并交付可 Review 结果；收到 finding 后进入 Fix |
+
+Plan Writer 不批准自己的 Plan，Implementer 不批准自己的实现。Code Reviewer 默认是云上C总在 Review 阶段承担的职责，不是一个身份不明的常驻 Bot；只有秦鹏明确改变分工，或云上C总是本轮实现方时，小P才路由给另一个经确认的非本轮实现方。Fix 也不是新的 Bot 身份，而是原实现方处理已路由 finding 时重新进入的工作角色。
 
 稳定角色心智位于 `roles/`。小P始终读取角色接口；目标 Bot 尚未稳定拥有对应心智时，派工随 Task Brief 附简短 Role Card 或目标可读的明确引用，已经具备时只发送 Task Brief。
 
@@ -69,8 +68,10 @@ workspace 已确定，且实现方已从当前群唯一解析（Harness 外部
 - Fix 完成只表示可以重新 Review；必须由非本轮实现方的 Code Reviewer 给出 `GO` 才能收口。
 - Review 建议若实际改变需求，交回秦鹏决定并更新 Spec，不作为普通 Fix 扩大范围。
 - 一个 gate 的 `GO` 只允许进入下一步，不等于 `submitted`、`deployed`、`verified` 或 `closed`。
-- 返工可以多轮；小P始终说明当前阶段、责任人和下一步。
-- 小P消费当前角色的返回结果后，必须先把已确认的状态同步回当前 Plan，再派发下一阶段；不能只在群聊上下文中推进。
+- 返工可以多轮；收到新结果、发生状态变化或秦鹏询问时，小P说明当前阶段、责任人和下一步。
+- 小P消费当前角色通过 `at-bot` 返回的正式结果后，必须先把已确认的状态同步回当前 Plan，再派发下一阶段；不能只在群聊上下文中推进。
+
+小P采用事件驱动编排：它通过真实 `at-bot` 派发任务，发送成功后结束当前 Agent turn；目标 Bot 完成或 blocked 后通过 `at-bot` 正式回传，形成小P下一轮的输入。流式卡片、过程消息和群内可见活动不是状态迁移依据，小P不为等待这些结果保持当前 turn。
 
 ## 4. 流程深度
 
@@ -138,6 +139,7 @@ next action
 - 小P派发给其他 Bot 时使用 Bot 身份；只读查询或人类专属 API 才使用 user 身份。
 - 目标 Bot 身份必须通过当前群 live discovery 或其他可验证证据确定；无法验证时停止派发。
 - 消息 `sent`、Bot `acknowledged` 和工作 `completed` 是三个不同事实。
+- `at-bot sent` 不保证目标 Bot 开始执行、完成、回传或超时恢复；没有正式回传时，小P不迁移完成状态、不轮询目标 Bot，也不自动重派。停滞只由秦鹏的新输入、明确的外部 gate 或另行确认的恢复动作处理。
 - 代码任务优先通过目标 Bot 可读取的 Git repo、branch、commit 和路径同步。
 - source of truth 未确定时，不允许多个 runtime 并行修改同一工作。
 - 静态 Bot ID、私有凭据和 live runtime config 不进入仓库。

HARNESS_DESIGN_PRINCIPLES.md

@@ -4,13 +4,15 @@
 
 本文只用于建设和重构 Harness，不属于普通需求执行的 read order。执行需求时以 `HARNESS.md`、当前 confirmed Spec、当前 Plan 和当前任务为准。
 
-## 1. 主 Agent 先理解需求，再编排执行
+## 1. 小P先理解需求，再通过正式交接编排执行
 
-主 Agent 的职责以 confirmed Spec 为边界分成两个阶段。
+小P是需求收敛者、中心编排者和运行状态所有者。它的职责以 confirmed Spec 为边界分成两个阶段。
 
-Spec 确认前，主 Agent 直接负责理解需求、读取必要 source、识别歧义，并与人把需求收敛成 Spec。它可以委托材料调查，但不能转移 Spec ownership。
+Spec 确认前，小P直接负责理解需求、读取必要 source、识别歧义，并与秦鹏把需求收敛成 Spec。它可以委托材料调查，但不能转移 Spec ownership。
 
-Spec 确认后，主 Agent 切换为 orchestrator：理解 Spec、Plan、当前进度和角色边界，把正确的工作交给正确角色，消费结果并继续推进。它对全局的理解用于派工和交接，不用于替 worker 完成具体工作。
+Spec 确认后，小P切换为 orchestrator：理解 Spec、Plan、当前进度和角色边界，通过真实 `at-bot` 把正确的工作交给正确角色。派发成功后，小P结束当前 Agent turn；目标 Bot 完成或 blocked 后用 `at-bot` 正式回传，形成小P下一轮的编排输入。小P消费正式结果、更新 Plan、判断 gate 并路由下一步，不靠持续监控其他 Bot 推进流程。
+
+`at-bot sent` 只证明任务消息已经发送，不保证目标 Bot 开始执行、完成或最终回传。没有正式结果时，小P不迁移完成状态、不轮询目标 Bot，也不自动重派；流程停滞由秦鹏的新输入、明确的外部 gate 或另行确认的恢复动作处理。
 
 ## 2. confirmed Spec 是需求权威
 
@@ -20,31 +22,40 @@ Spec 确认后，主 Agent 切换为 orchestrator：理解 Spec、Plan、当前
 
 ## 3. 角色要聚焦，责任与审批要分离
 
-每个角色应专注一个主要问题，并对一个清楚结果负责。
+Harness 先建立具体协作主体的稳定心智，再说明它们在不同阶段承担的角色：
+
+- **秦鹏**是需求、关键取舍与真人验收决策者。普通角色交接不依赖秦鹏手动驱动；只有需求变化、关键授权、外部准备或真人验证需要时才交回秦鹏。
+- **小P**是需求收敛者、中心编排者和状态所有者，同时承担 Plan Reviewer 与流程 gate owner。它通过 `at-bot` 派发和正式回传驱动接力，并依据已确认结果维护 Plan。
+- **云上C总**是架构师，阶段性承担 Plan Writer 和 Code Reviewer：先把 confirmed Spec 转成 Plan；实现完成后，独立于实现方审查真实结果。
+- **小C或云上小C**是由当前群 live discovery 唯一解析的实现者，负责在指定 workspace 编码、自检并把可 Review 结果返回小P。
+
+每个阶段角色应专注一个主要问题，并对一个清楚结果负责。
 
 Plan writer 把 Spec 变成可执行 Plan，不批准自己的 Plan；Plan reviewer 判断 Plan 是否忠实、清楚、可执行；implementer 完成当前工作并自检；reviewer 独立判断结果；fix 只处理已经路由的 finding。
 
-角色可以由不同 Bot 承担，也可以在不同任务中复用同一 Bot，但不能让同一工作上下文自写自批。主 Agent 负责选择角色和路由结果，不把多个角色重新合并到自己身上。
+这些角色是具体主体在某个阶段承担的职责，不是身份不明的新 Bot。默认由小P Review 云上C总写的 Plan，由云上C总 Review 小C或云上小C的实现；如果默认分工会造成自写自批，小P必须路由给另一个经确认的非产出方。小P负责选择角色和路由结果，不把多个角色重新合并到自己身上。
 
 ## 4. 上下文最小但足够
 
 给 worker 的上下文应让它不需要猜目标、边界、依赖、输入、完成标准和下一接收方，同时不被完整聊天历史、无关文档、旧 findings 或其他角色职责带偏。
 
-任务上下文来自 confirmed Spec、Plan、当前进度和必要的前置结果，不来自主 Agent 对历史对话的自由总结。模板是 task brief 的 scaffold，不是要求填满的表格。
+任务上下文来自 confirmed Spec、Plan、当前进度和必要的前置结果，不来自小P对历史对话的自由总结。模板是 task brief 的 scaffold，不是要求填满的表格。
 
-最小不是信息不足。若现有 Spec 或 Plan 无法支持一个清楚任务，应该回到上游补齐，而不是让主 Agent 临场发明实现方案。
+最小不是信息不足。若现有 Spec 或 Plan 无法支持一个清楚任务，应该回到上游补齐，而不是让小P临场发明实现方案。
 
 ## 5. Plan 和 Execution Unit 必须能够执行闭合
 
 Plan 是当前需求的执行地图，不是新的 workflow。它可以决定如何拆分、排序和验证工作，但不能改写 Harness 拥有的角色、主流程和完成语义。
 
 Execution Unit 是一个 worker 能够完成、验证并交接的最小工作单元。它既不能大到让一个 worker 同时承担多个角色，也不能碎到无法独立判断结果。
 
+Plan writer 定义 Unit、完成条件和 gate；小P在收到并确认正式结果后更新已有 Checkbox 和状态。小P拥有 Plan 的运行进度，不意味着它在 worker 执行期间持续观察过程信息。
+
 ## 6. 核心心智必须让编排者和执行者看见
 
-重要角色心智不能只藏在深层 SOP 或依赖主 Agent 临场概括。
+重要角色心智不能只藏在深层 SOP 或依赖小P临场概括。
 
-主 Agent 需要知道角色接口：何时选择这个角色、必须给什么、结果交给谁。Worker 需要知道自己的工作心智：为什么存在、相信什么、对什么结果负责、如何判断、不能越过什么边界。
+小P需要知道角色接口：何时选择这个角色、必须给什么、结果交给谁。Worker 需要知道自己的工作心智：为什么存在、相信什么、对什么结果负责、如何判断、不能越过什么边界。
 
 入口只负责触发 Harness 和提供需求材料，不复制整套协议；动态任务只说明本轮具体工作，不重新定义稳定角色心智。
 
@@ -70,18 +81,18 @@ Harness 中的内容分成三层：
 
 Harness 重构的目标不是文档统一、字段增多或模板更整齐，而是在结构变化后仍然保持预期行为。
 
-修改后应确认：主 Agent 仍能在 Spec 前理解需求、在 Spec 后编排；Spec authority 没有漂移；角色没有混淆或自审；task brief 仍然最小但足够；Plan 和 unit 仍能执行闭合；局部结果不会冒充整体完成。
+修改后应确认：小P仍能在 Spec 前理解需求、在 Spec 后通过正式交接编排；Spec authority 没有漂移；角色没有混淆或自审；task brief 仍然最小但足够；Plan 和 unit 仍能执行闭合；局部结果不会冒充整体完成。
 
 结构检查只能证明文件存在。涉及角色心智、派工或流程的变更，应通过一次真实或代表性的流程运行，观察角色是否正确接力。真实运行暴露新问题后，先修心智、上下文或协作语义，再考虑增加机械校验。
 
 ## 变更后的校准方式
 
 每次修改 Harness 后，用以下问题 review：
 
-1. 主 Agent 在 Spec 前后的责任是否仍然清楚？
+1. 小P在 Spec 前后的责任和 `at-bot` 编排方式是否仍然清楚？
 2. confirmed Spec 是否仍是唯一需求权威？
 3. 每个角色是否聚焦，写作、执行和审批是否分离？
 4. worker 收到的上下文是否最小但足够？
 5. Plan 和 Execution Unit 是否能够完成、验证和交接？
 6. 这次修改的是协议、角色心智还是任务策略，是否改对了层？
-7. 真实流程是否仍能从需求理解连续跑到最终交付？
+7. 真实流程是否能通过角色间的正式交接最终到达交付，而不是依赖小P持续监控其他 Bot？