@event4u/agent-config 12.1.0 → 14.0.0

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -180,11 +180,11 @@ class RoadmapStats {
     }
 
     get open_blockers(): Blocker[] {
-        return this.blockers.filter((b) => b.status !== 'resolved');
+        return this.blockers.filter((b) => !blocker_is_resolved(b));
     }
 
     get resolved_blockers(): Blocker[] {
-        return this.blockers.filter((b) => b.status === 'resolved');
+        return this.blockers.filter((b) => blocker_is_resolved(b));
     }
 
     get done(): number {
@@ -365,6 +365,49 @@ interface Blocker {
      * costs one enum entry and turns a silent swallow into a rendered field.
      */
     question: string;
+    /**
+     * Gate taxonomy: `0` auto-run · `1` budget-preauthorized · `2`
+     * consent-once · `3` human-only. Empty string when the entry declares
+     * none, and an absent class READS AS 3 at every consumer.
+     *
+     * The default is the safe end on purpose. An agent that inferred the class
+     * at runtime could promote a Hard-Floor gate into something it executes;
+     * authoring it into the file means a misclassification is a reviewed edit,
+     * and `lint_roadmap_blockers` refuses a runnable class that names no
+     * command.
+     */
+    blockerClass: string;
+    /** The command a class-0/1 entry is resolved by running. */
+    run: string;
+    /** Spend estimate for class 1 — recorded, never enforced by the lint. */
+    budget: string;
+}
+
+/**
+ * Is this blocker settled?
+ *
+ * A PREFIX test, not equality, and the difference was measured: authors write
+ * the resolution into the status line — `**Status:** RESOLVED 2026-08-17 —
+ * **option (b)**, narrowed to two rules` — and an equality check matches
+ * neither `open` nor `resolved`, so the entry falls through to open. Found
+ * 2026-08-17 in `road-to-mixed-trigger-activation-cost`: a decision taken two
+ * days earlier was still being rendered by `agent-config gates` as a live one
+ * the reader owed an answer to, and it inflated every blocker count in the
+ * dashboard by one.
+ *
+ * `lint_roadmap_blockers` already read the same field as a prefix
+ * (`/^-\s*\*\*Status:\*\*\s*resolved/i`), so the two surfaces disagreed about
+ * what "resolved" means — the lint exempted the entry from its decidability
+ * ratchet while the dashboard counted it open.
+ */
+function blocker_is_resolved(b: Blocker): boolean {
+    return /^resolved\b/.test(_strip(b.status).toLowerCase());
+}
+
+/** Class of a blocker, with the absent-field default applied. */
+function blocker_class(b: Blocker): '0' | '1' | '2' | '3' {
+    const c = _strip(b.blockerClass).split(/[\s—–-]/)[0] as string;
+    return c === '0' || c === '1' || c === '2' ? c : '3';
 }
 
 // Strip fenced code blocks before blocker detection — a roadmap that shows the
@@ -380,8 +423,23 @@ function _stripFencedCode(text: string): string {
     return text.replace(FENCED_CODE_RE, (m) => '\n'.repeat(_splitlines(m).length));
 }
 
-const BLOCKER_FIELD_RE =
-    /^-[ \t]*\*\*(Status|Owner|Blocks|Resolved when|What to do|Recommendation|If you do nothing|Question):\*\*/i;
+/**
+ * Terminator for a blocker field's continuation lines — ANY `- **Label:**`
+ * bullet, not a closed list of known labels.
+ *
+ * It used to enumerate eight names, which silently diverged from the contract
+ * the two call sites below already document ("up to the next `- **Field:**`
+ * marker"): a bullet whose label was not on the list did not terminate, so the
+ * PREVIOUS field kept absorbing it and the dashboard rendered the two as one
+ * run-on sentence. Measured when `- **Options:**` and `- **Side finding:**`
+ * first appeared in a blocker — a reader saw the side finding as part of
+ * `Resolved when`, i.e. the generator changed what a field meant.
+ *
+ * A closed list is the wrong shape for a terminator: every future field name
+ * would have to be added here to avoid corrupting the field above it, and the
+ * failure is silent in generated output nobody edits by hand.
+ */
+const BLOCKER_FIELD_RE = /^-[ \t]*\*\*[^*]+:\*\*/;
 
 /** Strip an inline `<!-- comment -->` and trim. */
 function _stripComment(s: string): string {
@@ -493,6 +551,9 @@ function parse_blockers(raw_text: string): Blocker[] {
                 recommendation: _blockerField(body, 'Recommendation') ?? '',
                 ifNothing: _blockerField(body, 'If you do nothing') ?? '',
                 question: _blockerField(body, 'Question') ?? '',
+                blockerClass: _blockerField(body, 'Class') ?? '',
+                run: _blockerField(body, 'Run') ?? '',
+                budget: _blockerField(body, 'Budget') ?? '',
             });
         }
     }
