Implemented Ad-Hoc Task handling
This commit is contained in:
67
workplans/archived/260329-ADHOC-2026-03-29.md
Normal file
67
workplans/archived/260329-ADHOC-2026-03-29.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: ADHOC-2026-03-29
|
||||
type: workplan
|
||||
title: "Ad Hoc Tasks — 2026-03-29"
|
||||
domain: custodian
|
||||
repo: the-custodian
|
||||
status: done
|
||||
owner: custodian
|
||||
topic_slug: custodian
|
||||
created: "2026-03-29"
|
||||
updated: "2026-03-29"
|
||||
state_hub_workstream_id: "370c2481-6806-41eb-a917-f8874f03184f"
|
||||
---
|
||||
|
||||
# ADHOC-2026-03-29 — Ad Hoc Tasks
|
||||
|
||||
Migrated from the legacy `interactive-the-custodian` pseudo-workstream. These
|
||||
tasks were completed before the Ad Hoc Tasks file-backed convention existed.
|
||||
|
||||
## Three-tier token recording on task done
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-03-29-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "83919aef-7e93-44a2-97f6-d4f57b71acce"
|
||||
```
|
||||
|
||||
Added heuristic fallback (1000/500), workplan proration tier, and exact-count
|
||||
tier to update_task_status. Token event always created on done.
|
||||
|
||||
## Add record_interactive_task MCP tool
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-03-29-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "55eb2176-fa4c-4abb-bd1a-88ab87749b91"
|
||||
```
|
||||
|
||||
New MCP tool that found or created an interactive workstream per repo and
|
||||
recorded ad-hoc tasks with token consumption in a single call.
|
||||
|
||||
## Token note taxonomy and seed record correction
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-03-29-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "ba2543ef-2ae9-4870-8d28-4578c2ef30c4"
|
||||
```
|
||||
|
||||
Introduced measured/userbased/workplan/heuristic note taxonomy. Fixed two
|
||||
null-note seed records to userbased. Added token_note field to TaskUpdate
|
||||
schema and note param to both MCP tools.
|
||||
|
||||
## Post-WP-0030 fixes and improvements
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-03-29-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "f1512b0a-3f04-4c8b-a26f-ce82cbdd7390"
|
||||
```
|
||||
|
||||
Fixed deep-link prefix handling, FileAttachment to fetch migration, missing
|
||||
landing pages, and FK link cells with async title help-tips after WP-0030.
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
id: CUST-WP-0034
|
||||
type: workplan
|
||||
title: "SCOPE.md Delegation — Custodian Preparation"
|
||||
domain: custodian
|
||||
repo: the-custodian
|
||||
status: done
|
||||
owner: custodian
|
||||
topic_slug: custodian
|
||||
created: "2026-04-30"
|
||||
updated: "2026-05-01"
|
||||
state_hub_workstream_id: "bf94b5e9-2bc3-4c09-88cd-233849d4d86c"
|
||||
---
|
||||
|
||||
# CUST-WP-0034 — SCOPE.md Delegation Preparation
|
||||
|
||||
## Goal
|
||||
|
||||
Prepare the custodian to delegate SCOPE.md generation and maintenance to
|
||||
repo-scoping. The work now has four concrete changes: (1) upgrade the
|
||||
DOI engine's C5 check from file-presence to content-structure validation so
|
||||
the custodian can detect stale or non-conforming SCOPE.md files; (2) surface
|
||||
structured SCOPE.md health in repo dispatch and ecosystem refresh queries;
|
||||
(3) register capability request routes so `scope.generate` and `scope.update`
|
||||
requests are formally routed to repo-scoping; (4) update the scope-analyst
|
||||
kaizen agent to describe itself as a routing shim rather than a standalone
|
||||
analyser.
|
||||
|
||||
This workplan does not move any SCOPE.md generation logic — that lives in
|
||||
RREG-WP-0005. It only makes the custodian aware of the delegation interface.
|
||||
|
||||
Depends on: none
|
||||
Unblocks: RREG-WP-0005 (capability route must exist before registration), RREG-WP-0006
|
||||
|
||||
## T01: Upgrade DOI engine C5 — content structure validation
|
||||
|
||||
```task
|
||||
id: CUST-WP-0034-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7d31bbea-cebf-486e-b622-05bc5ca141ea"
|
||||
```
|
||||
|
||||
Replace the current file-presence check in `state-hub/api/doi_engine.py` (C5)
|
||||
with a three-level content check:
|
||||
|
||||
- **C5a** (pass/fail): SCOPE.md present at repo root
|
||||
- **C5b** (pass/warn): All 11 standard sections present as H2 headings:
|
||||
`One-liner`, `Core Idea`, `In Scope`, `Out of Scope`, `Relevant When`,
|
||||
`Not Relevant When`, `Current State`, `How It Fits`, `Terminology`,
|
||||
`Related / Overlapping`, `Provided Capabilities`
|
||||
- **C5c** (pass/warn): `## Provided Capabilities` contains at least one
|
||||
fenced `capability` block that parses as valid YAML with `type` and `title`
|
||||
|
||||
C5b and C5c emit `warn` (not `fail`) so a stub SCOPE.md doesn't hard-fail
|
||||
the DoI gate while still surfacing clearly in the dashboard.
|
||||
|
||||
Acceptance: `make check-doi REPO=the-custodian` reports C5a/C5b/C5c
|
||||
separately; the-custodian SCOPE.md passes all three; a repo with a blank
|
||||
stub SCOPE.md shows C5b and C5c as warn.
|
||||
|
||||
## T02: Surface SCOPE.md health in repo dispatch
|
||||
|
||||
```task
|
||||
id: CUST-WP-0034-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "243280c7-3e68-4791-9243-ef9ee6b6d311"
|
||||
```
|
||||
|
||||
Extend `GET /repos/{slug}/dispatch` with a `scope_needs_review: bool` field.
|
||||
It is `true` when either C5b or C5c is `warn` or `fail` for the repo. This
|
||||
ensures agents picking up a repo at session start see the signal without
|
||||
needing to call the DOI engine separately.
|
||||
|
||||
Also add `scope_needs_review` to the MCP `get_repo_dispatch` tool output.
|
||||
|
||||
Acceptance: for a repo with a stub SCOPE.md, `get_repo_dispatch("that-repo")`
|
||||
returns `scope_needs_review: true`; for a repo with a valid SCOPE.md it
|
||||
returns `false`.
|
||||
|
||||
Completed in the same implementation pass as T05. Dispatch now also includes
|
||||
`scope_issue_details`.
|
||||
|
||||
## T03: Register capability routes for scope generation
|
||||
|
||||
```task
|
||||
id: CUST-WP-0034-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "042c54d4-0aa6-41e1-9497-4172986d779b"
|
||||
```
|
||||
|
||||
Register two capability routes in the custodian's capability request system
|
||||
pointing to repo-scoping:
|
||||
|
||||
```
|
||||
capability_key: scope.generate
|
||||
provider_repo: repo-scoping
|
||||
description: >
|
||||
Generate a SCOPE.md from scratch for a given repo using its approved
|
||||
characteristics profile.
|
||||
input_schema: {repo_slug: string, output_path: string}
|
||||
```
|
||||
|
||||
```
|
||||
capability_key: scope.update
|
||||
provider_repo: repo-scoping
|
||||
description: >
|
||||
Diff an existing SCOPE.md against the current characteristics profile
|
||||
and write an updated version.
|
||||
input_schema: {repo_slug: string, output_path: string}
|
||||
```
|
||||
|
||||
Use `register_capability()` (MCP tool) or the `/capabilities/` API directly.
|
||||
These routes are the formal contract that downstream automation (and the
|
||||
scope-analyst agent) will use to trigger SCOPE.md work.
|
||||
|
||||
Acceptance: `list_capabilities()` returns both `scope.generate` and
|
||||
`scope.update` with `provider_repo: repo-scoping`.
|
||||
|
||||
Completed: State Hub capability catalog contains active `scope.generate` and
|
||||
`scope.update` entries attributed to `repo-scoping`.
|
||||
|
||||
## T04: Update scope-analyst kaizen agent
|
||||
|
||||
```task
|
||||
id: CUST-WP-0034-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b6d64844-8a6d-4856-bdf5-3867fb49f215"
|
||||
```
|
||||
|
||||
Update `agents/agent-scope-analyst.md`:
|
||||
|
||||
1. Add a short **Delegation** section at the top explaining that as of
|
||||
RREG-WP-0005, the authoritative SCOPE.md generator is repo-scoping.
|
||||
The scope-analyst persona is now a routing shim: it inspects the repo,
|
||||
decides whether `scope.generate` or `scope.update` is appropriate, and
|
||||
issues the capability request via `request_capability()`.
|
||||
|
||||
2. Retain the existing heuristics and template sections — they remain valid
|
||||
as the spec that repo-scoping must produce to. They also serve as
|
||||
fallback if repo-scoping is unavailable.
|
||||
|
||||
3. Add a code example showing how to issue the capability request:
|
||||
```
|
||||
request_capability(
|
||||
title="scope.generate",
|
||||
description="Generate SCOPE.md for target-repo at /path/to/SCOPE.md",
|
||||
capability_type="api",
|
||||
requesting_agent="scope-analyst",
|
||||
requesting_domain="custodian",
|
||||
requesting_workstream_id="<workstream-uuid>",
|
||||
priority="medium",
|
||||
)
|
||||
```
|
||||
|
||||
Acceptance: `get_kaizen_agent("scope-analyst")` returns the updated persona;
|
||||
the delegation flow is clear in the first screen of the agent instructions.
|
||||
|
||||
Completed: `agents/agent-scope-analyst.md` now opens with the delegation model,
|
||||
uses repo-scoping as the authoritative generator/updater, and includes a
|
||||
`request_capability(...)` example matching the live State Hub MCP signature.
|
||||
|
||||
## T05: Expose structured SCOPE.md health for repo-scoping refresh
|
||||
|
||||
```task
|
||||
id: CUST-WP-0034-T05
|
||||
status: done
|
||||
priority: high
|
||||
assignee: custodian
|
||||
state_hub_task_id: "b5d5a1f2-4148-4a1e-86e0-2249f6d633cc"
|
||||
```
|
||||
|
||||
Unblock repo-scoping RREG-WP-0006-T04 by making State Hub's SCOPE.md health
|
||||
machine-readable enough for ecosystem-wide refresh.
|
||||
|
||||
Implemented State Hub support:
|
||||
|
||||
- Split DoI C5 into C5a file presence, C5b canonical section structure, and
|
||||
C5c capability block parseability.
|
||||
- Exposed `scope_needs_review` and `scope_issue_details` from
|
||||
`GET /repos/{slug}/dispatch`; the MCP `get_repo_dispatch` tool inherits the
|
||||
same JSON shape.
|
||||
- Added `GET /repos/scope-health?needs_review=true&reachable_only=true` so
|
||||
repo-scoping can request the exact reachable repos needing SCOPE.md
|
||||
generation/update.
|
||||
- Included reason codes and targeted refresh hints:
|
||||
`missing_sections`, `invalid_capability_blocks`, and
|
||||
`needs_refresh_sections`.
|
||||
- Documented the contract in `state-hub/mcp_server/TOOLS.md`.
|
||||
|
||||
Acceptance: repo-scoping can call State Hub and get a complete list of
|
||||
reachable repos needing SCOPE.md generation/update, with reason codes for
|
||||
missing file, missing/stale sections, and missing/invalid capability
|
||||
declarations.
|
||||
|
||||
Verification:
|
||||
|
||||
- `state-hub/.venv/bin/python -m pytest tests/test_doi_scope_health.py -q`
|
||||
passed: 5 tests.
|
||||
- `state-hub/.venv/bin/python -m pytest -x -q` passed: 228 tests.
|
||||
- `git diff --check` passed.
|
||||
@@ -0,0 +1,199 @@
|
||||
---
|
||||
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"
|
||||
---
|
||||
|
||||
# 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.
|
||||
Reference in New Issue
Block a user