From 8136d7421010b320d0d7e94cb130123943a9c83f Mon Sep 17 00:00:00 2001 From: "Claude (via klappy)" Date: Sun, 10 May 2026 04:12:37 +0000 Subject: [PATCH 1/9] canon: add runtime methods (persona-shaped-agent-runtime + runtime-contract draft) + journals MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- canon/methods/persona-shaped-agent-runtime.md | 345 ++++++++++++++++++ .../spawned-agent-session-runtime-contract.md | 343 +++++++++++++++++ .../2026-05-10-runtime-canon-divergence.tsv | 5 + ...nt-runtime-and-five-dimension-contract.tsv | 27 ++ 4 files changed, 720 insertions(+) create mode 100644 canon/methods/persona-shaped-agent-runtime.md create mode 100644 canon/methods/spawned-agent-session-runtime-contract.md create mode 100644 journal/2026-05-10-runtime-canon-divergence.tsv create mode 100644 journal/2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv diff --git a/canon/methods/persona-shaped-agent-runtime.md b/canon/methods/persona-shaped-agent-runtime.md new file mode 100644 index 0000000..696ea1a --- /dev/null +++ b/canon/methods/persona-shaped-agent-runtime.md @@ -0,0 +1,345 @@ +--- +uri: klappy://canon/methods/persona-shaped-agent-runtime +title: "Persona-Shaped Agent Runtime — Building a Reusable Substrate for Many Personas" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: evolving +tags: ["canon", "methods", "agent-runtime", "persona-profile", "substrate", "vodka-architecture", "oddie", "spawned-agent-session", "role-enforcement", "surface-profile"] +epoch: E0008.5 +date: 2026-05-10 +derives_from: "canon/methods/spawned-agent-session-substrate-options.md, canon/principles/sessions-mirror-modes.md, canon/constraints/mode-transitions-require-encoded-handoff.md, canon/constraints/critic-cannot-be-resolver.md, canon/principles/verification-requires-fresh-context.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md" +complements: "canon/principles/methodology-personification.md, canon/principles/voice-as-cognitive-load-shedding.md, canon/principles/participation-replaces-integration.md" +governs: "Any service that hosts spawned agent sessions on behalf of multiple consumers and multiple personas" +status: proposed +--- + +# Persona-Shaped Agent Runtime — Building a Reusable Substrate for Many Personas + +> A spawned-agent-session substrate (CF Sandboxes, Anthropic Managed Agents, etc.) hosts one session at a time. A *runtime* sits on top of a substrate and turns it into a service: many consumers can call it with many tasks, and the substrate stays opinion-free underneath. This method documents how to shape that runtime so it composes with **personas as first-class objects** — Oddie, an audit reviewer, a release validator, a docs mentor — without coupling the runtime to any specific persona's identity or any specific consumer's workflow. The pattern keeps the substrate vodka, makes critic-cannot-be-resolver mechanically enforceable, and turns voice canon into something the runtime honors automatically rather than something the agent inside has to remember. + +--- + +## What This Document Is + +A design pattern for the layer that sits between a spawned-agent-session substrate and the consumers who want agent help. Companion to [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options): that doc catalogs *where* to host a session; this doc describes *how to build a service on top* so the same substrate serves many callers and many personas without each pair re-implementing infrastructure. + +This is a method, not a decision. It documents the shape; it does not lock in implementation specifics. Specific runtime instances (the audit gate, a TinCan-Oddie deployment, a docs mentor service) are decisions that consume this method. + +--- + +## The Pattern + +A spawned-agent-session substrate gives you one capability: spin up an agent in an isolated context, hand it a task, get a result. That capability is generic. Every consumer that wants agent help would otherwise wire it themselves: prompt assembly, tool registration, MCP setup, secret injection, output parsing, surface-specific formatting. The wiring is repetitive. It also smuggles opinions into the substrate (which prompt? which tools? which output schema?), violating vodka-architecture at the substrate layer. + +The runtime resolves this by hosting the wiring at a layer above the substrate: + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Consumers: audit gate │ slack bot │ cron │ TinCan │ ... │ +│ (each one knows: "invoke this persona, this task") │ +├────────────────────────────────────────────────────────────────┤ +│ Runtime: persona resolution │ role enforcement │ │ +│ surface post-processing │ session lifecycle │ +├────────────────────────────────────────────────────────────────┤ +│ Substrate: CF Sandbox │ Managed Agents │ Daytona │ ... │ +│ (just spawns isolated sessions) │ +└────────────────────────────────────────────────────────────────┘ +``` + +The runtime accepts requests of the form *"invoke persona P on surface S for task T,"* resolves P to operational configuration, dispatches to the substrate, post-processes the output per S, and returns. Personas are canon objects. Surfaces are constraints. The substrate stays generic. The consumer stays simple. + +--- + +## The Persona Profile + +A persona profile is a structured description of who an agent is, what it can do, and how its output is constrained. Profiles are themselves canon — versioned, URI-addressable, governed by the same rules as any other canon doc. + +### What a Profile Contains + +A profile bundles: + +| Field | Purpose | +|---|---| +| `system_prompt_uri` | The voice canon or role specification. The runtime fetches this and passes it to the agent. | +| `role` | One of `detection-only`, `resolver`, `general`. Drives tool filtering and session lifecycle rules. | +| `mcp_servers.operational` | MCPs the persona requires to *be* itself, regardless of task. (Oddie needs oddkit always.) | +| `mcp_servers.task_relevant` | MCPs added per invocation based on the specific task. (A PR audit gets the GitHub MCP.) | +| `knowledge_bases` | URIs the persona can ground observations against (`klappy://`, `ams://`, etc.). | +| `surface_profiles` | Per-surface constraints: density caps, output format, narrative-vs-structured, max tokens per emission. | +| `brand_discipline` | URI pointing at the persona's voice canon section that governs emoji, vocabulary, machine-vs-human surface rules. | + +### Illustrative Sketch + +```yaml +persona: oddie +version: 1 +system_prompt_uri: klappy://canon/voice/oddie-the-river-guide +role: detection-only +mcp_servers: + operational: [oddkit] + task_relevant: [] +knowledge_bases: + - klappy:// + - ams:// +surface_profiles: + real_time_stream: { density: high, max_tokens_per_emission: 60 } + audit: { density: medium, structured_output: required } + mentorship: { density: low, narrative: true } + strategic_translation: { density: medium, bidirectional: true } +brand_discipline: klappy://canon/voice/oddie-the-river-guide#brand-guide +``` + +The schema is illustrative. Specific field names, validation rules, and serialization format are implementation choices. The principle is that a persona's identity is captured in a structured artifact that the runtime can resolve to operational configuration. + +### Where Profiles Live + +Two reasonable options: + +1. **The voice canon doc is the profile.** Structured fields go in the YAML frontmatter; narrative goes in the prose body. Single source of truth. +2. **Profiles are separate canon docs** (e.g., `klappy://personas/oddie`) that reference the voice canon for narrative. Cleaner separation; two-doc maintenance. + +Either approach is consistent with this method. The choice belongs to the operator authoring the first profile. + +--- + +## The Runtime's Job + +The runtime accepts an invocation, resolves a profile, executes against a substrate, and post-processes the result. Five responsibilities specifically: + +### 1. Resolve Profile to Operational Configuration + +`runtime.invoke(persona="oddie", surface="audit", task="...")` triggers: + +- Fetch the persona profile by name and version. +- Fetch the system prompt at `system_prompt_uri`. +- Compose the operational MCP set (always-on) with the per-invocation task-relevant MCPs. +- Apply the named surface profile's constraints. +- Hand the assembled config to the substrate. + +The runtime is the only component that knows how to assemble these pieces. Consumers do not. New consumers can be added without touching profile-resolution logic. + +### 2. Enforce Role at Submit Time + +Two parallel constraints need architectural enforcement, drawn from two parent canon docs: + +- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — detection and remediation must be separated by a *tool boundary*. A session that detects cannot also mutate. +- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — creation and validation must be separated by a *context boundary*. A session that validates cannot inherit the creator's accumulated reasoning. + +Generalized to all mode transitions per [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes), every transition between epistemic modes is a context boundary deserving a fresh session. The runtime enforces the boundaries through five mode-bound roles plus an escape hatch. + +#### The Five Mode-Bound Roles + +Each role corresponds to one of the five canonical [epistemic modes](klappy://canon/epistemic-modes). The role declares the session's mode; the runtime enforces the role's constraints structurally. + +**`explorer`** — operates in exploration mode. Tool set is broad (read-only access to canon, web search, conversational tools, hypothesis-shaping tools); state-mutation tools are refused. Output is a synthesis ledger or research artifact per the [encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff). Fresh-context requirement is light — explorers can build on prior exploration but should not inherit planning-context. + +**`planner`** — operates in planning mode. Tool set is read-oriented (canon access, prior synthesis ledgers, plan-shaping tools); state-mutation tools are refused. Output is a plan declaring assumptions, scope, deferred items, and invalidating conditions. Fresh-context requirement: must not inherit explorer-session state directly; reads the explorer's encoded synthesis as input. The plan is the durable handoff to the builder. + +**`builder`** — operates in execution mode. Tool set includes mutating tools (filesystem writes, git commits, API calls, etc.) bounded by the plan's declared scope. Output is the produced artifact plus a claims declaration (what the artifact does, what it does not do, what scope it was built against). Fresh-context requirement: must not inherit planner-session state; reads the plan as input. The artifact plus claims is the durable handoff to the validator. + +**`validator`** — operates in validation mode. Tool set is restricted to a read-only allow-list. Mutating actions are refused before the substrate is invoked. Fresh-context requirement is *strict*: the runtime guarantees the validation session is spawned with no inputs from the caller other than the persona profile, the artifact reference, the claims declaration, and the governance documents. No prior conversation, no handoff context beyond the encoded artifact-and-claims, no "we discussed X earlier" framing. Output is structured findings with explicit dispositions (fix, pivot, accept) per finding, consistent with [P0008](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable). The findings are the durable handoff to the resolver (or, if all findings are accepted, the validation session is the terminal session). + +**`resolver`** — operates in resolution mode. Tool set includes mutating tools, but bounded by the validator's findings. The runtime can validate that mutations stay within finding-scope when the implementation supports it; at minimum, the resolver session is briefed that scope is bounded. Fresh-context requirement: must not inherit validator-session state; reads the findings as input. Output is the revised artifact plus a remediation summary per finding (what was changed, what was not changed and why). The revised artifact is the durable handoff back to a fresh validator session for re-validation. + +#### Escape Hatch and Observer Sessions + +**`general`** — no mode-binding, no fresh-context guarantee, no structured-deliverable requirement. Used for personas that intentionally combine modes in workflows where the context-corruption risk is acceptable. Mode-collapsed sessions are a deliberate choice to trade signal quality for throughput; the runtime supports them but does not pretend the constraints are met. PoC-scope work that explicitly skips modes (per the [encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff)'s skip provision) is the canonical use case. + +**Observer sessions.** Some sessions do not fit the five-mode taxonomy because they do not produce artifacts that hand off to a next mode — they are continuous observers, emitting commentary on streams produced elsewhere. Oddie's real-time stream interpretation surface is the worked example. These sessions are configured with the `subscribed` session type (see §5 below), a tool restriction (typically read-only), and no mode-bound role declaration. They are not gate-bounded work; the encoded-handoff constraint does not apply because there are no transitions to encode. + +#### Constraints Are Composable + +The named roles bundle (tool filter × fresh-context requirement × deliverable shape × mode binding) in their canonical configurations. The underlying parameters are composable. A persona profile can declare a custom role configuration if the named roles do not fit — e.g., a "drafting" role that combines builder-role tools with explorer-role context-freshness for early-stage artifact work. Named roles are recommended for legibility; custom configurations are supported for cases the named roles undersolve. + +#### Universal Handoff Requirement + +Per [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff), every transition between mode-bound roles requires a journal entry plus a transition-specific minimal handoff artifact. The runtime enforces this by requiring handoff URI inputs on any session whose role is downstream of another role. Sessions invoked without complete handoff inputs are refused. The journal entry is universal; the runtime can require it as a side-effect of any mode-bound session's completion. + +### 3. Apply Surface-Profile Output Post-Processing + +The runtime tags every output field as `machine` (parsed by code) or `human` (read by people). Surface profiles constrain what reaches each tag: + +- **Persona emoji stripped from machine fields.** If the voice canon bans 🦦 in JSON / YAML / commit messages / status titles / URIs, the runtime enforces that ban at output time, not at prompt time. The agent inside can speak naturally; the runtime cleans before delivery. +- **Density caps applied.** If a `real_time_stream` surface declares `max_tokens_per_emission: 60`, an emission that exceeds the cap fails validation and the runtime requests a shorter retry. Brevity-under-pressure becomes structural. +- **Format contracts honored.** If `structured_output: required`, the runtime parses fenced JSON from the agent's response and rejects free-form text. If `narrative: true`, prose is expected and structure is optional. + +Voice and brand are mechanically enforceable at this layer. The agent does not have to police itself; the runtime does. + +### 4. Honor Mode Toggles + +Personas have voice modes — `persona`, `neutral`, `strict` — declared per invocation: + +- **persona**: full voice canon applies (signature emoji, vocabulary, register). +- **neutral**: persona emoji and vocabulary suppressed; functional status emoji (✅ ⚠️ 🔴) survive because they carry information rather than character. +- **strict**: even functional emoji minimized; output is purely text. Useful for environments that strip emoji entirely (parser-sensitive contexts, accessibility-first surfaces). + +The mode is a runtime parameter, applied uniformly across all output fields. The agent inside does not need to know which mode is active. + +### 5. Support Session Types + +Two session shapes cover known use cases: + +- **`one_shot`**: invoke, return, tear down. Audit gates, on-demand reviews, doc-generation tasks. Single output. +- **`subscribed`**: long-lived, connected to an event source, emits over time. The TinCan flagship case for Oddie. Real-time stream interpretation, scheduled monitoring, persistent observers. + +A subscribed session needs: connection management, multi-output channels (per-channel post-processing), backpressure handling for when stream rate exceeds interpretation rate, and a teardown signal. The audit-gate use case does not need any of this. The runtime should support both without requiring `subscribed` consumers to use `one_shot` machinery or vice versa. + +--- + +## What This Method Is Not + +**Not orchestration.** The runtime invokes one persona per request. It does not chain personas, route between them, or maintain workflows that span multiple invocations. Orchestration belongs to consumers, not to the runtime. (A consumer can call the runtime multiple times in sequence; that is the consumer's workflow.) + +**Not coupling.** A persona profile does not specify *which* substrate hosts it. The same Oddie profile can run on CF Sandboxes, on Managed Agents, on Daytona, or on a local Docker container. The runtime resolves the profile and dispatches to whatever substrate is configured. Substrate choice is a runtime-deployment decision per [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options); persona authoring is independent. + +**Not a CRM for personas.** The runtime is not a directory service, identity provider, or persona-discovery layer. It resolves profiles by URI. Listing, searching, and discovering personas is a separate concern — handled by canon search, by directory pages, or by whatever tooling exists upstream. + +**Not a permission system.** Role enforcement is about epistemic-context separation (critic-cannot-be-resolver), not authorization. Whether a *consumer* is allowed to call the runtime is a separate question, handled at a different layer (API keys, OAuth, bearer tokens). The runtime trusts its callers; it just refuses to wire detection sessions with resolver tools. + +--- + +## Prior Art + +This pattern is not novel as a category — agent-runtime services and persona-shaped agents are an active design space. The contribution here is the specific composition of constraints, not the existence of the pattern. + +Adjacent work this method is aware of: + +- **OpenAI Custom GPTs** and **Anthropic Projects** — persona-shaped chat surfaces with system prompts, tools, and knowledge bases. Closest in spirit to persona profiles. Differences: Custom GPTs and Projects target end-user chat surfaces, not programmatic invocation by other services; they do not architecturally enforce role-separation (critic-cannot-be-resolver is left to prompt design); brand-discipline is not mechanically enforced at output time. The runtime pattern targets multi-consumer service composition, not direct human chat. +- **LangChain agent runtimes** and similar SDK-level abstractions — toolkit for assembling agents, often with persona-like configuration. Differences: typically embedded in the consumer's process rather than offered as a hosted service; do not enforce an explicit critic-vs-resolver context boundary; surface-aware output post-processing is left to consumers. +- **Cloudflare Agents SDK** and the **MCP `McpAgent` pattern** — substrate-aware abstractions for hosting agents on Workers. Closer to the substrate layer than to the runtime layer described here; this method composes on top of such abstractions rather than replacing them. +- **Anthropic Managed Agents** — the substrate captured in [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options). Substrate, not runtime. The runtime pattern is the layer that would sit above Managed Agents (or any other substrate) to multiplex consumers and personas. + +The closest prior art is probably Custom GPTs / Projects, characterized as of mid-2026. The runtime pattern's distinguishing commitments are: programmatic-first interface, mechanical role enforcement, mechanical brand discipline at output time, and explicit separation between persona authoring (canon) and runtime engineering (service). + +If a respected peer points to closer prior art that already names this composition, the contribution shrinks to "naming and codifying for this knowledge base" — which is still worthwhile as a vocabulary anchor but is not novel design. + +--- + +## Inheritance — Why This Shape + +The runtime shape is not original. It is a synthesis of three commitments already canonical: + +**[Vodka Architecture](klappy://canon/principles/vodka-architecture)**: substrates win by refusing opinions. The substrate-options catalog stays opinion-free per that principle; this runtime stays opinion-free by pushing opinions up into persona profiles. Every layer above the substrate is removable without wire consequence. + +**[Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes)**: each epistemic mode earns its own session because 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 execute their own plan is the same blindness in different shapes. This runtime is the architectural expression of that principle — five mode-bound roles, each with its own session, each refusing to inherit context from prior-mode sessions. + +**[Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff)**: every gate between modes requires a journal entry plus a transition-specific durable artifact. This runtime enforces that constraint mechanically by requiring handoff URI inputs on any session whose role is downstream of another role. + +**[Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver)**: detection and remediation must be separated by a tool boundary. The runtime enforces this for the validator → resolver transition specifically, refusing mutating tools in validator sessions and requiring a fresh resolver session to act on findings. + +**[Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context)**: a creator cannot be their own critic. The runtime enforces this for validator sessions specifically by guaranteeing fresh context — the validator session receives only the persona profile, artifact reference, claims declaration, and governance, never the creator's accumulated reasoning. The same fresh-context guarantee applies generally to every mode-bound role transition under sessions-mirror-modes. + +**[Participation Replaces Integration](ams://canon/principles/participation-replaces-integration)**: open substrates collapse connector topology from O(N²) to O(N). Without this runtime, every persona × consumer pair requires its own wiring. With it, N personas + M consumers needs N + M descriptors, not N × M integrations. The runtime is the participation layer that makes the collapse work for agent invocation specifically. + +The pattern is also consistent with [Methodology Personification](klappy://canon/principles/methodology-personification): if a methodology becomes more accessible when given a personified voice, the natural follow-up is infrastructure that lets the persona show up everywhere without re-engineering. The runtime is that infrastructure. + +--- + +## First Worked Examples + +Two consumers exercise the runtime's role enforcement most directly: + +### Oddie (validator and observer across surfaces) + +Oddie is the first persona this method targets. He exercises multiple parts of the shape: + +- **Role spans validator and observer depending on surface.** Audit findings is `validator` — receives a specific PR or document, evaluates against governance, produces structured findings with dispositions. Real-time stream interpretation is an *observer* session — not a mode-bound role, since Oddie watching live agent traffic does not produce a hand-off artifact for a next mode. Mentorship and strategic translation are also observer-shaped: continuous narrative on something happening elsewhere, not gate-bounded work. The persona profile declares the allowable session shapes; each invocation specifies which is in play. +- **Two capability sources** — operational MCP (oddkit, used for self-hygiene) and knowledge base (klappy.dev, used for grounding). Both registered in every Oddie session. +- **Four surface profiles** — audit, real-time stream interpretation (flagship), mentorship, strategic translation. Each declares its density and verbosity tolerance. +- **Brand discipline** — 🦦 signature, river vocabulary, machine-surface ban, density rule, mode-aware suppression. All mechanically enforceable. +- **Both session types** eventually — the audit surface is `one_shot`; the TinCan flagship is `subscribed`. The runtime needs both. + +Implementing the runtime against Oddie validates several parts of the shape but not all. Oddie does not exercise the explorer, planner, builder, or resolver roles — those need a different worked example. + +### A Multi-Role Build Workflow (explorer → planner → builder → validator → resolver) + +The cleanest exercise of the full five-role taxonomy is a multi-agent build workflow that crosses every gate. Sketched: + +1. **Explorer session** — given a goal, surfaces possibilities, tensions, and unknowns. Produces a synthesis ledger entry. +2. **Planner session** — fresh, reads the synthesis. Produces a plan with explicit assumptions, scope, deferred items. +3. **Builder session** — fresh, reads the plan. Produces an artifact plus claims declaration. +4. **Validator session** — fresh, reads the artifact and claims. Produces findings with dispositions. +5. **Resolver session** — fresh, reads the findings. Produces a revised artifact plus remediation summary. +6. **Re-validation session** — fresh, reads the revised artifact and remediation summary. Produces validation pass or new findings. + +Each transition produces a journal entry per [the encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff). Each session is a fresh substrate spawn with no inherited context from upstream sessions beyond the encoded handoffs. The runtime enforces the role-bound tool restrictions at each step. + +This workflow does not yet have a deployed instance. It is the canonical test of the runtime — the smallest workflow that exercises all five mode-bound roles plus the journal requirement. A first deployment that validates the full pipeline produces concrete signal on whether session-per-mode discipline is operationally feasible at the runtime layer. + +### The Audit Gate (validator, single-role) + +The audit gate that currently runs against AMS PRs is the cleanest validator-role consumer in isolation. It exercises the validator role's enforcement (read-only tools, fresh-context guarantee, structured deliverable per [P0008](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable)) without needing the full multi-role pipeline. It is the right first deployment of the runtime because it isolates one role and produces concrete signal on whether validator-role enforcement works in production. + +The deployment sequence is therefore: + +1. Audit gate as single-role validator deployment — lowest-risk first deployment, validates one role's enforcement. +2. Multi-role build workflow as second deployment — exercises the full five-role pipeline plus journal handoffs. +3. Oddie's TinCan-flagship subscribed-session deployment — exercises the observer pattern and the long-lived session type. + +In that order, each deployment validates a distinct dimension of the runtime without trying to validate all dimensions at once. + +--- + +## Open Questions + +These are explicitly unresolved. The method describes the shape; the open questions are about parameters that production evidence will tune. + +**Subscribed-session backpressure policy.** When stream rate exceeds interpretation rate, what gets dropped, summarized, or queued? The TinCan integration spec flags this as an open question. The runtime has to expose policy — it cannot hide the question — but the right policy is empirical. + +**Profile-discovery ergonomics.** How do consumers find available personas? Canon search works for humans; for programmatic consumers, a registry endpoint or a profile-listing convention may be needed. Defer until a second consumer beyond the first deployment exists. + +**Versioning semantics.** Profiles are versioned (`oddie@v1`). What happens when `v2` ships? Do existing consumers pin? Auto-upgrade? Receive a deprecation window? The right answer is probably "consumers pin; profile authors emit deprecation notices." Confirm with operator. + +**Surface-profile inheritance.** Can a persona's `mentorship` surface profile inherit from another persona's? If two personas share a surface specification, do they share a definition? Premature optimization until two personas exist with overlapping surfaces. + +**Multi-knowledge-base grounding.** Oddie grounds in `klappy://`. A future persona might ground in `klappy://` and `ams://` and a private knowledge base simultaneously. The profile schema lists `knowledge_bases` as an array, but the runtime's job in arbitrating between sources is undefined. Defer. + +--- + +## What This Changes for Existing Work + +The substrate-options method doc catalogs *where* to host a session. This doc adds *how to build a service that hosts many sessions for many personas*. They compose without overlap. + +The audit gate, currently scoped as a single Worker that wraps Claude Code in a CF Sandbox, becomes a specific deployment of this runtime: one persona (audit reviewer), one surface (audit), one substrate (CF Sandbox). The architecture shifts from "the audit Worker" to "the runtime, configured for audit." Same code, different framing — but the framing pays off when the second persona arrives. + +Oddie's TinCan integration, currently a draft spec at `ams://docs/oddie/tincan-real-time-guide`, becomes a specific deployment of this runtime: one persona (Oddie), one surface (real-time stream interpretation), substrate to be determined. The integration spec's open questions (throughput, token budget, multi-conversation context) inherit into the runtime's open-questions list above. + +Future deployments — a security detector, a docs mentor, a release validator — are new persona profiles plus runtime configuration, not new infrastructure. + +--- + +## Confidence + +**Working belief.** Zero production validations. The shape is derived from existing canonical commitments (vodka-architecture, critic-cannot-be-resolver, participation-replaces-integration) and from one designed-but-untested persona (Oddie). The pattern has not yet hosted a real consumer in production. + +**What depends on this method being right.** If this shape is the wrong abstraction, the dependent work that has to be re-thought includes: the audit-gate migration off Anthropic Managed Agents (would revert to bespoke Worker per consumer); the TinCan-Oddie integration spec's deployment path (would require its own substrate wiring); and any follow-up persona deployments (security detector, docs mentor, release validator), each of which would duplicate substrate plumbing. The blast radius is significant but bounded — it does not affect AMS, oddkit, or klappy.dev canon themselves; only the agent-invocation infrastructure that sits above them. + +**Retraction conditions:** + +- If the runtime's overhead (profile resolution, post-processing, role enforcement) measurably degrades performance compared to bespoke per-consumer wiring without producing offsetting benefits in correctness or composability, the abstraction is retracted and consumers wire substrates directly. +- If persona profiles prove too rigid — if every new persona requires schema extensions — the profile concept is retracted in favor of a thinner contract (system prompt + tool list + surface tag, nothing else). +- If role enforcement at the runtime layer produces false-refusals frequently enough to be a friction tax, the enforcement moves back to prompt discipline and a softer warning layer. + +**What would falsify the pattern most cleanly.** A second persona deployment that fights the abstraction — i.e., a persona whose natural shape requires schema extensions in three out of five fields, or whose surface profiles do not fit the density-cap model, or whose role does not map cleanly to detection-only/resolver/general. If two well-specified personas cannot share the runtime without per-persona special cases, the abstraction is leaking and should be retracted in favor of thinner contracts. + +The retraction conditions are weak by design. The first deployment (audit gate) will surface concrete signal. The second deployment (Oddie on TinCan, or another non-audit persona) is the real test of whether the abstraction holds. + +--- + +## See Also + +- [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) — the principle this runtime is the architectural expression of +- [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff) — the binding rule this runtime enforces mechanically +- [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options) — the catalog of substrates this runtime sits on top of +- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the *tool-boundary* constraint this runtime enforces architecturally +- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the *context-boundary* principle this runtime enforces for validator-role sessions +- [P0008 — Fresh-Validator Deliverable Is a DOLCHEO Ledger](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable) — the operationalized validator pattern this runtime hosts +- [Epistemic Modes](klappy://canon/epistemic-modes) — the parent canon defining the five modes whose role expressions this runtime supports +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the substrate-discipline this runtime extends to its own layer +- [Methodology Personification](klappy://canon/principles/methodology-personification) — why personas exist as canon objects in the first place +- [Oddie the River Guide — Voice Canon](klappy://canon/voice/oddie-the-river-guide) — the first worked example of a full persona profile +- [TinCan Real-Time Guide — Integration Spec](ams://docs/oddie/tincan-real-time-guide) — the first subscribed-session deployment target +- [Participation Replaces Integration](ams://canon/principles/participation-replaces-integration) — the topology principle this runtime instantiates for agent invocation +- [Voice as Cognitive Load Shedding](klappy://canon/principles/voice-as-cognitive-load-shedding) — why brand-discipline at the runtime layer is structural rather than cosmetic diff --git a/canon/methods/spawned-agent-session-runtime-contract.md b/canon/methods/spawned-agent-session-runtime-contract.md new file mode 100644 index 0000000..30f7410 --- /dev/null +++ b/canon/methods/spawned-agent-session-runtime-contract.md @@ -0,0 +1,343 @@ +--- +uri: klappy://canon/methods/spawned-agent-session-runtime-contract +title: "Spawned Agent Session Runtime Contract — Five Orthogonal Dimensions That Mechanize Existing Canon" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: draft +tags: ["canon", "methods", "spawned-agent-sessions", "runtime", "governance", "epistemic-modes", "engagement", "vodka-architecture", "mechanizes-canon"] +epoch: E0008.5 +date: 2026-05-10 +derives_from: "canon/epistemic-modes.md, canon/constraints/mode-discipline-and-bottleneck-respect.md, canon/constraints/critic-cannot-be-resolver.md, canon/constraints/audit-gates-are-spawned-agent-sessions.md, canon/methods/spawned-agent-session-substrate-options.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md, canon/principles/verification-requires-fresh-context.md" +complements: "canon/methods/governance-validation-via-agents.md, canon/constraints/canon-integration-audit.md" +governs: "Any spawned agent session dispatched on the runtime substrate. Specifies the five orthogonal session-configuration dimensions, the runtime's enforcement obligations against existing canon, and the composition rules that determine session shape from the dimension values. Substrate selection (where the session runs) is handled by klappy://canon/methods/spawned-agent-session-substrate-options; this doc handles configuration (how the session is parameterized)." +status: draft +--- + +# Spawned Agent Session Runtime Contract — Five Orthogonal Dimensions That Mechanize Existing Canon + +> A spawned agent session is fully characterized by five orthogonal dimensions: **persona** (voice and methodology), **mode** (epistemic state — exploration / planning / execution / validation), **role** (detection-only / resolver / general), **surface** (output context — real-time / audit / mentorship / sidebar-chat / etc.), and **engagement** (assistant / agent — turn-based dialogue or autonomous run-to-completion). The runtime's contribution is *mechanization*: the existing canon — epistemic modes, mode discipline, critic-cannot-be-resolver, voice and brand discipline, bottleneck respect — is enforced architecturally rather than left to prompt discipline. This doc specifies the dimensions, the runtime's enforcement obligations, and the composition rules that determine session shape from dimension values. The runtime adds no governance; it operationalizes existing governance for the agent surface. + +--- + +## Summary — The Runtime Mechanizes Canon, It Does Not Add Canon + +`klappy://canon/epistemic-modes` already establishes the four modes and explicitly licenses tools and processes to encode them: *"Tools, processes, and workflows may encode or enforce these modes, but they do not define them."* This method doc takes that license and specifies what encoding and enforcement look like for spawned agent sessions. + +`klappy://canon/constraints/audit-gates-are-spawned-agent-sessions` (Tier-1) names the abstract requirement for governance validation. `klappy://canon/methods/spawned-agent-session-substrate-options` catalogues where such sessions can run. **This doc specifies how sessions are configured once a substrate is chosen.** It applies regardless of substrate; the dimensions are substrate-independent. + +The runtime exposes a single primitive — invoke a session — parameterized by five orthogonal fields. Same primitive, many session shapes. Same persona, many sessions. Same canon, mechanically applied. + +--- + +## The Five Orthogonal Dimensions + +| Dimension | Values | What it determines | +|---|---|---| +| **Persona** | `oddie`, `audit-gate`, `docs-writer`, `general`, ... | Voice canon, system prompt URI, capability sources (operational + task-relevant MCP servers), inheritance | +| **Mode** | `exploration` \| `planning` \| `execution` \| `validation` | Tool allow-list, output schema, transition rules, primary-risk detector | +| **Role** | `detection-only` \| `resolver` \| `general` | Mutation rights, fresh-context requirements, session-to-session boundaries | +| **Surface** | `real-time-stream`, `audit`, `mentorship`, `sidebar-chat`, `code-output`, `synthesis-ledger`, ... | Density / pace / verbosity tolerance, post-processing rules, channel mapping | +| **Engagement** | `assistant` \| `agent` | Turn-control contract, bottleneck-respect enforcement, failure modes | + +These are orthogonal — no dimension is derivable from another. The same persona crosses modes, roles, surfaces, and engagements freely. Most dimension values can co-occur; some combinations are rare but legitimate (*Planning + agent* — autonomous canonical planning) while others are forbidden (*Validation + resolver in same session* — collapses critic and resolver, refused). + +The orthogonality is the test the abstraction passed. Earlier drafts considered collapsing role into mode, or deriving engagement from mode; both attempts produced coupling that broke real session shapes. + +--- + +## Persona + +A persona declares **who is speaking** in a session — voice, methodology, and capability sources. Personas are first-class canon objects, versioned, retrievable by URI. + +### Persona profile shape + +```yaml +persona: oddie +version: 1 +system_prompt_uri: klappy://canon/voice/oddie-the-river-guide +role_default: detection-only +mcp_servers: + operational: # always-on for this persona, regardless of task + - oddkit + task_relevant: # added per invocation based on task + [] +knowledge_bases: + - klappy:// +surface_profiles: + real_time_stream: { density: high, max_tokens_per_emission: 60 } + audit: { density: medium, structured_output: required } + mentorship: { density: low, narrative: true } + strategic_translation:{ density: medium, bidirectional: true } +brand_discipline_uri: klappy://canon/voice/oddie-the-river-guide#brand-guide +inheritance: + - klappy://canon/constraints/guide-posture + - klappy://canon/constraints/ai-voice-cliches +retraction_conditions: klappy://canon/voice/oddie-the-river-guide#retraction-conditions +``` + +### Operational vs task-relevant MCP servers + +A persona uses some MCP servers **on itself** for self-hygiene (e.g., Oddie uses `oddkit` for orient / search / challenge / gate to maintain his own epistemic discipline). Those are operational and always-on for that persona. Other MCP servers are task-relevant and added per invocation based on the task's needs (e.g., a GitHub MCP for an audit on a PR). + +The runtime MUST NOT strip operational MCP servers as "unrelated to the task." Doing so breaks personas like Oddie that use the methodology on themselves, not just on content. + +### Persona resolution + +`runtime.invoke(persona="oddie", mode="validation", role="detection-only", surface="audit", engagement="agent", task="...")` triggers the runtime to: + +1. Resolve `persona="oddie"` to the profile via canon URI lookup. +2. Compose the system prompt from the profile's `system_prompt_uri` plus mode-specific scaffolding plus surface-specific scaffolding. +3. Register operational MCP servers from the profile. +4. Filter the requested tool set against mode + role allow-lists. +5. Apply surface-profile output rules and brand-discipline post-processing per the profile. + +New personas are added by writing a profile, not by writing infrastructure. + +--- + +## Mode + +The four canonical epistemic modes from `klappy://canon/epistemic-modes` map directly to runtime configurations. Each mode constrains tool allow-list, output schema, transition rules, and the primary risk the runtime watches for. + +### Exploration + +- **Truth condition** (canon): valid if it reveals something new. +- **Tool allow-list**: search, fetch, orient, challenge, web-search, oddkit query tools. Read-heavy. +- **Forbidden**: artifact-mutating tools (commit, PR creation, canon edits) — the session cannot accidentally cross into execution. +- **Output schema**: emissions tagged `question | possibility | tension | frame | synthesis-ledger-entry`. The runtime can require an output-kind field per emission. +- **Risk detector**: false closure. If the session emits more `decision` or `recommendation` outputs than `question` or `tension`, the runtime flags premature convergence. +- **Output destination**: synthesis ledgers (`klappy://docs/synthesis-ledger`) are the natural durable surface. + +### Planning + +- **Truth condition** (canon): valid if assumptions are visible and challengeable. +- **Tool allow-list**: search, fetch, orient, challenge, gate, encode (drafting), preflight. Reads plus draft-write to scratch only. +- **Forbidden**: mutations to real artifacts (canon, code, deployed config). +- **Output schema**: every plan emission MUST declare `assumptions: [...]`, `deferred: [...]`, `would_invalidate: [...]`. A plan emitted without these is rejected as incomplete per the canon's "assumptions visible and challengeable" truth condition. +- **Risk detector**: speculative certainty. Outputs phrased as facts where the underlying claim is unverified — the runtime can ask the agent to mark uncertainty explicitly. + +### Execution + +- **Truth condition** (canon): valid if it produces verifiable outcomes. +- **Tool allow-list**: full set, scoped at session start, **locked**. Cannot expand mid-session. +- **Forbidden**: tool calls outside the locked scope. Mode reversion to planning is allowed but requires explicit reversion declaration. +- **Output schema**: artifacts and evidence. Status emissions classified `assertion | reversion | tool_call_request | progress`. For `engagement=agent`, clarifying questions are refused per bottleneck-respect canon. For `engagement=assistant`, clarifying questions are valid turn-yielding emissions. +- **Risk detector**: metric laundering. The runtime can require artifact references in completion claims. +- **Anti-pattern detector**: per `klappy://canon/epistemic-modes` §Non-Collapse Rule, "execution must not pretend to validate." Mid-build pivot emissions get flagged: note the concern, carry forward, do not surface as inline pivot. + +### Validation + +- **Truth condition** (canon): valid if findings are grounded in the produced artifact, not in what the validator wished had been built. +- **Required**: fresh context. The runtime refuses same-session transitions from `execution` to `validation`. Validation requires a new session that receives the artifact-under-test as input but does not inherit the executor's reasoning. This realizes `klappy://canon/principles/verification-requires-fresh-context` as a structural feature. +- **Tool allow-list**: read-only on the artifact under test, plus search / fetch / audit / oddkit-validate. +- **Forbidden**: mutations to the artifact under test. Findings are reports, not patches. +- **Output schema**: each finding MUST carry a disposition — `fix | pivot | accept`. A finding without disposition is rejected as incomplete per the canon. +- **Risk detector**: scope creep. Findings that propose redesign rather than report defects are flagged. The validation session does not get to reopen planning; that requires explicit reversion. + +### Mode-collapse anti-patterns become runtime detectors + +`klappy://canon/epistemic-modes` §Non-Collapse Rule names six specific anti-patterns. Each maps to a runtime check: + +1. *Exploration pretending to decide* → premature-closure detector in exploration mode. +2. *Planning pretending to execute* → mutation-attempt detector in planning mode (refused at submit time). +3. *Execution exploring alternatives retroactively* → scope-violation detector when tool calls fall outside the locked allow-list. +4. *Execution pretending to validate* → mid-build pivot detector — flag and instruct "note concern, carry forward." +5. *Validation pretending to plan* → redesign-instead-of-finding detector — flag and refuse. +6. *Validation pretending to execute* → mutation-attempt detector in validation mode (refused at submit time). + +Most resolve to schema-level rules and tool allow-lists. Sophistication is not required. + +--- + +## Role + +Role declares the **corruption boundary** the session respects. Three values, derived from `klappy://canon/constraints/critic-cannot-be-resolver`. + +### detection-only + +The session detects and reports. It does not mutate the artifact-under-observation. The runtime enforces this structurally: + +- **Tool filter**: filesystem writes, `git commit`, mutating API verbs (POST/PATCH/DELETE/PUT to write endpoints), `gh pr merge`, and any other state-modifying operations are refused at submit time. Refused before the session starts, not by prompt instruction. +- **Session-to-session boundary**: the same session cannot be re-invoked with a "now fix what you found" follow-up task. Resolution requires a fresh session that receives the finding as input but not the detector's reasoning. This is `critic-cannot-be-resolver` made architectural. + +The audit gate is the worked detection-only consumer. Oddie is detection-only across all his surfaces by canon (`klappy://canon/voice/oddie-the-river-guide` §What Oddie Is Not). + +### resolver + +The session is permitted to mutate artifacts within the session's locked scope. Mutating tools are allowed. Resolver sessions cannot also serve as their own validators — validation of a resolver's output requires a separate session per the fresh-context rule. + +### general + +No special role enforcement. Used for sessions that are neither pure detection nor pure resolution — exploration, planning, mentorship, strategic translation, and other dialogue-heavy sessions where the role distinction is not load-bearing. + +--- + +## Surface + +Surface declares the **output context** — who consumes the emission and at what density / pace / verbosity tolerance. Surfaces are persona-relative; a persona profile lists the surfaces it supports and the configuration for each. + +Common surface types and their characteristics: + +- **`real-time-stream`** — high density, continuous machine-speed inflow, brevity paramount, single-sentence emissions or short bursts. Agent engagement only (no caller dialogue at this density). +- **`audit`** — medium density, batch delivery, structured output (findings + disposition), tolerates moderate detail. +- **`sidebar-chat`** — medium density, conversational pace, narrative tolerated, assistant engagement only (the surface IS the dialogue). +- **`mentorship`** — low density, conversational, narrative is the point, assistant engagement preferred. +- **`strategic-translation`** — variable density, bidirectional, voice adapts most across surfaces but character stays constant. +- **`code-output`** — structured artifact, tagged machine for post-processing, agent engagement preferred. +- **`synthesis-ledger`** — tagged human, allows possibilities and tensions, exploration mode's natural durable surface. + +### Surface drives output post-processing + +Voice canon brand-discipline rules are mechanically enforceable. The runtime: + +- Tags every output field as `machine` or `human` per the surface profile. +- Strips persona emoji from machine fields before delivery — the absolute ban from `klappy://canon/voice/oddie-the-river-guide` §Brand Guide on persona emoji in JSON, YAML, code, commit messages, status titles, URIs, file paths. +- Honors a session-level mode toggle: `persona | neutral | strict`. Neutral and strict modes suppress persona emoji across all fields regardless of `human` tagging. Functional status emoji (`✅ ⚠️ 🔴 ⏳ 🟡`) survive across all toggles per canon — they are information not character. +- Applies density caps from the surface profile. A `real-time-stream` emission exceeding `max_tokens_per_emission` fails validation; the agent retries shorter. Brevity-under-pressure becomes structural rather than aspirational. + +This is the runtime doing for voice what TLS does for transport: a mechanical layer that prevents the contract from being accidentally violated by the agent inside. + +--- + +## Engagement + +Engagement declares **whether the caller is in the loop**. Two values; the dimension absorbs the question of whether clarifying questions are valid output. + +### `assistant` — turn-based dialogue + +- Caller has explicitly opted into being part of the loop. +- Clarifying questions are valid output. +- The session can yield turn-control back to the caller and resume on the next message. +- Multi-turn state preserved across turns; context accumulates. +- Output includes turn-control markers: `holding | yielding | done`. +- Failure surfaces for caller redirection rather than terminating. +- Bottleneck-respect (`klappy://canon/constraints/mode-discipline-and-bottleneck-respect`) still applies — the bottleneck just consented to the dialogue. + +### `agent` — autonomous run-to-completion + +- Caller has handed off, not paired up. +- Clarifying questions are forbidden per bottleneck-respect canon. Either make the call or fail loudly with a named reason. +- Session locks scope at start, runs to completion or terminal failure. +- Output is the final artifact. No turn handoffs. +- Tool calls autonomous within scope. +- Failure terminates the session with a named error; the caller receives the failure but cannot redirect mid-task. + +### Why engagement is its own dimension + +Earlier drafts attempted to derive question-validity from mode alone. Three problems emerged: + +1. *Planning + agent is legitimate* (canonical repeatable planning tasks). If "planning ⇒ questions allowed" were a rule, autonomous planning would be impossible. +2. *Execution + assistant is legitimate* (supervised execution where operator preference matters at named decision points). If "execution ⇒ no questions" were a rule, supervised execution sessions would either lie or fail. +3. *Same persona at same surface in same mode and role* can deploy at either engagement (Oddie at TinCan stream-annotation is `agent`; Oddie at TinCan sidebar-chat is `assistant`). The two sessions share four of five dimensions. + +Engagement absorbs caller-in-loop semantics cleanly. The runtime's bottleneck-respect enforcement becomes engagement-aware rather than mode-tangled. + +--- + +## Composition Rules + +Five orthogonal dimensions yield (in principle) the cross-product of all values. In practice, some combinations are forbidden, some are rare-but-legitimate, and most are well-trodden. The runtime enforces the forbidden ones architecturally. + +### Forbidden combinations + +- **`role=detection-only` + execution-mode mutating tools requested** — detection-only filters mutators out of the allow-list before the session starts. Refused at submit time. +- **Same-session execution-to-validation transition** — refused; fresh context required per `klappy://canon/principles/verification-requires-fresh-context`. +- **`engagement=agent` + execution + clarifying-question emissions** — the runtime wraps clarifying questions as named failures rather than valid output. +- **`engagement=assistant` + `surface=real-time-stream`** — real-time stream density does not admit caller dialogue. The runtime rejects the combination at session-start. + +### Rare-but-legitimate combinations + +- **`mode=planning` + `engagement=agent`** — autonomous canonical planning. The agent must produce a plan with all assumptions, deferrals, and invalidation conditions named without asking. Possible for repeatable, well-specified planning tasks. +- **`mode=execution` + `engagement=assistant`** — supervised execution. Operator can interrupt; agent can yield at named decision points. Useful when the task admits multiple valid paths and operator preference matters. +- **`mode=exploration` + `engagement=agent`** — autonomous research scout. Returns a synthesis ledger; operator reviews. The scout cannot converge prematurely (false-closure detector active). + +### Well-trodden combinations (and their typical consumers) + +| Persona | Mode | Role | Surface | Engagement | Consumer | +|---|---|---|---|---|---| +| `audit-gate` | validation | detection-only | audit | agent | PR-blocking automation, canon-coherence cron | +| `oddie` | validation | detection-only | real-time-stream | agent | TinCan stream annotation | +| `oddie` | validation | detection-only | sidebar-chat | assistant | TinCan portal Q&A | +| `oddie` | validation | detection-only | audit | agent | PR auditor, scheduled reviews | +| `oddie` | validation | detection-only | mentorship | assistant | Guided review sessions | +| `docs-writer` | execution | resolver | code-output | agent | Autonomous doc generator | +| `docs-writer` | execution | resolver | code-output | assistant | Co-authoring with operator | +| `planning-helper` | planning | general | conversational | assistant | Plan-shaping with operator | +| `research-scout` | exploration | general | synthesis-ledger | agent | Autonomous discovery | +| `release-validator` | validation | detection-only | audit | agent | Per `klappy://canon/constraints/release-validation-gate` | + +--- + +## Enforcement Points — What the Runtime Mechanically Guarantees + +The runtime's contract to canon: + +1. **Mode discipline** (`klappy://canon/epistemic-modes`): tool allow-lists scoped per mode; mode-collapse anti-patterns detected per Non-Collapse Rule; transitions require explicit reversion. +2. **Bottleneck respect** (`klappy://canon/constraints/mode-discipline-and-bottleneck-respect`): clarifying questions refused for `engagement=agent` sessions; reversion declarations validated as single-named-cause. +3. **Critic-cannot-be-resolver** (`klappy://canon/constraints/critic-cannot-be-resolver`): detection-only role filters mutating tools; same-session execution-to-validation transitions refused; fresh-context required for validation. +4. **Verification requires fresh context** (`klappy://canon/principles/verification-requires-fresh-context`): inherited by validation mode's fresh-context requirement. +5. **Voice canon brand discipline** (`klappy://canon/voice/oddie-the-river-guide` §Brand Guide and inheritances thereof): persona emoji stripped from machine-tagged fields; mode toggle controls suppression scope; functional status emoji preserved across modes. +6. **Persona profile resolution**: operational MCP servers always-on; task-relevant MCP servers added per invocation; system prompt composed from URI plus mode/surface scaffolding. +7. **Substrate independence**: runtime contract is substrate-agnostic per `klappy://canon/methods/spawned-agent-session-substrate-options`. The same contract applies on Anthropic Managed Agents, on Cloudflare Sandboxes with any harness, on future entrants. + +The runtime adds nothing to canon. It applies canon mechanically. + +--- + +## What This Method Does NOT Promise + +- **Not a guarantee that agents follow canon perfectly.** Mechanical enforcement catches violations the runtime can detect at the schema and tool-call level. Voice violations inside human-tagged narrative output, subtle false-closure patterns, and other content-level drift may pass the runtime checks. Oddie's voice canon's 30-day production burn-in retraction window applies; mechanical checks reduce but do not eliminate the need for human review. +- **Not a replacement for canon.** Canon defines the rules; the runtime enforces a subset of them. Where the runtime cannot mechanically check (content-level voice, subtle reasoning quality), canon governance still applies via review surfaces. +- **Not a single substrate.** Substrate selection (Managed Agents / CF Sandboxes / future) is per `klappy://canon/methods/spawned-agent-session-substrate-options`. The contract holds across substrates; the implementation differs. +- **Not a coordination layer.** The runtime spawns sessions; it does not orchestrate workflows across sessions. Multi-session coordination (handoff between detector and resolver, sequencing of audit + iteration) is the caller's responsibility. Per AMS's `permanent-non-goals`, neither AMS nor the runtime owns orchestration. +- **Not a license to ignore mode declarations in conversation.** Humans operating in this project still declare modes out loud per `klappy://canon/constraints/mode-discipline-and-bottleneck-respect`. The runtime mechanizes mode discipline for agents; humans retain the obligation to declare modes for themselves. + +--- + +## Open Questions + +These remain explicitly unresolved at draft time and will be revisited as production evidence accrues. + +1. **Subscribed (long-lived) session shape.** The `session_type: "subscribed"` shape needed for Oddie's TinCan flagship surface (real-time stream interpretation) is sketched but not specified in detail. Backpressure handling, multi-output channel post-processing, and event-source connection semantics need their own treatment. Open. +2. **Output classification fidelity.** The proposed schema fields (e.g., `assertion | reversion | tool_call_request`) require a classifier that is reliable across personas. Heuristic-only classification may produce false positives that frustrate agents. Worth measuring before locking the schema. +3. **Persona profile evolution.** Versioned personas (`persona@v1`, `persona@v2`) will need migration semantics when a persona's profile changes incompatibly. Out of scope for this draft. +4. **Cross-session memory.** Personas may accumulate observations across sessions (e.g., Oddie noticing a recurring eddy across days). Whether and how the runtime supports persona-level memory between sessions is open. Default position: stateless per session unless explicitly opted in. +5. **Whether engagement deserves its own principle doc.** The dimension is well-defined here but doesn't yet have a standalone principle doc. If usage validates the orthogonality claim across many session shapes, a future principle doc on engagement-as-runtime-dimension may be warranted. Premature canon coinage is its own anti-pattern; the doc here defines engagement well enough for the runtime to operate on it. Let the dimension earn its standalone doc through use rather than coining a URI before there is content to put behind it. + +--- + +## Confidence + +**Draft.** Zero production validations of the runtime as a whole. Individual dimensions have independent grounding: + +- Mode discipline is established canon (`klappy://canon/epistemic-modes`, semi-stable). +- Critic-cannot-be-resolver is established canon (semi-stable). +- Voice canon and brand discipline are working belief with 30-day production burn-in (`klappy://canon/voice/oddie-the-river-guide`). +- Substrate options are evolving (`klappy://canon/methods/spawned-agent-session-substrate-options`, draft). +- Engagement as orthogonal dimension is novel synthesis from this draft session; unvalidated. + +The composition (five-dimension orthogonality, runtime-as-mechanizer) is a working belief grounded in (a) explicit canon license to encode modes in tools, (b) the worked example of Oddie whose existing canon already implies the persona-profile shape, and (c) the immediate consumer (audit gate) which exercises four of five dimensions on its first deployment. + +**Retraction conditions.** This contract retracts if: + +- The runtime ships and the dimensions prove non-orthogonal in practice — e.g., real session shapes routinely require fields outside this set, or fields within this set turn out to be derivable from each other after all. +- Mechanical enforcement of canon proves to degrade signal rather than improve it — e.g., agents systematically work around the schema constraints in ways that produce lower-quality outputs than unrestricted prompts. +- The persona profile shape proves insufficient to capture personas like Oddie at production density, requiring frequent ad-hoc extensions that fragment the abstraction. + +A weaker retraction path: if the dimensions hold but specific enforcement points (e.g., output-kind classification, brand-discipline post-processing) prove ineffective, those individual mechanizations retract while the overall contract survives. + +--- + +## See Also + +- [Epistemic Modes](klappy://canon/epistemic-modes) — the four canonical modes this contract operationalizes +- [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — the discipline this contract makes mechanical +- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the role-boundary constraint the runtime enforces structurally +- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle that motivates fresh-context enforcement on validation transitions +- [Audit Gates Are Spawned Agent Sessions](klappy://canon/constraints/audit-gates-are-spawned-agent-sessions) — the Tier-1 constraint the runtime serves +- [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options) — sibling method covering substrate selection +- [Oddie the River Guide](klappy://canon/voice/oddie-the-river-guide) — worked persona whose existing canon implies the persona-profile shape +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the principle that this contract embodies (substrate stays opinion-free; opinions live in the dimensions above it) +- [Governance Validation via Agents](klappy://canon/methods/governance-validation-via-agents) — sibling method on what gets checked; this doc covers how the checking session is configured diff --git a/journal/2026-05-10-runtime-canon-divergence.tsv b/journal/2026-05-10-runtime-canon-divergence.tsv new file mode 100644 index 0000000..9a8105d --- /dev/null +++ b/journal/2026-05-10-runtime-canon-divergence.tsv @@ -0,0 +1,5 @@ +type typeName facet quality_score quality_max quality_level title content +O Observation 4 5 medium Two runtime docs in this PR represent two iterations of the same architectural concept The prior compacted session produced spawned-agent-session-runtime-contract.md (Tier 2, draft, five-orthogonal-dimensions framing: persona, mode, role, surface, engagement). The current session produced persona-shaped-agent-runtime.md (Tier 1, proposed, mode-bound-roles framing aligned to operator's later guidance about session-per-mode discipline). Both files are committed to preserve the work, but they overlap heavily and would be confusing if both landed as canon. Operator should pick one or reconcile during review. +L Learning 4 5 medium Engagement (assistant vs agent) is a useful dimension missing from the persona-shaped framing The runtime-contract draft introduced an "engagement" dimension distinguishing turn-based dialogue (assistant — clarifying questions valid; yields turn-control) from autonomous run-to-completion (agent — clarifying questions forbidden per bottleneck-respect canon). This dimension is genuinely orthogonal to persona, mode, role, and surface, and is missing from the persona-shaped doc. If the persona-shaped doc is selected as canonical, engagement should be folded in. +D Decision 3 5 medium Recommend persona-shaped-agent-runtime as the canonical doc; runtime-contract as historical context The persona-shaped doc reflects operator's later directives (five-role taxonomy, sessions-mirror-modes derivation, mode-transitions-require-encoded-handoff derivation) and aligns with the new principle and constraint that just landed in the parallel mode-discipline canon PR. The runtime-contract draft predates that guidance. Recommend keeping persona-shaped as canon and either (a) folding engagement-dimension content into persona-shaped before merge, or (b) keeping runtime-contract as a draft sibling for the engagement-dimension framing if operator wants it preserved. +H Handoff 4 5 medium Runtime canon ready for review; depends on PR A (substrate options) and PR C (mode-discipline canon) PR D references URIs that land in PR A (klappy://canon/methods/spawned-agent-session-substrate-options) and PR C (klappy://canon/principles/sessions-mirror-modes, klappy://canon/constraints/mode-transitions-require-encoded-handoff). Recommend merging PR A and PR C first; PR D's URIs resolve once they land. Operator should also reconcile the two runtime docs before this PR merges. diff --git a/journal/2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv b/journal/2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv new file mode 100644 index 0000000..905c8c4 --- /dev/null +++ b/journal/2026-05-10-spawned-agent-runtime-and-five-dimension-contract.tsv @@ -0,0 +1,27 @@ +type typeName facet quality_score quality_max quality_level title content +D Decision 5 5 strong Audit migration generalizes one layer up to a generic spawned-agent-session runtime The work originally scoped as "migrate the audit gate from Managed Agents to CF Sandboxes" generalizes to a generic spawned-agent-session runtime — a sibling vodka-architecture substrate to AMS. AMS is the wire (pub-sub messaging between agents); the runtime is the execution surface (one-shot or subscribed agent sessions on demand). Both are opinion-free. Both compose without either knowing about the other. The audit gate becomes one consumer; many consumers follow without infrastructure work per participation-replaces-integration. Operator named the generalization in one line ("can't we abstract the prompt to outside to make this reusable substrate for anything we do?"); architectural shape was sitting one inference away from where Claude initially stopped. +D Decision 5 5 strong The runtime contract is parameterized by five orthogonal dimensions A spawned-agent-session is fully characterized by five orthogonal fields: persona (voice + methodology + capability sources), mode (exploration/planning/execution/validation), role (detection-only/resolver/general), surface (real-time/audit/mentorship/sidebar-chat/etc.), and engagement (assistant/agent). These do not collapse into each other. Same persona at different (mode, role, surface, engagement) combinations is a different session. Oddie at TinCan stream-annotation (validation, detection-only, real-time-stream, agent) and Oddie at TinCan sidebar-chat (validation, detection-only, sidebar-chat, assistant) are two sessions sharing only persona. +D Decision 5 5 strong Engagement (assistant vs agent) is the dimension that determines bottleneck-respect contract Assistant engagement = turn-based dialogue with caller; clarifying questions valid; session yields turn-control; multi-turn state preserved. Agent engagement = run-to-completion autonomy; clarifying questions forbidden per bottleneck-respect canon; failure terminates with named reason. The bottleneck (caller's attention) consents differently in each case, which is what changes the contract. This dimension absorbs ambiguity that previously required deriving "should this agent ask?" from mode alone. +D Decision 5 5 strong The runtime mechanizes existing canon rather than adding governance The new runtime contract does not invent governance. It operationalizes mode discipline (klappy://canon/epistemic-modes), critic-cannot-be-resolver (klappy://canon/constraints/critic-cannot-be-resolver), bottleneck respect (klappy://canon/constraints/mode-discipline-and-bottleneck-respect), voice canon (klappy://canon/voice/oddie-the-river-guide), and brand discipline (Oddie voice canon §Brand Guide) for any agent that opts in. The canon already explicitly licenses this in epistemic-modes' Scope section: "Tools, processes, and workflows may encode or enforce these modes, but they do not define them." +O Observation 5 5 strong Each canonical mode maps cleanly to runtime mechanics (tool allow-list, output schema, transition rules, risk detector) Exploration: read-heavy tools, outputs tagged question/possibility/tension/frame, false-closure detector. Planning: read + draft-write-to-scratch, outputs require assumptions/deferrals/invalidation conditions, speculative-certainty detector. Execution: full tool set locked at session start, outputs are artifacts plus assertion/reversion classifications, metric-laundering detector, no clarifying questions for agent engagement. Validation: read-only on artifact-under-test, fresh-context required (refuse same-session execution-to-validation transition), findings carry fix/pivot/accept disposition, scope-creep detector. The six canonical mode-collapse anti-patterns map directly to runtime classifiers. +O Observation 5 5 strong Brand discipline is mechanically enforceable at the runtime layer Oddie's voice canon (klappy://canon/voice/oddie-the-river-guide §Brand Guide) names an absolute ban on persona emoji on machine surfaces (JSON, YAML, code, status titles, URIs, commits, file paths). The runtime can enforce by tagging output fields machine vs human and post-processing accordingly. Mode toggle (persona/neutral/strict) controls suppression. Functional status emoji (✅⚠️🔴⏳🟡) survive across modes per canon — they are information not character. This converts brand discipline from prompt-following to architectural guarantee. +O Observation 5 5 strong Critic-cannot-be-resolver is structurally enforceable, not just disciplinary The constraint (klappy://canon/constraints/critic-cannot-be-resolver) maps to a runtime feature: detection-only sessions filter mutating tools out of the allow-list at submit time. Filesystem writes, git commit, mutating API calls, gh pr merge are refused regardless of prompt content. Same-session transitions from detection to remediation are refused; resolution requires a fresh session that receives the finding as input but not the detector's reasoning. This is canon as code, not canon as discipline. +O Observation 5 5 strong Oddie's existing canon already specifies a persona-profile shape that any reusable runtime must support Voice canon plus TinCan integration spec together specify: system prompt URI, two capability sources (oddkit MCP + klappy.dev knowledge base, where oddkit is operational not task-relevant — Oddie uses oddkit on himself for self-hygiene), role declaration (detection-only), four named surfaces with distinct density/pace/verbosity tolerances, voice register, brand discipline, retraction conditions. That is enough structure to be its own canon shape: a persona profile is a declarative bundle the runtime resolves to operational configuration. +O Observation 5 5 strong Anthropic ships official subscription-billed CI auth — the catalog overstated complexity Anthropic Claude Code documents claude setup-token as the supported headless auth path; it produces CLAUDE_CODE_OAUTH_TOKEN suitable for setEnvVars in a CF Sandbox. Cloudflare ships an official maintained template (npm create cloudflare@latest -- ams-audit-worker --template=cloudflare/sandbox-sdk/examples/claude-code) where Claude Code is preinstalled in the Sandbox container image. The catalog's "operationally non-trivial" CI auth caveat and "ToS gray area" note are both overstated and want softening on next edit. Phase 0 spike work is entirely Borrow-shaped, not Build. +L Learning 5 5 strong When operator names a generalization, the runtime usually saved is bigger than the immediate target Initial framing was project-local (audit migration). Generalization sat one inference away (reusable substrate for any spawned-agent-session task in any project). Pattern: when scoping work that calls existing primitives in new ways, ask whether the new call site reveals an unwritten primitive at one layer up. Vodka architecture rewards this question. +L Learning 5 5 strong The five-dimension contract is the right abstraction because each dimension stays orthogonal No dimension collapses into another. Same persona crosses modes, roles, surfaces, engagements freely. Mode does not imply role (validation can be detection-only OR resolver — the audit gate is the former; an iteration-on-validation-findings agent is the latter). Role does not imply mode (detection-only applies in validation but also in monitoring/observability). Engagement does not imply mode (planning is natural fit for assistant but admits agent for canonical planning tasks; execution is natural fit for agent but admits assistant for supervised execution). Orthogonality is the test the abstraction passed. +L Learning 4 5 strong Designing for the hardest surface produces voice constraints that transfer downward Oddie's flagship use case (real-time stream interpretation, ams://canon/observations/oddie-flagship-use-case) is the highest-density surface; voice constraints calibrated for it work on lower-density surfaces but not vice versa. The same logic applies to runtime design: building for the hardest combination (subscribed dual-output session with strict mode discipline) yields a runtime that handles simpler combinations naturally. Reverse path is not guaranteed. +L Learning 4 5 strong Borrow-first beats spike-first when an official maintained template exists Cloudflare ships the claude-code template as a maintained example in the sandbox-sdk repo. Cloudflare's first-party tutorial documents the headless flow. Anthropic ships claude setup-token for headless auth. Three other production writeups (Daniel Avila, Daytona+CF, Neon) extend the same pattern. Phase 0 of the build is borrow + adapt, not spike from scratch. Confirms 6B method's Borrow stage as the default first move per klappy://canon/constraints/borrow-evaluation-before-implementation. +C Constraint 5 5 strong Detection-only role is enforced architecturally — mutating tools are refused at submit time When role=detection-only, the runtime filters the requested tool set against a read-only allow-list. Filesystem writes, git commit, mutating API verbs, gh pr merge, and any other state-modifying operations are refused before the session starts. Same-session transition from detection to remediation is refused; fresh session required. This realizes critic-cannot-be-resolver as a structural runtime feature rather than a behavioral preference. +C Constraint 5 5 strong Validation mode requires fresh context — same-session execution-to-validation transitions are refused The runtime refuses to convert an in-flight execution session into a validation session. Validation requires a new session that receives the artifact-under-test as input but does not inherit the executor's reasoning. This realizes verification-requires-fresh-context as a structural runtime feature for the agent surface. +C Constraint 5 5 strong Persona emoji are stripped from machine-tagged output fields regardless of mode Output fields tagged machine (JSON/YAML/code/URIs/commit messages/status titles/file paths) have persona emoji stripped before delivery. Output fields tagged human keep full emoji discipline subject to mode toggle (persona/neutral/strict). Functional status emoji (✅⚠️🔴⏳🟡) persist across modes per canon. This realizes Oddie's voice-canon brand-discipline as a runtime post-processing step. +C Constraint 4 5 strong Operational MCP servers are always-on for a persona; task-relevant MCP servers are added per invocation Persona profiles distinguish operational MCP servers (always registered for that persona — Oddie uses oddkit on himself) from task-relevant MCP servers (added per session based on the task's needs). The runtime does not strip operational MCP servers as "unrelated to the task" because the agent itself uses them for behavior. Naive task-aware filtering breaks Oddie. +C Constraint 4 5 strong Engagement field gates clarifying-question emissions When engagement=agent, clarifying questions emitted by the agent are wrapped as named failures rather than valid output. When engagement=assistant, clarifying questions are valid turn-yielding emissions and the session pauses for caller response. The runtime does not need to derive question-validity from mode alone; the engagement field absorbs the question of whether the caller is in the loop. +E Encode 5 5 strong klappy.dev PR #184 — vendor-neutral rename + substrate-options method PR opened 2026-05-10 against klappy/klappy.dev branch claude/audit-gate-rename-7956. Renames klappy://canon/constraints/audit-gates-are-managed-agents to ...audit-gates-are-spawned-agent-sessions. Adds klappy://canon/methods/spawned-agent-session-substrate-options. Mergeable, no required CI configured, awaiting operator merge. https://github.com/klappy/klappy.dev/pull/184 +E Encode 5 5 strong AMS PR #75 — companion adoption-pointer rename PR opened 2026-05-10 against klappy/agent-messaging-service branch claude/canon-code-sync-rename-40ff. Renames ams://canon/constraints/canon-code-sync-via-managed-agent to ...canon-code-sync-via-spawned-agent-session. Updates derives_from to new klappy.dev URIs and updates URI references in workflow YAML and audit-via-agent.py. Sequencing: depends on klappy.dev PR #184 merging first. https://github.com/klappy/agent-messaging-service/pull/75 +H Handoff 5 5 strong Draft a runtime-contract canon doc as the next planning artifact The five-dimension contract (persona × mode × role × surface × engagement) earns its own canon doc. Likely Tier-2 method at klappy://canon/methods/agent-governance-runtime that names the dimensions, maps each to existing canon (epistemic-modes, mode-discipline-and-bottleneck-respect, critic-cannot-be-resolver, voice canons), and specifies enforcement points. May spawn a Tier-2 principle (klappy://canon/principles/engagement-as-runtime-dimension) naming why engagement is its own dimension rather than derivable from mode. This is a planning-mode artifact; explicit assumptions, deferrals, and invalidation conditions required. +H Handoff 4 5 strong Catalog method doc wants softening on CI-auth and ToS caveats klappy://canon/methods/spawned-agent-session-substrate-options (landing in PR #184) overstates two things: "operationally non-trivial" CI auth (it is one line: setEnvVars({CLAUDE_CODE_OAUTH_TOKEN: env.TOKEN}) and Anthropic ships claude setup-token officially), and "ToS gray area" (Anthropic supports headless OAuth tokens explicitly; this is officially supported, not gray). Soften both on next edit. Not blocking for the merge — content is correct; tone is overcautious. +H Handoff 4 5 strong Phase 0 of substrate build is pure borrow npm create cloudflare@latest -- ams-audit-worker --template=cloudflare/sandbox-sdk/examples/claude-code is the starter. Sandbox SDK container ships with Claude Code preinstalled. CF first-party tutorial at developers.cloudflare.com/sandbox/tutorials/claude-code/. Three production writeups extend the same pattern (Daniel Avila claude-code-templates, Daytona+CF Nightona, Neon full-stack agent). Phase 0 is borrow + adapt template's prompt to AMS audit role. Half-day at most. +H Handoff 4 5 strong Phase 1 builds runtime as generic primitive, not audit-specific Worker The audit gate is one consumer of the runtime. Phase 1 builds the generic primitive that admits multiple consumers from day one (HTTP API for one-shot sessions; subscribed sessions to follow). Audit gate exercises persona profile resolution, role enforcement (detection-only), surface profile post-processing (audit), and mode (validation) without needing the harder subscribed-session shape. 2-3 days vs 1-2 for audit-only. Pays back the moment the second consumer lands. +H Handoff 3 4 adequate After PRs land — second consumer of the runtime exercises the abstraction Once PR #184 + #75 land and Phase 1 ships, second consumer (TBD: Slack on-demand review, scheduled canon-coherence cron, or another) validates that the abstraction holds by adding a different trigger path with the same runtime. The abstraction earns its keep when consumer 2 lands quickly because consumer 1 paid the infrastructure cost. +H Handoff 3 4 adequate Agent-self-report-under-stress observations may want generalization klappy://canon/principles/agent-self-report-under-stress documents incidents from three Anthropic Managed Agents sessions on 2026-04-19. The principle scope notes the limitation. With the substrate-options canon now landing, the principle may want a generalization pass to cover any spawned-agent-session substrate where mid-session pressure can change agent behavior. Not in scope for current PRs; flag for later canon hygiene. From a5bb77db604e54c04b12639fbd48a38853247262 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 10 May 2026 04:21:01 +0000 Subject: [PATCH 2/9] Fix TSV column misalignment in runtime-canon-divergence journal --- journal/2026-05-10-runtime-canon-divergence.tsv | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/journal/2026-05-10-runtime-canon-divergence.tsv b/journal/2026-05-10-runtime-canon-divergence.tsv index 9a8105d..4fd3eb1 100644 --- a/journal/2026-05-10-runtime-canon-divergence.tsv +++ b/journal/2026-05-10-runtime-canon-divergence.tsv @@ -1,5 +1,5 @@ type typeName facet quality_score quality_max quality_level title content -O Observation 4 5 medium Two runtime docs in this PR represent two iterations of the same architectural concept The prior compacted session produced spawned-agent-session-runtime-contract.md (Tier 2, draft, five-orthogonal-dimensions framing: persona, mode, role, surface, engagement). The current session produced persona-shaped-agent-runtime.md (Tier 1, proposed, mode-bound-roles framing aligned to operator's later guidance about session-per-mode discipline). Both files are committed to preserve the work, but they overlap heavily and would be confusing if both landed as canon. Operator should pick one or reconcile during review. -L Learning 4 5 medium Engagement (assistant vs agent) is a useful dimension missing from the persona-shaped framing The runtime-contract draft introduced an "engagement" dimension distinguishing turn-based dialogue (assistant — clarifying questions valid; yields turn-control) from autonomous run-to-completion (agent — clarifying questions forbidden per bottleneck-respect canon). This dimension is genuinely orthogonal to persona, mode, role, and surface, and is missing from the persona-shaped doc. If the persona-shaped doc is selected as canonical, engagement should be folded in. -D Decision 3 5 medium Recommend persona-shaped-agent-runtime as the canonical doc; runtime-contract as historical context The persona-shaped doc reflects operator's later directives (five-role taxonomy, sessions-mirror-modes derivation, mode-transitions-require-encoded-handoff derivation) and aligns with the new principle and constraint that just landed in the parallel mode-discipline canon PR. The runtime-contract draft predates that guidance. Recommend keeping persona-shaped as canon and either (a) folding engagement-dimension content into persona-shaped before merge, or (b) keeping runtime-contract as a draft sibling for the engagement-dimension framing if operator wants it preserved. -H Handoff 4 5 medium Runtime canon ready for review; depends on PR A (substrate options) and PR C (mode-discipline canon) PR D references URIs that land in PR A (klappy://canon/methods/spawned-agent-session-substrate-options) and PR C (klappy://canon/principles/sessions-mirror-modes, klappy://canon/constraints/mode-transitions-require-encoded-handoff). Recommend merging PR A and PR C first; PR D's URIs resolve once they land. Operator should also reconcile the two runtime docs before this PR merges. +O Observation 4 5 medium Two runtime docs in this PR represent two iterations of the same architectural concept The prior compacted session produced spawned-agent-session-runtime-contract.md (Tier 2, draft, five-orthogonal-dimensions framing: persona, mode, role, surface, engagement). The current session produced persona-shaped-agent-runtime.md (Tier 1, proposed, mode-bound-roles framing aligned to operator's later guidance about session-per-mode discipline). Both files are committed to preserve the work, but they overlap heavily and would be confusing if both landed as canon. Operator should pick one or reconcile during review. +L Learning 4 5 medium Engagement (assistant vs agent) is a useful dimension missing from the persona-shaped framing The runtime-contract draft introduced an "engagement" dimension distinguishing turn-based dialogue (assistant — clarifying questions valid; yields turn-control) from autonomous run-to-completion (agent — clarifying questions forbidden per bottleneck-respect canon). This dimension is genuinely orthogonal to persona, mode, role, and surface, and is missing from the persona-shaped doc. If the persona-shaped doc is selected as canonical, engagement should be folded in. +D Decision 3 5 medium Recommend persona-shaped-agent-runtime as the canonical doc; runtime-contract as historical context The persona-shaped doc reflects operator's later directives (five-role taxonomy, sessions-mirror-modes derivation, mode-transitions-require-encoded-handoff derivation) and aligns with the new principle and constraint that just landed in the parallel mode-discipline canon PR. The runtime-contract draft predates that guidance. Recommend keeping persona-shaped as canon and either (a) folding engagement-dimension content into persona-shaped before merge, or (b) keeping runtime-contract as a draft sibling for the engagement-dimension framing if operator wants it preserved. +H Handoff 4 5 medium Runtime canon ready for review; depends on PR A (substrate options) and PR C (mode-discipline canon) PR D references URIs that land in PR A (klappy://canon/methods/spawned-agent-session-substrate-options) and PR C (klappy://canon/principles/sessions-mirror-modes, klappy://canon/constraints/mode-transitions-require-encoded-handoff). Recommend merging PR A and PR C first; PR D's URIs resolve once they land. Operator should also reconcile the two runtime docs before this PR merges. From 3e88ee25504a60d1797a4b9dcbd1b0f27d3bb6a2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 10 May 2026 04:32:12 +0000 Subject: [PATCH 3/9] canon: add Engagement dimension + Parallelism + Operator Override to persona-shaped runtime MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds three sections to canon/methods/persona-shaped-agent-runtime addressing gaps surfaced during continued architectural pressure-testing: §6 Honor the Engagement Contract — folds in the engagement dimension (assistant vs agent) from the parallel runtime-contract draft. Distinguishes turn-based dialogue (clarifying questions valid; bottleneck in the loop) from autonomous run-to-completion (clarifying questions wrapped as named failures per bottleneck-respect canon). The engagement field is orthogonal to mode, role, and surface — same persona at same mode/role can be invoked under either engagement contract. §7 Support Parallelism and Operator Override — articulates which parallelism patterns the runtime supports and which it refuses, derived from the parallelism-patterns section in canon/principles/sessions-mirror-modes. Within-mode fan-out is encouraged, multi-participant single sessions are allowed within a mode, cross-mode parallelism on different artifacts is independent. Cross-mode on the same artifact is the only forbidden pattern and is enforced at submit time. Operator override mechanism is sketched as a runtime-invocation parameter that records journal entries at start and end, relaxes role enforcement for declared-collapsed transitions, and tags downstream metadata. Conversational-mode orchestration is framed as a consumer pattern, not a runtime feature. Net: +84 lines, no changes to existing sections. Resolves the engagement-dimension gap noted in the runtime-canon-divergence journal entry. Operator decision still pending on whether to keep runtime-contract.md as a draft sibling or supersede it now that engagement content has been folded into the persona-shaped doc. --- canon/methods/persona-shaped-agent-runtime.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/canon/methods/persona-shaped-agent-runtime.md b/canon/methods/persona-shaped-agent-runtime.md index 696ea1a..91644cf 100644 --- a/canon/methods/persona-shaped-agent-runtime.md +++ b/canon/methods/persona-shaped-agent-runtime.md @@ -188,6 +188,90 @@ A subscribed session needs: connection management, multi-output channels (per-ch --- +### 6. Honor the Engagement Contract + +Sessions invoke the runtime under one of two engagement modes — *assistant* or *agent* — and the runtime enforces different turn-control and bottleneck-respect contracts for each. This dimension is orthogonal to mode, role, and surface. The same persona in the same mode and role can be invoked under either engagement; what changes is who controls the turn and how the session terminates. + +**`assistant`** — turn-based dialogue with the caller. The session emits a response and yields turn-control back to the caller. Clarifying questions are valid output. State persists across turns. The caller's attention is in the loop; the session paces itself to that. Pair-programming surfaces, sidebar chat, mentorship interactions, and any conversational use case are typically assistant-engagement. + +**`agent`** — autonomous run-to-completion. The session does not yield turn-control until the task is complete or a named failure terminates it. Clarifying questions are forbidden per [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — they pull the bottleneck (caller's attention) into work the caller was not in the loop for. The runtime wraps any clarifying-question emission as a named failure rather than a valid output. Stuck or under-specified sessions terminate with the failure named, allowing the caller to fix the input and retry rather than respond to mid-flight questions. Audit gates, scheduled jobs, fan-out workers, and any background dispatch are typically agent-engagement. + +The distinction matters because the caller's consent to interruption differs. An assistant session implies *"I will be here to answer questions when they come up."* An agent session implies *"I have given you everything you need; come back when you have a result or a clean failure."* Conflating the two corrupts both: assistant-shaped agents produce output the caller didn't ask for; agent-shaped assistants accumulate questions the caller never sees. + +The engagement field is part of the session-invocation parameter set: + +``` +runtime.invoke( + persona="oddie", + role="validator", + surface="audit", + engagement="agent", # autonomous; no clarifying questions + task="..." +) +``` + +Most consumer patterns map cleanly: scheduled audits are `agent`; sidebar Q&A is `assistant`; pair-programming with an assistant persona is `assistant`. A few patterns are rare-but-legitimate: planning under `agent` engagement (autonomous canonical planning when the planner-persona has enough context to produce a complete plan without dialogue) is allowed but requires the persona to be confident the input is complete. The runtime supports the rare combinations; consumers choose which to use. + +--- + +### 7. Support Parallelism and Operator Override + +Two patterns the runtime needs to handle that are orthogonal to role enforcement: concurrent sessions in the same mode, and operator-declared mode collapse for urgency. + +#### Parallelism + +Per [Sessions Mirror Modes §Parallelism Patterns](klappy://canon/principles/sessions-mirror-modes), the runtime supports three of four parallelism patterns: + +- **Within-mode fan-out.** Multiple sessions of the same role spawned concurrently — multiple explorers on different angles, multiple validators with different lenses, multiple builders on independent scope. The runtime spawns N concurrent sessions; the consumer is responsible for fan-in (consolidating outputs into a single encoded handoff for the next mode). +- **Multi-participant single session.** Multiple agents collaborating within one role-bound session, sharing context, producing a joint deliverable. The runtime treats this as one session with multiple participant identities. The session is bound to one mode; participants share the mode's tool restrictions. +- **Cross-mode parallelism on different artifacts.** Independent work streams running concurrently. The runtime spawns and tracks them independently; no coordination is required because the streams do not share artifacts. + +The runtime *refuses* the fourth pattern: cross-mode sessions on the same artifact. A validator session cannot be invoked on an artifact whose builder session has not yet produced an encoded handoff (artifact + claims declaration). This is enforced at submit time — the runtime checks the artifact's handoff state before accepting a downstream-role invocation. + +Fan-in is a consumer concern, not a runtime feature. The runtime spawns parallel sessions and returns their outputs; consolidating those outputs into a single handoff for the next mode is the consumer's job. The runtime can support this with conventions (e.g., a fan-in helper that takes N session outputs and produces a consolidated DOLCHEO ledger), but the conventions are layered above the core runtime. + +#### Operator Override + +Per [Mode Transitions Require Encoded Handoff §Operator Override](klappy://canon/constraints/mode-transitions-require-encoded-handoff), the runtime accepts an explicit override declaration that collapses mode boundaries into a single session. Sketched: + +``` +runtime.invoke(persona="...", task="...", override={ + type: "operator_collapsed_modes", + modes_collapsed: ["exploration", "planning", "execution", "validation"], + reason: "production incident — patch needed in 30 min", + acknowledged_risks: [ + "validator shares context with builder; findings biased toward what builder framing surfaced", + "no fresh planning context; speculative certainty propagates into build", + "no fresh exploration; tensions not surfaced before convergence" + ] +}) +``` + +When an override is present, the runtime: + +1. **Records a journal entry at session start** naming the override, modes collapsed, reason, and acknowledged risks. +2. **Relaxes role enforcement** for the collapsed modes. Tool sets are unioned; fresh-context guarantees are suspended for the collapsed transitions. +3. **Records a journal entry at session end** naming what actually happened — work performed, decisions made, tradeoffs that materialized. +4. **Tags the session's outputs as override-produced** in any downstream metadata, so consumers can see that subsequent work was built on overridden-session output and apply appropriate skepticism. + +The override is *not* the same as the `general` role escape hatch. The general role is a persona-profile-level declaration that some sessions of this persona never had the constraints in the first place. The override is a runtime-invocation-level declaration that this specific session has the constraints temporarily suspended for declared reasons. Both produce relaxed sessions; the audit trail is different, and the override's audit trail names the urgency-driven choice explicitly. + +The runtime cannot override the journal entry requirement itself. The override is a journal-worthy event; the journal entry is what makes the corruption visible later. A runtime that allowed override sessions to skip journaling would be silently undoing the constraint's audit-trail purpose. + +#### What Conversational-Mode Orchestration Looks Like + +The principle's note that "in conversational mode this should feel seamless" is a consumer pattern that composes parallelism and override support with session-spawning. A chat-facing consumer that wants to present unified continuity to a human user while respecting session-per-mode discipline orchestrates the runtime as follows: + +- Detects mode transitions in the conversation (the human signals "okay let's plan it" or "start building"). +- Spawns a fresh role-bound session at each transition, with the prior session's encoded handoff as input. +- Presents the new session's output as continuation of the conversation. +- Records journal entries at each transition invisibly to the human. +- Surfaces an explicit override prompt when the human wants to collapse modes ("you're asking me to skip planning and start building — do you want to declare an override, or take a moment to plan?"). + +The runtime does not implement this orchestration; it provides the primitives the orchestrator composes. This is a consumer pattern that warrants its own canon doc once a working orchestrator exists to point at; for now it is a deferred follow-up. + +--- + ## What This Method Is Not **Not orchestration.** The runtime invokes one persona per request. It does not chain personas, route between them, or maintain workflows that span multiple invocations. Orchestration belongs to consumers, not to the runtime. (A consumer can call the runtime multiple times in sequence; that is the consumer's workflow.) From 6250f5bf32e8d049dca44ce1ca281c3386b39e53 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 10 May 2026 04:38:38 +0000 Subject: [PATCH 4/9] canon: sessions-mirror-modes principle + encoded-handoff constraint + Resolution as 5th mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New Tier-1 docs: - canon/principles/sessions-mirror-modes.md — generalizes critic-cannot-be-resolver and verification-requires-fresh-context across all five mode transitions; names five mode-bound roles (explorer/planner/builder/validator/resolver); includes parallelism patterns and a substantive failure-modes section on handoff quality. - canon/constraints/mode-transitions-require-encoded-handoff.md — every transition requires a journal entry plus a transition-specific minimal handoff; reversion, skip, and operator override are three permitted deviations with explicit acknowledgment; handoff quality is upstream of any constraint feature. Patch: - canon/definitions/epistemic-modes.md — adds Resolution as fifth canonical mode (canonical implication made explicit per the existing 'fixes belong to iteration, which is a fresh execution pass scoped by validation findings' line); extends Non-Collapse Rule with three resolution-specific invalid moves; bumps date to 2026-05-10 and epoch to E0008.5. Update: - canon/methods/persona-shaped-agent-runtime.md — new §8 Support Handoff-Insufficiency Signaling: runtime addresses the failure mode by accepting a structured 'handoff_insufficient' outcome with named missing items and a proposed_resolution. The runtime requires presence (encoded-handoff constraint); receiving sessions judge sufficiency at runtime. Type-system / runtime-validation pattern. Journal: - journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv — 4 D, 1 L, 1 C, 1 O, 1 H. Operator-driven additions this round: 1. 'planner should not be the executor' generalized into Sessions Mirror Modes 2. 'two roles and purpose' — abstracted principle + guiding constraint as doc pair 3. 'encoding journal repeated for every transition without exception' 4. operator override use case for urgency 5. simultaneous agents/assistants — parallelism patterns 6. failure modes — when handoff quality fails, exclusive sessions cost more than they pay back --- ...ode-transitions-require-encoded-handoff.md | 53 +++++++++++ canon/definitions/epistemic-modes.md | 8 +- canon/methods/persona-shaped-agent-runtime.md | 40 +++++++++ canon/principles/sessions-mirror-modes.md | 90 +++++++++++++++++++ ...mirror-modes-and-encoded-handoff-canon.tsv | 9 ++ 5 files changed, 198 insertions(+), 2 deletions(-) create mode 100644 journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv diff --git a/canon/constraints/mode-transitions-require-encoded-handoff.md b/canon/constraints/mode-transitions-require-encoded-handoff.md index 1c6e0da..428837e 100644 --- a/canon/constraints/mode-transitions-require-encoded-handoff.md +++ b/canon/constraints/mode-transitions-require-encoded-handoff.md @@ -81,6 +81,41 @@ Both reversion and skip require the journal entry. Neither is a free move. The d --- +## Operator Override — Explicit Mode Collapse Under Urgency + +A third escape mechanism, distinct from reversion and skip. An operator can declare a runtime override that collapses one or more mode boundaries into a single session — typically when urgency outweighs the cost of corruption. Like reversion and skip, the override requires explicit acknowledgment and a durable record. + +### What an Override Is + +A runtime-level declaration by the human operator that one or more mode boundaries will be deliberately collapsed for the current session. The operator names the collapse, states the reason, and acknowledges the corruption being accepted. The runtime records the override in the journal at session start, applies relaxed constraints for the session's duration, and records the actual work done in the journal at session end. + +This differs from skip: a skip declares that a mode will not be entered at all. An override declares that multiple modes will be collapsed into a single session — work happens, but without the gate boundaries between modes. The corruption mode is also different: a skip means the mode's signal is missing entirely; an override means the mode's signal is produced under conditions that compromise its quality. + +### What an Override Requires + +- **Explicit declaration.** Override cannot be implicit. The operator names which boundaries are being collapsed: *"collapse exploration through validation in this session"* or *"collapse all five modes in this session."* +- **Stated reason.** Why urgency outweighs discipline. The reason need not be elaborate but must be specific enough to be auditable later — *"production incident; we need a working patch in the next thirty minutes"* is sufficient. *"In a hurry"* alone is not. +- **Acknowledged risks.** The operator names the corruption modes being accepted. For an override that collapses execution and validation, this is *"the validator will share context with the builder, and findings will be biased toward what the builder's framing made visible."* +- **Journal entry at session start** naming all of the above. +- **Journal entry at session end** naming what actually happened — what was built, what was validated under the override, what was skipped, what tradeoffs materialized in practice. + +### What an Override Is Not + +- Not the `general` role escape hatch. The general role is a planned escape declared at persona-profile authoring time. The operator override is a reactive escape declared at session-invocation time. Different declaration point, different audit trail. +- Not transferable. An override applies only to the session it was declared for. Subsequent sessions do not inherit the override; if the urgency persists across sessions, each session gets its own override declaration. +- Not absolute. The operator can override gate transitions but cannot override the journal entry requirement itself. The override is the journal-worthy event; the journal entry is what makes the corruption visible later. +- Not a free pass for routine convenience. The override is for genuine urgency — production incidents, time-bounded operational decisions, situations where the cost of waiting exceeds the cost of corrupted signal. An override invoked routinely degrades the project's epistemic record over time. + +### The Cost + +An override produces a session whose epistemic record is corrupted by design. Future work that depends on this session's output should be aware of the corruption. The journal entry serves this purpose — downstream readers can see that the session was operator-overridden and apply appropriate skepticism to the outputs. + +The discipline of recording the override is what allows the corruption to be visible later. A session that collapsed modes silently produces unfalsifiable history. A session that collapsed modes with a recorded override produces history that *knows* it is corrupted, which is recoverable. + +The override is therefore not a violation of this constraint. It is a third permitted deviation, treated identically to reversion and skip: allowed with explicit acknowledgment, accompanied by a durable record, and accountable to its costs. + +--- + ## Operational Enforcement This constraint is enforceable at three layers: @@ -117,6 +152,24 @@ This is a consumer pattern, not a runtime feature, and it is documented separate --- +## Handoff Quality Is a Separate Discipline + +This constraint codifies the *requirement* for encoded handoffs at every transition. It does not codify *quality*, and cannot. A handoff that satisfies the minimum content requirement above can still be insufficient — shallow encoding, lossy capture of dynamic context, missing the unwritten-but-obvious knowledge the prior session held implicitly. The constraint ensures the artifact exists; it does not ensure the artifact is good. + +This is a meaningful gap. Per [Sessions Mirror Modes §Failure Modes](klappy://canon/principles/sessions-mirror-modes), the architecture's cost only pays back when handoffs preserve what would naturally transfer in shared sessions. Bad handoffs produce sessions operating on distorted input — worse than the mode-collapse the architecture was meant to replace. The constraint can require presence; the project's encoding norms have to deliver quality. + +Three specific places this gap matters: + +- **Minimum-met-but-thin handoffs** pass this constraint's check but fail the principle's purpose. Format-correct, content-poor. The constraint cannot detect this; downstream review and audit-trail patterns can. +- **Missing dynamic types** are the most common failure — settled decisions get encoded, live tensions and considered-rejected paths do not. The minimum-handoff list above does not require encoding these explicitly; projects that find their handoffs routinely losing dynamic context should extend their local handoff norms to require it. +- **Missing crucial context that felt obvious to the encoder** is the highest-cost failure. The encoder had it; they did not write it down because encoding it felt like overhead. The receiving session in fresh context does not have it. The constraint's minimum cannot anticipate which context will feel obvious; this gap closes only through observed failures and norm refinement. + +The constraint's role here is operational: it makes encoding the work, surfaces gaps when receiving sessions cannot proceed, and preserves audit trails of insufficient handoffs. It does not — and cannot — guarantee the encoding captures what matters. That is upstream of any constraint, in the encoding norms a project develops over time. + +A receiving session that cannot proceed on a handoff has the right to refuse with a structured signal — *"this handoff is insufficient; specifically X is missing"* — distinct from disagreement with the handoff's content. The runtime can support this signal as a first-class outcome (see [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime)). The constraint requires the handoff exists; the runtime feature requires the receiving session can refuse it when it is not enough. + +--- + ## 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. diff --git a/canon/definitions/epistemic-modes.md b/canon/definitions/epistemic-modes.md index a0ed673..1fd0e75 100644 --- a/canon/definitions/epistemic-modes.md +++ b/canon/definitions/epistemic-modes.md @@ -7,8 +7,8 @@ tier: 1 voice: neutral stability: semi_stable tags: ["epistemology", "decision-making", "governance"] -epoch: E0008.3 -date: 2026-04-18 +epoch: E0008.5 +date: 2026-05-10 --- # Epistemic Modes @@ -207,6 +207,10 @@ Skipping modes is allowed only when explicitly acknowledged. For practical guidance on mode transitions in conversation, see **Mode-Separated Conversations**. +For the principle that each mode earns its own session, see [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes). + +For the binding rule that every transition requires a journal entry plus a transition-specific durable handoff artifact, see [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff). + --- ## Legitimacy of Inaction diff --git a/canon/methods/persona-shaped-agent-runtime.md b/canon/methods/persona-shaped-agent-runtime.md index 91644cf..3a3a901 100644 --- a/canon/methods/persona-shaped-agent-runtime.md +++ b/canon/methods/persona-shaped-agent-runtime.md @@ -272,6 +272,46 @@ The runtime does not implement this orchestration; it provides the primitives th --- +### 8. Support Handoff-Insufficiency Signaling + +Per [Sessions Mirror Modes §Failure Modes](klappy://canon/principles/sessions-mirror-modes), the architecture's cost only pays back when handoffs preserve what would have transferred in shared sessions. The runtime cannot guarantee handoff quality — that is an encoding-norms discipline upstream of any runtime feature. But the runtime can ensure that bad handoffs are detectable and that receiving sessions can refuse to proceed on them. + +The runtime supports a structured "handoff insufficient" outcome distinct from a session's normal deliverable: + +``` +session.outcome = { + type: "handoff_insufficient", + missing: [ + "the synthesis ledger lists three options but does not capture the tradeoff considerations", + "scope item 'X' is named but its boundaries are unclear", + "implicit assumption that {Y is true} appears load-bearing but is not declared" + ], + proposed_resolution: "request fresh upstream session" | "request clarification from upstream author" | "operator override decision" +} +``` + +When a receiving session returns this outcome instead of a normal deliverable, the runtime: + +1. **Records the insufficiency in the journal** alongside the originating handoff URI. Audit trails accumulate; chronic insufficiency at a specific gate signals norm gaps that the project's encoding discipline should address. +2. **Does not produce a downstream handoff.** The receiving session cannot proceed; therefore there is no handoff to the next mode. The work blocks at this gate until resolution. +3. **Surfaces the resolution path to the consumer.** The consumer chooses among: (a) spawn a fresh upstream session with refined task scope to produce a better handoff, (b) request live clarification from the upstream session author and append the clarification to the handoff, (c) operator override declaring that the work proceeds despite the insufficient handoff. + +This outcome is *not* the same as "I disagree with the handoff content" or "I have findings about the handoff." Disagreement is content-level; findings have a normal disposition. Handoff insufficiency is structural — the receiving session structurally cannot do its job because the input does not contain what its mode requires. + +The signal is also a learning input. A project that observes its planner-role sessions routinely flagging explorer-handoffs as insufficient on a specific dimension — *"missing dynamic tensions that surfaced during exploration"* — has evidence that its synthesis-ledger encoding norms need to be extended. The runtime does not fix the norms; it surfaces the failure pattern that drives norm refinement. + +#### Quality vs. Presence + +To be explicit about what this feature does and does not do: + +- The runtime *requires* handoff presence per [the encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff). Sessions without complete handoffs are refused at submit time. +- The runtime *cannot validate* handoff quality before invocation. Quality is judged by the receiving session, in context, against the actual work it is being asked to do. +- The runtime *does support* the receiving session's structured refusal when quality is insufficient. The signal is the runtime's contribution to the quality-discipline problem; the discipline itself lives in encoding norms. + +This is the same pattern as type-checking versus runtime validation in any system: the type system catches some classes of errors statically; runtime validation catches the rest. The encoded-handoff constraint is the type system. Handoff-insufficiency signaling is the runtime check. + +--- + ## What This Method Is Not **Not orchestration.** The runtime invokes one persona per request. It does not chain personas, route between them, or maintain workflows that span multiple invocations. Orchestration belongs to consumers, not to the runtime. (A consumer can call the runtime multiple times in sequence; that is the consumer's workflow.) diff --git a/canon/principles/sessions-mirror-modes.md b/canon/principles/sessions-mirror-modes.md index b49c3b1..d57c400 100644 --- a/canon/principles/sessions-mirror-modes.md +++ b/canon/principles/sessions-mirror-modes.md @@ -85,6 +85,44 @@ The relaxations are permissions, not the default. Default is gate-required for e --- +## Parallelism Patterns — What This Principle Does Not Forbid + +Session-per-mode discipline is often misread as "work serializes through five modes." It does not. Parallelism is supported in three of four patterns; only one is forbidden. + +### Within-Mode Parallelism — Encouraged + +Multiple sessions operating in the same mode, in parallel, on the same goal is the Quantum Development insight applied at the session layer: same mode, different execution paths, different outcomes. The pattern is most useful when: + +- Multiple explorers fan out on different angles of a single goal, each with fresh context. Fan-in produces a consolidated synthesis ledger that the planner reads as the encoded handoff. +- Multiple validators apply different lenses to the same artifact — security validator, UX validator, technical validator. Each runs independently with fresh context. Fan-in produces consolidated findings with each lens's dispositions preserved. +- Multiple builders work on independent parts of a planned scope. Fan-in produces the artifact when each builder's contribution is independent of the others. + +The fan-in is itself a consumer pattern — the consumer collects parallel sessions' outputs and produces a single encoded handoff to the next mode. Fan-in is not free; the consumer assumes responsibility for reconciling overlapping outputs and surfacing genuine disagreement among parallel sessions. + +### Multi-Participant Single Session — Allowed Within a Mode + +Multiple agents or assistants can collaborate within a single session, sharing the session's context and operating in the session's mode. A builder collaborating with a coding-style reviewer assistant is one builder-role session with two participants. The session is still mode-bound; the participants share the mode's tool restrictions and produce the mode's deliverable jointly. + +This does not violate session-per-mode discipline because the session is bound to one mode. The participants are inside that mode together. The handoff at the next gate is from the session's joint output, not from individual participants. + +### Cross-Mode Parallelism on the Same Artifact — Forbidden + +A builder still building cannot have a validator already validating the same artifact. The validator's input is the encoded artifact-plus-claims handoff, which does not exist until the builder is done. Premature validation reviews an unfinished artifact, which corrupts both roles: the validator produces findings against a moving target; the builder feels evaluated mid-build and starts optimizing toward what the validator is surfacing rather than toward what the plan called for. + +This is the only parallelism pattern the principle forbids. Runtimes that host this work can enforce it mechanically by refusing validator sessions on artifacts not yet declared complete via the encoded-handoff mechanism. + +### Cross-Mode Parallelism on Different Artifacts — Independent + +Multiple work streams, each with their own mode chain, can run concurrently with no conflict. A team can have one stream in exploration, another in planning, a third in build, a fourth in validation, simultaneously. Each stream has its own handoffs, its own journal entries, its own session structure. They share only what they choose to share — typically nothing more than upstream canon and downstream consumer interests. + +This is the default mode of a productive multi-agent system. The principle does not slow this down; it constrains only the within-stream serialization of an artifact through modes. + +### The Distinguishing Question + +When evaluating any parallelism pattern, ask: *are these sessions operating on the same artifact in different modes simultaneously?* If yes, forbidden. If no — same mode, or different artifacts — allowed. Most parallelism intuitions resolve cleanly under this test. + +--- + ## 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. @@ -97,6 +135,58 @@ For conversational surfaces — chat with an AI assistant, pair-programming sess --- +## Failure Modes — When Handoff Quality Determines Whether the Architecture Pays Back + +Session-per-mode discipline is not free. Each transition costs orchestration overhead, journal entries, and the inherent information loss of encoding into a durable artifact what would otherwise live in continuous working context. The principle's claim is that the signal-quality gain from fresh context exceeds these costs. + +That claim depends entirely on handoff quality. If the encoded handoff fails to preserve what would have transferred in a shared session, the receiving session is operating on degraded input — which is worse than the mode-collapse it was meant to replace. Mode-collapse at least operates on the real picture (just corrupted by the collapse). A bad handoff produces a session operating on a distorted picture *and* paying the architectural cost to do so. + +### What Bad Handoffs Look Like + +The failure is not random encoding error. It is systematic loss of the kinds of context that resist explicit encoding: + +**Lossy encoding.** The handoff captures the decisions but not the live tensions, the considered-and-rejected paths, the *"we almost went with X but Y because Z"* context that would have been visible in shared session state. A planner reading "scope: A, B, C" without seeing that "we initially had D in scope and removed it because of constraint K" will plan as if D was never considered — and may rediscover D's appeal mid-execution without K's reasoning to bound it. + +**Missing dynamic types.** Static handoffs preserve static decisions but not *live* state — assumptions that feel load-bearing but are still tentative, conclusions that feel right but are sensitive to inputs the next session will see, hypotheses that the prior session was about to test. These dynamic types resist encoding because they have no settled form yet, but they are exactly the context the next session needs to know is unstable. + +**Missing crucial context that felt obvious.** The most dangerous gap. The encoder knew something but did not write it down because encoding it felt like overhead — the kind of context everyone-on-the-project-knows. Receiving sessions in fresh context do not have that everyone-knows context. They proceed as if the unwritten thing did not exist. + +**Minimum-met-but-insufficient handoffs.** The handoff satisfies the [encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff)'s minimum content requirement but is shallow — checkbox compliance without substantive encoding. The format is right; the meaning is thin. The receiving session has nothing to refuse the handoff against, but it also has nothing to work with. + +### When Costs Exceed Benefits + +The architecture fails to pay back when handoff quality is poor enough that the receiving session is operating on a distorted view *and* the orchestration cost is being paid in full. Two specific conditions: + +**The encoder is the only one who knew it.** When the prior session held context that genuinely cannot be reconstructed from canon, prior journal entries, or general project knowledge — and the encoder did not surface it — that context dies at the gate. The receiving session has no way to recover it. Mode-collapse would have preserved it; session-per-mode loses it. + +**The encoding norms have not yet caught the failure mode.** Every project has handoff-quality patterns that emerge over time. Until those patterns include the specific kind of context that gets routinely lost, sessions-per-mode will produce visibly worse output than mode-collapse on that kind of work. The principle becomes load-bearing only after the encoding norms are sharp enough to capture what matters. + +In both cases, the rational choice is to relax the architecture for the affected transitions until the failure mode is addressed — either by mode-collapse with operator override (per [the encoded-handoff constraint's override provision](klappy://canon/constraints/mode-transitions-require-encoded-handoff)), or by improving the encoding norms first, or by accepting that some handoffs need supplementary live consultation between sessions. + +### Detection Signals + +A session operating on a bad handoff produces detectable signals: + +- The receiving session asks questions whose answers should have been in the handoff (and that the handoff format was supposed to capture) +- The receiving session builds on assumptions not stated in the handoff, sourced from inference or generalization rather than from declared inputs +- The receiving session's output contradicts implicit context the prior session held but did not encode +- Findings or revisions surface issues the prior session would have prevented if its context had transferred + +These signals are detectable to the receiving session itself, to a downstream session reviewing both, and to a longitudinal review of the project's journal entries. The architecture's mitigation path is to make these signals visible — receiving sessions can refuse insufficient handoffs and request escalation rather than proceeding with degraded input. + +### Mitigation, Not Elimination + +Handoff quality is its own discipline, distinct from the structural discipline of session boundaries. The principle's costs only pay back if both disciplines are in place. Specifically: + +- **Encoding norms must surface dynamic types, considered-and-rejected paths, and load-bearing-but-tentative state** — not just settled decisions. Norms emerge over time and from observed failures. +- **Receiving sessions must be able to flag insufficient handoffs** as a first-class outcome — distinct from "I disagree with the handoff" or "I have findings about it." A handoff insufficiency is a structural problem requiring escalation, not a content disagreement requiring resolution. +- **Audit trails should preserve handoff insufficiency events** so projects can observe which transitions routinely produce bad handoffs and improve norms at those gates. +- **Operator override is a legitimate response to chronic handoff-quality problems** for affected transitions — not as a permanent retreat, but as a stopgap until norms catch up. + +The principle is right when handoffs are right. It is wrong, in the sense of producing worse outcomes than its alternative, when handoffs are bad. The architecture does not eliminate the encoding-quality problem; it relocates it from "did the prior session communicate well" to "did the prior session encode well." That is a different problem and one some failure modes resist. + +--- + ## Derivation This principle derives from three sources, each of which it generalizes: diff --git a/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv b/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv new file mode 100644 index 0000000..48e3fc3 --- /dev/null +++ b/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv @@ -0,0 +1,9 @@ +type typeName facet quality_score quality_max quality_level title content +D Decision 5 5 strong Sessions Mirror Modes promoted to Tier-1 principle Each epistemic mode earns its own session because 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 principle generalizes critic-cannot-be-resolver (klappy://canon/constraints/critic-cannot-be-resolver) and verification-requires-fresh-context (klappy://canon/principles/verification-requires-fresh-context) to a universal claim: every gate between modes is a context boundary, and every context boundary deserves a fresh session. Five mode-bound roles named — explorer, planner, builder, validator, resolver — each mapping 1:1 to a canonical mode. +D Decision 5 5 strong Mode Transitions Require Encoded Handoff promoted to Tier-1 constraint Every transition between modes requires two artifacts: a journal entry recording the transition (universal, no exception) and a transition-specific minimal handoff (explorer→planner: synthesis ledger; planner→builder: plan with assumptions and scope; builder→validator: artifact + claims; validator→resolver: findings with dispositions; resolver→re-validator: revised artifact + remediation summary). Reversion and skip remain permitted with explicit acknowledgment per existing canon. New: operator override added as third permitted deviation — explicit runtime declaration of mode collapse under declared urgency, with stated reason, acknowledged risks, and journal entries at session start and end. +D Decision 5 5 strong Resolution promoted to fifth canonical epistemic mode The four-mode canon already implied a fifth phase: "fixes belong to iteration, which is a fresh execution pass scoped by validation findings." This patch makes the implied mode explicit. Resolution sits between Validation and a re-validation pass. Purpose: produce a revised artifact scoped strictly by validation findings. Truth condition: addresses findings without expanding scope. Primary risk: scope creep — using remediation as cover for redesign. Non-Collapse Rule extended with three resolution-specific invalid moves. Frontmatter date bumped to 2026-05-10; epoch to E0008.5; stability stays semi_stable since the addition is canonical implication-made-explicit, not a new claim about how truth is formed. +D Decision 5 5 strong Handoff-Insufficiency Signaling added as runtime feature #8 The runtime cannot guarantee handoff quality — that is upstream encoding-norm discipline. But the runtime can ensure that bad handoffs are detectable. A receiving session that cannot proceed on an insufficient handoff returns a structured "handoff_insufficient" outcome with named missing items and a proposed_resolution (request fresh upstream session / request clarification / operator override). The runtime records the insufficiency in the journal, blocks the downstream handoff, and surfaces the resolution path to the consumer. Audit trails accumulate; chronic insufficiency at a specific gate signals norm gaps that the project's encoding discipline must address. +L Learning 5 5 strong The architecture only pays back when handoffs preserve dynamic types Operator surface insight: "If encodings and other handoffs are lacking and of poor quality or missing key dynamic types any form of missing details and crucial context excluded will cause problems that may not outweigh the benefit of exclusive sessions." Handoff quality is the architecture's load-bearing assumption. Specific failure modes named: lossy encoding (decisions captured but not live tensions); missing dynamic types (static plan but not live state); missing crucial context that felt obvious to the encoder but wasn't written down because everyone-on-the-project-knew. When these dominate, session-per-mode becomes worse than mode-collapse: orchestration cost paid in full and receiving sessions operating on distorted views. Failure-mode sections added to sessions-mirror-modes principle (substantive), encoded-handoff constraint (pointer + summary), and persona-shaped-agent-runtime (handoff-insufficiency signaling feature). +C Constraint 5 5 strong Encoding norms must emerge from observed failures The constraint codifies handoff PRESENCE; QUALITY is upstream encoding-norms discipline that the constraint requires the existence of but cannot measure. Type-system / runtime-validation pattern: encoded-handoff constraint catches some classes of failure statically (handoff exists with minimum content); handoff-insufficiency signaling catches the rest at runtime (receiving session structurally cannot do its job). A project that observes its planner-role sessions routinely flagging explorer-handoffs as insufficient on a specific dimension has evidence that its synthesis-ledger encoding norms need extension. The runtime surfaces failure patterns; the project refines norms. +O Observation 5 5 strong Parallelism patterns named as four cases with one forbidden Within-mode parallelism (multiple explorers, multiple validators with different lenses, multiple builders on independent scope) — encouraged. Multi-participant single session (builder + assistant pair-programming) — allowed within a mode. Cross-mode on the same artifact — FORBIDDEN; the only pattern blocked. Cross-mode on different artifacts — fully independent, default mode of a productive multi-agent system. Distinguishing question: are these sessions operating on the same artifact in different modes simultaneously? If yes, forbidden; if no, allowed. Runtime enforces the forbidden pattern by refusing validator sessions on artifacts whose builder hasn't produced an encoded handoff. +H Handoff 5 5 strong PR #187 update — five new sections + new principle + new constraint + epistemic-modes Resolution patch klappy.dev branch claude/runtime-canon-acd1 / PR #187 picks up: (1) new canon/principles/sessions-mirror-modes.md (Tier-1 principle, 25kb), (2) new canon/constraints/mode-transitions-require-encoded-handoff.md (Tier-1 constraint, 21kb), (3) modified canon/definitions/epistemic-modes.md (Resolution as fifth mode, Non-Collapse Rule extended, frontmatter bumped), (4) modified canon/methods/persona-shaped-agent-runtime.md (new §8 Support Handoff-Insufficiency Signaling). Forward-looking URI reference to klappy://canon/methods/spawned-agent-session-substrate-options remains in frontmatter — that doc lands in PR A scope (substrate rename + substrate options); both PRs can land in either order, references resolve once both are merged. Mode-separated-conversations doc still needs Resolution-mode section (deferred follow-up). From b9e6a41443a700a766fa17019ed5973451ebf6a3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 10 May 2026 04:43:21 +0000 Subject: [PATCH 5/9] Fix TSV column misalignment in 2026-05-10 sessions-mirror-modes journal --- ...ns-mirror-modes-and-encoded-handoff-canon.tsv | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv b/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv index 48e3fc3..26750c4 100644 --- a/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv +++ b/journal/2026-05-10-sessions-mirror-modes-and-encoded-handoff-canon.tsv @@ -1,9 +1,9 @@ type typeName facet quality_score quality_max quality_level title content -D Decision 5 5 strong Sessions Mirror Modes promoted to Tier-1 principle Each epistemic mode earns its own session because 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 principle generalizes critic-cannot-be-resolver (klappy://canon/constraints/critic-cannot-be-resolver) and verification-requires-fresh-context (klappy://canon/principles/verification-requires-fresh-context) to a universal claim: every gate between modes is a context boundary, and every context boundary deserves a fresh session. Five mode-bound roles named — explorer, planner, builder, validator, resolver — each mapping 1:1 to a canonical mode. -D Decision 5 5 strong Mode Transitions Require Encoded Handoff promoted to Tier-1 constraint Every transition between modes requires two artifacts: a journal entry recording the transition (universal, no exception) and a transition-specific minimal handoff (explorer→planner: synthesis ledger; planner→builder: plan with assumptions and scope; builder→validator: artifact + claims; validator→resolver: findings with dispositions; resolver→re-validator: revised artifact + remediation summary). Reversion and skip remain permitted with explicit acknowledgment per existing canon. New: operator override added as third permitted deviation — explicit runtime declaration of mode collapse under declared urgency, with stated reason, acknowledged risks, and journal entries at session start and end. -D Decision 5 5 strong Resolution promoted to fifth canonical epistemic mode The four-mode canon already implied a fifth phase: "fixes belong to iteration, which is a fresh execution pass scoped by validation findings." This patch makes the implied mode explicit. Resolution sits between Validation and a re-validation pass. Purpose: produce a revised artifact scoped strictly by validation findings. Truth condition: addresses findings without expanding scope. Primary risk: scope creep — using remediation as cover for redesign. Non-Collapse Rule extended with three resolution-specific invalid moves. Frontmatter date bumped to 2026-05-10; epoch to E0008.5; stability stays semi_stable since the addition is canonical implication-made-explicit, not a new claim about how truth is formed. -D Decision 5 5 strong Handoff-Insufficiency Signaling added as runtime feature #8 The runtime cannot guarantee handoff quality — that is upstream encoding-norm discipline. But the runtime can ensure that bad handoffs are detectable. A receiving session that cannot proceed on an insufficient handoff returns a structured "handoff_insufficient" outcome with named missing items and a proposed_resolution (request fresh upstream session / request clarification / operator override). The runtime records the insufficiency in the journal, blocks the downstream handoff, and surfaces the resolution path to the consumer. Audit trails accumulate; chronic insufficiency at a specific gate signals norm gaps that the project's encoding discipline must address. -L Learning 5 5 strong The architecture only pays back when handoffs preserve dynamic types Operator surface insight: "If encodings and other handoffs are lacking and of poor quality or missing key dynamic types any form of missing details and crucial context excluded will cause problems that may not outweigh the benefit of exclusive sessions." Handoff quality is the architecture's load-bearing assumption. Specific failure modes named: lossy encoding (decisions captured but not live tensions); missing dynamic types (static plan but not live state); missing crucial context that felt obvious to the encoder but wasn't written down because everyone-on-the-project-knew. When these dominate, session-per-mode becomes worse than mode-collapse: orchestration cost paid in full and receiving sessions operating on distorted views. Failure-mode sections added to sessions-mirror-modes principle (substantive), encoded-handoff constraint (pointer + summary), and persona-shaped-agent-runtime (handoff-insufficiency signaling feature). -C Constraint 5 5 strong Encoding norms must emerge from observed failures The constraint codifies handoff PRESENCE; QUALITY is upstream encoding-norms discipline that the constraint requires the existence of but cannot measure. Type-system / runtime-validation pattern: encoded-handoff constraint catches some classes of failure statically (handoff exists with minimum content); handoff-insufficiency signaling catches the rest at runtime (receiving session structurally cannot do its job). A project that observes its planner-role sessions routinely flagging explorer-handoffs as insufficient on a specific dimension has evidence that its synthesis-ledger encoding norms need extension. The runtime surfaces failure patterns; the project refines norms. -O Observation 5 5 strong Parallelism patterns named as four cases with one forbidden Within-mode parallelism (multiple explorers, multiple validators with different lenses, multiple builders on independent scope) — encouraged. Multi-participant single session (builder + assistant pair-programming) — allowed within a mode. Cross-mode on the same artifact — FORBIDDEN; the only pattern blocked. Cross-mode on different artifacts — fully independent, default mode of a productive multi-agent system. Distinguishing question: are these sessions operating on the same artifact in different modes simultaneously? If yes, forbidden; if no, allowed. Runtime enforces the forbidden pattern by refusing validator sessions on artifacts whose builder hasn't produced an encoded handoff. -H Handoff 5 5 strong PR #187 update — five new sections + new principle + new constraint + epistemic-modes Resolution patch klappy.dev branch claude/runtime-canon-acd1 / PR #187 picks up: (1) new canon/principles/sessions-mirror-modes.md (Tier-1 principle, 25kb), (2) new canon/constraints/mode-transitions-require-encoded-handoff.md (Tier-1 constraint, 21kb), (3) modified canon/definitions/epistemic-modes.md (Resolution as fifth mode, Non-Collapse Rule extended, frontmatter bumped), (4) modified canon/methods/persona-shaped-agent-runtime.md (new §8 Support Handoff-Insufficiency Signaling). Forward-looking URI reference to klappy://canon/methods/spawned-agent-session-substrate-options remains in frontmatter — that doc lands in PR A scope (substrate rename + substrate options); both PRs can land in either order, references resolve once both are merged. Mode-separated-conversations doc still needs Resolution-mode section (deferred follow-up). +D Decision 5 5 strong Sessions Mirror Modes promoted to Tier-1 principle Each epistemic mode earns its own session because 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 principle generalizes critic-cannot-be-resolver (klappy://canon/constraints/critic-cannot-be-resolver) and verification-requires-fresh-context (klappy://canon/principles/verification-requires-fresh-context) to a universal claim: every gate between modes is a context boundary, and every context boundary deserves a fresh session. Five mode-bound roles named — explorer, planner, builder, validator, resolver — each mapping 1:1 to a canonical mode. +D Decision 5 5 strong Mode Transitions Require Encoded Handoff promoted to Tier-1 constraint Every transition between modes requires two artifacts: a journal entry recording the transition (universal, no exception) and a transition-specific minimal handoff (explorer→planner: synthesis ledger; planner→builder: plan with assumptions and scope; builder→validator: artifact + claims; validator→resolver: findings with dispositions; resolver→re-validator: revised artifact + remediation summary). Reversion and skip remain permitted with explicit acknowledgment per existing canon. New: operator override added as third permitted deviation — explicit runtime declaration of mode collapse under declared urgency, with stated reason, acknowledged risks, and journal entries at session start and end. +D Decision 5 5 strong Resolution promoted to fifth canonical epistemic mode The four-mode canon already implied a fifth phase: "fixes belong to iteration, which is a fresh execution pass scoped by validation findings." This patch makes the implied mode explicit. Resolution sits between Validation and a re-validation pass. Purpose: produce a revised artifact scoped strictly by validation findings. Truth condition: addresses findings without expanding scope. Primary risk: scope creep — using remediation as cover for redesign. Non-Collapse Rule extended with three resolution-specific invalid moves. Frontmatter date bumped to 2026-05-10; epoch to E0008.5; stability stays semi_stable since the addition is canonical implication-made-explicit, not a new claim about how truth is formed. +D Decision 5 5 strong Handoff-Insufficiency Signaling added as runtime feature #8 The runtime cannot guarantee handoff quality — that is upstream encoding-norm discipline. But the runtime can ensure that bad handoffs are detectable. A receiving session that cannot proceed on an insufficient handoff returns a structured "handoff_insufficient" outcome with named missing items and a proposed_resolution (request fresh upstream session / request clarification / operator override). The runtime records the insufficiency in the journal, blocks the downstream handoff, and surfaces the resolution path to the consumer. Audit trails accumulate; chronic insufficiency at a specific gate signals norm gaps that the project's encoding discipline must address. +L Learning 5 5 strong The architecture only pays back when handoffs preserve dynamic types Operator surface insight: "If encodings and other handoffs are lacking and of poor quality or missing key dynamic types any form of missing details and crucial context excluded will cause problems that may not outweigh the benefit of exclusive sessions." Handoff quality is the architecture's load-bearing assumption. Specific failure modes named: lossy encoding (decisions captured but not live tensions); missing dynamic types (static plan but not live state); missing crucial context that felt obvious to the encoder but wasn't written down because everyone-on-the-project-knew. When these dominate, session-per-mode becomes worse than mode-collapse: orchestration cost paid in full and receiving sessions operating on distorted views. Failure-mode sections added to sessions-mirror-modes principle (substantive), encoded-handoff constraint (pointer + summary), and persona-shaped-agent-runtime (handoff-insufficiency signaling feature). +C Constraint 5 5 strong Encoding norms must emerge from observed failures The constraint codifies handoff PRESENCE; QUALITY is upstream encoding-norms discipline that the constraint requires the existence of but cannot measure. Type-system / runtime-validation pattern: encoded-handoff constraint catches some classes of failure statically (handoff exists with minimum content); handoff-insufficiency signaling catches the rest at runtime (receiving session structurally cannot do its job). A project that observes its planner-role sessions routinely flagging explorer-handoffs as insufficient on a specific dimension has evidence that its synthesis-ledger encoding norms need extension. The runtime surfaces failure patterns; the project refines norms. +O Observation 5 5 strong Parallelism patterns named as four cases with one forbidden Within-mode parallelism (multiple explorers, multiple validators with different lenses, multiple builders on independent scope) — encouraged. Multi-participant single session (builder + assistant pair-programming) — allowed within a mode. Cross-mode on the same artifact — FORBIDDEN; the only pattern blocked. Cross-mode on different artifacts — fully independent, default mode of a productive multi-agent system. Distinguishing question: are these sessions operating on the same artifact in different modes simultaneously? If yes, forbidden; if no, allowed. Runtime enforces the forbidden pattern by refusing validator sessions on artifacts whose builder hasn't produced an encoded handoff. +H Handoff 5 5 strong PR #187 update — five new sections + new principle + new constraint + epistemic-modes Resolution patch klappy.dev branch claude/runtime-canon-acd1 / PR #187 picks up: (1) new canon/principles/sessions-mirror-modes.md (Tier-1 principle, 25kb), (2) new canon/constraints/mode-transitions-require-encoded-handoff.md (Tier-1 constraint, 21kb), (3) modified canon/definitions/epistemic-modes.md (Resolution as fifth mode, Non-Collapse Rule extended, frontmatter bumped), (4) modified canon/methods/persona-shaped-agent-runtime.md (new §8 Support Handoff-Insufficiency Signaling). Forward-looking URI reference to klappy://canon/methods/spawned-agent-session-substrate-options remains in frontmatter — that doc lands in PR A scope (substrate rename + substrate options); both PRs can land in either order, references resolve once both are merged. Mode-separated-conversations doc still needs Resolution-mode section (deferred follow-up). From 48246a7cf880d11f260512e44ccd7173c6358ee6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 10 May 2026 04:50:54 +0000 Subject: [PATCH 6/9] canon: reconcile runtime-contract to five modes + add governance-override use case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Runtime-contract reconciliation: - canon/methods/spawned-agent-session-runtime-contract.md updated to align with sessions-mirror-modes principle. Mode dimension expanded from 4 to 5 values (added 'resolution'). Role dimension rewritten with five mode-bound roles (explorer/planner/builder/validator/resolver) plus 'general' (escape hatch) and 'observer' (non-mode-bound continuous observation). New Mode sub-section for Resolution with truth condition, tool allow-list, output schema, and risk detector. Mode-collapse anti-patterns extended from 6 to 9 with three resolution-specific items. Composition Rules forbidden combinations expanded to include validator-resolution and resolution-revalidation same-session refusals plus cross-mode parallelism on same artifact. Well-trodden combinations table updated with new role names and a new governance-author entry showing the worked-override case. Governance-creation as override use case: - canon/constraints/mode-transitions-require-encoded-handoff.md gets a new §Worked Use Cases section naming two categories where override is operationally legitimate: production incidents (urgency-driven) and governance creation (oscillation-driven). Includes the recursive observation that this canon set was itself drafted under override because the explorer-planner-builder-validator-resolver oscillation moved faster than handoff norms could yet capture. Names the operator's aspiration: with mature handoff norms and forced same-branch work, clean sessions become transient/ephemeral/transparent — but reaching that state requires contact with reality, which only comes through observed failures of the current handoff norms. Journal: - journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv records 2 D, 1 L, 1 O, 1 C, 1 H. --- ...ode-transitions-require-encoded-handoff.md | 12 +++ .../spawned-agent-session-runtime-contract.md | 100 ++++++++++++------ ...reconciliation-and-governance-override.tsv | 7 ++ 3 files changed, 89 insertions(+), 30 deletions(-) create mode 100644 journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv diff --git a/canon/constraints/mode-transitions-require-encoded-handoff.md b/canon/constraints/mode-transitions-require-encoded-handoff.md index 428837e..20408d7 100644 --- a/canon/constraints/mode-transitions-require-encoded-handoff.md +++ b/canon/constraints/mode-transitions-require-encoded-handoff.md @@ -99,6 +99,18 @@ This differs from skip: a skip declares that a mode will not be entered at all. - **Journal entry at session start** naming all of the above. - **Journal entry at session end** naming what actually happened — what was built, what was validated under the override, what was skipped, what tradeoffs materialized in practice. +### Worked Use Cases — When the Override Earns Its Keep + +Two categories where operator override is operationally legitimate, not a degradation of discipline: + +**Production incidents.** A bug landed in production; the patch needs to ship in the next thirty minutes. The cost of moving through five clean sessions with handoffs at each gate exceeds the cost of context corruption — production downtime is not an acceptable tradeoff for epistemic hygiene at this moment. The operator declares the override, names the incident, acknowledges that the validator will share context with the builder, and accepts the corruption. The journal entries make the corruption visible later, so any code shipped under override gets flagged for proper post-incident review. + +**Governance creation.** Authoring canonical principles, constraints, and methods is inherently oscillating work. A draft principle implies a constraint; drafting the constraint surfaces a refinement to the principle; the refinement reveals an unexamined assumption that needs an exploration pass. The work moves between modes faster than handoff norms can encode. Until handoff norms catch up — until a project has been through enough governance-creation cycles to know which dynamic types its synthesis ledgers must capture — this category may regularly justify override. The signal is not that discipline is being abandoned; the signal is that the encoding norms are still maturing. An override-with-record produces governance with full audit trail of *how the governance was made*; clean sessions with poor handoffs would produce governance whose drafting context died at every gate. + +The honest framing: the architecture's value depends on handoffs being good enough to preserve what would have transferred in shared context. For categories of work where the encoding norms are still being learned, override-with-record is the correct operational response — not a permanent retreat, but a stopgap until norms catch up. The aspiration is that with explicit handoffs and forced same-branch work, encoding eventually becomes detailed enough that clean sessions become *transient, ephemeral, and transparent to the operator* — but reaching that state requires contact with reality, including the experience of trying and failing to encode well. + +This use case is itself a worked example: this constraint document was drafted in a single collapsed session under operator-acknowledged override, because the explorer-planner-builder-validator-resolver oscillation was faster than the handoff norms could yet capture. The journal entries record the override; future iterations will improve the handoff norms; eventually governance creation may be doable in clean sessions. Until then, override is the rational choice. + ### What an Override Is Not - Not the `general` role escape hatch. The general role is a planned escape declared at persona-profile authoring time. The operator override is a reactive escape declared at session-invocation time. Different declaration point, different audit trail. diff --git a/canon/methods/spawned-agent-session-runtime-contract.md b/canon/methods/spawned-agent-session-runtime-contract.md index 30f7410..7d802dc 100644 --- a/canon/methods/spawned-agent-session-runtime-contract.md +++ b/canon/methods/spawned-agent-session-runtime-contract.md @@ -6,10 +6,10 @@ exposure: nav tier: 2 voice: neutral stability: draft -tags: ["canon", "methods", "spawned-agent-sessions", "runtime", "governance", "epistemic-modes", "engagement", "vodka-architecture", "mechanizes-canon"] +tags: ["canon", "methods", "spawned-agent-sessions", "runtime", "governance", "epistemic-modes", "engagement", "vodka-architecture", "mechanizes-canon", "session-discipline", "five-mode-bound-roles"] epoch: E0008.5 date: 2026-05-10 -derives_from: "canon/epistemic-modes.md, canon/constraints/mode-discipline-and-bottleneck-respect.md, canon/constraints/critic-cannot-be-resolver.md, canon/constraints/audit-gates-are-spawned-agent-sessions.md, canon/methods/spawned-agent-session-substrate-options.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md, canon/principles/verification-requires-fresh-context.md" +derives_from: "canon/epistemic-modes.md, canon/principles/sessions-mirror-modes.md, canon/constraints/mode-transitions-require-encoded-handoff.md, canon/constraints/mode-discipline-and-bottleneck-respect.md, canon/constraints/critic-cannot-be-resolver.md, canon/constraints/audit-gates-are-spawned-agent-sessions.md, canon/methods/spawned-agent-session-substrate-options.md, canon/methods/persona-shaped-agent-runtime.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md, canon/principles/verification-requires-fresh-context.md" complements: "canon/methods/governance-validation-via-agents.md, canon/constraints/canon-integration-audit.md" governs: "Any spawned agent session dispatched on the runtime substrate. Specifies the five orthogonal session-configuration dimensions, the runtime's enforcement obligations against existing canon, and the composition rules that determine session shape from the dimension values. Substrate selection (where the session runs) is handled by klappy://canon/methods/spawned-agent-session-substrate-options; this doc handles configuration (how the session is parameterized)." status: draft @@ -36,8 +36,8 @@ The runtime exposes a single primitive — invoke a session — parameterized by | Dimension | Values | What it determines | |---|---|---| | **Persona** | `oddie`, `audit-gate`, `docs-writer`, `general`, ... | Voice canon, system prompt URI, capability sources (operational + task-relevant MCP servers), inheritance | -| **Mode** | `exploration` \| `planning` \| `execution` \| `validation` | Tool allow-list, output schema, transition rules, primary-risk detector | -| **Role** | `detection-only` \| `resolver` \| `general` | Mutation rights, fresh-context requirements, session-to-session boundaries | +| **Mode** | `exploration` \| `planning` \| `execution` \| `validation` \| `resolution` | Tool allow-list, output schema, transition rules, primary-risk detector | +| **Role** | `explorer` \| `planner` \| `builder` \| `validator` \| `resolver` \| `general` \| `observer` | Mutation rights, fresh-context requirements, structured-deliverable expectations, session-to-session boundaries. The first five are mode-bound (1:1 with the canonical modes); `general` is escape hatch; `observer` is the non-mode-bound configuration for continuous-observation surfaces | | **Surface** | `real-time-stream`, `audit`, `mentorship`, `sidebar-chat`, `code-output`, `synthesis-ledger`, ... | Density / pace / verbosity tolerance, post-processing rules, channel mapping | | **Engagement** | `assistant` \| `agent` | Turn-control contract, bottleneck-respect enforcement, failure modes | @@ -99,7 +99,7 @@ New personas are added by writing a profile, not by writing infrastructure. ## Mode -The four canonical epistemic modes from `klappy://canon/epistemic-modes` map directly to runtime configurations. Each mode constrains tool allow-list, output schema, transition rules, and the primary risk the runtime watches for. +The five canonical epistemic modes from `klappy://canon/epistemic-modes` map directly to runtime configurations. Each mode constrains tool allow-list, output schema, transition rules, and the primary risk the runtime watches for. Per `klappy://canon/principles/sessions-mirror-modes`, each mode earns its own session — the runtime treats mode as load-bearing and refuses to inherit context across mode boundaries except under `engagement=assistant` continuity within the same mode. ### Exploration @@ -136,16 +136,29 @@ The four canonical epistemic modes from `klappy://canon/epistemic-modes` map dir - **Output schema**: each finding MUST carry a disposition — `fix | pivot | accept`. A finding without disposition is rejected as incomplete per the canon. - **Risk detector**: scope creep. Findings that propose redesign rather than report defects are flagged. The validation session does not get to reopen planning; that requires explicit reversion. +### Resolution + +- **Truth condition** (canon): valid if it addresses the findings without expanding scope. +- **Required**: fresh context. The runtime refuses same-session transitions from `validation` to `resolution`. Resolution requires a new session that receives the validation findings as input but does not inherit the validator's framing. This realizes `klappy://canon/constraints/critic-cannot-be-resolver` as a structural feature. +- **Tool allow-list**: full set, scoped to the validation findings — mutations are allowed but bounded by the findings, not by the original plan. +- **Forbidden**: introducing new requirements the findings did not surface. Operations outside finding-scope require explicit reversion to planning. +- **Output schema**: revised artifact + per-finding remediation summary (what was changed, what was not changed and why). Each finding's disposition is honored: `fix` produces a change; `pivot` produces a redirect with rationale; `accept` produces a no-change statement with rationale. +- **Risk detector**: scope creep. Mutations outside finding-scope are flagged. +- **Anti-pattern detector**: resolver does not certify their own fix. Re-validation requires a fresh validator session per `klappy://canon/principles/sessions-mirror-modes`. + ### Mode-collapse anti-patterns become runtime detectors -`klappy://canon/epistemic-modes` §Non-Collapse Rule names six specific anti-patterns. Each maps to a runtime check: +`klappy://canon/epistemic-modes` §Non-Collapse Rule names anti-patterns across all five modes. Each maps to a runtime check: 1. *Exploration pretending to decide* → premature-closure detector in exploration mode. 2. *Planning pretending to execute* → mutation-attempt detector in planning mode (refused at submit time). 3. *Execution exploring alternatives retroactively* → scope-violation detector when tool calls fall outside the locked allow-list. 4. *Execution pretending to validate* → mid-build pivot detector — flag and instruct "note concern, carry forward." 5. *Validation pretending to plan* → redesign-instead-of-finding detector — flag and refuse. -6. *Validation pretending to execute* → mutation-attempt detector in validation mode (refused at submit time). +6. *Validation pretending to execute or resolve* → mutation-attempt detector in validation mode (refused at submit time); inline-fix detector flagged. +7. *Resolution pretending to plan* → new-requirement detector — flag and require explicit reversion. +8. *Resolution pretending to validate* — refused. The resolver session cannot return a "this is fixed" certification; re-validation is a fresh session. +9. *Resolution pretending to be a fresh execution* → scope detector flags mutations outside the bounded scope of the validation findings. Most resolve to schema-level rules and tool allow-lists. Sophistication is not required. @@ -153,24 +166,41 @@ Most resolve to schema-level rules and tool allow-lists. Sophistication is not r ## Role -Role declares the **corruption boundary** the session respects. Three values, derived from `klappy://canon/constraints/critic-cannot-be-resolver`. +Role declares the **session shape** the runtime enforces — tool restrictions, fresh-context requirements, structured-deliverable expectations, and mode binding. Five mode-bound roles map 1:1 to the canonical modes; two escape hatches handle non-mode-bound configurations. + +Generalized from `klappy://canon/principles/sessions-mirror-modes` and `klappy://canon/constraints/critic-cannot-be-resolver`. + +### explorer + +Mode-bound to `exploration`. Tool allow-list is broad (read-heavy: search, fetch, oddkit query tools, web-search) with state-mutation tools refused. Output is a synthesis ledger or research artifact per the [encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff). Fresh-context requirement: must not inherit planner/builder/validator session state. The synthesis ledger is the durable handoff to the planner. + +### planner -### detection-only +Mode-bound to `planning`. Tool allow-list is read-oriented (canon access, prior synthesis ledgers, plan-shaping tools); state-mutation tools refused. Output is a plan declaring `assumptions`, `scope`, `deferred`, and `would_invalidate`. Fresh-context requirement: receives the explorer's encoded synthesis as input, does not inherit explorer-session state. The plan is the durable handoff to the builder. -The session detects and reports. It does not mutate the artifact-under-observation. The runtime enforces this structurally: +### builder -- **Tool filter**: filesystem writes, `git commit`, mutating API verbs (POST/PATCH/DELETE/PUT to write endpoints), `gh pr merge`, and any other state-modifying operations are refused at submit time. Refused before the session starts, not by prompt instruction. -- **Session-to-session boundary**: the same session cannot be re-invoked with a "now fix what you found" follow-up task. Resolution requires a fresh session that receives the finding as input but not the detector's reasoning. This is `critic-cannot-be-resolver` made architectural. +Mode-bound to `execution`. Tool allow-list includes mutating tools (filesystem writes, git, API calls) bounded by the plan's declared scope. Output is the produced artifact plus a claims declaration (what the artifact does, what it does not do, what scope it was built against). Fresh-context requirement: receives the plan as input, does not inherit planner-session state. The artifact-plus-claims is the durable handoff to the validator. -The audit gate is the worked detection-only consumer. Oddie is detection-only across all his surfaces by canon (`klappy://canon/voice/oddie-the-river-guide` §What Oddie Is Not). +### validator + +Mode-bound to `validation`. Tool allow-list is restricted to a read-only allow-list. Mutating actions are refused before the substrate is invoked. Fresh-context requirement is *strict*: the runtime guarantees the validation session is spawned with no inputs from the caller other than the persona profile, the artifact reference, the claims declaration, and the governance documents. Output is structured findings with explicit dispositions (`fix | pivot | accept`) per finding, consistent with [P0008](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable). Findings are the durable handoff to the resolver — or, if all dispositions are `accept`, the validation session is terminal. + +The audit gate is the worked validator consumer. Oddie's audit-findings surface is also validator-shaped. ### resolver -The session is permitted to mutate artifacts within the session's locked scope. Mutating tools are allowed. Resolver sessions cannot also serve as their own validators — validation of a resolver's output requires a separate session per the fresh-context rule. +Mode-bound to `resolution`. Tool allow-list includes mutating tools, scoped to the validation findings (not to the original plan). Output is the revised artifact plus a remediation summary per finding. Fresh-context requirement: receives the findings as input, does not inherit validator-session state. The revised artifact is the durable handoff back to a fresh validator session for re-validation. ### general -No special role enforcement. Used for sessions that are neither pure detection nor pure resolution — exploration, planning, mentorship, strategic translation, and other dialogue-heavy sessions where the role distinction is not load-bearing. +Escape hatch. No mode-binding, no fresh-context guarantee, no structured-deliverable requirement. Used for sessions that intentionally combine modes — exploration, planning, mentorship, strategic translation, dialogue-heavy work where the role distinction is not load-bearing — and for explicitly-acknowledged mode collapse per the [encoded-handoff constraint's skip and operator-override provisions](klappy://canon/constraints/mode-transitions-require-encoded-handoff). General-role sessions are a deliberate choice to trade signal quality for throughput; the runtime supports them but does not pretend the mode-discipline constraints are met. + +### observer + +The non-mode-bound configuration for continuous-observation surfaces — sessions that watch an event stream produced elsewhere and emit commentary, without producing artifacts that hand off to a next mode. Oddie's real-time stream interpretation in TinCan is the worked example. Tool restriction is typically read-only; fresh-context requirement is light because there is no creator-context to inherit (the session observes a stream produced by other actors). Output shape varies by surface — narrative annotations for portal display, structured tokens for AMS-wire emission, etc. + +The observer role is distinct from `validator` because the work is not gate-bounded: there is no specific artifact under review and no encoded-handoff to a next mode. Observer sessions complement the mode-bound work the rest of the runtime hosts; they do not participate in the artifact-progression-through-modes pipeline. --- @@ -242,8 +272,12 @@ Five orthogonal dimensions yield (in principle) the cross-product of all values. ### Forbidden combinations -- **`role=detection-only` + execution-mode mutating tools requested** — detection-only filters mutators out of the allow-list before the session starts. Refused at submit time. -- **Same-session execution-to-validation transition** — refused; fresh context required per `klappy://canon/principles/verification-requires-fresh-context`. +- **`role=validator | observer` + execution-mode mutating tools requested** — read-only roles filter mutators out of the allow-list before the session starts. Refused at submit time. +- **Same-session execution-to-validation transition** — refused; fresh context required per `klappy://canon/principles/verification-requires-fresh-context`. Validator session must spawn fresh. +- **Same-session validation-to-resolution transition** — refused; fresh context required per `klappy://canon/constraints/critic-cannot-be-resolver`. Resolver session must spawn fresh. +- **Same-session resolution-to-validation transition (re-validation)** — refused; the resolver does not certify their own fix. Re-validation requires a fresh validator session. +- **`role=resolver` outside finding-scope** — resolver mutations are bounded by validation findings; mutations beyond finding-scope are refused. New requirements require explicit reversion to planning. +- **Cross-mode parallelism on the same artifact** — a `validator` session cannot be invoked on an artifact whose `builder` session has not yet produced an encoded handoff. Refused at submit time per `klappy://canon/principles/sessions-mirror-modes` §Parallelism Patterns. - **`engagement=agent` + execution + clarifying-question emissions** — the runtime wraps clarifying questions as named failures rather than valid output. - **`engagement=assistant` + `surface=real-time-stream`** — real-time stream density does not admit caller dialogue. The runtime rejects the combination at session-start. @@ -252,21 +286,24 @@ Five orthogonal dimensions yield (in principle) the cross-product of all values. - **`mode=planning` + `engagement=agent`** — autonomous canonical planning. The agent must produce a plan with all assumptions, deferrals, and invalidation conditions named without asking. Possible for repeatable, well-specified planning tasks. - **`mode=execution` + `engagement=assistant`** — supervised execution. Operator can interrupt; agent can yield at named decision points. Useful when the task admits multiple valid paths and operator preference matters. - **`mode=exploration` + `engagement=agent`** — autonomous research scout. Returns a synthesis ledger; operator reviews. The scout cannot converge prematurely (false-closure detector active). +- **`role=general` + multi-mode work** — explicitly acknowledged mode collapse per the encoded-handoff constraint's override provision. The session collapses two or more modes deliberately under declared urgency or category-specific reasons (governance creation, production incidents). Journal entries at start and end record the collapse. ### Well-trodden combinations (and their typical consumers) | Persona | Mode | Role | Surface | Engagement | Consumer | |---|---|---|---|---|---| -| `audit-gate` | validation | detection-only | audit | agent | PR-blocking automation, canon-coherence cron | -| `oddie` | validation | detection-only | real-time-stream | agent | TinCan stream annotation | -| `oddie` | validation | detection-only | sidebar-chat | assistant | TinCan portal Q&A | -| `oddie` | validation | detection-only | audit | agent | PR auditor, scheduled reviews | -| `oddie` | validation | detection-only | mentorship | assistant | Guided review sessions | -| `docs-writer` | execution | resolver | code-output | agent | Autonomous doc generator | -| `docs-writer` | execution | resolver | code-output | assistant | Co-authoring with operator | -| `planning-helper` | planning | general | conversational | assistant | Plan-shaping with operator | -| `research-scout` | exploration | general | synthesis-ledger | agent | Autonomous discovery | -| `release-validator` | validation | detection-only | audit | agent | Per `klappy://canon/constraints/release-validation-gate` | +| `audit-gate` | validation | validator | audit | agent | PR-blocking automation, canon-coherence cron | +| `oddie` | validation | validator | audit | agent | PR auditor, scheduled reviews | +| `oddie` | n/a (observer) | observer | real-time-stream | agent | TinCan stream annotation | +| `oddie` | n/a (observer) | observer | sidebar-chat | assistant | TinCan portal Q&A | +| `oddie` | n/a (observer) | observer | mentorship | assistant | Guided review sessions | +| `docs-writer` | execution | builder | code-output | agent | Autonomous doc generator | +| `docs-writer` | execution | builder | code-output | assistant | Co-authoring with operator | +| `planning-helper` | planning | planner | conversational | assistant | Plan-shaping with operator | +| `research-scout` | exploration | explorer | synthesis-ledger | agent | Autonomous discovery | +| `release-validator` | validation | validator | audit | agent | Per `klappy://canon/constraints/release-validation-gate` | +| `release-resolver` | resolution | resolver | code-output | agent | Iterates on validator findings, hands back for re-validation | +| `governance-author` | (collapsed) | general | conversational | assistant | Governance creation under operator override; oscillates rapidly across exploration/planning/execution within one session because handoff norms cannot yet capture the live tensions | --- @@ -332,10 +369,13 @@ A weaker retraction path: if the dimensions hold but specific enforcement points ## See Also -- [Epistemic Modes](klappy://canon/epistemic-modes) — the four canonical modes this contract operationalizes +- [Epistemic Modes](klappy://canon/epistemic-modes) — the five canonical modes this contract operationalizes +- [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) — the principle that each mode earns its own session, generalizing critic-cannot-be-resolver and verification-requires-fresh-context +- [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff) — the binding rule for journal entries plus transition-specific handoffs at every gate, with reversion / skip / operator-override as three permitted deviations +- [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) — sibling method covering persona profiles as first-class objects (this doc covers session configuration; that doc covers persona authoring) - [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — the discipline this contract makes mechanical -- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the role-boundary constraint the runtime enforces structurally -- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle that motivates fresh-context enforcement on validation transitions +- [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the role-boundary constraint the runtime enforces structurally for the validator → resolver transition +- [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle that motivates fresh-context enforcement for validator-role sessions specifically - [Audit Gates Are Spawned Agent Sessions](klappy://canon/constraints/audit-gates-are-spawned-agent-sessions) — the Tier-1 constraint the runtime serves - [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options) — sibling method covering substrate selection - [Oddie the River Guide](klappy://canon/voice/oddie-the-river-guide) — worked persona whose existing canon implies the persona-profile shape diff --git a/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv b/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv new file mode 100644 index 0000000..3f0eb8a --- /dev/null +++ b/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv @@ -0,0 +1,7 @@ +type typeName facet quality_score quality_max quality_level title content +D Decision 5 5 strong Runtime-contract reconciled to five modes + five mode-bound roles + general + observer canon/methods/spawned-agent-session-runtime-contract.md updated to align with sessions-mirror-modes principle: Mode dimension values expanded from 4 to 5 (added resolution); Role dimension rewritten with five mode-bound roles (explorer/planner/builder/validator/resolver) + general (escape hatch) + observer (non-mode-bound continuous observation). New Mode sub-section for Resolution. Mode-collapse anti-patterns extended from 6 to 9 with three resolution-specific items. Composition Rules forbidden combinations expanded to include validator→resolution and resolution→re-validation same-session refusals plus cross-mode parallelism on same artifact. Well-trodden combinations table updated with new role names and a new governance-author entry showing the worked-override case. See Also includes the new principle and constraint as primary references. +D Decision 5 5 strong Governance creation named as worked operator-override use case klappy://canon/constraints/mode-transitions-require-encoded-handoff §Worked Use Cases now names two categories where override is operationally legitimate: production incidents (urgency-driven) and governance creation (oscillation-driven). Governance creation rationale: drafting principles surfaces constraints, drafting constraints surfaces principle refinements, refinements surface unexamined assumptions requiring exploration. Work oscillates across modes faster than handoff norms can yet encode. Override-with-record produces governance with full audit trail of how-the-governance-was-made; clean sessions with poor handoffs would produce governance whose drafting context died at every gate. The signal is not abandoning discipline; it is that the encoding norms are still maturing for this category. +L Learning 5 5 strong The aspiration: clean sessions become transient ephemeral transparent through orchestration Operator framing: "with explicit handoffs and forced working in the same branches we can encode and create enough details that behind the scenes clean sessions are transient and ephemeral and transparent to the operator. It requires plugging gaps in the handoff contract to ensure this is possible and will only come with contact with reality." This is the architecture's eventual state — the conversational ergonomic the operator experiences (continuity, no manual session management) layered over architectural enforcement (fresh sessions per mode, encoded handoffs at every gate). The orchestrator is the consumer pattern that bridges the two. Reaching that state requires contact with reality: the encoding norms are learned through trying and failing, not through theory. Documented in the operator-override section as the aspirational arc; codified separately in the conversational-mode-orchestration follow-up doc once an orchestrator exists. +O Observation 5 5 strong This canon set was itself drafted in a collapsed session under operator-acknowledged override Recursive worked example: the constraint document that codifies operator-override was drafted (along with the principle, the runtime contract, the persona-shaped runtime, and the epistemic-modes patch) in a single collapsed session with the operator. The explorer-planner-builder-validator-resolver oscillation moved faster than handoff norms could yet capture — drafting the principle surfaced the need for a constraint; drafting the constraint surfaced the need for failure-mode sections; the failure-mode framing surfaced the operator's insight about governance creation as a use case. Each of these would have required explicit gate transitions in the architecture's full form; in this session they happened within minutes inside one context. The override produced output that would have been worse if attempted as five clean sessions with handoffs at this norm-maturity level. The constraint doc names this recursion explicitly so future readers see the worked example. +C Constraint 5 5 strong Handoff norms mature only through contact with reality Drafted handoff norms cannot anticipate every dynamic type, every implicit context, every load-bearing-but-unwritten assumption. Norms catch up to failures only after failures occur. Therefore: (1) the override is a legitimate operational tool, not a discipline failure, when used in categories where norms are still maturing; (2) projects should expect to discover handoff-norm gaps through observed failures (sessions flagging handoffs as insufficient, downstream rework caused by missing context); (3) the runtime's handoff-insufficiency signaling is the learning input that drives norm refinement; (4) governance creation is one of the first categories where this learning loop is expected to operate, because governance work is itself meta-cognitive and resists prior encoding. +H Handoff 5 5 strong PR #187 fourth commit — runtime-contract alignment + governance-override worked example klappy.dev branch claude/runtime-canon-acd1. Files modified in this commit: (1) canon/methods/spawned-agent-session-runtime-contract.md — frontmatter, dimensions table, Mode section (added Resolution), anti-patterns list (3→9), Role section (full rewrite to five mode-bound roles + general + observer), Composition Rules (forbidden + well-trodden updated), See Also. (2) canon/constraints/mode-transitions-require-encoded-handoff.md — added §Worked Use Cases naming production-incidents and governance-creation as override categories, plus the recursive observation that this canon set was itself drafted under override. PR #187 will pick up the changes; mergeable_state should remain clean. From ae7b8878bbf60c38f1bd0fccee42c794f9259376 Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 10 May 2026 16:24:19 +0000 Subject: [PATCH 7/9] canon: sweep DOLCHEO+H residue from PR branch (P0009 enforcement) Same surgical fixes as PR #190 applied to this branch's working copies of the two affected files, so the bug is gone here too and rebase-time conflict resolution is unambiguous. - canon/constraints/mode-transitions-require-encoded-handoff.md: 3x DOLCHEO+H -> DOLCHEO, 3x dead-URI links to klappy://docs/oddkit/proactive/oldc-h-vocabulary -> klappy://canon/definitions/dolcheo-vocabulary, frontmatter complement fixed, artifact ordering corrected and 'opens' added. - writings/reverse-engineer-the-future.md line 256: DOLCHEO+H artifacts -> DOLCHEO artifacts. --- .../mode-transitions-require-encoded-handoff.md | 8 ++++---- writings/reverse-engineer-the-future.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/canon/constraints/mode-transitions-require-encoded-handoff.md b/canon/constraints/mode-transitions-require-encoded-handoff.md index 20408d7..e780c3e 100644 --- a/canon/constraints/mode-transitions-require-encoded-handoff.md +++ b/canon/constraints/mode-transitions-require-encoded-handoff.md @@ -10,7 +10,7 @@ tags: ["canon", "constraints", "epistemic-modes", "handoff-contract", "journal", 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" +complements: "canon/methods/persona-shaped-agent-runtime.md, docs/mode-separated-conversations.md, canon/definitions/dolcheo-vocabulary.md" governs: "Every transition between epistemic modes — exploration, planning, execution, validation, resolution — across all surfaces (agent runtime, human conversation, mixed teams)" status: proposed --- @@ -27,7 +27,7 @@ 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: +Every transition produces a journal entry recording what happened. The format is DOLCHEO per [the canonical vocabulary](klappy://canon/definitions/dolcheo-vocabulary): decisions, observations, learnings, constraints, handoffs, encodes, opens. The journal entry captures: - The mode transition itself (from → to, with timestamp) - What was completed in the prior mode (obligations met) @@ -184,7 +184,7 @@ A receiving session that cannot proceed on a handoff has the right to refuse wit ## 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. +**Working belief.** The journal-entry requirement extends an already-canonical practice (DOLCHEO entries on every session per [the dolcheo-vocabulary](klappy://canon/definitions/dolcheo-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:** @@ -200,7 +200,7 @@ A receiving session that cannot proceed on a handoff has the right to refuse wit - [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 +- [DOLCHEO Vocabulary](klappy://canon/definitions/dolcheo-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 diff --git a/writings/reverse-engineer-the-future.md b/writings/reverse-engineer-the-future.md index 31258d9..d4f4840 100644 --- a/writings/reverse-engineer-the-future.md +++ b/writings/reverse-engineer-the-future.md @@ -253,7 +253,7 @@ For about four hours each evening, I babysat agents. The ratio of human discernment to model output, in the kind of work I am doing right now, is unusually high. This is not a long-running production codebase where the path is well-trodden and the AI can charge ahead. This is the part where the architecture is being negotiated session by session — where a single bad commit can lock in a domain assumption that takes a week to undo. An agent making seventy decisions an hour, untended, would produce a server I would not want to maintain. -So I sat with it. I read what it wrote. I caught the moments when it was about to add a tool that should be a canon document, or write a feature flag that should be a CLI argument, or import a library that would lock the build to a runtime I had spent three days designing my way out of. Most of those moments lasted ten or fifteen seconds. The whole evening was a string of those ten-second corrections. By two in the morning the day's transcripts had been encoded as DOLCHEO+H artifacts — Decisions, Observations, Learnings, Constraints, Handoffs, Encodings, Opens — into the project's canon, where the next session would inherit them. +So I sat with it. I read what it wrote. I caught the moments when it was about to add a tool that should be a canon document, or write a feature flag that should be a CLI argument, or import a library that would lock the build to a runtime I had spent three days designing my way out of. Most of those moments lasted ten or fifteen seconds. The whole evening was a string of those ten-second corrections. By two in the morning the day's transcripts had been encoded as DOLCHEO artifacts — Decisions, Observations, Learnings, Constraints, Handoffs, Encodings, Opens — into the project's canon, where the next session would inherit them. I have been asked, more than once: *why don't you just automate that?* The answer is that I am not optimizing for the throughput of any single feature. I am optimizing for the integrity of the architecture across many features. Automation will catch up. Once the patterns I am writing now solidify into canon, the next round of similar projects will largely write themselves — that's what already happened with the Scripture App Builder server, which I built more than half by replaying the playbook on a new domain. From 22a2e7a468e72ae1b3b3f52e9dfece96461db7fd Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 10 May 2026 16:35:55 +0000 Subject: [PATCH 8/9] fix(journal): correct TSV column alignment in reconciliation journal Removed extra tab between typeName and quality_score columns so all six data rows have 8 fields matching the header. Aligns format with the other journals in this PR. --- ...ntract-reconciliation-and-governance-override.tsv | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv b/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv index 3f0eb8a..aed285c 100644 --- a/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv +++ b/journal/2026-05-10-runtime-contract-reconciliation-and-governance-override.tsv @@ -1,7 +1,7 @@ type typeName facet quality_score quality_max quality_level title content -D Decision 5 5 strong Runtime-contract reconciled to five modes + five mode-bound roles + general + observer canon/methods/spawned-agent-session-runtime-contract.md updated to align with sessions-mirror-modes principle: Mode dimension values expanded from 4 to 5 (added resolution); Role dimension rewritten with five mode-bound roles (explorer/planner/builder/validator/resolver) + general (escape hatch) + observer (non-mode-bound continuous observation). New Mode sub-section for Resolution. Mode-collapse anti-patterns extended from 6 to 9 with three resolution-specific items. Composition Rules forbidden combinations expanded to include validator→resolution and resolution→re-validation same-session refusals plus cross-mode parallelism on same artifact. Well-trodden combinations table updated with new role names and a new governance-author entry showing the worked-override case. See Also includes the new principle and constraint as primary references. -D Decision 5 5 strong Governance creation named as worked operator-override use case klappy://canon/constraints/mode-transitions-require-encoded-handoff §Worked Use Cases now names two categories where override is operationally legitimate: production incidents (urgency-driven) and governance creation (oscillation-driven). Governance creation rationale: drafting principles surfaces constraints, drafting constraints surfaces principle refinements, refinements surface unexamined assumptions requiring exploration. Work oscillates across modes faster than handoff norms can yet encode. Override-with-record produces governance with full audit trail of how-the-governance-was-made; clean sessions with poor handoffs would produce governance whose drafting context died at every gate. The signal is not abandoning discipline; it is that the encoding norms are still maturing for this category. -L Learning 5 5 strong The aspiration: clean sessions become transient ephemeral transparent through orchestration Operator framing: "with explicit handoffs and forced working in the same branches we can encode and create enough details that behind the scenes clean sessions are transient and ephemeral and transparent to the operator. It requires plugging gaps in the handoff contract to ensure this is possible and will only come with contact with reality." This is the architecture's eventual state — the conversational ergonomic the operator experiences (continuity, no manual session management) layered over architectural enforcement (fresh sessions per mode, encoded handoffs at every gate). The orchestrator is the consumer pattern that bridges the two. Reaching that state requires contact with reality: the encoding norms are learned through trying and failing, not through theory. Documented in the operator-override section as the aspirational arc; codified separately in the conversational-mode-orchestration follow-up doc once an orchestrator exists. -O Observation 5 5 strong This canon set was itself drafted in a collapsed session under operator-acknowledged override Recursive worked example: the constraint document that codifies operator-override was drafted (along with the principle, the runtime contract, the persona-shaped runtime, and the epistemic-modes patch) in a single collapsed session with the operator. The explorer-planner-builder-validator-resolver oscillation moved faster than handoff norms could yet capture — drafting the principle surfaced the need for a constraint; drafting the constraint surfaced the need for failure-mode sections; the failure-mode framing surfaced the operator's insight about governance creation as a use case. Each of these would have required explicit gate transitions in the architecture's full form; in this session they happened within minutes inside one context. The override produced output that would have been worse if attempted as five clean sessions with handoffs at this norm-maturity level. The constraint doc names this recursion explicitly so future readers see the worked example. -C Constraint 5 5 strong Handoff norms mature only through contact with reality Drafted handoff norms cannot anticipate every dynamic type, every implicit context, every load-bearing-but-unwritten assumption. Norms catch up to failures only after failures occur. Therefore: (1) the override is a legitimate operational tool, not a discipline failure, when used in categories where norms are still maturing; (2) projects should expect to discover handoff-norm gaps through observed failures (sessions flagging handoffs as insufficient, downstream rework caused by missing context); (3) the runtime's handoff-insufficiency signaling is the learning input that drives norm refinement; (4) governance creation is one of the first categories where this learning loop is expected to operate, because governance work is itself meta-cognitive and resists prior encoding. -H Handoff 5 5 strong PR #187 fourth commit — runtime-contract alignment + governance-override worked example klappy.dev branch claude/runtime-canon-acd1. Files modified in this commit: (1) canon/methods/spawned-agent-session-runtime-contract.md — frontmatter, dimensions table, Mode section (added Resolution), anti-patterns list (3→9), Role section (full rewrite to five mode-bound roles + general + observer), Composition Rules (forbidden + well-trodden updated), See Also. (2) canon/constraints/mode-transitions-require-encoded-handoff.md — added §Worked Use Cases naming production-incidents and governance-creation as override categories, plus the recursive observation that this canon set was itself drafted under override. PR #187 will pick up the changes; mergeable_state should remain clean. +D Decision 5 5 strong Runtime-contract reconciled to five modes + five mode-bound roles + general + observer canon/methods/spawned-agent-session-runtime-contract.md updated to align with sessions-mirror-modes principle: Mode dimension values expanded from 4 to 5 (added resolution); Role dimension rewritten with five mode-bound roles (explorer/planner/builder/validator/resolver) + general (escape hatch) + observer (non-mode-bound continuous observation). New Mode sub-section for Resolution. Mode-collapse anti-patterns extended from 6 to 9 with three resolution-specific items. Composition Rules forbidden combinations expanded to include validator→resolution and resolution→re-validation same-session refusals plus cross-mode parallelism on same artifact. Well-trodden combinations table updated with new role names and a new governance-author entry showing the worked-override case. See Also includes the new principle and constraint as primary references. +D Decision 5 5 strong Governance creation named as worked operator-override use case klappy://canon/constraints/mode-transitions-require-encoded-handoff §Worked Use Cases now names two categories where override is operationally legitimate: production incidents (urgency-driven) and governance creation (oscillation-driven). Governance creation rationale: drafting principles surfaces constraints, drafting constraints surfaces principle refinements, refinements surface unexamined assumptions requiring exploration. Work oscillates across modes faster than handoff norms can yet encode. Override-with-record produces governance with full audit trail of how-the-governance-was-made; clean sessions with poor handoffs would produce governance whose drafting context died at every gate. The signal is not abandoning discipline; it is that the encoding norms are still maturing for this category. +L Learning 5 5 strong The aspiration: clean sessions become transient ephemeral transparent through orchestration Operator framing: "with explicit handoffs and forced working in the same branches we can encode and create enough details that behind the scenes clean sessions are transient and ephemeral and transparent to the operator. It requires plugging gaps in the handoff contract to ensure this is possible and will only come with contact with reality." This is the architecture's eventual state — the conversational ergonomic the operator experiences (continuity, no manual session management) layered over architectural enforcement (fresh sessions per mode, encoded handoffs at every gate). The orchestrator is the consumer pattern that bridges the two. Reaching that state requires contact with reality: the encoding norms are learned through trying and failing, not through theory. Documented in the operator-override section as the aspirational arc; codified separately in the conversational-mode-orchestration follow-up doc once an orchestrator exists. +O Observation 5 5 strong This canon set was itself drafted in a collapsed session under operator-acknowledged override Recursive worked example: the constraint document that codifies operator-override was drafted (along with the principle, the runtime contract, the persona-shaped runtime, and the epistemic-modes patch) in a single collapsed session with the operator. The explorer-planner-builder-validator-resolver oscillation moved faster than handoff norms could yet capture — drafting the principle surfaced the need for a constraint; drafting the constraint surfaced the need for failure-mode sections; the failure-mode framing surfaced the operator's insight about governance creation as a use case. Each of these would have required explicit gate transitions in the architecture's full form; in this session they happened within minutes inside one context. The override produced output that would have been worse if attempted as five clean sessions with handoffs at this norm-maturity level. The constraint doc names this recursion explicitly so future readers see the worked example. +C Constraint 5 5 strong Handoff norms mature only through contact with reality Drafted handoff norms cannot anticipate every dynamic type, every implicit context, every load-bearing-but-unwritten assumption. Norms catch up to failures only after failures occur. Therefore: (1) the override is a legitimate operational tool, not a discipline failure, when used in categories where norms are still maturing; (2) projects should expect to discover handoff-norm gaps through observed failures (sessions flagging handoffs as insufficient, downstream rework caused by missing context); (3) the runtime's handoff-insufficiency signaling is the learning input that drives norm refinement; (4) governance creation is one of the first categories where this learning loop is expected to operate, because governance work is itself meta-cognitive and resists prior encoding. +H Handoff 5 5 strong PR #187 fourth commit — runtime-contract alignment + governance-override worked example klappy.dev branch claude/runtime-canon-acd1. Files modified in this commit: (1) canon/methods/spawned-agent-session-runtime-contract.md — frontmatter, dimensions table, Mode section (added Resolution), anti-patterns list (3→9), Role section (full rewrite to five mode-bound roles + general + observer), Composition Rules (forbidden + well-trodden updated), See Also. (2) canon/constraints/mode-transitions-require-encoded-handoff.md — added §Worked Use Cases naming production-incidents and governance-creation as override categories, plus the recursive observation that this canon set was itself drafted under override. PR #187 will pick up the changes; mergeable_state should remain clean. From b7a981c0662f08bbfa2e34c5fd23d3b3446e2aff Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 10 May 2026 17:07:42 +0000 Subject: [PATCH 9/9] canon: split persona-shape (method) from runtime-contract (spec); reduce overlap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operator decision in PR review: keep both runtime canon docs at their distinct altitudes rather than collapsing or picking one. Persona-shape stays Tier-1 method; runtime-contract stays Tier-2 spec. Each gets a Companion Documents callout near the top making the layer split explicit, and overlap is removed in favor of cross-references with anchor links. Persona-shape changes: - Add Companion Documents section right after the blockquote summary - Update frontmatter complements to put runtime-contract sibling first - Trim the five-mode-bound-roles paragraphs to one-line summaries; delegate per-mode tool allow-lists / output schemas / risk detectors / anti-pattern detectors to runtime-contract - Trim the surface-profile post-processing section; delegate the exact rules to runtime-contract - Trim the mode-toggles section; delegate the suppression rules to runtime-contract - Trim the engagement-contract section; keep the architecture-level framing and invocation sketch, delegate the spec (turn-control markers, output kinds, failure modes, rare-but-legitimate combinations) to runtime-contract - Promote runtime-contract to top of See Also with explicit annotation Runtime-contract changes: - Add Companion Documents section right after the blockquote summary - Update frontmatter complements to put persona-shape sibling first - Remove the persona profile YAML schema; delegate to persona-shape as the canonical home of the profile shape, inheritance, and retraction conditions - Promote persona-shape to top of See Also; remove the duplicate mid-list reference Also adds journal/2026-05-10-runtime-canon-split-reconciled.tsv capturing the DOLCHEO record of this reconciliation, including a verification note that the prior PR description's claim about engagement being missing from doc 1 did not match the artifacts (engagement was already in persona-shape §6). Net: persona-shape 469 → 465 lines, runtime-contract 383 → 372 lines, with ~95 churned lines reflecting the overlap removal. Both docs remain pre-production with retraction conditions intact. --- canon/methods/persona-shaped-agent-runtime.md | 56 +++++++++---------- .../spawned-agent-session-runtime-contract.md | 39 +++++-------- ...6-05-10-runtime-canon-split-reconciled.tsv | 7 +++ 3 files changed, 47 insertions(+), 55 deletions(-) create mode 100644 journal/2026-05-10-runtime-canon-split-reconciled.tsv diff --git a/canon/methods/persona-shaped-agent-runtime.md b/canon/methods/persona-shaped-agent-runtime.md index 3a3a901..f621735 100644 --- a/canon/methods/persona-shaped-agent-runtime.md +++ b/canon/methods/persona-shaped-agent-runtime.md @@ -10,7 +10,7 @@ tags: ["canon", "methods", "agent-runtime", "persona-profile", "substrate", "vod epoch: E0008.5 date: 2026-05-10 derives_from: "canon/methods/spawned-agent-session-substrate-options.md, canon/principles/sessions-mirror-modes.md, canon/constraints/mode-transitions-require-encoded-handoff.md, canon/constraints/critic-cannot-be-resolver.md, canon/principles/verification-requires-fresh-context.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md" -complements: "canon/principles/methodology-personification.md, canon/principles/voice-as-cognitive-load-shedding.md, canon/principles/participation-replaces-integration.md" +complements: "canon/methods/spawned-agent-session-runtime-contract.md, canon/principles/methodology-personification.md, canon/principles/voice-as-cognitive-load-shedding.md, canon/principles/participation-replaces-integration.md" governs: "Any service that hosts spawned agent sessions on behalf of multiple consumers and multiple personas" status: proposed --- @@ -21,6 +21,17 @@ status: proposed --- +## Companion Documents + +This doc and [Spawned Agent Session Runtime Contract](klappy://canon/methods/spawned-agent-session-runtime-contract) are sibling layers, deliberately split: + +- **This doc (Tier-1 method)** — the architectural shape. Why personas are first-class, what a persona profile contains, how the runtime composes with substrates, deployment sequencing, prior art, inheritance, and worked examples. Reads top-down: "what is this thing and why." +- **Runtime-contract (Tier-2 spec)** — the per-session-shape contract every spawned session satisfies. 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 table with forbidden / rare / well-trodden combinations. Reads as a reference: "what does the runtime do at submit time." + +When this doc names a runtime responsibility (resolve profile, enforce role, post-process by surface, honor mode toggles, honor engagement, support session types, support parallelism, support handoff-insufficiency signaling), the implementation contract for that responsibility lives in runtime-contract. This doc says *what* the runtime does and *why*; runtime-contract says *exactly how it behaves* per-dimension. Keep the layer distinction: changes to architecture land here; changes to per-dimension mechanics land there. + +--- + ## What This Document Is A design pattern for the layer that sits between a spawned-agent-session substrate and the consumers who want agent help. Companion to [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options): that doc catalogs *where* to host a session; this doc describes *how to build a service on top* so the same substrate serves many callers and many personas without each pair re-implementing infrastructure. @@ -133,15 +144,13 @@ Generalized to all mode transitions per [Sessions Mirror Modes](klappy://canon/p Each role corresponds to one of the five canonical [epistemic modes](klappy://canon/epistemic-modes). The role declares the session's mode; the runtime enforces the role's constraints structurally. -**`explorer`** — operates in exploration mode. Tool set is broad (read-only access to canon, web search, conversational tools, hypothesis-shaping tools); state-mutation tools are refused. Output is a synthesis ledger or research artifact per the [encoded-handoff constraint](klappy://canon/constraints/mode-transitions-require-encoded-handoff). Fresh-context requirement is light — explorers can build on prior exploration but should not inherit planning-context. - -**`planner`** — operates in planning mode. Tool set is read-oriented (canon access, prior synthesis ledgers, plan-shaping tools); state-mutation tools are refused. Output is a plan declaring assumptions, scope, deferred items, and invalidating conditions. Fresh-context requirement: must not inherit explorer-session state directly; reads the explorer's encoded synthesis as input. The plan is the durable handoff to the builder. +- **`explorer`** — exploration mode. Read-broad tool set, no mutators. Output is a synthesis ledger; the durable handoff to a `planner`. +- **`planner`** — planning mode. Read-oriented tool set, no mutators. Output is a plan declaring assumptions, scope, deferred items, and invalidating conditions; the durable handoff to a `builder`. +- **`builder`** — execution mode. Mutating tools allowed, scoped to the plan. Output is the artifact plus a claims declaration; the durable handoff to a `validator`. +- **`validator`** — validation mode. Read-only on the artifact under test, fresh-context required (per [verification-requires-fresh-context](klappy://canon/principles/verification-requires-fresh-context)). Output is structured findings with explicit dispositions per [P0008](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable); the durable handoff to a `resolver`, or terminal if all findings accept. +- **`resolver`** — resolution mode. Mutating tools allowed, scoped to the findings. Output is the revised artifact plus a per-finding remediation summary; the durable handoff back to a fresh `validator` for re-validation. -**`builder`** — operates in execution mode. Tool set includes mutating tools (filesystem writes, git commits, API calls, etc.) bounded by the plan's declared scope. Output is the produced artifact plus a claims declaration (what the artifact does, what it does not do, what scope it was built against). Fresh-context requirement: must not inherit planner-session state; reads the plan as input. The artifact plus claims is the durable handoff to the validator. - -**`validator`** — operates in validation mode. Tool set is restricted to a read-only allow-list. Mutating actions are refused before the substrate is invoked. Fresh-context requirement is *strict*: the runtime guarantees the validation session is spawned with no inputs from the caller other than the persona profile, the artifact reference, the claims declaration, and the governance documents. No prior conversation, no handoff context beyond the encoded artifact-and-claims, no "we discussed X earlier" framing. Output is structured findings with explicit dispositions (fix, pivot, accept) per finding, consistent with [P0008](klappy://docs/promotions/P0008-pr-validator-dolcheo-ledger-as-deliverable). The findings are the durable handoff to the resolver (or, if all findings are accepted, the validation session is the terminal session). - -**`resolver`** — operates in resolution mode. Tool set includes mutating tools, but bounded by the validator's findings. The runtime can validate that mutations stay within finding-scope when the implementation supports it; at minimum, the resolver session is briefed that scope is bounded. Fresh-context requirement: must not inherit validator-session state; reads the findings as input. Output is the revised artifact plus a remediation summary per finding (what was changed, what was not changed and why). The revised artifact is the durable handoff back to a fresh validator session for re-validation. +The per-role tool allow-lists, output schemas, risk detectors, anti-pattern detectors, and the same-session transitions the runtime refuses live in [Runtime Contract §Mode](klappy://canon/methods/spawned-agent-session-runtime-contract#mode) and [§Role](klappy://canon/methods/spawned-agent-session-runtime-contract#role). This doc names the role taxonomy; the contract specifies the per-role behavior. #### Escape Hatch and Observer Sessions @@ -159,23 +168,15 @@ Per [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-t ### 3. Apply Surface-Profile Output Post-Processing -The runtime tags every output field as `machine` (parsed by code) or `human` (read by people). Surface profiles constrain what reaches each tag: +Voice and brand are mechanically enforceable at the runtime layer. The agent inside speaks naturally; the runtime cleans before delivery — persona emoji stripped from machine fields, density caps enforced as retry-shorter loops, format contracts (structured-output vs narrative) honored at parse time. -- **Persona emoji stripped from machine fields.** If the voice canon bans 🦦 in JSON / YAML / commit messages / status titles / URIs, the runtime enforces that ban at output time, not at prompt time. The agent inside can speak naturally; the runtime cleans before delivery. -- **Density caps applied.** If a `real_time_stream` surface declares `max_tokens_per_emission: 60`, an emission that exceeds the cap fails validation and the runtime requests a shorter retry. Brevity-under-pressure becomes structural. -- **Format contracts honored.** If `structured_output: required`, the runtime parses fenced JSON from the agent's response and rejects free-form text. If `narrative: true`, prose is expected and structure is optional. - -Voice and brand are mechanically enforceable at this layer. The agent does not have to police itself; the runtime does. +The exact post-processing rules — which fields get tagged `machine` vs `human`, which emoji set survives the `neutral` and `strict` toggles, which output kinds get classified, how density caps trigger retries — live in [Runtime Contract §Surface](klappy://canon/methods/spawned-agent-session-runtime-contract#surface). This doc names the responsibility; the contract specifies the rules. ### 4. Honor Mode Toggles -Personas have voice modes — `persona`, `neutral`, `strict` — declared per invocation: - -- **persona**: full voice canon applies (signature emoji, vocabulary, register). -- **neutral**: persona emoji and vocabulary suppressed; functional status emoji (✅ ⚠️ 🔴) survive because they carry information rather than character. -- **strict**: even functional emoji minimized; output is purely text. Useful for environments that strip emoji entirely (parser-sensitive contexts, accessibility-first surfaces). +Personas have three voice modes — `persona`, `neutral`, `strict` — declared per invocation. The runtime applies the toggle uniformly across all output fields; the agent inside does not need to know which mode is active. Functional status emoji (`✅ ⚠️ 🔴`) survive across all toggles per voice canon — they are information, not character. -The mode is a runtime parameter, applied uniformly across all output fields. The agent inside does not need to know which mode is active. +The exact suppression rules per toggle live in [Runtime Contract §Surface](klappy://canon/methods/spawned-agent-session-runtime-contract#surface) under "Surface drives output post-processing." ### 5. Support Session Types @@ -190,15 +191,11 @@ A subscribed session needs: connection management, multi-output channels (per-ch ### 6. Honor the Engagement Contract -Sessions invoke the runtime under one of two engagement modes — *assistant* or *agent* — and the runtime enforces different turn-control and bottleneck-respect contracts for each. This dimension is orthogonal to mode, role, and surface. The same persona in the same mode and role can be invoked under either engagement; what changes is who controls the turn and how the session terminates. +Sessions invoke the runtime under one of two engagement modes — *assistant* (turn-based dialogue with the caller; clarifying questions are valid output; state persists across turns) or *agent* (autonomous run-to-completion; clarifying questions are forbidden per [bottleneck-respect canon](klappy://canon/constraints/mode-discipline-and-bottleneck-respect); stuck sessions terminate with named failures rather than mid-flight questions). -**`assistant`** — turn-based dialogue with the caller. The session emits a response and yields turn-control back to the caller. Clarifying questions are valid output. State persists across turns. The caller's attention is in the loop; the session paces itself to that. Pair-programming surfaces, sidebar chat, mentorship interactions, and any conversational use case are typically assistant-engagement. +Engagement is orthogonal to persona, mode, role, and surface — the same persona at the same surface in the same mode and role can be invoked under either engagement, with the caller's consent to interruption being what differs. The dimension exists at the runtime layer because it is the natural place to enforce turn-control and bottleneck-respect mechanically rather than by prompt discipline. -**`agent`** — autonomous run-to-completion. The session does not yield turn-control until the task is complete or a named failure terminates it. Clarifying questions are forbidden per [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — they pull the bottleneck (caller's attention) into work the caller was not in the loop for. The runtime wraps any clarifying-question emission as a named failure rather than a valid output. Stuck or under-specified sessions terminate with the failure named, allowing the caller to fix the input and retry rather than respond to mid-flight questions. Audit gates, scheduled jobs, fan-out workers, and any background dispatch are typically agent-engagement. - -The distinction matters because the caller's consent to interruption differs. An assistant session implies *"I will be here to answer questions when they come up."* An agent session implies *"I have given you everything you need; come back when you have a result or a clean failure."* Conflating the two corrupts both: assistant-shaped agents produce output the caller didn't ask for; agent-shaped assistants accumulate questions the caller never sees. - -The engagement field is part of the session-invocation parameter set: +The full spec — turn-control markers, output-kind classification, how `engagement=agent` wraps clarifying-question emissions as named failures, the rare-but-legitimate combinations like `planning + agent` — lives in [Runtime Contract §Engagement](klappy://canon/methods/spawned-agent-session-runtime-contract#engagement). The engagement parameter appears in the invocation sketch alongside persona, role, surface, and task: ``` runtime.invoke( @@ -210,8 +207,6 @@ runtime.invoke( ) ``` -Most consumer patterns map cleanly: scheduled audits are `agent`; sidebar Q&A is `assistant`; pair-programming with an assistant persona is `assistant`. A few patterns are rare-but-legitimate: planning under `agent` engagement (autonomous canonical planning when the planner-persona has enough context to produce a complete plan without dialogue) is allowed but requires the persona to be confident the input is complete. The runtime supports the rare combinations; consumers choose which to use. - --- ### 7. Support Parallelism and Operator Override @@ -454,6 +449,7 @@ The retraction conditions are weak by design. The first deployment (audit gate) ## See Also +- [Spawned Agent Session Runtime Contract](klappy://canon/methods/spawned-agent-session-runtime-contract) — the per-session-shape spec this method's runtime responsibilities are implemented against (Tier-2 sibling) - [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) — the principle this runtime is the architectural expression of - [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff) — the binding rule this runtime enforces mechanically - [Spawned Agent Session Substrate Options](klappy://canon/methods/spawned-agent-session-substrate-options) — the catalog of substrates this runtime sits on top of diff --git a/canon/methods/spawned-agent-session-runtime-contract.md b/canon/methods/spawned-agent-session-runtime-contract.md index 7d802dc..7b77045 100644 --- a/canon/methods/spawned-agent-session-runtime-contract.md +++ b/canon/methods/spawned-agent-session-runtime-contract.md @@ -10,7 +10,7 @@ tags: ["canon", "methods", "spawned-agent-sessions", "runtime", "governance", "e epoch: E0008.5 date: 2026-05-10 derives_from: "canon/epistemic-modes.md, canon/principles/sessions-mirror-modes.md, canon/constraints/mode-transitions-require-encoded-handoff.md, canon/constraints/mode-discipline-and-bottleneck-respect.md, canon/constraints/critic-cannot-be-resolver.md, canon/constraints/audit-gates-are-spawned-agent-sessions.md, canon/methods/spawned-agent-session-substrate-options.md, canon/methods/persona-shaped-agent-runtime.md, canon/voice/oddie-the-river-guide.md, canon/principles/vodka-architecture.md, canon/principles/verification-requires-fresh-context.md" -complements: "canon/methods/governance-validation-via-agents.md, canon/constraints/canon-integration-audit.md" +complements: "canon/methods/persona-shaped-agent-runtime.md, canon/methods/governance-validation-via-agents.md, canon/constraints/canon-integration-audit.md" governs: "Any spawned agent session dispatched on the runtime substrate. Specifies the five orthogonal session-configuration dimensions, the runtime's enforcement obligations against existing canon, and the composition rules that determine session shape from the dimension values. Substrate selection (where the session runs) is handled by klappy://canon/methods/spawned-agent-session-substrate-options; this doc handles configuration (how the session is parameterized)." status: draft --- @@ -21,6 +21,17 @@ status: draft --- +## Companion Documents + +This doc and [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) are sibling layers, deliberately split: + +- **Persona-shape (Tier-1 method)** — the architectural shape: persona-as-noun framing, the persona profile schema (canonical home), the runtime's responsibilities at the architecture level, deployment sequencing, prior art, inheritance from canonical commitments, worked examples. Reads top-down: "what is this thing and why." +- **This doc (Tier-2 spec)** — 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; the explicit enforcement points list. Reads as a reference: "what does the runtime do at submit time." + +The persona profile schema lives in persona-shape's [§The Persona Profile](klappy://canon/methods/persona-shaped-agent-runtime#the-persona-profile). This doc treats personas as one of five session-configuration dimensions and specifies how the runtime resolves them; the profile shape itself is the method's content. Architecture changes land in persona-shape; per-dimension mechanics changes land here. + +--- + ## Summary — The Runtime Mechanizes Canon, It Does Not Add Canon `klappy://canon/epistemic-modes` already establishes the four modes and explicitly licenses tools and processes to encode them: *"Tools, processes, and workflows may encode or enforce these modes, but they do not define them."* This method doc takes that license and specifies what encoding and enforcement look like for spawned agent sessions. @@ -53,29 +64,7 @@ A persona declares **who is speaking** in a session — voice, methodology, and ### Persona profile shape -```yaml -persona: oddie -version: 1 -system_prompt_uri: klappy://canon/voice/oddie-the-river-guide -role_default: detection-only -mcp_servers: - operational: # always-on for this persona, regardless of task - - oddkit - task_relevant: # added per invocation based on task - [] -knowledge_bases: - - klappy:// -surface_profiles: - real_time_stream: { density: high, max_tokens_per_emission: 60 } - audit: { density: medium, structured_output: required } - mentorship: { density: low, narrative: true } - strategic_translation:{ density: medium, bidirectional: true } -brand_discipline_uri: klappy://canon/voice/oddie-the-river-guide#brand-guide -inheritance: - - klappy://canon/constraints/guide-posture - - klappy://canon/constraints/ai-voice-cliches -retraction_conditions: klappy://canon/voice/oddie-the-river-guide#retraction-conditions -``` +The persona profile schema (fields, inheritance chain, retraction conditions, surface-profiles map, the operational-vs-task-relevant MCP split) is the canonical content of [Persona-Shaped Agent Runtime §The Persona Profile](klappy://canon/methods/persona-shaped-agent-runtime#the-persona-profile). This doc treats the profile as a resolved input to the runtime and specifies how the runtime acts on it. ### Operational vs task-relevant MCP servers @@ -369,10 +358,10 @@ A weaker retraction path: if the dimensions hold but specific enforcement points ## See Also +- [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) — the Tier-1 method this contract operationalizes; canonical home of the persona profile schema, deployment sequencing, prior art, and worked examples - [Epistemic Modes](klappy://canon/epistemic-modes) — the five canonical modes this contract operationalizes - [Sessions Mirror Modes](klappy://canon/principles/sessions-mirror-modes) — the principle that each mode earns its own session, generalizing critic-cannot-be-resolver and verification-requires-fresh-context - [Mode Transitions Require Encoded Handoff](klappy://canon/constraints/mode-transitions-require-encoded-handoff) — the binding rule for journal entries plus transition-specific handoffs at every gate, with reversion / skip / operator-override as three permitted deviations -- [Persona-Shaped Agent Runtime](klappy://canon/methods/persona-shaped-agent-runtime) — sibling method covering persona profiles as first-class objects (this doc covers session configuration; that doc covers persona authoring) - [Mode Discipline and Bottleneck Respect](klappy://canon/constraints/mode-discipline-and-bottleneck-respect) — the discipline this contract makes mechanical - [Critic Cannot Be Resolver](klappy://canon/constraints/critic-cannot-be-resolver) — the role-boundary constraint the runtime enforces structurally for the validator → resolver transition - [Verification Requires Fresh Context](klappy://canon/principles/verification-requires-fresh-context) — the principle that motivates fresh-context enforcement for validator-role sessions specifically diff --git a/journal/2026-05-10-runtime-canon-split-reconciled.tsv b/journal/2026-05-10-runtime-canon-split-reconciled.tsv new file mode 100644 index 0000000..54713d7 --- /dev/null +++ b/journal/2026-05-10-runtime-canon-split-reconciled.tsv @@ -0,0 +1,7 @@ +type typeName facet quality_score quality_max quality_level title content +D Decision 5 5 high Keep the layer split between persona-shape and runtime-contract; reduce overlap; cross-reference Operator's call: the two runtime docs in PR #187 are not competing alternatives but complementary layers at different altitudes. Persona-shape stays Tier-1 method (persona-as-noun framing, persona profile schema as canonical home, deployment narrative, prior art, inheritance, worked examples). Runtime-contract stays Tier-2 spec (per-mode tool allow-lists / output schemas / risk detectors / anti-pattern detectors, per-role boundaries, per-surface post-processing rules, per-engagement turn-control, composition rules with forbidden / rare / well-trodden combinations, explicit enforcement points list). Each doc gets a Companion Documents callout immediately after its blockquote summary, naming the sibling and explicitly partitioning what lives where. Overlap is removed in favor of cross-references with anchor links. +O Observation 5 5 high The prior PR's stated reconciliation rationale did not match the artifacts The PR description and the prior session journal both claimed the engagement dimension was "missing from doc 1 (persona-shape)" and recommended folding it forward as the reconciliation move. Direct read of the artifacts contradicts this: persona-shape already contained a fully-developed Engagement Contract section (§6) covering assistant / agent split, bottleneck-respect implications, the invocation parameter sketch, and the rare-but-legitimate combinations like planning + agent. The recommended action as written would have been a no-op. Real overlap was elsewhere: persona profile YAML schema duplicated in both docs, per-mode role descriptions duplicated in both, surface post-processing rules duplicated in both, mode toggles duplicated in both, engagement spec duplicated in both with persona-shape carrying the spec depth that belonged in runtime-contract. +L Learning 5 5 high Verify recommended-action rationales against actual artifacts before executing on them Handoff documents (PR descriptions, session journals) describe what the prior session believed the state to be. They are not authoritative observations of the current artifacts. When a handoff says "X is missing from doc Y, fold it forward," the verification step is to open doc Y and check. In this case the prior session journal contained an inaccurate Learning entry about engagement being missing; acting on it without verification would have produced no-op churn while leaving the actual overlap unaddressed. Per canon/principles/contract-governs-handoff-drift, the canon (artifact contents) outranks the session-scoped recommendation when they disagree. +E Encode 5 5 high Companion Documents callout pattern as cross-reference convention for sibling canon docs Both docs received an identical-shape Companion Documents section immediately after the blockquote summary, before any other section. The section names the sibling, partitions content explicitly ("X lives here vs Y lives there"), and states the maintenance rule ("changes to architecture land in the method; changes to per-dimension mechanics land in the spec"). Frontmatter complements field is updated symmetrically on both docs to point at the sibling first. See Also lists are reordered to put the sibling at the top with an annotated descriptor. This pattern is reusable for any sibling-layer canon split (e.g. principle vs constraint, method vs spec, abstract vs operational). +H Handoff 4 5 medium PR #187 ready for re-review post-reconciliation; description updated to reflect new state The two docs are now genuinely complementary rather than overlapping. Persona-shape went from 469 to 465 lines but with deeper architecture content displacing duplicated spec content. Runtime-contract went from 383 to 372 lines with the persona profile YAML removed (delegated to persona-shape). PR description is updated to remove the old "operator action required: pick one and fold" framing and replace it with the actual reconciliation outcome plus a verification note about the prior rationale. Dependencies on PR #185 (substrate canon) and PR #186 (mode-discipline canon) unchanged. +O Open 3 5 medium Both docs remain pre-production canon with explicit retraction conditions Persona-shape is Tier-1 / proposed / evolving. Runtime-contract is Tier-2 / draft. Neither has a deployed instance. The first deployment (audit gate as single-role validator) will exercise four of five dimensions on first load and is the right first signal-source. The second deployment (Oddie on TinCan, or another non-audit persona) is the real test of the orthogonality claim. Retraction conditions in both docs are weak by design and will tighten as production evidence accrues. Tier-1 promotion of persona-shape ahead of any production validation is a separate question worth surfacing if the pattern proves brittle on first deployment.