@event4u/agent-config 8.7.0 → 8.9.0

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

@@ -232,6 +232,18 @@ Write the pick to frontmatter as `execution.mode:`
   and expensive as a mid-run ambiguity halt; pre-existing `[~]` items
   guarantee the archival gate interrupts the run.
   `lint_roadmap_complexity` warns on the same patterns as a backstop.
+- **Human-gate scan (ALL picks):** scan drafted steps for human-gate
+  patterns (`user verifies/reviews/approves`, `manually check`,
+  `sign-off`, `wait for approval`, `ask the user`, "Review / Sign-off"
+  phases). Human checkpoints default to **zero** (template rule 22) —
+  rewrite each hit as agent-verifiable check (command, targeted test)
+  **before saving**, or promote to structured `## Blockers` entry:
+  **human gate** only when only a human can decide/authorize
+  (Hard-Floor authorization, billable spend, contested decision);
+  **external dependency** becomes a blocker whose `Resolved when:`
+  names an agent-checkable status probe — never a human gate. Do not
+  author safety floors as steps — they fire at run time on their own.
+  `lint_roadmap_complexity` warns on the same patterns as a backstop.
 
 ### 11. Hand back — HARD STOP, never auto-offer execution
 

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

@@ -57,7 +57,11 @@ with the **scope delta below**.
   (`false` / missing) the pipeline never runs locally; remote CI is
   the gate. On red → stop, surface, do **not** silently roll into
   the next phase. Under `mode: phase-checkpoints`, additionally emit
-  the compact status + continue prompt at every boundary; under
+  a compact status LINE at every boundary — but under `process-full`
+  this is a NON-BLOCKING status, NOT a stop-and-wait: the run continues
+  to the next phase immediately. `phase-checkpoints` narrows to a
+  stop-and-wait only under `/roadmap:process-phase`, never here (a
+  process-full invocation overrides the mode's boundary-wait). Under
   `autonomous`, boundaries are silent (quality pipeline aside).
 - **Final archival:** when the roadmap is fully closed, run the
   archival check from
@@ -66,10 +70,32 @@ with the **scope delta below**.
 ## Iron Law — Full is Full
 
 ```
-/roadmap:process-full PROCESSES EVERY OPEN STEP IN THE FILE.
-PHASE-INTERNAL "(DEFERRED)" / "(OPTIONAL)" / "GATED ON PHASE X"
-NOTES DO NOT NARROW THE WORKING SET. ONLY THE FIVE HALT CONDITIONS
-STOP THE RUN.
+/roadmap:process-full IS LAW: IT PROCESSES EVERY OPEN STEP IN THE FILE,
+TO COMPLETION, ACROSS EVERY PHASE. ONLY THE FIVE HALT CONDITIONS STOP IT.
+PHASE-INTERNAL "(DEFERRED)" / "(OPTIONAL)" / "GATED ON PHASE X" NOTES DO
+NOT NARROW THE WORKING SET. A PHASE BOUNDARY IS NOT A STOP.
+```
+
+The **five — and only five — halt conditions** (exhaustive; nothing else
+stops the run):
+
+1. **Hard-Floor** trigger ([`non-destructive-by-default`](../../rules/non-destructive-by-default.md)).
+2. **Council-off + genuine ambiguity** (only outside an accepted contract with council available).
+3. **Security-sensitive** surface reached.
+4. **Scope-out-of-roadmap** work discovered.
+5. **Test / quality red** that cannot be cleared within the N=3 budget.
+
+```
+FORBIDDEN NON-HALT REASONS — NEVER STOP THE RUN FOR ANY OF THESE:
+  · "running low on context / token budget"
+  · "quality would degrade / deserves a fresh focused run later"
+  · "avoid a PR pile-up" / "let the open PRs merge first"
+  · "this phase is large / touches a deep subsystem"
+  · "phase-checkpoints mode, so I'll checkpoint and wait"
+  · any agent-invented caution not in the five halt conditions above.
+INVENTING A HALT REASON IS A VIOLATION OF THE COMMAND AND THE USER'S WILL.
+IF CONTEXT RUNS OUT MID-RUN, KEEP LANDING COMPLETE STEPS UNTIL IT DOES —
+NEVER ANNOUNCE A BOUNDARY-STOP BY CHOICE.
 ```
 
 Phase-internal `(deferred)` / `(optional)` / `gated on Phase N` tags are

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`](../../../../../../docs/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` /
@@ -96,3 +96,32 @@ context only — does NOT mean the user's message is about that file.
 - Treat the open file as relevant only when the user's message
   explicitly references it (e.g. "fix this file", "what does this
   do?", "update the open file").
+
+## Goal-driven execution — vague ask → verifiable goal
+
+Before executing a multi-step task, transform it into criteria a tool can
+check. Strong criteria let the loop run independently; weak criteria ("make it
+work") guarantee rework.
+
+| Vague ask | Verifiable goal |
+|---|---|
+| "Add validation" | Write tests for the invalid inputs, then make them pass |
+| "Fix the bug" | Write a test that reproduces it (fails), then make it pass |
+| "Refactor X" | Tests green before AND after; diff shows no behavior change |
+| "Make it faster" | Name the metric + target (p95 < 200ms); measure before/after |
+| "Clean this up" | Clarification trigger — no checkable success state exists yet |
+
+For multi-step tasks, state the plan with a verify per step:
+
+```
+1. [step] → verify: [check]
+2. [step] → verify: [check]
+3. [step] → verify: [check]
+```
+
+A step without a `verify:` is not a step — it is an assumption. A task whose
+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).

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

@@ -12,7 +12,7 @@ whether dispatch is physically possible on the host).
 | Key | Default | Purpose |
 |---|---|---|
 | `subagents.enabled` | `true` | Global master switch. `false` = the whole layer is off — the canonical kill-switch. No auto-dispatch, no routing, everything runs in-session. |
-| `subagents.auto` | `ask` | Auto-dispatch mode: `off` \| `ask` \| `on`. |
+| `subagents.auto` | `on` | Auto-dispatch mode: `off` \| `ask` \| `on`. Default `on` on subagent-capable hosts (flipped from `ask` 2026-07-09, ADR-117), `off` elsewhere. |
 | `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. |

package/dist/agent-src/contexts/execution/orchestration-benchmark-gate.md

@@ -1,9 +1,19 @@
-# Orchestration Benchmark & Default-Flip Gate (Phase 6)
-
-The falsification gate the whole auto-orchestration roadmap is built around.
-Reaching the user's "default `on`" is a **measured milestone**, not an
-assumption: the shipped default for `subagents.auto` flips toward `on` only
-when a real benchmark proves a net win at held quality.
+# Orchestration Benchmark & Demotion Gate (Phase 6 → telemetry-demotion)
+
+Originally the falsification gate the auto-orchestration roadmap was built
+around: shipped default for `subagents.auto` would flip toward `on` only on a
+benchmark proving a net win at held quality.
+
+**As of 2026-07-09 the shipped default IS `on`** on subagent-capable hosts
+(ADR-117; [`orchestration-default-flip-verdict`](../../../../agents/settings/contexts/orchestration-default-flip-verdict.md)
+§ 2026-07-09). Flipped on a **bounded-downside re-evaluation**, not a passed
+benchmark: rigorous paired bench:ab not producible here (no runtime executing
+model `Task`/`Agent` calls), win-validation deadlocked (telemetry needs `on`,
+`on` gated on telemetry). Re-eval broke the deadlock — downside of `on` is
+structurally small (delegable slices cost-routed to cheapest tier,
+classification fires only on real structural signals, every return verified) →
+`on` gathers realized telemetry responsibly. This gate now governs
+**demotion**: measured regression flips default back to `ask`.
 
 ## Measurement — pin the method
 
@@ -30,18 +40,20 @@ HONEST-NULL EXIT: no win, or quality regressed → KEEP the conservative default
 
 `gateVerdict()` encodes pass = `net_win && quality_held`.
 
-## Default flip — one line, host-gated
+## Default state + demotion — host-gated
 
-On a **passing** gate, the shipped default for `subagents.auto` becomes `on`
-**only** on hosts whose capability manifest reports `subagent_spawn: true`
-(`off` elsewhere). `resolveShippedDefault()` encodes this. The flip itself is a
-one-line edit to the `subagents.auto` default in
-`src/config/agent-settings.template.yml` — no code change, host-gated by the
-manifest at runtime.
+Shipped default for `subagents.auto` is `on` on hosts whose manifest reports
+`subagent_spawn: true` (`off` elsewhere) — set directly in
+`src/config/agent-settings.template.yml`. `resolveShippedDefault()` remains the
+host-gated resolver, now serving **demotion**: fed a `fail` verdict from
+accumulated real-world orchestration telemetry, resolves back to `ask`
+(conservative). A `pass` keeps `on`. Demotion path is a one-line edit,
+host-gated by the manifest at runtime.
 
-Until the gate passes, the shipped default stays `ask` (conservative). This is
-the reconciliation of the user's "default on" goal with the council's
-"prove-first": `on` is the destination, reached by evidence, not assumed.
+The 2026-07-09 flip reconciles the user's "default on" goal with the council's
+"prove-first": rather than wait on a benchmark that cannot be produced here,
+`on` ships because its downside is bounded and reversible, and realized
+telemetry is now free to accrue and drive demotion if it regresses.
 
 ## Reproducibility
 

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

@@ -23,6 +23,8 @@ v1 forward-compat rule on unknown fields).
   "task_class": null,
   "tier_chosen": null,
   "tier_source": null,
+  "dispatch_tokens": null,
+  "session_tier": null,
   "escalated_from": null,
   "verify_result_by_tier": null
 }
@@ -46,8 +48,10 @@ v1 forward-compat rule on unknown fields).
 | `tier_source` | enum \| null | Where `tier_chosen` came from: `static` (frontmatter/category pin) · `inferred` (deterministic per-slice inference) · `inherit` (session tier — no downshift decision). Lets the evidence gate score inferred routing separately from static pinning. |
 | `escalated_from` | string \| null | When the slice re-dispatched after a verification failure: tier of the FAILED attempt (e.g. `lite` when a lite return failed verify and the slice re-ran on `medium`). `null` = no escalation. |
 | `verify_result_by_tier` | object \| null | Map tier → verification result per attempt of this slice (e.g. `{"lite":"fail","medium":"pass"}`). Values: `pass` \| `fail` \| `skipped`. Feeds the per-tier verify-pass-rate tripwire. Enums only, no verdict bodies. |
+| `dispatch_tokens` | int \| null | **Cost-% extension.** Absolute tokens the dispatched slice consumed (measured subagent usage). Feeds the MODELED cost-% in `orchestration_savings_report`, which needs an absolute base the token-count delta lacks. `null` = not recorded. Counts only. |
+| `session_tier` | string \| null | **Cost-% extension.** The orchestrator's OWN tier — the baseline the downshift cost-% measures `tier_chosen` against (a `high`→`lite` downshift is a rate win the token count can't see). `null` = not recorded. |
 
-All five routing fields are additive and optional — a line without them is
+These routing + cost fields are additive and optional — a line without them is
 still a valid orchestration line; readers ignore unknown fields per the v1
 forward-compat rule.
 
@@ -74,10 +78,22 @@ audit-log-v1 path; `YYYY-MM` = current UTC month). The line is a standard
 audit-log-v1 object with `input_kind: "orchestration"` and an `orchestration`
 sub-object carrying this shape.
 
-**No hook or daemon required.** The agent writes directly via its file-write
-tool — same mechanism as any other agent-written artifact. No-runtime-compatible
-capture path (decided 2026-06-30, maintainer decision; see
-`road-to-subagent-value-realization.md § Council notes`).
+**No hook or daemon required.** The agent writes the line directly —
+no-runtime-compatible capture path (decided 2026-06-30, maintainer decision; see
+`road-to-subagent-value-realization.md § Council notes`). Do NOT hand-author the
+JSON: run the recorder, which validates + builds a conformant line from the
+counts you already have:
+
+```bash
+./scripts-run src/scripts/orchestration_record --spawn-count <n> \
+  --token-delta <±n> --provenance measured|estimated \
+  [--tier-chosen lite|medium|high] [--tier-source static|inferred|inherit] \
+  [--task-class <id>] [--tiers a,b] [--dispatch-outcome DONE|BLOCKED|…]
+```
+
+A capture **hook** is the wrong tool: the PostToolUse payload carries no subagent
+token usage (only the orchestrator sees it) and a hook reverses the 2026-06-30
+no-hook decision. Reader: `src/scripts/orchestration_savings_report.ts`.
 
 **`token_delta` sourcing priority:**
 1. Host-reported: read `usage.output_tokens` (and `usage.input_tokens` if
@@ -87,6 +103,21 @@ capture path (decided 2026-06-30, maintainer decision; see
    response length (chars / 4 ≈ tokens). Set `token_delta_provenance:
    "estimated"`. Lossy; measured always preferred.
 
+## Savings report
+
+Aggregate accumulated telemetry into a token-savings report:
+
+```bash
+./scripts-run src/scripts/orchestration_savings_report [--dir <path>] [--format text|json]
+```
+
+Sums `token_delta` across dispatches (negative = net saved); splits by
+provenance (measured vs estimated), `tier_chosen`, `task_class`. Reports
+**ABSOLUTE net tokens saved, never a percentage**: telemetry records net delta,
+not the absolute in-session baseline → "% of session saved" not derivable. A
+percentage needs an additive absolute-baseline field (deferred follow-up).
+Reader: [`src/scripts/_lib/orchestration_savings.ts`](../../../../src/scripts/_lib/orchestration_savings.ts).
+
 ## Related
 
 - [`audit-log-v1`](../../../../docs/contracts/audit-log-v1.md) — the frozen

package/dist/agent-src/contexts/execution/roadmap-process-loop.md

@@ -28,6 +28,25 @@ roadmaps with open work that is blocked-for-later — parked, not active).
   surface alternatives in the pre-run summary.
 - None active → tell the user; suggest [`/roadmap:create`](../../commands/roadmap/create.md).
 
+### Live merge-state before any "in-flight / merged / handled" claim
+
+Selection reasoning that **excludes** a roadmap — or a pre-run summary,
+decision, or user-facing message that **describes** one — as *in-flight*,
+*handled by an open PR*, *already merged*, or *not yet merged* → verify **live
+at claim time** (`gh pr view <n> --json state,mergedAt` / `gh pr list --search
+"<slug>"`). Never infer merge state from:
+
+- **dashboard open-count** — lags: a completed roadmap archives in the
+  **merging** PR, so it can read "open" on `main` while its PR is already
+  merged, or read "open" seconds before a merge you never re-checked;
+- **session memory** ("opened a PR for this earlier") or an **earlier fetch** —
+  a merge can land between fetch and message.
+
+Stale merge-state claim ships an unnecessary message about work already done —
+the failure this prevents. The [`direct-answers`](../../rules/direct-answers.md)
+Iron-Law-2 live-state rule (git/PR state never from memory), applied to
+roadmap selection.
+
 ## 2. Pre-run summary — gate or inline note
 
 Read `roadmap.skip_pre_run_gate` from `.agent-settings.yml` (default
@@ -259,6 +278,24 @@ drafting, council enablement), not safety.
 
 On halt: stop, surface state, do **not** auto-fix outside the failing step.
 
+### Forbidden non-halt reasons — agent-invented cautions
+
+Halt list above is exhaustive. Never stop a `process-full` (or any wrapper) run
+for an invented reason not on it. NOT halt conditions — stopping for them
+violates the command + user's will:
+
+- "low context / token budget" — keep landing complete steps until context
+  actually runs out; never announce a boundary-stop by choice.
+- "quality would degrade / deserves a fresh focused run later"
+- "avoid a PR pile-up" / "let open PRs merge first"
+- "this phase is large / deep subsystem"
+- "phase-checkpoints, so I'll checkpoint and wait" — under `process-full` a
+  phase boundary emits a non-blocking status line and the run continues; the
+  stop-and-wait reading applies only to `process-phase`.
+
+Genuine inability to continue = one of the five real halt conditions fired —
+surface THAT, not a manufactured caution.
+
 ### Non-halt — gating notes, "optional" tags
 
 The following are **authoring annotations**, never halt conditions. Do

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

@@ -0,0 +1,34 @@
+# Subagent Topologies — per-mode communication shape
+
+Descriptive, not enforced. Documents the **expected agent-to-agent
+communication topology** for each [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
+mode so consumers can predict latency, failure modes, and where consensus
+is required. Cited from
+an internal findings note (local-only) <!-- council-ref-allowed: ADR decision trace for topology anti-drift defaults -->
+row 7 (the external runtime's `hierarchical, 6–8 agents, raft consensus` anti-drift
+default).
+
+| Mode | Topology | Anti-drift default | Notes |
+|---|---|---|---|
+| do-and-judge | `hierarchical` | 1 implementer · 1 judge · session-orchestrated | Two-node hub-and-spoke; orchestrator owns the loop. |
+| do-and-judge-two-stage | `hierarchical` | 1 implementer · 2 sequential judges | Stages are serialized; spec-judge gates quality-judge. |
+| do-in-steps | `ring` | N steps · 1 judge between each | Step N output → judge → step N+1 input; cycle on revise. |
+| do-in-parallel | `star` | 6–8 implementers · 1 judge · session-hub | Capped by `subagents.max_parallel`; judge runs once on union. |
+| do-competitively | `mesh` | 2–4 implementers · 1 judge | Implementers do not see each other; judge sees all candidates. |
+| judge-with-debate | `hierarchical-mesh` | 2 judges · 1 meta-judge | Judges debate (mesh edge); meta-judge reconciles (hierarchical). |
+| do-in-worktrees | `adaptive` | per-step topology of the underlying mode | Each worktree picks its own shape; chain is hierarchical. |
+
+**Anti-drift default** (the external runtime convention, descriptive only):
+`hierarchical, 6–8 agents, raft consensus`. Consumers free to
+override per orchestration — the table is the **starting point**,
+not a constraint. Topology is metadata for capacity planning, not
+runtime-enforced.
+
+**Glossary:**
+
+- `hierarchical` — orchestrator hub; agents reply to hub only.
+- `mesh` — agents see each other's outputs (e.g. competing diffs).
+- `hierarchical-mesh` — peer debate followed by hub reconciliation.
+- `ring` — output of step N feeds input of step N+1 in order.
+- `star` — N agents fan out from a single hub; no peer comms.
+- `adaptive` — topology shifts per step; outer chain remains hub.

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

@@ -11,15 +11,15 @@ incidents.
 
 ## Gate zero — `quality.local_auto_run` (default `false`)
 
-`false` or missing → **never run quality tools or full test suites
-proactively — never ask**. User runs them manually; **remote CI is the
-authoritative gate.** Run one ONLY on: (1) explicit ask this turn,
-(2) concrete CI failure — run exactly that failing check, (3) new-gate
-carve-out (a NEW gate/test this change introduces runs once to be
-proven). Completion wording: *"quality gates delegated to remote CI"* —
-never a pass claim for tools that did not run. Narrow probes proving
-the specific change (one `--filter` test, `curl`, syntax check on the
-edited file) stay allowed. Everything below applies when `true`.
+`false`/missing → **never run the full quality pipeline or full test
+suites proactively — never ask**; remote CI is the gate. Run one ONLY on:
+(1) explicit ask this turn, (2) concrete CI failure — run exactly that
+check, (3) new-gate carve-out (a NEW gate/test this change adds, run once).
+Completion wording: *"quality gates delegated to remote CI"* — never a pass
+claim for tools that did not run. Narrow probes stay allowed (one `--filter`
+test, `curl`); a type-check + lint **scoped to the changed files** is
+REQUIRED before a source push/PR — NOT the full pipeline. Everything below
+applies when `true`.
 
 ## When to run what — timing matters (`local_auto_run: true`)
 

package/dist/agent-src/rules/active-remediation.md

@@ -0,0 +1,92 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "Spotted an issue while working (security gap, missing test, bad code, duplication, stale idiom) — never ignore; fix small+aligned inline, ask on bigger, propose a follow-up PR for many"
+triggers:
+  - intent: "spotted an unrelated issue while working"
+  - intent: "found legacy or duplicated code"
+  - keyword: "refactor"
+  - keyword: "duplicate"
+  - keyword: "legacy"
+  - keyword: "deprecated"
+  - keyword: "modernize"
+  - keyword: "upgrade"
+  - keyword: "cleanup"
+  - keyword: "technical debt"
+workspaces: [engineering]
+packs: [engineering-base]
+---
+
+# Active Remediation
+
+The user doesn't see the code at the spot you're editing — you do. So this package guides the agent to **actively improve** what it touches: don't accept legacy, debt, security gaps, or duplication as given. But active improvement is bounded — never the scope creep `minimal-safe-diff` exists to stop. The rule is a **ladder**: act by size and alignment, and **never silently ignore** a real issue.
+
+## The Iron Law
+
+```
+NEVER IGNORE A REAL ISSUE YOU SPOT — AT MINIMUM, NOTE IT.
+SMALL + TASK-ALIGNED → FIX IT NOW, IN THE SAME CHANGE, WITH ITS TEST.
+BIGGER OR DIVERGENT → NOTE IT, FINISH THE TASK, THEN ASK — NEVER MID-FLOW.
+TOO MANY → PROPOSE ONE OR MORE SEPARATE FOLLOW-UP PRs THE USER REVIEWS.
+A LIVE SECURITY / DATA-EXPOSURE GAP IS NEVER MERELY "NOTED FOR LATER".
+```
+
+## What to remediate
+
+Security gaps (broken access control, injection, secrets, missing authz — see `broken-access-control`) · missing/weak test coverage · bad code (dead code, silent error-swallow, unguarded edge cases) · **duplication** (same/near-same logic repeated instead of one method/abstraction) · **stale version-idioms** (code for an older language/framework version than the project runs).
+
+## The ladder — classify, then act
+
+### Fix now (autonomous, inline) — a bounded amendment to `minimal-safe-diff`
+
+Allowed **only** when ALL hold — the testable "small + task-aligned" definition:
+- **Same request path / module** as the current task (not an unrelated feature).
+- **≤ ~10 changed lines** in one production file plus its test file — no wider cross-file ripple.
+- **No public-API / response-shape change**, no new parameter.
+- **No dependency bump, no migration, no data change.**
+- **Its verification ships in the same commit** — the security fix's negative test, the correctness fix's case.
+
+Under those constraints the fix is auditable in the same diff and is *not* scope creep — it corrects a boundary the agent touched. Anything outside them → **note + ask**, never auto. (`minimal-safe-diff` still governs the rest: no reformatting, no opportunistic refactor, no drive-by rename.)
+
+### Note + ask (batched)
+
+Bigger, or diverges from the task → do **not** refactor inline, do **not** interrupt the flow. Note the site (file:line + issue). Surface the batch as **one** numbered-options prompt (`user-interaction`, one recommendation line) **after the task is delivered** — or mid-work only when the flow makes it natural. Each option carries a real trade-off (`no-cheap-questions`). Refactor only on an explicit yes, as a separate scoped change (`scope-control`, `downstream-changes`).
+
+### Propose a follow-up PR (many spots)
+
+Too many to fold in without blowing the current diff's scope → propose **one or more separate follow-up PRs** (or a roadmap under `agents/roadmaps/`, using the shared-prefix convention) so the user reviews before merge. Creating the PR/roadmap is **permission-gated** — propose, get a yes, then create (`scope-control`, `commit-policy`).
+
+## Version-gated modernization
+
+Update stale idioms to the version the project **actually runs** — only when that version is **verified**:
+- **Establish the version first** from the manifest constraint (`composer.json` `require`, `package.json` `engines`, `.tool-versions`, lockfile) — use the **lowest** bound; on an ambiguous/monorepo range, ask once. **Unknown version → do not touch** (must fit the project structure — the `source-discovery` gate).
+- **Syntax-only, behavior-preserving idioms** (e.g. `array()` → `[]`, `isset($x)?$x:$d` → `$x ?? $d`, concat → template) provably equivalent → treat as a small fix (auto per the ladder).
+- **Behavioral changes** (`readonly`/typed properties, new semantics) and **any dependency/version bump** → **ask only**, never auto (a version bump stays under `minimal-safe-diff`'s no-dependency-bump prohibition; a pure syntax idiom is categorically different).
+
+## Live-security carve-out (priority)
+
+A **live cross-user / cross-tenant data exposure** (`broken-access-control`) is not "note for later": a potential GDPR-notifiable breach (Art. 33, 72 h from discovery). Meets the fix-now bar → fix now with its negative test. Otherwise → **stop and surface it immediately** (a safety surface, visible even under an autonomous mandate — like the `no-pr-progress-comments` safety carve-out). Never defer silently, never look away.
+
+## Guardrails — don't become a nagging machine
+
+- Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
+- Threshold to surface at all: a **real, nameable** improvement with concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
+
+## When it fires
+
+While implementing/modifying code you pass an issue outside the literal task. Also on explicit "clean this up / modernize / dedupe".
+
+## When NOT to fire
+
+- No issue spotted. Prose/docs-only. User fenced the scope ("just this one line").
+- The issue is the task itself — then it's just the task (no ladder needed).
+
+## See also
+
+- [`minimal-safe-diff`](minimal-safe-diff.md) — the carve-out above is bounded by it; everything outside the five conditions stays note+ask.
+- [`broken-access-control`](broken-access-control.md) — the security category + the live-exposure carve-out.
+- [`prefer-enums-over-literals`](prefer-enums-over-literals.md) — an instance of this ladder (enum literals).
+- [`source-discovery-gate`](source-discovery-gate.md) — establishing the verified project version before modernizing.
+- [`scope-control`](scope-control.md), [`commit-policy`](commit-policy.md) — PR/commit creation stays permission-gated.
+- [`improve-before-implement`](improve-before-implement.md) — the pre-work challenge (before); this is the during/after remediation.

package/dist/agent-src/rules/agent-authority.md

@@ -13,7 +13,7 @@ Four rules answer **"may the agent do this autonomously?"** Higher band wins.
 
 | Band | Trigger | Canonical rule |
 |---|---|---|
-| **1. Hard Floor** | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | [`non-destructive-by-default`](non-destructive-by-default.md) |
+| **1. Hard Floor** | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit · irreversible external action (send · publish · post · purchase · submit) | [`non-destructive-by-default`](non-destructive-by-default.md) |
 | **2. Permission Gate** | Git op · branch / PR / tag · architectural or library change · scope expansion | [`scope-control`](scope-control.md) |
 | **3. Commit Default** | About to commit — never, unless one of four exceptions fires | [`commit-policy`](commit-policy.md) |
 | **4. Trivial-vs-Blocking** | Routine workflow question — act or ask | [`autonomous-execution`](autonomous-execution.md) |

package/dist/agent-src/rules/broken-access-control.md

@@ -0,0 +1,106 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "Endpoint/query returning user or tenant data — authenticated ≠ authorized; enforce a server-derived ownership/tenant/role check + the three negative tests (401/non-owner/cross-tenant)"
+triggers:
+  - intent: "returning user or tenant data"
+  - intent: "adding an endpoint that reads a record by id"
+  - keyword: "endpoint"
+  - keyword: "route"
+  - keyword: "authorization"
+  - keyword: "tenant"
+  - keyword: "IDOR"
+  - keyword: "session"
+  - keyword: "login"
+  - keyword: "controller"
+  - keyword: "findById"
+routes_to:
+  - "skill:authz-review"
+  - "skill:threat-modeling"
+  - "skill:multi-tenancy"
+workspaces: [engineering]
+packs: [engineering-base]
+---
+
+# Broken Access Control
+
+The most common — and most damaging — failure in real systems and AI-written code: log in as one user, see another user's data. **Authenticated ≠ authorized.** The login check passes so the endpoint *feels* protected; the per-object ownership/tenant check is a separate line devs and AI omit — especially when the object id comes from the request. OWASP Web #1 (A01:2021) and API #1 (BOLA/IDOR), trivially scriptable, and a recurring real-world breach class — e.g. First American Financial (885M documents exposed via sequential ids with no ownership check).
+
+## The Iron Law
+
+```
+AUTHENTICATED IS NOT AUTHORIZED. EVERY REQUEST-SUPPLIED ID/FILTER GETS A
+SERVER-DERIVED OWNERSHIP/TENANT CHECK BEFORE ANY DATA IS RETURNED.
+NO DATA-RETURNING ENDPOINT IS DONE WITHOUT THREE NEGATIVE TESTS:
+UNAUTHENTICATED → 401 · NOT-OWNER → 403/404 · CROSS-TENANT → 403/404 (404 HIDES EXISTENCE).
+ROLE DECIDES WHICH FIELDS — THE SERVER STRIPS THEM. THE FRONTEND HIDING A FIELD IS NOT PROTECTION.
+A LIVE CROSS-USER EXPOSURE IS A NOTIFIABLE BREACH — NEVER SILENTLY PATCH IT.
+```
+
+## Non-optional controls (every data-returning surface)
+
+- **Server-derived principal.** Ownership/tenant derived from the session/token, **never** from a request header/param/body the caller controls. A matching id in the request is not authorization.
+- **Ownership/tenant check on every request id** before returning data. `findById(params.id)` with no `where owner/tenant = currentPrincipal` is the canonical bug.
+- **Tenant-scoped by construction.** Every query on a tenant table carries the tenant predicate; prefer a base scope that injects it so a forgotten clause can't leak. (DSGVO: Mandantentrennung / Trennungskontrolle is a required TOM — a missing `tenant_id` filter is a compliance failure, not just a bug.)
+- **Response minimization.** Return only entitled fields — no `SELECT *` / full-object serialization leaking PII "because the model has it" (Art. 25(2)).
+- **Property-level authz (BOPLA / mass assignment).** Reject `role` / `user_id` / `tenant_id` / `is_admin` from the request body; explicit field allow-list, never whole-body binding.
+- **Role/field-level output filtering (vertical BOPLA).** *Which* fields a principal receives depends on role + business rules — a driver role must not receive `price`; an office role must not receive the boss's `offer`. Serialize via a **role-scoped output DTO**, never the raw model / `to_json()`; sensitive fields (`price`/`cost`/`margin`/`salary`/`discount`/`offer`/internal notes) default-deny per role.
+- **No guessable public ids** on sensitive resources — UUID/ULID, not sequential integers (turns one bug into full-DB enumeration).
+
+## The three negative tests — the completion gate
+
+A protected endpoint is **not complete** until these exist and pass (happy-path 200 alone is the tautology this rule stops):
+
+1. **unauthenticated → 401** (no token).
+2. **authenticated but not the owner → 403/404** (user A requests user B's object with A's token).
+3. **cross-tenant → 403/404** (a principal in tenant A requests tenant B's resource; prefer 404 on sensitive resources — a hard 403 confirms the id exists in another tenant).
+
+Small + task-aligned gap in code you touched → add the check **and** its negative test in the same commit (auto-fix boundary in `active-remediation`). Bigger → surface it.
+
+## Role-based field-level access — both directions (vertical BOPLA + BFLA)
+
+Object-ownership (above) is *horizontal* (may this principal touch this record). This is *vertical*: which **fields** and which **functions** a role may reach — the maintainer's case (driver ≠ price, office worker ≠ boss's offer). Depends on role + business rules, and **the server is the only boundary** — the frontend hiding a field does not protect it: the raw JSON on the wire is readable via `curl`/DevTools/a proxy (3Fun leak: a privacy toggle filtered only in the app; the server returned every user's location to a direct query).
+
+- **Read side (CWE-213 / Excessive Data Exposure).** Build the response from a **role-scoped output DTO** — never serialize the ORM model directly. Sensitive fields default-deny per role. A client `?fields=` selection is ergonomics, not authorization — intersect it server-side with the role's read-allowlist.
+- **Write side (CWE-915).** Bind input through a **role-scoped write-allowlist** — never the raw body. Read-allowed ≠ write-allowed: a role may *see* `status` but not *set* `status:"approved"`; two independent sets.
+- **Function level (BFLA, OWASP API #5).** A role must not reach a function/verb reserved for a higher role. Gate **every mutating verb** (POST/PUT/PATCH/DELETE), deny-by-default — not just the GET you were asked about. The admin button being hidden is not a control.
+- **Nested / GraphQL.** Field-level checks propagate to nested selections; a low-role token selecting a restricted field gets null/error, not data.
+- **Negative tests, per (role × sensitive field), both directions:** lower-role token → the field is **absent from the raw response body** (assert the body, not the UI); lower-role setting it on input → rejected/ignored, **verified by re-reading the persisted record**; every privileged verb → 403 for lower roles (403/404 on sensitive object reads).
+
+## Defense-in-depth (so one miss can't leak)
+
+Stack ≥2 independent layers on sensitive data — query-level ownership scoping, a centralized default-deny policy layer (a route with no policy is denied, not silently open), and DB row-level security as the backstop for a forgotten `WHERE tenant_id`. The RLS / policy-layer configuration, the per-role authz matrix, and the audit greps live once in [`authz-review`](../skills/authz-review/SKILL.md).
+
+## GDPR / DSGVO — data protection by design
+
+A cross-user leak violates **Art. 5(1)(f)** (integrity & confidentiality — a principle → higher fine tier), **Art. 25** (by design/default: default-deny + least privilege + response minimization), and **Art. 32** — which also **mandates a process for regularly testing effectiveness** of these controls (untested authz is a direct Art. 32 gap; hence the three negative tests are non-optional). A discovered live exposure is a **notifiable breach** (Art. 33, 72 h from discovery) — surface as "notify + remediate", never a silent patch. Data-protection context, not legal advice → `privacy-review`, `domain-safety-pii`.
+
+## Backstop greps (authoring-time)
+
+```bash
+# Record fetched by request id with no owner/tenant predicate nearby (high-noise — a hit means read the line, not auto-fix)
+rg -n '(findById|find|findOne|get)\(\s*(req\.|request\.|params\.|\$request|\$id)'
+# Client-supplied tenant/user hint used as the scope (should come from the session)
+rg -n '(tenant|tenantId|user_id|userId)\s*=\s*(req|request|params|headers|query)\.'
+```
+
+The full authoring-time grep set (mass-assignment, raw-serialization, secrets) lives once in [`ai-code-blindspots`](../skills/ai-code-blindspots/SKILL.md).
+
+A hit means read that line — is the ownership/tenant check present? Some are safe (already scoped); none should ship unchecked.
+
+## When it fires
+
+Writing/modifying any endpoint, route, query, or serializer returning user- or tenant-owned data, or any auth/session/login/tenant path.
+
+## When NOT to fire
+
+- Public, non-user-specific data with no principal concept (public docs page, health check with no data).
+- Prose/docs/config-only edits.
+
+## See also
+
+- [`authz-review`](../skills/authz-review/SKILL.md) — the 6-stage per-entrypoint chain, defense-in-depth, authz matrix, negative-test contract.
+- [`security-sensitive-stop`](security-sensitive-stop.md) — threat-model BEFORE editing an auth/tenant path (fires first).
+- [`active-remediation`](active-remediation.md) — the fix-now/ask/follow-up ladder + the live-exposure safety carve-out.
+- [`threat-modeling`](../skills/threat-modeling/SKILL.md), [`multi-tenancy`](../skills/multi-tenancy/SKILL.md), [`ai-code-blindspots`](../skills/ai-code-blindspots/SKILL.md), [`privacy-review`](../skills/privacy-review/SKILL.md).

package/dist/agent-src/rules/communication-through-line.md

@@ -0,0 +1,42 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "Multi-step or continuation replies carry a red thread — state the goal once, tie each turn back to it, name what changed since last turn, close the loop with one end-summary"
+triggers:
+  - intent: "producing a multi-step or continuation reply"
+  - intent: "reporting progress on ongoing work"
+workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
+packs: [meta]
+---
+
+# Communication Through-Line
+
+The user follows the work through your replies. A multi-step task whose replies jump between sub-topics with no visible thread forces the user to re-derive where things stand every turn. Give the work a **red thread**: a followable narrative from goal to result. Session-spanning coherence — distinct from single-reply brevity (`direct-answers`) and option formatting (`user-interaction`), which it never overrides.
+
+## The Iron Law
+
+```
+STATE THE GOAL ONCE. TIE EACH TURN BACK TO IT. NAME WHAT CHANGED SINCE THE LAST TURN.
+CLOSE THE LOOP WITH ONE END-SUMMARY. NEVER MAKE THE USER RE-DERIVE WHERE THINGS STAND.
+```
+
+## Checkable behaviors
+
+- **Anchor once.** At the start of a multi-step task, state the goal/plan in one line (not re-stated every turn).
+- **Each turn locates itself.** A mid-task reply says, in a few words, where it sits in the plan ("step 3/5", "now the downstream wiring") — so the user never scrolls up to orient.
+- **Name the delta.** On a continuation, say what changed since the last turn (what landed, what's next) rather than restating everything.
+- **Close the loop.** A work reply ends with ONE end-summary mapping back to the stated goal — reached or not, what remains. (Same single end-summary `direct-answers` requires; do not add a second.)
+- **Signal pivots.** If the work changes direction (new sub-task, interrupt, blocker), say so explicitly — a silent topic switch breaks the thread.
+
+## When NOT to over-apply
+
+- A one-shot answer or trivial reply needs no plan-anchor or end-summary (`direct-answers` brevity wins).
+- Don't narrate for its own sake — the thread is orientation, not play-by-play (respect `personal.play_by_play`).
+- Never let the through-line inflate a reply past what the task needs; brevity and the one-recommendation rule win on conflict.
+
+## See also
+
+- [`direct-answers`](direct-answers.md) — brevity + the single end-summary this closes the loop with.
+- [`user-interaction`](user-interaction.md) — the one-recommendation format; through-line never adds a competing summary.
+- [`language-and-tone`](language-and-tone.md) — the thread is in the user's language.