From 21dafaa77740082031c1cb2bda7590e8608ccffb Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 1 May 2026 14:41:16 +0200 Subject: [PATCH] New workplan for better adhoc task management --- ...P-0036-adhoc-tasks-and-workplan-archive.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 workplans/CUST-WP-0036-adhoc-tasks-and-workplan-archive.md diff --git a/workplans/CUST-WP-0036-adhoc-tasks-and-workplan-archive.md b/workplans/CUST-WP-0036-adhoc-tasks-and-workplan-archive.md new file mode 100644 index 0000000..7cde19a --- /dev/null +++ b/workplans/CUST-WP-0036-adhoc-tasks-and-workplan-archive.md @@ -0,0 +1,199 @@ +--- +id: CUST-WP-0036 +type: workplan +title: "Ad Hoc Tasks and Workplan Archiving" +domain: custodian +repo: the-custodian +status: todo +owner: custodian +topic_slug: custodian +created: "2026-05-01" +updated: "2026-05-01" +state_hub_workstream_id: "b2867cd8-1866-4baa-b844-a0f37d276cae" +--- + +# CUST-WP-0036 — Ad Hoc Tasks and Workplan Archiving + +## Goal + +Replace the current permanent `interactive-` pseudo-workstream pattern +with a file-backed **Ad Hoc Tasks** convention for small opportunistic work +discovered during normal sessions. + +The convention must preserve the original intent: + +- make spontaneous quick fixes visible for review; +- track token consumption and other future review dimensions; +- avoid forcing every small improvement through full issue analysis, + requirements generation, solution planning, and formal workplan creation; +- keep ADR-001 consistency intact by giving every tracked workstream a backing + workplan file. + +At the same time, improve closed-workplan handling by moving completed +workplans into `workplans/archived/` and prefixing the archived filename with +the completion date in `YYMMDD-` form. Example: + +```text +workplans/ADHOC-2026-05-01.md +workplans/archived/260501-ADHOC-2026-05-01.md +``` + +This gives quick visual reference for both the opening date and finishing date +of a workplan. + +Depends on: CUST-WP-0014, CUST-WP-0029 +Unblocks: removal of the legacy `interactive-the-custodian` consistency +failure; cleaner token/accounting review for opportunistic work. + +## T01: Specify the Ad Hoc Tasks convention + +```task +id: CUST-WP-0036-T01 +status: todo +priority: high +state_hub_task_id: "b9ca840e-c66f-4bce-ab83-2bec68a4c0c3" +``` + +Document the Ad Hoc Tasks policy in the project rules / workplan convention +docs. + +The specification must define: + +- **Name:** Ad Hoc Tasks. +- **Active filename:** `workplans/ADHOC-YYYY-MM-DD.md`, dated by creation day. +- **Archived filename:** `workplans/archived/YYMMDD-ADHOC-YYYY-MM-DD.md`, + dated by completion/archive day. +- **Workstream slug:** `adhoc-YYYY-MM-DD`. +- **Task IDs:** `ADHOC-YYYY-MM-DD-T01`, `T02`, etc. +- **Purpose:** small, low-risk work discovered during a session and completed + directly. +- **Promotion rule:** anything requiring analysis, design, human approval, + dependency tracking, or multiple planned phases becomes a normal workplan + instead. +- **Closure rule:** once all tasks are done/cancelled and no new task has been + added for 24 hours, close the workstream and archive the file. + +Acceptance: the convention is documented clearly enough that an agent can +decide whether a discovered item belongs in Ad Hoc Tasks or a normal workplan. + +## T02: Teach consistency tooling about archived workplans + +```task +id: CUST-WP-0036-T02 +status: todo +priority: high +state_hub_task_id: "8ab029f6-8cc8-4a7c-9505-1dcd5df16f00" +``` + +Update `state-hub/scripts/consistency_check.py` and +`state-hub/scripts/validate_repo_adr.py` so archived workplans are valid +backing files. + +Requirements: + +- Active workplans are read from `workplans/*.md`. +- Archived workplans are read from `workplans/archived/*.md`. +- Archived filenames may be prefixed with `YYMMDD-` before the workplan id. +- A completed/archived DB workstream with a matching archived file is not + reported as orphaned. +- Active DB workstreams still require an active root-level workplan file. +- Archived files must not be treated as active session-start work. + +Acceptance: moving a completed workplan to `workplans/archived/260501-...md` +does not create C-07/C-08/C-12 false positives, while an active DB workstream +without a root-level workplan still fails. + +## T03: Implement timestamped archive workflow + +```task +id: CUST-WP-0036-T03 +status: todo +priority: medium +state_hub_task_id: "6922752a-6034-479a-921a-ed1ba12c740a" +``` + +Add a safe archival helper or consistency-fix path that moves closed workplans +to `workplans/archived/` with a completion-date prefix. + +Design requirements: + +- Use the workstream completion/archive date when available; otherwise use the + current date. +- Preserve the workplan frontmatter and task blocks unchanged except for + status/update fields that the existing consistency rules already manage. +- Never archive a workplan with open tasks. +- Avoid overwriting an existing archived file; report a clear conflict instead. + +Acceptance: a completed workplan can be archived through a repeatable command, +and a subsequent consistency run remains clean for that workplan. + +## T04: Replace `record_interactive_task` with file-backed adhocs + +```task +id: CUST-WP-0036-T04 +status: todo +priority: high +state_hub_task_id: "a5a0f1d9-70eb-4ef4-9081-2dd6a556a89e" +``` + +Replace the permanent `interactive-` pseudo-workstream behavior with a +file-backed Ad Hoc Tasks workflow. + +Implementation shape: + +- Introduce `record_adhoc_task(...)`. +- Keep `record_interactive_task(...)` as a deprecated compatibility alias. +- When recording an adhoc, find or create today's + `workplans/ADHOC-YYYY-MM-DD.md` for the target repo. +- Create or reuse the corresponding `adhoc-YYYY-MM-DD` workstream. +- Add a task block to the file, sync it to State Hub, mark it done, and record + token usage. +- Do not create DB-only workstreams. + +Acceptance: recording an adhoc task produces a file-backed workstream and does +not create a C-07 consistency failure. + +## T05: Migrate or retire legacy interactive workstreams + +```task +id: CUST-WP-0036-T05 +status: todo +priority: medium +state_hub_task_id: "4bc4edec-a97d-45f0-8929-5da0395a21c0" +``` + +Clean up existing `interactive-` pseudo-workstreams. + +Options to evaluate: + +- create archived `ADHOC-...` files for historically relevant interactive + workstreams; +- mark empty or obsolete interactive workstreams archived with an explicit + migration progress event; +- add a one-time compatibility exception only for pre-migration legacy rows. + +Acceptance: `interactive-the-custodian` no longer causes the current C-07 +failure, and the migration preserves enough history for token review. + +## T06: Tests, docs, and dashboard/review surface + +```task +id: CUST-WP-0036-T06 +status: todo +priority: medium +state_hub_task_id: "ac480949-2ae4-4e6f-9a85-c72b18b96d2f" +``` + +Add focused tests and user-facing references. + +Coverage should include: + +- consistency checker sees timestamp-prefixed archived workplans; +- active workstreams still require root-level workplans; +- `record_adhoc_task` creates file-backed tasks and token events; +- old `record_interactive_task` alias still works during deprecation; +- dashboard or API token review can distinguish adhoc tasks from normal + planned tasks. + +Acceptance: tests cover the new lifecycle, and the tool reference explains +when to use Ad Hoc Tasks versus a normal workplan.