@event4u/agent-config 2.10.0 → 2.12.0

package/docs/contracts/decision-engine-gates.md

@@ -0,0 +1,115 @@
+# Decision-engine gates (v1)
+
+**Status:** beta — landed 2026-05-14 via `road-to-productization.md` Phase 2.
+**Owners:** `work_engine` maintainers.
+**Scope:** the optional `decision_engine:` block in `.agent-settings.yml`.
+
+## Purpose
+
+Cross the package from **observable** (Level-5) to **controllable**
+(Level-6). The engine has scored confidence-bands, risk-classes, and
+memory-hits since Phase 4 of `road-to-decision-trace`; this contract
+turns those signals into refusal gates the user opts into.
+
+Absent block = unchanged behaviour. Enforcement is opt-in only; the
+engine never silently halts on a signal the user did not configure.
+
+## Schema
+
+All keys optional. Unknown keys are rejected hard by
+`scripts/validate_decision_engine.py` and by
+`work_engine.scoring.decision_engine.parse`.
+
+| Key                    | Type            | Default | Notes |
+|------------------------|-----------------|---------|-------|
+| `surface_traces`       | bool            | `false` | Mirrored to `DecisionTraceHook`. Predates the gates; lives here so the block has one schema. |
+| `min_confidence`       | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Plan floor. |
+| `block_on_risk`        | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Implement ceiling. |
+| `require_memory_hits`  | bool            | `false` | Phase=Refine demands `memory_hits >= 1`. |
+| `on_block`             | enum            | `stop`  | `stop` \| `ask` \| `warn`. Action when a gate fires. |
+| `ask_timeout_seconds`  | int (>= 0)      | `30`    | Non-TTY wait before applying `on_block_fallback`. |
+| `on_block_fallback`    | enum            | `stop`  | `stop` \| `warn`. Resolution after `ask_timeout`. |
+
+## Gate-to-phase mapping
+
+Each gate fires on exactly one phase. The dispatcher emits gate
+decisions on `AFTER_STEP` for that phase only.
+
+| Gate                  | Phase     | Signal compared             | Fires when                          |
+|-----------------------|-----------|-----------------------------|-------------------------------------|
+| `min_confidence`      | Plan      | `confidence_band`           | actual < floor                      |
+| `require_memory_hits` | Refine    | `state.memory.hits`         | hits < 1                            |
+| `block_on_risk`       | Implement | `risk_class`                | actual >= ceiling                   |
+
+`low` < `medium` < `high` for both confidence and risk. `off` disables
+the gate.
+
+## Conflict matrix
+
+Only one gate fires per phase, so cross-phase conflicts are impossible
+by construction. Within a phase, **only the highest-impact gate
+applies**; downstream gates are evaluated against the same phase but
+skipped if a higher-priority gate already fired.
+
+Priority (highest → lowest):
+
+1. `block_on_risk` (Implement)
+2. `require_memory_hits` (Refine)
+3. `min_confidence` (Plan)
+
+This priority surfaces only when a future schema adds gates that
+overlap on the same phase; today each gate owns a unique phase and the
+priority is documentary. The order is locked so future additions
+inherit the contract.
+
+### Worked examples
+
+| Config                                                                                | Phase     | confidence | risk     | hits | Outcome                          |
+|---------------------------------------------------------------------------------------|-----------|------------|----------|------|----------------------------------|
+| `min_confidence: medium`                                                              | Plan      | `low`      | -        | -    | `min_confidence` fires, action=stop |
+| `min_confidence: medium`                                                              | Plan      | `high`     | -        | -    | no fire — band at/above floor    |
+| `block_on_risk: medium`                                                               | Implement | -          | `high`   | -    | `block_on_risk` fires, action=stop |
+| `block_on_risk: high`                                                                 | Implement | -          | `medium` | -    | no fire — below ceiling          |
+| `require_memory_hits: true`                                                           | Refine    | -          | -        | 0    | `require_memory_hits` fires      |
+| `require_memory_hits: true`                                                           | Refine    | -          | -        | 2    | no fire                          |
+| `min_confidence: high, block_on_risk: low, require_memory_hits: true` (all on)        | Plan      | `low`      | `low`    | 0    | `min_confidence` fires (Plan-owning gate) — Refine/Implement gates inert this phase |
+
+## Non-TTY timeout protocol
+
+`on_block=ask` is interactive. In a non-interactive context the
+engine cannot block waiting for keystrokes that will never arrive.
+Detection follows two signals (either disables interactivity):
+
+- environment variable `CI` set to `1`, `true`, `yes` (case-insensitive)
+- `sys.stdin.isatty()` or `sys.stdout.isatty()` returns false
+
+When non-interactive, `on_block=ask` collapses to action `ask_timeout`.
+The consumer (CLI / dispatcher) is expected to:
+
+1. wait `ask_timeout_seconds` for a stdin response;
+2. apply `on_block_fallback` (`stop` or `warn`) when the timeout
+   elapses or stdin is closed;
+3. surface `block_reason=ask_timeout` on the decision trace so the
+   reason is replay-visible.
+
+Default fallback is `stop` (fail-safe). Flip to `warn` only when CI
+explicitly wants advisory gates.
+
+## Rollback
+
+The block is config-only. Remove the `decision_engine:` block and
+the engine reverts to observe-only behaviour — no migration, no DB
+state, no schema lock. Per-key removal also works (each key has a
+safe default).
+
+## Test surface
+
+Coverage lives in `tests/work_engine/scoring/test_decision_engine.py`:
+
+- schema parser: defaults, unknown-key rejection, bad-type rejection;
+- gate evaluation: per-phase, per-signal, conflict isolation;
+- TTY detection: env-var detection, fallback to `ask_timeout`;
+- action resolution: `stop` / `warn` short-circuit interactivity.
+
+Wiring tests (dispatcher + hook) live in
+`tests/work_engine/test_decision_gate_hook.py`.

