@guanlin4924/devflow-pi 0.1.93 → 0.1.95

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/assets/baseline-template.md

@@ -5,11 +5,11 @@
 - **来源类型**：{{PRD / 会议纪要 / 用户描述 / 其他}}
 - **来源文件/说明**：{{来源}}
 - **生成时间**：{{日期}}
-- **项目上下文**：`.planning/PROJECT.md`
-- **项目导航**：`.planning/navigation/INDEX.md`
+- **项目上下文**：`.devflow/planning/PROJECT.md`
+- **项目导航**：`.devflow/planning/navigation/INDEX.md`
 - **功能名称**：{{功能名称}}
-- **功能目录名**：{{功能名，用于 .planning/features/{功能名}/}}
-- **下游输出目录**：`.planning/features/{{功能名}}/`
+- **功能目录名**：{{功能名，用于 .devflow/planning/features/{功能名}/}}
+- **下游输出目录**：`.devflow/planning/features/{{功能名}}/`
 
 ## 二、需求整理摘要
 
@@ -138,11 +138,11 @@
 
 | 来源类型 | 路径/范围 | 结论 |
 |----------|-----------|------|
-| 里程碑 | `.planning/milestones/...` | {{相关/无相关/不存在/未扫描原因}} |
-| 历史需求基线 | `.planning/requirements/...` | {{相关/无相关/不存在/未扫描原因}} |
-| 经验教训 | `.planning/lessons/...` | {{相关/无相关/不存在/未扫描原因}} |
-| 阶段上下文 | `.planning/*/CONTEXT.md` | {{相关/无相关/不存在/未扫描原因}} |
-| Legacy/项目规则历史 | `features/` / `.context/lessons/` / `.context/workflow/` | {{如存在则记录；不存在则写“不适用”}} |
+| 里程碑 | `.devflow/planning/milestones/...` | {{相关/无相关/不存在/未扫描原因}} |
+| 历史需求基线 | `.devflow/planning/requirements/...` | {{相关/无相关/不存在/未扫描原因}} |
+| 经验教训 | `.devflow/planning/lessons/...` | {{相关/无相关/不存在/未扫描原因}} |
+| 阶段上下文 | `.devflow/planning/*/CONTEXT.md` | {{相关/无相关/不存在/未扫描原因}} |
+| Legacy/项目规则历史 | `features/` / `.devflow/context/lessons/` / `.devflow/context/workflow/` | {{如存在则记录；不存在则写“不适用”}} |
 
 ### 9.2 关联历史功能/里程碑
 
@@ -169,7 +169,7 @@
 统一使用以下功能目录，后续 skill 不得重新生成不同目录名：
 
 - **功能名**：{{功能名}}
-- **输出目录**：`.planning/features/{{功能名}}/`
+- **输出目录**：`.devflow/planning/features/{{功能名}}/`
 - **当前功能切片**：读取本文档“当前功能切片”中的当前 FP/BR/BC。
 - **当前执行切片**：读取本文档“3.0a 当前执行切片范围”。非当前切片只能作为依赖上下文，不得生成实现任务。
 - **跨功能依赖**：读取 `depends_on` 引用的历史 FP/BR/BC 详情，不得只读当前 FP 而忽略依赖项。
@@ -178,37 +178,37 @@
 
 - 读取本文档的当前功能切片、`depends_on` 引用详情、功能点详情、业务规则、边界场景。
 - 输出必须带当前 `Slice ID`，且只展开当前执行切片。
-- 输出 `.planning/features/{{功能名}}/功能点梳理.md`。
+- 输出 `.devflow/planning/features/{{功能名}}/功能点梳理.md`。
 
 ### 11.1a 给测试指导书
 
-- 读取 `.planning/features/{{功能名}}/功能点梳理.md`（主要输入）和本文档的 FP/BR/BC/CR 关联。
-- 同时读取 `.planning/PROJECT.md`。
+- 读取 `.devflow/planning/features/{{功能名}}/功能点梳理.md`（主要输入）和本文档的 FP/BR/BC/CR 关联。
+- 同时读取 `.devflow/planning/PROJECT.md`。
 - 此步骤为可选，不阻塞下游门禁。
-- 输出 `.planning/features/{{功能名}}/测试指导书.md`。
+- 输出 `.devflow/planning/features/{{功能名}}/测试指导书.md`。
 
 ### 11.2 给前端技术方案
 
-- 读取 `.planning/features/{{功能名}}/功能点梳理.md` 中的页面/组件/字段/交互拆解。
+- 读取 `.devflow/planning/features/{{功能名}}/功能点梳理.md` 中的页面/组件/字段/交互拆解。
 - 只为当前执行切片生成前端方案；后置切片只列为依赖或后续范围。
 - 读取本文档的当前功能切片、跨功能依赖、涉及页面/模块、入口/触发、主流程、边界场景、数据要求。
