Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
9.7 KiB
requirements, system_design, created, status
| requirements | system_design | created | status | ||||||
|---|---|---|---|---|---|---|---|---|---|
|
|
2026-09-17 | done |
Implementation Plan: Office Routine Arming Visibility and Coordinator Install Idempotency
Overview
An Office routine has two independent switches — intent (office_routines.status)
and schedule state (whether its triggers can actually fire it) — and the product
today reports only intent. This plan makes schedule state visible everywhere
intent already is (routine reads, an unattended-install startup scan) and closes
the one identity defect that lets onboarding duplicate the pre-installed
coordinator routine. It repairs nothing: no criterion in any of the three
requirement documents enables, disables, creates, or deletes a trigger, and none
changes the existing routine-status dispatch gates. The scheduler already checks
status before it claims a cron slot, and the manual and webhook paths reject
non-firing statuses; this plan only makes the independent schedule state visible.
Two system-design documents back this plan: Routine Schedule State covers REQ-OFFICE-ROUTINE-ARMING-001/002/003 (classification, the read-path report, and the startup scan — one vertical feature contract split across two requirement documents by scope), and Coordinator Install Idempotency covers REQ-OFFICE-COORDINATOR-INSTALL-001. Both were written after Build, grounded directly in the merged implementation, rather than before it — the three requirement documents already pinned every table, column, function, and endpoint this plan touches at file-and-line precision, so drafting the designs speculatively ahead of code would have either duplicated that text or drifted from it. This plan itself still carries the remaining architecture decisions — package placement, response shape, verification boundaries — that the requirements deliberately left to Build.
Work lands in three waves: classification is the foundation everything else reads (Wave 1); the read-path report, the startup scan, and the coordinator install fix are three independent consumers of it and can proceed in parallel (Wave 2); the frontend surface depends on the backend response shape Wave 2 defines (Wave 3).
Code facts confirmed on this branch (2026-09-17)
All paths relative to apps/backend.
- Schema.
office_routinesandoffice_routine_triggersare defined ininternal/office/repository/sqlite/base.go,createRoutineTables(L414-467) — one dialect-agnostic file for both SQLite and PostgreSQL viainternal/db/dialect. There is no separate PostgreSQL schema file. - Trigger reads today.
internal/office/repository/sqlite/routines.go:GetDueTriggers(L65-78) filterskind='cron' AND enabled=1 AND next_run_at IS NOT NULL AND next_run_at <= ?with noORDER BYand does not readoffice_routines.status.RoutineService.processCronTriggerreads the routine and applies its status gate beforeClaimTrigger; the query is only the first stage of that path.ClaimTriggerandUpdateTriggerNextRunremain the trigger-state writers. - Coordinator install today.
internal/office/routines/service.go:CreateDefaultCoordinatorRoutine(L145-196) callsfindCoordinatorRoutine(L197-217), which matches workspace + assignee + canonical name +hasCronTrigger(L222-239, ignoresenabled, matches on kind + exact expression only). Its two production callers —internal/office/agents/service.go:572andinternal/office/onboarding/service.go:767— both discard the returned routine and only warn-log the error (if _, err := ...), which is why AC-OFFICE-COORDINATOR-INSTALL-001.10 forbids reporting through a return value. - Cron evaluation.
internal/office/shared/cron.go:NextCronTimevalidates the timezone, requires exactly 5 fields, follows the shared day-of-month/day-of-week OR and DST rules, and returnsErrUnsatisfiableCronwhen an otherwise valid expression has no possible occurrence. Schedule classification uses the same occurrence path. - Startup sequencing.
internal/office/infra/reconcile.go:Reconciler.ReconcileAll(L34-54) is synchronous with a void return;createTriggersForNewRoutines(L113-132) gives every trigger-less routine amanualtrigger. Called frominternal/backendapp/main.go:1378-1380, immediately followed bylog.Info("Office reconciliation complete")and, a few lines later (~L1393),services.Office.RegisterEventSubscribers. That gap is the wiring point for the startup-scan completion signal required by AC-OFFICE-ROUTINE-ARMING-003.1 — nothing today observesReconcileAllreturning. - The actual routine list/detail response.
internal/office/routines/handler.go'slistRoutines(L45-52) andgetRoutine(L98-105) backGET /workspaces/:wsId/routinesandGET /routines/:id, returningRoutineListResponse/RoutineResponse(internal/office/routines/dto.go:34-41) — today just*Routine(intent only). This, not the dashboard, is Task 02's target. Separately,internal/office/dashboard/service_agents.go'sListRoutinesblock insiderunSoftQueries(~L551-561) only countsstatus == "active"into the workspace KPI tile'sRoutineCountand is not in scope. - Trigger HTTP routes,
internal/office/routines/handler.go,RegisterRoutes(L30-42):GET/POST /routines/:id/triggers,DELETE /routine-triggers/:triggerId,POST /routine-triggers/:publicId/fire. No route edits, enables, or disables a trigger — confirms## Out of scope→ Disabling a trigger from the UI in the visibility document. - Metrics prior art.
internal/orchestrator/office_stall_metrics.go(expvar.NewMap+ label builder, L20-46) andinternal/workflow/signalmetrics/are the two labelled-counter conventions already in the codebase; this plan's new counters follow the same shape rather than inventing a third. - Persistence conformance.
internal/persistence/requiredstoresalready registers office's schema owner (catalog.go:52) andinternal/persistence/storeconformancealready has a fixed office adapter (adapters.go:224-229). No new table is required by any criterion in these three documents; Task 05's serialization mechanism must be chosen so that stays true (see its risks).
Waves
Wave 1 — classify
Wave 2 — three independent consumers of classification
- Task 02: Report intent and schedule state on routine reads (API)
- Task 04: Surface unarmed routines at startup
- Task 05: Match the coordinator routine on identity, not mutable trigger state
Wave 3 — frontend
Tasks 02, 04, and 05 touch disjoint files and have independent verification boundaries; once Task 01 lands they may proceed in parallel. Task 03 depends only on Task 02's response shape, not on Task 04 or Task 05.
Required workflow verification
After all task-level checks pass:
cd apps/backend && gofmt -l $(git diff --name-only main -- '*.go')— must be empty.make -C apps/backend test(full suite; the office and persistence packages are the ones this plan can regress).make -C apps/backend lint.- If Task 05 adds a schema owner (see its risks):
go run ./cmd/sqlguard ./internalandgo test -race ./internal/persistence/storeconformance -count=1fromapps/backend. cd apps/web && pnpm run typecheck && pnpm run lint.cd apps/web && pnpm run i18n:check.- Playwright coverage per Task 03 (
cd apps/web && pnpm e2e:run, scoped to the affected spec — see that task). - Commit the explicit changed paths with a Conventional Commit message.
Risks and non-goals
- Keep repairs separate from visibility. The operator-initiated re-arm
action remains outside this plan. A work order that starts writing
enabledornext_run_atoutside Task 05's coordinator-install path has drifted from scope. Schedule classification must continue to report an impossible cron expression astrigger_invalid, matchingNextCronTimeand the scheduler's permanent-disarm behavior. - Dispatch grace is one constant, not two. AC-OFFICE-ROUTINE-ARMING-001.10 requires classification (Task 01) and the startup scan (Task 04) to share the exact same 60-second compile-time constant. Define it once in Task 01 and import it in Task 04; do not redeclare it.
- Task 05's serialization mechanism is Build's choice, but three
candidates are pre-ruled-out in the requirement's own
## Out of scope: a bare default-isolation transaction (both callers can still both read "absent"), a PostgreSQL advisory lock (no SQLite equivalent), and an in-process-only guard (fails the documented cross-process domain). See Task 05 for the constraint set the chosen mechanism must satisfy. - No coverage percentage is a project gate. New tests must assert the specific acceptance criteria named in each task, not a line-coverage target.
- Translation completeness. Task 03's copy must exist in all five
shipped locales (
pt-pt,zh-cn,zh-hk,zh-tw, plus source English) beforepnpm run i18n:checkpasses; usepnpm run i18n:zh-hantfor the Traditional Chinese pair rather than hand-translating.