diff --git a/specs/InnerLoop.md b/specs/InnerLoop.md index 35d5ab9..c41965c 100644 --- a/specs/InnerLoop.md +++ b/specs/InnerLoop.md @@ -1,29 +1,53 @@ # The Inner Loop — Assimilate and Surpass -Status: **v1.5** — corrected from CB-WP-0007 (session shape) on -2026-08-01. Change from v1.4: a **soft 25% meta budget** (below), after a -spend review found the project 38% product / 62% loop-meta with cost per -response degraded 2.9x from its best window. +Status: **v1.6** — corrected from CB-WP-0008 (stage 0) and ADR-0006 on +2026-08-01. Changes from v1.5: budgets measure the window they govern and +a breach never blocks its own repair (D1/D2); loop work cashes out into +something runnable in the pass that invents it (D4); the tier table +covers changes to the loop's own operation (D5). -> **Meta budget — soft, 25% of spend per pass.** Work on the loop's own -> instruments and process is capped at a quarter of a pass. Measured by -> `make status` from each workplan's `kind:` frontmatter -> (`product` | `meta` | `mixed`). +> **Meta budget — soft, 25% of the trailing three passes.** Work on the +> loop's own instruments and process is capped at a quarter of recent +> spend. Measured by `make status` from each workplan's `kind:` +> frontmatter (`product` | `meta` | `mixed`), over a **trailing 3-pass +> window**; the lifetime figure is reported as history and is not the +> metric (ADR-0006 D1). > > **Soft on purpose.** A task already started may be finished — stopping -> mid-task to satisfy a ratio wastes the work and leaves the tree in a -> worse state than either finishing or never starting. What the budget -> forbids is *opening* new meta work above the line. +> mid-task to satisfy a ratio wastes the work and leaves the tree worse +> than either finishing or never starting. What the budget constrains is +> *opening* new meta work above the line, and it constrains it with two +> exemptions: +> +> 1. **Repairing the instrument that reports a breach is always in +> budget.** A gate must never block its own remedy (ADR-0006 D2, +> CB-RES-0005 §4). v1.5 had no such exemption, and the first thing it +> did was forbid fixing the budget's own defect. +> 2. **The maintainer may authorize above-line work**, recorded as +> `authorized_above_budget:` in the workplan frontmatter. Undocumented +> above-line meta work is a violation the evidence file must report. > > A pass that exceeds it **says so in its evidence file and names the -> product work displaced**. That is the whole enforcement: this is a -> reporting budget, not a gate, for the same reason the session-shape -> budget is (CB-RES-0005 §4) — it constrains judgment, not artifacts. +> product work displaced**. That is the whole enforcement: a reporting +> budget, not a gate, for the same reason the session-shape budget is — +> it constrains judgment, not artifacts. + +> **Loop work cashes out (v1.6, ADR-0006 D4).** A `meta` pass must ship at +> least one executable check, command, or gate. Findings that stay prose +> are recorded as findings and do **not** count as delivery. > -> *(v1.5, from the CB-WP-0007 spend review: CB-WP-0005 and CB-WP-0006 cost -> ~$74, 31% of all spend, for zero measured efficiency gain. Their return -> was correctness of claims, which is real and is not optimization. The -> budget exists so that distinction has to be made out loud.)* +> Measured basis: cost per response across five passes ran 0.123, 0.228, +> 0.362, 0.298, 0.123 dollars, and the reading that survived the data is +> that **cost tracks distance from a runnable check** — the passes that +> shipped a command were cheap, the passes that argued about what a +> number means were not (CB-EV-0007 §5). **Refuted if** a prose-only meta +> pass lowers cost per response or catches a class no command could. + +> **Every gate is an experiment (v1.6, ADR-0006 D3).** Each standing +> control gate has an entry in `gates.toml` naming what it has caught, a +> `review_by` date, and what would retire it. `make gate-review` reports +> what is overdue and what has caught nothing; `loop-lint` fails when the +> registry drifts from the Makefile in either direction. v1.4 — corrected from CB-WP-0005 (assertion coverage) on 2026-07-31. Change from v1.3: where a claim rests on numbers, the @@ -31,28 +55,10 @@ adversarial reviewer must read the assertion behind each quoted number and **mutate it** — re-running the command that prints a number is not verification of that number (§Step 2). -v1.3 changed from v1.2: single source of fact is now executable -(`make facts-check`, CB-WP-0004 T04), giving the duplicated-fact-drift -class its first gate. - -v1.2 changes from v1.1: single source of fact; review targets the -harness and states its sampling limit; correction vs retarget; the chaos -roll's calibration window; the live cost budget. The design goal is now -stated: **optimize for cheap correction, not for exhaustive prevention.** -Rationale: `history/260731-loop-hardening-retrospective.md`. - -v1.1 — corrected from CB-WP-0002 (cost accounting) on -2026-07-31. Changes from v1.0: the instrument must exist and emit its own -target; inherited numbers are re-derived before use; every reporting tool -exposes `--self-test`; cost is in the definition of done. Rationale: -`history/260731-cost-accounting-retrospective.md`. - -v1.0 — survived its first full pass (CB-WP-0001, the GROUND game kernel) -and was corrected from it on 2026-07-31. Changes from v0.2: measurement -validity (the positive control), metric feasibility and instrument naming, -four implementation rules the pass earned, and the requirement that -evidence state what it does not support. Rationale and the failures behind -each: `history/260731-inner-loop-retrospective.md`. +v1.5 (meta budget), v1.3 (executable single source of fact), v1.2 +(design goal: cheap correction over exhaustive prevention), v1.1 +(instruments emit their own targets) and v1.0: see +`specs/InnerLoopReference.md` §Change log. Normative process for building every Clay-Borg capability. Referenced by all workplans. @@ -111,7 +117,7 @@ are never skipped for code-producing work. | Tier | Weight of steps 1–3 | Structural trigger (forces at least this tier) | |---|---|---| | **L** | Full: separate survey, adversarial review, ADR | Creates a new capability port, or is named a high-leverage pass by the maintainer | -| **M** | Survey and ADR merged into one document; review optional | Touches a canonical interface, or adds/updates an external dependency | +| **M** | Survey and ADR merged into one document; review optional | Touches a canonical interface, adds/updates an external dependency, **or changes whether or how the loop constrains its own operation** — budgets, gates, review requirements, or these tier rules (v1.6, ADR-0006 D5) | | **S** | One provenance paragraph in the commit message | Everything else (utilities, fixes, refactors inside a boundary) | **The chaos roll.** After deriving the structural tier, roll **d4** @@ -119,32 +125,13 @@ are never skipped for code-producing work. random (`shuf -e S M L -n 1`), overriding the structural derivation — up or down. -> **Calibration window, opened 2026-07-31 (CB-WP-0003 T06).** The rate was -> d10 and the mechanism **never fired**: two rolls across two workplans -> (CB-WP-0001: 9, CB-WP-0002: 2), against ~0.2 expected firings. At d10 and -> ~2 tier decisions per workplan it would take roughly twenty workplans to -> observe four overrides, so the mechanism was set at a rate that prevented -> its own evaluation — the one option T06 ruled out. -> -> Raised to **d4 (25%) for the next 12 tier declarations**, then evaluated -> and either kept, returned to d10, or deleted. Expected ~3 firings in the -> window, which is enough to see whether an overridden tier produces a -> different outcome than the argued one. -> -> **Stated cost:** a chaos-L override on work that would have been S buys a -> full survey, adversarial review, and ADR. Measured comparable: CB-WP-0001 -> T03 (a tier-L survey) cost **$9.91**. At 25% over 12 declarations the -> window is expected to cost **$20–30**. That is the price of finding out -> whether the mechanism is worth keeping, and it is cheaper than carrying an -> unevaluated ritual indefinitely. Both rolls are recorded in the tier declaration -(`tier: M (structural L, chaos 10→M)`). **Record the roll every time, -including when it changes nothing** (`tier: L (structural L, chaos 4)`), -so a mechanism that never fires is visible rather than assumed. Purpose: -an occasional random -reweighting keeps the classification honest — arguing everything into S -stops paying off when audits can compare argued tiers against the random -sample — and occasionally forces a deep look at something "obviously -trivial", which is where local optima hide. +> **Calibration window, opened 2026-07-31, running to 12 tier +> declarations** (declaration 4 of 12 as of 2026-08-01). The rate was +> raised from d10 to d4 because at d10 the mechanism never fired and +> so prevented its own evaluation. Record the roll every time, +> including when it changes nothing (`tier: L (structural L, chaos 4)`). +> Rationale, cost estimate and the two dead rolls: +> `specs/InnerLoopReference.md` §Chaos roll — calibration. Chaos limits: a rolled-down tier relaxes *process* weight only. Invariants (zero foreign types in canonical interfaces, determinism, passing diff --git a/specs/InnerLoopReference.md b/specs/InnerLoopReference.md index 06af1fd..bf2b529 100644 --- a/specs/InnerLoopReference.md +++ b/specs/InnerLoopReference.md @@ -139,3 +139,59 @@ A capability has completed the loop when all of the following are committed: ([CostAccounting.md](CostAccounting.md)) - [ ] retrospective note (may be one paragraph appended to the evidence file): what the loop itself should change + +## Chaos roll — calibration (moved from InnerLoop v1.6) + +> **Calibration window, opened 2026-07-31 (CB-WP-0003 T06).** The rate was +> d10 and the mechanism **never fired**: two rolls across two workplans +> (CB-WP-0001: 9, CB-WP-0002: 2), against ~0.2 expected firings. At d10 and +> ~2 tier decisions per workplan it would take roughly twenty workplans to +> observe four overrides, so the mechanism was set at a rate that prevented +> its own evaluation — the one option T06 ruled out. +> +> Raised to **d4 (25%) for the next 12 tier declarations**, then evaluated +> and either kept, returned to d10, or deleted. Expected ~3 firings in the +> window, which is enough to see whether an overridden tier produces a +> different outcome than the argued one. +> +> **Stated cost:** a chaos-L override on work that would have been S buys a +> full survey, adversarial review, and ADR. Measured comparable: CB-WP-0001 +> T03 (a tier-L survey) cost **$9.91**. At 25% over 12 declarations the +> window is expected to cost **$20–30**. That is the price of finding out +> whether the mechanism is worth keeping, and it is cheaper than carrying an +> unevaluated ritual indefinitely. Both rolls are recorded in the tier declaration +(`tier: M (structural L, chaos 10→M)`). **Record the roll every time, +including when it changes nothing** (`tier: L (structural L, chaos 4)`), +so a mechanism that never fires is visible rather than assumed. Purpose: +an occasional random +reweighting keeps the classification honest — arguing everything into S +stops paying off when audits can compare argued tiers against the random +sample — and occasionally forces a deep look at something "obviously +trivial", which is where local optima hide. + + +## Change log — v1.0 to v1.3 (moved from InnerLoop v1.6) + +v1.3 changed from v1.2: single source of fact is now executable +(`make facts-check`, CB-WP-0004 T04), giving the duplicated-fact-drift +class its first gate. + +v1.2 changes from v1.1: single source of fact; review targets the +harness and states its sampling limit; correction vs retarget; the chaos +roll's calibration window; the live cost budget. The design goal is now +stated: **optimize for cheap correction, not for exhaustive prevention.** +Rationale: `history/260731-loop-hardening-retrospective.md`. + +v1.1 — corrected from CB-WP-0002 (cost accounting) on +2026-07-31. Changes from v1.0: the instrument must exist and emit its own +target; inherited numbers are re-derived before use; every reporting tool +exposes `--self-test`; cost is in the definition of done. Rationale: +`history/260731-cost-accounting-retrospective.md`. + +v1.0 — survived its first full pass (CB-WP-0001, the GROUND game kernel) +and was corrected from it on 2026-07-31. Changes from v0.2: measurement +validity (the positive control), metric feasibility and instrument naming, +four implementation rules the pass earned, and the requirement that +evidence state what it does not support. Rationale and the failures behind +each: `history/260731-inner-loop-retrospective.md`. + diff --git a/workplans/CB-WP-0009-adaptive-gates.md b/workplans/CB-WP-0009-adaptive-gates.md index 6db3480..9f0f035 100644 --- a/workplans/CB-WP-0009-adaptive-gates.md +++ b/workplans/CB-WP-0009-adaptive-gates.md @@ -92,7 +92,7 @@ a finding, both pinned by self-tests. First run: **0 due, 2 silent** ```task id: CB-WP-0009-T03 -status: todo +status: done priority: medium state_hub_task_id: "0b1b33ac-8046-4b34-b287-7b32755d964a" ``` @@ -111,6 +111,11 @@ Fold **D2**, **D4** and **D5** into `specs/InnerLoop.md`: pointer. Loadability is itself a gate; growing the file to fit a rule about gates would be the joke writing itself. +**Done 2026-08-01.** v1.6 in `specs/InnerLoop.md`, **386 lines** — the +chaos-roll calibration rationale and the v1.0–v1.3 change log moved to +`specs/InnerLoopReference.md`, so the file came in *smaller* than it +started at 399. + ## Task: control loop — did the changes fire? ```task