flatnotes-tasksmd-github-audit

彻底审核 Tasks.md + Flatnotes 的偏差和准确性；使用 GitHub (gh CLI) 作为事实来源来检测过时的笔记/卡片和丢失的链接。生成报告和可选的修复计划。

# Flatnotes + Tasks.md + GitHub Audit

Use this skill when Brandon asks to **audit** the Flatnotes/Tasks.md system for accuracy and ensure it’s **up to date**, using **GitHub as the source of truth**.

## Quick start
Run the bundled auditor (report-only):

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

Outputs:
- Markdown report: `tmp/flatnotes-tasksmd-audit.md`
- JSON report: `tmp/flatnotes-tasksmd-audit.json`

> If `gh` is not authenticated, the audit still runs but GitHub checks will be marked as `SKIPPED_GITHUB`.

---

## Data sources (defaults)
- Tasks.md root: `/home/ds/.config/appdata/tasksmd/tasks`
- Flatnotes root: `/home/ds/.config/appdata/flatnotes/data`
- Flatnotes “system notes” mirror in workspace: `notes/resources/flatnotes-system/`

Override via env vars:
- `TASKS_ROOT`
- `FLATNOTES_ROOT`

---

## Audit goals (what “accurate” means)

### A) Board hygiene (Tasks.md)
- Global lanes exist: `00 Inbox`, `05 Backlog`, `10 Next`, `20 Doing`, `30 Blocked`, `40 Waiting`, `90 Done`.
- **Lane rule preference:** `prio-p2` lives in `05 Backlog` by default (no `prio-p2` in `10 Next`).
- Doing WIP ≤ 3 (preference).
- Cards should be consistently formatted (Outcome/Steps) and tagged (proj/prio/eff/type).
- Blocked cards include `Unblock:`.
- Project cards include a Flatnotes pointer (`Flatnotes: ...`).

### B) Project completeness (Flatnotes)
For each active project in `SYS Workspace - Project Registry`:
- Required project notes exist:
  - `PJT <slug> - 00 Overview`
  - `PJT <slug> - 10 Research`
  - `PJT <slug> - 20 Plan`
  - `PJT <slug> - 90 Log`
- Hub note has:
  - Current status (1–3 bullets)
  - Links section with repo + Tasks filter
  - Decisions section linking relevant ADR(s)

### C) GitHub truth reconciliation (GitHub = source of truth)
For each project repo in the registry:
- Open PRs should have a corresponding Tasks card (Doing/Next/Blocked/Waiting) OR an explicit reason why not.
- Recently merged PRs should be reflected somewhere:
  - preferably a short note in the project log (`PJT <slug> - 90 Log`) + hub status update, or
  - a Done card with PR link.
  - (Audit treats either as reconciled; it may warn if a merged PR is only on a Done card but missing from the log.)
- Done cards should ideally include a PR link when work was shipped via PR.

---

## Workflow (recommended)
1) **Parse registry**
   - Read `SYS Workspace - Project Registry` from Flatnotes.
   - Extract: slug, status, Tasks tag, GitHub repo URL.

2) **Scan Tasks.md**
   - Index cards by lane and by `proj-*` tag.
   - Flag lane rule violations (`prio-p2` in Next, etc.).
   - Flag cards missing Flatnotes pointer.

3) **Scan Flatnotes**
   - Check required project notes exist.
   - Check hub Decisions section links ADR notes.

4) **GitHub cross-check**
   - Use `gh`:
     - `gh pr list --state open --json ...`
     - `gh pr list --state merged --search "merged:>=<date>" --json ...` (or equivalent)
   - Try to match PRs ↔ Tasks cards using:
     - PR URL in card content
     - PR number
     - Title substring heuristic

5) **Report**
   - Output: summary + per-project drift list + fix plan.

---

## Applying fixes (guardrails)
Default is **report-only**.

If Brandon explicitly asks to apply fixes:
- Safe auto-fixes allowed:
  - create missing Flatnotes notes (`10 Research`, etc.) using existing templates
  - add missing ADR links to hub Decisions section
  - move `prio-p2` from Next → Backlog
  - add missing Flatnotes pointers to Tasks cards
- Anything that renames files or deletes content: ask first.

---

