diff --git a/canon/constraints/mode-transitions-require-encoded-handoff.md b/canon/constraints/mode-transitions-require-encoded-handoff.md new file mode 100644 index 00000000..1c6e0da3 --- /dev/null +++ b/canon/constraints/mode-transitions-require-encoded-handoff.md @@ -0,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 index 8689e50b..a0ed6736 100644 --- a/canon/definitions/epistemic-modes.md +++ b/canon/definitions/epistemic-modes.md @@ -13,7 +13,7 @@ date: 2026-04-18 # 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 @@ This is a Canon document because it constrains _how truth is formed_, not merely --- -## The Four Epistemic Modes +## The Five Epistemic Modes ### 1. Exploration Mode @@ -137,6 +137,35 @@ For the full contract, see `klappy://canon/validation-as-epistemic-mode`. --- +### 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 @@ In particular: - 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 index 00000000..b49c3b1a --- /dev/null +++ b/canon/principles/sessions-mirror-modes.md @@ -0,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/docs/appendices/mode-separated-conversations.md b/docs/appendices/mode-separated-conversations.md index 36afe6a0..d0a5d54d 100644 --- a/docs/appendices/mode-separated-conversations.md +++ b/docs/appendices/mode-separated-conversations.md @@ -108,6 +108,34 @@ Invalid moves: --- +## Resolution Conversations + +Purpose: + +- address validation findings per their explicit dispositions (fix, pivot, accept) +- produce a revised artifact scoped strictly by the findings +- hand off to a fresh re-validation conversation + +Characteristics: + +- findings exist with explicit dispositions before the conversation begins +- scope is bounded by the findings, not by reopening planning +- each finding has a remediation action (or is accepted as-is, with reasoning) +- conducted in a fresh session per session-per-mode discipline (see `canon/principles/sessions-mirror-modes`) +- the revised artifact plus a remediation summary per finding is the durable handoff +- re-validation is performed in a separate session that does not inherit the resolver's reasoning + +Invalid moves: + +- introducing requirements the findings did not surface — that requires explicit reversion to planning +- using remediation as cover for redesign or for changes outside the findings +- self-validating the fix in the same session that produced it (the resolver does not certify their own work) +- ignoring findings rather than disposing of them explicitly +- treating validation findings as suggestions rather than as scoped work items +- handing off to re-validation without a remediation summary + +--- + ## Mode Signaling Mode MAY be signaled explicitly: 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 index 00000000..153624cf --- /dev/null +++ b/journal/2026-05-10-mode-discipline-canon-set.tsv @@ -0,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.