@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/commands/council-optimize.md

@@ -0,0 +1,115 @@
+---
+name: council-optimize
+cluster: optimize
+skills: [ai-council]
+description: Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "council on this perf hot path, second opinion on this optimization, external review of /optimize output"
+  trigger_context: "user has an optimization target (code path, query, profile result, /optimize-* output) and wants a ranked external opinion"
+---
+
+# council-optimize
+
+## Instructions
+
+Specialised council mode for **optimization targets**: hot paths,
+slow queries, allocation profiles, or the output of an `/optimize-*`
+command (`/optimize-skills`, `/optimize-agents`,
+`/optimize-augmentignore`, `/optimize-rtk-filters`). Wraps
+`/council` with the `optimize` neutrality preamble, which focuses
+members on **ranked**, **evidence-based** suggestions instead of
+generic "you should profile" advice.
+
+### 1. Resolve the target
+
+The user invoked `/council-optimize <target>` or `/council-optimize`.
+If nothing was supplied, ask (one question per turn):
+
+> What should the council optimize?
+>
+> 1. A file or directory of code (perf hot path)
+> 2. A query / SQL / DB call (paste it now)
+> 3. The output of an `/optimize-*` command — re-run it now and feed
+>    the report to the council
+> 4. A free-form description of the bottleneck
+
+Pick **1** → `/council files:<paths>` with `mode_override=optimize`.
+Pick **2** → `/council prompt:"<query + context>"` with
+`mode_override=optimize`.
+Pick **3** → run the chosen `/optimize-*` command first, then feed
+its report file to `/council files:<report>` with
+`mode_override=optimize`.
+Pick **4** → `/council prompt:"<description>"` with
+`mode_override=optimize`.
+
+### 2. Capture the constraint
+
+Optimization is meaningless without a target metric. Ask **once**
+(one question per turn) before invoking `/council`:
+
+> What does "better" mean here?
+>
+> 1. Latency (p50 / p95 / p99 — pick which)
+> 2. Throughput (req/s)
+> 3. Memory footprint
+> 4. Cost ($ / 1M ops)
+> 5. Token count (for LLM workflows)
+> 6. Other — describe in one line
+
+The chosen metric becomes the `original_ask` for the handoff preamble:
+`Optimize for <metric>: <one-line scope>`.
+
+### 3. Run /council with the optimize mode preamble
+
+Invoke the matching `/council` form (`files:` / `prompt:`) with
+`mode_override=optimize`. The `optimize` mode addendum from
+`scripts/ai_council/prompts.py` requires members to:
+
+- Rank suggestions by expected impact on the chosen metric, not by
+  effort or cleverness.
+- Cite the evidence (line, query plan, profile entry) for each
+  suggestion. No hand-wave "this is probably slow".
+- State at least one suggestion the member explicitly **rejects** as
+  low-leverage, so the user does not over-engineer.
+- Mark at least one suggestion that requires measurement before
+  committing — i.e. flag what is hypothesis vs. confirmed.
+
+The cost gate from `/council` Step 3 still applies.
+
+### 4. Render the report
+
+Use the standard stacked + Convergence/Divergence layout. Add a
+one-line header at the top so the optimization metric is visible:
+
+```
+## Council on <target> — optimize for <metric>
+```
+
+### 5. Hand back to the user
+
+The council is **advisory**. Do **not** apply optimizations
+autonomously. Surface ranked suggestions and let the user pick which
+to drive into a normal `/work` / `/implement-ticket` flow.
+
+### Hard floor (restated)
+
+`/council-optimize` produces **text only**. It does NOT edit code,
+run benchmarks, or change configuration.
+
+## Failure modes
+
+- **No measurable metric** → if the user picks "Other" without a
+  unit, ask once for clarification; if still vague, stop. Generic
+  "make it better" is exactly what this command refuses to enable.
+- **Target too large** → bundler raises `BundleTooLarge`; suggest
+  narrowing to the hot path (`/council files:<single-file>`).
+
+## See also
+
+- `/council` — base orchestration entry point.
+- `/optimize-skills`, `/optimize-agents`, `/optimize-augmentignore`,
+  `/optimize-rtk-filters` — internal optimization commands; their
+  output can be fed to `/council-optimize` for an external ranking.
+- `ai-council` skill — neutrality guidelines.

