coulomb/clay-borg
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

CB-WP-0009-T03: InnerLoop v1.6

Browse source 
D2 the two exemptions — repairing the instrument that reports a breach
is always in budget, and the maintainer may authorize above-line work in
the workplan frontmatter. v1.5 had neither, and the first thing it did
was forbid fixing the budget's own defect.

D4 loop work cashes out into something runnable in the pass that invents
it, with the measured basis and the refutation condition stated.

D5 the tier table now triggers at M for changes to the loop's own
operation, closing the gap CB-RES-0005 §6 opened and this pass's own ADR
had to declare around.

The file went from 399 lines to 386: the chaos-roll calibration
rationale and the v1.0-v1.3 change log moved to InnerLoopReference.md.
Loadability is a gate too, and growing the file to fit a rule about
gates would have been the joke writing itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-01 15:43:34 +02:00
parent cd2dc5380a
commit 2b6bf29e8f
3 changed files with 116 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

121
specs/InnerLoop.md
View file

@ -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

56
specs/InnerLoopReference.md
View file

@ -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`.

7
workplans/CB-WP-0009-adaptive-gates.md
View file

@ -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