package/docs/contracts/decision-trace-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Decision-trace v1

package/docs/contracts/file-ownership-matrix.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # File-ownership matrix

package/docs/contracts/hook-architecture-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Hook architecture v1

package/docs/contracts/implement-ticket-flow.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `/implement-ticket` — Flow Contract

package/docs/contracts/installed-tools-lockfile.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Installed-Tools Lockfile — Wire Contract

package/docs/contracts/kernel-membership.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linear AI — rules inclusion list

package/docs/contracts/linear-ai-three-layers.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linear AI — three-layer split rationale

package/docs/contracts/linter-structural-model.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linter Structural Model

package/docs/contracts/load-context-budget-model.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `load_context:` Budget Accounting Model

package/docs/contracts/load-context-schema.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `load_context:` Frontmatter Schema

package/docs/contracts/memory-visibility-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Memory-visibility v1

package/docs/contracts/one-off-script-lifecycle.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # One-off-script lifecycle

package/docs/contracts/orchestration-dsl-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Orchestration DSL v1

package/docs/contracts/package-self-orientation.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Package Self-Orientation

package/docs/contracts/persona-schema.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Persona Schema — two-tier (Core / Specialist)

package/docs/contracts/release-trunk-sync.md

@@ -0,0 +1,104 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# ADR — Release-trunk sync: main fast-forwards on every tag
+
+> **Status:** Decided · 2026-05-14
+> **Context:** PR #43 feedback (Level-5/6 product rating) and PR #143
+> revealed `main` lagging the latest tag by N skills + rules at multiple
+> points across the 2.x cycle. External readers landing on `main`
+> consistently saw stale README counts and missing skill catalogues
+> relative to the npm/Packagist artefact.
+> **Closes:** [Road to Productization](../../agents/roadmaps/road-to-productization.md) § P1.2.
+
+## Decision
+
+Every tagged release (`X.Y.Z`) **fast-forwards `main` to the tag's
+commit as the final step of the release pipeline**. No exceptions. No
+grace period.
+
+The fast-forward is owned by [`scripts/release.py`](../../scripts/release.py)
+and runs after the GitHub Release is published. The release pipeline
+is **not green** until `main == <new-tag>` at the remote.
+
+`main` is therefore a **moving stable trunk pointer**, not a feature
+branch. External readers (README, AGENTS.md, marketplace metadata, npm
+tarball provenance) reading `main` see the artefact that was last
+published, not work-in-progress.
+
+## Protocol
+
+1. `scripts/release.py` cuts `release/X.Y.Z`, bumps version files,
+   opens a release PR against `main`, waits for CI, merges.
+2. The merge commit on `main` becomes the tag's commit; the tag is
+   pushed.
+3. `publish-npm.yml` and the marketplace flow trigger on the tag.
+4. The release pipeline asserts `git rev-parse origin/main ==
+   git rev-parse refs/tags/X.Y.Z` before exit-0.
+5. If a hotfix lands on `release/X.Y.Z` after step 1 but before step 4,
+   the FF still happens — release-branch commits are part of the
+   release, not a separate trunk.
+
+### Why fast-forward, not merge
+
+Fast-forward keeps `main` linear with the tag history. A merge-commit
+on top of the tag would put `main` at a SHA that is **not** the tag's
+SHA, re-introducing the exact divergence this contract closes.
+
+If a fast-forward is impossible (force-push to `main`, divergent
+history, abandoned release-prep), the pipeline **fails loudly**; the
+operator either resets `main` manually with an audit trail or aborts
+the release.
+
+## CI Gate (P1.3)
+
+[`scripts/check_release_trunk_sync.py`](../../scripts/check_release_trunk_sync.py)
+runs on every `release/X.Y.Z` branch (detected by `git rev-parse
+--abbrev-ref HEAD` matching `^release/\d+\.\d+\.\d+$`).
+
+It enforces: **`main` is at most ONE tagged release behind the
+release-prep branch's target version.**
+
+- On `release/2.11.0`: `main` may be at `2.10.0` or `2.11.0`. `2.9.0`
+  or older → **hard fail**.
+- On any other branch class (feature, fix, chore, docs, the agent's
+  own `feat/road-to-productization` branch): the check is a **no-op**
+  exit-0 — feature branches never trip the gate.
+- Wired into `task ci` as `check-release-trunk-sync`. No warning-only
+  mode; the exit code is the gate.
+
+### Bootstrap mode
+
+When the repo state does not yet match the gate (transitional first
+run after this contract lands), the check reads
+`docs/contracts/release-trunk-sync.bootstrap` for an opt-out window
+keyed by current version. The bootstrap file is purged at the next
+release. Absence of the file = gate is live.
+
+## Rollback
+
+Revertible by removing `check-release-trunk-sync` from `Taskfile.yml`
+and deleting `scripts/check_release_trunk_sync.py`. No state, no
+schema, no migration. Branch-detection key (`release/X.Y.Z`) is
+already used by `scripts/release.py` so removing this contract does
+not orphan the convention.
+
+## Risks
+
+| # | Risk | Mitigation |
+|---|---|---|
+| 1 | Gate fires on feature branches mid-PR | Branch-name regex; non-`release/` branches no-op exit-0 |
+| 2 | Hotfix release leaves `main` behind | FF runs **after** hotfix commits land on the release branch |
+| 3 | Manual tag (no `scripts/release.py`) skips the FF | Out of scope of this contract — covered by `release-guard.yml` which fails on tag/version mismatch; manual tags already break the pipeline |
+| 4 | Detached HEAD or shallow checkout breaks detection | Check gracefully exits-0 with a `::warning::` line when `git rev-parse --abbrev-ref HEAD == HEAD` (detached) |
+
+## See also
+
+- [`scripts/release.py`](../../scripts/release.py) — release pipeline owner.
+- [`.github/workflows/release-guard.yml`](../../.github/workflows/release-guard.yml)
+  — tag/version-file integrity gate (orthogonal: this contract handles
+  trunk position, release-guard handles version-string integrity).
+- [`agents/roadmaps/road-to-productization.md`](../../agents/roadmaps/road-to-productization.md)
+  § Phase 1.

