bcquality/custom/knowledge/architecture/task-state-lives-in-the-mandatory-artifact.md

bc-version	domain	keywords	technologies	countries	application-area
all	architecture	task-state persistence resumability bc-task pull-request pte appsource lifecycle operator-handoff	al mcp	w1	all

Task State Lives in the Mandatory Artifact — Never a New Store

Description

A task's progress through the lifecycle gates (start, red, green, review, merge) must be readable by both the operator and Claude, must survive a machine change, and must survive an operator change — a different developer picking up where the last one stopped. That rules out anything machine-local (a gitignored file, session memory).

The correct home is not a new, bespoke state store — it's whichever artifact is already mandatory for that task's flow:

• PTE (app.json idRange 50000–99999): a BC sub-task always exists before development starts ([[development-requires-bc-task]], no exceptions). The sub-task's comments (taskComments, PAG6102902) ARE the state store. Nothing new to build — just a disciplined format for what gets written there.
• AppSource: no BC task is mandatory today ([[one-task-in-progress-at-a-time]] — "AppSource app: offer, never block"). The mandatory artifact instead is the pull request. Open it as a draft early — at the start gate, not only when work is ready for review — and its description carries the state as a checklist.

Do not build a third mechanism (a community example: a dedicated workflowSessionManager with its own session IDs) when a task already has a mandatory home. Building a parallel store means two sources of truth that can drift; the artifact the flow already requires cannot drift from itself.

State vocabulary (both flows use the same stages)

TASK_STARTED        branch created, BC gitHubDevStatus = In Progress (PTE only)
RED_CONFIRMED        test written, developer confirmed the failing run
GREEN_CONFIRMED       test passes, developer/CI has actually run it
REVIEW: APPROVE | APPROVE_WITH_NOTES | BLOCK    al-review's verdict
ON_HOLD              parked mid-task (Focus gate) — always includes why
MERGED               track branch merged, BC Done (PTE) / PR merged (AppSource)

PTE format — a tagged comment per transition

Write one [CURABIS-STATE] comment per transition via Create_TaskComment_PAG6102902 (new) or Modify_TaskComment_PAG6102902 (correcting the same transition, never silently editing history — see Anti-Pattern). Keep it one line, machine-parseable:

[CURABIS-STATE] RED_CONFIRMED — 2026-08-03, mid

To resume: call List_TaskComments_PAG6102902 scoped to projectNo + subTaskNo, filter for [CURABIS-STATE] lines, the last one is current state. Never infer state from gitHubDevStatus alone — that enum only has four values (Backlog/In Progress/Done/On Hold) and cannot distinguish "red confirmed" from "green confirmed" from "blocked in review".

AppSource format — a checklist in the PR description

Open the PR as a draft at the start gate (not when work is ready), title and branch as normal, description containing:

## CURABIS Task State
- [x] Branch created — 2026-08-03, mid
- [x] Test written, RED confirmed — 2026-08-03, mid
- [ ] Implementation
- [ ] Test GREEN confirmed
- [ ] Independent review (al-review)
- [ ] Merged

Update via gh pr edit --body, checking boxes as gates pass — never remove or reorder completed lines, only append the next checked box. To resume: gh pr view <number> --json body and read which boxes are checked.

Why not adopt a dedicated session-state tool

The community pattern this generalizes from (workflow_start/workflow_next/ workflow_status, etc.) has real persisted, queryable state — genuinely worth having — but enforces no gating whatsoever: the tool hands back a natural-language instruction and trusts the calling agent to follow it, with no human checkpoint anywhere in the mechanism. CURABIS's actual advantage is the opposite property — RED_CONFIRMED and BLOCK are hard stops, not suggestions ([[testcase-must-fail-before-implementation]]). Building a parallel state store without also rebuilding that discipline would trade a real strength for a shinier mechanism. This rule adds the persistence without touching the gating.

Anti-Pattern

// WRONG: editing a state comment's text after the fact to "fix" the record
Modify_TaskComment_PAG6102902(commentId, "[CURABIS-STATE] GREEN_CONFIRMED — 2026-08-03")
// on a comment that previously said RED_CONFIRMED — this destroys the
// audit trail. Append a new comment for the new state; only use Modify
// to correct a typo in the SAME transition, never to change which
// transition it records.

Scope

Applies to every task on every CURABIS-owned or customer repo, PTE and AppSource alike, from the moment [[development-requires-bc-task]] or the AppSource equivalent activates. Wired into Smiley's Task Lifecycle gates — see smiley.agent.md.