← Back to Git & GitHub
Git & GitHub by @branexp

flatnotes-tasksmd-github-audit

Thoroughly audit Tasks.md +

0
Source Code

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):

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.