Models

Key Ideas

• Goal: the smallest useful unit of work, framed as the difference between what exists and what should exist.
• Feature: an organized set of Goals that together produce a larger product outcome.
• Workflow State: the current position of a Goal in the system’s work lifecycle.
• Node: the local or distributed actor that owns active work.
• Projection: a fast, queryable view over durable flat-file state.
• Plain Objects: model data should stay simple enough for people and agents to read directly.

Purpose

Models give Refine a shared language for software work. They let Application behavior, Infrastructure mechanisms, people, agents, and Surfaces agree on what exists without depending on one screen or command.

The central product model is the Goal. A Goal records an actionable prompt, notes, rounds, status, priority, reporter, assignee, Feature membership, node ownership, and logs needed to understand and advance work. The model is intentionally ordinary: it should be possible to open the file, read it, and understand what the work is.

Features exist to preserve intent across multiple Goals. A Feature should not replace the Goal model; it groups Goals, preserves ordering when order matters, and lets the system explain larger outcomes without losing the smaller work units that agents can execute.

Expected Role

Models should be the stable center of the system. Surfaces may rename controls, Application workflows may gain new steps, and Infrastructure may change providers or storage mechanisms, but the Model should preserve the meaning of work.

Current implementation details that matter to intent:

• Goal and Feature are explicit Rust model types.
• Goal statuses are named workflow states: backlog, todo, plan, implement, quality, governance, review, done, failed, and cancelled. Legacy status names are accepted only while reading or migrating older records.
• Goals can belong to Features with a linear integer order. For Goals assigned to the same node, that order is a hard completion barrier: the next Goal waits until its predecessor reaches review, done, or cancelled, and failure keeps later ordered Goals blocked.
• Priority is a hard same-node start gate, not a hint. A lower-priority authored Todo is ineligible while a higher-priority authored and Feature-eligible Todo or automated-active Goal remains in todo, plan, implement, quality, or governance; runner-active Todo work still holds the gate.
• Linear Feature order plus priority is the canonical dependency model. “After X” and imported depends_on compile to Feature order by design; there is deliberately no separate dependency DAG or blocked-by graph.
• Ordering and priority are currently enforced per node. Until intended global enforcement is available, users must pin work that needs one enforced sequence to the same node.
• Active work is owned by a node so distributed or multi-instance operation can be reasoned about explicitly.
• Projections exist so the system can stay fast without replacing flat files as the source of truth.
• Scheduler indexes should scale with active work rather than total project history. Read projections should keep a bounded per-record working set and load deep searchable text only when a query needs it.
• A Goal Round may carry a versioned implementation_plan. It binds proposal, independent criticism, final checklist, phase/process/Git evidence, failures, and implementation discrepancies to the exact Round, pinned context digest, Goal/Round context, implementation and target branches, and base commit. The proposal and final plan remain human-readable: one plain-language, top-down, single-line summary explaining what will change and why, followed by any number of stable, one-line checklist items that clearly advance that plan and capture concerns that cannot safely be ignored. Detailed verification belongs to execution evidence. Missing planning evidence remains valid for legacy records.

Future model changes should preserve these properties: human readability, agent readability, stable workflow meaning, and clear node ownership for active work.

Future Direction

As AI agents improve, models should become more expressive without becoming more obscure. Refine may need richer representations of design intent, quality evidence, governance decisions, agent capabilities, review provenance, and composition plans while preserving linear Feature order plus priority as the dependency model.

The direction should be toward a model that a superintelligent software system can use to compose large systems from many smaller changes while still leaving people an understandable audit trail. New model fields should answer real questions: what is the work, why does it matter, which node owns active progress, what evidence supports it, what can safely happen next, and what changed as a result.