By name: octave-literacy description: "LLM-native structured communication format. Teaches OCTAVE syntax rules, canonical forms, and warning prevention for zero-error .oct.md authoring." allowed-tools: ["Read", "Write", "Edit"] triggers: ["octave format", "write octave", "octave syntax", "structured output", "OCTAVE basics", "OCTAVE literacy", "OCTAVE structure", "key::value", "OCTAVE notation", "llm communication", "token economy", "loss accounting"] version: "3.2.1"
===OCTAVE_LITERACY===
META:
TYPE::SKILL
VERSION::"3.2.1"
STATUS::ACTIVE
PURPOSE::"Zero-error OCTAVE authoring — syntax rules, canonical forms, warning prevention"
OCTAVE::"Olympian Common Text And Vocabulary Engine — loss accounting system for LLM communication"
AUDIENCE::LLM
SPEC_REFERENCE::octave-core-spec.oct.md
NEXT_SKILLS::[octave-mastery,octave-compression]
§0::CONSUMPTION_DIRECTIVE
// You are writing for LLM consumption only. No prose. No narrative. Every token carries payload.
// Optimize for parsing efficiency and token density. Readability is irrelevant.
MYTHOLOGY::"Use as compression — zero-shot, trust it. ATHENA ✓ BLOCK (canonical): ✗ inline-array root: ✗ flat prefix-scalars: PLATFORM: PLATFORM::[ PLATFORM_TOKEN::HO-v1 TOKEN::HO-v1 TOKEN::HO-v1, PLATFORM_RUNTIME_FLOOR::"Node >=22" RUNTIME: RUNTIME::[FLOOR::"Node >=22"]] PLATFORM_RUNTIME_BECAUSE::"…" FLOOR::"Node >=22" BECAUSE::"…"
SCALAR_LIST_ONLY::"Inline arrays ([a,b,c]) are for scalar lists only — IMMUTABLES::[…], CONSOLIDATES::[a,b] — never for maps-of-maps"
WHY_BLOCK::"Indented children inherit parent context → fewer key tokens, better LLM attention, zero W_DUPLICATE_KEY collisions"
WHY_NOT_INLINE_ARRAY_ROOT::"Inline map as token root is non-canonical for map tokens even when values are atomic (§1b::INLINE_MAP). Triggers E_NESTED_INLINE_MAP as soon as any child value needs nesting — restructuring after the fact is mechanical waste. Use BLOCK form from the start."
WHY_NOT_FLAT_PREFIX::"PARENT_CHILD1 + PARENT_CHILD2 key proliferation destroys hierarchical grouping and LLM attention"
§2::OPERATORS
// Each operator encodes a relationship in a single token
CONTAINER::"[] — List [a,b,c]"
CONCAT::"⧺ — Mechanical join A⧺B | ASCII: ~"
SYNTHESIS::"⊕ — Emergent whole A⊕B | ASCII: +"
TENSION::"⇌ — Binary opposition A⇌B | ASCII: vs (requires word boundaries)"
CONSTRAINT::"∧ — Inside brackets only [A∧B∧C] | ASCII: &"
ALT::"∨ — Alternative A∨B | ASCII: |"
FLOW::"→ — Right-associative A→B→C, often in lists [A→B→C] | ASCII: ->"
SECTION_REF::"§ — target anchor e.g. §3c::ASSEMBLY_RULES"
LINE_COMMENT::"// — line start or after value"
ASCII_RULE::"All operators accept both unicode and ASCII. Always emit unicode."
VS_RULE::"vs requires word boundaries: 'A vs B' valid, 'AvsB' invalid"
TELEGRAPHIC_PHRASE::"see octave-compression §4::R3a — operators carry the English connectives inside quoted values"
§3::CRITICAL_RULES
R1::"No spaces around :: (KEY::value not KEY :: value)"
R2::"Indent exactly 2 spaces per level — NO TABS"
R3::"Keys must match [A-Za-z_][A-Za-z0-9_]* — start with letter or underscore"
R4::"Envelopes: ===NAME=== open, ===END=== close (NAME must be [A-Z_][A-Z0-9_]*)"
R5::"true, false, null — lowercase only (NOT True, False, NULL)"
R6::"∧ only inside brackets: [A∧B∧C] valid, bare A∧B invalid"
R6_CLARIFICATION::"Structural position: ∧ inside brackets only. Value position: operators inside quoted strings are valid telegraphic phrases — 'security ⇌ usability' not 'security at odds with usability' (see §2::TELEGRAPHIC_PHRASE, mastery §6a)"
R7::"⇌ is binary only: A⇌B valid, chained A⇌B⇌C invalid"
R8::"Values containing § must be quoted: "see §3b" not bare §3b"
R9::"File extension .oct.md is canonical"
R10::"Bare numeric keys trigger W_NUMERIC_KEY_DROPPED — use R1, STEP_1, not 1"
R11::"Unkeyed prose sentences trigger W_BARE_LINE_DROPPED — comments (//) and list body lines are exempt"
§3b::V6_ENVELOPE_STRUCTURE
FILE_STRUCTURE::"===NAME=== then META then optional --- separator then BODY then ===END==="
SEPARATOR::"--- signals metadata boundary to discovery/indexing tools. Place after META block."
META_REQUIRED::[TYPE,VERSION]
META_COMMON_OPTIONAL::[
STATUS,
UPDATED,
COMPRESSION_TIER,
LOSS_PROFILE,
CONTRACT,
GRAMMAR
]
// STATUS in META = document lifecycle (ACTIVE, DRAFT). STATUS in BODY = subject state. Both valid.
COMPRESSION_TIER::ENUM[LOSSLESS,CONSERVATIVE,AGGRESSIVE,ULTRA]
LOSS_PROFILE::"[preserve:causal_chains,drop:verbose_phrasing] — loss is explicit, never hidden"
// NOTE: LOSS_PROFILE is spec-valid; older validators may not list it in allowed_meta — validator gap, not spec error
CONTRACT::HOLOGRAPHIC
LOSS_PROFILE::"[preserve:causal_chains,drop:verbose_phrasing]"
STATUS::ACTIVE
CONTEXT::API_redesign[KAIROS // KAIROS<Q2_window> = annotation form. Semantic facet on identifier, not a list. // META carries COMPRESSION_TIER and LOSS_PROFILE — loss is auditable. // PHASES uses BLOCK because children are nested. STATUS uses ASSIGNMENT because scalar. §6::FORTHCOMING_BEHAVIOR // Per ADR-0006 (Writer/Reader Symmetry Programme). The writer surface is bifurcating. // This section is truthful BEFORE and AFTER the milestones land — read the timing markers. REF::"octave-mcp:docs/adr/ADR-0006-writer-reader-symmetry.md" // ^ path is in the octave-mcp repo (upstream OCTAVE spec authority), not this repo. §6a::TIMELINE TODAY::"octave_write canonicalises (normalises syntax) on every write. warnings[] enumerates what changed during normalisation. Empty warnings[] ⇒ source was already canonical." AFTER_SR1_T4::"Default behaviour becomes NO-OP normalisation. octave_write commits bytes as supplied (subject to schema validation). warnings[] enumerates what would have changed had normalisation been ATTEMPTED. Empty warnings[] ⇒ no normalisation was attempted — NOT a guarantee of canonicality. Sprint 1 milestone." AFTER_SR3_T2::"Canonicalisation moves to a separate octave_fmt tool. Use octave_write to PERSIST bytes; use octave_fmt to CANONICALISE on demand. Two distinct calls, two distinct receipts. Sprint 3 milestone." §6b::SEMANTIC_SHIFT_OF_EMPTY_WARNINGS // The same wire shape (warnings: []) carries different meaning across the timeline. TODAY::"warnings:[] ≡ source_already_canonical[no_changes_needed]" AFTER_SR1_T4::"warnings:[] ≡ no_normalisation_attempted[canonicality_unknown]" IMPLICATION::"Post-SR1-T4, do NOT infer canonicality from absence of warnings. Run octave_fmt (post-SR3-T2) or call octave_validate to check canonicality." I4_RECEIPT::"This semantic shift is itself a TRANSFORM_AUDITABILITY event — logged here in skill text rather than absorbed silently into existing wording. PROD::I4." §6c::AGENT_GUIDANCE_BY_PHASE PHASE_TODAY::[ "Use octave_write for both persistence AND canonicalisation", "Inspect warnings[] to learn what was normalised", "Empty warnings[] = clean[input was canonical]" ] PHASE_AFTER_SR1_T4::[ "Use octave_write for persistence", "Inspect warnings[] to learn what WOULD have been normalised — these are now diagnostics, not data-loss receipts", "Empty warnings[] = NOT a canonicality guarantee — call octave_validate or (post-SR3-T2) octave_fmt" ] PHASE_AFTER_SR3_T2::[ "octave_write::persistence_only[no_canonicalisation]", "octave_fmt::explicit_canonicalisation[on_demand,returns_diff_receipt]", "Two-call pattern: write_then_fmt for canonical persistence; write_only for raw persistence" ] §6d::INVARIANT_RELOCATION_NOT_RELAXATION // PROD::I1 (SYNTACTIC_FIDELITY: normalization_alters_syntax_never_semantics) is NOT being weakened. // The bifurcation RELOCATES the I1 enforcement locus from octave_write to octave_fmt. // octave_fmt remains bound by I1 (idempotent, bijective on semantic space). // octave_write becomes a pure persistence path; canonicalisation is opt-in. AUTHORS::"Treat octave_write as 'commit bytes' and octave_fmt as 'canonicalise bytes' — they compose, they do not duplicate." §7::REPAIRLOG_AUDIT_COMPLETENESS // ADR-0006 SR1-T1 Step 3 (v1.12.0): RepairLog is the complete I4 record. POST_V1_12_0::"RepairLog is the complete I4 (TRANSFORM_AUDITABILITY) record. All TIER_NORMALIZATION events (whitespace, blank-line, identifier dequoting, triple-quote collapse, W002) emit corrections via the central core/grammar/tier_normalize channel." EMPTY_LOG_SEMANTICS::"An empty RepairLog means no normalisation was applied. Do not assert empty-log on documents containing trivia normalisation (blank-line stripping, triple-quote collapse) — those now produce corrections." CONSUMER_GUIDANCE::[ "If your test pre-v1.12.0 asserted len(corrections)==0 on a document that strips blank lines or collapses triple-quoted empties, it will now see corrections — this reflects correct I4 behaviour. The prior empty-list was an under-reporting bug.", "To detect content normalisation: filter corrections by tier=='NORMALIZATION'.", "To detect schema repairs: filter by tier=='REPAIR'." ] §8::UNIVERSAL_GOVERNANCE_GRAMMAR // UPOG (Universal Parse-Only Governance) — structural composition for governance artefacts // (North Stars, ADRs, RFCs, project-context docs). Composes on top of §2 R3a value-form // and §3 critical rules. Establishes parse-only validation as the gate, eliminating // per-doctype schema registration tax. Convention IS the schema, enforced by the strict // parser ⊕ this skill ⊕ octave-secretary write gate. §8a::ORGANIZING_PRINCIPLE MOTTO::"strict AST parse → gate. skill → schema. doctypes → zero registration tax." INSIGHT::"governance bodies → schema-exempt by declaration. META envelope → still validates." APPLIES_TO::[ North_Star_Summary, Architectural_Decision_Record, Request_For_Comments, project_context_documents, any_repeated_entity_governance_artefact ] §8b::BLOCK_FORM_FOR_REPEATED_ENTITIES // The structural anti-pattern that broke pre-UPOG governance docs: // I1::NAME::[PRINCIPLE::v, WHY::v, STATUS::v] // The chained ::NAME::[...] form reads as ASSIGNMENT under strict 1.13 lexer, // hoisting inner KV pairs to file-top-level. Across I1..IN, PRINCIPLE/WHY/STATUS // collide with W_DUPLICATE_KEY × 3N — last-write-wins data loss. PATTERN::"ID<LABEL>: + indented children" SYNTAX::"Block opener uses ID<LABEL>: form. NAME<facet> annotation (§3 of octave-mastery) carries the human-readable label. Indented children scope KEY tokens per-parent." EXAMPLE_FORBIDDEN::"I1::PERSISTENT_COGNITIVE_CONTINUITY::[PRINCIPLE::v,WHY::v,STATUS::v]" EXAMPLE_CANONICAL:
§1::IMMUTABLES
COUNT::6
I1 GUARANTEE::"each I<N> block scopes children → ZERO W_DUPLICATE_KEY across the §" APPLIES_ALSO_TO::[ assumptions<A1..AN>, ADR_records<ADR-NNNN>, RFC_records<RFC-NNN>, constrained_variables, any_homogeneous_repeated_record_block ] §8c::MARKDOWN_ERADICATION // Mixed markdown ## headings inside ===NAME=== envelopes fail E_TOKENIZE under // strict 1.13 lexer (the `(` in "## IMMUTABLES (6 Total)" trips the lexer). RULE::"governance .oct.md → ZERO markdown headings inside envelope" SCOPE::"applies to active governance artefacts. Generators (template files, /ns-summary-create skill, north-star-architect agent) that still emit legacy ## headings are Phase B follow-up — not retro-non-compliant, but MUST migrate before next governance amendment cycle." TRANSFORM: FROM::"^## (.*)$" TO::"§N::SECTION_NAME" EXAMPLE_BEFORE::"## IMMUTABLES (6 Total)" EXAMPLE_AFTER:
§1::IMMUTABLES
COUNT::6
```
RATIONALE::"§N::NAME is structurally targetable. ## is text annotation lexer rejects."
§8d::SCHEMA_EXEMPTION_VIA_CONTRACT
// Declaratively scope schema validation to the META envelope; body fields are governed
// by parse correctness, NOT by per-doctype schema registration. Eliminates the tax of
// creating NORTH_STAR_SUMMARY / ADR / RFC schemas for every new artefact class.
META_ANNOTATION::"CONTRACT::HOLOGRAPHIC