SKILL.md
===OCTAVELITERACY=== 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<exclusively> SPECREFERENCE::octave-core-spec.oct.md NEXT_SKILLS::[octave-mastery,octave-compression]
§0::CONSUMPTIONDIRECTIVE // 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<strategicwisdom> = 1 token replacing 15." MYTHOLOGYANTIPATTERN::"ZEUS::executivedecision — use EXECUTIVE::decision when literal is equally clear" // Full vocabulary: octave-mastery §1 §1::CORESYNTAX ASSIGNMENT::"KEY::value — double colon, no spaces around ::" BLOCK::"KEY: + newline + 2-space indent — use when value has nested children" CHOICE::"scalar value → ASSIGNMENT. nested children → BLOCK. Never mix." LIST::"[a,b,c] — square brackets, no YAML bullets ever" STRING::"bareword if no spaces/special chars, else double-quoted" NUMBER::"42 or 3.14 or -1e10 — no quotes" BOOLEAN::"true or false — lowercase only" NULLVALUE::"null — lowercase only" COMMENT::"// — line start or after value" §1b::BRACKETFORMS CONTAINER::"[a,b,c] — bare brackets = list" ANNOTATION::"NAME<qualifier> — semantic facet on identity (ATHENA<strategicwisdom>, LLM<exclusively>)" ANNOTATIONDISCIPLINE::"Annotations are SHORT qualifiers (1-3 words, ≤32 chars, identifier-only). Multi-word reasoning belongs in a sibling RATIONALE value as a quoted telegraphic phrase (see octave-mastery §6a)." ANNOTATIONWRONG::"I6<migrationonmovingtargetisantipatternforzerowarnings>" ANNOTATIONRIGHT::"I6<productiongradequality> + RATIONALE::\"Migration on moving target is anti-pattern for strict typing during data model changes.\"" CONSTRUCTOR::"NAME[args] — structured arguments on identifier (REGEX[pattern], ENUM[a,b], JITGRAMMARCOMPILATION[META→GBNF])" // These are SEPARATE forms. <> qualifies what something IS. [] parameterizes what something DOES. // ATHENA<strategicwisdom> = annotation (identity facet). ENUM[a,b,c] = constructor (validation args). // Lenient parser canonicalizes []→<> ONLY for annotation-context uses. Genuine constructors keep []. // When in doubt: identity/archetype qualifier → <>. Parameterized operation/schema → []. INLINEMAP::"[key::val, key2::val2] — dense key-value pairs, values must be atoms, no nesting" §1c::LITERALZONES // Fenced code blocks pass through with ZERO processing SYNTAX::"KEY then newline then fence of 3+ backticks" RULES::[ zeroprocessingbetweenfences, tabsallowed, NFCbypass, infotagpreserved ] USECASES::[ embeddedcode, teachingexamples, verbatimcontent, OCTAVEaboutOCTAVE ] FENCESCALING::"use N+1 backticks to wrap content containing N-backtick fences" §1d::BLOCKCANONICALFORMS // Three shapes agents reach for when nesting — only one is correct RULE::"Multi-field token (any key whose value is a map) → BLOCK form. Never inline-array root. Never flat prefix-scalars." THREESHAPES: `` ✓ BLOCK (canonical): ✗ inline-array root: ✗ flat prefix-scalars: PLATFORM: PLATFORM::[ PLATFORMTOKEN::HO-v1 TOKEN::HO-v1 TOKEN::HO-v1, PLATFORMRUNTIMEFLOOR::"Node >=22" RUNTIME: RUNTIME::[FLOOR::"Node >=22"]] PLATFORMRUNTIMEBECAUSE::"…" FLOOR::"Node >=22" BECAUSE::"…" ` SCALARLISTONLY::"Inline arrays ([a,b,c]) are for scalar lists only — IMMUTABLES::[…], CONSOLIDATES::[a,b] — never for maps-of-maps" WHYBLOCK::"Indented children inherit parent context → fewer key tokens, better LLM attention, zero WDUPLICATEKEY collisions" WHYNOTINLINEARRAYROOT::"Inline map as token root is non-canonical for map tokens even when values are atomic (§1b::INLINEMAP). Triggers ENESTEDINLINEMAP as soon as any child value needs nesting — restructuring after the fact is mechanical waste. Use BLOCK form from the start." WHYNOTFLATPREFIX::"PARENTCHILD1 + PARENTCHILD2 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: ->" SECTIONREF::"§ — target anchor e.g. §3c::ASSEMBLYRULES" LINECOMMENT::"// — line start or after value" ASCIIRULE::"All operators accept both unicode and ASCII. Always emit unicode." VSRULE::"vs requires word boundaries: 'A vs B' valid, 'AvsB' invalid" TELEGRAPHICPHRASE::"see octave-compression §4::R3a — operators carry the English connectives inside quoted values" §3::CRITICALRULES 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" R6CLARIFICATION::"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::TELEGRAPHICPHRASE, 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 WNUMERICKEYDROPPED — use R1, STEP1, not 1" R11::"Unkeyed prose sentences trigger WBARELINEDROPPED — comments (//) and list body lines are exempt" §3b::V6ENVELOPESTRUCTURE FILESTRUCTURE::"===NAME=== then META then optional --- separator then BODY then ===END===" SEPARATOR::"--- signals metadata boundary to discovery/indexing tools. Place after META block." METAREQUIRED::[TYPE,VERSION] METACOMMONOPTIONAL::[ STATUS, UPDATED, COMPRESSIONTIER, LOSSPROFILE, CONTRACT, GRAMMAR ] // STATUS in META = document lifecycle (ACTIVE, DRAFT). STATUS in BODY = subject state. Both valid. COMPRESSIONTIER::ENUM[LOSSLESS,CONSERVATIVE,AGGRESSIVE,ULTRA] LOSSPROFILE::"[preserve:causalchains,drop:verbosephrasing] — loss is explicit, never hidden" // NOTE: LOSSPROFILE is spec-valid; older validators may not list it in allowedmeta — validator gap, not spec error CONTRACT::HOLOGRAPHIC<validationlawindocument> GRAMMAR::GBNFCOMPILER<generateconstrainedoutput> §3c::ASSEMBLYRULES RULE::"When concatenating profiles, omit intermediate ===END=== — only final one terminates" USECASES::[ agentcontextinjection, specificationlayering, multipartdocuments ] §3d::SECTIONPATHREFERENCES SYNTAX::"§N::NAME — section reference. §3b::V6ENVELOPESTRUCTURE is a valid cross-reference." QUOTING::"Quote § when used as content value: VALUE::\"see §3b\" not VALUE::§3b" NESTING::"§3b inside §3 — subsection. Prefix digit tracks depth." §4::WARNINGPREVENTION // octavewrite returns warnings[] — each warning is silent data loss WBARELINEDROPPED::"Cause: line has no key:: prefix. Fix: add a key or use // comment." WNUMERICKEYDROPPED::"Cause: bare integer key (1::thing). Fix: use R1::thing or STEP1::thing." WCHECK::"After every octavewrite call, inspect warnings[]. Today: Empty = clean. Non-empty = data lost. AFTER ADR-0006 SR1-T4: see §6 — empty no longer implies clean." WCHANGESMODENESTEDMAP::"Cause: passing a nested dict as a changes-mode value to octavewrite. Fix: use content= with formatstyle=preserve for any block-nested content. Changes-mode serializes nested dicts as inline maps → ENESTEDINLINEMAP. Exception: scalar-array appends (e.g. into AMENDS::[…]) remain changes-mode-friendly." // WCHANGESMODENESTEDMAP: per octave-mcp changes-mode footgun — revisit post-ADR-0006-SR3-T2 when changes-mode gains native nesting support // Semantic of warnings[] is changing. See §6::FORTHCOMINGBEHAVIOR for timing markers. §5::WORKEDEXAMPLE // Shows: envelope, META with optional fields, separator, operators, annotation, loss accounting EXAMPLE: `` ===DECISION=== META: TYPE::DECISION VERSION::"1.0.0" COMPRESSIONTIER::CONSERVATIVE LOSSPROFILE::"[preserve:causalchains,drop:verbosephrasing]"
STATUS::ACTIVE CONTEXT::APIredesign[KAIROS<Q2window>] DECISION::microserviceextraction[auth⊕payments→independentservices] PHASES: PLAN::[Research→Design] BUILD::[Code⊕Test] METRICS: LATENCY::"<200ms p99" AVAILABILITY::"99.95%" ===END=== `` // KAIROS<Q2window> = annotation form. Semantic facet on identifier, not a list. // META carries COMPRESSIONTIER and LOSSPROFILE — loss is auditable. // PHASES uses BLOCK because children are nested. STATUS uses ASSIGNMENT because scalar. §6::FORTHCOMINGBEHAVIOR // 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::"octavewrite canonicalises (normalises syntax) on every write. warnings[] enumerates what changed during normalisation. Empty warnings[] ⇒ source was already canonical." AFTERSR1T4::"Default behaviour becomes NO-OP normalisation. octavewrite 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." AFTERSR3T2::"Canonicalisation moves to a separate octavefmt tool. Use octavewrite to PERSIST bytes; use octavefmt to CANONICALISE on demand. Two distinct calls, two distinct receipts. Sprint 3 milestone." §6b::SEMANTICSHIFTOFEMPTYWARNINGS // The same wire shape (warnings: []) carries different meaning across the timeline. TODAY::"warnings:[] ≡ sourcealreadycanonical[nochangesneeded]" AFTERSR1T4::"warnings:[] ≡ nonormalisationattempted[canonicalityunknown]" IMPLICATION::"Post-SR1-T4, do NOT infer canonicality from absence of warnings. Run octavefmt (post-SR3-T2) or call octavevalidate to check canonicality." I4RECEIPT::"This semantic shift is itself a TRANSFORMAUDITABILITY event — logged here in skill text rather than absorbed silently into existing wording. PROD::I4." §6c::AGENTGUIDANCEBYPHASE PHASETODAY::[ "Use octavewrite for both persistence AND canonicalisation", "Inspect warnings[] to learn what was normalised", "Empty warnings[] = clean[input was canonical]" ] PHASEAFTERSR1T4::[ "Use octavewrite 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 octavevalidate or (post-SR3-T2) octavefmt" ] PHASEAFTERSR3T2::[ "octavewrite::persistenceonly[nocanonicalisation]", "octavefmt::explicitcanonicalisation[ondemand,returnsdiffreceipt]", "Two-call pattern: writethenfmt for canonical persistence; writeonly for raw persistence" ] §6d::INVARIANTRELOCATIONNOTRELAXATION // PROD::I1 (SYNTACTICFIDELITY: normalizationalterssyntaxneversemantics) is NOT being weakened. // The bifurcation RELOCATES the I1 enforcement locus from octavewrite to octavefmt. // octavefmt remains bound by I1 (idempotent, bijective on semantic space). // octavewrite becomes a pure persistence path; canonicalisation is opt-in. AUTHORS::"Treat octavewrite as 'commit bytes' and octavefmt as 'canonicalise bytes' — they compose, they do not duplicate." §7::REPAIRLOGAUDITCOMPLETENESS // ADR-0006 SR1-T1 Step 3 (v1.12.0): RepairLog is the complete I4 record. POSTV1120::"RepairLog is the complete I4 (TRANSFORMAUDITABILITY) record. All TIERNORMALIZATION events (whitespace, blank-line, identifier dequoting, triple-quote collapse, W002) emit corrections via the central core/grammar/tiernormalize channel." EMPTYLOGSEMANTICS::"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." CONSUMERGUIDANCE::[ "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::UNIVERSALGOVERNANCEGRAMMAR // 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::ORGANIZINGPRINCIPLE MOTTO::"strict AST parse → gate. skill → schema. doctypes → zero registration tax." INSIGHT::"governance bodies → schema-exempt by declaration. META envelope → still validates." APPLIESTO::[ NorthStarSummary, ArchitecturalDecisionRecord, RequestForComments, projectcontextdocuments, anyrepeatedentitygovernanceartefact ] §8b::BLOCKFORMFORREPEATEDENTITIES // 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 WDUPLICATEKEY × 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." EXAMPLEFORBIDDEN::"I1::PERSISTENTCOGNITIVECONTINUITY::[PRINCIPLE::v,WHY::v,STATUS::v]" EXAMPLECANONICAL: ` §1::IMMUTABLES COUNT::6 I1<PERSISTENTCOGNITIVECONTINUITY>: PRINCIPLE::"persist context⊕decisions⊕learnings → cross-session continuity" WHY::"amnesia → system failure [prevent re-learning cost]" STATUS::PENDING OWNER::implementation-lead GATE::B1 I2<STRUCTURALINTEGRITYPRIORITY>: PRINCIPLE::"correctness⊕compliance → precedence over velocity" ... ` GUARANTEE::"each I<N> block scopes children → ZERO WDUPLICATEKEY across the §" APPLIESALSOTO::[ assumptions<A1..AN>, ADRrecords<ADR-NNNN>, RFCrecords<RFC-NNN>, constrainedvariables, anyhomogeneousrepeatedrecordblock ] §8c::MARKDOWNERADICATION // Mixed markdown ## headings inside ===NAME=== envelopes fail ETOKENIZE 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::SECTIONNAME" EXAMPLEBEFORE::"## IMMUTABLES (6 Total)" EXAMPLEAFTER: ` §1::IMMUTABLES COUNT::6 `` RATIONALE::"§N::NAME is structurally targetable. ## is text annotation lexer rejects." §8d::SCHEMAEXEMPTIONVIACONTRACT // 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 NORTHSTARSUMMARY / ADR / RFC schemas for every new artefact class. METAANNOTATION::"CONTRACT::HOLOGRAPHIC<parseonlygovernance>" SEMANTIC::"META → still validates against generic META schema. Body → parse-only governed. Body schemavalidationerrors → non-load-bearing by declaration." PRECEDENT::"§3b METACOMMONOPTIONAL already permits the HOLOGRAPHIC contract facet — we are using the existing hook, no spec change required." SUCCESSCRITERION::"octavevalidate STRICT → warnings:[] ⊕ errors:[] ⊕ repairs:[]" §8e::CANONICALANDSOURCEMETA // Path-tracking META fields enforced by canonical-paths pre-commit hook. CANONICAL::"runtime delivery path (e.g. .hestai/north-star/… or .hestai-sys/…)" SOURCE::"git-committed source path (e.g. src/<pkg>/bundledhub/… or repo-local)" RULE::"every governance .oct.md → META.CANONICAL ⊕ META.SOURCE required" PROJECTLOCAL::"if file lives only in project tree → CANONICAL == SOURCE" BUNDLEDHUB::"source ≠ canonical → CANONICAL points to .hestai-sys/, SOURCE points to bundledhub/" §8f::VALUEFORMDELEGATION // Reasoning-field values (PRINCIPLE, WHY, RATIONALE, EVIDENCE, …) → R3a §4 of octave-compression. // Do NOT use snakecaseblobs in reasoning fields → triggers WSNAKECASEBLOB advisory // (see octave-secretary §5::SNAKECASEBLOB anti-pattern, octave-mcp 1.13.0). SEECOMPRESSION::"octave-compression §4::R3a" SEESECRETARY::"octave-secretary §5::SNAKECASEBLOB" RULE::"quoted prose ∨ telegraphic operator form. NEVER bare snakecaseblob in reasoning fields." §8g::MIGRATIONCHECKLIST // Mechanical migration recipe — every legacy field preserved verbatim, only shape changes. STEP1::"replace every ## Heading → §N::SECTIONNAME" STEP2::"replace every I#::NAME::[KEY::v,…] → I#<NAME>:\\n KEY::v indented children" STEP3::"add META.CONTRACT::HOLOGRAPHIC<parseonlygovernance>" STEP4::"add META.CANONICAL ⊕ META.SOURCE" STEP5::"telegraphic-compress reasoning values per R3a (operators carry connectives)" STEP6::"octavevalidate STRICT → confirm warnings:[] ⊕ errors:[] ⊕ repairs:[]" INVARIANT::"core structural field names preserved (PRINCIPLE, WHY, STATUS, INHERITS, IS, ISNOT, GATES, LOADFULLNORTHSTARIF, THEOATH, …). Permitted semantic splits where the legacy form encoded multiple values in one slot: ASSUMPTIONS::N[note] → ASSUMPTIONSCOUNT::N ⊕ ASSUMPTIONSNOTE::note. RELATED::[issues]∨[adrs] → RELATEDISSUES::[…] ⊕ RELATEDADRS::[…]. IF::trigger,THEN::[actions] → TRIGGER::trigger ⊕ ACTION::[actions] (within §::PROTECTIONCLAUSE block). Splits are mechanical and lossless — no semantic content dropped." §8h::ENFORCEMENTLOCI // The convention is enforced at three structural points — drift in any one is detectable. LOCUS1::"this skill — declares the pattern (vault delivery via bundledhub)" LOCUS2::"octave-secretary agent — sole valid .oct.md write path, invokes octavewrite" LOCUS3::"octave-mcp 1.13 STRICT lexer — refuses non-compliant grammar at parse" DRIFTDETECTION::"file hash on bundled-hub skill source ⊕ pre-commit OCTAVE validation" ===END===