## Bundled code
- `scripts/audit.mjs` — generates the report (Markdown + JSON). If needed, patch it rather than rewriting.

---

## 中文说明

# Flatnotes + Tasks.md + GitHub 审核

当 Brandon 要求**审核** Flatnotes/Tasks.md 系统的准确性，并以 **GitHub 作为事实来源**确保其**保持最新**时，使用本技能。

## 快速开始
运行内置的审核工具（仅生成报告）：

```bash
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 “system notes” 镜像：`notes/resources/flatnotes-system/`

通过环境变量覆盖：
- `TASKS_ROOT`
- `FLATNOTES_ROOT`

---

## 审核目标（“准确”的含义）

### A) 看板规范（Tasks.md）
- 存在全局泳道：`00 Inbox`、`05 Backlog`、`10 Next`、`20 Doing`、`30 Blocked`、`40 Waiting`、`90 Done`。
- **泳道规则偏好：** `prio-p2` 默认归属 `05 Backlog`（`10 Next` 中不应有 `prio-p2`）。
- Doing 在制品数 ≤ 3（偏好）。
- 卡片格式应一致（Outcome/Steps）并打好标签（proj/prio/eff/type）。
- Blocked 卡片包含 `Unblock:`。
- 项目卡片包含 Flatnotes 指针（`Flatnotes: ...`）。

### B) 项目完整性（Flatnotes）
对于 `SYS Workspace - Project Registry` 中每个活跃项目：
- 存在必需的项目笔记：
  - `PJT <slug> - 00 Overview`
  - `PJT <slug> - 10 Research`
  - `PJT <slug> - 20 Plan`
  - `PJT <slug> - 90 Log`
- 中心笔记包含：
  - 当前状态（1–3 个要点）
  - 链接区，含 repo + Tasks 过滤器
  - 决策区，链接相关的 ADR

### C) GitHub 事实对账（GitHub = 事实来源）
对于注册表中每个项目 repo：
- 打开的 PR 应有对应的 Tasks 卡片（Doing/Next/Blocked/Waiting），或有明确的不需要的理由。
- 近期合并的 PR 应在某处有所体现：
  - 最好是在项目日志（`PJT <slug> - 90 Log`）中有简短记录 + 中心状态更新，或
  - 一张带 PR 链接的 Done 卡片。
  - （审核将两者均视为已对账；如果合并的 PR 仅存在于 Done 卡片但日志中缺失，可能会发出警告。）
- 当工作通过 PR 交付时，Done 卡片最好包含 PR 链接。

---

## 工作流程（推荐）
1) **解析注册表**
   - 从 Flatnotes 读取 `SYS Workspace - Project Registry`。
   - 提取：slug、状态、Tasks 标签、GitHub repo URL。

2) **扫描 Tasks.md**
   - 按泳道和 `proj-*` 标签为卡片建立索引。
   - 标记泳道规则违规（`prio-p2` 出现在 Next 中等）。
   - 标记缺失 Flatnotes 指针的卡片。

3) **扫描 Flatnotes**
   - 检查必需的项目笔记是否存在。
   - 检查中心笔记的决策区是否链接了 ADR 笔记。

4) **GitHub 交叉核对**
   - 使用 `gh`：
     - `gh pr list --state open --json ...`
     - `gh pr list --state merged --search "merged:>=<date>" --json ...`（或等效命令）
   - 尝试通过以下方式匹配 PR ↔ Tasks 卡片：
     - 卡片内容中的 PR URL
     - PR 编号
     - 标题子串启发式匹配

5) **报告**
   - 输出：摘要 + 各项目偏差列表 + 修复计划。

---

## 应用修复（防护栏）
默认为**仅生成报告**。

如果 Brandon 明确要求应用修复：
- 允许的安全自动修复：
  - 使用现有模板创建缺失的 Flatnotes 笔记（`10 Research` 等）
  - 向中心笔记的决策区添加缺失的 ADR 链接
  - 将 `prio-p2` 从 Next → Backlog 移动
  - 向 Tasks 卡片添加缺失的 Flatnotes 指针
- 任何重命名文件或删除内容的操作：先询问。

---

## 内置代码
- `scripts/audit.mjs` — 生成报告（Markdown + JSON）。如有需要，对其打补丁而非重写。