@tea-agent/loop-agent 0.3.0 → 0.4.0

package/docs/architecture/runtime-boundaries.md

@@ -1,147 +1,147 @@
-# Runtime Boundaries
-
-本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
-
-## 分层概览
-
-```text
-Skill layer
-  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
-
-CLI layer (src/cli/)
-  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
-
-Application layer (src/application/，逐步引入)
-  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
-
-Workflow runtime (src/workflows/)
-  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
-
-Executors (src/executors/)
-  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
-
-Infrastructure / Store (src/infrastructure/，逐步引入)
-  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
-
-Governance (scripts/check-*.sh, src/governance/)
-  └─ 防止 command registry、skill entry、import architecture 漂移
-```
-
-## 各层职责
-
-### Skill layer
-
-- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
-- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
-- **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
-
-### CLI layer
-
-- **位置**：`src/cli.ts`、`src/cli/**`
-- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
-- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
-- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
-
-### Application layer
-
-- **位置**：`src/application/**`（按计划逐步引入）
-- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
-- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
-- **禁止**：直接承担 CLI formatting 或 argv 解析。
-
-### Workflow runtime
-
-- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
-- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排。
-- **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
-- **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
-
-### Executors
-
-- **位置**：`src/executors/**`
-- **职责**：封装 Cursor SDK/CLI、Pi SDK/CLI、shell 执行与 write guard。
-- **允许依赖**：`src/shared/**`、外部 SDK。
-- **禁止**：依赖 `src/commands/**` 或 CLI 输出格式。
-
-### Infrastructure / Store
-
-- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
-- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
-- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
-
-### Governance
-
-- **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
-- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、skill entry 完整性。
-
-## 允许的依赖方向
-
-```text
-Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
-
-CLI                   ──────────>   Application (目标态)
-CLI                   ──────────>   Commands (handler 薄层)
-Commands              ──────────>   Application / Workflows / Infrastructure
-
-Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
-Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
-
-Executors             ──────────>   Shared / 外部 SDK
-Executors             ──X──>        Commands / CLI
-
-Application           ──────────>   Workflows / Infrastructure / Task / Records
-Application           ──X──>        CLI formatting
-
-Infrastructure        ──────────>   Shared / node:fs
-Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
-```
-
-**规则摘要**
-
-| From | May import | Must not import |
-|------|------------|-----------------|
-| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
-| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
-| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
-| `src/cli/**` | commands, adapters, shared, application（目标） | — |
-| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
-
-## 已知过渡耦合
-
-当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
-
-`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
-
-## Governance 钩子
-
-以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
-
-| Script | 检查内容 | 失败条件 |
-|--------|----------|----------|
-| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` import | 新的未 allowlist violation |
-| `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
-| `scripts/check-skill-entry.sh` | `SKILL.md` reference 文件存在、行数阈值 | reference 缺失（fail）；行数 > 220（warn） |
-
-相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
-
-### 验证命令
-
-```bash
-bash scripts/check-repo.sh
-bash scripts/check-architecture-boundaries.sh
-bash scripts/check-command-registry-drift.sh
-bash scripts/check-skill-entry.sh
-```
-
-Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
-
-## 演进里程碑
-
-| Phase | 边界变化 |
-|-------|----------|
-| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
-| 1 | CLI command definition 单源 |
-| 2 | Skill entry 瘦身 + frontmatter references |
-| 3 | DAG application use-case；Loop 开始脱离 command JSON |
-| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
-| 7 | Harness Store / Repository 集中 `.harness` 副作用 |
+# Runtime Boundaries
+
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
+
+## 分层概览
+
+```text
+Skill layer
+  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
+
+CLI layer (src/cli/)
+  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
+
+Application layer (src/application/，逐步引入)
+  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
+
+Workflow runtime (src/workflows/)
+  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
+
+Executors (src/executors/)
+  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
+- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
+- **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
+
+### CLI layer
+
+- **位置**：`src/cli.ts`、`src/cli/**`
+- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
+- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
+- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
+
+### Application layer
+
+- **位置**：`src/application/**`（按计划逐步引入）
+- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
+- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
+- **禁止**：直接承担 CLI formatting 或 argv 解析。
+
+### Workflow runtime
+
+- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
+- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排。
+- **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
+- **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
+
+### Executors
+
+- **位置**：`src/executors/**`
+- **职责**：封装 Cursor SDK/CLI、Pi SDK/CLI、shell 执行与 write guard。
+- **允许依赖**：`src/shared/**`、外部 SDK。
+- **禁止**：依赖 `src/commands/**` 或 CLI 输出格式。
+
+### Infrastructure / Store
+
+- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
+- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
+
+### Governance
+
+- **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
+- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、skill entry 完整性。
+
+## 允许的依赖方向
+
+```text
+Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
+
+CLI                   ──────────>   Application (目标态)
+CLI                   ──────────>   Commands (handler 薄层)
+Commands              ──────────>   Application / Workflows / Infrastructure
+
+Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
+Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
+
+Executors             ──────────>   Shared / 外部 SDK
+Executors             ──X──>        Commands / CLI
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+Infrastructure        ──────────>   Shared / node:fs
+Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
+```
+
+**规则摘要**
+
+| From | May import | Must not import |
+|------|------------|-----------------|
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
+| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
+| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance 钩子
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+|--------|----------|----------|
+| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` import | 新的未 allowlist violation |
+| `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
+| `scripts/check-skill-entry.sh` | `SKILL.md` reference 文件存在、行数阈值 | reference 缺失（fail）；行数 > 220（warn） |
+
+相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
+
+### 验证命令
+
+```bash
+bash scripts/check-repo.sh
+bash scripts/check-architecture-boundaries.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-skill-entry.sh
+```
+
+Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
+
+## 演进里程碑
+
+| Phase | 边界变化 |
+|-------|----------|
+| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
+| 1 | CLI command definition 单源 |
+| 2 | Skill entry 瘦身 + frontmatter references |
+| 3 | DAG application use-case；Loop 开始脱离 command JSON |
+| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
+| 7 | Harness Store / Repository 集中 `.harness` 副作用 |

