Planning Board (planning-board)

Category: boards | Form: | Symbol: Pb

Kanban-style planning board — cards serve as proto-elements for top-down design

Kanban board for project planning. Cards can serve as proto-elements: set a title (→ element name), intention (→ element intention), and requirements (→ element spec.requirements) using the same vocabulary as real elements. Decompose cards into parent/child trees, then use resolve-card to propose element types and materialize-card to create real elements. Card fields copy directly to elements — no translation. Also works as a standard kanban board with columns, phases, assignees, labels, and card references (blocked_by, blocks, related, parent).

Guide

Kanban-style planning board — cards serve as proto-elements for top-down design

What It Does

Planning-board is a Boards element: a kanban surface with columns, cards, WIP limits, typed card references, and a move-history audit trail. Cards carry the standard board fields — title, description, phase, assignees, labels, due date, story points, priority, tags — and move across columns with drag-and-drop movement that enforces per-column WIP limits.

What sets it apart from a plain board is the proto-element lifecycle. A card can capture an intention and structured requirements using the same vocabulary as real elements. These fields map directly across on materialization: title → display_name, intention → intention, requirements → spec.requirements, description → README. You decompose large cards into parent/child trees with add-ref parent, call resolve-card to have the LLM gateway propose an element type (and, for parent cards, a composition strategy), and then materialize-card to create the real element(s). Card fields copy directly to elements — no translation.

It also works as a standard kanban board: columns and phases, assignees and labels, and card references (blocked_by, blocks, related, parent). The board spec stores only its column layout; all card data (intention, requirements, resolution, element_ref) lives on the cards themselves. The board is a data element (activity_type: data), is not wirable, and its only configurable property is columns.

Element Definition

Property	Value
Type	planning-board
Category	boards
Form	atom
Symbol	Pb / #F59E0B
Workbench	workbench-board-panel
Open mode	workbench

States (runtime.states): provisioned (initial) → active → error.

Portal board chrome (portal_board_features): settings drawer and empty-column CTA are enabled; weighted forecast view and per-card activity timeline are not.

Properties

Field	Type	Default	Description
columns	array	Backlog / In Progress / Done	Kanban columns. Each column has id, name, phase (todo | in_progress | closed); optional position, wip_limit (0 = no limit), color.

Default columns: backlog (todo), in_progress (in_progress), done (closed).

Capabilities

Capability	Description
kanban	Column-based card organisation with WIP limits, card references, and move history
proto-element-lifecycle	Cards capture intention + requirements, then resolve (AI) → materialize (create real element)
intent-resolution	resolve-card proposes an element type and composition strategy from intention, requirements, and dependency graph
materialization	materialize-card creates real elements from resolved cards (title→display_name, intention→intention, requirements→spec.requirements)
card-hierarchy	Parent/child references (add-ref parent) for decomposing work into subtasks
move-history	Append-only audit trail of every card move with timestamps and actor

Attachable modifiers (contract.attaches): rate-limit, auth-policy.

Error Codes

Code	Class	Retryable	Description
PLANNING_BOARD_WIP_EXCEEDED	limit	No	Card move/create would exceed the target column’s wip_limit
PLANNING_BOARD_COLUMN_NOT_FOUND	validation	No	column_id does not match any column on this board
PLANNING_BOARD_CARD_NOT_FOUND	validation	No	Card does not exist or belongs to a different board
PLANNING_CARD_NOT_INTENT	validation	No	resolve-card: card has no intention set — cannot resolve
PLANNING_CARD_ALREADY_RESOLVED	validation	No	resolve-card: card already resolved — pass force=true
PLANNING_CARD_NOT_RESOLVED	validation	No	materialize-card: no resolution — run resolve-card first or provide override_type
PLANNING_CARD_ALREADY_MATERIALIZED	validation	No	materialize-card: card already has element_ref set
PLANNING_MATERIALIZATION_FAILED	internal	Yes	materialize-card: element creation failed — check circle quota and resolved type
PLANNING_SELF_REF	validation	No	A card cannot reference itself

