audit-task-status
Reconciles Forge Flow task and epic files with the task registry (docs/tasks/registry.json, the single source of truth): fixes status drift in task-file frontmatter and epic files, and surfaces registry tasks with no body file on disk. Use when task or epic statuses look out of sync with the registry ("the epic file is stale", "are the statuses in sync"), after a batch of merges or completions, or as a pre-release consistency check.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- audit-task-status
- description
- Reconciles Forge Flow task and epic files with the task registry (docs/tasks/registry.json, the single source of truth): fixes status drift in task-file frontmatter and epic files, and surfaces registry tasks with no body file on disk. Use when task or epic statuses look out of sync with the registry ("the epic file is stale", "are the statuses in sync"), after a batch of merges or completions, or as a pre-release consistency check.
02 资源文件 3
- 参考文档evals/evals.json1.5 KB
- 脚本scripts/audit_status.py24.8 KB
- 参考文档WHY.md1.1 KB
03 SKILL.md 正文
Audit & align task status
Makes task-file frontmatter and epic files tell the same truth as docs/tasks/registry.json, and reports registry-health gaps (tasks with no body file). The forge CLI is the only sanctioned writer of the registry; never hand-edit it.
Index
| File or section | Read when… |
|---|---|
WHY.md |
Explaining to the user why epic files drifted, or deciding which of the three layers to trust |
| The authority rule (below) | Before any edit — which layer wins |
| Workflow (below) | Every invocation — steps 1–5 |
scripts/audit_status.py |
Run it (step 2 and step 5) — read-only detector |
| What "aligned" means (below) | Deciding you are done |
The authority rule
The registry is ground truth. Always reconcile the other layers TO it, never the
reverse. If a task file or epic file disagrees with the registry, the registry
wins — fix the doc. The only exception is if the registry itself looks wrong (a
status that contradicts a merged PR); in that case stop and surface it to the user,
because changing the registry means a forge task state transition, not a doc edit.
Workflow
1. Sync the machine layer (registry ↔ task-file frontmatter)
Run the consistency hook with --fix — it auto-corrects trivial registry/task-file
drift and reports anything it can't fix:
python3 .claude/hooks/forge/consistency-banner.py --fix --json
rc=0 with no findings means layers 1↔2 agree. If it reports blocking drift it
can't auto-fix, resolve that first (it usually means a task file was hand-edited to
a status the registry disagrees with — fix the file to match the registry).
Do not trust rc=0 alone as proof of full alignment — this hook only checks
registry↔task-file. It is blind to epic files. The next steps are where the value is.
2. Independently verify task-file frontmatter (don't just trust the hook)
The hook is informational and has been wrong before. Confirm independently — for
every registry task, the body file's status: frontmatter must equal the registry
status. Use the bundled script:
python3 .claude/skills/audit-task-status/scripts/audit_status.py
It reads the registry, locates each task's body file, and reports three things:
- task-file status mismatches (frontmatter
status:≠ registry status), - epic-file drift (see step 3),
- registry tasks with no body file on disk.
Read its output before editing anything — it tells you the exact scope.
3. Reconcile epic files (the layer the framework forgets)
For each epic with open or recently-changed work, the epic file (<epic>/<epic>.md)
has up to four things that drift — the bundled script reports the first three; you
verify and fix:
- The progress counter — a prose line like
**Tasks:** N total — M completed, …. Recompute from the registry and rewrite it. Refresh any "as of <date>" stamp. - The per-task status — in TWO idioms, depending on the epic:
- Pipe tables:
| T### | … | <status> | … |. Column position varies between epics (some add columns beforeStatus), so locate theStatusheader rather than counting columns. Cells may carry annotations after the status (completed (PR #N),closed — phantom). Fix any cell whose leading status token disagrees with the registry. - Checklists:
- [x] T###: … ✅/- [~] T###a: … superseded. The checkbox alone is ambiguous, so the script only flags a row when an explicit status word in the line contradicts the registry. Verify these by hand — a[x]next to a task the registry callssupersededis real drift; a[x]that's merely annotated(commit pending)while the registry sayscompletedis cosmetic, not a status mismatch.
- Pipe tables:
- The prose
**Status:**header (and the epic'sstatus:frontmatter). An epic whose every task is terminal (completed/superseded/closed) but whose prose header still saysin_progress/pendingis contradicting itself — fix the header to match the rollup. (This is distinct from the counter; an epic can have a right counter and a stale header, or vice-versa.)
Watch for internal contradictions — a counter saying "1 ready" while the table
row for the same task says completed, or a **Status:** in_progress header on an
all-terminal epic. Make every layer (header, counter, rows) AND the registry agree.
Scope discipline — do NOT backfill missing table rows by default. Epic files routinely list only a subset of their tasks (the headline ones); the registry holds the complete per-task detail. Many Forge epic files explicitly say "registry is authoritative — counts drift as tasks are added". Adding a row for every registry task is a large rewrite that fights the file's design. Fix the counters and the statuses of rows that already exist; only backfill individual rows if the user explicitly asks. When you skip a backfill, say so plainly (e.g. "counter now reflects all N tasks; 35 of them don't have individual table rows, by design").
4. Report the registry-health extras
Beyond status, surface (don't fix unless asked):
- Tasks with no body file — registry entries created with
--no-file, or whose body was later deleted/moved. The script lists them. These aren't a status problem, but they break resume/lock for those tasks. Offer the fix rather than doing it silently:python3 .claude/scripts/forge/forge.py task reconcile-files(dry-run) →--applyto create stub bodies.
5. Verify and commit
Re-run the audit script — every layer should now report 0 mismatches. Re-run
the consistency hook (rc=0) to confirm your epic-file edits didn't disturb the
machine layer (they shouldn't — you only touched epic prose). Then commit the epic
files (and any task files the hook fixed) together:
docs(epics): align <epics> statuses with registry
Spell out in the commit what drifted and what you deliberately left (e.g. "fixed counters + N stale rows + the T### contradiction; did NOT backfill the M missing rows — epic defers per-task detail to the registry").
What "aligned" means (the done condition)
- Registry ↔ task-file frontmatter: 0 status mismatches.
- Every epic-file counter matches the registry's completed/total for that epic.
- Every epic-file row that exists (table OR checklist) matches the registry status.
- Every epic's prose
**Status:**header agrees with its task rollup. - No internal contradictions within an epic file (header vs counter vs rows).
- Registry-tasks-without-body-files reported (and fixed only if the user opted in).
Verify the script's findings — it is a first pass, not an oracle
The bundled audit_status.py is a fast detector, but it resolves body files by the
registry file field with a glob fallback, and parses heterogeneous human prose —
so it can mis-report at the edges. Treat its output as candidates to confirm, not
gospel. Two false-positive classes it has produced before (now guarded, but stay
alert): a T###-*.md file outside a /tasks/-or-/orphan/ dir (e.g. a
docs/debug/ triage note) shadowing the real body file; and a cosmetic annotation
([x] … (commit pending)) read as a status. Before you edit anything, spot-check
each flagged item against the registry and the actual file line — the same
empirical-premise discipline any audit finding deserves.
Notes
- This is a deterministic audit, not a judgment call — the registry decides every status. The only place judgment enters is the scope of epic-file backfill (step 3) and whether to create missing body files (step 4); both default to "ask, don't silently expand scope".
- The bundled
scripts/audit_status.pydoes the read-only detection; the fixes are small targeted edits you apply by hand (epic prose is human-authored — an Edit-per-fix keeps the change reviewable). Don't try to regex-rewrite whole tables.
Project-specific overrides: if SKILL.local.md exists in this directory, read it — it is consumer-owned, survives framework refresh, and wins on conflict. A sidecar that relaxes a gate defined above must state how to prove the gate is wrong in that case. Doctrine: rules/framework-vs-project-root.md.
04 同仓库更多 Skills
wizard
Generates an interactive bash wizard that walks a human through steps only they can perform — opens each URL, says what to click and copy, captures values (hidden entry for secrets), writes .env and GitHub secrets, confirms before irreversible actions. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
vet-idea
Vets an idea, decision, or plan BEFORE it is built. Runs a single model through five fixed adversarial advisor roles, a peer-review pass, and a chairman synthesis that emits a halt-capable GO / NO-GO / RECONSIDER verdict. Advisory and non-mutating — outputs a report, never writes task state. Use when an idea, feature, or costly hard-to-reverse decision is of uncertain worth and the question is whether to build it at all. NOT FOR settled work (bug fixes, approved features) or for shaping how to build it (the ISA Interview workflow).
triage-incident
Production incident triage — from "something is broken for users" to fixed, verified, and learned-from. Pulls the error signal (Sentry/logs/user report), reproduces before touching code, routes the fix through /fix-bug's prod fast path, and closes with a postmortem entry. Use when something is broken for users in production — an outage, data corruption, a Sentry spike, or a crash-rate alert. NOT FOR bugs found in development (use /fix-bug directly) or CI failures (use /diagnose-ci).
setup-review-bot
Configures a repo's AI code reviewers — the post-PR mention bot and the pre-push local reviewer — and writes the AGENTS.md the reviewers read. Interviews the user for what the reviewer should weight, then sets git config forge.reviewBot / forge.localReview and populates AGENTS.md at the project root. Use when a repo has no reviewer configured, when review findings are consistently off-target, or when onboarding a new project.
security-review
Portable security review for a feature, endpoint, or change before it ships. Orchestrates the existing OWASP review (@security-boss) and secrets scan (security_secrets validator), then adds the pass they miss — an explicit business-logic-flaw walkthrough (IDOR, race/TOCTOU, state-machine bypass, privilege escalation, price/quantity tampering). Advisory and non-mutating — produces a findings report; real findings are filed as tasks. Use when a change touching money, access control, or multi-step state is about to ship, or when the auth looks fine but the flow could be abused. NOT FOR SAST or dependency-CVE scanning (consumer CI owns those).
run-epic
Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".