Skip to content

canon/definitions: DOLCHEO vocabulary (tier 2) — adds Open as the seventh letter#112

Merged
klappy merged 2 commits into
mainfrom
canon/definitions-dolcheo-vocabulary
Apr 19, 2026
Merged

canon/definitions: DOLCHEO vocabulary (tier 2) — adds Open as the seventh letter#112
klappy merged 2 commits into
mainfrom
canon/definitions-dolcheo-vocabulary

Conversation

@klappy
Copy link
Copy Markdown
Owner

@klappy klappy commented Apr 19, 2026

Adds canon/definitions/dolcheo-vocabulary.md (tier 2) as the canon home for the vocabulary. Supersedes docs/oddkit/proactive/dolche-vocabulary.md by adding Open as the seventh letter: the forward-pointing thread that stays with the current owner.

Summary

Seven letters: Decision, Observation (closed), Learning, Constraint, Handoff, Encode, Open.

Both Os retain the single letter O; section placement and an optional -open tag suffix disambiguate closed Observation from Open item. Open items carry priority bands (P1..Pn, with sub-bands like P1.1). Open vs Handoff distinguished by ownership — Open stays with the current owner; Handoff transfers.

The odd/ledger/2026-04-19-agent-team-pilot.md ledger (open in #109) is the first DOLCHEO-native ledger and is referenced as the working example.

Why canon (not docs)

This vocabulary governs how session capture works across all oddkit-powered projects. It also sets the contract that oddkit_encode must satisfy — the tool must accept all seven prefixes, return per-artifact arrays for batched input, and read this vocabulary at runtime via prompt-over-code (live canon → bundled baseline → fail-loud). That contract lives in canon, not docs.

Backward compatibility

Every DOLCHE journal is a valid DOLCHEO journal with zero Open entries. Trigger phrases (encode DOLCHE, journal this, run the gauntlet) continue to work.

Gauntlet

  • oddkit_preflight — clean
  • oddkit_challenge in canon-tier-2 mode — block_until_addressed: false; prior-art (GTD's Next Actions / Waiting For, kanban, issue trackers), scope boundaries, and retraction conditions addressed inline in a dedicated section
  • Writing Canon 8-point checklist — pass (title, blockquote, metadata, summary, header scan, no buried claims, axiom space, ghost writer)
  • Frontmatter schema (canon/meta/frontmatter-schema) — native YAML types: tier: 2 unquoted, date: 2026-04-19 unquoted, epoch: E0008.3 unquoted simple identifier, strings with punctuation quoted
  • AI voice clichés (canon/constraints/ai-voice-cliches) — one negation-parallelism pattern caught and rewritten; em-dash density in body prose reduced from 46 to 40

Next

Unblocks the oddkit_encode batch-mode + prompt-over-code canary refactor (next PR on klappy/oddkit), which reads this vocabulary at runtime. Canon ships before the code that reads it.


Note

Low Risk
Low risk: changes are documentation/governance additions that don’t alter runtime code, but they define a new contract that future oddkit_encode implementations must follow.

Overview
Defines DOLCHEO as the new tier-2 canon vocabulary for session capture by adding Open as a seventh dimension (unresolved, owner-retained threads) with priority bands and explicit disambiguation from closed Observations while keeping the single-letter O.

Adds new encoding-type docs for E (Encode) and O with facet: open (Open items), and updates the Observation encoding-type doc to cross-reference the new Open/Observation split and section-based classification expectations for oddkit_encode.

Reviewed by Cursor Bugbot for commit 9cb7459. Bugbot is set up for automated code reviews on this repo. Configure here.

klappy added 2 commits April 19, 2026 15:51
Add canon/definitions/dolcheo-vocabulary.md. Supersedes
docs/oddkit/proactive/dolche-vocabulary.md by adding Open as the
seventh letter — the forward-pointing thread that stays with the
current owner.

Seven letters: Decision, Observation (closed), Learning, Constraint,
Handoff, Encode, Open. Both Os remain O; section placement and the
optional '-open' tag suffix disambiguate. Open items carry priority
bands (P1..Pn, with sub-bands like P1.1).

Open vs Handoff distinguished by ownership: Open stays with the
current owner; Handoff transfers to another owner. Worked examples
included.

Canon contract for oddkit_encode follows: the tool must accept all
seven prefixes, return per-artifact arrays for batched input, and
read this vocabulary at runtime via the prompt-over-code pattern
(live canon -> bundled baseline -> fail-loud).

Backward compatible with DOLCHE: every DOLCHE journal is a valid
DOLCHEO journal with zero Open entries.

Gauntlet run:
- oddkit_preflight: clean
- oddkit_challenge (canon-tier-2): block_until_addressed=false;
  prior-art, scope, and retraction conditions addressed inline
- Writing Canon 8-point checklist: pass (title, blockquote,
  metadata, summary, header scan, no buried claims, axiom space,
  ghost writer)
- Frontmatter schema: native YAML types (tier: 2 int, date
  unquoted, simple identifiers unquoted, strings with punctuation
  quoted)
- AI voice clichés: one negation-parallelism pattern caught and
  rewritten; em-dash density in body prose reduced
Complete the per-type governance surface for DOLCHEO. The umbrella
canon doc at canon/definitions/dolcheo-vocabulary.md defined seven
artifact types; the per-type docs under odd/encoding-types/ must
exist for each so BM25 search surfaces all seven independently.

Before this change the inventory was missing:
- encode.md (letter E, meta-level action)
- open.md (letter O, facet=open, forward-pointing)

Both follow the minimal template established by decision.md,
observation.md, learning.md, constraint.md, and handoff.md: frontmatter
tagged 'encoding-type' for discovery, opening blockquote, Type
Identity table, Field Schema, Trigger Words.

open.md registers letter O alongside observation.md with an explicit
Facet row (open vs closed). Classification preference: a paragraph
inside a section headed 'Open items' or 'forward-pointing' classifies
as Open regardless of trigger words; '[O-open]' prefix forces Open;
bare '[O]' outside an Open items section stays closed Observation.
This matches the disambiguation rule in the umbrella doc.

observation.md gets a See Also footer pointing at open.md and the
umbrella doc so the O-letter collision is traversable from either
side in search results.

Gauntlet:
- oddkit_challenge (canon-tier-2) on the pair: CHALLENGED, but
  block_until_addressed=false. The prerequisites it surfaced
  (evidence, prior art, scope, retraction conditions) are all
  addressed in the umbrella doc's frontmatter chain and its
  explicit 'Scope, Prior Art, and Retraction Conditions' section.
  These two files are structural companions, not independent
  principle-extractions.
- Frontmatter schema: native YAML types, universal fields present.
- AI-voice cliches pass: no negation parallelism, no formulaic
  transitions, em-dash density normal.
@klappy
Copy link
Copy Markdown
Owner Author

klappy commented Apr 19, 2026

The second commit on this PR (9cb7459) adds the missing per-type governance docs so all seven DOLCHEO dimensions surface independently in BM25.

What this commit adds

  • odd/encoding-types/encode.md (new) — letter E, meta-level action. Previously referenced by how-to-write-encoding-types.md as an existing type but had no governance doc. Now it does.
  • odd/encoding-types/open.md (new) — letter O with facet: open. Registers alongside observation.md (which remains the fallback). Classification preference documented inline: sections headed Open items or forward-pointing → Open regardless of trigger words; [O-open] prefix → Open; bare [O] outside an Open items section → closed Observation.
  • odd/encoding-types/observation.md (light touch) — added a See Also footer pointing at open.md and the umbrella canon doc so the O-letter collision is traversable from either side in search.

All three mirror the minimal template established by the existing type docs (decision.md, learning.md, constraint.md, handoff.md): frontmatter tagged encoding-type for discovery, opening blockquote, Type Identity table (with Facet row on open.md), Field Schema, Trigger Words.

Gauntlet for this commit

  • oddkit_challenge in canon-tier-2 mode on the pair — block_until_addressed: false. The prerequisites surfaced (evidence, prior art, scope, retraction conditions) are all addressed in the umbrella doc's Scope, Prior Art, and Retraction Conditions section. These files are structural companions, not independent principle-extractions.
  • Frontmatter schema — native YAML types, all required universal fields present.
  • AI-voice clichés — no negation parallelism, no formulaic transitions, em-dash density normal.

This isn't a pivot — it's continuation of the existing per-type governance pattern that DOLCHE established under odd/encoding-types/. DOLCHEO just had two letters missing from that inventory (E was referenced but never authored; O-open is the newly-named seventh type).

@klappy klappy merged commit d030871 into main Apr 19, 2026
1 check passed
klappy added a commit that referenced this pull request Apr 19, 2026
…l O/O-open collision

Two follow-ups after PR #112 landed the DOLCHEO umbrella:

1. docs/oddkit/proactive/dolche-vocabulary.md:
   - status: active -> superseded
   - superseded_by: canon/definitions/dolcheo-vocabulary.md
   - Adds a banner blockquote pointing readers at the DOLCHEO umbrella
     while preserving the doc for historical reference.

2. odd/encoding-types/how-to-write-encoding-types.md:
   - Custom-type conventions now acknowledge the one intentional exception
     to letter-collision: Observation and Open both register letter O and
     disambiguate by facet plus section placement, per the DOLCHEO
     contract. Future custom types should not introduce collisions unless
     they follow the same facet pattern.
klappy added a commit that referenced this pull request Apr 19, 2026
…nal collision (#113)

Two follow-ups after PR #112 landed the DOLCHEO umbrella:

1. docs/oddkit/proactive/dolche-vocabulary.md:
   - status: active -> superseded
   - superseded_by: canon/definitions/dolcheo-vocabulary.md
   - Adds a banner blockquote pointing readers at the DOLCHEO umbrella
     while preserving the doc for historical reference.

2. odd/encoding-types/how-to-write-encoding-types.md:
   - Custom-type conventions now acknowledge the one intentional exception
     to letter-collision: Observation and Open both register letter O and
     disambiguate by facet plus section placement, per the DOLCHEO
     contract. Future custom types should not introduce collisions unless
     they follow the same facet pattern.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant