Generated from cat-harness/work-plan/skills/work-plan/work-plan-store.md — do not edit here.

✎ Edit this page’s source

The work plan’s contract

The work plan is a data store, and this is its contract. work-plan in scenarios/roles.json is a mechanical Role with a store block: what it holds, and how it is reached. This skill is the other half, what it must do. How an agent USES the plan is todo-manager; this file says what the plan promises back.

This contract names no Tool. A process or skill that touches the work plan says which operation below it performs (“note the bean”, “claim it”), never which command does it. How one Tool performs an operation belongs on that Tool’s page, listed in §”Tools”. The Tool in use is chosen by the deployment description, per checkout.

A diagram draws the store as a data store, never a lane: a dataStoreReference with dataStoreRef="work-plan", declared once in processes/global-tasks.bpmn. A task that opens or closes a work item writes to it with a dataOutputAssociation; a task that reads the plan has a dataInputAssociation from it. The task sits in the lane of whoever does it.

What it holds

KindWhat
bean-defswork items ($schema: bean/1.0.0), shaped by schemas/kinds/bean-defs.schema.json
bean-notesaddenda to a work item, one per writer, never rewritten
workflow-staterunning and finished BPMN instances (folio-workflow-instance/v1)

Operations

Every Tool provides these. Each line says what a caller can rely on.

OperationGuarantee
get(id)the work item as last written, or “none”. A short id resolves to exactly one work item or to none
list(filter)work items by status, type, tag or parent; archived work items only when the filter asks for them
create(bean)the id is unique; the work item is readable by get once create returns
update(id, change, ifMatch)refused when ifMatch names a version that is no longer current; a retry on the current version lands. archived: true archives the work item
note(id, text, by)appended to the work item’s notes, never rewriting earlier ones
history(id)every change to the work item, oldest first: when, by whom, what changed, and which process step made it when one did
positions(id)every workflow instance that names the work item: process, step(s), instance status, last move
beansAt(process, step?)the work items with a token at that process (and step)

Archiving is a field, not an operation. update(id, { archived: true }, ifMatch) is refused unless the work item is completed or scrapped, and the work item keeps its status. get still finds an archived work item; list leaves it out unless asked. Where an archived work item lives is the Tool’s choice, stated on its page.

A work item’s position lives only in the workflow instances. The work item records no process or step of its own; positions and beansAt read the instances the store holds. A tag such as process:code-change-review may label a work item for people, and is never read as its position.

Responsibilities

Each line is something a test can check against any Tool.

  1. Give back what was written. get after create or update returns, byte for byte, the work item written.
  2. Keep ids unique. No two work items share an id.
  3. Keep links whole. parent, blocking and blocked_by name work items that exist.
  4. Keep the lists closed. status and type take only the values the schema declares.
  5. Lose nothing to a race. Two writers at once both land: the second update with a stale ifMatch is refused, retried on the current version, and lands. Nothing is overwritten unread.
  6. Keep the history. history(id) answers who changed what and when, and which process step did it.
  7. Archive only what is finished. archived: true on a work item that is not completed or scrapped is refused.
  8. Know where a work item is. positions and beansAt agree with the instances the store holds.

Tools

ToolBacked byPage
git state brancha branch per graph (cat/<harness>/beans), mounted at beans/, written with the beans CLI (beans-cli) or by hand (beans-manual), read with bean-querywork-plan-store-git-branch
work items serverbeans-serve GraphQL (schema); its mutations already take ifMatchproposed
MCP servicean MCP server over the same operationsproposed
run-scoped storein memory or a scratch branch, one per benchmark run, never the real plan (req:model-benchmark)proposed

Tests

The conformance suite lives in the tools layer (scripts/tests/sdlc/work-plan-store-conformance.ts, one describe per responsibility above) and runs against both of the git Tool’s access modes. Until this file carries a tested-by: line, kg-audit reports this role as mechanical-role-untested.

Not its responsibility

Deciding what to work on, who claims a work item, or whether work is done. Those are judgements made in the lanes of the people and agents who read and write the plan.


Provenance (6)

Who decided, when, and under which work item. This record was moved out of the text of the page.

The work plan's contract

  • owner-decision owner Q-DS-1 Q-DS-2 2026-11-01
    (owner, 2026-11-01, Q-DS-1 A and Q-DS-2 A).
  • owner-decision owner cat-harness#991 Q-BSD-2 2026-11-02
    (owner, 2026-11-02, cat-harness#991). The Tool in use is chosen by the deployment description, per checkout (Q-BSD-2 A).
  • proposal Q-BR-3
    A diagram draws the store as a data store, never a lane (Q-BR-3 A): a dataStoreReference with dataStoreRef="work-plan", declared once in [processes/global-tasks.bpmn](../../../processes/global-tasks.bpmn).

Operations

  • owner-decision owner Q-BSD-7 2026-11-02
    (owner, 2026-11-02, Q-BSD-7 B).
  • owner-decision owner Q-BSD-1 2026-11-02
    (owner, 2026-11-02, Q-BSD-1 B).

Tools

  • issue cat-harness#991 Q-BSD-5
    | | beans server | beans-serve GraphQL ([schema](https://github.com/litlfred/beans/blob/main/internal/graph/schema.graphqls)); its mutations already take ifMatch | proposed, cat-harness#991 | | MCP service | an MCP server over the same operations | proposed, cat-harness#991 | | run-scoped store | in memory or a scratch branch, one per benchmark run, never the real plan (req:model-benchmark) | proposed, cat-harness#991 (Q-BSD-5 A)

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev