CCCC Context Ops Contract v3
Status: Active (Context v3 in the native CCCC workspace)
This document defines the operation list and payload shapes for daemon IPC:
context_sync(seedocs/standards/CCCC_DAEMON_IPC_V1.md)
The goal is to make context_sync usable from SDKs and MCP/Web ports without reading daemon source code.
0. Conformance Language
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.
1. Overview
context_sync applies a batch of small operations to a group's context v3 storage:
coordination= shared control plane (brief)tasks= shared dispatch truthagent_states= per-actor short-term working memorymeta= restricted projection-support metadata
Read-only projections such as board and attention are daemon-computed and are not directly writable via context ops.
All operations are applied in order. Each operation is authorized against the in-memory result of the preceding operations under the Context storage lock. If any operation is invalid or unauthorized, the daemon rejects the entire batch before writing payload files. Task IDs used for authorization MUST match the IDs used by the corresponding operation, including accepted whitespace.
Canonical Context files that are unreadable, malformed, or contain inconsistent identity metadata MUST cause an explicit error; they MUST NOT be interpreted as empty state and overwritten by a later update. Missing files still support new Groups and the documented legacy migration path.
Context uses atomic replacement of individual files, not a multi-file database transaction. A storage failure can leave part of a validated batch written. The revision is reserved before payload writes so such a failure invalidates prior if_version tokens. After an I/O error, callers MUST reload the current state before deciding what to retry; a newer revision alone is not a success receipt. Dry runs and rejected batches do not reserve a revision.
New task records are written in their ordered creation sequence before updates to previously stored tasks. Creation references resolve to earlier tasks, so a new reference target is durable before the create that names it. This ordering also applies across task-number digit widths; lexical filename order MUST NOT let a dependent create survive alone and replay stale references on retry.
Task numbers are durable identities within a Group. Deleting a task, including its unexecuted descendants, MUST NOT make a reserved number available for a later task. The existing Context version record retains the allocation high-water mark and reserves newly allocated numbers before payload writes. This forward guarantee starts with the persisted allocation record; task numbers already deleted before that record existed cannot be reconstructed from current task files. A partial storage failure may leave gaps; it MUST NOT allow a deleted or reserved ID to identify different work. Dry runs and rejected batches do not consume numbers.
Legacy migration MUST preserve existing references whose targets were present in canonical storage before migration, even when a legacy task with the same ID is imported under a new number. Matching the referencing task's identity does not prove its references are legacy. Newly imported tasks use the legacy ID mapping. Recovery of missing references requires a proven task identity and reference mapping; ambiguous recovery MUST fail before changing existing files or recording migration success.
context_sync only mutates the Context v3 stores named by its operations. It MUST NOT implicitly write the separate legacy Group memory files.
2. Operation Item Shape
Each item in args.ops MUST be a JSON object with:
type ContextOpV3 = { op: string } & Record<string, unknown>Rules:
opMUST be one of the strings listed in §3.- Unknown
opvalues MUST be rejected. - Unknown fields MAY be ignored unless an op explicitly forbids them.
3. Operation List
3.1 Coordination
coordination.brief.update
{
op: "coordination.brief.update"
objective?: string
current_focus?: string
constraints?: string[]
project_brief?: string
project_brief_stale?: boolean
}Permission: foreman or user.
Notes:
- Partial patch: only provided fields are updated. A provided
constraintsreplaces the whole list. - Daemon sets
updated_byandupdated_atautomatically. project_brief_staleis a manual marker that only the foreman or user sets. It refers toproject_briefand defaults to false; false does not show that the brief is current.- MCP
cccc_bootstraprecovery returns the brief's ownupdated_atascoordination_brief.updated_atwhen it exists, and omits it otherwise. It is the time of the last brief update, whichever fields that update provided, includingconstraintsalone; it is not a check that the content is current. Other Context writes do not change it.
Coordination notes (coordination.note.add, stored as recent_decisions and recent_handoffs) were removed; the op is rejected as unknown. Notes an older context file already holds stay in that file unchanged and are never returned.
3.2 Tasks
Task statuses:
type TaskStatus = "planned" | "active" | "done" | "archived"Checklist statuses:
type ChecklistStatus = "pending" | "in_progress" | "done"Waiting values:
type TaskWaitingOn = "none" | "user" | "actor" | "external"Task type values:
type TaskType =
| "free"
| "standard"
| "optimization"Task source references are optional metadata:
type BacklogSource = { scope_key: string; path: string; entry_id: string }path MUST be a normalized workspace-relative path without traversal. entry_id MUST contain exactly 12 lowercase hexadecimal characters. scope_key MUST be nonempty. Other source fields are rejected. A source reference does not grant file access, read the file, or write backlog content. The referenced file or entry may later disappear; clients MUST show a missing source rather than silently matching another entry by title.
ever_executed is daemon-owned, monotonic execution history. Entering active or done through create, move, or restore records it; clients cannot set or clear it. Returning to planned does not make executed work deletable. Older records which had already returned to planned before this marker existed have no reconstructible execution history; no history is invented for them.
Reads of tasks with a nonempty blocked_by include read-only open_blocked_by: the stored blocked_by subset whose referenced tasks are not completed. A dependency is completed only in done, or archived with archived_from=done. Archiving unfinished work, or an archive without a known prior status, does not release its dependents. Missing references remain unresolved. This is computed from the full task snapshot before filtering or paging; completing a dependency does not rewrite the dependent task or its revision, and reopening it makes it block again. Explicit waiting_on=actor or external remains blocked independently. Clients MUST edit blocked_by, not this projection; task.create and task.update ignore open_blocked_by input.
Every task read exposes a daemon-owned unsigned rev. Existing task files with no stored revision read as rev: 0 without being rewritten; new tasks start at rev: 1. A semantic task change advances its revision once per operation, including tasks changed indirectly. rev and the derived updated_at timestamp are excluded when detecting an identical patch, which retains both values. Revision overflow is rejected before persistence. Clients MUST NOT set rev.
Every operation targeting an existing task MAY include if_task_rev: number. The guard is checked under the Context lock against that operation's preceding in-memory result. A mismatch rejects the entire batch with task_conflict and details {task_id, expected, actual}. Unrelated task or agent-state writes do not invalidate this guard. A supplied whole-context if_version still applies independently and is checked first. Invalid guards (including null, negative, fractional and string values) are rejected. Dry runs validate/project revisions without writing. After any I/O failure reload the task before retrying; task files atomically contain their content and revision, but the Context file batch is not a multi-file transaction. A delete guard covers its named root, not independent revisions of every descendant.
task.create has no existing task revision and rejects if_task_rev; retry identity is separate from revision fencing. Task ID non-reuse prevents a deleted task's token from referring to later work. Direct file editors must coordinate with the Context writer and maintain revisions; this API cannot fence edits that bypass its storage lock and metadata.
task.create
{
op: "task.create"
title: string
outcome?: string
status?: TaskStatus
parent_id?: string | null
assignee?: string | null
priority?: string
blocked_by?: string[]
waiting_on?: TaskWaitingOn
handoff_to?: string | null
task_type?: TaskType
notes?: string
checklist?: Array<{ id?: string; text: string; status?: ChecklistStatus }>
source?: BacklogSource | null
client_request_id?: string
parent_ref?: string
blocked_by_refs?: string[]
}Permission: any actor.
Rules:
titleis required.sourceis optional. A null source has no association; non-null references are validated as described above. This operation never changes the source file.- The daemon assigns the next unused
T<number>ID. Clients MUST use the assigned ID from authoritative task reads, or from the operation's change entry (task_id, see §6), rather than infer it from the current task count. - If
parent_idis provided, the parent task MUST exist. client_request_idis the caller's own id for the task and is stored on it. If the same caller (by) already created a task with thatclient_request_id, the operation creates nothing and its change entry names the existing task withreplayed: true. The operation's other fields are not compared or applied. A deleted task no longer reserves itsclient_request_id.parent_refnames the parent by theclient_request_idof a task the same caller created, earlier in the same batch or before it. It MUST NOT be combined withparent_id. Eachblocked_by_refsentry is resolved the same way and appended toblocked_by. A ref that names no such task MUST reject the batch. Onecontext_synccan then create a whole tree, validated as a whole; a retry of that batch, after a lost reply or a storage failure, returns the tasks already written and creates only the missing ones.- Peer actors MUST NOT create a task assigned to another peer.
- If
task_typeis provided, it MUST be one of the allowed task-type ids above. - If
task_typeis omitted, the daemon MUST persiststandardfor a root task andfreefor a subtask. task_typestores the durable work kind. It MUST NOT be treated as lifecycle state or parent/child structure.task_typedoes not auto-seednotesorchecklist; those remain ordinary editable task content.
task.update
{
op: "task.update"
task_id: string
if_task_rev?: number // unsigned revision from the task read
title?: string
outcome?: string
parent_id?: string | null
assignee?: string | null
priority?: string
blocked_by?: string[]
waiting_on?: TaskWaitingOn
handoff_to?: string | null
task_type?: TaskType
notes?: string
checklist?: Array<{ id?: string; text: string; status?: ChecklistStatus }>
source?: BacklogSource | null
}Permission: assignee / handoff target / foreman / user. A peer MAY also claim a planned or active task that has neither an assignee nor a handoff target by setting assignee to itself in this update.
Omitted source preserves the existing association; null removes it. Setting a source follows the same task authorization and revision guard as other fields.
Rules:
- Partial patch: omitted editable fields stay unchanged, and each provided field replaces its stored value whole.
notesis not appended to, andchecklistis not merged item by item. - If
parent_idchanges, the daemon MUST reject cycles. task.updatedoes not change lifecycle status.- If
task_typeis provided, it MUST be one of the allowed task-type ids above.
task.move
{
op: "task.move"
task_id: string
if_task_rev?: number // unsigned revision from the task read
status: TaskStatus
}Permission: assignee / handoff target / foreman / user.
Notes:
- This is the canonical lifecycle transition op.
task.moveonly acceptstask_id,statusand optionalif_task_rev. Fields such asoutcome,notes,checklist, ortask_typeMUST go throughtask.update.- Moving to
archivedrecordsarchived_from. - This operation changes only task lifecycle state. It does not implicitly rewrite an assignee's
agent_stateor append daily/stable memory.
task.restore
{ op: "task.restore"; task_id: string; if_task_rev?: number }Permission: assignee / handoff target / foreman / user.
Rules:
- The task MUST currently be archived.
task.delete
{ op: "task.delete"; task_id: string; if_task_rev?: number }Permission: assignee / handoff target / foreman / user. A peer MUST be the assignee or handoff target of every task in the affected subtree; otherwise the entire batch is rejected before reserving a revision or writing any state.
Rules:
- This operation is for removing work that never entered execution, not for erasing task history.
- The target task and every descendant MUST be
planned, orarchiveddirectly fromplanned. - If the target or any descendant has execution history, the entire operation MUST be rejected.
- A successful delete removes the complete target subtree atomically.
- Task deletion does not implicitly rewrite actor-owned
agent_state; an actor or the localuserrecovery authority may reconcile stale working-state hints explicitly.
3.3 Agent State
Agent states are keyed by actor_id.
Agent state is actor-owned short-term working context. Task and coordination operations MUST NOT implicitly update or clear it. Normal writes are explicit self-writes through the operations below; the local user principal remains the recovery authority described in §4.
agent_state.update
{
op: "agent_state.update"
actor_id: string
active_task_id?: string | null
focus?: string
blockers?: string[]
next_action?: string
what_changed?: string
open_loops?: string[]
commitments?: string[]
environment_summary?: string
user_model?: string
persona_notes?: string
}Permission: self / user.
Notes:
- Partial patch.
- Daemon stores data into
hot(active_task_id,focus,blockers,next_action) andwarm(the rest). open_loopsis the current memo for unfinished work, unresolved facts, risks, assumptions, and follow-ups.commitmentsrecords promises made to users or other actors.agent_stateis actor-owned working state. Foreman should guide peers via tasks, coordination, or help/role-notes, not by directly rewriting a peer'sagent_state.resume_hintis not part of this contract; clients must useopen_loopsfor current memo entries.- Legacy aliases
agent_id,environment,user_profile, andnotesare tolerated by daemon but SHOULD NOT be used by new clients.
agent_state.clear
{ op: "agent_state.clear"; actor_id: string }Permission: self / user.
Notes:
- Clears both
hotandwarm, then refreshesupdated_at. - The stored entry can remain after its Actor is removed. Context read projections MUST omit states whose Actor ID is no longer in the Group's Actor list, including entries left by earlier removals. Disabled or stopped Actors still in that list remain eligible; clearing state does not itself change membership.
3.4 Restricted Meta
meta.merge
{
op: "meta.merge"
data: {
project_status?: string | null
}
}Permission: foreman or user.
Rules:
- Only
project_statusis allowed. - Resulting
metapayload MUST stay within daemon size limits.
4. Optimistic Concurrency (CAS)
context_sync accepts an optional if_version field:
{ group_id: string; ops: [...]; if_version?: string }Rules:
- If
if_versionis provided and does not match the current context version hash, the entire batch MUST be rejected with error codeversion_conflict. - If
if_versionis omitted, no version check is performed.
5. Dry Run
If context_sync.args.dry_run == true, the daemon MUST NOT persist changes and SHOULD still return a computed changes list.
6. Result Notes
context_sync returns changes: Array<{ index, op, detail }> where detail is intended for logs/UI. SDKs SHOULD NOT parse detail as a stable machine contract.
A task.create entry also carries task_id: the task the operation created or, for a replayed client_request_id, the existing task, with replayed: true.
A Foreman's write that holds a task operation also carries review_reminder: string once at least 10 top-level tasks have been finished since the last reminder. The daemon adds every write's newly finished top-level tasks, by anyone, to meta.finished_since_review_reminder and restarts it in the write that returns the reminder, so the Foreman hears it once. Archiving or deleting tasks leaves the count alone, and meta.merge cannot set that key. A dry run returns no reminder and records nothing. While skill:cccc:self-evolution is blocked, removed, disabled or hidden for that Foreman, a due reminder is dropped and the count restarts.
When Group Space is enabled and a curated context change is detected, the daemon MAY also return:
space_sync?: {
queued: boolean
reason?: "not_bound" | "binding_inactive" | "missing_remote_space_id" | "provider_disabled" | "enqueue_failed"
deduped?: boolean
job_id?: string
provider?: "notebooklm"
kind?: "context_sync"
idempotency_key?: string
error?: string
}Curated trigger allowlist:
coordination.*task.*
agent_state.* updates do not trigger Group Space export.
7. Permission Model
| Role | Allowed ops |
|---|---|
user | All ops |
foreman | All ops except changing another actor's agent_state |
peer | task.create, task.update (own assigned / handed-off), task.move (own assigned / handed-off), task.restore (own assigned / handed-off), task.delete (own assigned / handed-off), agent_state.update (self), agent_state.clear (self) |
Permission checks use context_sync.args.by.