feat(canon): E0008.4 Phase 1 — Encode governance from truthkit-kb (field schemas, quality criteria, architecture brief, Phase 2 handoff)

odd/encoding-types/constraint.md

@@ -6,23 +6,27 @@ exposure: nav
 tier: 2
 voice: neutral
 stability: semi_stable
-tags: ["odd", "oddkit", "encode", "dolche", "constraint", "encoding-type"]
-epoch: E0008
-date: 2026-04-15
-derives_from: "docs/oddkit/proactive/dolche-vocabulary.md"
+tags: ["odd", "oddkit", "encode", "dolche", "dolcheo", "constraint", "encoding-type", "tsv", "governance", "epoch-8.4"]
+epoch: E0008.4
+date: 2026-04-30
+derives_from: "canon/definitions/dolcheo-vocabulary.md, docs/architecture/encode-architecture-problem-and-gaps.md, canon/principles/prompt-over-code.md"
+complements: "odd/encoding-types/decision.md, odd/encoding-types/observation.md, odd/encoding-types/learning.md, odd/encoding-types/handoff.md, odd/encoding-types/open.md, odd/encoding-types/encode.md, odd/encoding-types/how-to-write-encoding-types.md, odd/encoding-types/serialization-format.md"
 governs: "oddkit_encode parsing and quality scoring for type C"
 status: active
 ---
 
+
 # Encoding Type: Constraint (C)
 
-> What now governs future work. Rules, boundaries, and non-negotiables.
+> What now governs future work. Rules, boundaries, and non-negotiables that emerged from the session. Constraints bind future behavior — they are the artifacts most likely to prevent future mistakes. A constraint without enforcement is a suggestion.
 
 ---
 
 ## Summary — The Binding Layer
 
-Constraints bind future behavior and prevent repeated mistakes. A constraint without enforcement is a suggestion.
+Constraints are the artifacts that prevent future mistakes by binding future behavior. They emerge from decisions, observations, and learnings — but once established, they outlive the context that created them. A constraint from six months ago still governs today's work even if nobody remembers why.
+
+The key discipline: constraints define what cannot be done, not just what should be done. "Use TSV for encode input" is a decision. "The tool description must never hardcode specific keywords" is a constraint — it binds all future work regardless of context.
 
 ---
 
@@ -32,21 +36,76 @@ Constraints bind future behavior and prevent repeated mistakes. A constraint wit
 |---|---|
 | Letter | C |
 | Name | Constraint |
+| Priority | High — constraints bind future behavior and prevent repeated mistakes |
 
 ---
 
 ## Field Schema
 
+When encoding a Constraint, the model outputs a row with the following fields (serialization format governed by `odd/encoding-types/serialization-format.md`):
+
+```
+C	{title}	{body}	{origin}	{scope}
+```
+
 | Field | Recommended | Description |
 |---|---|---|
 | type | yes | Always `C` |
-| title | yes | Short summary of the constraint |
-| body | yes | What is bound, limited, or prohibited |
+| title | yes | Short summary of the constraint (≤12 words) |
+| body | yes | The constraint statement — what is bound, limited, or prohibited |
+| origin | no | What decision, observation, or learning produced this constraint |
+| scope | no | "permanent", "until {condition}", "this project", "this epoch", or empty |
+
+Example:
+
+```
+C	Server must never hardcode encoding type keywords	The encode tool description and server code must never hardcode specific type keywords because the DOLCHE vocabulary is extensible via governance and hardcoding creates drift between code and canon.	D: Governance-defined TSV contract for encode input	permanent
+```
 
 ---
 
 ## Trigger Words (Fallback Classification)
 
+When encode input is unstructured (not TSV), these trigger words classify a paragraph as Constraint:
+
 ```
-must, must not, shall, never, always, required, prohibited, constraint, cannot
+must, must not, shall, shall not, never, always, required, prohibited, constraint, cannot, non-negotiable, boundary, rule, forbidden, mandatory
 ```
