docs(labs): introduce Lab 16 - Steady (Active Skill Governor)

labs/16-steady/README.md

@@ -0,0 +1,38 @@
+# Lab 16: Steady (Programmable Real-Time Skill Governor)
+
+This lab project documents the theoretical foundations, programmable schemas, and real-world use-cases of **Steady**, a real-time trajectory governor for LLM agent skills.
+
+## The Problem: The "Works on My Machine" Crisis of AI Skills
+
+Today, the standard way developers build agent capabilities is by adding custom skill files (like `.claude/skills/deploy.md` or `.gemini/skills/build.md`). These are flat, passive markdown files filled with natural-language instructions. 
+
+When a developer tests a skill locally in their chat window, the agent usually follows the instructions and it passes. However, when run in production, CI pipelines, or under high-context stress (large repo structures, history drift, complex logs), the agent gets confused, hallucinates, or gets trapped in infinite loops. 
+
+The developer has **no way to enforce boundaries or guarantee determinism.**
+
+## The Solution: Steady (Active Skill Stabilization)
+
+Instead of relying on offline benchmarking or wishing for "perfect" prompts, **Steady** introduces **Active Skill Stabilization**. 
+
+Under this paradigm, **Active Skills remain 100% standard Markdown files** that any existing coding agent can natively read and understand. However, the constraints (tool clamps, command whitelist regex, and safety guards) are defined strictly as metadata within the **YAML frontmatter** of the skill file.
+
+When the agent attempts to run any command, the pre-tool execution hook (such as `guard.sh`) dynamically parses the active skill's frontmatter in real-time, evaluates the constraints, and **physically blocks or steers the agent** back into its allowed lane. 
+
+The agent can still think creatively, but its execution trajectory is collapsed to a deterministic set of safe tool paths.
+
+## Lab Documentation Index
+
+This lab documents the system architecture across three canonical modules:
+
+1. **[docs/01-concept-and-theory.md](docs/01-concept-and-theory.md)**:
+   * The mathematical roots of trajectory entropy.
+   * Volatility ($f' = p(1-p)$) and the "zero-gradient" zones (Saturated Success vs. Saturated Failure).
+   * The NASA F' flight software lineage.
+2. **[docs/02-programmable-invariants.md](docs/02-programmable-invariants.md)**:
+   * The YAML frontmatter schema for active skills.
+   * The real-time hook interception model (how `guard.sh` acts as the Governor).
+   * Designing the active state machine interface.
+3. **[docs/03-use-cases-and-examples.md](docs/03-use-cases-and-examples.md)**:
+   * **Database Migrations:** Locking down shell tools and enforcing read-only health checks.
+   * **Strict Builder:** Collapsing the tool choice space during compilation tasks.
+   * **Prompt Injection Defense:** Neutralizing prompt leaks and jailbreaks via global execution invariants.

labs/16-steady/docs/01-concept-and-theory.md

@@ -0,0 +1,88 @@
+# 01-Concept and Theory: The Math of Trajectory Entropy and F'
+
+## 1. Introduction: From Stochastic to Deterministic
+
+Current Large Language Models (LLMs) are inherently probabilistic (stochastic) prediction engines. When we wrap an LLM inside an autonomous agent loop and give it a set of tools (like shell execution, file read/write, or API access), we create a **probabilistic dynamical system**. 
+
+The sequence of tool calls and actions that the agent takes to achieve a goal is called its **trajectory**. 
+
+Without constraints, the trajectory is open-loop. If we run the same agent against the same goal 10 times, we will often get 10 different trajectories. Some will succeed quickly, some will wander down expensive and inefficient paths, and some will crash, hallucinate, or get stuck in infinite loops.
+
+**Steady** changes the paradigm: it uses real-time, programmable boundaries to **collapse the trajectory state space**, ensuring that the only possible execution paths are safe and deterministic by construction.
+
+---
+
+## 2. The Math of Volatility: $f' = p(1-p)$
+
+In any model-graph or skill-execution node, if we run the node $N$ times, we can measure its success rate $p \in [0, 1]$ (where success is defined by a rigorous downstream verifier or compiler test).
+
+The volatility or sensitivity of that node, denoted $f'$, is modeled mathematically as:
+
+$$f' = p(1-p)$$
+
+This formula is the exact mathematical representation of the **variance of a Bernoulli trial**, and it mirrors the shape of **binary entropy**. 
+
+```
+               f' (Sensitivity / Trajectory Volatility)
+                 ^
+               1 |          * (Max Volatility / Maximum Flakiness)
+                 |       *     *
+                 |     *         *
+                 |   *             *
+               0 +--------------------> p (Success Rate)
+                 0         0.5         1
+              [Saturated             [Saturated
+               Failure]               Success]
+```
+
+### The Three Operational Zones
+
+This volatility curve has three distinct zones of interest to a systems developer:
+
+1. **Saturated Failure ($p = 0, f' = 0$):**
+   * The skill fails 100% of the time. 
+   * Because $f' = 0$, there is no gradient. Small prompt tweaks or context changes will not make it pass. This is a **brick wall**. The system cannot self-heal here; it must escalate immediately to prevent wasted compute.
+2. **Saturated Success ($p = 1, f' = 0$):**
+   * The skill passes 100% of the time.
+   * Because $f' = 0$, the execution is completely stable. This is the **inverse to failure**. The trajectory is reliable, and the system can freeze or cache this path to save expensive LLM tokens.
+3. **The Sensitive Region ($0 < p < 1, f' > 0$):**
+   * This is the "flaky" or "fragile" zone. The agent sometimes succeeds and sometimes fails. The trajectory is highly sensitive to tiny perturbations in the prompt, repo size, temperature, or context window ordering. 
+   * This is the **Active Development/Triage Zone**. It has the highest entropy, meaning it contains the most signal. Shifting a node from $p=0.5$ to $p=1.0$ is where engineering optimization has the highest leverage.
+
+---
+
+## 3. The Shift: Offline Profiling vs. Active Real-Time Stabilization
+
+Traditional software testing relies on **offline profiling**: running a test suite 100 times, measuring the flakiness (finding nodes where $f' > 0$), and then manually modifying code or prompts until the flakiness disappears.
+
+For probabilistic agent systems, this offline process is too slow, expensive, and fragile. A prompt that is stable ($p=1$) on a small repository can instantly become highly volatile ($p=0.4$) when run on a large production repository because the context window is "drowned" by unrelated files.
+
+### Active Real-Time Stabilization
+
+Rather than trying to write the "perfect" english prompt and hoping the agent behaves, **Steady** implements **Active Trajectory Clamping**. 
+
+By running a real-time **Governor** inside the pre-tool execution hook (like `guard.sh`), we physically intercept the agent's proposed tool calls on the fly. 
+
+If the agent attempts to take a tool path that violates the skill's defined invariants, the Governor blocks the execution, restricts the agent's available tools, and injects a corrective instruction directly into the agent's prompt history. 
+
+This **collapses the available choice space to 1** at the boundary, forcing the agent's trajectory back to the centerline. By preventing drift in real-time, **we guarantee determinism on the very first run, rendering offline flakiness measurements completely obsolete.**
+
+---
+
+## 4. The NASA F' Lineage
+
+This philosophy is not new; it is the core architecture used to fly deep-space missions where software failure is fatal.
+
+**NASA JPL's F' (F Prime)** is the open-source flight software framework that powered the **Ingenuity Mars Helicopter**. In flight software, you cannot have "stochastic" or flaky execution. If a variable drifts slightly, or a thread takes too long to respond, a helicopter on Mars will crash.
+
+F' solves this by enforcing:
+1. **Strict Components and Ports:** Every software block has statically typed, rigid boundaries.
+2. **State-Machine Bounds:** The system moves deterministically through bounded operational phases (e.g., Takeoff $\to$ Hover $\to$ Landing).
+3. **Real-time Telemetry and Invariant Interrupts:** If any sensor or execution state drifts outside the mathematically proven safe boundary of the active state, the system **automatically interrupts execution** and steers the hardware back to a safe "recovery mode."
+
+### Bridging F' and Probabilistic LLMs
+
+**Steady** brings this exact NASA flight safety discipline to LLM agents:
+
+* The **LLM** acts as the high-reasoning, creative engine (analogous to a helicopter adapting to wind gusts in real-time).
+* The **Steady Governor** acts as the high-integrity flight computer. It monitors the LLM's proposed commands against the active skill's state invariants, clamping tool sets and blocking destructive paths the millisecond a gust of "hallucination" attempts to veer the agent off course.

labs/16-steady/docs/02-programmable-invariants.md

@@ -0,0 +1,133 @@
+# 02-Programmable Invariants: Active Skill Contracts and Real-Time Governors
+
+## 1. The Active Skill Specification: Standards-Compatible
+
+One of the most important architectural design constraints of **Steady** is compatibility: **Active skills must remain standard Markdown skill files** (e.g. `SKILL.md`). 
+
+Any standard coding agent (such as Claude Code, Cursor, or Codex) can natively load, parse, and read the file as general prompting context. The agent remains entirely unaware of the execution engine.
+
+The programmable constraints (the trajectory lanes) are embedded directly within the **YAML frontmatter** at the very top of the `.md` file.
+
+### Schema of an Active Skill
+
+Below is the YAML schema used to define programmable invariants:
+
+```yaml
+---
+name: build                     # Unique identifier
+description: Runs project build  # Short description
+
+# 1. TOOL CLAMPING: Restricts the agent's available tools
+clamped_tools:
+  - Bash
+  - ReadFile
+  - WriteFile
+
+# 2. RUNTIME INVARIANTS: Regex whitelists/blacklists for commands
+invariants:
+  # The agent can run Bash, but ONLY for these specific allowed commands
+  allowed_command_patterns:
+    - "^go build ./...$"
+    - "^go test ./...$"
+    - "^git diff.*$"
+  # Explicitly block destructive filesystem moves
+  blocked_command_patterns:
+    - "rm -rf"
+    - "git reset --hard"
+
+# 3. REAL-TIME STEERING: What to do when the agent veers off course
+on_invariant_violation:
+  action: "DENY_AND_STEER"
+  # This message is returned directly to the agent's thought history
+  message: "Your proposed command was blocked. As the Builder skill, you are only allowed to compile, run tests, or view diffs. Do not perform destructive git moves."
+---
+
+You are the Boatstack builder. Read the approved feature plan and execute the code changes.
+When done, verify the build compiles successfully using the compilation commands.
+```
+
+---
+
+## 2. The Real-Time Governor Runtime
+
+How does this YAML metadata get enforced in real-time?
+
+The **Steady Governor** runs as a pre-tool execution hook (such as `guard.sh` or a local shell wrapper). When the coding host (e.g. Claude) proposes a tool call, the execution flow is intercepted:
+
+```
+                  ┌─────────────────────────────────┐
+                  │    Agent Proposes Tool Call     │
+                  │   (e.g., cmd: "rm -rf labs")    │
+                  └────────────────┬────────────────┘
+                                   │ (Intercepted by guard.sh)
+                                   ▼
+                  ┌─────────────────────────────────┐
+                  │   Steady Governor (safety-hook) │
+                  └────────────────┬────────────────┘
+                                   │
+                   Parse active    │
+                 SKILL.md metadata │
+                                   ▼
+                  ┌─────────────────────────────────┐
+                  │    Are Invariants Satisfied?    │
+                  └────────────────┬────────────────┘
+                                   │
+                   No (Violation)  │  Yes (Pass)
+         ┌─────────────────────────┴─────────────────────────┐
+         ▼                                                   ▼
+┌─────────────────────────────────┐                 ┌──────────────────┐
+│        DENY_AND_STEER           │                 │   ALLOW & EXEC   │
+├─────────────────────────────────┤                 └──────────────────┘
+│ 1. Block command execution.     │
+│ 2. Return deny JSON to host.    │
+│ 3. Inject "Steer Message" into  │
+│    agent's prompt history.      │
+└─────────────────────────────────┘
+```
+
+---
+
+## 3. Step-by-Step State Machines (High-Integrity Clamping)
+
+In advanced implementations, we can represent a skill not as a single flat prompt, but as a **sequence of steps (a finite state machine)**. 
+
+During each step, the Governor dynamically mutates the environment, exposing only the tools and command whitelists required for that specific step. This completely collapses the choice space at each node.
+
+### Conceptual Frontmatter for State-Bounded Skills
+
+```yaml
+---
+name: database-migration
+description: Safely runs migrations and checks health.
+
+steps:
+  # STEP 1: Discovery Phase (Read-only)
+  1_discover:
+    allowed_tools:
+      - ReadFile
+      - ListDirectory
+    on_success: "2_execute"
+
+  # STEP 2: Execution Phase (Narrow execution)
+  2_execute:
+    allowed_tools:
+      - Bash
+    allowed_command_patterns:
+      - "^npx prisma migrate deploy$"
+    on_success: "3_verify"
+    on_fail: "1_discover" # auto-rollback or retry
+
+  # STEP 3: Verification Phase (Read-only query)
+  3_verify:
+    allowed_tools:
+      - RunReadOnlyQuery
+    on_success: "COMPLETE"
+---
+```
+
+When the Governor executes this skill:
+1. In `1_discover`, the agent literally *cannot* execute a bash command because the tool is masked out in real-time. Hallucinations are physically blocked.
+2. Once the agent reads the migrations folder, the Governor's transition function automatically unlocks the bash command for `npx prisma migrate deploy`.
+3. If the command succeeds, it locks bash and unlocks `RunReadOnlyQuery`. 
+
+This step-by-step clamping guides the agent through a perfect, deterministic trajectory, eliminating flakiness and ensuring 100% stable runs across every user environment.