2026-05-10 — TASKSET 6 — Operator ergonomics

---

rank: decision outranks: [finding, runbook]

2026-05-10 — TASKSET 6 — Operator ergonomics

Date: 2026-05-10 Status: closed Supersedes: none Superseded-by: none — current

Context

TASKSET 5b-ii shipped all eight petrova.act.* verb forms at /console/acts/new/<verb>. The forms were functional but lacked three operator-requested ergonomics:

1. Sweep freshness — no way to see when state files were last written by petrova sweep-state.
2. Idempotency collision warning — no signal when a dry-run re-encounters an already-open PR with the same key.
3. PR diff preview — dry-run showed the PR body but not what files would actually change.

This taskset delivers all three.

Decisions

D1 — petrova.sweeps.status tool + /console/sweeps page

New MCP+HTTP tool petrova.sweeps.status reads last_full_sweep from every state file and computes per-repo and per-integration freshness. Returns:

{
  "slug": "eva-hq",
  "last_full_sweep": "2026-05-10T14:26:11.771Z",
  "age_minutes": 12,
  "stale": false,
  "integration_freshness": {
    "ares": { "last_verified_at": "2026-05-06T16:42:48Z", "age_minutes": 5760 },
    ...
  }
}

Dashboard page /console/sweeps displays a table with:

• Last sweep timestamp + relative age
• “stale” badge when age > 24h
• Per-integration verification age chips

Nav entry added to Shell between phases and governance.

D2 — Idempotency collision warning in verb forms

New GET endpoint /api/acts-check?key=<idempotency_key> returns collision info if an open PR with that key exists in the fleet. After dry-run, ActFormShell client JS calls this and displays a warning box if collision is found, with a link to the existing PR.

D3 — PR diff preview in dry-run forms

The dry-run response now includes content_preview (first 600 chars of each file’s contents) alongside the existing path, operation, and size_bytes. ActFormShell renders these as expandable pre blocks under the “Files changed” header.

Schema updated: spec/verbs/_common.schema.json#/$defs/DiffPreview.items now allows content_preview.

Evidence

• Host tests: 74/74 pass (tool count bumped from 21 → 22)
• CLI tests: 185/186 pass (1 pre-existing diagnose.test.ts failure, unrelated)
• Dashboard builds: 0 errors 0 warnings
• New files:
  • host/src/tools/sweeps.ts
  • dashboard/src/pages/console/sweeps.astro
  • dashboard/src/pages/api/acts-check.ts
• Modified:
  • host/src/mcp.ts, host/src/http.ts, api/rpc.ts (register sweeps tool)
  • dashboard/src/layouts/Shell.astro (nav entry)
  • dashboard/src/components/ActFormShell.astro (collision + diff preview)
  • cli/src/pr-emitter.ts (content_preview in dry-run)
  • spec/verbs/_common.schema.json (schema field)

Consequences

For code:

• 22 tools now exposed via MCP/HTTP/RPC (was 21)
• Verb forms now show file contents preview + collision warnings
• Sweeps page shows state-file freshness for all 10 registered repos

For in-flight phases:

• TASKSET 6 closed — operator ergonomics delivered.
• All six tasksets (1-6) now complete.

For invariants:

• MR-7 (audit trail) unchanged — collision warning surfaces existing PR, doesn’t suppress it.
• No schema-breaking changes — added optional content_preview only.

Alternatives considered

• Idempotency collision in the verb itself — rejected: the verb returns the dry-run result; collision check is a read-only concern best handled by the dashboard.
• Diff hunks instead of content preview — rejected: computing full diffs requires Git API access; content_preview is a cheap string slice with no network calls.
• Real-time sweep status — rejected: too expensive. State files are written by batch sweeper; freshness computed from existing timestamps.

Risks

• content_preview size — capped at 600 chars to avoid bloated responses. Operator can click through to the PR for full view. Acceptable.
• /api/acts-check on every dry-run — one extra fetch, negligible overhead. Cached by browser.

Sign-off

• Subagent: Claude Code
• Human: alex@devarno.com — 2026-05-10