package/docs/contracts/roadmap-complexity-standard.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Roadmap Complexity Standard

package/docs/contracts/rule-classification.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/rule-interactions.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Rule-Interaction Matrix
@@ -99,6 +100,31 @@ junior (yields). For `complements`, ordering is documentary only.
   in the rule files.
 - Skill ↔ rule interactions — the matrix is rule-only. Skills are
   invoked, not always-active.
+- **Orchestration-layer surfaces** (AI Council, Memory, Work-Engine /
+  Decision-Engine): these are runtime systems, not `always`-rules.
+  Their interactions are governed by their own contracts and stay
+  out of this matrix by design — see "Out of scope" below.
+
+## Out of scope — orchestration surfaces (Council × Memory × Work-Engine)
+
+The matrix is **rule-only**. The orchestration layer is governed by
+dedicated contracts; cross-referencing them here would duplicate the
+source of truth and weaken it. Canonical contracts:
+
+| Surface | Canonical contract |
+|---|---|
+| Decision-Engine gates (`min_confidence`, `block_on_risk`, `require_memory_hits`, `on_block`) | [`decision-engine-gates.md`](decision-engine-gates.md) |
+| Decision-trace shape (what the engine emits per phase) | [`decision-trace-v1.md`](decision-trace-v1.md) |
+| Memory contract (entries, scopes, retention) | [`agent-memory-contract.md`](agent-memory-contract.md) |
+| Memory visibility in the trace (`affected` keys) | [`memory-visibility-v1.md`](memory-visibility-v1.md) |
+| AI-Council consultation flow | [`../skills/ai-council/SKILL.md`](../../.agent-src.uncompressed/skills/ai-council/SKILL.md) |
+
+Where an `always`-rule **does** interact with one of these surfaces
+(e.g. `non-destructive-by-default` gating a memory-driven action), the
+gate lives in the rule and the precedence is captured in this matrix
+as a rule-pair (the orchestration surface is the *occasion*, not a
+participant). For Council ↔ Memory ↔ Work-Engine interactions among
+themselves, the dedicated contracts above are authoritative.
 
 ## See also
 