@@ -527,6 +588,9 @@ function parse_blockers(raw_text: string): Blocker[] {
             recommendation: '',
             ifNothing: '',
             question: '',
+            blockerClass: '',
+            run: '',
+            budget: '',
         });
     }
     return blockers;
@@ -1172,6 +1236,8 @@ export {
     is_roadmap_candidate,
     count_checkboxes,
     parse_blockers,
+    blocker_class,
+    blocker_is_resolved,
     blocker_needs_user,
     parse_roadmap,
     bar,

package/dist/agent-src/skills/ai-council/SKILL.md

@@ -17,6 +17,67 @@ packs:
 
 # ai-council
 
+## Council-first — try the council BEFORE the user, on these classes
+
+```
+A DESIGN DECISION THE AGENT CANNOT SETTLE FROM THE TREE GOES TO THE COUNCIL
+FIRST, NOT TO THE USER FIRST. THE USER IS THE ESCALATION, NOT THE DEFAULT.
+NEVER PRESENT A COUNCIL VERDICT THAT WAS NOT REACHED. AN INCONCLUSIVE RUN
+IS REPORTED AS INCONCLUSIVE, AND WHATEVER YOU DECIDE INSTEAD IS LABELLED
+OWN ANALYSIS.
+```
+
+Interrupting the user is the expensive path: it costs a round trip and their
+attention, and on a question two models could have settled it buys nothing they
+wanted to be asked. So the ordering is **tree → council → user**, and the
+council leg is the one that gets skipped.
+
+**Classes that go to the council first** — each is a judgement with a real
+trade-off and no answer in the tree:
+
+| Class | Example |
+|---|---|
+| Competing implementations of one feature | two sessions shipped the same phase; discard, overwrite, or merge |
+| Which of N designs, all defensible | four declared types with a derived fifth, or five declared |
+| Reopening a recorded decision | an ADR or honest-null blocks a change that now looks net-positive |
+| Scope re-cut inside an authorized task | this phase splits into two, or absorbs the next |
+| Is the evidence sufficient to conclude | n=1 measurement, a proxy metric, an unreplicated finding |
+
+**Classes that still go straight to the user, and the council never substitutes
+for them:** anything behind the Hard Floor
+([`non-destructive-by-default`](../../rules/non-destructive-by-default.md)) ·
+spend · a scope EXPANSION beyond what was authorized · a decision whose inputs
+only the user holds (a preference, a deadline, a business constraint) · the
+`high_impact` and `user_required` classes, which
+[`ask-when-uncertain`](../../rules/ask-when-uncertain.md) routes to the user by
+Iron Law. A council cannot consent on the user's behalf, and asking it to is not
+autonomy, it is laundering.
+
+### When the council cannot answer
+
+Measured 2026-08-17: a run returned **0 of 2 seats**, both `cli_quota_exhausted`,
+with the counters at 72/50 and 99/50. The CLI reported it correctly as
+`INCONCLUSIVE — DEGRADED` and did not print a quorum it had not reached. Three
+things follow, and the first is the one under pressure:
+
+1. **Never dress your own verdict as the council's.** A fan-out, a solo read, or
+   your own judgement is a legitimate substitute **only when named as such** —
+   the boundary [`council-availability`](../../rules/council-availability.md)
+   states.
+2. **Do not bounce to the user just because the council failed.** An
+   unreachable council does not upgrade a decidable question into a
+   user-required one. Decide it, label it own analysis, state the reason the
+   council was unavailable, and name what would change the answer.
+3. **Escalate only if it is genuinely undecidable without them** — the two
+   options are close AND the cost of being wrong is high AND nothing in the tree
+   separates them. Then say the council was attempted and why it failed, so the
+   user is not asked to arbitrate something they will assume was already tried.
+
+`agent-config council:status` is free and answers availability; `council_cli
+estimate <file>` is free and answers parse-and-cost. Run both before concluding
+the council is not an option — and note the question goes in a **file**, since
+prose passed as an argument overflows the argument limit.
+
 ## When to use
 
 * The host agent has drafted a roadmap, plan, or design and wants an

package/dist/agent-src/skills/authz-review/SKILL.md

@@ -11,6 +11,10 @@ workspaces:
   - engineering
 packs:
   - engineering-base
+triggers:
+  - phrase: "authorization check"
+  - phrase: "permission check"
+  - keyword: "authz"
 ---
 
 # authz-review

package/dist/agent-src/skills/design-system-capture/SKILL.md

@@ -306,6 +306,10 @@ handoff shape emitted alongside `design-system.json`
   — when the artifact is a mock — an explicit "prototype, not production code"
   warning so a consumer never ships the reference verbatim.
 
+**What to capture FROM** a running project: sources first, SSR fetch second,
+rendered snapshot only with consumer tooling; record the git SHA. Rationale:
+[snapshot preference order](references/snapshot-preference-order.md).
+
 ## Gotcha
 
 - **Over-writing instead of diff-updating** — the most common failure.

package/dist/agent-src/skills/design-system-capture/references/snapshot-preference-order.md

@@ -0,0 +1,77 @@
+# Snapshot preference order — what to capture a design system FROM
+
+When a design system has to be captured out of a running project — for a
+handoff, an external design pass, or a reference bundle — there is more than one
+thing you could point at, and they are not equally good. This is the preference
+order, highest fidelity per unit of effort first.
+
+**Take the first level the project supports. Do not skip down the list for
+convenience, and do not skip UP it for thoroughness** — Level C is additional
+evidence, never a replacement for Level A.
+
+## Level A — source-level (always available, the default)
+
+The involved component sources, plus the token layer (DTCG / CSS custom
+properties), plus the page composition that assembles them.
+
+**Why this is the default and not the fallback**, which is the part that reads
+backwards until you have seen the alternative: in a component project, a
+rendered DOM dump is *worse* input than the sources it came from. Hydrated
+markup is utility-class soup with the component boundaries erased — the very
+structure a design system is made of is the structure rendering destroys. A
+reader (human or tool) reworks clean sources far better than expanded markup.
+
+Level A needs no dev server, no browser, and no network. It is available in a
+bare checkout, which is why it is also the only level that always works.
+
+## Level B — SSR fetch (no browser)
+
+When the stack renders server-side and a dev server is running, an ordinary
+HTTP fetch of the rendered page.
+
+Use it to answer what Level A cannot: what the composition actually resolves to
+for a given route — conditional branches taken, data-dependent states, the real
+class strings after server-side composition. Zero browser dependency, so it
+stays cheap.
+
+Level B **supplements** Level A. Capturing B alone leaves you with the soup
+problem above and no component boundaries.
+
+## Level C — rendered snapshot (consumer tooling only)
+
+If the project already carries a browser-automation tool, or a DevTools bridge
+is available in the session, additionally capture a screenshot plus a
+computed-style extract as visual ground truth.
+
+**Capability-detect, never hard-depend.** Level C is available when the consumer
+already has the tooling; it is never a reason to install a browser stack, add a
+dependency, or fail a capture. A project without it captures at A (and B where
+applicable) and says so.
+
+Of the two artefacts, **the screenshot is the valuable part** — it is the only
+one that records what a person actually sees. The DOM dump is supplementary and
+carries the erasure problem Level A exists to avoid.
+
+## Every snapshot records the source revision
+
+Whatever level was captured, record the git SHA the capture was taken at.
+
+This is the anchor that makes a return leg possible: without it, reworked output
+cannot be diffed against what was sent, and a capture from an unknown state is
+evidence about nothing in particular. It costs one line and it is the difference
+between a snapshot and a screenshot.
+
+## State the level in the output
+
+A capture says which level it reached and why it stopped there — "Level A + B;
+no browser tooling detected, so no visual ground truth". A consumer reading the
+bundle can then tell *absent because unavailable* from *absent because
+overlooked*, which is the same distinction the extraction floor draws for
+not-extractable values.
+
+## See also
+
+- [`design-system-json.md`](design-system-json.md) — the import contract the
+  captured artefact is emitted against.
+- [`../SKILL.md`](../SKILL.md) § Design-system extraction floor — what a
+  complete extraction carries once the source has been chosen.

package/dist/agent-src/skills/experiment-loop/SKILL.md

@@ -0,0 +1,116 @@
+---
+model_tier: inherit
+name: experiment-loop
+description: "Use to drive a scalar metric down or up across bounded iterations — keep on strict improvement, revert otherwise, state on disk. Triggers 'minimize X', 'optimize until it stops improving'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# experiment-loop
+
+> A bounded **change → commit → evaluate → keep-or-revert** cycle against a
+> **scalar metric**, where the decision input is an
+> [evaluator-output](../../../docs/contracts/evaluator-output.md) verdict and the
+> loop's entire state lives in an append-only register on disk.
+
+This file **routes**. The protocol, the register format, and the pivot ladder are
+reference files loaded on demand — a loop doctrine read in full on every session
+that merely mentions optimization is a payload nobody asked for.
+
+| Need | Load |
+|---|---|
+| The iteration protocol and its two exit conditions | [`references/protocol.md`](references/protocol.md) |
+| The register's row shape and write ordering | [`references/register-format.md`](references/register-format.md) |
+| What to do when the metric stops moving | [`references/pivot-ladder.md`](references/pivot-ladder.md) |
+
+## When to use
+
+* The goal is expressible as **"minimize X"** or **"maximize X"** against a
+  mechanical verifier — bundle size, violation count, query count, runtime.
+* A verifier already emits, or can be wrapped to emit, the evaluator-output
+  contract. Wrapping is usually free: three of this repo's verifiers were wrapped
+  with zero changes to any of them.
+
+Do **NOT** use when:
+
+* The target is a **known end state**, not a number — "make the tests pass" has a
+  destination, so use [`verify-repair-loop`](../verify-repair-loop/SKILL.md),
+  which converges toward it. This skill has no destination; it has a direction.
+* The verdict is **subjective craft** — no scalar, nothing to optimize.
+* The metric is a **proxy nobody agreed on**. Optimizing an unowned proxy is how
+  a loop makes a system worse while its number improves.
+
+## The Iron Law
+
+```
+THE METRIC IS NEVER SOVEREIGN. `pass` IS.
+KEEP ONLY ON `pass && score > baseline`. A CHANGE THAT IMPROVES THE NUMBER
+AND BREAKS BEHAVIOUR IS REVERTED — MEASURED, NOT ASSUMED.
+COMMIT BEFORE YOU EVALUATE, SO EVERY REVERT IS A GIT OPERATION.
+THE REGISTER IS WRITTEN BEFORE THE ACTION IT RECORDS, NEVER AFTER.
+STATE LIVES ON DISK AND IS RE-READ EACH CYCLE — NEVER IN THE CONVERSATION.
+```
+
+Each line is a measured failure, not a preference. Spike s01 ran a change that
+improved its metric by 67 % and broke the behaviour it measured; only `pass`
+reverted it. The same run crashed between its commit and its register append,
+twice, leaving the branch one iteration ahead of its own record.
+
+## Procedure
+
+1. **Inspect the verifier before trusting it.** Run the evaluator once on the
+   unchanged tree and check its verdict: `pass` must be true and `metric_state`
+   must be `present`. A baseline taken from an evaluator that is already red, or
+   whose metric is unreadable, is not a baseline — every later comparison
+   inherits the defect silently.
+2. **Fix the metric and the verifier** before the first change. Name the
+   evaluator, its direction, and the baseline score.
+3. **Declare the bound** — a maximum iteration count, written into the register's
+   first row. An unbounded loop is not this skill.
+4. **Iterate** per [`references/protocol.md`](references/protocol.md): one focused
+   change, commit, evaluate, keep or revert, append the outcome.
+5. **Exit** on either condition (both machine-checkable, never prose): the bound
+   is reached, or the explicit exit signal fires.
+6. **Report** from the register, not from memory. If the register cannot
+   reconstruct the run without the transcript, the run is not reportable.
+
+## Validation
+
+* The register reconstructs the run with the transcript discarded — every kept
+  change traceable to a row, every row to a commit.
+* Both branches ran at least once. **A loop whose revert branch never executed
+  is a one-branch loop with a comment**; spike s01 found its revert broken on
+  first use after four green iterations.
+* The final tree passes the evaluator with `pass: true`.
+
+## Output format
+
+1. **The register path**, and the iteration count actually run against the bound.
+2. **A metric line**: baseline → final, and the number of keeps versus reverts.
+3. **The exit condition that fired**, named — bound reached, or exit signal.
+4. **Every reverted iteration listed** with its reason. A revert is a result the
+   next run needs, not noise to summarise away.
+
+## Gotcha
+
+* **A metric that improves while the system degrades.** The reason `pass` is
+  sovereign. Never widen a verifier to make an iteration keep.
+* **A revert path that has never run.** Exercise it deliberately once.
+* **A register appended after the mutation.** A crash in between leaves the
+  branch ahead of the record; write the row first, then update its outcome.
+* **Loop state in the conversation.** It decays silently and the loop keeps
+  comparing against a baseline it no longer holds.
+* **Iterating past the bound because the number is still moving.** The bound is
+  the contract; extending it is a new run with a new baseline.
+
+## Do NOT
+
+* Do NOT keep a change on `score` alone.
+* Do NOT edit the verifier to move the metric.
+* Do NOT batch several changes into one iteration — a keep you cannot attribute
+  is a keep you cannot revert.
+* Do NOT delete a register row. Rows are append-only, including the embarrassing
+  ones.

package/dist/agent-src/skills/experiment-loop/evals/output-schema.yml

@@ -0,0 +1,27 @@
+# Behavior-schema contract for `experiment-loop`.
+#
+# Locks the sections a refactor could quietly drop while the skill still
+# reads plausibly. Each one is a measured failure from spike s01
+# (agents/evidence/eval-findings/metric-loop-s01.md), not a style
+# preference:
+#
+#   The Iron Law  — `pass` sovereign over `score`; a change that improved
+#                   the metric 67% and broke behaviour was reverted only
+#                   because of it.
+#   Validation    — the both-branches-ran check; s01's revert path was
+#                   broken and four green iterations never noticed.
+#   Output format — the register-derived report; a report from memory is
+#                   the in-conversation state the register exists to replace.
+#   Do NOT        — the four keeps that must not happen.
+#
+# Enforced by `skill_linter` (`lint_output_schema`, matches `^## <header>$`) —
+# a missing section is a hard error.
+
+version: 1
+
+required_headers:
+  - "The Iron Law"
+  - "Procedure"
+  - "Validation"
+  - "Output format"
+  - "Do NOT"

package/dist/agent-src/skills/experiment-loop/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "skill": "experiment-loop",
+  "last_eval": "2026-08-17",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers the bounded keep-or-revert loop against a SCALAR metric (direction, no destination). Should-not-trigger covers the near-miss neighbours the roadmap's gap-table names: iterate-to-a-known-end-state (verify-repair-loop), subjective craft with no scalar, a one-shot measurement, a one-shot review, and asking what a metric currently is.",
+  "queries": [
+    {"q": "minimize the bundle size, keep changes that help and revert the rest", "trigger": true},
+    {"q": "optimize this until it stops improving, bounded to ten tries", "trigger": true},
+    {"q": "drive the query count down across iterations and record what you kept", "trigger": true},
+    {"q": "run a keep-or-revert loop against the lint violation count", "trigger": true},
+    {"q": "reduce this metric as far as it goes without breaking the tests", "trigger": true},
+    {"q": "keep fixing until the tests pass", "trigger": false, "note": "a known end state, not a direction → verify-repair-loop"},
+    {"q": "iterate this change to green, run the suite each time", "trigger": false, "note": "converges toward a destination → verify-repair-loop"},
+    {"q": "is this diff clean — naming, structure, conventions?", "trigger": false, "note": "subjective craft, no scalar to optimize"},
+    {"q": "how big is the bundle right now?", "trigger": false, "note": "a single measurement, no loop"},
+    {"q": "review my changes before I open the PR", "trigger": false, "note": "one-shot review → /review-changes"}
+  ]
+}