Inherited board errors (boards/contract.yaml): E_BOARD_WIP_EXCEEDED, E_BOARD_COLUMN_NOT_EMPTY, E_BOARD_CIRCULAR_REF, E_BOARD_SELF_REF, E_BOARD_CARD_NOT_FOUND, E_BOARD_COLUMN_NOT_FOUND.

Operations

Auth levels are verbatim from YAML (read, write, execute, admin). Paths are relative to /api/{circle}/{slug}/ops/.

Proto-element lifecycle (planning-board only)

resolve-card

POST cards/{card_id}/resolve · auth write Proposes the most appropriate element type for an intent card by analyzing its intention, requirements, and dependency graph via the LLM gateway. For parent cards with children it also proposes a composition strategy (standalone, app, or automation). Stores the proposal in the card’s resolution field; creates no elements. Input: force (boolean, default false) to re-resolve. Output includes resolution, alternatives, and confidence (0.0–1.0).

materialize-card

POST cards/{card_id}/materialize · auth execute Creates real element(s) from a resolved card, mapping card.title → display_name, card.intention → intention, card.requirements → spec.requirements, card.description → README. Leaf cards become a single element; parent cards follow the composition strategy (standalone = each child independently; app = an app with children as members; automation = an automation with children as steps). Sets the card’s element_ref. Input: accept_resolution (default true), override_type, override_composition, target_circle, include_children (default true).

Cards (overridden to add proto-element fields)

add-card

POST cards · auth write Creates a card in a column. Requires title. Position defaults to bottom of the column; phase defaults to todo. For proto-element planning, set intention and requirements (same schema as element.spec.requirements: context, user_stories, outcomes, guidelines, dependencies, boundaries, safety). Other inputs: description, column_id, phase, position, assignees, labels, element_ref, due_date, story_points, priority, tags.

get-card

GET cards/{card_id} · auth read Returns the full card with resolved references, derived is_ready, children, and intent flags: is_intent (intention set), is_resolved (resolution set), is_materialized (element_ref set). Intent fields (intention, requirements, resolution) are included when present.

update-card

PUT cards/{card_id} · auth write Updates any combination of card fields (only provided fields change). Can set or clear (null) intention, requirements, and resolution. Use move-card to change column and reorder-card to change position.

list-cards

GET cards · auth read Lists cards with ANDed filters: column_id, phase, assignee, label, children_of, limit, offset, and a filter enum. Planning-board adds proto-element filter values: intents, unresolved, resolved, materialized (alongside ready, blocked, archived, root_only, all).

board-summary

GET summary · auth read Returns column counts, ready counts, WIP status, and phase counts, plus intent_summary (total_intents, unresolved, resolved, materialized).

Inherited board operations

These come from the boards category and are not redefined by planning-board:

Op	Method + Path	Auth	Purpose
move-card	POST cards/{card_id}/move	write	Move a card to another column (enforces WIP)
reorder-card	POST cards/{card_id}/reorder	write	Change a card’s position within its column
archive-card	POST cards/{card_id}/archive	write	Soft-remove a card from board view
unarchive-card	POST cards/{card_id}/unarchive	write	Restore an archived card
delete-card	DELETE cards/{card_id}	write	Permanently delete a card
add-ref	POST cards/{card_id}/refs	write	Add a typed reference (blocks/blocked_by/related/parent)
remove-ref	DELETE cards/{card_id}/refs/{target_card_id}	write	Remove a card reference
add-column	POST columns	write	Add a column (id, name, phase required)
update-column	PUT columns/{column_id}	write	Update column name/phase/WIP/position
remove-column	DELETE columns/{column_id}	admin	Remove a column (fails if non-archived cards remain)
add-file	POST cards/{card_id}/files	write	Attach a base64 file to a card
get-file	GET cards/{card_id}/files/{filename}	read	Download a card file
list-files	GET cards/{card_id}/files	read	List a card’s files
delete-file	DELETE cards/{card_id}/files/{filename}	write	Remove a card file
move-history	GET cards/{card_id}/moves	read	Audit trail of a card’s column moves

Quick Start