package/.agent-src/commands/council-pr.md

@@ -0,0 +1,123 @@
+---
+name: council-pr
+cluster: optimize
+skills: [ai-council]
+description: Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "council on PR #N, external review of pull request, second opinion on a PR"
+  trigger_context: "user has a PR number / URL and wants an external review before approve/merge"
+---
+
+# council-pr
+
+## Instructions
+
+Specialised council mode for **GitHub PRs**. Wraps `/council diff:<base>..<head>`
+with a PR-aware neutrality preamble (the `pr` mode) and an opt-in
+"post a comment summary on the PR" step at the end.
+
+### 1. Resolve the PR target
+
+The user invoked `/council-pr <number>` or `/council-pr <url>`. If
+neither was supplied, ask (one question per turn, per
+`ask-when-uncertain`):
+
+> Which PR should the council review?
+>
+> 1. PR number on the current repo (e.g. `#123`)
+> 2. Full GitHub URL
+> 3. Cancel
+
+### 2. Pull PR metadata via gh CLI
+
+Run:
+
+```bash
+gh pr view <number> --json number,title,body,headRefName,baseRefName,author,url
+```
+
+Capture: title, body, head ref, base ref. The **PR title + body** is
+the user's `original_ask` for the handoff preamble — verbatim, after
+`_strip_host_identity()` cleansing in `prompts.py`. Do **not** add the
+agent's framing.
+
+### 3. Fetch the diff range locally
+
+```bash
+git fetch origin <base>:<base>
+git fetch origin <head>:<head>
+```
+
+Compute the diff range as `origin/<base>..origin/<head>` (or the local
+refs if already fetched).
+
+### 4. Run /council with the pr mode preamble
+
+Invoke `/council diff:<base>..<head>` with:
+
+- `original_ask` = PR title + body (capped per
+  `bundler.size_guard`; warn if truncated).
+- The neutrality preamble uses the `pr` mode addendum from
+  `scripts/ai_council/prompts.py` — focuses members on
+  PR-specific risks (shipping risk, reviewer fatigue, scope creep)
+  on top of the generic diff focus (correctness, security, tests,
+  maintainability).
+
+The cost gate from `/council` Step 3 still applies. Council is
+billable; suppress the question only when the resolved members are
+all-manual.
+
+### 5. Render the report
+
+Use the standard stacked + Convergence/Divergence layout from
+`/council` Step 6. Add a one-line PR header at the top:
+
+```
+## Council on PR #<number> — <title>
+
+Base: <base> · Head: <head> · Author: <author>
+```
+
+### 6. Offer to post a comment summary (opt-in)
+
+After the report renders, ask (in the user's language):
+
+> 1. Post a one-paragraph summary as a PR comment? (read-only otherwise)
+> 2. Skip — keep the council output local
+
+If picked **1**:
+
+- Build a short summary: convergent points, divergent points, suggested
+  actions. Keep it ≤ 800 chars.
+- Run `gh pr comment <number> --body "<summary>"`.
+- **Never** request changes, approve, or merge — comment only.
+
+Suppress the comment offer when `personal.autonomy: on` (posting to a
+public PR is a write operation that should always be explicit).
+
+### Hard floor (restated)
+
+`/council-pr` produces **text** and (on user opt-in) a **single PR
+comment**. It does **NOT**:
+
+- Approve, request changes, or merge a PR.
+- Edit project files.
+- Open new issues or PRs.
+- Post comments without explicit user opt-in.
+
+## Failure modes
+
+- **`gh` not installed / not authed** → state the install command
+  (`brew install gh && gh auth login`) and stop.
+- **PR is closed / merged** → ask whether to proceed (council on a
+  closed PR is fine for retrospectives) or cancel.
+- **Diff too large** → bundler raises `BundleTooLarge`; suggest
+  `/council files:<paths>` for a narrower review.
+
+## See also
+
+- `/council` — base orchestration entry point.
+- `ai-council` skill — neutrality guidelines.
+- `/review-changes` — internal four-judge variant for local diffs.

package/.agent-src/commands/council.md

@@ -0,0 +1,219 @@
+---
+name: council
+cluster: optimize
+skills: [ai-council]
+description: Consult external AIs (OpenAI, Anthropic) for an independent second opinion on a prompt, roadmap, diff, or file set — neutral framing, redacted context, advisory output only.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "external second opinion, cross-AI review, devil's advocate on a plan/roadmap/diff, polling another model"
+  trigger_context: "user wants an outside critique on an artefact (roadmap, diff, prompt, files) without polluting the reviewer with the host agent's framing"
+---
+
+# council
+
+## Instructions
+
+### 1. Resolve the target + capture the original ask
+
+The user invoked `/council` on exactly one input mode:
+
+- `prompt:"<text>"` — a free-form question or proposal
+- `roadmap:<path>` — a roadmap file under `agents/roadmaps/`
+- `diff:<base>..<head>` — a git diff range
+- `files:<path>,<path>` — a comma-separated file list
+
+Optional invocation flag: `mode:api|manual` overrides the per-member
+and global mode for this call only (see Step 2.5). `mode:playwright`
+is reserved for Phase 2c — refuse politely if invoked.
+
+Optional **rounds**: `rounds:N` (1-3) enables multi-round debate. Round
+1 sees the artefact alone. Round 2+ sees the artefact plus anonymised
+critiques from the previous round (provider/model identity stripped).
+Total spend = N × single-round cost; surface this in the cost gate.
+Default `rounds:1` (single round, v1 behaviour).
+
+Optional **mode_override**: `mode_override=pr|design|optimize` swaps
+the system-prompt addendum for one of the specialised lenses
+(see `prompts.py` `_MODE_TABLE`). The bundle mode (`prompt:` /
+`roadmap:` / `diff:` / `files:`) is unchanged; only the per-mode
+neutrality addendum is replaced. Routed by `/council-pr`,
+`/council-design`, `/council-optimize` — surface to the user as
+"council on <target> — <lens> lens" so the report header is
+unambiguous.
+
+If none was supplied, ask the user which mode + target. **One question
+per turn** (per `ask-when-uncertain`). Do not assume the working-tree
+diff.
+
+Also capture the user's **original ask** verbatim — the free-form
+sentence that triggered the council, distinct from the bundled
+artefact. For `prompt:"…"` mode the ask and the artefact are the
+same string. For `roadmap` / `diff` / `files` modes, the ask is the
+user's framing sentence ("review this roadmap before I execute it",
+"is this diff safe to merge?"). This string flows into
+`consult(..., original_ask=…)` in Step 5 so council members receive
+the neutral handoff preamble alongside the artefact (per
+`ai-council` skill § Neutrality — context-handoff).
+
+### 2. Check the council is configured + price table fresh
+
+Read `.agent-settings.yml` → `ai_council`:
+
+- If `ai_council.enabled` is false → state that and offer to flip it
+  on. Do not flip it autonomously.
+- If no member has `enabled: true` → list the install commands
+  (`./agent-config keys:install-anthropic`, `./agent-config keys:install-openai`)
+  and stop.
+- If a member is enabled but its `*.key` file is missing or has the
+  wrong mode → tell the user which key to install. Do not fall back to
+  env vars. Ever.
+
+Load the price table via `scripts.ai_council.pricing.load_prices()`
+(auto-bootstraps `.agent-prices.md` from defaults if missing). Run
+`pricing.is_stale(table)` and, if stale, surface the staleness gate
+from the `ai-council` skill (§ Stale price-table gate) before
+continuing.
+
+### 2.5. Resolve per-member execution mode
+
+For each enabled member, resolve its mode via
+`scripts.ai_council.modes.resolve_mode(name, invocation_mode,
+member_settings, global_mode)`. Precedence: invocation flag >
+per-member setting > global setting > default (`api`).
+
+Construct each member from the resolved mode:
+
+- `api` → `AnthropicClient` / `OpenAIClient` (billable, cost-gated).
+- `manual` → `ManualClient` from `scripts.ai_council.clients`
+  (`billable=False`, no API key, no SDK call).
+- `playwright` → reserved for Phase 2c. If a settings/invocation
+  resolves to it, refuse with a one-line note.
+
+### 3. Cost confirmation — ALWAYS ASK for billable members
+
+Council calls to billable members spend money. Even under
+`personal.autonomy: on`, the agent **must** ask before invoking any
+billable member.
+
+Compute `orchestrator.estimate(question, members, table)` over the
+**billable** subset only (`getattr(m, "billable", True)`). Manual
+members contribute `$0` and skip the estimate.
+
+Render the cost-confirmation numbered-options block per the
+`ai-council` skill (§ Pre-call estimate format) — per-member tokens
++ USD, projected total, budget caps, then `1. Run / 2. Cancel`. If
+the resolved member set is **all-manual**, skip the gate entirely
+(spend = $0) and proceed directly to Step 4.
+
+Wait for the user's pick. `1` proceeds; anything else aborts.
+
+### 4. Bundle the context
+
+Use `scripts.ai_council.bundler`:
+
+- `prompt` mode → `bundle_prompt(text)`
+- `roadmap` mode → `bundle_roadmap(path)`
+- `diff` mode → `bundle_diff(base, head)`
+- `files` mode → `bundle_files(paths)`
+
+The bundler runs redaction + size guard. If `BundleTooLarge` raises,
+surface the byte count and ask the user to narrow scope. Do **not**
+truncate silently.
+
+Print the manifest (what was included) and the excluded list before
+sending — gives the user a chance to abort if scope is wrong.
+
+### 5. Run the orchestrator
+
+Members are constructed from the settings file plus
+`load_anthropic_key()` / `load_openai_key()`. Cost budget comes from
+`ai_council.cost_budget`.
+
+Detect project context once via
+`scripts.ai_council.project_context.detect_project_context()` (reads
+`composer.json`, `package.json`, root `README.md` — never raises;
+empty-fields fall back to bare neutrality preamble).
+
+Call:
+
+```python
+consult(
+    members, question, budget,
+    table=table,
+    on_overrun=_handle_overrun,
+    project=project,
+    original_ask=original_ask,
+    rounds=rounds,  # 1 by default; 2-3 enables multi-round debate
+)
+```
+
+`project` + `original_ask` flow into `handoff_preamble()` so each
+member receives a neutral context-handoff alongside the artefact
+(see `ai-council` skill § Neutrality — context-handoff). Members run
+**sequentially**; per-member errors are normalised — one failure
+does not abort the others. Define `_handle_overrun(event)` per the
+`ai-council` skill (§ Mid-flow overrun callback) to surface the user
+prompt before each breaching member.
+
+### 6. Render the report
+
+Use `scripts.ai_council.orchestrator.render(responses)` for the
+per-member sections (stacked, not side-by-side — narrow terminals).
+Then write the **Convergence / Divergence** section yourself:
+
+- **Agreements** — points all members made (or did not contradict).
+- **Disagreements** — points where members took opposing positions.
+- **Unique insights** — points raised by exactly one member.
+- **Suggested next actions** — translated into concrete options for
+  the user.
+
+End with a numbered-options block asking the user how to proceed
+(e.g. update the roadmap, request a second round, ignore the
+critique).
+
+### 7. Hard floor — text only
+
+`/council` produces **text**. It does **NOT**:
+
+- Edit any file in the project.
+- Open, comment on, or merge any PR.
+- Run `git` commands beyond `git diff` (read-only).
+- Persist API responses outside the current chat unless the user
+  explicitly asks (Phase 4 — out of scope for v1).
+
+This is restated in step 7 deliberately. The neutrality framing
+loses meaning if the council can act on the project directly.
+
+## Failure modes
+
+- **Member SDK not installed** → tell the user exactly which `pip
+  install` runs (`pip install anthropic` / `pip install openai`).
+  Do not fall back to mocks.
+- **Key file mode drift** → refuse and point at the install script.
+  The 0600 contract is non-negotiable.
+- **Manual mode + non-interactive stdin** → `ManualClient` reads
+  pasted replies from stdin terminated by a line containing only
+  `END`. If stdin is closed before any reply lands, the member
+  returns empty text with `error="manual_aborted"`; render the
+  partial result and ask the user.
+- **Invalid mode value** → `resolve_mode()` raises
+  `InvalidModeError` with the exact settings path. Surface verbatim
+  and stop.
+- **Cost budget exceeded mid-fan-out** → render the partial
+  responses and clearly mark the unfinished members with their
+  `cost_budget_exceeded` error. Do not silently retry.
+- **Stale price table, refresher fails (offline)** → state the
+  failure, re-offer "continue with stale table / cancel", do not
+  proceed silently.
+- **`.agent-prices.md` corrupt (missing frontmatter or columns)** →
+  surface the parse error, suggest deleting the file to bootstrap
+  fresh from defaults; never silently fall back.
+- **All members error** → render the errors and ask the user
+  whether to fix and retry, or abort.
+
+## See also
+
+- `ai-council` skill — neutrality guidelines, anti-patterns, redaction expectations.
+- `subagent-orchestration` skill — internal multi-agent variant (no network calls).
+- `docs/customization.md` § Available settings → `ai_council.*`.