-- 同时读取 `.planning/navigation/INDEX.md` → 筛选前端类型代码库 → 加载对应 navigation 文件。
-- 输出 `.planning/features/{{功能名}}/前端技术方案.md`。
+- 同时读取 `.devflow/planning/navigation/INDEX.md` → 筛选前端类型代码库 → 加载对应 navigation 文件。
+- 输出 `.devflow/planning/features/{{功能名}}/前端技术方案.md`。
 
 ### 11.3 给后端技术方案
 
-- 读取 `.planning/features/{{功能名}}/功能点梳理.md` 中的 API/服务节点和逻辑维度。
+- 读取 `.devflow/planning/features/{{功能名}}/功能点梳理.md` 中的 API/服务节点和逻辑维度。
 - 只为当前执行切片生成后端方案；共享能力若服务于后置切片，必须有当前切片可验证门禁。
 - 读取本文档的当前功能切片、跨功能依赖、业务规则、数据要求、与历史功能/里程碑的关联、兼容性要求、边界场景、代码现实对照。
-- 同时读取 `.planning/navigation/INDEX.md` → 筛选后端/服务类型代码库 → 加载对应 navigation 文件。
-- 输出 `.planning/features/{{功能名}}/后端技术方案.md`。
+- 同时读取 `.devflow/planning/navigation/INDEX.md` → 筛选后端/服务类型代码库 → 加载对应 navigation 文件。
+- 输出 `.devflow/planning/features/{{功能名}}/后端技术方案.md`。
 
 ### 11.4 给变更清单
 
 - 读取本文档的功能点、业务规则、边界场景、反向审视与用户拍板。
-- 同时读取 `.planning/features/{{功能名}}/前端技术方案.md` 和 `.planning/features/{{功能名}}/后端技术方案.md`。
+- 同时读取 `.devflow/planning/features/{{功能名}}/前端技术方案.md` 和 `.devflow/planning/features/{{功能名}}/后端技术方案.md`。
 - 变更任务必须标注 `Slice ID`；不得生成后置切片的实现任务。
-- 输出 `.planning/features/{{功能名}}/变更清单.md`。
+- 输出 `.devflow/planning/features/{{功能名}}/变更清单.md`。
 
 ### 11.5 给测试验收
 

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/references/antipatterns.md

@@ -35,13 +35,13 @@ Required:
 Wrong:
 
 - Assuming the project keeps outbound-call style `features/*.spec.md` history.
-- Treating `.context/lessons/README.md` as the only source of historical product or requirement decisions.
+- Treating `.devflow/context/lessons/README.md` as the only source of historical product or requirement decisions.
 - Ignoring milestone artifacts because their filenames differ from spec documents.
 
 Required:
 
-- Use this workflow's primary history model first: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, and `.planning/*/CONTEXT.md`.
-- Treat `features/`, `.context/lessons/`, and `.context/workflow/` as optional legacy or project-rule evidence when present.
+- Use this workflow's primary history model first: `.devflow/planning/milestones/`, `.devflow/planning/requirements/`, `.devflow/planning/lessons/`, and `.devflow/planning/*/CONTEXT.md`.
+- Treat `features/`, `.devflow/context/lessons/`, and `.devflow/context/workflow/` as optional legacy or project-rule evidence when present.
 - Record exactly which history sources were checked.
 
 ## Implementation Leakage

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/references/challenge-review-guide.md

@@ -25,7 +25,7 @@ Do not:
 
 ## Entry Triage Carry-Forward
 
-If `.planning/requirements/{功能名}/入口分诊.md` exists, start challenge review from its findings:
+If `.devflow/planning/requirements/{功能名}/入口分诊.md` exists, start challenge review from its findings:
 
 - Duplicate or already-done evidence feeds C1 and C2.
 - Prior rejection / out-of-scope evidence feeds C3 and may block baseline until the user explicitly reverses it.
@@ -96,8 +96,8 @@ Do not silently choose. The user must decide when the choice changes scope, sema
 
 Search available history before claiming there is no precedent:
 
-- Primary workflow history: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, and `.planning/*/CONTEXT.md`.
-- Optional legacy/project-rule history when present: `features/`, `.context/lessons/README.md`, `.context/workflow/`, root `AGENTS.md`, and root `CLAUDE.md`.
+- Primary workflow history: `.devflow/planning/milestones/`, `.devflow/planning/requirements/`, `.devflow/planning/lessons/`, and `.devflow/planning/*/CONTEXT.md`.
+- Optional legacy/project-rule history when present: `features/`, `.devflow/context/lessons/README.md`, `.devflow/context/workflow/`, root `AGENTS.md`, and root `CLAUDE.md`.
 
 Do not assume outbound-call style `features/*.spec.md` exists. This workflow's normal long-term memory is milestone/planning based.
 

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/references/project-context-guide.md