Create the board

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "planning-board",
  "slug": "roadmap",
  "name": "Product Roadmap",
  "spec": {
    "columns": [
      { "id": "backlog",     "name": "Backlog",     "phase": "todo",        "position": 0 },
      { "id": "in_progress", "name": "In Progress", "phase": "in_progress", "position": 1 },
      { "id": "done",        "name": "Done",        "phase": "closed",      "position": 2 }
    ]
  }
}

Capture an intent card

POST /api/{circle}/roadmap/ops/add-card
Content-Type: application/json

{
  "title": "Daily sales digest",
  "intention": "Summarize yesterday's sales and email the team each morning",
  "requirements": {
    "outcomes": [{ "text": "An email is sent every weekday at 08:00" }],
    "dependencies": [{ "name": "Sales DB", "type": "service" }]
  },
  "column_id": "backlog"
}

Resolve, then materialize

POST /api/{circle}/roadmap/ops/cards/{card_id}/resolve
{}

POST /api/{circle}/roadmap/ops/cards/{card_id}/materialize
Content-Type: application/json

{ "accept_resolution": true }

The response’s element_id / element_path point at the newly created element; the card’s element_ref is now set (is_materialized becomes true).

Common Mistakes

Resolving a card with no intention. resolve-card requires the card to have an intention set — otherwise it fails with PLANNING_CARD_NOT_INTENT. Set intention (and ideally requirements) on the card first via add-card or update-card.

Materializing before resolving. materialize-card needs a stored resolution. Without one it fails with PLANNING_CARD_NOT_RESOLVED — run resolve-card first, or pass override_type to materialize directly.

Re-running resolve or materialize. A card already resolved returns PLANNING_CARD_ALREADY_RESOLVED (pass force=true to re-resolve); a card already materialized returns PLANNING_CARD_ALREADY_MATERIALIZED (its element_ref is already set).

Duplicate column IDs. Column ids must be unique within the board — duplicates corrupt card routing and are rejected by validation. A board with no columns warns that you should add at least one column before creating cards.

Exceeding a column’s WIP limit. Moving or creating a card into a column at its wip_limit fails with PLANNING_BOARD_WIP_EXCEEDED. Set wip_limit: 0 on the column to remove the limit.

Relationships

• Attaches to: rate-limit, auth-policy

Capabilities

• kanban: Column-based card organisation with WIP limits, card references, and move history
• proto-element-lifecycle: Cards can serve as proto-elements: capture intention + requirements, then resolve (AI) → materialize (create real element)
• intent-resolution: resolve-card proposes an element type and composition strategy from the card’s intention, requirements, and dependency graph
• materialization: materialize-card creates real elements from resolved intent cards, mapping card fields to element fields (title→display_name, intention→intention, requirements→spec.requirements)
• card-hierarchy: Cards support parent/child references (add-ref parent) for decomposing complex work into subtasks
• move-history: Append-only audit trail of every card move with timestamps and actor

Properties

Property	Type	Default	Description
columns	array	[{"id":"backlog","name":"Backlog","phase":"todo","position":0},{"id":"in_progress","name":"In Progress","phase":"in_progress","position":1},{"id":"done","name":"Done","phase":"closed","position":2}]	Kanban columns for this planning board. Each column has a stable id, display name, and phase (todo | in_progress | closed). Optional: position, color, wip_limit. Common layouts: Backlog/Sprint/Done (scrum) or Idea/Designing/Building/Done (product planning). The add-card op accepts phase aliases (Backlog, In Progress, Done) that map to the phase enum, so columns can use human-readable names.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

add-card

Post /ops/cards | Auth: Write

Create a new card in a column

Creates a card in the specified column. Position defaults to the bottom of the column (highest position number). To add at the top, set position to 0. Phase defaults to “todo”. Column can be specified by ID, name, or phase alias (Backlog→todo, Sprint/In Progress→in_progress, Done/Review→closed). Phase also accepts friendly names. All blocked_by/blocks/related/parent references should be added separately via add-ref after creation. For top-down planning, set intention and requirements to create a proto-element card. These fields use the same schema as elements — title maps to display_name, intention maps to intention, requirements maps to spec.requirements. Use resolve-card and materialize-card to turn the card into a real element later.

add-column

Post /ops/columns | Auth: Write

Add a new column to the board

