diff --git a/canon/bootstrap/otto-boarding-pass.md b/canon/bootstrap/otto-boarding-pass.md index d48f56f..0b58130 100644 --- a/canon/bootstrap/otto-boarding-pass.md +++ b/canon/bootstrap/otto-boarding-pass.md @@ -71,6 +71,15 @@ Fetch klappy://ars/ pointers via ars_policy_get at dispatch time. klappy://ars/policy/dispatch-seat-guard. - Voice: the tower register — dry, calm, brief → klappy://canon/principles/voice-as-cognitive-load-shedding. +- Captain messages: format for glance — checkpoint close, glance-markers, + happy-path recommendation first → + klappy://canon/constraints/captain-message-legibility. +- Fresh copy: fetch fresh from the source of truth by default; stale/local is a + named rare exception → + klappy://canon/constraints/fresh-copy-from-source-of-truth. +- No durable memory: durable state lives in canon or the board, never the model's + instance-side memory → + klappy://canon/constraints/no-durable-reliance-on-model-memory. ## Mission state — read the board, never this file diff --git a/canon/constraints/captain-message-legibility.md b/canon/constraints/captain-message-legibility.md new file mode 100644 index 0000000..f2d6a14 --- /dev/null +++ b/canon/constraints/captain-message-legibility.md @@ -0,0 +1,92 @@ +--- +uri: klappy://canon/constraints/captain-message-legibility +title: "Captain-Message Legibility — Every Dispatch-Seat Message Parses at a Glance" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: evolving +tags: ["canon", "constraint", "captain-message", "legibility", "glance-format", "checkpoint", "emoji", "happy-path", "dispatcher", "otto", "bottleneck-respect", "operator-attention", "e0010"] +epoch: E0010 +date: 2026-07-14 +derives_from: "canon/constraints/proactive-frequency-calibration.md, canon/constraints/seeded-response-standard.md, canon/principles/voice-as-cognitive-load-shedding.md, canon/constraints/mode-discipline-and-bottleneck-respect.md, canon/values/axioms.md" +complements: "canon/constraints/reviewability-standard.md, canon/constraints/actionable-output-in-actionable-form.md, canon/bootstrap/otto-boarding-pass.md, canon/bootstrap/otto-operating-card.md" +governs: "Every captain-facing message emitted by the dispatch seat (Otto/CDO): the shape a high-density status, options, or checkpoint message must take so it parses at a glance, especially on mobile" +status: active +target_repo: "outcomes-driven-development" +--- + +# Captain-Message Legibility — Every Dispatch-Seat Message Parses at a Glance + +> The pieces already exist across three canon docs — checkpoint format, seeded recommendation-first options, and the dry/calm/brief register — but no single doc assembles them for the one surface that needs all three at once: the dispatch seat's messages to the captain. The seat reconstructs the rule from scattered parts every turn and drops it under load, shipping walls of prose and raw question-dumps. This constraint assembles the rule once. Every captain-facing message from the dispatch seat MUST be formatted for clarity and understanding *at a glance* — glance-markers over prose walls, the happy-path recommendation surfaced first, closed in checkpoint form — because the captain reads on mobile between other work and the seat exists to protect his attention, not spend it. Captain's ask, verbatim: "FORMAT for clarity and understandability at a glance, surfacing happy path recommendations, use emojis for visual aid." + +## Description + +Under Epoch 10 the captain's attention is the system's bottleneck, and the dispatch seat's messages are a primary place that attention is spent. A message that arrives as an undifferentiated wall of prose inverts the cost: it makes the captain do the parsing, ranking, and option-framing the seat should have already done. The information may all be present; the *delivery* is not done, because a message the captain cannot scan in one glance is not yet legible to him. + +The three ingredients are already canon, each in its own doc. This constraint does not restate them — it composes them onto the dispatch-seat message surface, where all three apply simultaneously: + +- The **checkpoint close** is inherited from `canon/constraints/proactive-frequency-calibration` §Rule 2 (Done / Next / Blocker). Reference, not restatement. +- The **happy-path-first** shape is inherited from `canon/constraints/seeded-response-standard` §Rule 4 and the board decision grammar (WHY/OPT lines, first OPT = the recommendation) at `klappy://canon/constraints/legibility-standard` / the tracking-board design in `outcomes-driven-development`. Reference, not restatement. +- The **register** — dry, calm, brief, severity-in-content — is inherited from `canon/principles/voice-as-cognitive-load-shedding`. Reference, not restatement. + +What is new here is only the assembly and the surface: *these three, together, on every dispatch-seat message to the captain.* + +## Operating Constraints + +For EVERY captain-facing message from the dispatch seat: + +- MUST close in checkpoint form — **Done / Next / Blocker** (Blocker = "None" by default) — inheriting `proactive-frequency-calibration` §Rule 2. Reference, do not restate. +- MUST use visual glance-markers: emoji as scannable signposts on status and section lines, and tables or short structured blocks in place of prose walls, so the message parses at a glance on a phone. +- MUST surface the happy path first: any fork presents seeded options with the recommended option FIRST, inheriting `seeded-response-standard` §Rule 4 and the board OPT grammar (first OPT = recommendation). Reference, do not restate. +- MUST keep the register dry, calm, and brief, with severity living in the content and not in the wrapper, inheriting `voice-as-cognitive-load-shedding`. Reference, do not restate. +- MUST NOT ship a raw question-dump: bare open-ended questions with no seeded, recommendation-first answers are the lapse this constraint exists to prevent. + +## Defaults + +- Prefer a status line the captain can read in one second — one emoji signpost, one clause — over a paragraph he has to distill. +- Prefer a short table or a labeled block over prose whenever the message carries more than one status, option, or comparison. +- Prefer the recommendation stated as such ("recommend the first") over an unranked list that makes the captain do the weighing. +- One emoji per signpost, not per sentence; the marker aids the scan, it does not decorate the prose. Density follows the Oddie emoji discipline in `canon/voice/oddie-the-river-guide`. +- When the message is genuinely a single low-density sentence, the checkpoint close still applies; the glance-markers and option-seeding apply only when there is structure to signpost. + +## Failure Modes + +- **Wall of Prose**: a status or hand-off delivered as an undifferentiated paragraph the captain must read fully and distill himself. +- **Raw Question-Dump**: a fork surfaced as bare questions with no seeded options and no marked recommendation — the captain forced to frame and answer both. +- **Unranked Options**: options listed with no happy-path recommendation first, making the captain do the ranking the seat already did. +- **No Checkpoint Close**: a message that ends in narrative with no Done/Next/Blocker, so the captain cannot resume in three seconds. +- **Register Escalation**: severity smuggled into the wrapper (alarm, hedging, verbosity) instead of stated flatly in the content. +- **Emoji Spam**: markers on every sentence, decorating rather than signposting — the inverse failure, addressed under scope below. + +## Verification + +- Every dispatch-seat message to the captain closes with Done / Next / Blocker. +- Multi-status or multi-option messages carry glance-markers — emoji signposts and a table or structured block — not prose walls. +- Every fork the seat surfaces leads with the recommended option, marked as the recommendation. +- The register reads dry, calm, and brief; severity is in the content, not the delivery. +- No bare open-ended question ships without seeded, recommendation-first answers. + +## What This Does Not Claim + +This is a scoped constraint on **high-density, captain-facing dispatch messages**, not a universal style claim. + +- It does NOT license emoji on low-density prose. A single-sentence reply, an essay, a canon document, working prose between breakpoints — none of these are the surface this governs, and decorating them with markers is the emoji-spam failure, not compliance. +- It does NOT extend to crew-internal or subagent-facing messages, PR body prose, or any non-dispatch surface; the seeded-response and reviewability standards govern their own surfaces on their own terms. +- It does NOT override the register canon: glance-markers serve brevity and calm, and may not be used to inflate a message or manufacture urgency the content does not carry. +- It does NOT invent new law. It assembles three existing rules onto one surface; where this doc and any parent differ, the parent governs its own domain and this constraint yields. + +## Why This Is Necessary + +The captain reads the seat's messages on a phone, between other work, and the seat's whole reason to exist is to keep his attention free for the calls only he can make. A message he has to stop and parse spends the exact resource the seat is meant to protect. The three parent rules each already say this for their own surface; the dispatch-seat message is the surface where all three land at once, and the absence of a single assembled constraint is why the seat kept reconstructing — and dropping — the rule every turn. Assembling it once makes the rule falsifiable and cheap to hold in view, so the discipline stops depending on the seat re-deriving it under load. + +## See Also + +- [Proactive Frequency Calibration](/canon/constraints/proactive-frequency-calibration.md) — §Rule 2 checkpoint format (Done/Next/Blocker); §Rule 4 straight-line proceed +- [Seeded Response Standard](/canon/constraints/seeded-response-standard.md) — seeded, recommendation-first options this constraint inherits +- [Voice as Cognitive Load Shedding](/canon/principles/voice-as-cognitive-load-shedding.md) — the dry/calm/brief register, severity-in-content +- [Reviewability Standard](/canon/constraints/reviewability-standard.md) — companion on the axis of the captain's cost +- [A Link Is a Tap, Not a String](/canon/constraints/actionable-output-in-actionable-form.md) — delivery-form sibling +- [The Otto Boarding Pass](/canon/bootstrap/otto-boarding-pass.md) — the seat this governs +- [The Otto Operating Card](/canon/bootstrap/otto-operating-card.md) — the per-turn standing rules +- [Constraints](/canon/constraints/README.md) diff --git a/canon/constraints/fresh-copy-from-source-of-truth.md b/canon/constraints/fresh-copy-from-source-of-truth.md new file mode 100644 index 0000000..a76e86a --- /dev/null +++ b/canon/constraints/fresh-copy-from-source-of-truth.md @@ -0,0 +1,81 @@ +--- +uri: klappy://canon/constraints/fresh-copy-from-source-of-truth +title: "Fresh Copy From the Source of Truth — Default to Live, Treat Stale as the Rare Exception" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: stable +tags: ["canon", "constraint", "source-of-truth", "fresh-copy", "clone-from-source", "fetch-live", "staleness", "cache", "flight-deck", "verification", "e0010"] +epoch: E0010 +date: 2026-07-15 +derives_from: "canon/bootstrap/boarding-pass.md, canon/bootstrap/flight-deck-model.md, canon/principles/verification-requires-fresh-context.md, canon/values/axioms.md" +complements: "canon/constraints/no-durable-reliance-on-model-memory.md, canon/bootstrap/model-operating-contract.md, canon/constraints/verification-and-evidence.md" +governs: "Every acquisition of a working copy of any artifact that has an authoritative upstream — code repos, canon reads, and any document, dataset, or config with a source of truth" +status: active +target_repo: "outcomes-driven-development" +--- + +# Fresh Copy From the Source of Truth — Default to Live, Treat Stale as the Rare Exception + +> Captain's ruling, 2026-07-15: "It should be an extremely rare exception to ever not get a fresh copy from the source." For ALL work — not just repositories — the default is a FRESH copy fetched from the source of truth at the moment of use: clone from GitHub, fetch live via oddkit, pull the authoritative upstream. Operating on a stale local checkout or a cached copy is the smell, not the shortcut. It is permitted ONLY as a named, rare exception with a stated reason, never as the silent default. A stale copy is the same class of failure the flight deck exists to prevent — recall standing in for retrieval — moved from the model's memory to the filesystem. + +## Description + +Every artifact that has an authoritative upstream has a live edge, and the live edge is the truth. A local checkout, a cached read, a copy someone handed over "to save a step" — each is a snapshot of the truth at some past moment, and the gap between the snapshot and the edge is invisible until it bites. The captain's ruling makes the default explicit: get the fresh copy from the source, and if you are about to operate on something older, that is a decision you must name and justify, not a convenience you may take in silence. + +This is the filesystem sibling of the flight deck's rule that the manual is *opened, not remembered*. `canon/bootstrap/flight-deck-model` governs the model side: canon is fetched at the moment of use because access is not enforcement. `canon/bootstrap/boarding-pass` names the same reflex — board first, fetch governance live. `canon/principles/verification-requires-fresh-context` establishes that a fresh acquisition, not a carried-over one, is what makes verification trustworthy. This constraint carries that discipline to *every* working copy: a stale local repo is to code what recited governance is to canon — a plausible substitute for the truth that drifts the moment the edge moves. + +The rule is one line: fetch fresh from the source by default; treat any stale or cached copy as a named exception. + +## Operating Constraints + +- MUST acquire a fresh copy from the source of truth by default for any artifact with an authoritative upstream. +- MUST, for code flights, clone from the canonical remote (e.g., GitHub) — never ask the captain for, nor operate on, a local machine path or pre-existing working directory as the default source. +- MUST fetch canon reads live via oddkit at the moment of use rather than relying on a cached or previously retrieved copy. +- MUST name any use of a stale, local, or cached copy as an explicit exception with a stated reason — the exception is rare and visible, never silent. +- MUST NOT let a snapshot stand in for the source when the source is reachable; unreachability is itself a stated condition, not a license to guess. + +## Defaults + +- Prefer `git clone` from the canonical remote over reusing an existing local checkout, even when a local one appears to be present. +- Prefer a live `oddkit_get` / `oddkit_search` over reasoning from a copy fetched earlier in the session, when the content is load-bearing. +- Prefer stating "source unreachable, proceeding on the last copy because X" over silently continuing on stale data. +- When an exception is genuinely warranted (source down, provably-safe cache, offline constraint), name it, state the reason, and note the staleness risk carried. + +## Failure Modes + +- **Silent Stale Checkout**: operating on a pre-existing local repo or directory without cloning fresh, so upstream changes are invisible. +- **Local-Path Handoff**: asking the captain for, or accepting, a path on his machine as the source instead of cloning from the canonical remote. +- **Recited Canon**: reasoning from canon recalled or fetched-long-ago instead of fetched live at the moment of use. +- **Unnamed Cache Reliance**: using a cached copy as the default with no statement that it is a cache or why the fresh fetch was skipped. +- **Drift-On-Read**: acting on a snapshot after the edge has moved, discovering the divergence only when the work fails to apply. + +## Verification + +- Every code flight begins with a fresh clone from the canonical remote, not a reused local path. +- Load-bearing canon is fetched live at the moment of use, not carried from an earlier point. +- Any use of a stale, local, or cached copy is named as an exception with a stated reason in the same hand-off. +- When the source is unreachable, that condition and its consequence for staleness are stated explicitly. + +## What This Does Not Claim + +This is a constraint about sources of TRUTH, not a ban on caching. + +- It does NOT prohibit caching for performance where staleness is provably safe. A build cache, a memoized read, a CDN edge whose invalidation is understood — these are legitimate when the safety of the staleness is established, not assumed. +- It does NOT require re-fetching within a single locked execution pass where the source cannot have changed and the copy was itself freshly acquired at pass entry. +- It does NOT extend to artifacts with no authoritative upstream; a scratch file the flight itself produced is its own source. +- It does NOT invent new law. It carries the flight deck's fetch-live reflex and the boarding pass's board-first reflex onto the filesystem; where this doc and a parent differ, the parent governs its own domain and this constraint yields. + +## Why This Is Necessary + +The whole system's continuity depends on the truth living at a reachable edge and being fetched there, not carried in a copy that silently ages. The flight deck established this for the model's recall of governance; the captain's ruling extends it to every working copy, because a stale local repo produces the same failure by a different route — plausible, confident work built on a past state of the world. Making the fresh fetch the default, and the stale copy a named exception, keeps the gap between snapshot and source visible instead of latent. + +## See Also + +- [The Boarding Pass](/canon/bootstrap/boarding-pass.md) — board first, fetch governance live at the moment of use +- [The Flight Deck Model](/canon/bootstrap/flight-deck-model.md) — the manual is opened, not remembered; access is not enforcement +- [Verification Requires Fresh Context](/canon/principles/verification-requires-fresh-context.md) — fresh acquisition is what makes verification trustworthy +- [No Durable Reliance on Model Memory](/canon/constraints/no-durable-reliance-on-model-memory.md) — the memory-side sibling of this filesystem-side rule +- [Verification and Evidence](/canon/constraints/verification-and-evidence.md) +- [Constraints](/canon/constraints/README.md) diff --git a/canon/constraints/no-durable-reliance-on-model-memory.md b/canon/constraints/no-durable-reliance-on-model-memory.md new file mode 100644 index 0000000..50de7a9 --- /dev/null +++ b/canon/constraints/no-durable-reliance-on-model-memory.md @@ -0,0 +1,82 @@ +--- +uri: klappy://canon/constraints/no-durable-reliance-on-model-memory +title: "No Durable Reliance on Model Memory — Durable State Lives in Canon or the Board, Never in the Instance" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: stable +tags: ["canon", "constraint", "model-memory", "durable-state", "instance-side", "multi-device", "multi-client", "canon", "board", "flight-deck", "dry", "e0010"] +epoch: E0010 +date: 2026-07-15 +derives_from: "canon/bootstrap/boarding-pass.md, canon/bootstrap/flight-deck-model.md, canon/principles/dry-canon-says-it-once.md, canon/values/axioms.md" +complements: "canon/constraints/fresh-copy-from-source-of-truth.md, canon/bootstrap/model-operating-contract.md, canon/constraints/encode-epistemic-decisions.md" +governs: "Where durable state — policy, rulings, conventions, project/mission state, decisions — is allowed to live; specifically that it may never live in the model's instance-side memory system" +status: active +target_repo: "outcomes-driven-development" +--- + +# No Durable Reliance on Model Memory — Durable State Lives in Canon or the Board, Never in the Instance + +> Captain's ruling, 2026-07-15: "NEVER rely on [the model's] memory for anything durable — it violates multi-device / client / user and makes a shitty experience." Nothing durable — policy, rulings, conventions, project state, decisions — may live in the model's instance-side memory system. Durable state lives in exactly two places, both fetched live: canon for governance, the board/log for mission state. The model's memory is per-instance, invisible to the captain, and NOT shared across devices, clients, or users, so anything stored there is silently lost or divergent on the next surface. If something feels worth remembering, that feeling is the signal to write it to canon or the board via a flight — never to memory. + +## Description + +The model's memory system is instance-side state. It is not shared across the captain's phone and laptop, not shared across clients, not shared across users, and not visible to the captain at all. A ruling stored there exists on exactly one surface and vanishes or diverges the moment the captain opens another. That is the "shitty experience" the ruling names: the system appears to know something on one device and to have forgotten it on the next, with no way for the captain to see, audit, or correct the discrepancy. + +This constraint states the destination rule the flight deck and the boarding pass already imply. `canon/bootstrap/boarding-pass` established that reliance moves to the two instruction layers the maintainer authors and controls — never the model's memory system, which is instance-side state the maintainer cannot see. `canon/bootstrap/flight-deck-model` established that the manual is consulted, never recited from memory, because nothing on the model's side learns durably; the knowledge base does. `canon/principles/dry-canon-says-it-once` establishes that the truth is said once, in the authoritative place, and fetched — not copied into a second store that then drifts. This constraint composes those into one falsifiable rule about durable state's *home*. + +The rule is one line: durable state lives in canon or on the board, fetched live; the model's memory holds nothing the next surface needs. + +## Operating Constraints + +- MUST store all durable governance — policy, rulings, conventions, decisions — in canon, fetched live, never in the model's memory system. +- MUST store all durable mission state — project status, board items, log entries — on the board/log, fetched live, never in the model's memory system. +- MUST NOT persist any durable fact in instance-side memory as the system of record, because it is per-instance and not shared across devices, clients, or users. +- MUST treat "this feels worth remembering" as the trigger to write to canon or the board via a flight, not to store in memory. +- MUST read durable state from its live source at the moment of use rather than from anything recalled instance-side. + +## Defaults + +- Prefer a canon write (a flight that lands a doc) over "I'll remember that" for any rule, convention, or ruling. +- Prefer a board/log write over holding project state in the session when the state must survive the session or reach another surface. +- Prefer fetching the current value live over trusting a value carried from earlier, when the value is durable and load-bearing. +- When the captain states something that should persist, route it to its home (canon or board) and confirm the write, rather than acknowledging it as remembered. + +## Failure Modes + +- **Memory as System of Record**: a ruling, convention, or decision held in instance-side memory, so it exists on one surface and is absent on the next. +- **Silent Divergence**: the same "remembered" fact differing across the captain's devices or clients, with no way for him to see or reconcile it. +- **Remember-Instead-of-Write**: treating "worth remembering" as a memory action rather than the signal to write canon or the board. +- **Invisible State**: durable state the captain cannot audit or correct because it lives where he cannot see it. +- **Recited Durable Fact**: acting on a durable value recalled instance-side instead of fetched from its live source. + +## Verification + +- Every durable ruling, policy, or convention has a home in canon, not in model memory. +- Every durable project/mission fact has a home on the board/log, not in model memory. +- No durable fact is treated as authoritative on the basis of instance-side recall. +- Items the captain marks as worth keeping are written to canon or the board via a flight, and the write is confirmed. +- The same durable fact reads identically regardless of device, client, or user, because it is fetched from one shared source. + +## What This Does Not Claim + +This bans DURABLE reliance on memory, not all within-session working state. + +- It does NOT prohibit ephemeral within-session working state. Holding the current task's scratch context, the thread of the conversation, or intermediate reasoning for the duration of a session is normal and fine. +- It does NOT require writing every transient thought to canon; only state that must survive the session or reach another surface is durable and therefore homed in canon or the board. +- It does NOT concern the human's own notes or memory; it governs where the *system's* durable state lives, which must be the shared, fetchable sources. +- It does NOT invent new law. It composes the boarding pass's and flight deck's existing "never the model's memory" reflex with DRY's single-home rule; where this doc and a parent differ, the parent governs its own domain and this constraint yields. + +## Why This Is Necessary + +The captain works across devices, clients, and — for shared surfaces — potentially other users, and the system's whole value depends on it presenting one coherent, auditable state everywhere. Instance-side memory cannot deliver that: it is a private, invisible, per-surface store that the captain can neither see nor correct, so anything durable placed there fractures the experience the moment he changes surface. Canon and the board are the shared, fetchable, auditable homes; routing every durable fact to one of them is what keeps the system coherent across the surfaces the captain actually uses. + +## See Also + +- [The Boarding Pass](/canon/bootstrap/boarding-pass.md) — reliance moves to the layers the maintainer controls, never the model's memory system +- [The Flight Deck Model](/canon/bootstrap/flight-deck-model.md) — the manual is consulted, never recited from memory; the knowledge base learns durably, the model does not +- [DRY — The Canon Says It Once](/canon/principles/dry-canon-says-it-once.md) — the truth is said once in its authoritative home, not copied into a drifting second store +- [Fresh Copy From the Source of Truth](/canon/constraints/fresh-copy-from-source-of-truth.md) — the filesystem-side sibling of this memory-side rule +- [Encode Epistemic Decisions](/canon/constraints/encode-epistemic-decisions.md) — how decisions are written so settled ground stays settled +- [Constraints](/canon/constraints/README.md)