200 lines
6.6 KiB
Markdown
200 lines
6.6 KiB
Markdown
---
|
|
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-<repo>` 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-<repo>` 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-<repo>` 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.
|