package/dist/agent-src/skills/experiment-loop/references/pivot-ladder.md

@@ -0,0 +1,54 @@
+# experiment-loop — the pivot ladder
+
+Loaded on demand by [`experiment-loop`](../SKILL.md), when the exit signal
+`consecutive_reverts >= N` fires. The metric has stopped moving. The question is
+whether that is a fact about the system or about the hypotheses being tried.
+
+Climb one rung at a time. Each rung is a **new run** with a fresh register and a
+re-declared baseline — never a quiet continuation of the old one, because a run
+whose hypothesis class changed mid-flight cannot be read afterwards.
+
+## Rung 1 — a different hypothesis class, same metric
+
+The reverts share a shape: every attempt tried to shave the same structure. Pick
+a class the run has not touched — a different module, a different layer, a
+different kind of change — and rerun with the current score as the baseline.
+
+Stop climbing here if the first iteration of the new class keeps.
+
+## Rung 2 — check the metric measures what you meant
+
+Before concluding the system is optimal, confirm the number is the number. The
+measured failure mode: a diff-volume metric that looked like shipping volume was
+counting the repository's own review bookkeeping — a committed copy of the diff
+being measured — so the ranking it produced was of the wrong thing entirely.
+Excluding the bookkeeping moved the p90 by more than half and reordered the top
+five.
+
+Ask: does the metric include artefacts the change did not author? Generated
+files, snapshots, vendored trees, its own output? Correcting that is a
+**measurement fix** and legitimate.
+
+## Rung 3 — decide whether tuning is the honest move
+
+Rung 2's correction has a twin that is not legitimate: adjusting the metric until
+the answer is pleasant. The discriminator is stated once, plainly:
+
+> **Removing an input that was never part of the quantity is a correction.
+> Moving a threshold or growing an exclusion set until the result improves is
+> tuning.** A correction can be justified without reference to its effect on the
+> outcome. Tuning cannot.
+
+If the only available move needs the outcome to justify it, stop. The run's
+answer is that the metric does not move under changes of this kind, and that is
+a real result worth recording.
+
+## Rung 4 — publish the null
+
+No rung produced a keep. Write the run up: the metric, the bound, the hypothesis
+classes tried, the register path, and the conclusion that the metric did not
+move. A published null is why the next person does not re-run this.
+
+**Do not climb back down.** Re-running rung 1 with slightly different wording is
+the shape that turns a bounded loop into an unbounded one, and it burns budget
+producing rows that all say the same thing.

