docs(logbook): record stale km completion preview rollout [skip ci]

2026-05-24 23:26:36 +08:00
parent 825de2ef58
commit ede2b3752b
1 changed files with 102 additions and 0 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -1,3 +1,105 @@
+## 2026-05-24｜T161 KM stale completion queue filters + batch dry-run preview
+
+**觸發**：
+
+- T160 已把 owner-review completion 分成 ready / blocked / completed / failed，但 operator 還缺篩選與批次預覽，無法快速看「這批能不能逐筆乾跑」。
+- 使用者要求前端呈現已完成與推進中工作，且不能讓批次操作被誤解成 AI 已自動批量寫 KM。
+- 本階段目標是加上 owner-review completion queue filter 與 batch dry-run preview；批次只讀、不寫 KM、不寫治理 audit。
+
+**修正**：
+
+- `GET /api/v1/ai/governance/km-stale-owner-review-completion-queue` 新增篩選：
+  - `priority_tier=P0|P1|P2` 可重複傳。
+  - `recommended_completion_outcome=all|refresh_with_evidence|archive|supersede`。
+  - `batch_governance_event_id`。
+  - `can_preview=true|false`。
+- 新增 `POST /api/v1/ai/governance/km-stale-owner-review-completion-queue/batch-preview`：
+  - schema `km_stale_owner_review_completion_batch_preview_v1`。
+  - 回傳 candidate / previewable / blocked / completed / failed count。
+  - 回傳 batch preview fingerprint。
+  - guardrail：`writes_km=false`、`writes_governance_audit=false`、`batch_writes_allowed=false`、`manual_review_required=true`。
+  - 不建立 batch executor、不新增 governance audit row；每筆 completion 仍必須走單筆 dry-run fingerprint + owner confirm。
+- AwoooP Work Items / AI 治理 / Completion 分流佇列新增：
+  - readiness filters：可處理 / 卡住 / 已完成 / 失敗 / 待處理 / 全部。
+  - priority filters：全部優先級 / P0 / P1 / P2。
+  - 批次預覽按鈕與 dry-run 結果摘要，明確顯示批次寫入=false。
+
+**local verification**：
+
+```text
+python3 -m py_compile apps/api/src/models/governance.py apps/api/src/services/governance_km_stale_review_service.py apps/api/src/api/v1/ai_governance.py apps/api/tests/test_ai_governance_endpoints.py -> OK
+/Users/ogt/.pyenv/shims/ruff check apps/api/src/models/governance.py apps/api/src/services/governance_km_stale_review_service.py apps/api/src/api/v1/ai_governance.py apps/api/tests/test_ai_governance_endpoints.py -> OK
+DATABASE_URL='postgresql+asyncpg://test:test@localhost/test' /Users/ogt/.pyenv/shims/pytest apps/api/tests/test_ai_governance_endpoints.py -q
+  -> 60 passed
+DATABASE_URL='postgresql+asyncpg://test:test@localhost/test' /Users/ogt/.pyenv/shims/pytest apps/api/tests/test_ai_governance_endpoints.py apps/api/tests/test_governance_agent.py apps/api/tests/test_hermes_kb_growth_worker.py apps/api/tests/test_governance_dispatcher.py -q
+  -> 110 passed
+pnpm --dir apps/web exec next lint --file 'src/app/[locale]/awooop/work-items/page.tsx' -> OK
+pnpm --filter @awoooi/web exec tsc --noEmit --incremental false -> OK
+json parse apps/web/messages/zh-TW.json apps/web/messages/en.json -> OK
+git diff --check -> OK
+local Browser smoke:
+  /zh-TW/awooop/work-items?project_id=awoooi
+  hasCompletionQueue=true, hasReadyFilter=true, hasBatchPreview=true, hasPriorityAll=true, hasCriticalError=false
+```
+
+**production deploy / smoke**：
+
+```text
+code commit:
+4cfc6a4c feat(governance): preview stale km completion batches
+
+deploy marker:
+825de2ef chore(cd): deploy 4cfc6a4 [skip ci]
+
+Gitea Actions:
+3011 CD -> success
+  tests 3973 -> success
+  build-and-deploy 3974 -> success
+  post-deploy-checks 3975 -> success
+3012 AI Code Review -> success
+3013 Type Sync Check -> success
+
+K8s:
+awoooi-api    image=.../api:4cfc6a4c7915b71c2ce3aa57ab37a6c8d023f195 ready=2/2
+awoooi-web    image=.../web:4cfc6a4c7915b71c2ce3aa57ab37a6c8d023f195 ready=2/2
+awoooi-worker image=.../api:4cfc6a4c7915b71c2ce3aa57ab37a6c8d023f195 ready=1/1
+
+completion queue filtered API:
+schema_version=km_stale_owner_review_completion_queue_v1
+project_id=awoooi
+status_bucket=ready
+priority_tiers=P0
+can_preview=True
+total=10
+returned=5
+ready_count=10
+batch_writes_allowed=False
+first=bf81a30d-6abe-4c0c-b4ba-9c0ba0d761bf|ready|P0|True|preview_stale_km_review_completion
+
+completion batch preview API:
+schema_version=km_stale_owner_review_completion_batch_preview_v1
+status=dry_run
+candidate_count=5
+previewable_count=5
+blocked_count=0
+writes_km=False
+writes_governance_audit=False
+batch_writes_allowed=False
+
+Browser production smoke:
+  hasCompletionUnavailable=false
+  hasPreviewFingerprint=true
+  hasBatchWritesGuardrail=true
+  hasReadyTen=true
+  hasCriticalError=false
+  screenshot=/tmp/t161-completion-batch-preview-production-final.png
+```
+
+**下一步**：
+
+- T162：把 KM stale completion queue 狀態回寫到 Work Items summary 與 Telegram 詳情/歷史，讓告警卡能看到 completion queue 狀態與 owner-review 卡點。
+- T163：處理頁面仍顯示的「完整自動修復聲明：不可宣稱」缺口，把 execution / verification / KM / learning 回寫缺口接到更可操作的 owner work items。
+
 ## 2026-05-24｜T160 KM stale owner-review completion queue

 **觸發**：