JAM-40: Mission Control task boundary and lifecycle hardening

Recommended fix: define one explicit intake rule in AGENTS.md for when work becomes a Mission Control task, then route every lifecycle mutation through one canonical server-side transition path that verifies the write before confirming success. Category: Tool, with a small AGENTS behavioral rule update. Do not start with a new skill.

1. Problem Statement and Goal

Mission Control already has the right status model on paper, but it does not yet have one reliable operational path that makes the board reflect reality every time.

Current friction has two parts:

1. Task boundary drift. It is not always clear when work should stay chat-native versus become a Mission Control task.
2. Lifecycle drift. Status changes can be issued through multiple paths, but there is no single transition mechanism with write verification.

AGENTS.md already defines the intended lifecycle:

• start work: up-next -> in-progress
• deliverable ready: in-progress -> needs-review
• approved: needs-review -> done

The problem is not missing intent. The problem is missing enforcement.

Goal: define a canonical operational model for task creation and task lifecycle transitions so the board reflects reality, status changes persist, and agents stop using ad hoc status writes.

2. Success Metric

This spec is successful if the implementation that follows can satisfy all of the below:

• Boundary clarity: agents can decide task vs chat with a short deterministic rule set, without improvising.
• Lifecycle reliability: every prototype transition persists after immediate re-read and after UI refresh.
• Single path: all normal status changes use one canonical transition path, not raw full-list replacement.
• Fail closed behavior: ambiguous task matches and invalid transitions return an error instead of guessing.
• Prototype proof: 3 to 10 real task transitions complete cleanly before broader codification.

3. Current State

3.1 Existing rules already define the intended behavior

/Users/vinny/.openclaw/workspace/AGENTS.md already contains mandatory rules for:

• spec completion workflow
• up-next queue workflow
• task status lifecycle

Those rules correctly say the board should reflect reality and that tasks should move as work happens.

3.2 The main status mutation path is still a raw full-array write

AGENTS.md also defines a chat workflow for:

• "move [task name] to [column]"

That workflow reads tasks.json, mutates one task in memory, then performs:

• PUT http://localhost:3100/api/tasks
• with the full tasks array

This is not a targeted task transition. It is a list replacement.

3.3 The web UI also writes the full task list

mission-control/components/tasks/TasksWorkspace.tsx currently:

• mutates task state optimistically in the browser
• writes the browser cache immediately
• sends PUT /api/tasks with the full tasks array
• polls /api/tasks every 5 seconds and can rehydrate the UI from server state

This means status changes are not owned by a single mutation path.

3.4 The data store is partly hardened, partly not

mission-control/lib/tasks-store.ts currently:

• uses atomic rename writes
• uses a lock for createTask()
• does not use the lock for writeTasks()

mission-control/app/api/tasks/route.ts currently accepts a full-array PUT and passes it directly to writeTasks().

So the system has atomic file writes, but not a canonical per-task transition path, and not a consistent lock boundary for updates.

3.5 Status vocabulary is already drifting across layers

The Mission Control app uses the canonical statuses:

• backlog
• up-next
• in-progress
• needs-review
• done

But the task capture skill still advertises and parses:

• next
• blocked
• no canonical up-next
• no canonical needs-review

mission-control/scripts/capture-task.mjs already contains normalization logic that maps legacy values like next -> up-next and blocked -> backlog + blocked=true, which is another sign that workflow rules and tool interfaces have drifted.

3.6 Current board snapshot is small enough for a real prototype

Current tasks.json snapshot:

Active real tasks available for validation:

4. Platform Capabilities

This work does not require a new OpenClaw platform feature.

The current stack already supports the right shape:

• local Next.js API routes for deterministic server-side mutations
• local scripts for deterministic task operations
• chat workflows that can call scripts instead of improvising JSON edits
• existing Mission Control UI that can call a targeted endpoint instead of replacing the full list

Browser automation is not required for the fix itself.

5. Community Patterns

Two external patterns are relevant.

First, Linear issue statuses uses a small ordered workflow where tasks move through clearly bounded categories such as backlog, started, review, and done. The useful pattern is not Linear's exact labels. It is the combination of a small state machine and clear transition semantics.

Second, REST API Design: Dealing with concurrent updates describes the lost update problem that appears when multiple clients submit changes based on stale resource state. Mission Control currently uses full-list replacement for normal task updates, which is exactly the class of write path that can lose newer changes.

6. Options

7. Recommendation

Recommend Option B.

The simplest durable fix is:

1. Codify the task boundary in AGENTS.md.
2. Create one canonical transition helper/API for lifecycle changes.
3. Make chat commands and UI status changes use that path.
4. Verify the persisted task after each transition before reporting success.

Do not start with a new skill. A skill would improve ergonomics, but it would not solve the core reliability problem unless the underlying mutation path is fixed first.

This is a staged implementation, because the right fix spans both operator behavior and Mission Control code.

8. Security Considerations

This is primarily a correctness problem, not a data exposure problem, but there are still guardrails to enforce.

• Ambiguous task references: never guess. If title matching returns multiple tasks, stop and ask.
• Wrong-task mutation risk: prefer displayId once a task is identified.
• Invalid transitions: reject illegal moves rather than forcing them through.
• False success: never say a transition succeeded until the persisted task is re-read and confirmed.
• Cron: do not use cron as the primary fix. At most, add a narrow secondary audit later if Pete wants a consistency check, but only after the canonical mutation path exists.

