@event4u/agent-config 8.8.0 → 8.10.0

package/dist/agent-src/commands/worktree.md

@@ -0,0 +1,85 @@
+---
+model_tier: medium
+name: worktree
+disable-model-invocation: true
+pack: engineering-base
+tier: 2
+visibility: internal
+description: Worktree orchestrator — routes to create, status, verify, cleanup
+cluster: worktree
+type: orchestrator
+auto_detect: true
+suggestion:
+  eligible: true
+  trigger_description: "isolate this in a worktree, which worktrees are active, is the worktree merge-ready, clean up finished worktrees"
+  trigger_context: "parallel work needs an isolated working directory, or existing worktrees need status/verification/removal"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /worktree
+
+Top-level orchestrator for the governed-worktree family — a THIN layer
+over host-native primitives (Claude Code `EnterWorktree`/`ExitWorktree`,
+subagent `isolation: "worktree"`) and plain `git worktree` elsewhere.
+Explicitly OUT of scope: auto-merge, daemons, background watchers,
+dispatch beyond the existing subagent worktree isolation.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/worktree create` | `commands/worktree/create.md` | Create a governed worktree + write the scope-lock note (propose-once branch naming) |
+| `/worktree status` | `commands/worktree/status.md` | List active worktrees — ownership, dirty state, ahead/behind, merge-readiness incl. verification evidence |
+| `/worktree verify` | `commands/worktree/verify.md` | Run the scoped verification for the worktree's declared change — narrow probes, not full CI |
+| `/worktree cleanup` | `commands/worktree/cleanup.md` | Safe removal gate — refuses while the branch has commits on no other ref |
+
+All four route through the
+[`worktree-lifecycle`](../../skills/worktree-lifecycle/SKILL.md) skill;
+creation mechanics live in
+[`using-git-worktrees`](../../skills/using-git-worktrees/SKILL.md).
+
+## Non-interactive & auto-detection
+
+`/worktree` honors the [`non-interactive-contract`](../contexts/execution/non-interactive-contract.md)
+(surface detection, confidence tiers, `--yes`/`--json`, abort schemas,
+the `auto_detect` kill-switch). Detection table:
+
+| Basis (signal) | Sub-command | Confidence |
+|---|---|---|
+| Explicit sub given (`/worktree status`) | that one | — (detection skipped) |
+| "isolate / do this on the side / new worktree for X" | `worktree/create` | HIGH |
+| "which worktrees / what's active / merge-ready?" | `worktree/status` | HIGH |
+| "verify the worktree change", scoped probe intent | `worktree/verify` | MEDIUM |
+| "remove / clean up the worktree(s)" | `worktree/cleanup` | HIGH |
+| No clear signal | — | LOW → menu (interactive) / `ambiguous_routing` (CI) |
+
+`cleanup` is the only destructive sub-command — on MEDIUM-or-lower
+confidence it is never auto-selected; show the menu instead.
+
+## Dispatch
+
+1. Parse the user's argument: `/worktree <sub-command> [args]`.
+2. **Explicit sub** → look it up and route. Otherwise run the detection
+   table above per the non-interactive-contract.
+3. Load the body of the routed file and follow its `## Instructions`
+   section verbatim with the remaining args.
+4. On **LOW** confidence (or `--no-auto-detect`): interactive → print
+   the menu and ask; non-interactive → emit `ambiguous_routing` and stop.
+
+   > 1. create — new governed worktree + scope-lock note
+   > 2. status — list worktrees with merge-readiness
+   > 3. verify — run the scoped verification for a worktree
+   > 4. cleanup — safely remove finished worktrees
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command
+  explicitly authorizes it.
+- **Do NOT chain sub-commands.** One `/worktree <sub>` per turn.
+- **No auto-merge, no watchers.** The cluster reports and gates; the
+  user (or an explicitly invoked command) merges.
+- Auto-detection never guesses past LOW, and never auto-selects
+  `cleanup` below HIGH confidence.

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,8 +23,12 @@ 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
+  "verify_result_by_tier": null,
+  "first_pass_success": null,
+  "escalated": null
 }
 ```
 
@@ -32,22 +36,26 @@ v1 forward-compat rule on unknown fields).
 
 | Field | Type | Meaning |
 |---|---|---|
-| `task_size_estimate` | int | Pre-dispatch estimate of the task's size (orchestrator's sizing heuristic). Counts only, no body. |
-| `spawn_count` | int | Subagents dispatched for this task. `0` → handled in-session. |
-| `tiers` | string[] | Model tiers dispatched to, one per spawn class (e.g. `["sonnet","opus"]`). Tier names only, no prompts. |
-| `token_delta` | int | Net token cost vs the in-session baseline. Positive = cost more; negative = saved. Counts only. |
-| `token_delta_provenance` | enum | `"measured"` from host-reported `usage` metadata (preferred); `"estimated"` when self-estimated from response length (mark always when host usage unavailable). |
-| `wall_clock_ms` | int | Dispatch wall-clock duration, milliseconds. |
+| `task_size_estimate` | int | Pre-dispatch estimate of the task's size (the orchestrator's sizing heuristic). Counts only, no body. |
+| `spawn_count` | int | Number of subagents dispatched for this task. `0` → handled in-session. |
+| `tiers` | string[] | Model tiers dispatched to, one entry per spawn class (e.g. `["sonnet","opus"]`). Tier names only, no prompts. |
+| `token_delta` | int | Net token cost of the dispatch versus the in-session baseline. Positive = orchestration cost more; negative = saved tokens. Counts only. |
+| `token_delta_provenance` | enum | `"measured"` when sourced from host-reported `usage` metadata (preferred); `"estimated"` when self-estimated from response length (mark always when host usage is unavailable). |
+| `wall_clock_ms` | int | Wall-clock duration of the dispatch, milliseconds. |
 | `outcome` | enum | One of `DONE` · `DONE_WITH_CONCERNS` · `NEEDS_CONTEXT` · `BLOCKED` · `killed`. |
-| `verify_mode` | enum | How output was verified: `deterministic` · `judge` · `none`. |
-| `verdict_changed_outcome` | bool \| null | **A3 extension (ADR-109 Track A).** For a review/verdict subagent (e.g. `production-validator`): did the verdict change the outcome vs the in-session baseline? `true` = caught a real issue the baseline missed / flipped a false `READY`→`NOT READY`; `false` = no lift; `null` = not a verdict dispatch / not measured. **Negative-control (clean single-file) tasks MUST record `false`** — a `true` on a control = spurious findings, fails Gate A. Additive field on THIS object, not a second schema. Boolean/counts only, no bodies. |
+| `verify_mode` | enum | How the dispatch's output was verified: `deterministic` · `judge` · `none`. |
+| `verdict_changed_outcome` | bool \| null | **A3 extension (ADR-109 Track A).** For a review/verdict subagent (e.g. `production-validator`): did the subagent's verdict actually change the outcome versus the in-session baseline? `true` = it caught a real issue the baseline missed or flipped a false `READY`→`NOT READY`; `false` = same outcome as baseline (no lift); `null` = not a verdict dispatch / not measured. **Negative-control tasks (a clean single-file task) MUST record `false`** — a subagent that reports `true` on a control is producing spurious findings and fails Gate A. This is an additive field on THIS object, not a second schema. Counts/boolean only, no bodies. |
 | `task_class` | string \| null | **Routing extension (road-to-cost-aware-model-routing Phase 0).** Category id of the dispatched slice (e.g. `read-only-fanout`, `mechanical-edit`, `implementation`, `review-synthesis`). Enum-style id only, never free-form task text. `null` = pre-extension line / unclassified. |
 | `tier_chosen` | string \| null | Tier the slice was dispatched on (`lite` \| `medium` \| `high`). `null` = pre-extension line. |
 | `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. |
