@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/minimal-safe-diff-mechanics.md

@@ -0,0 +1,241 @@
+# Minimal Safe Diff — Mechanics
+
+> Anti-over-engineering criteria, larger-change guidance, break-glass exception, and the bounded remediation carve-out for the `minimal-safe-diff` rule
+
+_Origin: migrated from `src/rules/minimal-safe-diff.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, "The rule", "Before writing the diff", the red-flags list, and "Own-orphan cleanup" (anchor-referenced by `downstream-changes`) stay in the rule; this file carries the worked criteria._
+
+## When the task seems to require a larger change
+
+- A rename, restructure, or framework upgrade that crosses the minimal-diff
+  line is a **separate, explicit** task — ask the user before expanding.
+- A bug fix that exposes a broader design problem stays a bug fix. Log the
+  design problem as a follow-up (ticket, note, TODO) and ship the fix alone.
+- A new feature that tempts you to "clean up" the module first: resist.
+  Add the feature, commit it, then propose the cleanup as a separate change.
+
+## Auto-formatter or linter rewrites unrelated code
+
+Revert those hunks before staging. The diff you present is the diff you own.
+If project policy forbids partial formatting, split into two commits:
+*format only* · *behavior change*.
+
+## Anti-over-engineering
+
+The smallest change is also the least *abstract* and least *speculative* one:
+
+- **Three similar lines beat a premature abstraction.** Do not extract a helper
+  / generic / config layer to dedupe two or three call sites — inline
+  repetition is cheaper to read and change than the wrong abstraction. Per new
+  abstraction: **cite the second caller — or inline it.** The operative
+  **code-level** threshold in this suite is the **second real repetition** (or a
+  genuine second axis of change), matching `architecture` and
+  [`component-oriented-and-oop-development`](../component-oriented-and-oop-development.md);
+  the "three lines" phrasing is about *line* count inside one call site, not a
+  third-occurrence gate. A borrowed "wait for the third occurrence" rule is
+  **not** adopted for code — it would fork a threshold this repo already
+  decided. UI extractions carry deliberately higher, scoped bars (ADR-213) —
+  the per-class canon is [`abstraction-thresholds`](../abstraction-thresholds.md).
+- **No speculative features.** Nothing beyond what was asked: no
+  configurability or "flexibility" nobody requested, no parameters with one
+  call site, no error handling for scenarios that cannot occur in this
+  codebase.
+- **The rewrite trigger.** If the change could be half the size without losing
+  behavior, rewrite before presenting. Self-check: *"Would a senior engineer
+  call this overcomplicated?"* — if yes, simplify.
+- **No tombstones.** Delete removed code completely — no `_oldName` renames,
+  no `// removed X` / `// no longer used` markers, no dead re-export shims kept
+  "for safety". Git history is the tombstone.
+- **No docstrings/comments on untouched code.** Do not annotate code the diff
+  does not change.
+
+### The sanctioned-rewrite trap (second-system effect)
+
+Distinct from *the rewrite trigger* above, which fires **mid-diff** on your own
+bloated change. This one fires at **intake**, when the user has already
+sanctioned a rewrite, a v2, a from-scratch replacement, or a large refactor —
+and it is the single highest over-build context there is. The second system a
+person builds is the most over-built one they will ever build: every constraint
+the first system taught them arrives as a feature, and none of it is demanded
+by the ticket in front of them.
+
+Permission to rewrite is permission to **replace the behaviour that exists** —
+not a licence to add the capability the old system lacked. The v2 ships the
+v1 surface, minus what is provably dead, plus only what was explicitly asked
+for. Everything the rewrite "makes easy to add now" is a separate change with
+its own demand gate (guideline § 8-pre) and its own place on the
+solution-size ladder (§ 8b-ladder).
+
+Wrong/right pairs for each ban:
+[`simplicity-and-goal-demos`](simplicity-and-goal-demos.md)
+— the demos are the recognition surface; match your diff against the *right*
+column before presenting.
+
+**Not adopted (council):** the source's "validate only at system boundaries /
+trust internal code" clause is **rejected** — internal code can be wrong, and
+"trust" is not a testing strategy. Keep validating internal invariants; this
+fold is about *diff shape*, not about dropping internal checks.
+
+## Break-glass exception
+
+The rule stays in force during production incidents. "Break-glass mode"
+narrows verification (see `verify-before-complete`) — it does **not**
+license drive-by edits.
+
+Allowed during break-glass:
+
+- The **smallest** change that stops the bleeding — one file, one
+  method, one guard — preferred over any refactor.
+- A fast revert to a known-good commit, even if it undoes unrelated
+  improvements shipped in the same PR.
+
+Not allowed, even in break-glass:
+
+- "While I'm in there" cleanups, reformatting, or dependency bumps.
+- Expanding the fix to neighboring modules without evidence they are
+  part of the incident.
+- Merging the hotfix with pending refactors from another branch.
+
+After the incident, open a **follow-up PR** for any scope that was
+intentionally deferred and reference the break-glass commit in its
+description.
+
+## Bounded remediation carve-out
+
+The default stands: no drive-by edits, no opportunistic refactors. The one
+bounded exception — a **small, task-aligned security/correctness fix in code
+the current task already touches** — is governed by `active-remediation`
+(mechanics: [`active-remediation-mechanics`](active-remediation-mechanics.md)).
+It is permitted inline **only** when ALL hold: same request path / module,
+≤ ~10 changed lines in one production file (plus its test file), no
+public-API / response-shape change, no dependency bump or migration, and its
+verification (e.g. the negative test) ships in the same commit. Anything
+outside those five conditions is **not** this carve-out — it is note + ask
+per `active-remediation`. This never licenses reformatting, renames,
+dependency bumps, or version upgrades (a syntax-idiom modernization is
+allowed only under `active-remediation`'s version-gated,
+behavior-preserving clause; a dependency/version bump stays ask-only). The
+sole case that may interrupt is a **live cross-user/tenant data exposure**
+(`broken-access-control`) — fix-now-if-small, else stop and surface; never
+defer it silently.
+
+## Shared-path repair — scope, and when NOT to fire
+
+The rule's pre-fix clause is the obligation; this is its boundary.
+
+**Does not fire** when nothing else reaches the code (a leaf function, a
+one-caller private), or when the shared repair is genuinely larger than the
+five-condition bounded carve-out above permits. In the second case it is
+note + ask per [`active-remediation`](active-remediation-mechanics.md) — never
+a silent per-caller patch presented as the minimal diff, and never a
+shared-path rewrite smuggled in under a bug-fix label.
+
+**Enumerate with the tool, not from memory.** The caller set is a grep or an
+index query, and its COUNT is what makes "repairing once is smaller" a claim
+rather than an intuition — two callers and a three-line patch each is not
+obviously worse than one shared change, while nine callers is.
+
+## Before writing the diff — the three questions
+
+Migrated verbatim from the rule (road-to-trigger-delivered-rule-bodies A1),
+which had to pay for the pre-fix root-cause clause out of its own token
+ceiling. Nothing was cut; this is where it now lives.
+
+Ask yourself, in order:
+
+1. **What is the minimum set of files that must change for the stated task?**
+   If your answer includes files with no causal link to the task, stop and
+   remove them.
+2. **What is the minimum number of lines per file?** If you are editing a
+   method, edit the method — not the surrounding class.
+3. **Is any of this a refactor?** If yes, it belongs in its own commit or
+   PR, clearly labeled as a refactor, with no behavior change.
+
+## Red flags in your own diff — reject them
+
+Files the task never mentioned · import reordering, whitespace, or comments
+outside the edited region · "small improvements" to neighboring methods ·
+test-only mixed with behavior changes in one commit · renames outside the
+task scope · dependency bumps "because it was close to the cache".
+
+## When in doubt
+
+Ask. A minimal diff plus one follow-up is cheaper than a sprawling diff the
+reviewer has to untangle.
+
+## See also
+
+- `minimal-safe-diff` (rule) — Iron Law, the rule, the pre-fix shared-path repair clause, own-orphan cleanup. The pre-diff checklist, the red-flag catalog and the when-in-doubt line live HERE since A1.
+- [`active-remediation-mechanics`](active-remediation-mechanics.md) — the fix-now / note+ask / follow-up-PR ladder detail.
+
+## Re-derive the requirement, don't inherit the shape
+
+```
+A REPAIR INHERITS THE SHAPE OF WHAT IT REPAIRS UNLESS YOU ASK OTHERWISE.
+STATE THE REQUIREMENT IN ONE LINE, THEN ASK WHETHER THE CURRENT FORM
+*CAN* EXPRESS IT. A FORM THAT CANNOT IS NOT A PARAMETER BUG.
+```
+
+Applies to a downstream repair — clearing a red, or fixing what your own diff
+broke — where the smallest change is a different VALUE and the form is
+unexamined.
+
+### Why this is a guideline section and not a rule clause
+
+It was drafted as a clause in `minimal-safe-diff` on 2026-09-07 and moved here
+the same day, on the gate's own evidence rather than on preference.
+`check_preamble_payload_budget` measured the clause at +460 delivered tokens,
+then +271, then +180 after two rounds of cutting — a floor set by the Iron-Law
+block itself. That payload is re-written on EVERY subagent spawn, and the rule it
+would have lived in is `type: auto`: it fires on prompt keywords, not on tool
+output, so a red test nobody mentioned never loads it.
+
+Certain per-spawn cost against an activation path that misses the case the clause
+was written for is a bad trade, and the deterministic half does not depend on it
+— see § Honest limit below. The rule already routes here
+(`routes_to: guideline:agent-infra/minimal-safe-diff-mechanics`), which is the
+same reachability every other migrated body in this repository has.
+
+### Worked failure — 2026-09-07
+
+A change emptied `<repo>/.claude/skills` of skills and left ~49 flat-command
+wrappers behind. `resolveSkillsRoot` tried two workspace-relative roots and took
+the first non-empty one, so it resolved the wrappers, and the skill ranker ranked
+49 command wrappers instead of 299 skills.
+
+The repair chosen was to swap the ORDER of the two roots. The requirement was
+*"rank every catalogue the session can reach"*, which **no ordering of a
+first-hit loop can satisfy** — and the host-global root the whole task was about
+appeared in neither position. The evidence had been measured an hour earlier and
+sat in the same session's own notes: `~/.claude/skills` 307, `.claude/skills` 49,
+`src/skills` 299.
+
+Two things made it easy to miss, and both are the shape of the trap rather than
+this instance of it:
+
+- **The docstring framed the question.** It read *"First existing catalogue root
+  … `.claude/skills` before `src/skills` because a CONSUMER install carries the
+  former"* — i.e. it asked *which root wins*, and that question was answered. A
+  docstring records what the code decided; it never records whether that was the
+  decision to make.
+- **The same docstring contained the premise of the correct answer.** If
+  consumers carry their own skills *and* the package ships skills, both must be
+  read. The sentence was read, used to justify an ordering, and its consequence
+  was not drawn.
+
+### Why the pre-work rules do not cover it
+
+[`improve-before-implement`](../../rules/improve-before-implement.md) does
+not activate for bug fixes ("the problem is already defined") and
+[`invite-challenge`](../../rules/invite-challenge.md) excludes "evidenced
+bug fixes". Both exclusions are right for the case they were written for and
+wrong for a downstream repair, which presents as a defined problem while its
+definition came from the broken code.
+
+### Honest limit
+
+The rule is `type: auto`, so it fires on prompt keywords and not on tool output:
+a red test nobody prompted about does not load it. The clause is the
+model-carried half. The deterministic half is a comparison of the two lists that
+diverged — `tests/contracts/catalogue_layer_parity.test.ts`, which reds when a
+directory the delivery side treats as an artifact source is not a root the reader
+reads, and which was measured to catch this exact defect on the pre-change tree.

