feat(framework): token economy (lite) - economical prose, hard never-compress gate (#134)

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.

Author: KailasMahavarkar

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.
 

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.

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 = [
     "<!-- GENERATED FILE. Edit skills/hyperstack/SKILL.md and re-run `bun run compile:context`. -->",
@@ -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.",
     "",