-
-All five routing fields are additive and optional — a line without them is
+| `escalated_from` | string \| null | When the slice was re-dispatched after a verification failure: the 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 of tier → verification result for every 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. |
+| `first_pass_success` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the subagent return was adopted without parent rework; `false` = the parent had to rework the return before adopting. `null` = pre-extension line / not measured. Boolean only, no bodies. |
+| `escalated` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the slice was retried on a higher tier after a verification failure; `false` = no escalation. `null` = pre-extension line / not measured. Boolean only, no bodies. |
+
+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.
 
@@ -70,37 +78,58 @@ object is an additive extension on an otherwise standard audit-log-v1 line:
 
 After every auto-dispatched orchestration run, the orchestrating agent writes one
 telemetry line to `agents/runtime/state/audit/YYYY-MM.jsonl` (the existing
-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.
+audit-log-v1 path, where `YYYY-MM` is the 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 the line directly — the
+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 the inputs and builds a
+conformant audit-log-v1 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|…] \
+  [--first-pass-success true|false] [--escalated true|false]
+```
 
-**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`).
+A capture **hook** is the wrong tool here: the PostToolUse payload carries no
+subagent token usage — only the orchestrator sees it (via the run result) — and
+a hook would reverse 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
-   available) from each subagent call's response metadata. Use the sum minus the
-   estimated single-agent baseline. Set `token_delta_provenance: "measured"`.
-2. Self-estimate fallback: host usage metadata unavailable → estimate from
+   available) from the response metadata of each subagent call. Use the sum
+   minus the estimated single-agent baseline. Set `token_delta_provenance:
+   "measured"`.
+2. Self-estimate fallback: if host usage metadata is unavailable, estimate from
    response length (chars / 4 ≈ tokens). Set `token_delta_provenance:
-   "estimated"`. Lossy; measured always preferred.
+   "estimated"`. This estimate is lossy; measured is always preferred.
 
 ## Savings report
 
-Aggregate accumulated telemetry into a token-savings report:
+Aggregate the 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).
+It sums `token_delta` across dispatches (negative = net saved) and splits by
+provenance (measured vs estimated), `tier_chosen`, and `task_class`. **Quality
+and cost render as PAIRED columns** (council verdict — never savings alone):
+`first_pass_success_rate` and `escalation_rate` aggregate over the lines that
+carry the quality booleans; with ≥ 20 such lines in the window the real rates
+render beside the savings figures, below 20 the quality columns render as
+`n/a (n=<count>)`. It reports
+**ABSOLUTE net tokens saved, never a percentage**: the telemetry records net
+delta, not the absolute in-session baseline, so a "% of session saved" is not
+derivable from this data. A percentage would require an additive
+absolute-baseline field on this object (deferred follow-up). Reader:
+[`src/scripts/_lib/orchestration_savings.ts`](../../../../src/scripts/_lib/orchestration_savings.ts).
 
 ## Related
 

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/design-fidelity.md

@@ -88,6 +88,46 @@ redesign.
 - Treating an internal "honesty gate" or "stub" concern as licence to redesign the UI.
 - Re-running a redesign after the user already said "match the prototype".
 
+## Surgical visual edits
+
+A request to change one visual thing — a colour, a label, a single element — is
+a **targeted edit**, not a redesign licence. Apply the same
+[`minimal-safe-diff`](minimal-safe-diff.md) discipline to design work that
+backend edits have always owed.
+
+- **Change only the semantic target.** Preserve the surrounding layout,
+  spacing, typography, dimensions, content, animation, and interaction states.
+  Do not rewrite the component, reflow the section, or "modernise" neighbours
+  while you are in there. (fixtures: `daf-edit-preservation`, `daf-unwanted-variations`.)
+- **A broader redesign needs an explicit trigger.** Only phrases like *"new
+  direction"*, *"from scratch"*, *"make it feel premium"*, *"rework the flow"*,
+  or *"give me variations / options"* license a from-scratch rework. Absent such
+  a phrase, a "fix / change / update the X" request is surgical — when unsure
+  which, ask ([`ask-when-uncertain`](ask-when-uncertain.md)). (fixture: `daf-redesign-trigger`.)
+- **Preserve stable anchors.** Where the host exposes DOM/comment metadata, keep
+  comment anchors and screen labels intact so the edit stays locatable. Where
+  the host has no such surface, preserve stable semantic anchors already present
+  in source comments / `data-*` attributes — never strip them, and do not invent
+  new ones.
+
+## Asset & imagery discipline
+
+Visual artifacts carry **real assets or honest placeholders — never fabricated
+brand evidence**. The design-surface instance of the no-invented-facts floor.
+
+- **Copy owned assets through the project's accepted path.** Reference or copy
+  project-owned assets (logos, icons, fonts, images) via the target project's
+  asset directory/pipeline — never hotlink a design-system's internal URL, never
+  bulk-copy a huge source folder. (fixtures: `daf-missing-asset`, `daf-external-asset-url`.)
+- **Real imagery where inspection matters.** On visual pages/decks, use actual
+  product / place / object / state imagery where the image IS the proof (a
+  product screenshot, a real dashboard state). Decorative atmosphere is not proof
+  — never pass a stock-like or invented image off as the real product. An
+  invented product screenshot is fabricated evidence. (fixture: `daf-invented-screenshot`.)
+- **Icons follow the iconography floor** — no emoji-as-icon in serious UI, no
+  hand-rolled icon when a set exists; see
+  [`iconography`](../skills/iconography/SKILL.md) § Iconography floor.
+
 ## See also
 
 - [`brand-source-of-truth`](brand-source-of-truth.md) / [`brand-consistency`](brand-consistency.md) — same precedence shape, for registered brand tokens.

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.