package/docs/contracts/rule-priority-hierarchy.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Rule Priority Hierarchy

package/docs/contracts/rule-router.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/settings-sync-yaml-subset.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Settings-sync YAML subset

package/docs/contracts/skill-domains.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Skill Domains — 6-domain taxonomy

package/docs/contracts/tier-3-contrib-plugin.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Tier-3 contrib plugin pattern

package/docs/contracts/ui-stack-extension.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # UI Stack Extension — adding a new frontend stack to the UI track

package/docs/contracts/ui-track-flow.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # UI Track — Flow Contract

package/docs/customization.md

@@ -139,7 +139,7 @@ Rules:
 | Setting | Default | Description |
 |---|---|---|
 | `agent_config_version` | *(empty)* | Exact semver pin of the agent-config release (see above). Empty = unpinned. |
-| `cost_profile` | `minimal` | Token budget (`minimal`, `balanced`, `full`, `custom`) |
+| `cost_profile` | `balanced` | Token budget (`minimal`, `balanced`, `full`, `custom`) — rationale: [`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md) |
 | `personal.user_name` | *(empty)* | User's first name for personalized responses |
 | `personal.minimal_output` | `true` | Suppress intermediate output |
 | `personal.play_by_play` | `false` | Share intermediate findings during analysis |

package/docs/getting-started.md

@@ -123,9 +123,11 @@ The system supports four configuration profiles:
 Set your profile in `.agent-settings.yml`:
 
 ```yaml
-cost_profile: minimal
+cost_profile: balanced
 ```
 
+`balanced` is the default — kernel + tier-1 auto-rules. Rationale:
+[`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md).
 You can override any individual setting. See [Customization](customization.md) for details.
 
 ---

package/docs/installation.md

@@ -240,8 +240,8 @@ wrapper (`./agent-config`) can fall through to it when no
 The orchestrator chains payload sync and bridge generation:
 
 ```bash
-bash scripts/install                  # defaults to cost_profile=minimal
-bash scripts/install --profile=balanced
+bash scripts/install                  # defaults to cost_profile=balanced
+bash scripts/install --profile=minimal
 bash scripts/install --force          # overwrite existing bridges
 bash scripts/install --skip-bridges   # payload only
 bash scripts/install --skip-sync      # bridges only
@@ -287,7 +287,7 @@ regardless of which AI tool they use.** No per-developer plugin installation nee
 After initial setup, commit these files:
 
 ```
-.agent-settings.yml                ← shared profile (e.g., cost_profile: minimal)
+.agent-settings.yml                ← shared profile (e.g., cost_profile: balanced)
 agents/installed-tools.lock        ← AI bill of materials (ADR-008, Phase 3)
 .augment/                          ← rules, skills, commands (symlinks)
 .cursor/rules/                     ← Cursor rules (symlinks)
@@ -517,16 +517,18 @@ The system works immediately with sensible defaults. Optionally, create `.agent-
 to choose a profile:
 
 ```yaml
-cost_profile: minimal
+cost_profile: balanced
 ```
 
 | Profile | What's active | For whom |
 |---|---|---|
-| `minimal` (default) | Rules + Skills only, zero overhead | New users, solo devs |
+| `minimal` | Kernel only — Iron-Law floor, zero router | Token-constrained agents |
 | `balanced` | + Runtime dispatcher + shell handler | Most teams |
 | `full` | + Tool adapters (GitHub, Jira) | Platform teams |
 
-No profile configured = `minimal` behavior. → [Full profile details](customization.md)
+No profile configured = `balanced` behavior (default). Rationale:
+[`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md).
+→ [Full profile details](customization.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.10.0",
+    "version": "2.12.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/ai_council/clients.py

@@ -53,6 +53,19 @@ def _resolve_key_path(filename: str) -> Path:
 DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5"
 DEFAULT_OPENAI_MODEL = "gpt-4o"
 
+#: Per-call output budget when no caller-supplied value reaches `ask()`.
+#: The CLI resolves the live default from `ai_council.max_output_tokens`
+#: in `.agent-settings.yml`; this constant is only the abstract-base /
+#: direct-API fallback when nothing else is wired up.
+DEFAULT_MAX_TOKENS = 2048
+
+#: Expansion target when the user sets `max_output_tokens: 0` ("unlimited")
+#: in settings. Anthropic requires `max_tokens` to be a positive integer,
+#: so 0 is widened to this safe ceiling before the SDK call. Big enough
+#: for current frontier models (Sonnet/GPT-4o headroom ≥ 16k); raise
+#: explicitly in settings if a larger budget is genuinely needed.
+UNLIMITED_TOKENS_FALLBACK = 16384
+
 # OpenAI reasoning models (o1, o3, o4 families) reject `max_tokens` and the
 # `system` role; they require `max_completion_tokens` and accept only `user`
 # (and `developer`) messages.
@@ -128,7 +141,7 @@ class ExternalAIClient(ABC):
         self,
         system_prompt: str,
         user_prompt: str,
-        max_tokens: int = 1024,
+        max_tokens: int = DEFAULT_MAX_TOKENS,
     ) -> CouncilResponse:
         """Send one independent query. Must never raise on network/API
         failure — return a `CouncilResponse` with `error` set instead.
@@ -162,7 +175,7 @@ class AnthropicClient(ExternalAIClient):
             ) from exc
         self._client = anthropic.Anthropic(api_key=api_key)
 
-    def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = 1024) -> CouncilResponse:
+    def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = DEFAULT_MAX_TOKENS) -> CouncilResponse:
         t0 = time.monotonic()
         try:
             response = self._client.messages.create(
@@ -218,7 +231,7 @@ class OpenAIClient(ExternalAIClient):
             ) from exc
         self._client = openai.OpenAI(api_key=api_key)
 
-    def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = 1024) -> CouncilResponse:
+    def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = DEFAULT_MAX_TOKENS) -> CouncilResponse:
         t0 = time.monotonic()
         kwargs: dict[str, object] = {"model": self.model}
         if _is_reasoning_model(self.model):
@@ -316,7 +329,7 @@ class ManualClient(ExternalAIClient):
         self,
         system_prompt: str,
         user_prompt: str,
-        max_tokens: int = 1024,  # noqa: ARG002 — accepted for ABC parity
+        max_tokens: int = DEFAULT_MAX_TOKENS,  # noqa: ARG002 — accepted for ABC parity
     ) -> CouncilResponse:
         t0 = time.monotonic()
         rounds: list[str] = []

package/scripts/ai_council/orchestrator.py

@@ -27,7 +27,11 @@ from scripts.ai_council.budget_guard import (
     today_spend_usd as _today_spend_usd,
     would_exceed as _would_exceed_daily,
 )
-from scripts.ai_council.clients import CouncilResponse, ExternalAIClient
+from scripts.ai_council.clients import (
+    DEFAULT_MAX_TOKENS,
+    CouncilResponse,
+    ExternalAIClient,
+)
 from scripts.ai_council.pricing import (
     CostEstimate,
     PriceTable,
@@ -51,7 +55,7 @@ class CostBudget:
 class CouncilQuestion:
     mode: str  # one of: prompt, roadmap, diff, files
     user_prompt: str  # bundled artefact text
-    max_tokens: int = 1024
+    max_tokens: int = DEFAULT_MAX_TOKENS
 
 
 @dataclass