diff --git a/.dispatch/job-state/docs-audit.md b/.dispatch/job-state/docs-audit.md index fa1f3e84..095ae785 100644 --- a/.dispatch/job-state/docs-audit.md +++ b/.dispatch/job-state/docs-audit.md @@ -1,6 +1,6 @@ --- job: docs-audit -updated_at: 2026-04-20 +updated_at: 2026-04-22 --- # docs-audit — state handoff @@ -9,62 +9,64 @@ Each run of the docs-audit job reads this file at Phase 0 and overwrites it at P ## last_audited_sha -`4dd3e83ff37c4549730046c25d839dd8df7795b2` — HEAD at the start of the 2026-04-20 Notifications run (before the PR that lands this file). The PR that lands this file will advance the SHA once merged; the next run should diff from whatever HEAD is when it reads the file. +`0ff89eec070c47411ea171a83bf5d3c547074578` — HEAD at the start of the 2026-04-22 Status Events run (before the PR that lands this file). The PR that lands this file will advance the SHA once merged; the next run should diff from whatever HEAD is when it reads the file. ## next_focus -**Audit the docs-pane "Status Events" section against `AGENT_LATEST_EVENT_TYPES` in `apps/server/src/server.ts` and the UI surfaces that render events.** +**Audit the docs-pane "Reviewers" section against the persona review round-trip loop and recheck state machine landed in PRs #372 / #374 / #381 / #382.** -Status Events is the oldest section that hasn't been re-audited since the 2026-04 passes began, and the backlog has been pointing at it as "in sync today, re-check when new event types are added." The 2026-04-20 Notifications pass touched the same event list (`done`/`waiting_user`/`blocked`) from the notification side, which is a good prompt to spot-check the primary Status Events copy itself. Likely checkpoints: +Reviewers is the highest-leverage next slice — multiple feature PRs have landed since the section was last touched (2026-04-18), and the existing copy is already known to be incomplete (resolution capture is in backlog and the round-trip schema and recheck state machine are entirely undocumented). Likely checkpoints: -- **Event type list.** `AGENT_LATEST_EVENT_TYPES` in `apps/server/src/server.ts` is still `working` / `blocked` / `waiting_user` / `done` / `idle`. Confirm the docs enumerate exactly this set (no extras, no drops). -- **Color mapping.** The 2026-04-18 Agents pass fixed a working/done color swap by resolving `--status-working` / `--status-done` / `--status-blocked` / `--status-waiting` from `apps/web/src/index.css`. Re-verify the hues in current copy actually match what that CSS produces (theme files may have shifted — check `apps/web/src/themes/` if it exists, otherwise `index.css`). -- **Event metadata the UI shows.** The sidebar renders the event message and "how long ago" — confirm the docs mention both and that the rendering component (`apps/web/src/components/app/agents-view.tsx` or siblings) still formats them the same way. -- **Sound cue alignment (cross-reference).** `apps/web/src/lib/sound-cues.ts` registers cues for `done` / `blocked` / `waiting_user` + a `review_finished` synthetic cue. The Status Events docs don't have to list sound cues (that's Notifications' job), but verify the two sections don't contradict each other about which statuses are "notable." -- **Dispatch event reporting guidance.** If the Status Events section describes how agents report events via `dispatch_event`, cross-check the tool's current signature in `apps/server/src/shared/mcp/server.ts` (`dispatch_event` in `AGENT_TOOLS`). +- **Review lifecycle subsection.** Currently mentions `review_status` with `reviewing`/`complete` and verdicts `approve`/`request_changes`. The round-trip loop adds parent-side tools (`dispatch_resolve_feedback`, `dispatch_submit_resolution`) and the recheck state machine adds new states/transitions. Trace through `apps/server/src/shared/mcp/server.ts` for the current `PERSONA_TOOLS` and `AGENT_TOOLS` lists and the actual review/resolution tool registrations. +- **Recheck state machine.** PR #382 (`fe8c5cd`) added `apps/server/src/reviews/poll-cadence.ts` plus changes to `agents/manager.ts`. Read those to enumerate the new states and how the loop progresses (parent submits resolution → reviewer rechecks → new verdict). Also look at `apps/web/src/components/app/persona-agent-row.tsx` for the "stacked status button" UI surface from PR #383 / #385. +- **Resolution reasons + parent summary.** PR #374 (`8ad64b9`) surfaces resolution reasons and a parent summary in the UI — `apps/web/src/components/app/feedback-panel.tsx` is the anchor file. Verify the docs describe what the parent agent passes and where it shows up. +- **DB anchor for round-trip.** `apps/server/src/db/migrations/0017_persona-review-round-trip.sql` is the schema for the loop. Use the column names there to confirm tool/field naming in the docs. +- **Autonomous Review flow (still in backlog).** The Agents section documents the create-agent checkbox; the Reviewers section never explains the end-to-end autonomous-review flow. Consider folding this into the same PR as the round-trip work since the tooling and lifecycle copy will overlap. Concrete pointers: -- Primary target: `apps/web/src/components/app/docs-pane.tsx` — section with `id: "events"`. +- Primary target: `apps/web/src/components/app/docs-pane.tsx` — section with `id: "personas"` (label "Reviewers"), the `Review lifecycle` subsection in particular. - Cross-check against: - - `apps/server/src/server.ts` — `AGENT_LATEST_EVENT_TYPES` plus event upsert path. - - `apps/web/src/index.css` — `--status-*` CSS variables. - - `apps/web/src/components/app/agents-view.tsx` — event rendering in the sidebar. - - `apps/server/src/shared/mcp/server.ts` — `dispatch_event` tool registration. + - `apps/server/src/shared/mcp/server.ts` — `PERSONA_TOOLS` and `AGENT_TOOLS` sets, plus the `review_status` / `dispatch_submit_feedback` / `dispatch_resolve_feedback` / `dispatch_submit_resolution` registrations. + - `apps/server/src/reviews/poll-cadence.ts` — recheck cadence / state transitions. + - `apps/server/src/agents/manager.ts` — review state fields on agent records. + - `apps/server/src/db/migrations/0017_persona-review-round-trip.sql` — schema source of truth for the loop. + - `apps/web/src/components/app/persona-agent-row.tsx` — UI surface for the stacked status button. + - `apps/web/src/components/app/feedback-panel.tsx` — UI surface for resolution reasons + parent summary. -Scope the PR to this one section plus whatever `git diff ..HEAD` turns up. +Scope the PR to the Reviewers section plus whatever `git diff ..HEAD` turns up. If the round-trip loop alone is enough for one PR, defer the Autonomous Review subsection back to backlog. ## backlog Items noticed during prior passes but left for later runs. Pick the most relevant one when `next_focus` is empty or already done. +- **docs-pane "Status Events" section — `metadata` parameter** — 2026-04-22 run noted that `dispatch_event` accepts an optional `metadata` (Record) param via `apps/server/src/shared/mcp/server.ts` registerTool input schema. Currently undocumented. It's an advanced/optional field; revisit only if a feature starts using metadata in a user-visible way (none does today — `latestEvent` rendering in `agent-card.tsx` doesn't read metadata). - **docs-pane "Jobs" section — lifecycle handoff files** — the 2026-04-19 Jobs run seeded the Jobs section with the four lifecycle tools (`job_log` / `job_complete` / `job_failed` / `job_needs_input`) and basic run lifecycle, but did not document the `.dispatch/job-state/.md` handoff convention. That's not a server feature — it's a pattern individual jobs adopt — but the docs could mention it under "Run lifecycle" as a recommended way for agents inside a recurring job to pass context between runs. Check `docs-audit.md` and any other `.dispatch/job-state/*.md` files that exist at the time for concrete examples. -- **docs-pane "Jobs" section — `JobNotifyConfig` is data-model-only today** — 2026-04-20 Notifications pass confirmed that `JobNotifyConfig` (`onComplete`/`onError`/`onNeedsInput`) on `JobRecord` is wired through to Slack via `jobService.onRunStateChange` in `apps/server/src/notifications/job-notifier.ts`, but is **not** exposed via any API or UI: `AddJobInput` / `JobConfigUpdate` don't include `notify`, the add-job form has no toggle, and `POST /api/v1/jobs` can't set it. The DB column exists and stays null for every user-created job. Do **not** document this as a Jobs feature yet — revisit when a UI or API is added. Deliberately omitted from the Notifications section for the same reason. +- **docs-pane "Jobs" section — `dispatch_rename_session` is now exposed to job agents** — PR #378 (`3940270`, "Expose dispatch_rename_session to job agents") added the tool to `JOB_TOOLS`. The Jobs section may not yet mention that job agents can rename their session. Quick spot-check next time the Jobs section is touched. +- **docs-pane "Jobs" section — `JobNotifyConfig` is data-model-only today** — 2026-04-20 Notifications pass confirmed that `JobNotifyConfig` (`onComplete`/`onError`/`onNeedsInput`) on `JobRecord` is wired through to Slack via `jobService.onRunStateChange` in `apps/server/src/notifications/job-notifier.ts`, but is **not** exposed via any API or UI: `AddJobInput` / `JobConfigUpdate` don't include `notify`, the add-job form has no toggle, and `POST /api/v1/jobs` can't set it. The DB column exists and stays null for every user-created job. Do **not** document this as a Jobs feature yet — revisit when a UI or API is added. - **docs-pane "Jobs" section — timeouts** — `timeoutMs` and `needsInputTimeoutMs` are configurable per job (defaults 30 min / 24 h in `apps/server/src/jobs/service.ts`). The current copy mentions "subject to a separate needs-input timeout" but does not call out that either value is configurable. A short bullet would close this. - **docs-pane "Media & Sharing" section** — audited 2026-04-19. Re-check when `registerShareTool` or `isMediaFile` in `apps/server/src/server.ts` gain new supported extensions (the current docs list is hand-maintained), or when the Share-file upload UI changes. -- **docs-pane Reviewers section — Autonomous Review flow** — the Agents pass documented the "Autonomous Review" checkbox on create-agent-dialog.tsx, but the Reviewers section never explains how auto-review actually works end-to-end (which persona is launched, when, what the parent agent sees, how addressing feedback works). Worth a "Autonomous review" subsection that ties the two features together. -- **docs-pane Reviewers section — resolution capture** — commit 4dd3e83 ("feat(server): resolution capture for persona feedback (CRU-128)") added `dispatch_resolve_feedback` and `dispatch_submit_resolution` to `AGENT_TOOLS` (see `apps/server/src/shared/mcp/server.ts`). The Reviewers section's "Review lifecycle" subsection should cover the parent agent's half of the loop: the parent agent fetches feedback via `dispatch_get_feedback`, resolves it via `dispatch_resolve_feedback`, and reports the resolution back with `dispatch_submit_resolution`. Migration `0016_feedback-resolution-capture.sql` is the DB anchor; `FeedbackRecord` in `apps/server/src/agents/manager.ts` is the type. - **docs-pane "Worktrees" — deps auto-install** — `setupWorktree` in `apps/server/src/agents/manager.ts` (search `setupWorktree`) auto-installs deps by detecting `pnpm-lock.yaml` / `yarn.lock` / `package-lock.json` / `bun.lockb`. The Automatic-worktree-creation bullet in docs-pane only mentions `.env` copying; a one-sentence mention of the lockfile-driven install would round it out. -- **`docs/03-api-spec.md`** — spot-check for new routes added in the last 30 days. Recent migrations (0012 auto-review, 0013 review agent type, 0014 base branch, 0015 jobs base branch + auto-archive, 0016 feedback resolution capture) imply the agents and jobs POST body schemas have grown. The actual on-demand run endpoint is `POST /api/v1/jobs/run` (body: `{ name, directory, wait?, triggerSource? }`) — spec may pre-date that. Notifications endpoints worth checking too: `/api/v1/notifications/settings` (GET/POST), `/api/v1/notifications/test` (POST), `/api/v1/focus` (POST). +- **`docs/03-api-spec.md`** — spot-check for new routes added in the last 30 days. Recent migrations (0012 auto-review, 0013 review agent type, 0014 base branch, 0015 jobs base branch + auto-archive, 0016 feedback resolution capture, 0017 persona review round-trip) imply the agents and jobs POST body schemas have grown. The actual on-demand run endpoint is `POST /api/v1/jobs/run` (body: `{ name, directory, wait?, triggerSource? }`) — spec may pre-date that. Notifications endpoints worth checking too: `/api/v1/notifications/settings` (GET/POST), `/api/v1/notifications/test` (POST), `/api/v1/focus` (POST). - **`docs/04-agent-lifecycle.md`** — verify it still matches `AgentStatus` / `SetupPhase` / `ArchivePhase` in `apps/server/src/agents/manager.ts`. Values: status ∈ {creating, running, stopping, stopped, archiving, error, unknown}; setupPhase ∈ {worktree, env, deps, session, null}; archivePhase ∈ {stopping, worktree-check, worktree-cleanup, finalizing, null}. -- **`docs/10-operations-runbook.md`** — verify service management commands match current `bin/dispatch-server` / `bin/dispatch-deploy` flags. -- **README.md** — two gaps to address in one small pass: - - feature list at `README.md:40` mentions "in-app browser notifications (with Slack fallback if no browser client acks)" but has no bullet for sound cues (added 2026-04-19 via commit 8704a99). A one-line addition keeps it in sync. - - MCP tools summary may be out of date for the same reasons the docs-pane was; spot-check against `AGENT_TOOLS` / `JOB_TOOLS` / `PERSONA_TOOLS`. +- **`docs/10-operations-runbook.md`** — verify service management commands match current `bin/dispatch-server` / `bin/dispatch-deploy` flags. PR #377 (`c9e06c0`, "use launchctl kickstart -k for macOS deploy restart") changed deploy/restart behavior — runbook may pre-date this. +- **README.md** — feature list at `README.md:40` mentions "in-app browser notifications (with Slack fallback if no browser client acks)" but has no bullet for sound cues (added 2026-04-19 via commit 8704a99). A one-line addition keeps it in sync. MCP tools summary may be out of date for the same reasons the docs-pane was; spot-check against `AGENT_TOOLS` / `JOB_TOOLS` / `PERSONA_TOOLS`. ## drift_patterns Observations about where docs tend to go stale. Each run should add new observations and prune ones that no longer apply. - **User-facing docs drift fastest.** When the app's behavior changes, the in-app docs-pane content is the first thing to notice. It's also the easiest to update in the same PR as the code change (a reviewer can flag stale copy), but in practice it often isn't — so this audit is where it catches up. +- **"Sidebar shows X" claims understate what's actually rendered.** 2026-04-22 found the Status Events section said the sidebar shows "the latest event message and a color-coded status indicator" but `agent-card.tsx` actually renders three things: a colored status label (Working / Blocked / Waiting / Done / Idle from `latestEventLabel`), a relative timestamp from `formatRelativeTime` in `agent-event-utils.ts` ("just now" / "5m ago" / "2h ago" / "3d ago"), and the message. When auditing any "sidebar shows" / "card shows" / "page shows" claim, open the actual rendering component (typically in `apps/web/src/components/app/`) and enumerate every span in the JSX — copy tends to mention only the most prominent one. - **Settings defaults flip without the docs noticing.** 2026-04-18 Worktrees run found the docs claimed the default worktree location was `.dispatch/worktrees/` (nested), but `WorktreeLocationSettings` in `apps/web/src/components/app/settings-pane.tsx` actually defaults to `"sibling"`, and so does `manager.ts` (`worktreeLocation = input.worktreeLocation ?? "sibling"`). When auditing a "default" claim in docs, trace it to the component's `useState(...)` initial value AND to the server-side fallback — the two can disagree, and the docs usually follow whichever one was true when the doc was first written. -- **The built-in MCP tool list sprawls without touching the docs.** The 2026-04-18 Repo Tools pass found the docs-pane listed 7 built-in tools; `AGENT_TOOLS` in `apps/server/src/shared/mcp/server.ts` actually has 17 now (resolution capture added two more in 4dd3e83). Each new tool gets added to `AGENT_TOOLS` / `JOB_TOOLS` / `PERSONA_TOOLS` but almost never to `docs-pane.tsx`. Grep for `AGENT_TOOLS = new Set` and diff against the `Built-in tools` list in `docs-pane.tsx` whenever touching this area. +- **The built-in MCP tool list sprawls without touching the docs.** The 2026-04-18 Repo Tools pass found the docs-pane listed 7 built-in tools; `AGENT_TOOLS` in `apps/server/src/shared/mcp/server.ts` actually has 17 now (resolution capture added two more in 4dd3e83). Each new tool gets added to `AGENT_TOOLS` / `JOB_TOOLS` / `PERSONA_TOOLS` but almost never to `docs-pane.tsx`. Grep for `AGENT_TOOLS = new Set` and diff against the `Built-in tools` list in `docs-pane.tsx` whenever touching this area. PR #378 (`3940270`) added `dispatch_rename_session` to JOB_TOOLS — typical pattern. - **The create-agent dialog accretes options silently.** When `create-agent-dialog.tsx` gains a field, the "Creating an agent" bullet list needs a matching entry. Grep `create-agent-dialog.tsx` for `

How events are used

- The agent sidebar shows the latest event message and a color-coded - status indicator for each agent. Events are also stored in the - database for activity tracking — the Activity page uses them to - build heatmaps, working-time breakdowns, and daily status charts. + Each agent's card in the sidebar shows the latest event's status + label (Working / Blocked / Waiting / Done / Idle, color-coded), a + relative timestamp (e.g. "just now", "5m ago"), and the message. + Events are also stored in the database for activity tracking — the + Activity page uses them to build heatmaps, working-time breakdowns, + and daily status charts.