@event4u/agent-config 1.15.0 → 1.17.0

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

@@ -0,0 +1,44 @@
+---
+name: context
+description: Context orchestrator — routes to create, refactor
+cluster: context
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a context document, update an existing context, refactor a context file"
+  trigger_context: "user wants to author or restructure a context document"
+---
+
+# /context
+
+Top-level orchestrator for the `/context` family. Replaces 2 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/context create` | `commands/context/create.md` | Analyze a codebase area and create a structured context document |
+| `/context refactor` | `commands/context/refactor.md` | Analyze, update, and extend an existing context document |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/context <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. create — author a new context document
+   > 2. refactor — update an existing context document
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/context <sub>` per turn.
+- If the user invokes `/context` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

package/.agent-src/commands/{copilot-agents-init.md → copilot-agents/init.md}

@@ -1,5 +1,7 @@
 ---
-name: copilot-agents-init
+name: copilot-agents:init
+cluster: copilot-agents
+sub: init
 description: Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers.
 skills: [copilot-config, copilot-agents-optimization, agent-docs-writing]
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Project init — only deliberately during onboarding."
 ---
 
-# /copilot-agents-init
-
+# /copilot-agents init
 Interactive initializer that **creates** `AGENTS.md` and
 `.github/copilot-instructions.md` in the consumer project from the
 package-shipped templates (`.augment/templates/AGENTS.md` and

package/.agent-src/commands/{copilot-agents-optimize.md → copilot-agents/optimize.md}

@@ -1,5 +1,7 @@
 ---
-name: copilot-agents-optimize
+name: copilot-agents:optimize
+cluster: copilot-agents
+sub: optimize
 description: Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience.
 skills: [copilot-agents-optimization, copilot-config, agent-docs-writing]
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Maintenance refactor; only when the maintainer chooses to run it."
 ---
 
-# /copilot-agents-optimize
-
+# /copilot-agents optimize
 Analyzes and refactors `AGENTS.md` and `.github/copilot-instructions.md` against the `.augment/` ecosystem.
 
 ## Steps

package/.agent-src/commands/copilot-agents.md

@@ -0,0 +1,44 @@
+---
+name: copilot-agents
+description: Copilot agents-doc orchestrator — routes to init, optimize
+cluster: copilot-agents
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create AGENTS.md, optimize copilot-instructions.md, scaffold copilot agent docs"
+  trigger_context: "user wants to author or tune AGENTS.md / copilot-instructions.md"
+---
+
+# /copilot-agents
+
+Top-level orchestrator for the `/copilot-agents` family. Replaces 2
+standalone commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/copilot-agents init` | `commands/copilot-agents/init.md` | Create AGENTS.md and `.github/copilot-instructions.md` from scratch |
+| `/copilot-agents optimize` | `commands/copilot-agents/optimize.md` | Refactor existing AGENTS.md and copilot-instructions.md for line budgets |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/copilot-agents <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. init — scaffold AGENTS.md + copilot-instructions.md from scratch
+   > 2. optimize — refactor existing files for budget and audience
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/copilot-agents <sub>` per turn.
+- If the user invokes `/copilot-agents` with no argument, **show the
+  menu** — do not guess which sub-command they meant.

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

@@ -0,0 +1,221 @@
+---
+name: council:default
+cluster: council
+sub: default
+skills: [ai-council]
+description: Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare.
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Default lens — invoked via /council dispatcher; no direct trigger."
+---
+
+# /council default
+
+Base orchestration entry point for the council. Specialised lenses
+(`/council pr`, `/council design`, `/council optimize`) wrap this same
+flow with mode-specific neutrality preambles.
+
+## Instructions
+
+### 1. Resolve the target + capture the original ask
+
+The user invoked `/council default` 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`.
+
+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 is unchanged; only
+the per-mode neutrality addendum is replaced. Routed by the
+`/council pr`, `/council design`, `/council optimize` sub-commands —
+surface to the user as "council on <target> — <lens> lens".
+
+If no input mode 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 (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
+
+- `/council` — cluster dispatcher.
+- `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/council/design.md

@@ -0,0 +1,97 @@
+---
+name: council:design
+cluster: council
+sub: design
+skills: [ai-council]
+description: Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "council on this design, second opinion on the ADR, external review of architecture proposal"
+  trigger_context: "user has a design doc / ADR / architecture proposal and wants an external review before commitment"
+---
+
+# /council design
+
+## Instructions
+
+Specialised council mode for **design documents, ADRs, and
+architecture proposals**. Wraps `/council files:<paths>` (or
+`/council prompt:"…"`) with the `design` mode neutrality preamble that
+focuses members on architectural risk rather than line-level
+correctness.
+
+### 1. Resolve the artefact
+
+The user invoked `/council design <path>` or `/council design`. If no
+path was supplied, ask (one question per turn):
+
+> Which design artefact should the council review?
+>
+> 1. A file path (ADR, design doc, RFC)
+> 2. Multiple files / a directory (the bundler will gather them)
+> 3. A free-form proposal in the chat — paste it now
+
+Pick **1** or **2** → use `files:` mode of `/council`.
+Pick **3** → use `prompt:` mode of `/council`.
+
+### 2. Capture the originating ask
+
+Look for the artefact's stated goal — the first paragraph after the
+title, or a `## Goal` / `## Problem` section if present. That goal is
+the `original_ask` for the handoff preamble. If the artefact has no
+goal section, ask the user (one question per turn):
+
+> What is the goal of this design? (one sentence — used as neutral
+> framing for the council, not their analysis)
+
+### 3. Run /council with the design mode preamble
+
+Invoke the matching `/council` form:
+
+- `files:` → `/council files:<paths>` with `mode_override=design`.
+- `prompt:` → `/council prompt:"<artefact text>"` with
+  `mode_override=design`.
+
+The `design` mode addendum from `scripts/ai_council/prompts.py`
+focuses council members on:
+
+- Trust-boundary and module-coupling risk.
+- Rollback / kill-switch criteria the design omits.
+- Sequencing risk (does step N really not block step N+1?).
+- Open questions disguised as decisions.
+
+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 reviewers know the lens:
+
+```
+## Council on <artefact path or "free-form proposal"> — design lens
+```
+
+### 5. Hand back to the user
+
+The council is **advisory**. Do **not** rewrite the design based on
+findings. Surface convergent + divergent points and let the user
+decide which to fold in via `/feature plan` or `/feature refactor`.
+
+### Hard floor (restated)
+
+`/council design` produces **text only**. It does NOT edit the
+design file, open ADR PRs, or modify the codebase.
+
+## Failure modes
+
+- **No artefact resolvable** → ask once; if still empty, stop.
+- **Artefact too large** → bundler raises `BundleTooLarge`; suggest
+  splitting (`/council files:<single-file>` per section).
+
+## See also
+
+- `/council` — base orchestration entry point.
+- `/feature plan` / `/feature refactor` — where design changes get
+  written, after the council surfaces issues.
+- `ai-council` skill — neutrality guidelines.

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

@@ -0,0 +1,116 @@
+---
+name: council:optimize
+cluster: council
+sub: 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,124 @@
+---
+name: council:pr
+cluster: council
+sub: pr
+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.