package/.agent-src/commands/create-pr.md

@@ -33,6 +33,29 @@ fallback structure defined in `/create-pr-description`. NEVER invent a custom bo
 
 The user reviews and adjusts the content in that step.
 
+### 2b. Offer council review (B2 hook)
+
+If `.agent-settings.yml` has `ai_council.enabled: true` **and** at least
+one member is enabled, ask (in the user's language):
+
+> 1. Run the council on this diff before opening the PR? (billable)
+> 2. Skip council review
+
+Suppress when `personal.autonomy: on` (council is billable; autonomy
+must not silently spend — see `road-to-ai-council.md` Decision 3).
+
+If picked **1**:
+
+- Compute the diff range — `origin/<default>..HEAD` from step 1.
+- Run `/council diff:<base>..<head>` with `original_ask` set to the
+  PR title from step 2 (the user's framing of the change).
+- Surface findings to the user before step 3. **Do not** auto-edit
+  the PR body or block PR creation — output is advisory.
+- Optional: offer to append a one-paragraph "Council notes" section
+  to the PR description for reviewer transparency. Default: skip.
+
+If picked **2** → continue.
+
 ### 3. Create the PR
 
 Once the user approves the content from step 2:

package/.agent-src/commands/do-and-judge.md

@@ -1,6 +1,6 @@
 ---
 name: do-and-judge
-skills: [subagent-orchestration, verify-before-complete]
+skills: [subagent-orchestration, verify-completion-evidence]
 description: Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
 disable-model-invocation: true
 suggestion:
@@ -90,7 +90,7 @@ Next step:  <commit / open PR / abandon>
 - No apply without the judge's `apply` verdict
 - No silent model fallback — unknown alias = stop and ask
 - No more than two revisions without user consent
-- No skipping of `verify-before-complete` on the final apply
+- No skipping of `verify-completion-evidence` on the final apply
 
 ## When to stop and ask
 
@@ -113,5 +113,5 @@ weaker verdicts.
 ## See also
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
-- [`verify-before-complete`](../skills/verify-before-complete/SKILL.md)
+- [`verify-completion-evidence`](../skills/verify-completion-evidence/SKILL.md)
 - [`subagent-configuration`](../contexts/subagent-configuration.md)

package/.agent-src/commands/do-in-steps.md

@@ -1,6 +1,6 @@
 ---
 name: do-in-steps
-skills: [subagent-orchestration, verify-before-complete]
+skills: [subagent-orchestration, verify-completion-evidence]
 description: Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
 disable-model-invocation: true
 suggestion:
@@ -57,7 +57,7 @@ On stop, report the last verified state so the user can resume.
 
 ### 5. Final verification
 
-After step N passes judgment, run `verify-before-complete` across the
+After step N passes judgment, run `verify-completion-evidence` across the
 whole changeset — targeted tests + full suite + quality pipeline.
 Never declare the plan "done" without this gate.
 
@@ -77,11 +77,11 @@ Next step:  <commit / open PR / resume from step K>
 
 - Never skip a step because the next one looks easier
 - Never apply a revised step without the judge re-verdicting
-- Never declare complete without final `verify-before-complete`
+- Never declare complete without final `verify-completion-evidence`
 - A failing step never cascades silently — stop, report, hand back
 
 ## See also
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
-- [`verify-before-complete`](../skills/verify-before-complete/SKILL.md)
+- [`verify-completion-evidence`](../skills/verify-completion-evidence/SKILL.md)
 - [`/do-and-judge`](do-and-judge.md) — single-change variant

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

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

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

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

package/.agent-src/commands/feature-dev.md

@@ -8,6 +8,14 @@ suggestion:
   trigger_description: "build this feature end-to-end, run the full feature workflow"
   trigger_context: "long-form feature description spanning multiple components"
 ---
+
+<!-- F2-deprecation-banner -->
+> **Deprecated — use `/feature dev`.** This standalone command
+> is kept as a deprecation shim for one release cycle and routes to
+> the same instructions below. New invocations should go through the
+> `/feature` orchestrator (`commands/feature.md`).
+<!-- /F2-deprecation-banner -->
+
 # /feature-dev
 
 > Full 7-phase feature development workflow for complex features.

package/.agent-src/commands/feature-explore.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "brainstorm this idea, explore this feature concept"
   trigger_context: "open-ended feature idea without acceptance criteria"
+superseded_by: feature explore
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-explore is deprecated; use /feature explore instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # feature-explore
 
 ## Instructions
@@ -181,4 +186,4 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)

package/.agent-src/commands/feature-plan.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "plan this feature, create a feature spec for X"
   trigger_context: "feature idea referenced and no plan doc exists"
+superseded_by: feature plan
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-plan is deprecated; use /feature plan instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # feature-plan
 
 ## Instructions
@@ -111,7 +116,7 @@ Before asking detailed questions, **proactively research**:
   `status: active` is a binding constraint — propose structure that
   respects it. If the feature needs to contradict an ADR, surface that
   as a decision for the user before drafting the plan. See
-  [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md).
+  [`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md).
 
 **Share key findings with the user** — this informs the discussion:
 
@@ -208,6 +213,32 @@ Mir sind noch ein paar offene Fragen aufgefallen:
 Hast du dazu schon eine Meinung?
 ```
 
+### 5d. Offer council idea-validation (B4 hook)
+
+Once the conversation has converged on a problem statement, proposal,
+and rough scope (rounds 1–4), but **before** step 6 writes the file,
+ask (in the user's language):
+
+> 1. Run the council on this idea before writing the plan? (billable)
+> 2. Skip — write the plan now
+
+Suppress when `personal.autonomy: on` (council is billable).
+
+If picked **1**:
+
+- Build a short prompt: the problem, the proposal, the scope, the
+  open questions from round 4. **Do not** include the agent's
+  framing or recommendations — neutrality preamble is mandatory.
+- Run `/council prompt:"<assembled prompt>"` with `original_ask` set
+  to the feature title from step 1.
+- Surface convergent + divergent points back to the user. **Do not**
+  rewrite the proposal autonomously; let the user decide which
+  council points to fold in.
+- After the user has reviewed, return to step 6 with the (possibly
+  updated) proposal.
+
+If picked **2** → continue.
+
 ### 6. Create the feature document
 
 - Read `.augment/templates/features.md` for the structure.
@@ -287,6 +318,6 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
 - [`refine-ticket`](refine-ticket.md) — optional upstream step: run first when the input is a Jira/Linear ticket rather than a fresh idea
 - [`estimate-ticket`](estimate-ticket.md) — sibling of `refine-ticket`; size + risk + split recommendation for an already-refined ticket

package/.agent-src/commands/feature-refactor.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "update the feature plan, refine the feature spec"
   trigger_context: "existing agents/features/*.md referenced in the prompt"
+superseded_by: feature refactor
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-refactor is deprecated; use /feature refactor instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # feature-refactor
 
 ## Instructions