9. Implementation Scope

9.1 Canonical operational model: task vs chat

Use this rule set.

Default rule: stay chat-native unless at least one durable-work trigger is present.

Operational rule: if the agent is about to do substantive async or multi-step work and no task exists, create or confirm a Mission Control task before continuing.

9.2 Canonical lifecycle model

Keep the current five statuses. Tighten the meaning of each.

Use explicit transition verbs instead of generic column moves for normal work.

Normal-path constraints:

• no direct up-next -> done
• no direct backlog -> done
• no direct in-progress -> done
• no silent auto-transition based on vibes or time elapsed

Assignee handling in v1:

• start should set assignee to the active worker when known
• ready should set assignee to Pete
• approve does not need a schema change in v1; preserve current assignee behavior unless explicitly changed later

9.3 Canonical transition path

Add one canonical status mutation path with this behavior:

1. Accept a task identifier and a transition verb.
2. Acquire the task store lock.
3. Read the latest persisted task list.
4. Resolve the exact target task.
5. Validate the requested transition against the allowed graph.
6. Mutate only the target task fields needed for the transition.
7. Persist the updated list.
8. Re-read the saved task from disk.
9. Return success only if the persisted task matches the intended state.

This can be exposed as either:

• a new targeted API endpoint such as POST /api/tasks/:id/transition, or
• a local helper script that calls a targeted API endpoint, or both

Key design point: normal lifecycle changes must stop using raw full-array PUT /api/tasks.

9.4 UI and workflow wiring

Status changes should converge on the same backend path from all normal entry points.

9.5 Why this is the minimum durable fix

The current failure mode is not just “people forgot.” It is structural:

• lifecycle rules already exist
• status writes are still implemented as list replacement
• the UI and chat paths do not share one verified mutation path
• status vocabulary already differs across AGENTS, skill docs, and scripts

So a policy-only fix will not hold.

9.6 Prototype validation plan

Run a small live prototype on real tasks before codifying this as settled workflow.

Validation checklist for each prototype transition:

• API or helper response returns the intended task and status
• immediate read of tasks.json confirms the same status
• UI reload still shows the same status
• unrelated tasks remain unchanged
• invalid transitions fail with a clear error
• ambiguous references fail closed

9.7 Files likely touched during implementation

Primary files:

• /Users/vinny/.openclaw/workspace/AGENTS.md
• /Users/vinny/.openclaw/workspace/mission-control/lib/tasks-store.ts
• /Users/vinny/.openclaw/workspace/mission-control/app/api/tasks/route.ts
• /Users/vinny/.openclaw/workspace/mission-control/components/tasks/TasksWorkspace.tsx
• /Users/vinny/.openclaw/workspace/mission-control/scripts/capture-task.mjs
• /Users/vinny/.openclaw/workspace/skills/mission-control-task-capture/SKILL.md
• /Users/vinny/.openclaw/workspace/skills/mission-control-task-capture/scripts/capture-from-chat.mjs

Likely additions:

• targeted task transition endpoint or helper
• allowed-transition map shared by UI and API
• small transition test harness

9.8 Non-goals for v1

• redesigning the whole Mission Control board
• adding a new task schema unless the prototype proves it is necessary
• solving every possible stale-write issue for every task field on day one
• cron-based healing as the primary mechanism
• auto-creating tasks for routine chat replies

10. Context Loading

When implementing this spec, load these files first:

1. /Users/vinny/.openclaw/workspace/AGENTS.md
2. /Users/vinny/.openclaw/workspace/mission-control/lib/tasks-store.ts
3. /Users/vinny/.openclaw/workspace/mission-control/app/api/tasks/route.ts
4. /Users/vinny/.openclaw/workspace/mission-control/components/tasks/TasksWorkspace.tsx
5. /Users/vinny/.openclaw/workspace/mission-control/data/tasks.json
6. /Users/vinny/.openclaw/workspace/skills/mission-control-task-capture/SKILL.md
7. /Users/vinny/.openclaw/workspace/skills/mission-control-task-capture/scripts/capture-from-chat.mjs
8. /Users/vinny/.openclaw/workspace/mission-control/scripts/capture-task.mjs

11. Guardrails

• Use one canonical transition path for normal status changes.
• Do not report success without read-after-write verification.
• Do not guess on ambiguous title matches.
• Do not mark work done before needs-review, except for an explicit admin override path.
• Do not create Mission Control tasks for ordinary one-reply chat work.
• Do not use cron as the primary mechanism for task correctness.
• Keep the implementation small and deterministic. Prefer script/API logic over prompt-only policy.

12. Handoff

Suggested next step

Review this spec, then split implementation into one narrow build task for lifecycle transitions and one narrow cleanup task for rule and vocabulary alignment.

Recommended subtask split

Subtask 1: Implement canonical Mission Control lifecycle transitions

Suggested Mission Control task text:

Add a canonical per-task transition path for Mission Control lifecycle changes. Replace raw full-list status writes in chat workflows and UI status changes with targeted transitions that validate allowed moves, write under lock, and verify persistence before returning success.

Subtask 2: Align Mission Control task intake rules and capture vocabulary

Suggested Mission Control task text:

Update AGENTS.md and the mission-control-task-capture skill so task creation follows the new task-vs-chat rubric and uses canonical status vocabulary: backlog, up-next, in-progress, needs-review, done. Remove legacy next and blocked language from user-facing guidance.

Ready for review

Yes.