package/docs/cursor-executor-usage.md

@@ -1,25 +1,25 @@
-# Cursor Executor 用法
-
-Cursor 用于有界写实现。每个 Cursor 写任务必须显式定义 scope。
-
-## Prompt 必填字段
-
-- task id
-- objective
-- allowed paths
-- forbidden paths
-- constraints
-- expected verification
-- 保留无关变更的指令
-
-## One-Shot Helper
-
-```bash
-loop-agent cursor-prompt \
-  --cwd . \
-  --timeout 1800000 \
-  --model composer-2.5 \
-  "<bounded task prompt>"
-```
-
-Cursor 返回后，主会话必须检查 diff 并运行相关验证命令。
+# Cursor Executor 用法
+
+Cursor 用于有界写实现。每个 Cursor 写任务必须显式定义 scope。
+
+## Prompt 必填字段
+
+- task id
+- objective
+- allowed paths
+- forbidden paths
+- constraints
+- expected verification
+- 保留无关变更的指令
+
+## One-Shot Helper
+
+```bash
+loop-agent cursor-prompt \
+  --cwd . \
+  --timeout 1800000 \
+  --model composer-2.5 \
+  "<bounded task prompt>"
+```
+
+Cursor 返回后，主会话必须检查 diff 并运行相关验证命令。

package/docs/decisions/README.md

@@ -1,3 +1,3 @@
-# 决策
-
-本目录存放架构决策记录（ADR）。
+# 决策
+
+本目录存放架构决策记录（ADR）。

package/docs/design/README.md

@@ -1,36 +1,36 @@
-# 设计笔记
-
-`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
-
-## 文档
-
-| 文档 | 用途 |
-|---|---|
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
-| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `1个月规划.md` | 首月落地计划 |
-| `1月wbs.md` | 首月 WBS 与分工 |
-| `六个月规划.md` | 六个月路线图与目标架构 |
-| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
-| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-
-## 当前实现边界
-
-`loop-agent` 当前拥有：仓库本地 harness、Agent DAG 生成/验证/执行、shell 验证、artifacts、reports、Loop state。它不是产品线 Task Pool、Orchestrator、docs-sync 服务、Git/CI 平台或 artifact store。
-
-设计文档使用两类 profile 名称：
-
-- **Business task profiles**：`backend-feature`、`frontend-feature`、`qa-casegen`、`qa-testcode`、`reviewer-gate`
-- **`loop-agent dag run-task --profile` governance profiles**：`auto`、`minimal`、`standard`、`reviewed`、`supervised`
-
-除非 CLI 显式扩展支持，否则不要把 business task profile 直接传给 `loop-agent dag run-task --profile`。用 `taskspec-to-loop-agent-mapping.md` 将 business profile 路由到当前 governance profile。
-
-## 维护规则
-
-设计笔记变更时：
-
-1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
-2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
-3. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
-4. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
-5. 运行 `bash scripts/check-repo.sh`
+# 设计笔记
+
+`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
+
+## 文档
+
+| 文档 | 用途 |
+|---|---|
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
+| `1个月规划.md` | 首月落地计划 |
+| `1月wbs.md` | 首月 WBS 与分工 |
+| `六个月规划.md` | 六个月路线图与目标架构 |
+| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
+
+## 当前实现边界
+
+`loop-agent` 当前拥有：仓库本地 harness、Agent DAG 生成/验证/执行、shell 验证、artifacts、reports、Loop state。它不是产品线 Task Pool、Orchestrator、docs-sync 服务、Git/CI 平台或 artifact store。
+
+设计文档使用两类 profile 名称：
+
+- **Business task profiles**：`backend-feature`、`frontend-feature`、`qa-casegen`、`qa-testcode`、`reviewer-gate`
+- **`loop-agent dag run-task --profile` governance profiles**：`auto`、`minimal`、`standard`、`reviewed`、`supervised`
+
+除非 CLI 显式扩展支持，否则不要把 business task profile 直接传给 `loop-agent dag run-task --profile`。用 `taskspec-to-loop-agent-mapping.md` 将 business profile 路由到当前 governance profile。
+
+## 维护规则
+
+设计笔记变更时：
+
+1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
+2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
+3. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
+4. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
+5. 运行 `bash scripts/check-repo.sh`