@@ -2,20 +2,20 @@
 
 ## 加载顺序
 
-1. `.planning/PROJECT.md` — 项目上下文和已上线能力
-2. `.planning/navigation/INDEX.md` — 代码库注册表（Codebase Registry），从中识别与需求相关的代码库
-3. `.planning/navigation/{name}.md` — 加载 INDEX.md 中标识的相关代码库的导航文件
-4. `.planning/milestones/` — 归档的里程碑记录，是本工作流的主要历史口径
-5. `.planning/requirements/` — 已确认或历史需求基线
-6. `.planning/lessons/` — 跨里程碑经验教训
-7. `.planning/*/CONTEXT.md` — 之前阶段的决策记录
-8. `features/`、`.context/lessons/`、`.context/workflow/` — 仅当目标项目存在时作为兼容历史或项目规则来源，不作为默认历史口径
+1. `.devflow/planning/PROJECT.md` — 项目上下文和已上线能力
+2. `.devflow/planning/navigation/INDEX.md` — 代码库注册表（Codebase Registry），从中识别与需求相关的代码库
+3. `.devflow/planning/navigation/{name}.md` — 加载 INDEX.md 中标识的相关代码库的导航文件
+4. `.devflow/planning/milestones/` — 归档的里程碑记录，是本工作流的主要历史口径
+5. `.devflow/planning/requirements/` — 已确认或历史需求基线
+6. `.devflow/planning/lessons/` — 跨里程碑经验教训
+7. `.devflow/planning/*/CONTEXT.md` — 之前阶段的决策记录
+8. `features/`、`.devflow/context/lessons/`、`.devflow/context/workflow/` — 仅当目标项目存在时作为兼容历史或项目规则来源，不作为默认历史口径
 
 ## 对比分析要点
 
 ### 入口分诊证据复用
 
-- 如果 `.planning/requirements/{功能名}/入口分诊.md` 存在，先读取其中的"已实现/重叠检查"和"历史拒绝/范围检查"。
+- 如果 `.devflow/planning/requirements/{功能名}/入口分诊.md` 存在，先读取其中的"已实现/重叠检查"和"历史拒绝/范围检查"。
 - 分诊结果只能作为 Phase 4/4.5 的优先证据入口，不能替代源码比差。
 - 当分诊结论为 `already_done`、`wontfix` 或 `ready_for_human` 时，baseline 不应继续生成通过状态，除非用户明确改变范围或推翻历史决策。
 - 分诊已搜索的来源必须并入 baseline 的搜索来源记录，避免重复声明"未发现历史"。
@@ -39,8 +39,8 @@
 
 ### 历史口径映射
 
-- outbound-call 中的 `features/*.spec.md` 对应本工作流里的 `.planning/milestones/`、`.planning/requirements/baseline.md` 和阶段 `CONTEXT.md`。
-- outbound-call 中的 `.context/lessons/README.md` 对应本工作流里的 `.planning/lessons/README.md`；如果目标项目同时存在 `.context/lessons/`，将其标为项目规则/遗留经验来源。
+- outbound-call 中的 `features/*.spec.md` 对应本工作流里的 `.devflow/planning/milestones/`、`.devflow/planning/requirements/baseline.md` 和阶段 `CONTEXT.md`。
+- outbound-call 中的 `.devflow/context/lessons/README.md` 对应本工作流里的 `.devflow/planning/lessons/README.md`；如果目标项目同时存在 `.devflow/context/lessons/`，将其标为项目规则/遗留经验来源。
 - 输出时必须写清楚实际搜索了哪些目录或文件，不能只写"未发现历史"。
 
 ## 三级递进审查

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/references/questioning.md

@@ -16,7 +16,7 @@
 4. 已形成代码路由摘要：可能相关模块、候选源码路径、映射到这些路径的需求词、需要 Phase 4 深查的问题
 5. 已将问题绑定到来源、现有模块、候选 FP/BR/BC/CR，或图片阻塞点
 
-如果只读了 `.planning/navigation/*.md` 或只做了 Phase 1.5 轻量路由扫描，不得声称“当前系统已支持/不支持某能力”。只能说“可能相关”，并在 Phase 4 Level 2 下钻源码后再产出行为结论。
+如果只读了 `.devflow/planning/navigation/*.md` 或只做了 Phase 1.5 轻量路由扫描，不得声称“当前系统已支持/不支持某能力”。只能说“可能相关”，并在 Phase 4 Level 2 下钻源码后再产出行为结论。
 
 在 Phase 2 之前，只允许问会阻塞需求理解的输入澄清问题，例如 `critical_image` 无法识别、核心业务目标缺失、需求明显指向多个现有模块但无法判断边界。
 

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/references/requirement-review-checklist.md