Creates a column with id, name, and phase (required). The display label field is ‘name’ (not ‘title’). Phase accepts friendly names: Backlog/To Do→todo, Sprint/In Progress→in_progress, Done/Review→closed. Use position gaps (e.g., 15 between 10 and 20) to insert between existing columns without renumbering.

add-file

Post /ops/cards/{card_id}/files | Auth: Write

Attach a file to a card

Uploads a file to the card’s CAS folder at files/{card_id}/{filename}. Content is base64-encoded in the request body. Existing files with the same name are overwritten (upsert). Creates a DB index entry for fast listing. Maximum filename length is 255 characters; path separators are rejected.

add-ref

Post /ops/cards/{card_id}/refs | Auth: Write

Add a typed reference between cards

Creates a typed edge from this card to the target. relation=blocks automatically creates the inverse blocked_by on the target card. relation=parent makes this card a child of the target. Validates against circular references (BOARD_CIRCULAR_REF) and self-references (BOARD_SELF_REF).

archive-card

Post /ops/cards/{card_id}/archive | Auth: Write

Archive a card (soft-remove from board view)

Archived cards are hidden from default list_cards results but can be queried with filter=archived. Archive rather than delete to preserve history and references. Archived cards do not block other cards.

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

board-summary

Get /ops/summary | Auth: Read

Get board summary with column counts, phase breakdown, and intent status

Returns card counts per column, ready counts per column, WIP limit status, and aggregate counts by phase (todo, in_progress, closed). Also includes intent_summary with counts of intent cards by status (unresolved, resolved, materialized). Lightweight — does not return individual cards.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

delete-card

Delete /ops/cards/{card_id} | Auth: Write

Permanently delete a card

Hard deletes a card and all its references (blocked_by, blocks, related, parent). Subcards (children) are NOT deleted — they become orphans. Prefer archive-card to preserve history.

delete-file

Delete /ops/cards/{card_id}/files/{filename} | Auth: Write

Remove a file attachment from a card

Deletes the file from CAS and removes its DB index entry. The filename is extracted from the URL path. Returns not-found if the file doesn’t exist.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get-card

Get /ops/cards/{card_id} | Auth: Read

Get full card details including resolved references

Returns the card with all fields, resolved blocked_by/blocks/related/parent references (each includes title, phase, column_id, is_ready), and derived is_ready status. Children (subcards referencing this card as parent) are also included. Intent fields (intention, requirements, resolution) are included when present. The is_intent flag is true when the card has an intention set, indicating it’s a proto-element.

get-file

Get /ops/cards/{card_id}/files/{filename} | Auth: Read

Download a file attached to a card

Returns the file content as base64 along with metadata (size, content type, upload timestamp). The filename is extracted from the URL path.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list-cards

Get /ops/cards | Auth: Read

List cards with filters

Returns cards matching the given filters. Multiple filters are ANDed. Default: returns all non-archived cards sorted by column position then card position. Use filter=ready to find actionable work (all blockers resolved, phase=todo). Use filter=children_of to get subcards.

list-files

Get /ops/cards/{card_id}/files | Auth: Read

List files attached to a card

Returns metadata for all files attached to the card. Reads from the DB index table for fast listing without walking the CAS tree.

materialize-card

Post /ops/cards/{card_id}/materialize | Auth: Execute

Create element(s) from a resolved intent card

Creates concrete elements from the card’s resolution, mapping card fields directly to element fields:

card.title → element display_name card.intention → element intention card.requirements → element spec.requirements card.description → element README

For leaf cards (no children), creates a single element of the resolved type. For parent cards, the composition strategy determines behavior:

standalone — each child materialized independently, no container app — creates an app, materializes children as members, card blocks/blocked_by → app connections automation — creates an automation, materializes children as steps, card blocks/blocked_by → step depends_on edges

Each created element starts in draft state with the definition gate already satisfied (title + intention are set). The card’s element_ref is set to the created element’s ID. Child cards’ element_refs are set to their respective elements. Override the resolved type with override_type if the agent’s proposal doesn’t match your intent. Override composition with override_composition for parent cards.

move-card

Post /ops/cards/{card_id}/move | Auth: Write

