harden sm-flow protocol and archive v4.0 validation runs

- Rewrite hard constraint #1: apply must read Committed OpenSpec files as the execution source of truth - Promote sub-skill invocation to hard constraint #6; remove fallbacks.md and all degradation paths - Add file existence verification at commit and archive exit gates - Require grill question pool, evidence-driven conclusions, and user-interview confirmations to be written to decisions.md - Record v4.0 validation retrospective in workflow.md: propose overreach, sub-skill pseudo-calling, spec omitting user behavior - Archive knowledge-index-sort OpenSpec and devflow entries from prior run
2026-05-26 09:59:24 +08:00
parent 71e0b7f801
commit 63994b6440
11 changed files with 342 additions and 143 deletions
@@ -0,0 +1,52 @@
+# knowledge-index-sort Acceptance
+
+## 结果
+
+已接受。
+
+## 验证
+
+### 静态验证
+
+- 检查项：knowledge-index.html 和 scripts/update-knowledge-index.sh 内容一致性
+- 结果：passed
+- 备注：两个文件的排序 UI、排序逻辑、事件绑定、清空筛选重置逻辑完全一致
+
+### 脚本验证
+
+- 命令：未运行（纯前端静态页面，无测试框架）
+- 结果：not run
+- 备注：不适用
+
+### 浏览器/人工验证
+
+- 步骤：
+  1. 打开 knowledge-index.html
+  2. 切换排序下拉框的 4 种模式，验证条目顺序
+  3. 组合排序与标签筛选/搜索/年份筛选
+  4. 点击"清空筛选"验证排序重置
+- 结果：passed
+- 备注：用户确认验证通过
+
+## 已完成范围
+
+- 排序下拉框 UI（4 种模式：日期新→旧、旧→新、标签多→少、少→多）
+- applyFilters() 中排序逻辑（过滤后、渲染前）
+- bindSortSelect() 事件绑定
+- clearFilters() 重置排序为默认值
+- scripts/update-knowledge-index.sh 同步修改
+- OpenSpec 产物（proposal/design/specs/tasks）
+
+## 已知限制
+
+- 排序状态不持久化，刷新页面后恢复默认（date-desc）
+- 不做多列排序
+
+## Bug 修复和诊断
+
+- 无
+
+## 交接
+
+- 下一步：可选归档 OpenSpec change，功能已完整可用
+- OpenSpec 归档确认：待询问
@@ -0,0 +1,30 @@
+# knowledge-index-sort Brief
+
+## 背景
+
+- 用户目标：给 knowledge-index-panel 添加排序功能，支持按日期和标签数量排序
+- 当前问题：条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看
+- 关联 OpenSpec：`openspec/changes/knowledge-index-sort/`
+- devflow 分档：micro
+
+## 范围
+
+- 本次要做：在 filter-row 中添加排序下拉框，支持 4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
+- 本次不做：多列排序、拖拽排序、修改 ENTRIES 数据结构、分页
+- 影响区域：`knowledge-index.html`、`scripts/update-knowledge-index.sh`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## 关键决策
+
+- "按标签排序"指按标签数量排序（用户确认）
+- 排序在 applyFilters() 中执行，位于过滤之后、渲染之前
+- 排序与搜索、标签筛选、年份筛选取交集，即时响应
+
+## 执行偏差
+
+apply 阶段先实现了代码，后补写 OpenSpec 产物。已在 decisions.md 中记录并分析根因。此偏差推动了 sm-flow 协议本身的改进（commit gate 文件存在性检查、grill 退出条件 decisions.md 强制写入、archive 退出条件文件验证）。
@@ -0,0 +1,42 @@
+# knowledge-index-sort Decisions
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | "按标签排序"具体指什么？按第一个标签字母序？按标签数量？ | user-interview | 已解决 |
+| Q2 | 边界 | 排序是否只影响当前过滤后的可见条目（不影响过滤逻辑本身）？ | evidence-driven | 已解决 |
+| Q3 | 验收 | 排序变化后，页面应如何响应？即时重排还是需要点击"应用"？ | evidence-driven | 已解决 |
+
+## User-interview
+
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
+|---|---|---|---|
+| "按标签排序"具体指什么？ | "按数量" | 已确认 | 已回写 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| 排序只作用于过滤后的结果 | knowledge-index.html applyFilters() 代码 | 已汇报 |
+| 排序应即时响应（change 事件） | 与 year-filter/标签/搜索控件行为一致 | 已汇报 |
+
+## 关键取舍
+
+- 决策：排序位置放在 applyFilters() 中，过滤之后、渲染之前
+  - 原因：排序只影响可见条目，不影响过滤逻辑
+  - 影响：renderEntries 保持纯渲染职责
+  - 风险接受：当前接受
+
+- 决策：4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
+  - 原因：覆盖最常见排序需求
+  - 影响：UI 简洁，不需要复杂的多列排序
+  - 风险接受：当前接受
+
+## 执行偏差记录
+
+- 偏差：apply 阶段先实现了代码，后补写 OpenSpec 产物（proposal/design/specs/tasks）
+  - 分类：实现偏差（违反 sm-flow 协议——specify 阶段应先产出完整 OpenSpec）
+  - 原因：micro 模式下跳过了 specify 阶段的文件产出，直接进入 apply
+  - 修正：补写所有 OpenSpec 产物到 openspec/changes/knowledge-index-sort/
+  - 教训：即使是 micro 模式，OpenSpec 产物也不能跳过——这是 apply 的执行依据