e0f93304bf
Add archive terminology note tool, extend scan allowlist for generated trees, mark remaining tasks done, and add grandfather notes to archived workplans in this repo.
201 lines
6.7 KiB
Markdown
201 lines
6.7 KiB
Markdown
---
|
|
id: CUST-WP-0036
|
|
type: workplan
|
|
title: "Ad Hoc Tasks and Workplan Archiving"
|
|
domain: custodian
|
|
repo: the-custodian
|
|
status: done
|
|
owner: custodian
|
|
topic_slug: custodian
|
|
created: "2026-05-01"
|
|
updated: "2026-05-01"
|
|
state_hub_workstream_id: "b2867cd8-1866-4baa-b844-a0f37d276cae"
|
|
---
|
|
|
|
> **Terminology note:** Historical text in this archived workplan may use the legacy term "workstream". The fleet term is **workplan** (`canon/standards/workplan-terminology-fleet_v0.1.md`).
|
|
|
|
# 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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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.
|