+
+---
+
+## Quality Criteria
+
+Each criterion adds 1 to the quality score (max 4):
+
+| Criterion | Check | Gap message if missing |
+|---|---|---|
+| Substance | Body is ≥10 words | "Constraint is too brief — expand what is bound" |
+| Clarity | Body contains a clear prohibition or requirement (must/must not/never/always) | "Make the constraint explicit — what must or must not happen?" |
+| Origin | Origin column is non-empty | "What produced this constraint? Link to the decision or observation" |
+| Scope | Scope column is non-empty | "Is this permanent, temporary, or scoped to a specific context?" |
+
+Quality levels:
+
+| Score | Level | Status |
+|---|---|---|
+| 4 | strong | recorded |
+| 3 | adequate | recorded |
+| 2 | weak | draft |
+| 0–1 | insufficient | draft |
+
+---
+
+## What Makes a Good Constraint Encoding
+
+A strong Constraint answers: what is bound, why it's bound (origin), and how long it's bound (scope). The most common gap is missing scope — constraints without expiration or context become invisible governance debt. "Never do X" is stronger than "don't do X" but "never do X because Y, permanent" is strongest.
+
+The second most common gap is constraints that read like preferences. "We should use TypeScript" is a preference. "All server code must be TypeScript because the CI pipeline only compiles TS" is a constraint — it names the enforcement mechanism.
+
+---
+
+## See Also
+
+- [DOLCHE Vocabulary](klappy://docs/oddkit/proactive/dolche-vocabulary) — the six-dimension framework this type belongs to
+- [Encoding Type: Decision](klappy://odd/encoding-types/decision) — decisions often produce constraints
+- [Prompt Over Code](klappy://canon/principles/prompt-over-code) — why this governance doc exists instead of server code

odd/encoding-types/decision.md

@@ -6,23 +6,25 @@ exposure: nav
 tier: 2
 voice: neutral
 stability: semi_stable
-tags: ["odd", "oddkit", "encode", "dolche", "decision", "encoding-type"]
-epoch: E0008
-date: 2026-04-15
-derives_from: "docs/oddkit/proactive/dolche-vocabulary.md"
+tags: ["odd", "oddkit", "encode", "dolche", "dolcheo", "decision", "encoding-type", "tsv", "governance", "epoch-8.4"]
+epoch: E0008.4
+date: 2026-04-30
+derives_from: "canon/definitions/dolcheo-vocabulary.md, docs/architecture/encode-architecture-problem-and-gaps.md, canon/principles/prompt-over-code.md"
+complements: "odd/encoding-types/observation.md, odd/encoding-types/learning.md, odd/encoding-types/constraint.md, odd/encoding-types/handoff.md, odd/encoding-types/open.md, odd/encoding-types/encode.md, odd/encoding-types/how-to-write-encoding-types.md, odd/encoding-types/serialization-format.md"
 governs: "oddkit_encode parsing and quality scoring for type D"
 status: active
 ---
 
+
 # Encoding Type: Decision (D)
 
-> What was chosen. Explicit commitments with rationale that close options and create direction.
+> What was chosen. Explicit commitments with rationale. Decisions close options and create direction. They are the highest-stakes artifacts because they constrain all subsequent work. A decision without rationale is a debt. A decision without a constraint test is untested.
 
 ---
 
 ## Summary — The Highest-Stakes Artifact Type
 
-Decisions close options and create direction. They constrain all subsequent work, making them the most important artifacts to capture.
+Decisions are the encoding type most likely to affect future work. A missed observation can be recovered from the transcript. A missed decision may not surface again. Decisions create direction, close options, and bind future behavior. They deserve the most rigorous quality criteria of any encoding type.
 
 ---
 
@@ -32,21 +34,82 @@ Decisions close options and create direction. They constrain all subsequent work
 |---|---|
 | Letter | D |
 | Name | Decision |
+| Priority | Highest — decisions constrain all subsequent work |
 
 ---
 
 ## Field Schema
 
+When encoding a Decision, the model outputs a row with the following fields (serialization format governed by `odd/encoding-types/serialization-format.md`):
+
+```
+D	{title}	{body}	{rationale}	{alternatives}	{reversibility}
+```
+
 | Field | Recommended | Description |
 |---|---|---|
 | type | yes | Always `D` |
-| title | yes | Short summary of the decision |
-| body | yes | What was chosen and why |
+| title | yes | Short summary of the decision (≤12 words) |
+| body | yes | The decision statement — what was chosen and why it matters |
+| rationale | yes | Why this was chosen. Starts with the reasoning, not "because" |
+| alternatives | no | What else was considered. Empty string if none discussed |
+| reversibility | no | "reversible", "permanent", "reversible until {condition}", or empty |
+
+Example:
+
+```
+D	TSV as encode input format	Governance defines strict TSV output contract for encode input. Model outputs typed rows, server parses mechanically.	TSV is pure string splitting — no regex, no NLP. Model is already restructuring content. Adding column structure is trivial.	Free-form prose with regex classification; JSON structured output; model-labeled paragraphs	reversible
+```
 
 ---
 
 ## Trigger Words (Fallback Classification)
 
+When encode input is unstructured (not TSV), these trigger words classify a paragraph as Decision:
+
 ```
-decided, decision, chose, choosing, selected, committed to, going with
+decided, decision, chose, choosing, selected, committed to, going with, will use, adopted, settled on, picked, determined, resolved to
 ```
+
+These words are used by the server to build dynamic regex for fallback classification only. On the primary TSV path, the type letter `D` is the classifier.
+
+---
+
+## Quality Criteria
+
+Each criterion adds 1 to the quality score (max 5):
+
+| Criterion | Check | Gap message if missing |
+|---|---|---|
+| Substance | Body is ≥10 words | "Decision body is too brief — expand what was chosen" |
+| Rationale | Rationale column is non-empty and ≥3 words | "No rationale — add why this was chosen" |
+| Alternatives | Alternatives column is non-empty | "No alternatives considered — what else was an option?" |
+| Reversibility | Reversibility column is non-empty | "Note whether this is reversible or permanent" |
+| Constraints | Body or rationale mentions what this decision constrains or binds | "What constraints does this decision create?" |
+
+Quality levels:
+
+| Score | Level | Status |
+|---|---|---|
+| 5 | strong | recorded |
+| 3–4 | adequate | recorded |
+| 2 | weak | draft |
+| 0–1 | insufficient | draft |
+
+---
+
+## What Makes a Good Decision Encoding
+
+A strong Decision encoding answers five questions: What was chosen? Why? What else was considered? Is it reversible? What does it constrain? The model doesn't need to answer all five — but quality scoring rewards completeness.
+
+The most common gap is missing rationale. Models often encode the what without the why. The quality feedback loop teaches the model to include rationale in future calls.
+
+The second most common gap is missing alternatives. A decision without alternatives is an assertion, not a choice. Even "no alternatives were discussed" is better than silence — it's honest about the decision's context.
+
+---
+
+## See Also
+
+- [DOLCHE Vocabulary](klappy://docs/oddkit/proactive/dolche-vocabulary) — the six-dimension framework this type belongs to
+- [Prompt Over Code](klappy://canon/principles/prompt-over-code) — why this governance doc exists instead of server code
+- [Encode Does Not Persist](klappy://docs/oddkit/proactive/encode-does-not-persist) — the caller must save encoded artifacts

odd/encoding-types/handoff.md

@@ -6,23 +6,27 @@ exposure: nav
 tier: 2
 voice: neutral
 stability: semi_stable
-tags: ["odd", "oddkit", "encode", "dolche", "handoff", "encoding-type"]
-epoch: E0008
-date: 2026-04-15
-derives_from: "docs/oddkit/proactive/dolche-vocabulary.md"
+tags: ["odd", "oddkit", "encode", "dolche", "dolcheo", "handoff", "encoding-type", "tsv", "governance", "epoch-8.4"]
+epoch: E0008.4
+date: 2026-04-30
+derives_from: "canon/definitions/dolcheo-vocabulary.md, docs/architecture/encode-architecture-problem-and-gaps.md, canon/principles/prompt-over-code.md"
+complements: "odd/encoding-types/decision.md, odd/encoding-types/observation.md, odd/encoding-types/learning.md, odd/encoding-types/constraint.md, odd/encoding-types/open.md, odd/encoding-types/encode.md, odd/encoding-types/how-to-write-encoding-types.md, odd/encoding-types/serialization-format.md"
 governs: "oddkit_encode parsing and quality scoring for type H"
 status: active
 ---
 
+
 # Encoding Type: Handoff (H)
 
-> What comes next and what context the next session needs.
+> What comes next and what context the next session needs. Explicit transfer of state across conversation boundaries. Handoffs are the artifacts most likely to be lost because they describe what hasn't happened yet. A session without handoffs forces the next session to reconstruct context from scratch.
 
 ---
 
 ## Summary — The Continuity Layer
 
-Handoffs transfer state across session boundaries. A session without handoffs forces the next session to reconstruct context from scratch.
+Handoffs are how work survives across session boundaries. Every conversation ends. The question is whether the next one starts from zero or starts from where this one left off. Handoffs answer that question by explicitly naming: what's next, what's blocked, what context is needed, and who owns it.
+
+The key discipline: handoffs describe the future, not the past. "We decided to use TSV" is a decision. "Next session: write the remaining four encoding-type governance docs" is a handoff — it transfers intent across a boundary.
 
 ---
 
@@ -32,21 +36,76 @@ Handoffs transfer state across session boundaries. A session without handoffs fo
 |---|---|
 | Letter | H |
 | Name | Handoff |
+| Priority | High — handoffs are the most frequently lost artifact type |
 
 ---
 
 ## Field Schema
 
+When encoding a Handoff, the model outputs a row with the following fields (serialization format governed by `odd/encoding-types/serialization-format.md`):
+
+```
+H	{title}	{body}	{blocked_by}	{owner}
+```
+
 | Field | Recommended | Description |
 |---|---|---|
 | type | yes | Always `H` |
-| title | yes | Short summary of what comes next |
-| body | yes | What needs to happen and what context is needed |
+| title | yes | Short summary of what comes next (≤12 words) |
+| body | yes | What needs to happen and what context is needed to do it |
+| blocked_by | no | What must happen before this can proceed. Empty if unblocked |
+| owner | no | Who owns this next action — a person, role, or "next session" |
+
+Example:
+
+```
+H	Write O, L, C, H encoding-type governance docs	Create the remaining four default encoding-type governance docs following the Decision template. Each needs type identity, TSV schema, trigger words, and quality criteria.		next session
+```
 
 ---
 
 ## Trigger Words (Fallback Classification)
 
+When encode input is unstructured (not TSV), these trigger words classify a paragraph as Handoff:
+
 ```
-next session, next step, todo, follow up, blocked by, waiting on, continue, remaining, handoff
+next session, next step, todo, to do, follow up, blocked by, waiting on, needs to happen, pick up, continue, remaining, outstanding, handoff, hand off, carry forward, defer
 ```
+
+---
+
+## Quality Criteria
+
+Each criterion adds 1 to the quality score (max 4):
+
+| Criterion | Check | Gap message if missing |
+|---|---|---|
+| Substance | Body is ≥10 words | "Handoff is too brief — what context does the next session need?" |
+| Actionability | Body describes a concrete next action, not just a topic | "Make it actionable — what specifically needs to happen next?" |
+| Blocker clarity | Blocked_by column is non-empty OR body explicitly states unblocked | "Is this blocked by anything? State blockers or confirm unblocked" |
+| Ownership | Owner column is non-empty | "Who owns this? A person, role, or 'next session'" |
+
+Quality levels:
+
+| Score | Level | Status |
+|---|---|---|
+| 4 | strong | recorded |
+| 3 | adequate | recorded |
+| 2 | weak | draft |
+| 0–1 | insufficient | draft |
+
+---
+
+## What Makes a Good Handoff Encoding
+
+A strong Handoff answers: what needs to happen, what context is needed to do it, what's blocking it, and who owns it. The most common gap is handoffs that name a topic without naming an action — "encoding architecture" is a topic, "implement TSV parsing in the encode handler" is an action.
+
+The second most common gap is missing blockers. A handoff without blocker information forces the next session to rediscover dependencies. Even "unblocked" is valuable — it confirms the work can start immediately.
+
+---
+
+## See Also
+
+- [DOLCHE Vocabulary](klappy://docs/oddkit/proactive/dolche-vocabulary) — the six-dimension framework this type belongs to
+- [Proactive Session Close](klappy://docs/oddkit/proactive/proactive-session-close) — handoffs are central to session closing
+- [Prompt Over Code](klappy://canon/principles/prompt-over-code) — why this governance doc exists instead of server code