Tasks

The unified Quest model — tasks, proposals, events, offers, and requests under one shape

The Tasks domain in @holons/core/tasks is the most-used part of the system. It implements the Quest model: a single shape that covers tasks, proposals, events, offers, and requests, with the same lifecycle—create, accept participants, complete, recognize—applied uniformly.

A user opening the Telegram bot and typing /task do the dishes and a Claude agent calling the MCP task_create tool are doing exactly the same thing: producing a Quest in the holon's tasks lens.

Why "Quest" and not "Task"

Early on the system distinguished tasks, proposals, events, offers, and requests as separate types. They had different shapes, different lifecycle hooks, different UIs. The cost was significant: every new feature had to be replicated four times, every UI had four separate views, every aggregator special-cased on type.

The Quest model unifies them. They are still conceptually distinct (a type field still records what kind of work this is), but the data shape, persistence path, and operation surface are identical. The benefit is concrete: implementing appreciation, completion tracking, federation, or REA-event emission once covers all five.

The Quest shape

interface Quest {
  id?: string | number;
  title: string;
  description?: string;

  status: 'ongoing' | 'completed' | 'cancelled' | 'scheduled'
        | 'recurring' | 'repeating' | 'pending' | 'stopped' | string;
  type?: 'task' | 'quest' | 'event' | 'proposal' | 'recurring' | string;
  category?: string;

  // Schedule
  when?: string;     // ISO timestamp
  ends?: string;
  location?: string;

  // People
  participants: QuestParticipant[];
  appreciation?: any[];

  // Provenance
  created?: string;            // ISO from web
  date?: number;               // ms epoch from Telegram
  initiator?: QuestInitiator;

  // Ordering / dependencies (used by quest-tree / council pipelines)
  orderIndex?: number;
  dependsOn?: string[];

  _meta?: QuestMeta;
  _deleted?: boolean;

  // Open shape so existing call sites read/write extra fields safely
  [key: string]: any;
}

The shape is deliberately open: extra fields are preserved across writes. This is what let the unification happen without forcing every UI to give up data it cared about. The Telegram bot still writes message_thread_id, stoppers, dependencies, frequency, timeTracking; the web app still writes its richer schedule fields; both continue to work.

Schedule fields (when, ends, location) come from the web side. Telegram-side metadata sits alongside under the open index. A Quest written by either UI is fully readable by both.

Special quest forms

Two structures wrap the Quest model for higher-order workflows:

QuestTree (recursive backcasting)

A directed graph of nested quests, used by the AI council backcasting flow. Each node is a quest that is both a parent (of finer-grained sub-quests) and a child (of a coarser vision-level goal). The root captures the long-term vision; leaves are immediately-actionable steps.

interface QuestTree {
  vision: { statement, principles, targetDate?, successIndicators };
  nodes: Record<string, QuestTreeNode>;
  rootNodeIds: string[];
  maxGenerations: number;
  branchingFactor: number;
  headAdvisor: string;
  resourceFlows?: Array<{ fromNodeId, toNodeId, resourceType, description }>;
}

Each node carries holonic metadata—skills required, resources required, impact category (ecological / social / economic / spiritual / technical), success metrics, future state—so a generated tree captures not just the work but the reasoning behind it.

RitualSession → design streams

A ritual session produces a wish_statement, declared_values, a panel of advisors (real / mythic / archetype), and a set of design streams. createTasksFromDesignStreams() turns each stream into a Quest, preserving the link back to the ritual that birthed it.

This is how the system bridges practice (ceremony, ritual) and execution (tasks): the practice produces an artifact; the artifact decomposes into the work.

Operations

Grouped by file:

Creation (creation.ts)

Function	Purpose
createDefaultTask(input)	Construct a Quest with sensible defaults
createTaskFromStep(step, ctx)	Make a Quest from a design-stream step
createTasksFromDesignStreams(session)	Bulk-create from a RitualSession
createTasksFromQuestTree(tree)	Bulk-create from a QuestTree
createTaskRecord(input)	Lowest-level constructor — pure

Constants: COUNCIL_INITIATOR, DEFAULT_TASK_CATEGORY.

Participants (participants.ts) — all pure, all return a new Quest:

Function	Purpose
addParticipant(task, user)	Join
removeParticipant(task, userId)	Leave
toggleParticipant(task, user)	Convenience toggle
addAppreciation(task, user)	Recognize a contribution
removeAppreciation(task, userId)	Undo
toggleAppreciation(task, user)	Convenience toggle

Completion (completion.ts, completion-plan.ts, completion-execute.ts)

Function	Purpose
applyTaskCompletion(task)	Pure: mark a Quest completed
planTaskCompletion(task, ctx)	Compute the side effects of completion (REA events, scoring deltas, dependency cascades)
executeCompletionPlan(plan, deps)	Run the planned side effects

The plan/execute split lets a caller preview what completing a Quest will do—what events get emitted, who gets points, which dependent quests unblock—before actually applying it. The MCP server exposes both halves as separate tools so an agent can confirm before committing.

Persistence (persistence.ts)

Function	Purpose
saveTaskToHolon(holosphere, holonId, task)	Persist a single Quest
saveTasksToHolon(holosphere, holonId, tasks[])	Persist multiple

The HoloSphere interface required is minimal (HoloSphereLike)—just put and optionally get—so the persistence layer is testable with simple in-memory mocks.

Lifecycle in one picture

   createDefaultTask / createTaskFromStep
              │
              ▼
       Quest in memory
              │
              ▼          ┌─────────────────────┐
   addParticipant ─────► │  Quest in memory    │ ◄───── addAppreciation
   toggleParticipant     │  (pure updates)     │        toggleAppreciation
                         └──────────┬──────────┘
                                    │
                                    ▼
                          saveTaskToHolon
                                    │
                                    ▼
                          Quest in HoloSphere
                                    │
                                    ▼
                          planTaskCompletion
                                    │
                                    ▼
                          executeCompletionPlan
                                    │
                                    ▼
                          REA events + score updates +
                          dependency cascade

Every step except the persistence and execute calls is pure—so live previews (the web dashboard showing "if you complete this, you and Laura each get 2 points") are cheap.

MCP tool surface

The MCP server exposes 10 tools in the tasks domain — the full lifecycle (create, save, participants, appreciation, plan, complete) plus reads. An agent connected via MCP can drive any quest from creation to completion entirely through tool calls.

See also

• Council — proposals are a Quest type with extra voting machinery

• Scoring — how completed quests and appreciations turn into points

• REA Accounting — the event ledger that records the side effects of completion

• HolonsBot — the most-used Quest interface