@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/commands/review/changes.md

@@ -383,7 +383,7 @@ Per `verbosity.routine_confirmations` (default `false`):
 - [`verify-repair-loop`](../../skills/verify-repair-loop/SKILL.md) — opt-in test-verdict-gated iterate-to-green loop (step 6 hand-off); judge confirms after the numeric gate
 - [`/judge`](judge.md) — standalone judge, no review-changes dispatch
 - [`code-review`](../../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
-- [`role-contracts`](../../../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+- [`role-contracts`](../../guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
 
 ## References
 

package/dist/agent-src/commands/review/routing.md

@@ -120,7 +120,7 @@ After the block, ask:
 
 - [`review-routing`](../../skills/review-routing/SKILL.md) — the resolver
 - [`reviewer-awareness`](../../rules/reviewer-awareness.md) — the rule that routes here: paths and risk over seniority, primary + secondary on medium/high
-- [`review-routing-data-format`](../../../docs/guidelines/agent-infra/review-routing-data-format.md)
+- [`review-routing-data-format`](../../guidelines/agent-infra/review-routing-data-format.md)
   — YAML schemas
 - [`create-pr-description`](../../skills/create-pr:description-only/SKILL.md) —
   consumes the routing block

package/dist/agent-src/commands/roadmap/create.md

@@ -162,7 +162,7 @@ Show the complete roadmap to the user and ask (in their language) if anything sh
 
 Unless the roadmap will be saved as `status: draft`, add a
 `## Risk Register` per
-[`plan-review-gates § 1`](../../../docs/contracts/plan-review-gates.md):
+[`plan-review-gates § 1`](../../docs/contracts/plan-review-gates.md):
 read the C→R1 handoff state from step 0 if present (resolved branches
 seed the risk list — never re-ask them), identify the highest product and
 implementation risks, rank descending, write a mitigation per row, and

package/dist/agent-src/commands/roadmap/materialize.md

@@ -39,7 +39,7 @@ roadmap, writes one ticket per materialisable step into
 (acyclic dependency graph + empty `linear_state`), writes
 `<!-- ticket: T-NNN -->` markers back into the roadmap, and regenerates
 `agents/tickets/_registry.yml`. Format contract:
-[`ticket-bundle-format`](../../../../docs/contracts/ticket-bundle-format.md).
+[`ticket-bundle-format`](../../docs/contracts/ticket-bundle-format.md).
 
 ### 3. Gate on buildability
 
@@ -69,4 +69,4 @@ pastes a ticket into Linear/Jira (or creates it via MCP), or runs a per-ticket b
 - **Do NOT auto-create tracker issues** — paste/MCP is a separate user-invoked step (ADR-102, no API export).
 - **Do NOT commit or push.**
 - Bundle is the source of truth; the tracker is a projection
-  ([`ticket-bundle-format`](../../../../docs/contracts/ticket-bundle-format.md)).
+  ([`ticket-bundle-format`](../../docs/contracts/ticket-bundle-format.md)).

package/dist/agent-src/commands/roadmap/next.md

@@ -122,7 +122,7 @@ For each candidate read its frontmatter, its open-step count, and every
 3. **A date that must pass.**
 4. **A kernel-rule edit** — [`scope-control`](../../rules/scope-control.md)
    demands its own PR plus a ≥24 h soak, so it cannot close in this run
-   (kernel list: [`kernel-membership`](../../../docs/contracts/kernel-membership.md)).
+   (kernel list: [`kernel-membership`](../../docs/contracts/kernel-membership.md)).
 5. **Phases gated on a spike verdict** that may return FINDING.
 
 Also check the **family concurrency cap** (`lint_roadmap_family_cap`) —
@@ -148,6 +148,14 @@ ONE THAT MOVES MORE CHECKBOXES. PICKING BY CHECKBOX COUNT IS THE
 GOODHART MOVE THIS PACKAGE'S OWN DISCIPLINE FORBIDS.
 ```
 
+**An owner-recorded precedence outranks the severity read.** Where an accepted ADR
+states that a named roadmap or set is worked first, that record is the ranking and
+this section does not re-derive one — the owner has already made the call the
+council would otherwise settle. Precedence is not a bypass: a precedent roadmap
+still passes every disqualifier in step 2, and a disqualified precedent roadmap is
+skipped with its disqualifier named like any other. A `proposed` record carries no
+precedence.
+
 - **Exactly one survivor, or one that dominates** → take it, state the
   one-line reason inline, proceed. Do not ask
   ([`no-cheap-questions`](../../rules/no-cheap-questions.md)).

package/dist/agent-src/commands/roadmap/process-full.md

@@ -87,7 +87,7 @@ with the **scope delta below**.
 `--all` changes **cardinality, not lifecycle**: the same single-roadmap loop,
 iterated over the whole active estate. It is a flag rather than a
 `/roadmap:process-all` command because
-[`command-clusters`](../../../../../docs/contracts/command-clusters.md) says
+[`command-clusters`](../../docs/contracts/command-clusters.md) says
 sibling variants become a flag, and a drain is a count of the thing this
 command already does.
 
@@ -320,7 +320,7 @@ is therefore remediation work rather than a blocker.
 | a halt | one of the five conditions fired | **no** — the halt is reported | `exhausted` when a declared budget ran out; `stagnated` when the same failure signature repeated with budget left |
 
 **The closing report names the terminal state by word**, from
-[`terminal-states`](../../../../src/agent-src/contexts/execution/terminal-states.md).
+[`terminal-states`](../../contexts/execution/terminal-states.md).
 The reason is the failure that vocabulary exists to stop: a run that stopped at
 its iteration cap and one that finished both leave the roadmap looking the same,
 because the checkbox glyphs cannot express `exhausted`, `stagnated` or

package/dist/agent-src/commands/security-audit-config.md

@@ -35,7 +35,7 @@ suite's own `lint_agent_security` self-audit gate.
 
 (omit `--root` to audit the current repo). The script reuses the Phase-1
 detection library under the false-positive containment convention
-([`security-lint-containment`](../../docs/guidelines/agent-infra/security-lint-containment.md)),
+([`security-lint-containment`](../guidelines/agent-infra/security-lint-containment.md)),
 so doc/example files do not tank the score. It scans instruction files
 (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`,
 `.clinerules`, `.windsurfrules`), MCP configs (`.mcp.json`, `.cursor/mcp.json`,
@@ -63,7 +63,7 @@ Output is **decision support**, not a gate — detection is probabilistic
 (guardrails are evadable). Recommend the fix per finding (move a secret to
 `${env:VAR}`, pin an MCP server, remove a `bypassPermissions` flag, strip
 hidden Unicode), but never rewrite the consumer's config without confirmation
-(per [`scope-control`](../../../src/rules/scope-control.md)).
+(per [`scope-control`](../rules/scope-control.md)).
 
 ## Output format
 
@@ -81,5 +81,5 @@ Overall: B (84/100)
 ## See also
 
 - [`lint_agent_security`](../../../src/scripts/lint_agent_security.ts) — the self-audit (our own corpus) sibling.
-- [`untrusted-input-defense`](../../../src/rules/untrusted-input-defense.md), [`lethal-trifecta-guard`](../../../src/rules/lethal-trifecta-guard.md) — the always-on prevention rules.
+- [`untrusted-input-defense`](../rules/untrusted-input-defense.md), [`lethal-trifecta-guard`](../rules/lethal-trifecta-guard.md) — the always-on prevention rules.
 - [`/threat-model`](../threat-model/command.md), [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) — deep-pass dispatch.

package/dist/agent-src/commands/skill/preview.md

@@ -22,7 +22,7 @@ packs:
 Renders a skill's **declared intent** — its `## Steps`, execution type, handler,
 `allowed_tools`, and any file/command targets named in its body — so you can
 decide whether to run it. Read-only, no network, no execution. Implements the
-[`skill-dry-run`](../../../docs/contracts/skill-dry-run.md) contract.
+[`skill-dry-run`](../../docs/contracts/skill-dry-run.md) contract.
 
 ## Prerequisites
 

package/dist/agent-src/commands/skills/discover.md

@@ -22,7 +22,7 @@ packs:
 Surfaces a short, explained skill shortlist for a role. Reuses existing local
 signals only — the skill catalog frontmatter, the role's `skills.yml`
 shortlist, and (when present and not opted out) the local-analytics JSONL.
-Implements the [`skill-discovery`](../../../docs/contracts/skill-discovery.md)
+Implements the [`skill-discovery`](../../docs/contracts/skill-discovery.md)
 contract. Local-only, read-only, no network.
 
 ## Prerequisites

package/dist/agent-src/commands/sync/agent-settings.md

@@ -25,7 +25,7 @@ Reconciles `.agent-settings.yml` with the shipped template
 (`config/agent-settings.template.yml`) and the selected cost-profile
 preset (`config/profiles/{profile}.ini`). Applies the section-aware
 merge rules documented in
-[`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md):
+[`layered-settings`](../../guidelines/agent-infra/layered-settings.md):
 
 - Template section order wins — keys reorder to match.
 - Existing user scalar values are preserved.
@@ -141,6 +141,6 @@ is a local-agent concern.
 - [`scripts/sync_agent_settings.ts`](../../../../scripts/sync_agent_settings.ts) — the helper
 - [`config/agent-settings.template.yml`](../../../../config/agent-settings.template.yml) — canonical template
 - [`config/profiles/`](../../../../config/profiles/) — profile presets
-- [`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
+- [`layered-settings`](../../guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
 - [`scripts/install.ts`](../../../../scripts/install.ts) — first-install path; this command handles the update path
 - [`/sync-gitignore`](sync-gitignore.md) — sibling command for the `.gitignore` block

package/dist/agent-src/commands/sync/gitignore/fix.md

@@ -189,5 +189,5 @@ If the check fails, offer to re-sync the block with the current template:
   ignored-but-tracked detection (Phase 5.2)
 - [`scripts/check_gitignore_freshness.ts`](../../../../src/scripts/check_gitignore_freshness.ts) —
   manifest vs block coverage check (Phase 3.4)
-- [`docs/contracts/agents-layout.md`](../../../../../docs/contracts/agents-layout.md) —
+- [`docs/contracts/agents-layout.md`](../../../docs/contracts/agents-layout.md) —
   full classification contract for `agents/` entries

package/dist/agent-src/commands/tests/create.md

@@ -109,4 +109,4 @@ funnel per changed behavior — enumerate first, write second:
 
 ## See also
 
-- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#tester) — Tester mode output contract (Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps)
+- [`role-contracts`](../../guidelines/agent-infra/role-contracts.md#tester) — Tester mode output contract (Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps)

package/dist/agent-src/commands/tests/e2e-heal.md

@@ -32,7 +32,7 @@ packs:
 > 2. Fix a specific test file — which one?
 > 3. Fix tests that failed in CI — provide the CI run URL or error output
 
-- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../../guidelines/e2e/playwright.md`
 
 ### 2. Run failing tests
 

package/dist/agent-src/commands/tests/e2e-plan.md

@@ -32,7 +32,7 @@ packs:
 > 2. Which feature area? (e.g., "checkout flow", "user settings", or "all visible flows")
 > 3. Is there an existing seed/setup file? (e.g., `tests/e2e/fixtures/auth.ts`)
 
-- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../../guidelines/e2e/playwright.md`
 - Check for existing test plans in `specs/` or `tests/e2e/specs/`.
 
 ### 2. Explore the application

package/dist/agent-src/contexts/authority/kernel-rule-edits.md

@@ -19,13 +19,16 @@ weight, a trigger that swallows a sibling rule's domain) surfaces in
 real interactions before the second edit lands and confounds the
 diagnosis.
 
+A kernel-rule PR also carries a ratification artifact
+([`ratification-artifact`](../../docs/contracts/ratification-artifact.md)),
+gated by `check_kernel_edit_ratified` — an ADDITION to this soak, never a
+replacement, until blocker `ratification-platform-anchor` is decided.
+
 ## Trigger
 
 A PR is a "kernel-rule edit" iff it modifies any file in `src/rules/`
 that is in the locked kernel set
-(see [`docs/contracts/kernel-membership.md`](../../../docs/contracts/kernel-membership.md)).
-(Until 2026-07-31 this named the pre-ADR-051 authoring tree, which no
-longer exists — so the trigger could not match a live file.)
+(see [`docs/contracts/kernel-membership.md`](../../docs/contracts/kernel-membership.md)).
 
 The CI guard (Phase 4.2 of the always-budget-relief roadmap) fails
 any PR that touches **> 1** kernel rule in the same diff. Override is
@@ -59,6 +62,3 @@ diff instead of a silent 10× cost event.
 ## Source
 
 - Roadmap Phase 4: always-budget-relief roadmap § Phase 4 (transient — see `agents/roadmaps/archive/`).
-- Lesson: PR #36 (2026-05-04) condensed the rollout schedule under
-  autonomous mandate; the slow-rollout note was deferred until this
-  ADR pass.

package/dist/agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -4,7 +4,7 @@ Lookup table for the `slash-command-routing-policy` rule. Lists the
 locked clusters and their sub-commands so the rule itself can stay at
 its current LOC while still reflecting the full surface. Source of
 truth for the cluster names is
-[`docs/contracts/command-clusters.md`](../../../../../docs/contracts/command-clusters.md);
+[`docs/contracts/command-clusters.md`](../../../docs/contracts/command-clusters.md);
 this file mirrors that contract for runtime lookup. Linter:
 `scripts/check_cluster_patterns.ts` (verifies dispatcher shape).
 
@@ -15,7 +15,6 @@ this file mirrors that contract for runtime lookup. Linter:
 | `/fix` | 1 | `ci` · `pr-comments` · `portability` · `refs` · `seeder` | `/fix-ci` · `/fix-pr-comments` · `/fix-portability` · `/fix-references` · `/fix-seeder` |
 | `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills`                                                   |
 | `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap`                                                                 |
-| `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only`                                 |
 | `/agents` | 2 | `init` · `optimize` · `audit` | `/copilot-agents-init` · merger of `/optimize-agents-md` + `/copilot-agents-optimize` · `/optimize-agents` (folder ops moved to `/optimize:agents-dir`) |
 | `/memory` | 2 | `add` · `load` · `promote` · `propose` | `/memory-add` · `/memory-full` · `/memory-promote` · `/propose-memory`                                                                          |
 | `/roadmap` | 2 | `create` · `process-step` · `process-phase` · `process-full` | `/roadmap-create` · `/roadmap-process` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope)                |

package/dist/agent-src/contexts/communication/rules-auto/think-before-action-mechanics.md

@@ -43,7 +43,7 @@ behavior. Cannot → read more.
 ## Consult memory before editing
 
 Invariants live in the memory layer; architectural rationale lives in ADRs.
-Via [`memory-access`](../../../../../docs/guidelines/agent-infra/memory-access.md),
+Via [`memory-access`](../../../guidelines/agent-infra/memory-access.md),
 call `retrieve(types=["domain-invariants"], keys=<touched paths>, limit=3)` —
 a matching `domain-invariant` is a hard constraint. For *why* the current
 shape exists, check the ADR index `docs/decisions/INDEX.md`. Cite the `id` /
@@ -129,4 +129,4 @@ success cannot be checked is a clarification trigger, not an execution
 trigger (route to `ask-when-uncertain`).
 
 Wrong/right demos:
-[`simplicity-and-goal-demos`](../../../../../../docs/guidelines/agent-infra/simplicity-and-goal-demos.md).
+[`simplicity-and-goal-demos`](../../../guidelines/agent-infra/simplicity-and-goal-demos.md).

package/dist/agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md

@@ -108,6 +108,39 @@ The step-2 grep is not a second probe of the same file for the same fact — it
 returns information step 1 did not have, so it is one operation with step 3, per
 the enumerated-set carve-out.
 
+### Where the 800 came from, and what would falsify it
+
+Migrated out of `token-efficiency.md` on 2026-09-09 to fund that rule's
+provided-artifact carve-out — a named substitution rather than a deletion, per
+the council verdict on `blocker: standing-payload-headroom`.
+
+The number is a **stated default, not a measured optimum** — said plainly rather
+than implying a derivation it does not have. *Revisit-if:* a run records a
+probe-then-slice that cost more than the full read would have, or the host's
+ranged-read primitive changes its own default. Either falsifies the number, not
+the obligation.
+
+### The provided-artifact carve-out
+
+A handed-over design artifact is not a large file to be probed; it is the spec,
+and reading it whole is the work. A bundle of several thousand lines across
+markup, CSS and tokens is ordinary, so the agent that reads it properly is the
+one the size gate and the read-loop detector both punish, while the agent that
+skims it produces the fidelity failure `design-fidelity` exists to prevent.
+
+Two obligations, and they compose rather than cancel:
+
+1. **The size gate does not fire on it.** Read the artifact whole.
+2. **The read is declared** — [`context-hygiene`](../../../guidelines/agent-infra/context-hygiene-mechanics.md)
+   § the declared-protocol cap — with its goal, its expected read count and the
+   output shape, before the reading starts. Declaring raises the read-only abort
+   from 5 turns to 8; it never suspends it, and exceeding the declared count by
+   more than 2 is still the violation.
+
+What this does NOT do: it does not exempt an *undeclared* read loop, and it does
+not apply to a file that merely happens to be large. The discriminator is the
+handover, not the size.
+
 ### Exceptions
 
 - Small output (< 30 lines) — read directly.
@@ -187,6 +220,47 @@ Over 40,268 real Bash calls from one maintainer's transcripts:
   measurement artifact. It is not: that shape cannot be written as an
   allowlist pattern at all, so it shrinks only by not being written.
 
+### Re-measured 2026-09-10, with a shipped probe
+
+The figures above were computed once by hand. `autonomy_friction_traffic`
+(`./scripts-run src/scripts/autonomy_friction_traffic --store <dir> --limit 40`)
+recomputes them from a transcript store and shares the live detectors — and the
+metacharacter class is `category_a`'s own exported constant — so those cannot
+drift; the bucket ORDER restates the classifier by hand and is pinned by a test.
+Over **7,569 distinct** Bash calls in 39 transcripts (deduplicated by tool-use
+id, measuring session excluded):
+
+- **1.7 %** (126) are category A. Of the 7,443 uncovered calls, **7,143** are
+  disqualified by a shell metacharacter before their argv is read, 21 name a
+  consequence operation, and **279** get as far as the head list. Widening the
+  head list therefore cannot move this number — the shape can. The 279 is an
+  upper bound: a directory flag whose value escapes the tree lands there too.
+- **73.8 %** (5,585) carry the chain class; `cd` heads 3,573 of the uncovered
+  calls — a different denominator from the shape classes, which count every call.
+- **4.0 %** (306) write a file through the shell: 216 `cat >`, 66 `sed -i`,
+  16 a `python3 -c` opening a path for writing, 7 `perl -i`, 1 `tee`. A **floor**
+  — the rules are a positive list of five commands, so `echo >`, `jq >` and `cp`
+  are silent.
+
+**Two host facts that decide what any of this can buy**, both read out of the
+host's own permission documentation on 2026-09-10. First, `permissions.allow`
+does **not** bypass the auto-mode classifier — they are layers, so an allow
+entry cannot make a prompt go away on its own. Second, "don't ask again" saves a
+permanent rule for a read-only command and only a session-lifetime one for a
+write-shaped one. The second is why the write class earns its own line: no
+amount of confirming makes the next `sed -i` cheaper. The adjacent question —
+whether a hook's `permissionDecision: allow` suppresses the classifier — was
+looked for in the same pass and **not found documented**.
+
+**And a correction to the table below.** `git -C /repo status` is the right
+substitution for the host's matcher, but it is **not** category A: `category_a`
+refuses a global option whose value is absolute, and every cross-worktree
+invocation in a multi-worktree checkout writes an absolute one. So unwinding a
+chain removes the metacharacter without buying the allow. The row stays because
+it is still the cheaper shape; what changes is the claim that it lands inside
+category A. Pinned in `tests/scripts/autonomy_friction_traffic.test.ts` §
+"the recommended substitution is only covered with a RELATIVE path".
+
 ### The substitutions
 
 | Instead of | Write |
@@ -195,6 +269,9 @@ Over 40,268 real Bash calls from one maintainer's transcripts:
 | `V=$(git rev-parse HEAD); echo $V` | two calls, the second using the printed value |
 | `mkdir -p x && cp a x/` | two calls in the same block |
 | `cd sub && <cmd>` | the directory flag the tool already has (`-C`, `--cwd`, `--prefix`) |
+| `sed -i '' -e 's/a/b/' f` | the **Edit** tool — a write-shaped Bash grant expires with the session |
+| `cat > f <<'EOF' … EOF` | the **Write** tool for a new file, **Edit** for a change to an existing one |
+| `python3 -c "open(p,'w').write(s)"` | the same two tools; keep the interpreter for reads and computation |
 
 A loop that genuinely cannot be expressed without the shell stays a loop —
 prefer a script file over an inline `for` when it recurs.
@@ -211,7 +288,17 @@ first time a session chains work. It is ON by default with
 because the fact this one carries is a property of the host's permission
 matcher and holds in every consumer.
 
-**It never blocks, and it fires once.** So it changes what the agent knows,
+Since 2026-09-10 it carries a second shape class — a Bash command that fills a
+file (`sed -i`, `cat > f`, `tee f`, `perl -i`, a `python3 -c` opening a path for
+writing) — and the latch is per class, so a session sees at most one line per
+class instead of one line for whichever mistake came first. A redirect that
+names no file being filled (`2>&1`, `> /dev/null`) is still not a write and is
+still not flagged. The two classes read different views: the chain rules see
+quoted spans and heredocs removed, the write rules see quoted spans removed and
+heredoc BODIES removed with the command line kept — a heredoc marker and the
+redirect sharing its line cannot be separated otherwise.
+
+**It never blocks, and each class fires once.** So it changes what the agent knows,
 not what the agent may do: compliance stays model-carried, and the concern's
 tests establish detector behavior, not adherence. On a host with no
 `pre_tool_use` slot nothing fires at all and the rule is model-carried end to

package/dist/agent-src/contexts/communication/rules-auto/user-interaction-mechanics.md

@@ -189,7 +189,7 @@ rendered as a bulleted list of reasons — declines are short prose (one or
 two sentences), because a bulleted refusal reads as a checklist to argue
 against rather than a direct answer.
 
-Full example set: [`asking-and-brevity-examples § Bullet floor`](../../../../../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#bullet-floor).
+Full example set: [`asking-and-brevity-examples § Bullet floor`](../../../guidelines/agent-infra/asking-and-brevity-examples.md#bullet-floor).
 
 ## Summaries
 

package/dist/agent-src/contexts/contracts/frugality-charter.md

@@ -56,4 +56,4 @@ kernel chars. The pointers below replace them.
 
 ## Decidable carve-out predicates
 
-Predicates with one-sentence tests live in [`docs/guidelines/agent-infra/carve-out-predicates.md`](../../../docs/guidelines/agent-infra/carve-out-predicates.md). Default-terse applies unless a predicate's test is yes/no decidable from the artifact alone.
+Predicates with one-sentence tests live in [`docs/guidelines/agent-infra/carve-out-predicates.md`](../../guidelines/agent-infra/carve-out-predicates.md). Default-terse applies unless a predicate's test is yes/no decidable from the artifact alone.

package/dist/agent-src/contexts/execution/auto-dispatch-classification.md

@@ -129,7 +129,7 @@ tier `inferSliceTier` (§ below) already raised.
 Deny-by-default — a direction not listed here is denied. Direction rules,
 payload allow/deny lists, the report-only boundary, the no-recursion clause and
 the human egress gate:
-[`cross-vendor-worker-direction`](../../../../docs/contracts/cross-vendor-worker-direction.md).
+[`cross-vendor-worker-direction`](../../docs/contracts/cross-vendor-worker-direction.md).
 Role pairs, never vendor names — `classifyLadder` carries no vendor identity
 ([`subagent-routing`](subagent-routing.md) § Why vendor-neutral).
 

package/dist/agent-src/contexts/execution/auto-orchestration-activation.md

@@ -20,7 +20,7 @@ set, and what the host can physically do.
 | `subagents.downshift` | `true` | Route delegable sub-tasks to the lowest-capable tier (Phase 2). |
 | `subagents.quota_arbitrage` | `true` | Prefer a separate-quota-pool model where the host manifest allows it (Phase 2 bonus). |
 | `subagents.model_map` | `{}` | Optional per-tier model override for downshift routing. |
-| `emergency.orchestration_halt` | `false` | The ONE audited incident switch — see [`settings-classes.md`](../../../../docs/contracts/settings-classes.md) § "The one exception". NOT an activation gate: on-by-default, ceremony-free to arm, requires a non-empty `orchestration_halt_justification` to disarm. |
+| `emergency.orchestration_halt` | `false` | The ONE audited incident switch — see [`settings-classes.md`](../../docs/contracts/settings-classes.md) § "The one exception". NOT an activation gate: on-by-default, ceremony-free to arm, requires a non-empty `orchestration_halt_justification` to disarm. |
 
 ## Activation decision
 

package/dist/agent-src/contexts/execution/autonomy-mechanics.md

@@ -13,7 +13,7 @@ relevant. Detection logic lives in [`autonomy-detection.md`](autonomy-detection.
 | `auto` (default) | Same as `off` by default. Flips to `on` for the rest of the conversation as soon as the user expresses the intent "stop asking, just work". See [detection logic](autonomy-detection.md) — match by **intent**, not exact string. The flip never lifts the Hard Floor. |
 
 The value is read once on the first turn (per
-[`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
+[`layered-settings`](../../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
 and cached. Missing key → treat as `auto` (fail-closed — same behavior
 as the shipped template default; absence of a key never grants the most
 permissive mode). The one exception is the explicit cloud carve-out
@@ -193,6 +193,18 @@ decision. Engage per [`rdp-gate`](rdp-gate.md).
 The suite states three retry numbers; they are **stages of one escalation
 ladder on the same failing target**, not competing budgets:
 
+0. **Attempt 1 fails → read the candidate list, if one exists, BEFORE retry 1.**
+   Where the run recorded a candidate set for this work
+   ([`notes-first-reasoning`](../../rules/notes-first-reasoning.md)
+   § Reopening), the first failure reads it first: a failure is evidence about
+   the CHOSEN FORM, and retrying the same approach spends the budget without
+   ever reaching the second-best candidate — which is how the mechanism that
+   discovers a form was wrong never routes back to the form. Where no candidate
+   list exists the ladder is unchanged and stage 1 runs immediately.
+   **This adds a branch; it does not move the budget.** Reading the list is not
+   an attempt and is not counted, and the reopen is capped at one per candidate:
+   the second contradiction on the same candidate continues down this ladder
+   rather than reopening again.
 1. **Attempt 1 fails → up to 2 retries of the same approach**
    ([`think-before-action`](../../rules/think-before-action.md) "MAX 2
    RETRIES PER APPROACH") — the soft, agent-side stage: rethink between

package/dist/agent-src/contexts/execution/cheap-question-mechanics.md

@@ -4,7 +4,7 @@ Catalog material for [`no-cheap-questions`](../../rules/no-cheap-questions.md)
 
 ## Cheap classes — full catalog
 
-Sequencing · format-only · commit / CI / test asks · fenced re-ask · Iron-Law option · context-derived · dominant option · re-ask after decline · paternalistic (IL 3) · continuation under mandate (IL 4) · prereq-for-authorized-action (IL 5) · destination-already-stated (IL 6) · self-cleaning artefact follow-up · disguised commit ask (preview-as-bait) · commit-chunking-strategy (one-or-multiple / which-first / how-to-split). Extended examples: [`asking-and-brevity-examples`](../../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+Sequencing · format-only · commit / CI / test asks · fenced re-ask · Iron-Law option · context-derived · dominant option · re-ask after decline · paternalistic (IL 3) · continuation under mandate (IL 4) · prereq-for-authorized-action (IL 5) · destination-already-stated (IL 6) · self-cleaning artefact follow-up · disguised commit ask (preview-as-bait) · commit-chunking-strategy (one-or-multiple / which-first / how-to-split). Extended examples: [`asking-and-brevity-examples`](../../guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
 ## Iron Law 3 — No Paternalistic State-Assuming Options
 

package/dist/agent-src/contexts/execution/contract-decision-sheet.md

@@ -24,7 +24,7 @@ sheet-eligible when **all** hold:
 - it is answerable **before** the run starts — its answer does not depend on
   something the run itself produces;
 - its decision class is `trivial`, `low_impact`, or `medium_impact`
-  ([`ai-council-config`](../../../docs/contracts/ai-council-config.md)
+  ([`ai-council-config`](../../docs/contracts/ai-council-config.md)
   § decision_resolution);
 - a **conservative default** exists and can be stated in one line.
 
@@ -68,7 +68,7 @@ cost: each override is a decision the default did not carry.
 
 The contradiction was resolved on **the sheet's** side deliberately, and the
 asymmetry is durable rather than incidental: `user-interaction` is one of the
-locked nine ([`kernel-membership § 4`](../../../docs/contracts/kernel-membership.md)),
+locked nine ([`kernel-membership § 4`](../../docs/contracts/kernel-membership.md)),
 so amending its clause is an owner-reserved edit that `block-kernel-rule-writes`
 refuses at tool-call time, while the answer SHAPE is this page's own. When a
 page and a kernel rule contradict each other, the page is both the cheaper half
@@ -110,6 +110,6 @@ by whichever mechanism happened to hit them first.
 
 - [`roadmap-execution-contract`](roadmap-execution-contract.md) — the screen this renders inside; its single Accept is the authorization.
 - [`roadmap-process-loop § 3`](roadmap-process-loop.md) — the pre-scan that produces the rows, and the § 3a ladder that decides whether a contract is derived at all.
-- [`ai-council-config`](../../../docs/contracts/ai-council-config.md) § decision_resolution — the class table and the locked-class Iron Law.
+- [`ai-council-config`](../../docs/contracts/ai-council-config.md) § decision_resolution — the class table and the locked-class Iron Law.
 - [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one question per turn; one sheet answered by one keystroke is one question.
 - [`user-interaction`](../../rules/user-interaction.md) — the numbered-options shape and the single recommendation line.

package/dist/agent-src/contexts/execution/mandated-lines.md

@@ -175,6 +175,6 @@ counter and is the first thing to look at before adding a sixth line.
 
 ## See also
 
-- [`docs/contracts/settings-classes.md`](../../../docs/contracts/settings-classes.md) — a sibling contract in the same shape: prose that a gate reads.
+- [`docs/contracts/settings-classes.md`](../../docs/contracts/settings-classes.md) — a sibling contract in the same shape: prose that a gate reads.
 - [`verify-before-complete`](../../rules/verify-before-complete.md) — the evidence gate the pre-send sweep runs beside.
 - `src/scripts/lint_mandated_lines.ts` — the deterministic half.

package/dist/agent-src/contexts/execution/non-interactive-contract.md

@@ -127,6 +127,6 @@ A misbehaving heuristic is disabled by config, not by reverting 6.1.0.
 
 ## See also
 
-- [`command-clusters`](../../../docs/contracts/command-clusters.md) — the locked cluster/sub-command set.
+- [`command-clusters`](../../docs/contracts/command-clusters.md) — the locked cluster/sub-command set.
 - [`user-interaction`](../../rules/user-interaction.md) — numbered-options + recommendation rules the interactive path obeys.
 - [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) — the Hard Floor destructive sub-commands still answer to.

package/dist/agent-src/contexts/execution/orchestration-telemetry.md

@@ -243,7 +243,7 @@ removes or tightens THE TRIGGER, and the removal PR cites the numbers.
 
 ## Related
 
-- [`audit-log-v1`](../../../../docs/contracts/audit-log-v1.md) — the frozen
+- [`audit-log-v1`](../../docs/contracts/audit-log-v1.md) — the frozen
   JSONL contract this object rides on; the `orchestration` field is optional
   and additive, schema_version unchanged.
 - [`host-capability-manifest`](host-capability-manifest.md) — the manifest that

package/dist/agent-src/contexts/execution/plan-confidence-gate.md

@@ -7,7 +7,7 @@ the [`roadmap-writing`](../../skills/roadmap-writing/SKILL.md) skill,
 [`/feature:roadmap`](../../commands/feature/roadmap.md) — each of which links
 here instead of restating the gate. Machine-checked grammars (the C→R1 state
 schema, marker lines) are owned by
-[`docs/contracts/plan-review-gates.md`](../../../docs/contracts/plan-review-gates.md);
+[`docs/contracts/plan-review-gates.md`](../../docs/contracts/plan-review-gates.md);
 this context carries the agent-side procedure.
 
 ## Activation
@@ -22,7 +22,7 @@ equivalents drop the gate immediately
 (`DE: "einfach schreiben", "Interview überspringen" · EN: "just write it", "skip the interview"`).
 A bypass is **counted**, never punished: append a `gate_c_bypass` event to
 `agents/evidence/metrics/gate-metrics.jsonl` (see
-[`plan-review-gates § metrics`](../../../docs/contracts/plan-review-gates.md))
+[`plan-review-gates § metrics`](../../docs/contracts/plan-review-gates.md))
 so gate erosion stays visible.
 
 ## When it fires — and when NOT
@@ -127,7 +127,7 @@ On completing the gate (either path that ran an interview), write
 `agents/runtime/state/gate-c-<plan-slug>.json` so the R1 risk pass never
 re-asks resolved branches — the user is never interviewed twice for one
 plan. Schema (canonical:
-[`plan-review-gates § C→R1 handoff`](../../../docs/contracts/plan-review-gates.md)):
+[`plan-review-gates § C→R1 handoff`](../../docs/contracts/plan-review-gates.md)):
 resolved branches, plan hash, timestamp, and a mandatory `transcript_ref`
 (path + content hash of the interview transcript artifact).
 
@@ -136,7 +136,7 @@ resolved branches, plan hash, timestamp, and a mandatory `transcript_ref`
 lint and no hook entry behind it, and the state file is gitignored so CI never
 sees it — a human reading the diff is what catches a violation (stated
 `enforced_by: none` in
-[`plan-review-gates § 4.1`](../../../docs/contracts/plan-review-gates.md)).
+[`plan-review-gates § 4.1`](../../docs/contracts/plan-review-gates.md)).
 The rule defends against silent agent shortcuts, not against the local human
 (who holds the settings escape hatch anyway).
 Confident-path runs (no interview) write no state file; R1 then runs its
@@ -155,7 +155,7 @@ risk pass fresh.
 
 - [`/challenge-me vision`](../../commands/challenge-me/vision.md) — the four
   95%-conditions and the interview this gate routes into.
-- [`plan-review-gates`](../../../docs/contracts/plan-review-gates.md) — machine
+- [`plan-review-gates`](../../docs/contracts/plan-review-gates.md) — machine
   grammars: C→R1 state schema, Risk Register, completion review.
 - [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
   one-question-per-turn floor the degrade protocol runs under.

package/dist/agent-src/contexts/execution/roadmap-execution-contract.md

@@ -191,7 +191,7 @@ bodies.
 Identity semantics, revision semantics, the three senses of "gate" and the
 `[AC:<id>]` convention — including the verified fact that nothing parses
 `verify:` lines structurally today — are in
-[`guideline:agent-infra/traceability-field-mechanics`](../../../../docs/guidelines/agent-infra/traceability-field-mechanics.md).
+[`guideline:agent-infra/traceability-field-mechanics`](../../guidelines/agent-infra/traceability-field-mechanics.md).
 They are not optional reading: a slug grammar does not imply a namespace, and
 `evidence_refs` are syntactically safe tokens rather than verified evidence.
 

package/dist/agent-src/contexts/execution/subagent-modes-detail.md

@@ -114,7 +114,7 @@ Cross-wing or cross-skill chain executed across isolated git
 worktrees — each handoff in the chain runs in its own worktree, so
 the workspace state of one step never leaks into the next. Operationalizes
 the worktree boundary clause in
-[`docs/contracts/cross-wing-handoff.md`](../../../../docs/contracts/cross-wing-handoff.md)
+[`docs/contracts/cross-wing-handoff.md`](../../docs/contracts/cross-wing-handoff.md)
 § 3. State-machine layer only — worktree creation/destruction lives
 in [`using-git-worktrees`](../../skills/using-git-worktrees/SKILL.md) and
 [`finishing-a-development-branch`](../../skills/finishing-a-development-branch/SKILL.md).

package/dist/agent-src/contexts/execution/subagent-routing.md

@@ -49,7 +49,7 @@ THE SAME MINUS THE QUOTA WIN.
    for a removed category — and because `session_tier` sits non-null in 0 of 327
    records, leaving the saving unmeasurable in principle. Migration record and
    the union revisit-if:
-   [`budget-routing` contract](../../../../docs/contracts/budget-routing.md).
+   [`budget-routing` contract](../../docs/contracts/budget-routing.md).
    **Tier resolution therefore ends at step 3.** What survives of the module is
    `TIER_ORDER` and `readCooldowns`, read by `routing:doctor` as a diagnostic —
    monitoring, not routing, and note that nothing writes the cool-down file any
@@ -177,7 +177,7 @@ This resolves the direction; it does not license downshifting as a target. The
 cold start is paid per leg regardless of tier, which is precisely what the
 non-escalation floor above bounds. Analogous downgrade/cache coupling on the
 council side: see
-[`docs/contracts/ai-council-config.md`](../../../../docs/contracts/ai-council-config.md)
+[`docs/contracts/ai-council-config.md`](../../docs/contracts/ai-council-config.md)
 § `model_downgrade` for the analogous downgrade/cache coupling this suite
 already ships on the council side.
 

package/dist/agent-src/contexts/execution/subagent-spawn-contract.md

@@ -22,7 +22,7 @@ task without re-inventing any taxonomy.
 
 | Element | Source |
 |---|---|
-| `role_mode` | The six contracts in [`role-contracts`](../../../docs/guidelines/agent-infra/role-contracts.md). A review sub-task → `reviewer`; a planning sub-task → `planner`; default → null (no contract). |
+| `role_mode` | The six contracts in [`role-contracts`](../../guidelines/agent-infra/role-contracts.md). A review sub-task → `reviewer`; a planning sub-task → `planner`; default → null (no contract). |
 | `profile` | The active profile (`profile.id` in `.agent-settings.yml`); inherited from the session unless the sub-task is a different domain. |
 | `personas` | The persona ids already cited in the task's skill frontmatter (review lenses). Capped at 2 (`MAX_PERSONAS`). |
 | `knowledge_refs` | A SMALL set of knowledge references (ingest ids / file paths) relevant to the sub-task. Capped at 5 (`MAX_KNOWLEDGE_REFS`). |