package/dist/agent-src/skills/experiment-loop/references/protocol.md

@@ -0,0 +1,61 @@
+# experiment-loop — the iteration protocol
+
+Loaded on demand by [`experiment-loop`](../SKILL.md). One iteration, in order.
+
+## The cycle
+
+1. **Read the register from disk.** Not from the conversation, not from a
+   variable held since the last cycle. The baseline for this iteration is the
+   `score` of the most recent `keep` row, or the declared baseline if there is
+   none.
+2. **Make ONE focused change.** One hypothesis per iteration. A batched
+   iteration produces a keep you cannot attribute and therefore cannot revert.
+3. **Append the register row** with `decision: "pending"` — before the commit,
+   before the evaluation. See [`register-format.md`](register-format.md) for why
+   the ordering is this way round.
+4. **Commit.** The revert is then a git operation rather than a manual undo, and
+   the branch carries one commit per iteration whether it survives or not.
+5. **Evaluate** — run the evaluator, read its
+   [evaluator-output](../../../../../docs/contracts/evaluator-output.md) verdict.
+6. **Decide**, and update the row:
+
+   | Verdict | Decision |
+   |---|---|
+   | `pass: true` and `score > baseline` | **keep** |
+   | `pass: true` and `score <= baseline` | **revert** — no strict improvement |
+   | `pass: false` | **revert** — the tree is red |
+   | non-zero exit · absent JSON · timeout | **revert** — the experiment failed, the measurement did not happen |
+   | `metric_state: "unreadable"` | **revert** — an unread metric is not a zero |
+
+7. **Revert if the decision says so**, then loop.
+
+## The two exit conditions
+
+Both are **machine-checkable predicates**. Neither is prose, and that is
+deliberate: a stop condition written loosely rots, and the rot is invisible
+because the loop keeps running.
+
+**Condition A — the bound.** `iterations_run >= max_iterations`, where
+`max_iterations` was written into the register's first row before the first
+change. Reaching it is a normal exit, not a failure.
+
+**Condition B — the exit signal.** A predicate declared at the start, evaluated
+against the register each cycle. Two usable shapes:
+
+- `consecutive_reverts >= N` — the metric has stopped moving under this
+  hypothesis class. Route to [`pivot-ladder.md`](pivot-ladder.md).
+- `score >= target` — the run had a destination after all, and reached it.
+
+**Why two and not one.** A bound alone burns the whole budget on a metric that
+stopped moving at iteration three. An exit signal alone is an unbounded loop
+wearing a condition: if the signal never fires — and a subtly wrong predicate
+never fires — nothing stops it. Each guards a different failure direction, so
+neither is the redundant one.
+
+## What ends a run that is not an exit condition
+
+Nothing. Specifically **not**: the number looking good enough, the change
+starting to feel risky, or the register getting long. Those are judgements, and
+a loop that stops on a judgement produces a result nobody can reproduce. If the
+run should stop for a reason the predicates do not cover, that is a finding
+about the predicates — record it and fix them for the next run.

