canon: codify session-per-mode discipline + add Resolution as fifth mode#186
Merged
Conversation
Three Tier-1 canon additions plus journal entry capturing the work. NEW: klappy://canon/principles/sessions-mirror-modes Generalizes critic-cannot-be-resolver and verification-requires-fresh-context to a universal claim about session structure. Names five mode-bound roles (explorer, planner, builder, validator, resolver). Pressures relaxation candidates (E↔P bleed-over, PoC scope) — both are permissions, not defaults. NEW: klappy://canon/constraints/mode-transitions-require-encoded-handoff Operationalizes the principle as a binding rule. Every transition produces (a) a journal entry (DOLCHEO+H, no exceptions) and (b) a transition-specific minimal handoff. Handoffs enumerated per gate: synthesis ledger; plan with assumptions; artifact with claims; findings with dispositions; revised artifact with remediation summary. Reversion and skip allowed with explicit acknowledgment. PATCH: canon/definitions/epistemic-modes.md Adds Resolution as fifth canonical mode. The four-mode canon already implied this phase via 'fixes belong to iteration, which is a fresh execution pass scoped by validation findings'; the patch names what was implied. Updates the heading (Four → Five), pull-quote summary, adds the §5 Resolution Mode section with same structure as other four modes, and expands the Non-Collapse Rule with three resolution-specific invalid moves. JOURNAL: journal/2026-05-10-mode-discipline-canon-set.tsv DOLCHEO+H entry capturing the decisions, the operator-directed iteration that sharpened the framing, and the handoff to PR D (runtime doc) and parallel PR A (substrate canon). Self-applies the constraint: this PR's transition from execution to (eventual) validation produces the journal entry the new constraint requires. Operator-directed: 'execution and resolver as mode' / 'principles and constraints, two roles and purpose' / 'encoding journal should be repeated for every transition without exception'.
Canon Quality —
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: TSV column misalignment from extra tab character
- Removed the extra tab between typeName and quality_score on all five data rows so each row now has 8 fields matching the header.
Preview (f05d3a89bc)
diff --git a/canon/constraints/mode-transitions-require-encoded-handoff.md b/canon/constraints/mode-transitions-require-encoded-handoff.md
new file mode 100644
--- /dev/null
+++ b/canon/constraints/mode-transitions-require-encoded-handoff.md
@@ -1,0 +1,143 @@
+---
+uri: klappy://canon/constraints/mode-transitions-require-encoded-handoff
+title: "Mode Transitions Require Encoded Handoff — Every Gate Demands a Durable Artifact"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: evolving
+tags: ["canon", "constraints", "epistemic-modes", "handoff-contract", "journal", "dolcheo", "session-discipline", "mode-discipline", "encoding"]
+epoch: E0008.5
+date: 2026-05-10
+derives_from: "canon/principles/sessions-mirror-modes.md, canon/definitions/epistemic-modes.md, canon/constraints/critic-cannot-be-resolver.md, canon/principles/verification-requires-fresh-context.md"
+complements: "canon/methods/persona-shaped-agent-runtime.md, docs/mode-separated-conversations.md, docs/oddkit/proactive/oldc-h-vocabulary.md"
+governs: "Every transition between epistemic modes — exploration, planning, execution, validation, resolution — across all surfaces (agent runtime, human conversation, mixed teams)"
+status: proposed
+---
+
+# Mode Transitions Require Encoded Handoff — Every Gate Demands a Durable Artifact
+
+> A mode transition without a durable handoff is mode collapse with extra steps. The receiving session has no grounded artifact to read; it has only the working memory of the prior session, transmitted informally. That is exactly what session-per-mode discipline forbids. This constraint operationalizes [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) by requiring two things at every transition between epistemic modes: a journal entry recording the transition, and a transition-specific minimal handoff artifact. The journal is universal and applies to every transition without exception. The handoff content varies by transition. Both are required before the next mode's session can legitimately begin.
+
+---
+
+## The Two Required Artifacts
+
+Every legitimate transition between epistemic modes produces two artifacts:
+
+### 1. Journal Entry — Universal, No Exception
+
+Every transition produces a journal entry recording what happened. The format is DOLCHEO+H per [the canonical vocabulary](klappy://docs/oddkit/proactive/oldc-h-vocabulary): observations, learnings, decisions, constraints, encodes, handoffs. The journal entry captures:
+
+- The mode transition itself (from → to, with timestamp)
+- What was completed in the prior mode (obligations met)
+- What is being deferred or carried forward
+- Any reversion or skip, with explicit acknowledgment
+- The handoff artifact reference (URI or path)
+
+Journal entries are append-only durable records. They live in the project's ledger or equivalent canon-adjacent location. They do not replace the handoff artifact described below; they complement it. The journal is for the project's longitudinal memory; the handoff is for the next session's working context.
+
+This requirement admits no exceptions. Even transitions between modes whose obligations are minimal — exploration to planning, where neither produces a heavy artifact — produce a journal entry. Even transitions during PoC-scope work produce a journal entry. The journal is the audit trail that allows future work to trust the history.
+
+### 2. Transition-Specific Minimal Handoff
+
+Each transition has a minimum required handoff content beyond the journal. The receiving session reads this handoff, not the prior session's working memory. The minimal contents are:
+
+| Transition | Minimal Handoff |
+|---|---|
+| **Exploration → Planning** | Encoded synthesis of possibilities, tensions, unknowns, and competing frames surfaced during exploration. Stored as a synthesis ledger entry, research artifact, or equivalent durable encoding. The planner reads the synthesis; they do not inherit the explorer's session state. |
+| **Planning → Execution (build)** | A plan declaring: explicit assumptions, scope (what is in and out), deferred items, and conditions that would invalidate the plan. The builder reads the plan; they do not inherit the planner's reasoning beyond what is captured. |
+| **Execution → Validation** | The artifact itself plus an explicit claims declaration — what the artifact does, what it does not do, what scope it was built against. The validator reads the claims and the artifact; they do not inherit the builder's intent beyond what is declared. |
+| **Validation → Resolution** | Findings with explicit dispositions (fix, pivot, accept) per the validation mode's obligations. Each finding includes evidence grounded in the produced artifact. The resolver reads the findings; they do not inherit the validator's framing beyond what is captured. |
+| **Resolution → Validation (re-validation)** | The revised artifact plus a remediation summary per finding (what was changed, what was not changed and why). The re-validating session reads the revised artifact and the remediation summary; they do not inherit the resolver's reasoning beyond what is captured. |
+
+These are minimums. A handoff can include more — supporting evidence, screenshots, traces, alternative framings considered and rejected — but it cannot include less. A handoff that does not contain its minimum content is incomplete; the next session cannot legitimately begin until the handoff is complete.
+
+---
+
+## Why "Encoded" Is the Operative Word
+
+The handoff must be encoded — written down in a form the next session can read independently of any human or agent who participated in the prior session. Verbal handoffs, working-memory carry-over, and "I'll explain when you get there" patterns are not encoded handoffs. They are mode collapse with extra steps.
+
+The encoding requirement serves three purposes:
+
+**Independence.** The next session can begin without coordinating with the prior session. The handoff artifact is sufficient input. This is what makes session-per-mode discipline operationally feasible — a fresh planner can read the synthesis ledger and start planning without scheduling a conversation with the explorer.
+
+**Durability.** The handoff outlives both sessions. If a question arises later about why a plan made a specific assumption, the synthesis ledger that the plan was based on is still readable. The audit trail is preserved.
+
+**Falsifiability.** An encoded handoff can be reviewed for completeness. A working-memory handoff cannot — there is no way to check whether anything important was lost in the transition because there is no record of what was supposed to transfer. Encoding makes the handoff inspectable.
+
+---
+
+## Reversion and Skip Are Allowed With Acknowledgment
+
+This constraint does not forbid reversion or skip. It requires that both be encoded.
+
+**Reversion** — returning to an earlier mode — produces a journal entry naming the reversion and its cause. The originally received handoff remains valid for future re-attempts; nothing is destroyed. The reversion entry acknowledges that the prior mode's obligations were not met sufficiently to proceed, and reframes the work back into that mode.
+
+**Skip** — moving to a later mode without satisfying the intermediate one — produces a journal entry naming the skip and the explicit acknowledgment. Skipping validation, for example, is allowed when the artifact is throwaway and the cost of skipping is accepted. The acknowledgment must be explicit and durable, and the skipped mode's risks are inherited by the project.
+
+Both reversion and skip require the journal entry. Neither is a free move. The discipline is not that work always proceeds linearly through five modes; the discipline is that every deviation from linear progress is acknowledged in a durable record.
+
+---
+
+## Operational Enforcement
+
+This constraint is enforceable at three layers:
+
+**Agent runtime.** A runtime that hosts agent sessions per [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) can require a handoff URI and a journal entry reference as inputs to any session whose role is downstream of another role. Sessions invoked without complete handoff inputs are refused. This makes the constraint structural rather than dependent on agent discipline.
+
+**Human workflow tooling.** PR templates, design-doc templates, ticket workflows, and similar can require handoff fields before transitioning a unit of work to its next mode. The tooling does not enforce the *quality* of the handoff (the encoded synthesis might be sparse), but it enforces the *existence* of one.
+
+**Conversational surfaces.** Chat-based interfaces, pair-programming sessions, and design reviews enforce this constraint through explicit gating language: "okay, before we move from planning to building, let's encode the plan." The discipline is harder to mechanize at this layer and easier to violate; the mitigation is participant awareness and operator-as-bottleneck framing.
+
+The runtime layer is where this constraint is most cleanly enforced. The conversational layer is where it is most often violated and most consequential when violated, because conversations naturally flow across mode boundaries without ceremony.
+
+---
+
+## What This Constraint Does Not Require
+
+It does not require that the handoff be exhaustive. The minimums above are minimums; the goal is sufficient encoding to allow a fresh session to begin, not perfect documentation. A planner who declares three explicit assumptions, defines scope in two paragraphs, and notes one invalidating condition has met the minimum, even if a richer plan would have been better.
+
+It does not require that the handoff be authored by the prior session's primary agent. An explorer can ask a side-task to draft the synthesis ledger; a builder can ask another agent to write the claims declaration. The encoding requirement is about the artifact existing in durable form, not about who produced it.
+
+It does not require that every project use these specific role names. The mapping is to epistemic modes, which are canonical. Projects that use different vocabulary (research → spec → implementation → review → fix, for example) are still bound by this constraint, with the role names mapped to the canonical modes.
+
+It does not require that the receiving session never communicate with the prior session's participants. Q&A about ambiguities in the handoff is permitted. The constraint is that the handoff itself is the primary input — a question to the prior session's author is a clarification, not a substitute for the encoded artifact.
+
+---
+
+## Conversational Mode Should Feel Seamless — But Underneath Is Discipline
+
+Operators may object that this constraint is incompatible with chat-based work, where the cognitive flow naturally moves from "let's explore this" through "okay let's plan it" through "I'm building" without ceremony.
+
+The constraint is not that the *human experience* must feel like five separate conversations. The constraint is that the *epistemic record* must reflect five separate sessions when five modes were crossed. The two are reconciled by orchestration: a chat-facing surface can spawn fresh sessions per mode in the background, write encoded handoffs at each transition, and present a unified conversation to the human user. The user sees continuity; the system records discipline.
+
+This is a consumer pattern, not a runtime feature, and it is documented separately. See [Mode-Separated Conversations](klappy://docs/mode-separated-conversations) for the conversational application of mode discipline. The principle here is that the handoff requirement does not relax for conversational surfaces; it just gets handled by orchestration rather than by the human noticing each transition.
+
+---
+
+## Confidence
+
+**Working belief.** The journal-entry requirement extends an already-canonical practice (DOLCHEO+H entries on every session per [oldc-h-vocabulary](klappy://docs/oddkit/proactive/oldc-h-vocabulary)) to mode transitions specifically. The transition-specific handoff requirements extend already-canonical practice for individual transitions (P0008 for validator deliverables, plan documents for execution work, etc.) into a uniform contract.
+
+**Retraction conditions:**
+
+- If the universal journal-entry requirement produces audit-trail clutter without corresponding investigative value, the requirement narrows to specific high-stakes transitions (e.g., execution → validation) and becomes optional elsewhere.
+- If the transition-specific handoff minimums prove to over-specify in practice — projects routinely producing the minimums but finding them insufficient or excessive — the minimums are revised against observed need.
+- If conversational orchestration overhead (spawning fresh sessions, encoding handoffs invisibly) makes mode-disciplined chat surfaces too expensive to operate, the constraint is relaxed for conversational surfaces and remains binding only for explicit multi-session work.
+
+**What this constraint costs.** Visibly: more journal entries, more handoff artifacts, more orchestration when conversational surfaces want to remain chat-shaped. Invisibly: the cost of *not* having durable records when work fails or audits arise — a cost that is paid in confusion, lost context, and unfalsifiable history when the constraint is violated. The visible cost is what operators feel; the invisible cost is what makes the constraint load-bearing.
+
+---
+
+## See Also
+
+- [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) — the principle this constraint operationalizes
+- [Epistemic Modes](klappy://canon/epistemic-modes) — the parent canon defining the modes whose transitions this constraint governs
+- [DOLCHEO+H Vocabulary](klappy://docs/oddkit/proactive/oldc-h-vocabulary) — the journal entry format required at every transition
+- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle motivating the encoded handoff for execution → validation specifically
+- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the constraint motivating the encoded handoff for validation → resolution specifically
+- [P0008 — Fresh-Validator Deliverable Is a DOLCHEO Ledger](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable) — the operationalized handoff pattern for the validator role
+- [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) — the runtime architecture that enforces this constraint mechanically for agent work
+- [Mode-Separated Conversations](klappy://docs/mode-separated-conversations) — the conversational application of mode discipline
diff --git a/canon/definitions/epistemic-modes.md b/canon/definitions/epistemic-modes.md
--- a/canon/definitions/epistemic-modes.md
+++ b/canon/definitions/epistemic-modes.md
@@ -13,7 +13,7 @@
# Epistemic Modes
-> Exploration, planning, execution, and validation are not interchangeable.
+> Exploration, planning, execution, validation, and resolution are not interchangeable.
> Collapsing them produces false confidence, premature convergence, and brittle outcomes.
## Purpose
@@ -28,7 +28,7 @@
---
-## The Four Epistemic Modes
+## The Five Epistemic Modes
### 1. Exploration Mode
@@ -137,6 +137,35 @@
---
+### 5. Resolution Mode
+
+**Purpose:**
+To produce a revised artifact scoped strictly by validation findings.
+
+**Characteristics:**
+
+- Findings exist with explicit dispositions (fix, pivot, accept)
+- Scope is bounded by the findings, not by reopening planning
+- Each finding has a remediation action (or is accepted as-is)
+- The revised artifact is the deliverable; new requirements are not introduced
+
+**Truth Condition:**
+A resolution is valid if it **addresses the findings without expanding scope**.
+
+**Obligations:**
+
+- Address each finding per its disposition (fix what was marked fix; redirect what was marked pivot; document what was marked accept)
+- Do not introduce requirements the findings did not surface
+- Document remediation per finding — what was changed, what was not changed and why
+- Hand off to validation again — the resolver does not certify their own fix
+
+**Primary Risk:**
+Scope creep — using remediation as cover for redesign or for introducing changes outside the findings.
+
+For the role-and-session expression of this mode, see `klappy://canon/principles/sessions-mirror-modes`.
+
+---
+
## The Non-Collapse Rule
**Epistemic modes MUST NOT be collapsed.**
@@ -148,7 +177,10 @@
- Execution must not pretend to explore alternatives retroactively
- Execution must not pretend to validate — concerns noticed mid-build are noted and carried forward, not surfaced as inline pivots
- Validation must not pretend to plan — redesign requires explicit reversion
-- Validation must not pretend to execute — fixes belong to iteration, which is a fresh execution pass scoped by validation findings
+- Validation must not pretend to execute or resolve — findings produce a separate resolution pass, not inline fixes during the same review
+- Resolution must not pretend to plan — new requirements that emerge during remediation require explicit reversion to planning
+- Resolution must not pretend to validate — the resolver does not certify their own fix; re-validation is a separate session
+- Resolution must not pretend to be a fresh execution — its scope is bounded by findings, not by the original plan
When modes are collapsed:
diff --git a/canon/principles/sessions-mirror-modes.md b/canon/principles/sessions-mirror-modes.md
new file mode 100644
--- /dev/null
+++ b/canon/principles/sessions-mirror-modes.md
@@ -1,0 +1,137 @@
+---
+uri: klappy://canon/principles/sessions-mirror-modes
+title: "Sessions Mirror Modes — Each Epistemic Mode Earns Its Own Session"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: evolving
+tags: ["canon", "principles", "epistemic-modes", "session-discipline", "context-corruption", "mode-discipline", "agent-design", "fresh-context"]
+epoch: E0008.5
+date: 2026-05-10
+derives_from: "canon/definitions/epistemic-modes.md, canon/principles/verification-requires-fresh-context.md, canon/constraints/critic-cannot-be-resolver.md, canon/constraints/mode-discipline-and-bottleneck-respect.md"
+complements: "canon/constraints/mode-transitions-require-encoded-handoff.md, canon/methods/persona-shaped-agent-runtime.md, docs/mode-separated-conversations.md"
+governs: "All multi-mode work — agent-driven and human-driven — where the same artifact passes through more than one epistemic mode"
+status: proposed
+---
+
+# Sessions Mirror Modes — Each Epistemic Mode Earns Its Own Session
+
+> The structural blindness that makes a creator unable to validate their own work, a critic unable to remediate their own findings, and a planner unable to honestly execute their own plan is the same blindness in three different shapes. The fix is the same in all three: separate the contexts. Sessions should map one-to-one onto epistemic modes — explorer, planner, builder, validator, resolver — because the context corruption that follows mode collapse follows the same structural pattern across every transition. This principle generalizes critic-cannot-be-resolver and verification-requires-fresh-context to a universal claim about session boundaries: every gate between modes is a context boundary, and every context boundary deserves a fresh session.
+
+---
+
+## The Pattern
+
+Three constraints already canonical name the same structural problem in three places:
+
+- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the agent that detects drift cannot be the agent that resolves it. Same context corrupts both functions.
+- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — a creator cannot be their own critic, because the same lenses used to create are the same lenses used to evaluate.
+- [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — exploration, planning, and execution are distinct epistemic states with different truth conditions; collapsing them produces false confidence.
+
+These are not three independent rules. They are three applications of one structural insight: *a context that produced a mode's output cannot honestly evaluate, remediate, or transition out of that output without corruption.* The corruption is not a character flaw of the agent in the context. It is a structural property of any system that operates across mode boundaries with shared state.
+
+This principle generalizes the insight: every transition between epistemic modes is a context boundary, and every context boundary deserves a fresh session. There are no special cases. The transitions between exploration and planning, between planning and execution, between execution and validation, and between validation and resolution are all instances of the same pattern.
+
+---
+
+## The Roles
+
+A session is bound to a single role. The role is the operational expression of the mode the session is operating in. The roles are:
+
+| Role | Mode | Primary Output |
+|---|---|---|
+| **Explorer** | Exploration | A synthesis of possibilities, tensions, and unknowns. Questions outnumber answers. |
+| **Planner** | Planning | A plan with explicit assumptions, scope, deferred items, and conditions that would invalidate the plan. |
+| **Builder** | Execution | An artifact plus claims about what the artifact does and does not do. |
+| **Validator** | Validation | Findings with explicit dispositions — fix, pivot, or accept — grounded in the produced artifact. |
+| **Resolver** | Resolution | A revised artifact plus remediation summary per finding, scoped strictly by the findings. |
+
+The roles are not interchangeable. Each operates under the truth conditions and obligations of its mode (per [Epistemic Modes](klappy://canon/epistemic-modes)) and deserves a session whose context is bounded by that mode's purpose.
+
+---
+
+## Why Each Boundary Earns a Fresh Session
+
+The structural argument repeats at every transition, with the specific corruption shape varying:
+
+**Exploration → Planning.** A planner who shares the explorer's context inherits the explorer's framing of what is interesting. The planner narrows toward what was salient during exploration rather than toward what is actually load-bearing for the work ahead. Exploration's primary risk — false closure, mistaking familiarity for understanding — is most acute at this boundary. A fresh planner reads the exploration's encoded synthesis and forms their own narrowing.
+
+**Planning → Execution.** A builder who shares the planner's context inherits the planner's confidence in the plan. Where the plan was uncertain, the builder treats the planner's resolution of that uncertainty as fact, because the planner-context bridges the gap between assumption and decision. Speculative certainty — the planner's primary risk — propagates into execution as treated-as-known. A fresh builder reads the plan, sees the assumptions explicitly, and surfaces a question rather than silently filling in.
+
+**Execution → Validation.** This is the canonical case. A validator who shares the builder's context cannot honestly evaluate the artifact because their context contains the builder's intent, not just the builder's output. They see what was meant, not what was produced. This is the boundary [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) was written to defend.
+
+**Validation → Resolution.** A resolver who shares the validator's context inherits the validator's framing of each finding. Where the validator's framing was wrong — a finding incorrectly classified, a disposition applied without sufficient evidence — the resolver cannot independently assess. They optimize toward fixing what the validator said is broken rather than toward fixing what is actually broken. This is the boundary [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) was written to defend.
+
+**Resolution → Validation (re-validation).** When a resolver hands a revised artifact back for validation, the validating session must again be fresh. A validator who saw the original findings and now sees the resolution may unconsciously calibrate toward "did the resolver address my findings" rather than "does the revised artifact match its claims." A fresh validator session reading the revised artifact and the remediation summary, without the original-findings context, gets cleaner signal.
+
+The shape of the corruption changes at each boundary. The structural fix does not.
+
+---
+
+## What Sharing Context Costs
+
+Operators reasonably ask whether the gates can be relaxed. Two relaxations seem appealing:
+
+**Bleed-over between exploration and planning.** Both modes are thinking-shaped. Neither produces a load-bearing artifact. Same-session E↔P feels efficient.
+
+But exploration's primary risk is false closure, and planning's primary purpose is convergence. Sharing the session means convergence begins before tension-surfacing has finished. The cost is invisible from inside the session — the planner experiences clean reasoning while quietly missing the alternatives the explorer would have surfaced if pushed further. The fix is not to share context but to make the explorer-to-planner handoff cheap. A fresh planner reading a well-encoded synthesis ledger has the same speed advantage with none of the corruption.
+
+**PoC scope as a free pass.** For throwaway work, full mode discipline can feel like overhead. The temptation is to collapse all five roles into one session for a proof-of-concept and only impose discipline when the work is "real."
+
+The risk is that "PoC" stretches. Work that started exploratory becomes load-bearing because it was useful, and the audit trail of mode separation was never built. By the time someone notices the work is consequential, no one can trust its history. PoC scope can still skip modes — the canonical position is that *skipping is allowed when explicitly acknowledged* (per [Epistemic Modes](klappy://canon/epistemic-modes)) — but the discipline is acknowledgment, not size. PoC sessions that skip modes declare the skip; production work that skips modes does not get the same forgiveness.
+
+The relaxations are permissions, not the default. Default is gate-required for every transition.
+
+---
+
+## Why This Is Architectural, Not Conversational
+
+This principle applies wherever modes are crossed: human work, agent work, mixed teams. But the architectural application is what makes it operationally enforceable.
+
+For agent runtimes, sessions are first-class objects. A runtime that hosts agent work can enforce session-per-mode structurally — refusing to wire a builder's tools into a validator session, refusing to inherit context across role boundaries. See [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) for the runtime expression of this principle.
+
+For human work, the principle is harder to enforce mechanically and easier to violate. A human who explored, planned, built, validated, and resolved a piece of work in a single afternoon has crossed five mode boundaries with shared context and may not notice. The mitigation is the same as for any cognitive-discipline question: rest, peer review, and explicit acknowledgment when modes were collapsed for legitimate reasons (genuine PoC scope, time pressure with stated tradeoff).
+
+For conversational surfaces — chat with an AI assistant, pair-programming sessions, design reviews — the principle is most often violated and least often noticed. A conversation that flows from "let's explore this" to "okay, here's the plan" to "I'm building it now" to "looks good" within a single context window has executed every transition without any gate. The conversational ergonomic is comforting; the epistemic state is corrupted. Surfaces that want both ergonomic continuity and mode discipline have to orchestrate the transitions invisibly — spawning fresh sessions per mode while presenting unified continuity at the human-facing surface. That is a consumer pattern, not a runtime feature.
+
+---
+
+## Derivation
+
+This principle derives from three sources, each of which it generalizes:
+
+**Axiom 4 — You Cannot Verify What You Did Not Observe.** A session that operates across mode boundaries with shared context has not fully observed each mode's truth conditions. It has observed an interpolation between them, weighted by which mode's framing arrived first. Fresh context per mode restores the capacity to observe each mode's reality cleanly.
+
+**Verification Requires Fresh Context.** That principle named the corruption shape for the creation→validation transition specifically. This principle observes that the same shape applies at every transition — exploration→planning corrupted by premature convergence, planning→execution corrupted by speculative certainty, validation→resolution corrupted by inherited framing. The structural mechanism is the same; only the surface symptom differs.
+
+**Critic Cannot Be Resolver.** That constraint named the corruption shape for the detection→remediation transition. This principle observes that *every* role transition is a critic-cannot-be-resolver instance in spirit — each role's purpose is bounded by its mode's truth conditions, and each downstream role inherits corruption when it shares context with the upstream role.
+
+The relationship is not that this principle replaces those. It generalizes them, and they remain the canonical references for their specific transitions. Where a question is specifically about creation→validation, [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) is the right pointer. Where the question is about session structure across all transitions, this principle is the right pointer.
+
+---
+
+## Confidence
+
+**Working belief.** The underlying corruption mechanism is established (verification requires fresh context, critic cannot be resolver). Generalizing to all mode transitions is consistent with the established mechanism but has more limited production evidence — the canonical applications have been creation→validation and detection→remediation specifically.
+
+**Retraction conditions:**
+
+- If production evidence shows that one or more transitions produce no measurable signal degradation when context is shared (controlling for handoff quality), the universal claim is retracted in favor of the previously canonical narrower constraints.
+- If the cost of fresh sessions per transition exceeds the benefit at scale — for example, if the orchestration overhead for invisible mode transitions consumes most of the throughput gain — the principle is revised to identify which transitions justify fresh sessions and which do not.
+
+**What would falsify the principle most cleanly.** A controlled comparison between two work streams: one with full session-per-mode discipline, one with shared context across two-or-more transitions, both producing the same artifact. If the shared-context stream produces equal or higher-quality output with the same effort budget, the universal claim is wrong and the canonical narrower constraints (verification-requires-fresh-context, critic-cannot-be-resolver) are sufficient.
+
+The principle is consequential because it argues for more session boundaries — and therefore more handoffs, more journal entries, more orchestration cost — than the previously canonical narrower constraints required. That cost is real. The claim is that the signal-quality gain exceeds the cost. That claim deserves pressure.
+
+---
+
+## See Also
+
+- [Epistemic Modes](klappy://canon/epistemic-modes) — the parent canon defining the modes themselves
+- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle this generalizes for the creation→validation transition specifically
+- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the constraint this generalizes for the detection→remediation transition specifically
+- [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — the operator-attention argument for mode separation
+- [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff) — the binding rule that operationalizes this principle
+- [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) — the runtime architecture that enforces this principle for agent work
+- [Mode-Separated Conversations](klappy://docs/mode-separated-conversations) — the conversational application of this principle
diff --git a/journal/2026-05-10-mode-discipline-canon-set.tsv b/journal/2026-05-10-mode-discipline-canon-set.tsv
new file mode 100644
--- /dev/null
+++ b/journal/2026-05-10-mode-discipline-canon-set.tsv
@@ -1,0 +1,6 @@
+type typeName facet quality_score quality_max quality_level title content
+D Decision 5 5 strong Promote Resolution to fifth canonical epistemic mode The four-mode canon at klappy://canon/epistemic-modes already implied a fifth phase via the line "fixes belong to iteration, which is a fresh execution pass scoped by validation findings." This patch names that implied phase as Resolution mode, gives it the same structure as the other four (purpose, characteristics, truth condition, obligations, primary risk), and updates the Non-Collapse Rule with three resolution-specific invalid moves. Operator directed in conversation: "Builder as role, execution and resolver as mode."
+D Decision 5 5 strong Generalize critic-cannot-be-resolver and verification-requires-fresh-context to a universal session-per-mode principle New Tier-1 principle klappy://canon/principles/sessions-mirror-modes generalizes the structural insight from two existing canon docs to a universal claim: every transition between epistemic modes is a context boundary, and every context boundary deserves a fresh session. Names five mode-bound roles (explorer, planner, builder, validator, resolver). Pressures both relaxation candidates (E↔P bleed-over and PoC scope) and lands on "permissions, not the default."
+D Decision 5 5 strong Codify universal handoff requirement for every mode transition New Tier-1 constraint klappy://canon/constraints/mode-transitions-require-encoded-handoff operationalizes the principle by requiring two artifacts at every transition: a journal entry (DOLCHEO+H, no exceptions) and a transition-specific minimal handoff (encoded synthesis ledger; plan with assumptions; artifact with claims; findings with dispositions; revised artifact with remediation summary). Reversion and skip allowed with explicit acknowledgment.
+O Observation 4 5 medium Operator-directed iteration sharpened persona-shaped runtime to support the full five-role taxonomy Initial runtime draft used four ad-hoc named roles (detection-only, validator, resolver, general). Operator pushed back: "creator cannot be their own validator? Shouldn't we find that and include that here too?" — surfaced the verification-requires-fresh-context parent. Then: "the planner should not be the executor. We need explicit execution sessions for planning vs building vs validating vs resolving." This drove generalization to a universal principle and the five-role taxonomy. Observation: operator's pattern is to surface the next-level abstraction one-at-a-time; resisting urge to anticipate too far prevents premature canonization while operator's iteration tightens the framing.
+H Handoff 5 5 strong Mode-discipline canon set ready for review Three-doc canon set staged in PR C against klappy.dev/main: new principle (sessions-mirror-modes, Tier 1, evolving), new constraint (mode-transitions-require-encoded-handoff, Tier 1, evolving), patch to existing epistemic-modes adding Resolution as fifth mode. Runtime doc (persona-shaped-agent-runtime) lands separately in PR D and depends on this PR. Existing audit-gate substrate canon lands in parallel PR A. AMS adoption pointer rename lands in PR B after PR A merges.You can send follow-ups to the cloud agent here.
Reviewed by Cursor Bugbot for commit ba43490. Configure here.
The mode-separated-conversations appendix listed Planning, Execution, and Validation as the three core conversation types. With Resolution added as the fifth canonical epistemic mode (this PR), the appendix needs a parallel section so the conversational application of the five-mode taxonomy is complete. Adds Resolution Conversations section between Validation and Mode Signaling, mirroring the structure of existing sections (Purpose / Characteristics / Invalid moves). References sessions-mirror-modes for the session-per-mode discipline argument. Resolves the first of two follow-ups flagged when the canonical mode-discipline set was drafted.
klappy
pushed a commit
that referenced
this pull request
May 10, 2026
…ntract draft) + journals Two runtime method docs preserved here for operator review and reconciliation: DOC 1 (recommended canonical): canon/methods/persona-shaped-agent-runtime.md Tier 1, proposed. Reflects operator's session-per-mode guidance from 2026-05-10 conversation. Five mode-bound roles (explorer, planner, builder, validator, resolver) plus general escape hatch and observer carve-out. Derives from sessions-mirror-modes principle and mode-transitions-require-encoded-handoff constraint (PR C). DOC 2 (prior iteration, draft): canon/methods/spawned-agent-session-runtime-contract.md Tier 2, draft. Five-orthogonal-dimensions framing (persona, mode, role, surface, engagement) from prior compacted session. Introduces 'engagement' dimension (assistant vs agent — turn-based dialogue vs autonomous run-to-completion) that is genuinely orthogonal and missing from doc 1. Worth folding forward, or keeping as sibling, per operator decision. JOURNALS: - 2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv (prior session's DOLCHEO entries) - 2026-05-10-runtime-canon-divergence.tsv (this PR's entries — flags the two-doc situation, names engagement as the worth-preserving insight, recommends persona-shaped as canonical) DEPENDS ON: - PR #185 (substrate canon) — references klappy://canon/methods/spawned-agent-session-substrate-options - PR #186 (mode-discipline canon) — references klappy://canon/principles/sessions-mirror-modes and klappy://canon/constraints/mode-transitions-require-encoded-handoff OPERATOR ACTION REQUIRED: Pick one runtime doc as canonical, OR reconcile the two before merge. Recommend persona-shaped as canonical with engagement dimension folded in.
klappy
added a commit
that referenced
this pull request
May 10, 2026
…act (spec, Tier-2), with parallelism + operator-override extensions and P0009 sweep (#187) Lands provisional runtime canon as the best foreseeable shape for the persona-shaped agent runtime, expected to be tested, journaled, and iterated. ## Runtime canon split (the headline) Two complementary docs at distinct altitudes, deliberately not collapsed: - canon/methods/persona-shaped-agent-runtime.md — Tier-1 method, status: proposed, stability: evolving. The architectural shape: persona-as-noun framing, persona profile schema (canonical home), runtime responsibilities at the architecture level, deployment sequencing, prior art, inheritance from canonical commitments, worked examples. - canon/methods/spawned-agent-session-runtime-contract.md — Tier-2 spec, status: draft, stability: evolving. The per-session-shape contract: per-mode tool allow-lists / output schemas / risk detectors / anti-pattern detectors; per-role boundaries; per-surface post-processing rules; per-engagement turn-control; the composition rules with forbidden / rare / well-trodden combinations; explicit enforcement points list. Each doc opens with a Companion Documents callout naming the sibling and partitioning what lives where. Frontmatter complements is symmetric; See Also lists put the sibling at the top. Architecture changes land in the method; per-dimension mechanics changes land in the spec. Both docs carry retraction conditions in their Confidence sections. First deployment (audit gate as single-role validator) is the next signal-source. ## Downstream extensions to canon landed in #186 - canon/principles/sessions-mirror-modes.md gains a Parallelism Patterns section: within-mode parallelism encouraged, multi-participant single-session allowed, cross-mode-on-same-artifact forbidden, cross-mode-on-different-artifacts independent. - canon/constraints/mode-transitions-require-encoded-handoff.md gains an Operator Override section: explicit mode collapse under urgency, distinct from reversion and skip, requires acknowledgment and durable record. - canon/definitions/epistemic-modes.md gets see-also references to both new principles + epoch/date bump. ## P0009 enforcement (DOLCHEO+H residue sweep) DOLCHEO+H was the duplicated-H anti-pattern (H is already at position 5 of DOLCHEO). Replaced with DOLCHEO throughout: - mode-transitions-require-encoded-handoff.md updated to reference klappy://canon/definitions/dolcheo-vocabulary instead of the legacy oldc-h-vocabulary URI. - writings/reverse-engineer-the-future.md essay prose corrected. ## Reconciliation note Earlier framing of this PR described the two runtime docs as competing alternatives. Direct read showed they are complementary layers; operator's call was to keep both, reduce overlap, cross-reference cleanly. Verification finding: the prior PR claim about engagement being missing from doc 1 was wrong — engagement was already at parity in persona-shape §6. Real overlap was the persona profile YAML, per-mode role descriptions, surface post-processing, mode toggles, and engagement spec depth. That overlap is removed in the latest commit. ## Posture This is the best foreseeable shape with zero production validations behind it. Tier-1 designation on persona-shape is provisional; promotion past 'proposed' awaits production signal. Iterate via journal entries against real deployments rather than speculative redesigns. ## Journals - journal/2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv — five-dimension reasoning - journal/2026-05-10-runtime-canon-divergence.tsv — initial divergence flag - journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv — operator-override session record - journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv — parallelism + encoded-handoff session record - journal/2026-05-10-runtime-canon-split-reconciled.tsv — layer-split reconciliation + verification correction
klappy
pushed a commit
that referenced
this pull request
May 10, 2026
Encodes the corrected lane after a prior-session off-lane drift drafting Oddie content without checking that Oddie already exists in canon (PR #179, #180). Withdrawn off-lane draft lives at /mnt/user-data/outputs/oddie-system-prompt-v0.md and should be ignored. Lane: wire canon/methods/quality-attribute-tension-survey.md to oddkit's existing governance machinery (preflight, gate, challenge, validate, encode) following the runtime-contract / persona-shaped pattern that PR #187 landed 2026-05-10. Scope is the method doc + the session ledger on the same PR branch. Required reading enumerated: PRs #187 (runtime-contract pattern), #186 (five modes including Resolution), #180 + #179 (existing Oddie canon), plus four open PRs ahead that may force a rebase. Concrete steps, do-not list, and banked off-scope items captured so a fresh session can pick up without re-deriving context. Frontmatter matches odd/handoffs/ conventions; tier 2; status active.
klappy
pushed a commit
that referenced
this pull request
May 10, 2026
Encodes the corrected lane after a prior-session off-lane drift drafting Oddie content without checking that Oddie already exists in canon (PR #179, #180). Withdrawn off-lane draft lives at /mnt/user-data/outputs/oddie-system-prompt-v0.md and should be ignored. Lane: wire canon/methods/quality-attribute-tension-survey.md to oddkit's existing governance machinery (preflight, gate, challenge, validate, encode) following the runtime-contract / persona-shaped pattern that PR #187 landed 2026-05-10. Scope is the method doc + the session ledger on the same PR branch. Required reading enumerated: PRs #187 (runtime-contract pattern), #186 (five modes including Resolution), #180 + #179 (existing Oddie canon), plus four open PRs ahead that may force a rebase. Concrete steps, do-not list, and banked off-scope items captured so a fresh session can pick up without re-deriving context. Frontmatter matches odd/handoffs/ conventions; tier 2; status active.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Three Tier-1 canon additions plus a journal entry capturing the work. Codifies session-per-mode discipline and promotes Resolution to the fifth canonical epistemic mode.
Files
New canon
canon/principles/sessions-mirror-modes.md— Tier-1 principle, the why. Generalizes critic-cannot-be-resolver and verification-requires-fresh-context to a universal claim about session structure. Names five mode-bound roles (explorer, planner, builder, validator, resolver). Pressures both relaxation candidates (exploration↔planning bleed-over, PoC scope) and lands on "permissions, not the default."canon/constraints/mode-transitions-require-encoded-handoff.md— Tier-1 constraint, the what's required. Operationalizes the principle as a binding rule: every transition produces a journal entry (DOLCHEO+H, no exceptions) plus a transition-specific minimal handoff. Per-gate handoffs enumerated. Reversion and skip allowed with explicit acknowledgment.Canon patch
canon/definitions/epistemic-modes.md— adds Resolution as fifth canonical mode. The four-mode canon already implied this phase via "fixes belong to iteration, which is a fresh execution pass scoped by validation findings"; the patch names what was implied. Six explicit changes: heading (Four → Five), pull-quote summary, new §5 Resolution Mode section with same structure as other four modes, and three new resolution-specific entries in the Non-Collapse Rule.Journal
journal/2026-05-10-mode-discipline-canon-set.tsv— DOLCHEO+H entry capturing the decisions, the operator-directed iteration that sharpened the framing, and the handoff to dependent PRs.Operator-directed
This PR codifies operator decisions made in conversation:
Self-application
The PR's transition from execution mode (drafting these docs) to validation mode (PR review) produces the journal entry the new constraint requires. The constraint is self-applying.
Forward references and dependencies
persona-shaped-agent-runtime) depends on this PR because the runtime doc derives fromsessions-mirror-modesandmode-transitions-require-encoded-handoff.Confidence
Working belief. The principle generalizes two established constraints to a stronger universal claim — that argues for more session boundaries than the previously canonical narrower constraints required. The Confidence section in
sessions-mirror-modes.mdflags retraction conditions and the most-cleanly-falsifying test (controlled comparison of session-per-mode vs. shared-context for the same artifact).The Resolution mode patch is purely additive. Nothing in existing canon is contradicted; the patch names what was already implied.
Cross-reference inventory
Expected: only the new docs themselves and the journal entry. No external references yet (forthcoming PR D adds runtime doc references; future docs may add more).
Note
Medium Risk
Medium risk because it updates Tier-1 canon definitions and introduces new binding principles/constraints that may change how downstream docs and workflows interpret/enforce mode transitions.
Overview
Promotes Resolution to a first-class fifth epistemic mode and tightens the non-collapse rules to explicitly separate validation, resolution, and re-validation.
Adds a new Tier-1 principle (
sessions-mirror-modes) requiring fresh sessions per mode/role (explorer→planner→builder→validator→resolver), and a new Tier-1 constraint (mode-transitions-require-encoded-handoff) mandating a universal DOLCHEO+H journal entry plus a transition-specific minimal encoded handoff at every mode boundary (with explicit handling for reversion/skip).Extends
mode-separated-conversationswith a new Resolution Conversations section and records the decisions/handoff injournal/2026-05-10-mode-discipline-canon-set.tsv.Reviewed by Cursor Bugbot for commit 4d3dcd1. Bugbot is set up for automated code reviews on this repo. Configure here.