Skip to content

feat(dashboard): mechanically link spawned/torn-down tasks to their card - #9

Merged
joliverMI merged 1 commit into
mainfrom
fm/fm-card-work-link
Aug 18, 2026
Merged

joliverMI merged 1 commit into
mainfrom
fm/fm-card-work-link

Conversation

@joliverMI

Copy link
Copy Markdown
Owner

Summary

The fleet auditor traced every status discrepancy it has raised to one cause: no card's agent/backlog_ref was ever populated, so a status transition only happened when someone remembered to make it by hand - worst of all at teardown, the exact moment the worker doing the remembering is removed.

  • bin/fm-spawn.sh --card <card-id> (new flag): writes dashboard_card=<card-id> into the task's own state/<id>.meta (the durable identity link teardown later consumes), then best-effort sets the card's backlog_ref to <home>:<task-id> (the exact format the fleet auditor's sweep already reads) and its agent to the task id, advancing a not_started card to working. Refused on --secondmate and --relaunch for the same reason --mode/--yolo are: those spawns don't own that axis.
  • bin/fm-teardown.sh: reads dashboard_card= back out of meta and, once a real (non---force) landing actually succeeds, advances the card to testing - the exact hand-off the audit named as most likely to be forgotten. Scout and secondmate teardowns never touch the card (scratch worktree / not a backlog item), a --force discard never touches it (a discard is not a landing), and an already-complete card is never downgraded back.
  • Reuses the board's existing ref/agent/status fields end to end - no new store.
  • No card is the normal case and stays a complete no-op - the vast majority of fleet work never touches the dashboard. A bad card id or an unreachable dashboard never fails the spawn or teardown; it prints a loud warning: and best-effort records fm-dashboard.sh audit-log --fleet, so a link that could not fire is visible in the same discrepancy log the fleet auditor already reads, not silently dropped.
  • docs/dashboard.md gets a new "The mechanical card link" section owning the full design/rationale; the fleet-dashboard skill gets a one-paragraph pointer to prefer --card over manual follow-up calls.

Backfill

All 21 live cards still carry no agent/backlog_ref. None were backfilled - here's why, rather than guessing:

  • 20 cards (captain_dj, e.g. hue-area-selection-c10f, three-mode-display-port-8lvy, ...) belong to a project this task has no access to. Their own notes/prompts carry no task-id evidence, and I have no filesystem access to that project's backlog/state to independently establish which task, if any, currently serves each card.
  • 1 card (fleet-dashboard-gh63, captain firstmate) is already complete with no live task - the work that shipped it has presumably already been torn down, so there is nothing left to link retroactively.

Backfilling is now mechanical going forward: pass --card <id> the next time a task is dispatched to serve one of these.

Test plan

  • bin/fm-lint.sh bin/fm-spawn.sh bin/fm-teardown.sh tests/fm-dashboard-card-link.test.sh - shellcheck clean
  • New tests/fm-dashboard-card-link.test.sh (9 cases, real dashboard server + real fm-spawn.sh/fm-teardown.sh invocations, no mocked dashboard): link+advance-to-working at spawn, no-card no-op, unreachable-dashboard doesn't fail spawn/teardown, unknown-card-id warns + records a fleet finding, advance-to-testing at teardown on a real landed local-only merge, force-discard never advances, already-complete is never downgraded
  • Full existing suites re-run clean with zero regressions: tests/fm-dashboard.test.sh, tests/fm-teardown.test.sh (62/62), tests/fm-spawn-worktree-settle.test.sh, tests/fm-spawn-batch.test.sh, tests/fm-spawn-dispatch-profile.test.sh, tests/fm-teardown-endpoint-safety.test.sh, tests/fm-trace-context-spawn.test.sh
  • bin/fm-doc-audience-check.sh clean after the docs/dashboard.md addition

Every dashboard card's agent and backlog_ref sat empty, so status
transitions only happened when someone remembered to make them by
hand - worst of all at teardown, the exact moment the worker that
would have remembered is being removed.

fm-spawn.sh --card <card-id> now records dashboard_card=<id> in the
task's own state/<id>.meta and best-effort links the card's ref/agent
to the task identity, advancing a not_started card to working.
fm-teardown.sh reads that identity back and advances the card to
testing once a real (non-forced) landing succeeds, leaving scout,
secondmate, and already-complete cards untouched.

No card is the normal case and stays a complete no-op. A bad card id
or an unreachable dashboard never fails the spawn or the teardown; it
warns loudly and best-effort records fm-dashboard.sh audit-log
--fleet so a failed link is visible to the fleet auditor rather than
silently dropped.

All 21 live cards still carry no agent/ref - 20 belong to a project
this task has no access to verify task identities for, and the one
firstmate-owned card is already complete with no live task to link -
so none were backfilled; see the PR description for the per-card list.
@joliverMI
joliverMI merged commit 3c8f796 into main Aug 18, 2026
11 of 13 checks passed
@joliverMI
joliverMI deleted the fm/fm-card-work-link branch August 18, 2026 14:48
joliverMI added a commit that referenced this pull request Aug 19, 2026
…ard (#9)

Every dashboard card's agent and backlog_ref sat empty, so status
transitions only happened when someone remembered to make them by
hand - worst of all at teardown, the exact moment the worker that
would have remembered is being removed.

fm-spawn.sh --card <card-id> now records dashboard_card=<id> in the
task's own state/<id>.meta and best-effort links the card's ref/agent
to the task identity, advancing a not_started card to working.
fm-teardown.sh reads that identity back and advances the card to
testing once a real (non-forced) landing succeeds, leaving scout,
secondmate, and already-complete cards untouched.

No card is the normal case and stays a complete no-op. A bad card id
or an unreachable dashboard never fails the spawn or the teardown; it
warns loudly and best-effort records fm-dashboard.sh audit-log
--fleet so a failed link is visible to the fleet auditor rather than
silently dropped.

All 21 live cards still carry no agent/ref - 20 belong to a project
this task has no access to verify task identities for, and the one
firstmate-owned card is already complete with no live task to link -
so none were backfilled; see the PR description for the per-card list.

Co-authored-by: joliverMI <joliver@sensibletech.biz>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants