@event4u/agent-config 8.8.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/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

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/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/communication-through-line.md

@@ -7,7 +7,7 @@ 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: [engineering-base]
+packs: [meta]
 ---
 
 # Communication Through-Line

package/dist/agent-src/rules/delegation-policy.md

@@ -72,6 +72,11 @@ primitive → run in-session (clean no-op).
    session (an application of the N=3 budget, no new mechanism); an ordered
    slice never dispatches before its declared parent's return is verified.
    Both per [`subagent-steering`](../contexts/execution/subagent-steering.md).
+6. **Record** telemetry after each dispatch — run `orchestration_record`
+   (one validated line: spawn_count, token_delta + provenance, tier, task_class)
+   per [`orchestration-telemetry`](../contexts/execution/orchestration-telemetry.md)
+   § Emit. Agent-behavioral capture the savings report reads; skipping it leaves
+   the value-of-orchestration question unmeasured.
 
 ## Scope — does NOT
 

package/dist/agent-src/rules/direct-answers.md

@@ -30,7 +30,7 @@ THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
 WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
 ```
 
-Severity tiers (High = load-bearing · Medium = project-shape · Low = idioms), per-tier verification actions, and "just guess" override: [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md).
+Severity tiers, per-tier verification actions, "just guess" override, **no duration estimates**, and **never cite the rule** when declining: [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md).
 
 **Live-state facts — never from memory.** Git/PR merge/branch/sync/existence state is High-severity and decays silently (branch already merged, PR already closed, `main` already ahead). NEVER assert "merged / not merged / pending / still open / already in `main` / out of scope" — or any branch/sync/existence claim — from memory, a roadmap note, an earlier turn, or a recalled memory. Run the live check FIRST (`git log --first-parent origin/main`, `git branch -r --contains <ref>`, `gh pr view <n> --json state,mergedAt,baseRefName`); a state question is self-answering (per [`git-workflow`](../skills/git-workflow/SKILL.md)). Same for any external system that changes behind you (CI run, deploy, remote queue).
 

package/dist/agent-src/rules/downstream-changes.md

@@ -77,3 +77,4 @@ After completing all downstream changes:
 2. **No broken tests** — run the project test suite (Pest / PHPUnit, Jest / Vitest, pytest, `go test ./...`, `cargo test`).
 3. **No broken types / signatures** — project's type-checker (PHPStan / Psalm, TypeScript, mypy / pyright, `go vet`, `cargo check`).
 4. **No stale references** — grep for the old name / namespace / import path to confirm zero results.
+5. **No own-orphans** — the same sweep applied to the new diff: identifiers whose last reference disappeared in a file this diff touched are removed in the same diff (see [`minimal-safe-diff § Own-orphan cleanup`](minimal-safe-diff.md#own-orphan-cleanup)); pre-existing dead code stays.

package/dist/agent-src/rules/external-code-graph-interop.md

@@ -0,0 +1,65 @@
+---
+type: "auto"
+tier: "2a"
+description: "When the repo ships an external code-graph index (a graph.json-shaped artifact or a SCIP index), query IT first for codebase-structure questions — do not grep from scratch"
+triggers:
+  - keyword: "scip"
+  - keyword: "code-graph"
+  - keyword: "code graph"
+  - phrase: "graph.json"
+  - phrase: "who calls"
+  - phrase: "call graph"
+  - phrase: "find references"
+  - phrase: "where is this used"
+applies_to_user_types:
+  - "developer"
+  - "maintainer"
+workspaces: [engineering]
+packs: [meta]
+---
+
+# External Code-Graph Interop
+
+Some repos commit a pre-built code-intelligence index — a `graph.json`-shaped
+artifact or a SCIP index (`index.scip`, `*.scip`). When one exists, it already
+answers "who calls X", "where is Y used", "what does this import" far more
+precisely than a fresh `grep`. This suite is an **orchestrator, not a
+competitor**: query the existing index first.
+
+## The rule
+
+```
+REPO SHIPS A CODE-GRAPH INDEX (graph.json-shaped OR a SCIP index)
+→ QUERY IT FIRST FOR CODEBASE-STRUCTURE QUESTIONS. GREP IS THE FALLBACK,
+NOT THE FIRST MOVE. NEVER REBUILD WHAT THE INDEX ALREADY ANSWERS.
+```
+
+## When it fires
+
+A codebase-structure question (call graph, references, usages, import graph)
+AND the repo contains a detectable index:
+
+- a SCIP index — `index.scip` or any `*.scip` at the repo root or a conventional
+  index directory;
+- a `graph.json`-shaped artifact (a committed code-graph export).
+
+## What to do
+
+1. **Detect** the index (its path is the concrete pointer; the specific tool
+   that produced it is named in the repo's own docs, not here).
+2. **Query it** for the relationship the user asked about.
+3. **Fall back to `grep`/read** only for what the index does not cover, and say
+   so ("the index has no entry for X, so I grepped").
+
+## When NOT to fire
+
+- No such index in the repo — normal `grep`/read is the right first move.
+- The question is about content/semantics, not code structure.
+
+## See also
+
+- [`discovery_graph`](../scripts/discovery_graph.ts) — this suite's OWN artefact
+  relation-graph (`affected`/`explain`); the external code-graph is the
+  *source-code* analogue this rule defers to for code questions.
+- [`think-before-action`](think-before-action.md) — analyze with the best
+  available tool before grepping blind.

package/dist/agent-src/rules/git-history-discipline.md

@@ -120,6 +120,24 @@ If either stop fires and resolution is not immediate → tag the state (`git tag
 
 `--amend` on the *current local* commit before the first push is the narrow exception (treated as continuing to compose the commit, not rewriting history).
 