package/docs/development-principles.md

@@ -1,71 +1,73 @@
-# 开发原则
-
-loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
-
-## 操作立场
-
-项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
-
-- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
-- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `docs/`。
-- 工作以小步、可逆、可验证的增量推进。
-- 状态不确定时，先跑基线验证再开新工。
-- 完成由新鲜证据定义，而非意图或信心。
-
-## 原则
-
-1. 一次任务只推进一个有边界的工作块。
-2. 设计新行为前先搜索现有代码、文档、脚本与测试。
-3. Shell 验证是完成权威。
-4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
-5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
-6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
-7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
-8. 不要把隐藏流程状态只留在聊天里。
-9. 不要把占位实现当作已完成交付。
-10. 新增抽象前先沿用现有局部模式。
-
-## 仓库结构
-
-- 源码：`src/`
-- 测试：`test/`
-- Skill 指令：`skills/`
-- 验证与维护脚本：`scripts/`
-- 治理与交接产物：`docs/`
-
-## 变更纪律
-
-行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
-
-当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
-
-- 设计/契约文档 — 变更后的预期
-- 测试或验证脚本 — 变更后的行为
-- progress log 或 report — 非平凡交接证据
-- ADR — 架构或公开契约决策
-- 模板 — 重复流程可复用时
-
-除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
-
-## 搜索与复用
-
-实现前先检视现有系统：
-
-- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
-- 可用时用 `rg` 做文本搜索、`fd` 找文件。
-- 引入新 helper 前先读邻近测试与 helper。
-- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
-
-在搜索证明否则之前，假设系统可能已有部分解法。
-
-## 完成纪律
-
-完成声明必须回答：
-
-- 改了什么
-- 为何选此方案
-- 哪条命令验证、结果如何
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续项
-
-验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。
+# 开发原则
+
+loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
+
+## 操作立场
+
+项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
+
+这个模型吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践中的共同经验：用短入口文档导航长期知识，用结构化任务状态和 handoff artifact 跨 session 传递事实，用独立验证和评审回路约束 agent 输出，并把人类注意力集中在意图、边界、架构和反馈系统上。面向使用者的背景资料收录在 `website/docs/practices/`。
+
+- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
+- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `docs/`。
+- 工作以小步、可逆、可验证的增量推进。
+- 状态不确定时，先跑基线验证再开新工。
+- 完成由新鲜证据定义，而非意图或信心。
+
+## 原则
+
+1. 一次任务只推进一个有边界的工作块。
+2. 设计新行为前先搜索现有代码、文档、脚本与测试。
+3. Shell 验证是完成权威。
+4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
+5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
+6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
+7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
+8. 不要把隐藏流程状态只留在聊天里。
+9. 不要把占位实现当作已完成交付。
+10. 新增抽象前先沿用现有局部模式。
+
+## 仓库结构
+
+- 源码：`src/`
+- 测试：`test/`
+- Skill 指令：`skills/`
+- 验证与维护脚本：`scripts/`
+- 治理与交接产物：`docs/`
+
+## 变更纪律
+
+行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
+
+当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
+
+- 设计/契约文档 — 变更后的预期
+- 测试或验证脚本 — 变更后的行为
+- progress log 或 report — 非平凡交接证据
+- ADR — 架构或公开契约决策
+- 模板 — 重复流程可复用时
+
+除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
+
+## 搜索与复用
+
+实现前先检视现有系统：
+
+- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
+- 可用时用 `rg` 做文本搜索、`fd` 找文件。
+- 引入新 helper 前先读邻近测试与 helper。
+- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
+
+在搜索证明否则之前，假设系统可能已有部分解法。
+
+## 完成纪律
+
+完成声明必须回答：
+
+- 改了什么
+- 为何选此方案
+- 哪条命令验证、结果如何
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续项
+
+验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。