Flatnotes + Tasks.md + GitHub 审计

当 Brandon 要求对 Flatnotes/Tasks.md 系统进行 审计，以确保其 准确性 和 时效性，并以 GitHub 作为事实来源（source of truth） 时，请使用本技能。

快速开始

运行内置的审计器（仅生成报告）：

node skills/flatnotes-tasksmd-github-audit/scripts/audit.mjs --since-days 30 --write

输出内容：

• Markdown 报告：tmp/flatnotes-tasksmd-audit.md
• JSON 报告：tmp/flatnotes-tasksmd-audit.json

若 gh 命令未完成身份验证，审计仍会执行，但所有 GitHub 检查项将被标记为 SKIPPED_GITHUB。

数据源（默认路径）

• Tasks.md 根目录：/home/ds/.config/appdata/tasksmd/tasks
• Flatnotes 根目录：/home/ds/.config/appdata/flatnotes/data
• Flatnotes “系统笔记” 在 workspace 中的镜像路径：notes/resources/flatnotes-system/

可通过环境变量覆盖默认路径：

• TASKS_ROOT
• FLATNOTES_ROOT

审计目标（“准确”的定义）

A) 看板规范性（Tasks.md）

• 全局看板列（lane）必须存在：00 Inbox、05 Backlog、10 Next、20 Doing、30 Blocked、40 Waiting、90 Done。
• 列规则优先级：prio-p2 默认应位于 05 Backlog 中（即不应出现在 10 Next 中）。
• Doing 列的在制品（WIP）数量 ≤ 3（建议值）。
• 卡片格式需保持一致（Outcome/Steps 结构），且须打上标准标签（proj/prio/eff/type）。
• Blocked 卡片中需包含 Unblock: 字段。
• 项目类卡片需包含 Flatnotes 指针（Flatnotes: ...）。

B) 项目完整性（Flatnotes）

针对 SYS Workspace - Project Registry 中每个处于活跃状态的项目：

• 必需的项目笔记必须存在：
  • PJT - 00 Overview
  • PJT - 10 Research
  • PJT - 20 Plan
  • PJT - 90 Log
• 项目中心笔记（hub note）需包含：
  • 当前状态（1–3 条要点）
  • 链接区（含对应 repo 地址 + Tasks 过滤器链接）
  • 决策区（Decision section），其中需链接相关 ADR 笔记

C) GitHub 事实一致性校验（GitHub = source of truth）

针对注册表中每个项目仓库：

• 所有打开中的 PR 应有对应的 Tasks 卡片（位于 Doing / Next / Blocked / Waiting 列），或明确说明无需对应卡片的原因。
• 近期已合并的 PR 应在某处体现：
  • 首选方式：在项目日志（PJT - 90 Log）中添加简短记录，并同步更新 hub 的状态；或
  • 创建一张 Done 卡片，并附上该 PR 链接。
  • （审计将上述任一方式视为已达成一致性；但若某已合并 PR 仅出现在 Done 卡片中而未见于日志，审计可能发出警告。）
• 当工作通过 PR 发布时，Done 卡片理想情况下应包含该 PR 链接。

推荐工作流

1. 解析注册表

   • 从 Flatnotes 中读取 SYS Workspace - Project Registry。
   • 提取字段：slug、status、Tasks tag、GitHub repo URL。

2. 扫描 Tasks.md

   • 按列（lane）及 proj-* 标签对卡片建立索引。
   • 标记违反列规则的情形（例如 prio-p2 出现在 Next 列等）。
   • 标记缺失 Flatnotes 指针的卡片。

3. 扫描 Flatnotes

   • 检查各项目所需的笔记是否均已存在。
   • 检查项目中心笔记（hub note）的 Decisions 区域是否正确链接了相关 ADR 笔记。

4. GitHub 交叉核对

   • 调用 gh CLI：
     • gh pr list --state open --json ...
     • gh pr list --state merged --search "merged:>=" --json ...（或等效命令）
   • 尝试通过以下方式匹配 PR ↔ Tasks 卡片：
     • 卡片正文中是否包含 PR URL
     • PR 编号是否匹配
     • 标题子串启发式匹配

5. 生成报告

   • 输出内容：摘要 + 各项目偏差清单 + 修复方案。

应用修复（安全守则）

默认模式为 仅报告（report-only）。

仅当 Brandon 明确要求执行修复操作时，方可启用自动修复：

• 允许的安全自动修复包括：
  • 基于现有模板，创建缺失的 Flatnotes 笔记（如 10 Research 等）
  • 向 hub 的 Decisions 区域补充缺失的 ADR 链接
  • 将 prio-p2 卡片从 Next 列移至 Backlog 列
  • 为 Tasks 卡片补全缺失的 Flatnotes 指针
• 任何涉及重命名文件或删除内容的操作：必须先征得确认。

内置代码

• scripts/audit.mjs —— 生成 Markdown 与 JSON 报告。如需调整行为，建议直接打补丁（patch），而非重写。