feat(ack): add project knowledge guardrails

2026-07-31 21:09:36 +08:00
parent 7d1994cf93
commit ee66dbe9ce
32 changed files with 8353 additions and 139 deletions
@@ -0,0 +1,47 @@
+version: 1
+updatedAt: "2026-07-31T12:00:00+08:00"
+project:
+  name: "notes-web"
+verificationRegistry:
+  service-worktree-alignment:
+    path: "tests/ack/check_service_worktree.py"
+    args: ["--require-current-commit"]
+entries:
+  - id: "K-001"
+    revision: 1
+    kind: "verification"
+    status: "active"
+    title: "复测前确认服务与 worktree/commit 对齐"
+    subject: "service-worktree-alignment"
+    scope:
+      all: false
+      components: ["web"]
+      paths: ["web/**"]
+      dependencies: []
+      versions: []
+      tags: ["long-running-service"]
+      symbols: []
+      errorSignatures: []
+    appliesWhen: "修改常驻 Web 服务或前端构建产物"
+    directive: "复测前重启服务，并核对服务实例对应的 worktree 与 commit"
+    rationale: "历史任务曾因 Test 连接旧进程而产生假通过"
+    verification:
+      ref: "service-worktree-alignment"
+      expected: "服务实例、worktree 和 commit 一致"
+    provenance:
+      taskId: "BUG-002"
+      attemptId: "BUG-002-A2"
+      codeRef: "abc1234"
+      evidenceRef: "tasks.yaml#BUG-002"
+    owner: "web-team"
+    author: "developer"
+    reviewer: "test"
+    approval: null
+    createdAt: "2026-07-30T10:00:00+08:00"
+    lastValidatedAt: "2026-07-31T11:00:00+08:00"
+    reviewAfter: "2099-10-31T11:00:00+08:00"
+    temporary: false
+    removalCondition: null
+    statusReason: null
+    supersedes: []
+    conflictsWith: []
@@ -1,9 +1,10 @@
 # notes-web Agent 协作协议（示例，项目覆盖层）

-> 本项目基于 ack v0.8.1。
+> 本项目基于 ack v0.9.0。
 > 通用规范由 `/ack` 从 Skill 自身的 `references/` 读取，本文件只填项目差异。
 > 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
-> `docs/ack/` 只保存 `project.md` 与 `tasks.yaml`。
+> ACK 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+> `docs/ack/` 只保存 `project.md`、`tasks.yaml` 与 `knowledge.yaml`。

 ## 项目概览

@@ -12,6 +13,7 @@
 - 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
 - Base URL：`http://localhost:5173`
 - 任务板：`docs/ack/tasks.yaml`
+- 项目知识：`docs/ack/knowledge.yaml`
 - 覆盖层文件：`docs/ack/project.md`

 ## 稳定规范（引用，不重复）
@@ -44,6 +46,7 @@
 | `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 |
 | `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 |
 | `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
+| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |

 ## 命令

@@ -63,13 +66,22 @@ curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
 # 浏览器回归：tests/browser/cases/*.md
 ```

-任务板校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py` 执行。
+项目已审查的知识检查入口保存在 `knowledge.yaml.verificationRegistry`，格式为检查
+ID 对应仓库内相对 path 和结构化 args。知识正文不保存或自动执行自由 shell 命令。
+执行时只把检查 ID 交给 Skill 的 `scripts/run_verification.py`，不直接拼接
+path/args。
+项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py` 和
+`scripts/validate_knowledge.py` 执行。

 ## 硬规则（其余见 references/）

 - 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
 - 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 references/model-routing.md）。
 - `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
- 只有 Coordinator 写 `tasks.yaml`；Test 与 Developer 只读。
+- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Test 与 Developer 只读。
+- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
+  `candidate` 不派发，知识库不全量注入。
+- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
+  `knowledgeChecks`；关键约束应继续下沉到测试、lint、CI 或正式规范。
 - 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
 - 不提交或推送，除非用户明确要求。
@@ -2,12 +2,14 @@
 version: 1
 updatedAt: "2026-07-06T09:40:00+08:00"
 source: "Coordinator (PM) Agent"
-ackVersion: "0.8.1"
+ackVersion: "0.9.0"
 project:
  name: "notes-web"
  repoPath: "/home/dev/notes-web"
  baseUrl: "http://localhost:5173"
  devWorktree: "/home/dev/notes-web-wt/fix-preview"
+  overlayFile: "docs/ack/project.md"
+  knowledgeFile: "docs/ack/knowledge.yaml"

 summary:
  verified: ["BUG-002"]
@@ -27,6 +29,19 @@ tasks:
      - "docs/spec/fix-preview.md#preview"
    testRefs:
      - "tests/browser/cases/01-preview.md"
+    knowledgeRefs:
+      - "K-001@1"
+    knowledgeApplied:
+      - ref: "K-001@1"
+        result: "applied"
+        evidence: "重启服务并核对 commit 后再交给 Test"
+    knowledgeCandidates: []
+    knowledgeChecks:
+      - ref: "K-001@1"
+        result: "passed"
+        evidence: "服务实例、worktree 与 commit 9f8e7d6 一致"
+        checkedBy: "test-worker-1"
+        checkedAt: "2026-07-06T09:36:00+08:00"
    description: >
      用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
    stepsToReproduce:
@@ -55,9 +70,11 @@ tasks:
      worker: "dev-worker-1"
      rounds:
        - round: 1
+          attemptId: "BUG-002-A1"
          result: failed
          evidence: "只渲染了 title，缺少 before/after/coverChanged"
        - round: 2
+          attemptId: "BUG-002-A2"
          result: passed
          evidence: "复测 4 行 diff 全部出现，取消不触发写入"
    resolution:
@@ -76,6 +93,24 @@ tasks:
    specRefs:
      - "docs/spec/concurrency.md"
    testRefs: []
+    knowledgeRefs: []
+    knowledgeApplied: []
+    knowledgeCandidates:
+      - kind: "pitfall"
+        title: "乐观锁检查必须覆盖批量导入路径"
+        claim: "只在 API 写入路径检查版本号会漏掉批量导入"
+        scope:
+          components: ["server-store"]
+          paths: ["server/store/**"]
+          tags: ["concurrency"]
+        appliesWhen: "修改 note 的并发写入或批量导入逻辑"
+        directive: "同时验证 API 与批量导入的版本冲突处理"
+        rationale: "第二轮修复只覆盖 API，批量导入仍可静默覆盖"
+        evidenceRefs:
+          - "tasks.yaml#BUG-003-round-2"
+        proposedBy: "test-worker-1"
+        proposedAt: "2026-07-06T09:32:00+08:00"
+    knowledgeChecks: []
    description: >
      两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
    stepsToReproduce:
@@ -100,12 +135,15 @@ tasks:
      worker: "dev-worker-1"
      rounds:
        - round: 1
+          attemptId: "BUG-003-A1"
          result: failed
          evidence: "加了版本号但未在写入路径校验"
        - round: 2
+          attemptId: "BUG-003-A2"
          result: failed
          evidence: "校验只覆盖 API，未覆盖批量导入路径"
        - round: 3
+          attemptId: "BUG-003-A3"
          result: failed
          evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
    resolution: