[calvin-archastro]

Review on ArchCode

Problem and author intent

Users accumulate paused, blocked and failed Tasks (one sample: 36 paused Tasks for one user, 21 with inbox questions, 15 with reasons only in metadata.pause). The tasks skill's §7 has audit guidance, but nothing runs it end to end for my Tasks or explains the reasons in words a person can act on. Raw kinds like needs_access/host_environment and [factory:pause kind=…] comments are the only explanation today.

Intent: a tasks-audit skill a user can invoke ("audit my tasks", /tasks-audit) that finds their stuck Tasks, explains each one plainly, and walks them through approved fixes.

What changed

• tasks-audit/SKILL.md — workflow: connect → resolve assignee usr_… ID (the CLI has no "me" for --owner-user) → inventory (paused/failed/stalled lists, tasks blocked filtered by owner and is_blocked, metadata.pause, joined with the org-wide tasks inbox) → read-only investigation, one subagent per epic with a fixed brief and JSON findings schema (Workflow tool in Claude Code, parallel agents elsewhere, sequential fallback) → plain-language report ordered by what the user can do now, with blocker chains → choice-by-choice walk-through → approved commands only (tasks answer … --expected-version, deps add, split human steps, cancel).
• Safety rules: read-only until a specific change is approved; never flip native status on Factory-owned work; no invented reasons.
• tasks-audit/scripts/bootstrap.{sh,ps1} — copies of the tasks-execute bootstrap; probes tasks inbox and tasks answer --expected-version instead of tasks heartbeat.
• catalog/archdev.json entry, regenerated plugins/*, a pointer from tasks §7, the release-doc source list.
• scripts/fake-archdev answers the new probes (ARCHDEV_FAKE_NO_INBOX=1 drops inbox); both bootstrap test scripts cover tasks-audit, including the no-inbox rejection.

Unchanged: tasks §7 content, other skills' bootstraps.

Scope / risk / user impact

• Scope: skills + plugin bundle only.
• Risk: low. New opt-in skill; bootstrap is a copy of a tested script with one probe swapped.
• User impact: new tasks-audit skill in every harness plugin and npx skills add. archdev setup/upgrade install it once the companion firstlanding PR lands.

Testing

• tools/plugin-gen: npm run typecheck, npm test (138 pass, 0 fail — includes "every plugin carries every skill byte for byte" and the server-ownership check for every SKILL.md), npm run check (180 files match).
• scripts/test-skill-bootstrap.sh: all tasks-audit cases pass (harness envs, old versions, no-local, no-inbox, all Homebrew cases).
• Real bootstrap against installed archdev 0.55.8 resolves /opt/homebrew/bin/archdev.
• An independent read-only subagent checked every cited command/flag and data claim against archdev 0.55.8 and real Task data; its five findings (blocked_by_count counts done blockers, is_stalled rows have no lease, tasks blocked is org-wide incl. cancelled, metadata.pause missing, cancel unverified) are fixed.
• Canonical end-to-end proof: none honest for a prose skill — the behavior is an agent following the instructions. The executable proof is the bootstrap test (scripts/test-skill-bootstrap.sh, run by .github/workflows/skill-bootstrap-checks.yml on PRs) plus plugin-gen tests (.github/workflows/plugins.yml). test-skill-bootstrap.ps1 was not run locally (no pwsh); CI runs it.

CI fix included

scripts/test-skill-bootstrap-cli.{sh,ps1} failed with the released CLI 0.55.8. The Windows job fails on main too.

• Cause: the CLI's background hook-drain worker creates, holds and removes runtime files under ~/.archdev/hooks/<repo>/ after a callback runs: drain.lock/guarded, drain.guard and outbox/claim.lock.
  • Linux: the "before" snapshot caught drain.lock/guarded, which was gone by the "after" snapshot.
  • Windows: Get-FileHash could not read the drain.guard the worker holds open.
• Fix: both snapshots now skip that whole per-repository runtime directory. They already skipped its queue/.
• Unchanged: hook configuration (.archdev/hooks.json, harness settings files) is still compared.

Follow-ups

• Firstlanding: add tasks-audit to the CLI's SKILL_NAMES / tasks companions (PR linked in comments).
• tasks update --status cancelled is not in update --help; the skill tells the agent to check and report a refusal.

🤖 Generated with Claude Code

[calvin-archastro]

CLI install wiring: https://archdev.ai/ArchAstro/firstlanding/pull/21080