@@ -54,7 +54,7 @@ Use this checklist after feature point decomposition and before writing the base
 - [ ] 每个涉及已有代码的 FP，已从导航 Call Chain Map 提取受影响的文件清单：
   - 前端：受影响的路由、页面组件、composable、API 模块
   - 后端：受影响的 handler、service、repository、DAO
-- [ ] 如果 `.planning/code-index/` 存在，已通过 `code-index-query` 查询需求关键词、API 路径、页面名、字段名、状态名、表/配置/资源名，并记录使用到的 symbol/relation id
+- [ ] 如果 `.devflow/planning/code-index/` 存在，已通过 `code-index-query` 查询需求关键词、API 路径、页面名、字段名、状态名、表/配置/资源名，并记录使用到的 symbol/relation id
 - [ ] 调用链重叠类型已判断：扩展已有调用链 vs 新建独立调用链
 - [ ] 契约影响已预判：修改已有接口/参数时，已检查 Call Chain Map 中的其他调用方
 - [ ] 受影响的调用链文件、路由、API 路径已写回 FP 的"关联已有模块"
@@ -88,8 +88,8 @@ Level 2 发现"已存在且一致"或"已存在但冲突"时启动。
 - Historical feature overlap is classified as new, modify, replace, or affect.
 - Compatibility requirements are recorded.
 - Reuse opportunities are checked across business capability, installed library, and project pattern layers.
-- Historical lessons or prior work are searched using the workflow history model first: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, and `.planning/*/CONTEXT.md`.
-- Legacy history such as `features/` or `.context/lessons/` is used only when present and is labeled as legacy/project-rule evidence.
+- Historical lessons or prior work are searched using the workflow history model first: `.devflow/planning/milestones/`, `.devflow/planning/requirements/`, `.devflow/planning/lessons/`, and `.devflow/planning/*/CONTEXT.md`.
+- Legacy history such as `features/` or `.devflow/context/lessons/` is used only when present and is labeled as legacy/project-rule evidence.
 - The searched sources are recorded before claiming no related history.
 
 ### Challenge Review
@@ -103,7 +103,7 @@ Level 2 发现"已存在且一致"或"已存在但冲突"时启动。
 
 ### Downstream Readiness
 
-- One canonical feature name and `.planning/features/{功能名}/` output directory are defined.
+- One canonical feature name and `.devflow/planning/features/{功能名}/` output directory are defined.
 - Current feature slice and `depends_on` are sufficient for downstream skills to load current scope plus required historical context.
 - Frontend has enough information to identify pages, interactions, states, and API dependencies.
 - Backend has enough information to identify data, services, interfaces, rules, and risks.

package/plugins/devflow-requirements/skills/workflow-requirement-triage/SKILL.md

@@ -11,8 +11,8 @@ description: "Use as the lightweight first step for a new request, bug report, P
 
 Always create or update:
 
-- `.planning/requirements/{功能名}/入口分诊.md`
-- `.planning/requirements/{功能名}/入口分诊.meta.json`
+- `.devflow/planning/requirements/{功能名}/入口分诊.md`
+- `.devflow/planning/requirements/{功能名}/入口分诊.meta.json`
 
 `入口分诊.meta.json` minimum fields:
 
@@ -89,13 +89,13 @@ Search by domain concept, not just exact words.
 
 Required sources:
 
-1. `.planning/requirements/baseline.md`
-2. `.planning/features/`
-3. `.planning/milestones/`
-4. `.planning/lessons/`
-5. `.planning/*/CONTEXT.md`
-6. `.planning/navigation/INDEX.md` and relevant navigation files
-7. `code-index-query` against `.planning/code-index/` when present, for shallow symbol/entrypoint/resource candidate lookup
+1. `.devflow/planning/requirements/baseline.md`
+2. `.devflow/planning/features/`
+3. `.devflow/planning/milestones/`
+4. `.devflow/planning/lessons/`
+5. `.devflow/planning/*/CONTEXT.md`
+6. `.devflow/planning/navigation/INDEX.md` and relevant navigation files
+7. `code-index-query` against `.devflow/planning/code-index/` when present, for shallow symbol/entrypoint/resource candidate lookup
 8. Actual source files only enough to confirm whether a likely capability exists
 
 Search strategy:
@@ -128,13 +128,13 @@ Search for prior decisions that intentionally avoided this request.
 
 Required sources:
 
-- `.planning/requirements/baseline.md`
-- `.planning/features/**/需求梳理.md`
-- `.planning/features/**/需求澄清记录.md`
-- `.planning/features/**/PROGRESS.md`
-- `.planning/milestones/`
-- `.planning/lessons/`
-- `.planning/*/CONTEXT.md`
+- `.devflow/planning/requirements/baseline.md`
+- `.devflow/planning/features/**/需求梳理.md`
+- `.devflow/planning/features/**/需求澄清记录.md`
+- `.devflow/planning/features/**/PROGRESS.md`
+- `.devflow/planning/milestones/`
+- `.devflow/planning/lessons/`
+- `.devflow/planning/*/CONTEXT.md`
 - `.out-of-scope/` if present
 
 Treat these as prior rejection signals:

package/plugins/devflow-requirements/skills/workflow-wayfinder/SKILL.md

@@ -11,11 +11,11 @@ description: "Use when a requirement is too large or foggy for one clarification
 
 Always create or update:
 
-- `.planning/requirements/{功能名}/决策地图.md`
-- `.planning/requirements/{功能名}/决策地图.meta.json`
-- `.planning/requirements/{功能名}/source_units.yaml` (Core-generated)
-- `.planning/requirements/{功能名}/coverage.yaml`
-- `.planning/requirements/{功能名}/wayfinder/WF-xxx.md` for each ticket
+- `.devflow/planning/requirements/{功能名}/决策地图.md`
+- `.devflow/planning/requirements/{功能名}/决策地图.meta.json`
+- `.devflow/planning/requirements/{功能名}/source_units.yaml` (Core-generated)
+- `.devflow/planning/requirements/{功能名}/coverage.yaml`
+- `.devflow/planning/requirements/{功能名}/wayfinder/WF-xxx.md` for each ticket
 
 `决策地图.meta.json` minimum fields:
 
@@ -75,7 +75,7 @@ Do not merge `Grilling` and `Task`: a question to the user and a local artifact
 
 ## Phase 1 — Chart The First Map
 
-1. Read `.planning/requirements/{功能名}/入口分诊.md`.
+1. Read `.devflow/planning/requirements/{功能名}/入口分诊.md`.
 2. Read the raw user input and only the project context needed to understand the uncertainty.
 3. Run the **Source Coherence Gate** below before declaring Fog or creating any Grilling ticket.
 4. Write:

package/src/approval-store.ts