package/dist/agent-src/guidelines/agent-infra/missing-tool-handling.md

@@ -0,0 +1,66 @@
+# Missing Tool Handling
+
+> CLI tool needed for the task is not installed — ask before working around it; do NOT install silently
+
+_Origin: migrated from `src/rules/missing-tool-handling.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+When a CLI tool is needed to solve the task cleanly and is **not installed**
+(`command not found`, `which X` empty, missing from `$PATH`), **STOP and ask**
+before working around it or installing it.
+
+## The rule
+
+- **Never install silently.** Installing is an action that changes the user's
+  system — it requires explicit permission (see `scope-control`).
+- **Never silently work around** a missing tool with a brittle substitute
+  (awk-regex for YAML, `grep` for JSON, string splicing) when a proper tool
+  is the standard answer for the job. The workaround hides the real
+  dependency and makes the decision invisible to the user.
+- **Ask with numbered options** (see `user-interaction`). State which tool,
+  why it's the best fit, the install command, and the workaround cost.
+
+## When it applies
+
+- Any shell command fails with `command not found` for a tool the task
+  genuinely needs (yq, jq, rtk, gh, docker, mkcert, terraform, …).
+- A skill or spike requires a tool that is the idiomatic answer but is
+  absent locally.
+- You are about to substitute a verbose script for a single tool invocation
+  because the tool isn't there.
+
+## When it does NOT apply
+
+- The tool is a nice-to-have and a clean substitute already exists in the
+  repo (e.g. `jq` present → no need for `yq` just for JSON).
+- The tool is explicitly forbidden by project policy (check
+  `scope-control` and tool-allowlists first).
+- The missing artefact is a library dependency — those go through
+  `composer require`, `npm install`, `pip install` per the package-manager
+  rules, still with explicit permission.
+
+## How to ask
+
+```
+> `yq` is not installed. It's the cleanest way to parse the ticket YAML
+> in the Bash prototype — the alternative is a JSON conversion step,
+> which adds ~20ms to every run.
+>
+> 1. Install via `brew install yq` (recommended — one-time, stays on PATH)
+> 2. Use JSON conversion fallback — slower but no install needed
+> 3. Drop YAML — convert fixtures to JSON, use `jq` only
+> 4. Skip this path — I propose a different approach
+```
+
+After the user picks: if **install**, wait for confirmation that it is
+done (or run the documented install command only if the user explicitly
+authorises it in this turn). If **workaround**, record the decision in
+the artefact (comment or ADR) so the cost is visible.
+
+## Capture the learning
+
+If the same tool keeps coming up as missing across multiple tasks, flag
+it in the project's setup docs or `.agent-settings.yml` prerequisites.
+Don't make every session re-discover the gap.
+
+See also: `scope-control` · `ask-when-uncertain` · `user-interaction` ·
+`tool-safety`.

package/dist/agent-src/guidelines/agent-infra/model-recommendation.md

@@ -0,0 +1,101 @@
+# Model Recommendation
+
+> Surface-aware model_tier routing — when to auto-switch, when to suggest, how to phrase the one-question suggestion
+
+_Origin: migrated from `src/rules/model-recommendation.md` per the P4 pattern of `road-to-kernel-and-router.md`._
+
+**Iron Law.** When a skill or command carries a `model_tier` (a vendor-neutral
+capability band), route the turn to **that agent's best model in that band** —
+automatically where the surface supports a per-turn override, as a single
+suggestion where it does not. Never recommend another vendor's model. Never
+double-ask, never front-load the question.
+
+## Source of truth — the capability tier
+
+Each skill/command declares `model_tier: lite | medium | high | inherit`
+(ADR-035) — a band, not a model. `inherit` = "no opinion, keep the session
+model". The task→tier heuristics live in
+`contexts/model-recommendations.md` — cite them, don't restate. The **only**
+tier→model mapping the package maintains is the Claude generator's
+(`high→opus`, `medium→sonnet`, `lite→haiku`); every other agent resolves the
+band to its own line-up.
+
+## Surface-aware behaviour
+
+Read `model.auto_switch` from `.agent-settings.yml` (`auto | suggest | off`,
+default `suggest`) live, then:
+
+- **Claude Code / Desktop (native per-turn `model:` override).** When
+  `auto_switch: auto`, the rendered skill's native `model:` (mapped from the
+  tier by the generator) already performed the switch — **do NOT ask, do NOT
+  re-state it**. When `suggest`, no native key was emitted; surface the
+  one-question suggestion below using the skill's `model_tier`.
+- **Any surface without a per-turn override (Augment, etc.).** When
+  `auto_switch` is `auto` or `suggest`, surface **one** suggestion (per
+  `ask-when-uncertain`) naming the **tier** — the user maps it to their
+  agent's model. Do NOT name a specific vendor model; the package keeps no
+  per-vendor table. Never auto-act where the surface can't.
+- **`auto_switch: off`.** Inert. No native key, no suggestion.
+
+## Orchestrator → subagent model routing
+
+The main loop can't self-switch its own model — the user owns the session model
+(`/model`). But the orchestrator **does** own the model of every subagent it
+spawns (the `Agent` tool's `model:`, a Workflow agent's `model:`, or
+`subagents.implementer_model`). Right-sizing those is where tier-routing actually
+bites for token cost.
+
+**Judge per subtask — never blanket-downgrade.** The orchestrator assesses each
+delegated subtask's difficulty and matches the model to it. A cheap model on a
+hard subtask costs *more* (rework, wrong output) than it saves; a strong model on
+a trivial sweep burns budget for nothing. The goal is the **optimal**
+distribution, not the cheapest one.
+
+- **Downgrade** mechanical / narrow / well-specified work — code or file search,
+  broad reading, boilerplate or format-conversion edits, deterministic
+  transforms — to `medium` (or `lite` when genuinely trivial).
+- **Keep the strong (`high`) model** for ambiguous, cross-cutting, design,
+  security, or correctness-critical subtasks, and for any work needing deep
+  reasoning. When difficulty is unclear, keep the stronger model.
+- **Keep `high` for the orchestrator's own synthesis, judgment, and final
+  verification** of subagent output — the same reason the judge runs one tier up
+  (`subagent-configuration.md`).
+
+**Default is not free.** `subagents.implementer_model` defaults to the *session*
+model, so subagents inherit the session tier (e.g. `high`) unless the orchestrator
+sets `model:` per call or the user sets a baseline. Delegation alone does not lower
+cost — the explicit per-task model choice does.
+
+## The suggestion (non-auto surfaces)
+
+Ask **last** — after context / domain clarification, never before the task is
+understood. Name the tier, not a vendor model:
+
+```
+> 💡 This skill recommends the **{model_tier}** capability tier for {task type}.
+>
+> 1. Switch to your **{model_tier}**-tier model — continue
+> 2. Stay on the current model
+```
+
+(Tier → your model: `high` = your strongest reasoning model, `medium` = your
+balanced daily model, `lite` = your fastest/cheapest.) On "switched" → accept,
+continue. On "stay" → accept, no pushback; don't re-ask until the task type
+changes.
+
+## Preserved flows (re-pointed at tiers)
+
+- **Downgrade reminder.** After a `high`-tier task (architecture / refactoring /
+  root-cause found), remind the user that the implementation phase is cheaper on
+  the **`medium`** tier — using the next skill's `model_tier` as the target.
+  Full flow: `contexts/model-recommendations.md` § Downgrade reminder.
+- **Gemini warning.** Detected model `gemini` → surface the not-recommended
+  warning once, then accept the user's choice. Flow:
+  `contexts/model-recommendations.md` § Gemini warning.
+
+## No standing-selection fight
+
+A user's explicit `/model` choice is standing; the native per-turn `model:`
+override reverts on the next prompt, so the rule never overrides a standing
+selection beyond the current turn. With the default `suggest`, no native key is
+emitted at all — the user's `/model` is never silently overridden.

package/dist/agent-src/guidelines/agent-infra/naming.md

@@ -0,0 +1,69 @@
+---
+description: "Naming conventions for skills, rules, commands, and guidelines"
+source: package
+---
+
+# Naming Conventions
+
+## Principles
+
+1. **Name = purpose.** Reading the name tells you what it does.
+2. **No collisions across layers.** A rule and skill must NOT share the same name.
+3. **Consistent prefixes** for related items: `project-analysis-*`, `laravel-*`, `feature-*`.
+4. **Consistent suffixes** for similar roles: `-management`, `-integration`, `-config`.
+5. **No bare nouns** — `jira` says nothing, `jira-integration` says everything.
+
+## Naming patterns by layer
+
+### Skills
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{domain}-{activity}` | Activity/workflow skills | `code-refactoring`, `sql-writing`, `pest-testing` |
+| `{domain}-{role}` | Domain-specific expertise | `php-coder`, `fe-design`, `api-design` |
+| `{domain}-{management}` | CRUD/lifecycle management | `module-management`, `override-management` |
+| `{domain}-{integration}` | External tool integration | `jira-integration`, `sentry-integration` |
+| `{domain}-{config}` | Configuration/setup | `copilot-config`, `devcontainer` |
+| `{framework}-{feature}` | Framework-specific | `laravel-validation`, `laravel-mail` |
+| `{scope}-analysis-{variant}` | Analysis skills | `project-analysis-laravel`, `performance-analysis` |
+| `{action}-{target}` | Action commands as skills | `bug-analyzer`, `skill-reviewer` |
+
+### Rules
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{concern}` | Behavioral constraint | `scope-control`, `ask-when-uncertain` |
+| `{domain}-{concern}` | Domain-specific rule | `php-coding`, `e2e-testing` |
+| `{action}-{target}` | Trigger-based auto rule | `invite-challenge`, `downstream-changes` |
+
+### Commands
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{verb}-{target}` | Action commands | `create-pr`, `fix-ci`, `commit` |
+| `{target}-{verb}` | Target-first grouping | `roadmap-create` (legacy atomic; current cluster form is `/roadmap:create` and `/roadmap:process-step|phase|full`) |
+| `{scope}-{action}` | Scoped actions | `optimize-agents`, `review-changes` |
+
+### Guidelines
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{language}/{topic}.md` | Language-specific | `php/general.md`, `php/naming.md` |
+| `{domain}/{topic}.md` | Domain-specific | `agent-infra/naming.md`, `e2e/locators.md` |
+
+## Anti-patterns
+
+| Don't | Why | Do instead |
+|---|---|---|
+| Single bare noun (`jira`, `sql`) | Ambiguous — could be anything | `jira-integration`, `sql-writing` |
+| Same name across layers | Routing confusion | `agent-docs` (rule) + `agent-docs-writing` (skill) |
+| `-er` suffix for skills | Skills are not agents | `-ing` or `-management` |
+| `{dir}/{dir}.md` for guidelines | Redundant | `php/general.md` not `php/php.md` |
+| Abbreviations alone (`rtk`, `mcp`) | Meaningless to new users | `rtk-output-filtering`, `mcp` (OK if well-known) |
+| Inconsistent prefix grouping | Hard to discover related items | All Laravel skills start with `laravel-*` |
+
+## Linter enforcement
+
+The skill linter (`scripts/skill_linter.ts`) warns on:
+- **Bare-noun names** — single word without qualifier (e.g., `jira` instead of `jira-integration`)
+- **Layer collisions** — same name used for both a rule and a skill

package/dist/agent-src/guidelines/agent-infra/notes-horizon-mechanics.md

@@ -0,0 +1,90 @@
+# Notes-first reasoning — horizon and reopening mechanics
+
+Migrated out of [`notes-first-reasoning`](../../rules/notes-first-reasoning.md)
+on 2026-09-08. That rule is delivered on **every subagent spawn**, so its body is
+paid per spawn; this material is reference read on demand. Nothing was dropped —
+the four passages below are the rule's own text, verbatim, and the rule keeps
+both Iron Laws and points here.
+
+Same reason, and the same remedy, as the 2026-08-29 drain run recorded for
+`source-confidentiality`: the addition had no room under the per-spawn ceiling,
+and raising that ceiling is the config-weakening move this repository refuses.
+
+### Why reasoning stays out of the reply, and what grounds the notes file
+
+Reasoning dumped into the user-facing answer is both noise and a
+`reasoning_extraction` refusal risk (see `rdp-gate`). Keep it in the notes file.
+
+The notes file is grounded in the documented cross-run lessons memory
+(consolidated via [`memory-consolidation`](../../skills/memory-consolidation/SKILL.md));
+the rule's in-task sections are a local derivation for within-task scope. The
+gate itself reads settings + task-signal + host self-assessment.
+
+### The two section fields, in full
+
+The rule lists the sections and no count. That is deliberate: the structure
+carries the enumeration, so there is no "write N hypotheses" instruction to
+follow — a run records what the work actually surfaced, and an empty section is
+a fact about the work rather than a gap in the notes.
+
+`## Predictions` carries **chosen form** · prediction · confidence · result ·
+lesson — the calibration loop: hypothesis → prediction → reality →
+calibration. The form is named first because a prediction with no subject
+cannot be contradicted: when the observation comes back, "the prediction
+missed" has to point at *what* it was a prediction about, or nothing reopens.
+
+`## Decisions` escalates to
+[`decision-record`](../../skills/decision-record/SKILL.md)/ADR when the
+decision is cross-task or architectural — litmus: would a dev on a different
+component next month need this context? And `next-commitment` is the boundary
+this choice authorises work up to, not the plan for it: choosing a form is not
+permission to execute a twelve-step plan on it without re-reading the position.
+
+### The horizon — which boundaries count
+
+The boundary is the nearest of these that the plan actually reaches: a **test
+result** · a **type or schema inspection** · a **compile** · a **runtime probe**
+· a **call-site inventory** · a **dry run** · a **browser observation** · a
+**dependency-contract read**. The set is enumerable, which is the whole point —
+"the work up to the nearest of those" is decidable from the plan, and `next
+justified commitment` as prose degrades to *"implement solution"*, which is the
+starting point wearing a label.
+
+### Width scales with reversibility, never with task size
+
+| The action is… | The horizon runs to… |
+|---|---|
+| a reversible local edit | a whole implementation slice — stopping at the first boundary costs more than it saves |
+| stateful or cross-layer | the next boundary from the list above |
+| irreversible or a public contract | **before** the irreversible step, unless direct evidence already covers it |
+
+### The look-ahead ladder is a CEILING, never a quota
+
+Three to five moves is the *maximum*, and only for a forcing, irreversible or
+externally observable line. Stateful or cross-layer gets two to three. A quiet
+reversible line gets **one, deliberately** — and no artifact anywhere requires a
+minimum depth. Always-three-to-five across all variants is 1024 leaves at four
+branches and depth five, which buys nothing and costs the run its budget.
+
+### Reopening — the two consequences
+
+A reopen driven by ritual rather than by contradicting evidence is ceremony, and
+an uncapped reopen is a loop with better manners. Two consequences:
+
+- **A rejection whose premise is falsified is not a rejection.** A candidate
+  killed by an assumption that later turns out false is *un-evaluated*, not
+  dead — it returns to the set. That is what makes a stated `killed-if`
+  condition worth carrying: without it, "we ruled that out" is unfalsifiable.
+- **The first failure reads the candidate list before the retry**, where one
+  exists — see [`autonomy-mechanics`](../../contexts/execution/autonomy-mechanics.md)
+  § Retry-budget escalation ladder. Where none exists the ladder is unchanged.
+  This adds a branch; it does not move the N=3 budget.
+
+## See also
+
+- [`notes-first-reasoning`](../../rules/notes-first-reasoning.md) — the
+  rule this material was paid for in, and which keeps both Iron Laws.
+- [`rdp-gate`](../../contexts/execution/rdp-gate.md) — the
+  engagement gate that decides whether the notes discipline runs at all.
+- [`decision-record`](../../skills/decision-record/SKILL.md) — where a
+  cross-task or architectural decision escalates to.