+## Amend-after-hook-failure trap (data-loss)
+
+When a **pre-commit hook fails, the commit did NOT happen** — no new commit
+object was created. A reflexive `git commit --amend` at that point does not
+"retry the commit"; it rewrites the **previous, already-good** commit,
+destroying that work. This is the one place the narrow `--amend` exception
+above turns into data loss.
+
+Recovery — never amend after a hook failure:
+
+1. Read the hook output and **fix the cause** (the lint/test/format failure).
+2. **Re-stage** the fix (`git add`).
+3. Create a **NEW commit** (`git commit`, not `--amend`) — the prior commit was
+   never overwritten and must stay intact.
+
+Recovery procedures live next to this mechanism in
+[`skill:git-workflow`](../skills/git-workflow/SKILL.md).
+
 ## Why this rule exists
 
 Interactive rebase + fixup loops generate disproportionate token cost on every iteration: re-running CI per replayed commit, resolving the same content conflict in three derived files (`.condensation-hashes.json`, `dist/router.json`, `.windsurfrules`), losing the working tree to a stash that silently re-introduces older state. A single conflict can burn the budget of an entire feature.

package/dist/agent-src/rules/lethal-trifecta-guard.md

@@ -21,7 +21,11 @@ packs: [engineering-base]
 Prompt injection is not solvable at the model layer (OWASP LLM01). It is
 contained **architecturally**: a tool/skill/command becomes dangerous only when
 it combines all three legs of the *lethal trifecta*. Remove one leg and an
-injected instruction can do no consequential harm.
+injected instruction can do no consequential harm. This is the agentic attack
+surface OWASP's Agentic Security Initiative (ASI Top 10) catalogues — excessive
+agency, tool misuse, confused-deputy data exfiltration; the Least-Agency
+discipline in [`tool-safety`](tool-safety.md) is the same defence applied to the
+tool grant.
 
 ## The Iron Law
 
@@ -75,6 +79,7 @@ backstop.
 ## See also
 
 - [`untrusted-input-defense`](untrusted-input-defense.md) — data/instruction separation, spotlighting.
+- [`tool-safety`](tool-safety.md) — Least Agency: the narrowest tool grant breaks the egress leg by construction (OWASP ASI excessive-agency).
 - [`security-sensitive-stop`](security-sensitive-stop.md) — threat-model before editing a sensitive surface.
 - [`non-destructive-by-default`](non-destructive-by-default.md) — the human-in-the-loop egress floor.
 - [`threat-modeling`](../skills/threat-modeling/SKILL.md) — abuse-case enumeration.

package/dist/agent-src/rules/minimal-safe-diff.md

@@ -74,6 +74,54 @@ task scope · dependency bumps "because it was close to the cache".
 Ask. A minimal diff plus one follow-up is cheaper than a sprawling diff the
 reviewer has to untangle.
 