@@ -0,0 +1,340 @@
+import { randomUUID } from "node:crypto";
+import type { Database } from "bun:sqlite";
+
+/**
+ * Core human-approval primitive (control.db, schema v3).
+ *
+ * `proposeApproval` may be reached from an agent tool. `confirmApproval` must
+ * only be called from the runtime extension's interactive UI callback: there
+ * is deliberately no CLI or agent-tool entry point for it.
+ */
+
+export const APPROVAL_KINDS = ["execution_plan", "environment_profile", "mode_override", "human_result"] as const;
+export type ApprovalKind = typeof APPROVAL_KINDS[number];
+export const HUMAN_RESULT_STATUSES = ["passed", "failed", "blocked"] as const;
+export type HumanResultStatus = typeof HUMAN_RESULT_STATUSES[number];
+export type ProposalStatus = "proposed" | "consumed" | "rejected" | "expired";
+
+/** An unconfirmed proposal older than this can no longer be confirmed. */
+export const PROPOSAL_TTL_MS = 24 * 60 * 60 * 1000;
+export const APPROVED_VIA = "runtime_ui_confirm";
+
+export type ApprovalErrorCode =
+  | "approval_requires_database_authority"
+  | "invalid_proposal"
+  | "invalid_decision"
+  | "proposal_not_found"
+  | "proposal_not_pending"
+  | "proposal_expired"
+  | "pins_unavailable"
+  | "pins_mismatch"
+  | "state_revision_mismatch";
+
+export class ApprovalError extends Error {
+  constructor(readonly code: ApprovalErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = "ApprovalError";
+  }
+}
+
+export interface ProposalRecord {
+  id: string;
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  payload: Record<string, unknown>;
+  pins: Record<string, unknown>;
+  stateRevision: number;
+  status: ProposalStatus;
+  createdAt: string;
+  resolvedAt: string | null;
+}
+
+export interface ApprovalRecord {
+  id: string;
+  proposalId: string;
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  pins: Record<string, unknown>;
+  decision: Record<string, unknown>;
+  approvedVia: string;
+  approvedAt: string;
+  supersededAt: string | null;
+}
+
+export interface ProposeInput {
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  payload: Record<string, unknown>;
+  pins: Record<string, unknown>;
+  stateRevision: number;
+}
+
+export interface CurrentPins {
+  pins: Record<string, unknown>;
+  stateRevision: number;
+}
+
+export interface ConfirmInput {
+  projectId: string;
+  proposalId: string;
+  decision: Record<string, unknown>;
+  /**
+   * Recomputes the current pins for the stored proposal. It runs inside the
+   * write transaction (BEGIN IMMEDIATE), so it must be synchronous.
+   */
+  recompute: (proposal: ProposalRecord) => CurrentPins;
+  now?: Date;
+}
+
+export type ConfirmResult =
+  | { ok: true; approvalId: string; supersededIds: string[] }
+  | { ok: false; code: ApprovalErrorCode; message: string };
+
+/** Deterministic key-sorted JSON used to compare pins. */
+export function canonicalPinsJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalPinsJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value as Record<string, unknown>).sort().map(key => `${JSON.stringify(key)}:${canonicalPinsJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isKind(value: unknown): value is ApprovalKind {
+  return typeof value === "string" && (APPROVAL_KINDS as readonly string[]).includes(value);
+}
+
+const PIN_KEYS: Record<ApprovalKind, string[]> = {
+  execution_plan: ["dsl_sha256", "suite_fingerprint", "suite_graph_revision", "tc_sha256"],
+  environment_profile: ["profile_sha256"],
+  mode_override: ["binding_entry_sha256", "from", "suite_fingerprint", "tc_sha256", "to"],
+  human_result: ["evidence", "suite_fingerprint", "tc_sha256"],
+};
+
+/** Enforces the change-list §1.8 subject_key and pins_json shapes. */
+export function validatePinsShape(kind: ApprovalKind, subjectKey: string, pins: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  const keys = Object.keys(pins).sort();
+  if (canonicalPinsJson(keys) !== canonicalPinsJson(PIN_KEYS[kind])) errors.push(`${kind} pins must contain exactly: ${PIN_KEYS[kind].join(", ")}`);
+  if (kind === "environment_profile") {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(subjectKey)) errors.push("environment_profile subject_key must be a profile name");
+  } else if (!/^TC-[A-Za-z0-9_-]+$/.test(subjectKey)) {
+    errors.push(`${kind} subject_key must be a TC id`);
+  }
+  for (const key of keys) {
+    const value = pins[key];
+    if (key.endsWith("sha256") || key === "suite_fingerprint") {
+      if (typeof value !== "string" || value.length === 0) errors.push(`pin ${key} must be a non-empty string`);
+    }
+  }
+  if (kind === "human_result") {
+    const evidence = pins.evidence;
+    if (!Array.isArray(evidence) || evidence.some(item => !isRecord(item) || typeof item.path !== "string" || typeof item.sha256 !== "string")) {
+      errors.push("human_result evidence pins must be [{path, sha256}]");
+    }
+  }
+  return errors;
+}
+
+/** Validates a UI decision; human_result verdicts must come from the user. */
+export function validateDecision(kind: ApprovalKind, decision: Record<string, unknown>, pins: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  if (kind === "human_result") {
+    const keys = Object.keys(decision).sort();
+    if (canonicalPinsJson(keys) !== canonicalPinsJson(["actual_result", "status"])) errors.push("human_result decision must contain exactly status and actual_result");
+    if (!(HUMAN_RESULT_STATUSES as readonly string[]).includes(String(decision.status))) errors.push("human_result status must be passed, failed, or blocked");
+    if (typeof decision.actual_result !== "string" || !decision.actual_result.trim()) errors.push("human_result actual_result is required");
+    if (decision.status === "passed" && (!Array.isArray(pins.evidence) || pins.evidence.length === 0)) errors.push("a passed human_result requires at least one pinned evidence file");
+  } else if (canonicalPinsJson(decision) !== canonicalPinsJson({ approved: true })) {
+    errors.push(`${kind} decision must be {approved: true}`);
+  }
+  return errors;
+}
+
+export function databaseAuthority(db: Database, projectId: string): string | null {
+  const row = db.query("SELECT authority FROM authority_state WHERE project_id=?").get(projectId) as { authority: string } | null;
+  return row?.authority ?? null;
+}
+
+function assertDatabaseAuthority(db: Database, projectId: string): void {
+  const authority = databaseAuthority(db, projectId);
+  if (authority !== "database") {
+    throw new ApprovalError("approval_requires_database_authority", `project authority is ${authority ?? "unregistered"}; approvals require database authority`);
+  }
+}
+
+function proposalFromRow(row: any): ProposalRecord {
+  return {
+    id: row.id, projectId: row.project_id, feature: row.feature, kind: row.kind, subjectKey: row.subject_key,
+    payload: JSON.parse(row.payload_json), pins: JSON.parse(row.pins_json), stateRevision: row.state_revision,
+    status: row.status, createdAt: row.created_at, resolvedAt: row.resolved_at ?? null,
+  };
+}
+
+function approvalFromRow(row: any): ApprovalRecord {
+  return {
+    id: row.id, proposalId: row.proposal_id, projectId: row.project_id, feature: row.feature, kind: row.kind,
+    subjectKey: row.subject_key, pins: JSON.parse(row.pins_json), decision: JSON.parse(row.decision_json),
+    approvedVia: row.approved_via, approvedAt: row.approved_at, supersededAt: row.superseded_at ?? null,
+  };
+}
+
+function validateProposeInput(input: ProposeInput): void {
+  if (!isKind(input.kind)) throw new ApprovalError("invalid_proposal", `unknown approval kind: ${String(input.kind)}`);
+  if (!input.feature || /[/\\\x00-\x1f\x7f]/.test(input.feature)) throw new ApprovalError("invalid_proposal", "feature must be a plain feature name");
+  if (!isRecord(input.payload)) throw new ApprovalError("invalid_proposal", "payload must be an object");
+  if (!isRecord(input.pins)) throw new ApprovalError("invalid_proposal", "pins must be an object");
+  if (!Number.isInteger(input.stateRevision) || input.stateRevision < 0) throw new ApprovalError("invalid_proposal", "state_revision must be a non-negative integer");
+  const shapeErrors = validatePinsShape(input.kind, input.subjectKey, input.pins);
+  if (shapeErrors.length) throw new ApprovalError("invalid_proposal", shapeErrors.join("; "));
+}
+
+/** Must run inside a write transaction; expires older open proposals for the subject, then inserts. */
+function insertProposal(db: Database, input: ProposeInput, timestamp: string): { proposalId: string; expiredIds: string[] } {
+  assertDatabaseAuthority(db, input.projectId);
+  const proposalId = randomUUID();
+  const open = db.query(`SELECT id FROM approval_proposals
+    WHERE project_id=? AND feature=? AND kind=? AND subject_key=? AND status='proposed'`).all(input.projectId, input.feature, input.kind, input.subjectKey) as Array<{ id: string }>;
+  for (const item of open) {
+    db.query("UPDATE approval_proposals SET status='expired',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, item.id);
+  }
+  db.query(`INSERT INTO approval_proposals(id,project_id,feature,kind,subject_key,payload_json,pins_json,state_revision,status,created_at,resolved_at)
+    VALUES (?,?,?,?,?,?,?,?,'proposed',?,NULL)`).run(
+    proposalId, input.projectId, input.feature, input.kind, input.subjectKey,
+    canonicalPinsJson(input.payload), canonicalPinsJson(input.pins), input.stateRevision, timestamp,
+  );
+  return { proposalId, expiredIds: open.map(item => item.id) };
+}
+
+/**
+ * Records a proposal with the pins observed at proposal time. An older open
+ * proposal for the same feature/kind/subject is expired so only the newest
+ * proposal can be confirmed.
+ */
+export function proposeApproval(db: Database, input: ProposeInput, options: { now?: Date } = {}): { proposalId: string; expiredIds: string[] } {
+  validateProposeInput(input);
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.transaction(() => insertProposal(db, input, timestamp)).immediate();
+}
+
+/**
+ * All-or-nothing batch propose: every item is validated first, then all inserts and
+ * "expire older open proposal for the same subject" updates run in ONE immediate
+ * transaction that rolls back completely on any error.
+ */
+export function proposeApprovals(db: Database, inputs: ProposeInput[], options: { now?: Date } = {}): Array<{ proposalId: string; expiredIds: string[] }> {
+  if (!Array.isArray(inputs) || inputs.length === 0) throw new ApprovalError("invalid_proposal", "at least one proposal is required");
+  for (const input of inputs) validateProposeInput(input);
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.transaction(() => inputs.map(input => insertProposal(db, input, timestamp))).immediate();
+}
+
+export function getProposal(db: Database, projectId: string, proposalId: string): ProposalRecord | null {
+  const row = db.query("SELECT * FROM approval_proposals WHERE id=? AND project_id=?").get(proposalId, projectId);
+  return row ? proposalFromRow(row) : null;
+}
+
+export function listProposals(db: Database, projectId: string, filter: { feature?: string; status?: ProposalStatus; kind?: ApprovalKind } = {}): ProposalRecord[] {
+  const clauses = ["project_id=?"]; const params: Array<string> = [projectId];
+  if (filter.feature) { clauses.push("feature=?"); params.push(filter.feature); }
+  if (filter.status) { clauses.push("status=?"); params.push(filter.status); }
+  if (filter.kind) { clauses.push("kind=?"); params.push(filter.kind); }
+  return (db.query(`SELECT * FROM approval_proposals WHERE ${clauses.join(" AND ")} ORDER BY created_at, id`).all(...params) as any[]).map(proposalFromRow);
+}
+
+export function listApprovals(db: Database, projectId: string, filter: { feature?: string; kind?: ApprovalKind; includeSuperseded?: boolean } = {}): ApprovalRecord[] {
+  const clauses = ["project_id=?"]; const params: Array<string> = [projectId];
+  if (filter.feature) { clauses.push("feature=?"); params.push(filter.feature); }
+  if (filter.kind) { clauses.push("kind=?"); params.push(filter.kind); }
+  if (!filter.includeSuperseded) clauses.push("superseded_at IS NULL");
+  // approved_at has millisecond precision, so confirmations in one transaction
+  // window can tie. rowid preserves the actual append order; UUID ordering does not.
+  return (db.query(`SELECT * FROM approvals WHERE ${clauses.join(" AND ")} ORDER BY approved_at, rowid`).all(...params) as any[]).map(approvalFromRow);
+}
+
+/** The user declined the proposal in the UI; it can never be confirmed afterwards. */
+export function rejectProposal(db: Database, projectId: string, proposalId: string, options: { now?: Date } = {}): boolean {
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.query("UPDATE approval_proposals SET status='rejected',resolved_at=? WHERE id=? AND project_id=? AND status='proposed'")
+    .run(timestamp, proposalId, projectId).changes === 1;
+}
+
+export function proposalIsExpired(proposal: Pick<ProposalRecord, "createdAt">, now = new Date()): boolean {
+  const created = Date.parse(proposal.createdAt);
+  return !Number.isFinite(created) || now.getTime() - created > PROPOSAL_TTL_MS;
+}
+
+/**
+ * Confirms one proposal in a single IMMEDIATE transaction: re-checks database
+ * authority, proposal state and TTL, recomputes the pins (CAS), inserts the
+ * approval, consumes the proposal and supersedes the previous approval for the
+ * same feature/kind/subject. Stale or expired proposals are marked expired and
+ * the call fails; nothing else is written in that case.
+ */
+export function confirmApproval(db: Database, input: ConfirmInput): ConfirmResult {
+  const now = input.now ?? new Date();
+  const timestamp = now.toISOString();
+  const expire = (proposalId: string) => {
+    db.query("UPDATE approval_proposals SET status='expired',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, proposalId);
+  };
+  const transaction = db.transaction((): ConfirmResult => {
+    const authority = databaseAuthority(db, input.projectId);
+    if (authority !== "database") {
+      return { ok: false, code: "approval_requires_database_authority", message: `project authority is ${authority ?? "unregistered"}` };
+    }
+    const row = db.query("SELECT * FROM approval_proposals WHERE id=? AND project_id=?").get(input.proposalId, input.projectId);
+    if (!row) return { ok: false, code: "proposal_not_found", message: `unknown proposal: ${input.proposalId}` };
+    const proposal = proposalFromRow(row);
+    if (proposal.status !== "proposed") return { ok: false, code: "proposal_not_pending", message: `proposal is ${proposal.status}` };
+    if (proposalIsExpired(proposal, now)) {
+      expire(proposal.id);
+      return { ok: false, code: "proposal_expired", message: "proposal is older than the confirmation window; propose again" };
+    }
+    const decisionErrors = isRecord(input.decision) ? validateDecision(proposal.kind, input.decision, proposal.pins) : ["decision must be an object"];
+    if (decisionErrors.length) return { ok: false, code: "invalid_decision", message: decisionErrors.join("; ") };
+    let current: CurrentPins;
+    try {
+      current = input.recompute(proposal);
+    } catch (error) {
+      return { ok: false, code: "pins_unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!current || !isRecord(current.pins) || canonicalPinsJson(current.pins) !== canonicalPinsJson(proposal.pins)) {
+      expire(proposal.id);
+      return { ok: false, code: "pins_mismatch", message: "suite, TC, binding, DSL, profile or evidence changed since the proposal; propose again" };
+    }
+    if (current.stateRevision !== proposal.stateRevision) {
+      expire(proposal.id);
+      return { ok: false, code: "state_revision_mismatch", message: `workflow state revision changed from ${proposal.stateRevision} to ${current.stateRevision}; propose again` };
+    }
+    const superseded = db.query(`SELECT id FROM approvals
+      WHERE project_id=? AND feature=? AND kind=? AND subject_key=? AND superseded_at IS NULL`).all(proposal.projectId, proposal.feature, proposal.kind, proposal.subjectKey) as Array<{ id: string }>;
+    for (const item of superseded) {
+      db.query("UPDATE approvals SET superseded_at=? WHERE id=? AND superseded_at IS NULL").run(timestamp, item.id);
+    }
+    const approvalId = randomUUID();
+    db.query(`INSERT INTO approvals(id,proposal_id,project_id,feature,kind,subject_key,pins_json,decision_json,approved_via,approved_at,superseded_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,NULL)`).run(
+      approvalId, proposal.id, proposal.projectId, proposal.feature, proposal.kind, proposal.subjectKey,
+      canonicalPinsJson(proposal.pins), canonicalPinsJson(input.decision), APPROVED_VIA, timestamp,
+    );
+    const consumed = db.query("UPDATE approval_proposals SET status='consumed',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, proposal.id);
+    if (consumed.changes !== 1) throw new ApprovalError("proposal_not_pending", "proposal was consumed concurrently");
+    return { ok: true, approvalId, supersededIds: superseded.map(item => item.id) };
+  });
+  try {
+    return transaction.immediate();
+  } catch (error) {
+    if (error instanceof ApprovalError) return { ok: false, code: error.code, message: error.message };
+    throw error;
+  }
+}