Move a card to a different column

Moves the card to the target column. Column can be specified by ID, name, or phase alias (Backlog, In Progress, Done, etc.). Position defaults to bottom of the target column. This is tracked in the move history audit trail. Enforces WIP limits on the target column — fails with BOARD_WIP_EXCEEDED if the limit would be breached. Emits board.card.moved NATS event.

move-history

Get /ops/cards/{card_id}/moves | Auth: Read

Get the move history for a card

Returns the audit trail of column transitions for this card. Each entry includes from_column, to_column, moved_by (actor slug), and timestamp. Ordered newest first.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-column

Delete /ops/columns/{column_id} | Auth: Admin

Remove a column from the board

Fails with BOARD_COLUMN_NOT_EMPTY if the column has non-archived cards. Archive or move all cards first. The column’s position gap remains available for reuse.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

remove-ref

Delete /ops/cards/{card_id}/refs/{target_card_id} | Auth: Write

Remove a reference between cards

Removes the reference from this card to the target. If the reference has an inverse (blocks/blocked_by), the inverse is also removed.

reorder-card

Post /ops/cards/{card_id}/reorder | Auth: Write

Change a card’s position within its current column

Changes vertical position (priority) without changing column. Position 0 is the top (highest priority). Other cards in the column are renumbered automatically to maintain order.

resolve-card

Post /ops/cards/{card_id}/resolve | Auth: Write

Propose an element type for an intent card based on its requirements

Analyzes the card’s intention, requirements, and constraints to propose the most appropriate element type. Uses the LLM gateway to match the card’s needs against the element catalog. For parent cards with children, also proposes a composition strategy (standalone, app, or automation). The proposal is stored in the card’s resolution field for review before materialization. The agent considers: user_stories and outcomes (what it should do), guidelines and boundaries (technical constraints), dependencies (what it needs), and the card’s relationship graph (parent/child structure, blocking dependencies). Sequential dependencies suggest automation; loosely coupled children suggest app; single leaf suggests standalone. Does not create any elements — only proposes. Use materialize-card to act on the proposal. Set force=true to re-resolve a card that already has a resolution.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

unarchive-card

Post /ops/cards/{card_id}/unarchive | Auth: Write

Restore an archived card to the board

Restores an archived card, making it visible again in default list-cards results. The card retains all its fields and references. Position defaults to the bottom of the card’s original column.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update-card

Put /ops/cards/{card_id} | Auth: Write

Update card fields

Updates any combination of card fields. Only provided fields are updated — omitted fields remain unchanged. Phase accepts friendly names (Backlog, In Progress, Done, etc.). To change column use move-card. To change position use reorder-card. To manage references use add-ref/remove-ref. The intention and requirements fields follow the same schema as elements — when this card is materialized into an element, these fields copy directly across.

update-column

Put /ops/columns/{column_id} | Auth: Write

Update column name, phase, WIP limit, or position

Updates column properties. Changing phase does NOT change the phase of cards in the column — card phase is independent. Only provided fields are updated. Set wip_limit to 0 to remove the limit.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
PLANNING_BOARD_WIP_EXCEEDED	limit	no	Card move or create would exceed the target column’s wip_limit
PLANNING_BOARD_COLUMN_NOT_FOUND	validation	no	column_id does not match any column on this planning board
PLANNING_BOARD_CARD_NOT_FOUND	validation	no	Card does not exist or belongs to a different board
PLANNING_CARD_NOT_INTENT	validation	no	resolve-card: card has no intention field set — cannot resolve a card without intent
PLANNING_CARD_ALREADY_RESOLVED	validation	no	resolve-card: card already has a resolution — pass force=true to re-resolve
PLANNING_CARD_NOT_RESOLVED	validation	no	materialize-card: card has no resolution — run resolve-card first or provide override_type
PLANNING_CARD_ALREADY_MATERIALIZED	validation	no	materialize-card: card already has element_ref set — element was already created
PLANNING_MATERIALIZATION_FAILED	internal	yes	materialize-card: element creation failed — check the circle’s quota and the resolved element type
PLANNING_SELF_REF	validation	no	A card cannot reference itself