+## 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.**
+- **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.
+
+Wrong/right pairs for each ban:
+[`simplicity-and-goal-demos`](../docs/guidelines/agent-infra/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.
+
+## Own-orphan cleanup
+
+Your diff cleans up exactly the mess it made — nothing more:
+
+- An identifier (import, variable, function, parameter) is an **own-orphan**
+  iff its **last reference disappeared in a file THIS diff touched**. Remove
+  it in the same diff — it traces to the task; leaving it is an incomplete
+  change, not restraint.
+- If **any reference survives in a file the diff did not touch**, the
+  identifier is **pre-existing debt** — leave it untouched and surface it via
+  [`active-remediation`](active-remediation.md)'s note-and-ask ladder, never
+  delete drive-by.
+- The check is mechanical: after editing, grep each identifier your hunks
+  stopped referencing; zero remaining references and the last one was yours →
+  own-orphan (delete); otherwise → note. (`downstream-changes` runs the same
+  sweep for renames — this is that sweep applied to the new diff.)
+
 ## Break-glass exception
 
 This rule stays in force during production incidents. "Break-glass mode"
@@ -103,16 +151,16 @@ description.
 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`](active-remediation.md). 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`](broken-access-control.md)) —
+[`active-remediation`](active-remediation.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`](broken-access-control.md)) —
 fix-now-if-small, else stop and surface; never defer it silently.
 
 See also: `scope-control` · `downstream-changes` · `think-before-action` · `preservation-guard` · `verify-before-complete` · [`active-remediation`](active-remediation.md) · [`broken-access-control`](broken-access-control.md).

package/dist/agent-src/rules/non-destructive-by-default.md

@@ -32,9 +32,12 @@ Triggers below require explicit user confirmation **on this turn** — not from
 | **Production data / infra** | prod DB writes / migrations, prod config, secrets rotation, IAM / role / policy, DNS, anything in a `prod`-scoped path or pipeline |
 | **Whimsical / unscoped bulk deletion** | `rm -rf <dir>`, `git rm -r`, glob deletes, `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work — when **not required** by the task (task-aligned WIP deletions allowed, below) |
 | **Commit containing bulk deletions or infra changes** | diff removes a directory, deletes ≥5 unrelated files, or touches Terraform/Pulumi/k8s/Ansible/cloud-config — surface the diff + confirm even when [`commit-policy`](commit-policy.md) authorizes |
+| **Irreversible external action** | **send** / **publish** / **post** / **purchase** / **submit** — an outbound, externally-visible, or money-moving action the user cannot un-see: send an email/message, publish or post content, submit a form, place an order or payment. Also gated by [`scope-control`](scope-control.md) external-comms; named here so the Hard Floor lists the actual buttons |
 
 Standing "just keep going" + next step crosses the floor → STOP, surface it (one numbered-options block per [`user-interaction`](user-interaction.md)), wait.
 
+**Never act while asking.** The ask and the action are strictly sequential: surface the confirmation, then WAIT for the answer. Never fire the action in the same turn you ask for it — no do-then-ask race, no "I went ahead and…". **The approval names the exact object** so the user confirms the real thing, not a category: a download names filename + size + source; a purchase names amount + card-last4 + total; a send names recipient + subject. Shape per [`user-interaction`](user-interaction.md) numbered-options.
+
 ## Not in scope — deterministic regeneration
 
 Output regenerated from a tracked source (condensation, code-gen, formatters, lock-files) is reversible — **not destructive** ([`autonomous-execution`](autonomous-execution.md)). Per-file diff approval is theater.

package/dist/agent-src/rules/question-not-instruction.md

@@ -0,0 +1,76 @@
+---
+type: "auto"
+tier: "1"
+description: "A question is a request for an ANSWER, never authorization to act — answer first; never treat 'why…?' / 'can you…?' / 'what do you think?' as a green light to build, change, or execute"
+triggers:
+  - phrase: "warum"
+  - phrase: "wieso"
+  - phrase: "weshalb"
+  - keyword: "why"
+  - phrase: "what do you think"
+  - phrase: "was denkst du"
+  - phrase: "was hältst du"
+  - phrase: "geht das"
+  - phrase: "kannst du"
+  - phrase: "sollte ich"
+  - phrase: "should i"
+  - phrase: "is it possible"
+applies_to_user_types:
+  - "creator"
+  - "developer"
+  - "maintainer"
+  - "operator"
+  - "researcher"
+workspaces: [engineering]
+packs: [meta]
+---
+
+# Question Is Not an Instruction
+
+```
+A QUESTION ASKS FOR AN ANSWER. IT IS NOT AUTHORIZATION TO ACT.
+"WARUM…?" / "WHY…?" / "WAS DENKST DU?" / "GEHT DAS?" / "KANNST DU…?"
+→ ANSWER FIRST. NEVER BUILD, CHANGE, COMMIT, OR EXECUTE ON A QUESTION.
+RUNNING OFF ON A QUESTION IS A RULE VIOLATION, NOT INITIATIVE.
+```
+
+The user asks two distinct kinds of turn. Confusing them is the failure this
+rule exists to stop:
+
+| Turn shape | Signal | Correct response |
+|---|---|---|
+| **Question** | interrogative — `warum`, `wieso`, `why`, `?`, `was denkst du`, `geht das`, `kannst du`, `sollte ich`, `is it possible` | **Answer it.** Explain, reflect, surface the trade-off. Do NOT execute. |
+| **Instruction** | imperative — `mach`, `bau`, `implementiere`, `fix`, `erstelle`, `run`, `füge hinzu` | Execute per the usual authority gates. |
+
+## The trap
+
+A question that expresses **frustration or challenge** — *"Warum hast du nur
+eine Phase gemacht?"*, *"Wieso hast du das nicht anders gelöst?"* — is STILL a
+question. It demands an explanation, not a burst of corrective action. Reading
+the frustration as *"go fix everything now"* and charging off is the canonical
+violation: the user loses their answer AND gets unrequested work.
+
+## What to do
+
+1. **Answer the literal question** — directly, honestly, first token.
+2. If the answer implies work *might* follow, **stop after the answer** and let
+   the user decide. Offer numbered options if a decision is genuinely theirs
+   (per [`user-interaction`](user-interaction.md)), but do not start the work.
+3. Only a subsequent **imperative** turn authorizes execution.
+
+## When it does NOT fire
+
+- The turn is imperative (an instruction), even if phrased politely
+  (*"kannst du bitte X machen"* where X is clearly the ask + context makes it a
+  directive) — but when genuinely ambiguous between question and instruction,
+  treat it as a **question** and ask which the user meant (one line).
+- A rhetorical question inside a larger instruction (*"why not just do X? do
+  it"*) — the trailing imperative governs.
+
+## See also
+
+- [`user-interrupt-priority`](user-interrupt-priority.md) — a new *instruction*
+  mid-flight; this rule is its complement for a *question* mid-flight.
+- [`ask-when-uncertain`](ask-when-uncertain.md) — when the agent should ask;
+  this rule is about honouring the user's question, not the agent's.
+- [`direct-answers`](direct-answers.md) — answer the substance, no deflection.

package/dist/agent-src/rules/senior-engineering-discipline.md

@@ -58,7 +58,7 @@ Full surface→controls table + backstop greps: → `skill:ai-code-blindspots`.
 
 ### 3. Verify — never assert from memory
 
-No completion claim without exercising the real path (running endpoint / UI / test — not "the code looks right"). "Defined but not wired" (middleware written, never connected to the route) = **not done**. → `verify-before-complete`, `source-discovery-gate`.
+No completion claim without exercising the real path (running endpoint / UI / test — not "the code looks right"). "Defined but not wired" (middleware written, never connected to the route) = **not done**. **Before pushing code / opening a PR, run a changed-files static pass — type-checker + linter scoped to the diff (`tsc --noEmit` on the touched project, linter on changed files) — even when `quality.local_auto_run` is false: a narrow probe of your own diff, NOT the suppressed full pipeline. Letting a compile/lint error hit remote CI = completion claim without evidence (the beginner error this guards).** → `verify-before-complete`, `source-discovery-gate`.
 
 ## When it fires
 

package/dist/agent-src/rules/think-before-action.md

@@ -33,6 +33,7 @@ NO BLIND TRIAL-AND-ERROR. MAX 2 RETRIES PER APPROACH.
 - Prefer targeted inspection (jq, debugger, logs) over brute-force.
 - Always verify results after changes (API, UI, tests) using the concrete tool that exercises that surface — `curl` / Playwright / browser for HTTP and UI, debugger / `xdebug` for runtime frames, the project's test runner for behavior.
 - When behavior can be defined → prefer test-first / TDD.
+- **Multi-step task → restate as verifiable success criteria first** (test that reproduces the bug, failing-then-passing check, before/after invariant) and plan `step → verify:` per step; a task whose success cannot be checked is a clarification trigger, not an execution trigger. Transformation table: [`think-before-action-mechanics § Goal-driven execution`](../contexts/communication/rules-auto/think-before-action-mechanics.md#goal-driven-execution--vague-ask--verifiable-goal).
 - Unclear requirements → precise clarification question, not hidden assumptions.
 - Refactors must preserve behavior, validation, examples, and anti-failure guidance unless explicitly changed.
 - Do NOT modify code you do not fully understand — read it, trace the flow, then change it.