From 1ed3c3700d237a6e2a096c58663caddf31c47db1 Mon Sep 17 00:00:00 2001 From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com> Date: Sat, 18 Jul 2026 15:23:36 +0530 Subject: [PATCH] feat(framework): token economy (lite) - economical prose, hard never-compress gate Default output register compiled into every session's bootstrap: say it once, fewer words, grammar intact (lite, not caveman - words never break). Compress ONLY prose glue: preamble, restating, hedging, narration, option lists without a verdict. NEVER compress (hard gate, marker-guarded): diagrams/tables/visuals (padding rules stay), evidence (command output, errors, verification lines, numbers, ids), code/config, security + irreversible-action warnings, anything whose omission could change a decision. Seams closed from live pressure test: visuals are mandated where they beat prose (gate protects them once they exist AND requires them); user brevity requests compress prose only - they never touch the NEVER list; clarity beats economy on conflict. Compiler: extractOptionalSection (missing section tolerated in synthetic sources, real absence caught by new markers 'Token Economy' + 'NEVER compress'). Pressure evidence: ENOSPC docker scenario with 'minimal tokens, keep it SHORT' demanded twice - agent compressed to 7 prose sentences while keeping full storage-flow diagram, live df/system-df evidence, all fix commands, and the destructive image-prune warning. 87 tests pass. --- .../runtime-context/hyperstack.bootstrap.md | 20 ++++++++++++++++++ skills/hyperstack/SKILL.md | 21 +++++++++++++++++++ src/internal/context-compiler.ts | 12 +++++++++++ 3 files changed, 53 insertions(+) diff --git a/generated/runtime-context/hyperstack.bootstrap.md b/generated/runtime-context/hyperstack.bootstrap.md index 627ed23..fb5d105 100644 --- a/generated/runtime-context/hyperstack.bootstrap.md +++ b/generated/runtime-context/hyperstack.bootstrap.md @@ -117,6 +117,26 @@ Hyperstack is **ONE framework with four layers** - not four separate systems: - "I know the OKLCH token pattern" -> OKLCH has specific rules about alpha, chroma peaks, dark mode lightness - "This pattern looks common, I'll adapt it" -> Adaptation hides drift +## Token Economy (lite) +Default output register: economical. Say it once, in fewer words, with grammar +intact - lite means fewer words, never broken words. Technical terms stay exact. + +Compress ONLY: connective prose, preamble, restating the request, hedging, +narration of what you are about to do, option lists without a verdict. + +NEVER compress (hard gate - over-committing economy here is a bug, not thrift): +- diagrams, tables, and visual output - full padding and alignment rules stay +- evidence: command output, error text, verification lines, numbers, identifiers +- code and config +- security warnings and irreversible-action confirmations +- anything whose omission could change the user's decision + +When a visual is the clearest carrier of the answer, produce it - the gate +protects visuals once they exist AND mandates them where they beat prose. +User brevity requests ("short", "minimal tokens") compress prose only - they +never touch the NEVER list. "Verbose" / "explain fully" lifts the register for +that answer. When economy and clarity conflict, clarity wins - every time. + ## Degraded Mode - If MCP unavailable, tell the user explicitly: "MCP unavailable" and flag answers as uncertain. diff --git a/skills/hyperstack/SKILL.md b/skills/hyperstack/SKILL.md index 7b018a4..86085c9 100644 --- a/skills/hyperstack/SKILL.md +++ b/skills/hyperstack/SKILL.md @@ -272,6 +272,27 @@ persona's skill. --- +## Token Economy (lite) + +Default output register: economical. Say it once, in fewer words, with grammar +intact - lite means fewer words, never broken words. Technical terms stay exact. + +Compress ONLY: connective prose, preamble, restating the request, hedging, +narration of what you are about to do, option lists without a verdict. + +NEVER compress (hard gate - over-committing economy here is a bug, not thrift): +- diagrams, tables, and visual output - full padding and alignment rules stay +- evidence: command output, error text, verification lines, numbers, identifiers +- code and config +- security warnings and irreversible-action confirmations +- anything whose omission could change the user's decision + +When a visual is the clearest carrier of the answer, produce it - the gate +protects visuals once they exist AND mandates them where they beat prose. +User brevity requests ("short", "minimal tokens") compress prose only - they +never touch the NEVER list. "Verbose" / "explain fully" lifts the register for +that answer. When economy and clarity conflict, clarity wins - every time. + ## The Rationalization Catalog (Read Before Every Session) These are the exact thoughts you will have when you want to skip a skill. Every one is a bug in your reasoning. Every one has been written down because someone (probably you in a past session) used it to ship bad code. diff --git a/src/internal/context-compiler.ts b/src/internal/context-compiler.ts index 333eacc..847536a 100644 --- a/src/internal/context-compiler.ts +++ b/src/internal/context-compiler.ts @@ -52,6 +52,8 @@ const REQUIRED_BOOTSTRAP_MARKERS = [ "reflect", "bro", "Triggers:", + "Token Economy", + "NEVER compress", "auto-called", "hyper -> website-builder", ]; @@ -69,6 +71,14 @@ function extractTaggedBlock(source: string, tag: string): string { return match[1].trim(); } +function extractOptionalSection(source: string, heading: string): string { + try { + return extractSection(source, heading); + } catch { + return ""; + } +} + function extractSection(source: string, heading: string): string { const lines = source.split("\n"); const targetHeading = `## ${heading}`; @@ -192,6 +202,7 @@ export function compileUsingHyperstackBootstrap(source: string, personas: Person const disallowedTransitions = extractSimpleBullets(extractSection(body, "Disallowed Transitions")); const finalCheck = extractFinalCheck(body); const redFlags = extractRedFlags(body); + const tokenEconomy = extractOptionalSection(body, "Token Economy (lite)"); const content = [ "", @@ -237,6 +248,7 @@ export function compileUsingHyperstackBootstrap(source: string, personas: Person "## High-Signal Red Flags", ...redFlags, "", + ...(tokenEconomy ? ["## Token Economy (lite)", tokenEconomy, ""] : []), "## Degraded Mode", "- If MCP unavailable, tell the user explicitly: \"MCP unavailable\" and flag answers as uncertain.", "",