package/dist/agent-src/skills/experiment-loop/references/register-format.md

@@ -0,0 +1,66 @@
+# experiment-loop — the register
+
+Loaded on demand by [`experiment-loop`](../SKILL.md). The register is the run:
+if it cannot reconstruct what happened with the transcript discarded, the run
+was not recorded.
+
+## Shape
+
+An **append-only JSONL** file, one row per iteration, **untracked** (the run is
+evidence, not source). Re-read from disk at the top of every cycle.
+
+Row 0 declares the run:
+
+```json
+{"row": 0, "evaluator": "bundle-size", "direction": "minimize",
+ "baseline_score": -142000, "max_iterations": 12,
+ "exit_signal": "consecutive_reverts >= 3"}
+```
+
+Each iteration:
+
+```json
+{"row": 1, "label": "drop the polyfill for evergreen targets", "head": "a1b2c3d",
+ "baseline_score": -142000, "score": -138400, "metric": 138400,
+ "metric_state": "present", "pass": true, "decision": "keep",
+ "reason": "strict improvement"}
+```
+
+`decision` is one of `pending` · `keep` · `revert`. `reason` is one of
+`strict improvement` · `no strict improvement` · `test red` ·
+`evaluator failed` · `metric unreadable`.
+
+## Write the row BEFORE the action it records
+
+This is the ordering that costs a run to learn. The obvious sequence — commit,
+evaluate, revert, then append — leaves a window in which the branch has advanced
+and the register has not. Spike s01 hit it twice: the revert threw, the process
+died, and the row was never written, so the register described a run one
+iteration shorter than the branch.
+
+So: append the row with `decision: "pending"` first, then act, then rewrite that
+row's decision. A crash then leaves a visible `pending` — a row that says "an
+iteration started here and we do not know how it ended", which is recoverable —
+instead of silence, which is not.
+
+**"Append-only" and "rewrite the last row" are not in conflict.** Append-only
+governs *history*: no row is ever deleted and no earlier row is ever edited. The
+pending row is the write frontier, not history, until its outcome lands.
+
+## Why on disk and not in the conversation
+
+Two independent references converged on files-as-truth after documenting silent
+degradation of in-conversation loop state, and the mechanism is not exotic: a
+baseline held in context drifts as the context is summarised, and the loop keeps
+comparing against a number that is no longer the one it kept. Nothing errors.
+The run just quietly stops meaning anything.
+
+Re-reading from disk each cycle costs one file read and removes the entire
+class.
+
+## Reporting from the register
+
+The final report is derived, never remembered: iterations run against the bound,
+baseline → final score, keeps versus reverts, the exit condition that fired, and
+every reverted iteration with its reason. A revert is the most informative row in
+the file — it is the hypothesis the metric rejected, and the next run needs it.

package/dist/agent-src/skills/merge-conflicts/SKILL.md

@@ -7,6 +7,10 @@ workspaces:
   - engineering
 packs:
   - engineering-base
+triggers:
+  - phrase: "merge conflict"
+  - phrase: "rebase conflict"
+  - phrase: "resolve conflicts"
 ---
 
 # merge-conflicts