Zachary F. Mainen · HAAK · Architecture 39 · March 2026

Engagement State — The Third Externalization

HAAK externalizes along three axes. Two are built: the domain axis has boards and indices (what happened here, what exists here), and the actor axis has trace (designed in Architecture 20, partially…

#1. The gap

HAAK externalizes along three axes. Two are built: the domain axis has boards and indices (what happened here, what exists here), and the actor axis has trace (designed in Architecture 20, partially built). The method axis — engagement state — is named in Foundation 07, referenced in Architecture 20, but has no implementation. This document provides it.

The problem is concrete. When a method is invoked — a review, a filesystem reorganization, a paper submission pipeline — there is no persistent record of where that particular execution stands. The method-type exists as a document in patterns/methods/. The method-token — this review of this paper, at this phase, with these participants — exists only in the context windows of agents currently working on it, in scattered board entries, and in the user's memory.

When a session ends and a new one begins, the fresh agent faces an archaeological problem. It reads the board, scans file dates, infers from directory contents, and asks the user. Each source is incomplete. The board records events but not phase position. File dates record when something was last touched but not what step it was for. The user remembers the trajectory but cannot be queried programmatically by other agents. The result is that multi-session engagements — which are the norm for any serious work — degrade with each session boundary. Each handoff loses information. Each reconstruction takes time that could be spent on the work itself.

Foundation 07 identifies the three externalizations as the solution to the reconstruction problem: traces for actors, boards+indices for domains, engagement state for methods. The claim is that these three, together, are sufficient for any fresh agent to reconstruct the system's state. Two legs of this tripod are built. The third is missing. Until it exists, the reconstruction property is untestable.

#2. Formal definitions

The relational situational ontology provides the ground. An engagement is already defined in the ontology (Definition 13 of [[01-objects]]) as a normative token-compound — the intentional, goal-directed view of a particular instance of action. What follows formalizes the internal structure of engagements and the mechanism by which that structure is externalized.

Definition 1 (Phase Graph). A phase graph G = (V, E, v0, F) where V is a finite set of phases, E is a set of directed transitions (v, v') with each transition carrying an enabling condition c{v,v'}, v_0 in V is the initial phase, and F is a subset of V containing the terminal phases. The phase graph is a property of the method-type — it defines the normative structure of all engagements of that type. It is the method-type's contribution to the situation's shape.

The phase graph is not a simple sequence. Reviews have cycles (collect -> consult -> collect, when contradictions between reviewers require additional input). Writing has returns (validate -> draft, when a quality gate fails). Ingestion is mostly linear but branches at triage (different content types diverge to different patterns). The directed graph with cycles captures all of these. A walk through the graph — a sequence of visited phases — is a particular engagement's trajectory.

Definition 2 (Engagement). An engagement is a method-token: an execution instance of a method-type. Formally, e = (M, G, sigma, t0) where M is the method-type (the procedure being executed), G is M's phase graph (inherited from the type), sigma is the current engagement state (see Definition 3), and t0 is the creation timestamp. The engagement is the normative view of a situation — it says not just what is happening, but what should happen next and toward what end.

The distinction between engagement and situation is the distinction between the normative and descriptive views of the same token (Definition 13 of [[01-objects]]). A review round is a situation: these people, reading this manuscript, producing these documents. The same review round is an engagement: the editor should synthesize, two reviews are in, one is pending, the next step is to follow up with the third reviewer. The situation records what is; the engagement records what ought to be. Engagement state externalizes the normative view.

Definition 3 (Engagement State). The engagement state sigma = (v, H, O, A, D) where:

  • v in V is the current phase — where the engagement stands in its phase graph
  • H is a set of (phase, timestamp) pairs recording completed phases — where the engagement has been
  • O is a set of pending obligations — what must happen before the next transition can fire
  • A is a set of (actor-token, role) pairs — who is participating and in what capacity
  • D is a set of domain-instances — where the work is happening

The state is a complete snapshot. Given sigma and G, any agent can determine: the current phase (v), the history of how it got there (H), what remains to be done in this phase (O), who is involved (A), and where the work lives (D). This is exactly the information that is currently lost at session boundaries and reconstructed through archaeology.

Definition 4 (Phase Transition). A transition (v, v') fires when all enabling conditions c{v,v'} are satisfied. The effect is: v is replaced by v', H is extended with (v, tnow), and O is recomputed from the new phase's obligation set as defined by the method-type. Enabling conditions are heterogeneous — they may be temporal (a deadline has passed), material (all reviews are in), actorial (the editor has been assigned), or computational (a script has completed). The only requirement is that they be evaluable: given the current state, an agent can determine whether the condition holds.

The distinction between firing a transition and recording that a transition has fired is important. In the current design, agents fire transitions by writing the new state. There is no automated transition detection — agents exercise judgment about when conditions are met. This is deliberate. Automated detection is a future enhancement; the immediate need is a persistent record that agents can read and write.

Definition 5 (Engagement Nesting). If engagement e1 spawns sub-engagement e2, then completion of e2 (reaching a terminal phase in e2.G) is an enabling condition for some transition in e_1.G. The sub-engagement inherits the parent's domain constraints but may narrow them.

This mirrors situation nesting (Definition S3 of [[12-situation-nesting]]). A paper submission engagement contains a review engagement as a sub-engagement. Completion of the review (terminal phase: synthesis delivered) enables the submission engagement to transition from "under review" to "revise." The review sub-engagement inherits the paper's project directory as its domain but may add reviewer-specific workspaces. The nesting is normative: the sub-engagement exists because the parent's method-type prescribes it as a step.

Definition 6 (Reconstruction Property). Given complete actor traces T, domain boards+indices B, and engagement states Sigma for all active engagements, the system state is reconstructible up to actor-internal reasoning. Formally: any fresh agent reading T union B union Sigma can determine (a) what work is active, (b) what phase each active engagement is in, (c) what obligations are pending, and (d) who is involved and in what role.

The qualification "up to actor-internal reasoning" is essential. The externalized state does not capture why an agent made a particular judgment — the reasoning that led a reviewer to a specific critique, the editor's deliberation about panel composition. Those are actor-internal and ephemeral by design (Foundation 08: identity is context, and context dies with the session). What the reconstruction property guarantees is that the structural state — phase, obligations, participants, domains — survives session death. The reasoning can be recovered from transcripts if needed, but it is not part of the engagement state.

#3. Ontological grounding

Every formal object defined above maps to the relational situational ontology. There are no new primitives. The definitions are refinements of existing ontological structures, applied to the method axis.

An engagement is a situation in the ontological sense — a compound of belongings with qualities (Definition 11 of [[01-objects]]). The method-type defines which kinds of belongings compose the situation. A review engagement is a situation where manuscripts belong as material, reviewers belong as actors with quality "reviewer," an editor belongs as actor with quality "editor," and the review method belongs as method. The engagement adds the normative dimension: the situation is not just described but governed by the method-type's phase graph.

A phase is a quality of the engagement-as-situation. In the quality framework of [[02-relations]], qualities specify the nature of a belonging — in what way does A belong to B? The current phase is the engagement's mode of existence at this moment. "Collecting reviews" and "synthesizing" are different qualities of the same engagement, just as "author" and "reviewer" are different qualities of a person's belonging to different situations. The phase quality changes over time as transitions fire; other qualities of the engagement (its participants, its domain) may persist across phases.

The phase graph is the normative structure that the method-type contributes. Definition 12 of [[01-objects]] defines policies as normative type-compounds that prescribe what must or should happen. The phase graph is a policy embedded in the method-type: it constrains which phase-qualities are reachable from which, and under what conditions. Not all phase sequences are valid. A review cannot reach synthesis without passing through collection. A manuscript cannot reach submission without passing through validation. The phase graph enforces this ordering — not mechanically (agents write the transitions) but normatively (a transition that skips a required phase is a violation, detectable by any agent that reads the graph).

Engagement state is the inscription of the engagement's current qualities — its materialization (Definition S4 of [[12-situation-nesting]]). Just as a directory materializes a project-situation, an engagement state file materializes an engagement. It makes the situation readable to any actor who enters it. Without the inscription, the engagement exists only in the memories of its participants. With it, a fresh agent can enter the engagement, read the state, and participate meaningfully — the same advantage that indices provide for navigating the domain axis.

Obligations are belongings with normative quality. They belong to the engagement and specify what must happen. "Synthesize reviews into editorial assessment" is an obligation that belongs to the engagement at the synthesis phase with quality "required-action." When fulfilled, obligations enable transitions. This is the same mechanism by which policies constrain actions in Definition 12 — obligations are phase-local policies, binding only within the engagement and only during the current phase.

This grounding is not decorative. It means engagement state inherits all the properties of the ontological framework: qualities are entities subject to the quality graph, belongings carry provenance, situations nest with policy inheritance. An engagement state file is not an ad-hoc format — it is the materialization of an ontological structure, and its fields correspond to well-defined ontological objects.

#4. What engagement state replaces

Currently, engagement position is reconstructed from three informal sources, each with characteristic failure modes.

Board entries are reverse-chronological event logs. They record that a review was dispatched, that a reviewer returned their assessment, that the editor posted a synthesis. But events are not phase positions. To determine the current phase from a board, an agent must read all entries related to the engagement, mentally reconstruct the sequence, and infer which phase the engagement is in based on which events have occurred. This is O(N) in the number of board entries — exactly the linear scan that the Library Theorem identifies as the problem. Worse, board entries are mixed: the same board carries entries from multiple engagements, unrelated coordination messages, and meta-commentary. Filtering by engagement requires pattern-matching on free text.

Agent memory dies with the session. An agent that has been conducting a review knows precisely where the engagement stands — which reviewers have returned, what the editor's instructions were, what remains. This knowledge is context-window state. When the session ends, it vanishes. The successor agent starts from scratch. Memory files (memory/MEMORY.md) carry cross-session patterns, but they are not designed for engagement state — they hold durable preferences and conventions, not the phase position of a specific review of a specific paper.

User memory is reliable and rich. The user knows what is happening, what has been done, what comes next. But user memory is unscalable — a user tracking twenty concurrent engagements cannot maintain precise phase positions for all of them — and unqueryable — an agent cannot programmatically ask the user's memory what phase the tasting paper review is in without interrupting the user.

Engagement state replaces all three with a single, structured, persistent record per active engagement. The board remains for event logging; it records what happened. Engagement state records where we are. The difference is the difference between a ship's log (chronological record of events) and a navigation chart (current position, planned route, next waypoint). Both are necessary. Only the chart answers "where are we now?"

#5. Implementation

File format. Each active engagement gets an engagement.md file in the project directory where the work lives, alongside board.md and index.md. YAML frontmatter carries the formal state; the markdown body carries narrative context that helps a fresh agent orient.

---
method: review
engagement_id: review-tasting-2026-03
phase: synthesis
started: 2026-03-10
phases_completed:
  - { phase: recruit, completed: 2026-03-10 }
  - { phase: dispatch, completed: 2026-03-11 }
  - { phase: collect, completed: 2026-03-18 }
obligations:
  - "synthesize reviews into editorial assessment"
  - "draft author response"
actors:
  - { id: editor-session-xyz, role: editor, status: pending }
  - { id: reviewer-1-abc, role: reviewer, status: complete }
  - { id: reviewer-2-def, role: reviewer, status: complete }
  - { id: reviewer-3-ghi, role: reviewer, status: complete }
domains:
  - projects/ai-ontology/02-tasting-paper
parent_engagement: null
---

# Review: Tasting Paper

Three reviews collected. All reviewers returned substantive assessments.
Reviewer 1 raised methodological concerns about the sensory protocol.
Reviewers 2 and 3 converged on the statistical analysis as the strongest
contribution but diverged on the novelty claim.

Next: editor synthesizes, resolving the methodological disagreement and
producing a decision letter with the eLife vocabulary.

## Context for successor agents

The panel was assembled from existing personas (lopes-g, kampff-ar,
feierstein-c). No new personas were built. The manuscript is at
projects/ai-ontology/02-tasting-paper/ms-v2.md. Individual reviews
are in R1/.

The frontmatter is machine-readable: any agent or script can parse the YAML and determine the phase, the obligations, the participants. The body is human-readable: it provides the narrative context that makes the formal state meaningful. This is the same two-level structure as index.md — Contents for routing, Details for understanding — applied to engagement state.

Naming. When a project has one active engagement, the file is engagement.md. When multiple engagements coexist — a review and a submission pipeline running concurrently on the same manuscript — each gets a distinguishing name: engagement-review.md, engagement-submission.md. The naming follows the navigate-not-address principle (Architecture 11): the project's index.md lists active engagements; agents navigate there, not to memorized paths.

Lifecycle. An engagement state file is created when a method is invoked on a project — either manually by an agent writing the file or via a /engage start <method> skill invocation. It is updated at each phase transition: the agent writes the new phase, appends to the completion history, and recomputes obligations. It is archived — moved to .archive/ — when the engagement reaches a terminal phase. This follows the existing archiving convention: .archive/ at any level holds superseded or completed artifacts.

Multiple engagements can be active simultaneously in the same project directory. A paper may be under review (review engagement), undergoing revision (writing engagement), and being prepared for submission (submission engagement) at the same time. Each has its own state file, its own phase position, its own participants. There is no singleton constraint — principle 3 (parallelizable by default) applies.

Skills integration. Four skill verbs cover the lifecycle:

  • /engage start <method> — creates engagement.md from the method-type's phase graph, populating the initial phase, empty history, initial obligations, and current actor set.
  • /engage status — reads and reports the current engagement state in natural language. Equivalent to reading the file, but formatted for conversation.
  • /engage advance <phase> — records a phase transition: writes the new phase, timestamps the completed phase, recomputes obligations from the method-type's definition.
  • /engage close — archives the engagement state file to .archive/ and posts a completion summary to the board.

These are thin — they read and write a file. The intelligence is in the agent's judgment about when to advance, not in the skill's logic.

Session start integration. Agents already read board.md on session entry (CLAUDE.md convention). The addition: also read any engagement.md files in the active project directory. This tells the agent not just what happened (board) but where the work stands (engagement state). The board is a log; engagement state is a dashboard. Both are needed; together they are sufficient.

#6. Phase graphs for existing methods

Two methods already defined in patterns/methods/ are shown here with their phase graphs, demonstrating that the abstraction applies to existing workflows without modification.

#Review (method 01)

The review method's phase graph is the most complex in the current system. It has cycles (collect -> consult -> collect when reviewers contradict), branches (the find-panel sub-procedure), and multiple terminal paths (accept, revise, reject).

                    +--[gaps found]--+
                    |                |
                    v                |
recruit -----> dispatch -----> collect -----> consult -----> synthesize -----> respond
  ^                              ^    \         |                               |
  |                              |     \        |                               |
  +-------[panel incomplete]-----+      +-------+                               v
                                    [contradictions                           package
                                      unresolved]                               |
                                                                                v
                                                                         [TERMINAL]

Phases:

  • recruit: assemble reviewer panel from personas. Obligations: panel of 3-5, coverage matrix complete, cost estimate shown.
  • dispatch: send manuscript to reviewers, spawn parallel review subagents. Obligations: all reviewers assigned, engine selected.
  • collect: gather completed reviews. Obligations: all dispatched reviews returned.
  • consult: resolve contradictions between reviewers. Obligations: contradictions identified and addressed. Loops back to collect if additional input needed.
  • synthesize: editor produces editorial assessment, bias report, decision letter. Obligations: synthesis covers all major points, convergence check passed.
  • respond: draft author responses with literature support. Obligations: each concern addressed, rebuttal searches complete.
  • package: assemble final deliverables (PDFs, index). Terminal phase.

Enabling conditions on transitions:

  • recruit -> dispatch: panel approved by user, cost estimate accepted.
  • dispatch -> collect: all reviews spawned (not completed — spawning is the trigger).
  • collect -> consult: all reviews returned.
  • consult -> collect: contradictions remain unresolved after first pass.
  • consult -> synthesize: all contradictions addressed or flagged as irreducible.
  • synthesize -> respond: synthesis approved by user.
  • respond -> package: all responses drafted.

Multi-round review (revision rounds) restarts the graph at dispatch with the same panel, incrementing the round counter. The engagement state records which round is active.

#Write (method 03)

The write method is more linear, with a single significant cycle.

gather -----> research -----> draft -----> validate -----> iterate
                                ^             |               |
                                |             v               v
                                +----[fails gate]        [TERMINAL]

Phases:

  • gather: collect source material. Obligations: all referenced sources identified and accessible.
  • research: background research, literature check, gap analysis. Obligations: gaps identified and addressed.
  • draft: write the document. Obligations: complete draft in type-appropriate structure.
  • validate: quality gate — completeness, grounding, voice consistency, length. Obligations: all checks passed.
  • iterate: author review and revision. Terminal phase (user decides when done).

Enabling conditions:

  • gather -> research: user confirms material complete.
  • research -> draft: user confirms gaps filled.
  • draft -> validate: draft complete.
  • validate -> iterate: all checks pass. If checks fail, loops to draft.
  • iterate -> [terminal]: user approves.

The write method's simplicity relative to review is structural, not accidental. Writing is primarily sequential with one feedback loop; reviewing is inherently parallel (multiple reviewers) with multiple feedback loops (contradictions, panel gaps, revision rounds).

#7. The reconstruction test

Foundation 07 proposes a test for the sufficiency of the three externalizations: run a multi-context session, collect only the externalized state, and have a fresh agent reconstruct what happened. With engagement state in place, this test becomes feasible. Without it, the test would fail trivially — the method axis would have no externalization to read, and phase positions would be unrecoverable.

What the test looks like. A structured experiment with three phases:

Phase 1 — Generation. Run a multi-session engagement that spans at least three sessions and involves at least two context switches per session. A review engagement is the natural candidate: session 1 assembles the panel and dispatches reviews; session 2 collects reviews and begins synthesis; session 3 completes synthesis and packages deliverables. Each session ends with proper externalization: board updated, engagement state advanced, trace recorded (when built).

Phase 2 — Collection. After the engagement completes, collect all externalized state: the final and all intermediate versions of engagement.md, all board entries tagged to this engagement, the project index, and any actor traces. Remove all session transcripts, agent memories, and conversation histories. The collected state is the input to reconstruction.

Phase 3 — Reconstruction. A fresh agent — one that has never participated in the engagement — reads the collected state and produces a narrative reconstruction: what happened, in what order, who did what, what the current status is (or was at completion), and what the key decision points were. This reconstruction is compared against the actual transcript record.

What success means. Success is reconstruction that correctly identifies: (a) every phase the engagement passed through, in order; (b) the participants and their roles; (c) the key obligations at each phase and whether they were met; (d) the domain(s) where work occurred. The reconstruction need not capture actor-internal reasoning — why the editor chose a particular phrasing, why a reviewer focused on methodology rather than statistics. Those are context-window ephemera, not structural state.

Quantitatively: if the reconstruction correctly identifies all phase transitions (timing and ordering), all participant assignments, and all obligation resolutions, the test passes. If it misses a phase transition, misidentifies a participant, or cannot determine whether an obligation was met, the test fails — and the failure points to which externalization is inadequate.

What failure would reveal. Three failure modes correspond to the three externalizations:

  1. Engagement state failure. The reconstruction cannot determine phase positions — it knows events happened (from the board) but not which phase they correspond to. This means the engagement state was not written at transitions, or was written with insufficient detail. The fix is better engagement state hygiene.
  1. Board/index failure. The reconstruction can determine phase positions but cannot determine what happened within each phase — the events, the artifacts produced, the decisions made. This means boards were not updated or indices were stale. The fix is better domain externalization.
  1. Trace failure. The reconstruction can determine what happened and where the engagement stands, but cannot determine why context switches occurred — why the agent moved from one project to another, what triggered the transition. This means the actor trace was missing or incomplete. The fix is building the trace.

The test is informative regardless of outcome. Success validates the three-axis model. Failure identifies which axis needs work. The engagement state document makes the test possible by providing the method-axis input that was previously missing entirely.

#8. Relationship to governance (.agent files)

Engagement state and governance authority coexist in the same directories. They are orthogonal externalizations that operate at different timescales and answer different questions. The .agent file declares who may act — it is standing authority, permanent until revoked by a governance act recorded in the ledger (Architecture 43). The engagement.md file declares what action is underway — it is execution state, episodic, created when a method is invoked and archived when the method completes.

The two interact through a single constraint: agents can only create engagements where they have write access under the governance chain. Workspace scoping (Architecture 43, §6) already enforces this — an agent whose scope does not include a directory cannot write an engagement.md there. No additional mechanism is needed. The governed agent for a directory has authority over any engagements in its scope: it can audit them, intervene in them, or constrain them, because governance subsumes engagement management. The actors field in engagement.md and the assignment layer in .agent files track the same agents in different capacities — participation (who is doing the work) versus authority (who may govern the work). An agent may appear in both without contradiction: the editor governing projects/paper-x/ may also be an actor in the review engagement running there.

Engagement files are always archived on completion; .agent files are never archived. This asymmetry reflects the structural difference: governance is topology (persistent), engagement is trajectory (episodic).

#9. What this document does NOT cover

Four related topics are outside scope, each requiring its own treatment:

Trace — the actor-axis externalization. Architecture 20 designs the trace as a private navigation log. Building it is a separate work item. Engagement state does not depend on trace (they externalize different axes), but the reconstruction test requires both.

Phase graph formalization for all methods. This document shows phase graphs for review and write. Extending to all methods in patterns/methods/ is incremental work — each method's existing workflow section already describes its phases informally. Formalization means drawing the graph, naming the enabling conditions, and listing obligations per phase. This can be done method by method as engagements are created.

Automated phase transition detection. The current design has agents write transitions manually. A future enhancement would detect transitions automatically — monitoring for enabling conditions and notifying agents when a transition is available. This requires evaluable enabling conditions, which the current obligation model supports in principle but does not enforce. The automation is desirable but not blocking.

Engagement state querying across projects. The current design is per-project: each project directory holds its own engagement.md files. Querying across projects — "show me all active engagements across the system" — requires an engagement registry or a sweep that reads all project directories. This is the same pattern as the entity graph's relationship to domain databases: local state is authoritative, the graph provides cross-cutting views. An engagement registry would be a natural extension of the entity graph, with engagements as situation entities and phase positions as qualities. The ontological groundwork for this is already in place (Section 3); the implementation is future work.

architecture . 39 . engagement state . 2026-03-19 . zach + claude

Architecture 39 — Engagement State — The Third Externalization — 2026 — Zachary F. Mainen / HAAK