@event4u/agent-config 7.0.1 → 7.1.0

package/src/scripts/_lib/subagent_bundle.ts

@@ -0,0 +1,154 @@
+/**
+ * Subagent bundle resolver (Phase 2 / A2).
+ *
+ * Pure, no-I/O. Maps a task slice to a concrete subagent bundle by selecting
+ * from the EXISTING surfaces — role-modes, the `judge-*` review-lens skills,
+ * personas, knowledge-card refs, and an ADR-035 tier — instead of a new parallel
+ * registry. Feeds `composeSpawnBrief` (subagent_spawn.ts) real values.
+ *
+ * Contract: `src/agent-src/contexts/execution/subagent-spawn-contract.md`.
+ *
+ * ADR-100 guard: proprietary knowledge-card refs never enter a cross-project
+ * subagent bundle. The resolver drops them and records the drop.
+ */
+
+import type { RoleMode, SpawnSelection } from './subagent_spawn.js';
+
+export type Tier = 'lite' | 'medium' | 'high' | 'inherit';
+
+/** The well-known delegable slice kinds and their lens/role/tier mapping. */
+export type SliceKind =
+    | 'review'
+    | 'security'
+    | 'tests'
+    | 'bug-hunt'
+    | 'research'
+    | 'docs'
+    | 'refactor'
+    | 'plan';
+
+interface KindProfile {
+    /** Reuse a `judge-*` skill as a ready-made subagent role-profile, or null. */
+    judge_lens: string | null;
+    role_mode: RoleMode | null;
+    tier: Tier;
+}
+
+/**
+ * Slice-kind → bundle profile. The `judge-*` skills are reused as subagent
+ * role-profiles (the package already ships them as review lenses).
+ */
+const KIND_PROFILE: Record<SliceKind, KindProfile> = {
+    review: { judge_lens: 'judge-code-quality', role_mode: 'reviewer', tier: 'medium' },
+    security: { judge_lens: 'judge-security-auditor', role_mode: 'reviewer', tier: 'high' },
+    tests: { judge_lens: 'judge-test-coverage', role_mode: 'tester', tier: 'medium' },
+    'bug-hunt': { judge_lens: 'judge-bug-hunter', role_mode: 'developer', tier: 'medium' },
+    research: { judge_lens: null, role_mode: null, tier: 'lite' },
+    docs: { judge_lens: null, role_mode: null, tier: 'lite' },
+    refactor: { judge_lens: null, role_mode: 'developer', tier: 'high' },
+    plan: { judge_lens: null, role_mode: 'planner', tier: 'high' },
+};
+
+/** A knowledge-card ref tagged with its sharing tier (ADR-100). */
+export interface KnowledgeRef {
+    ref: string;
+    tier: 'public' | 'vendor' | 'proprietary';
+}
+
+export interface SliceInput {
+    kind: SliceKind;
+    task: string;
+    /** Active profile id (e.g. 'developer'), inherited from the session unless overridden. */
+    profile?: string | null;
+    /** Persona ids cited by the task's skill. */
+    personas?: string[];
+    /** Candidate knowledge-card refs (tier-tagged) for this slice. */
+    knowledge?: KnowledgeRef[];
+    /** Will this bundle be visible across project boundaries? */
+    cross_project?: boolean;
+}
+
+export interface ResolvedBundle {
+    selection: SpawnSelection;
+    judge_lens: string | null;
+    tier: Tier;
+    dropped_proprietary: number;
+    reason: string;
+}
+
+/**
+ * ADR-100 guard: keep refs whose tier is shareable in the bundle's visibility
+ * scope. In a cross-project bundle, `proprietary` refs are dropped.
+ */
+export function filterKnowledgeByPolicy(
+    knowledge: KnowledgeRef[],
+    cross_project: boolean,
+): { kept: string[]; dropped: number } {
+    const kept: string[] = [];
+    let dropped = 0;
+    for (const k of knowledge) {
+        if (cross_project && k.tier === 'proprietary') {
+            dropped += 1;
+            continue;
+        }
+        kept.push(k.ref);
+    }
+    return { kept, dropped };
+}
+
+/**
+ * Resolve a task slice into a subagent bundle: role-mode + reused judge lens +
+ * personas + ADR-100-filtered knowledge refs + tier. The result's `selection`
+ * is ready for `composeSpawnBrief`.
+ */
+export function resolveBundle(slice: SliceInput): ResolvedBundle {
+    const profile = KIND_PROFILE[slice.kind];
+    const cross = slice.cross_project === true;
+    const { kept, dropped } = filterKnowledgeByPolicy(slice.knowledge ?? [], cross);
+
+    // The reused judge lens rides as a persona-equivalent so the subagent loads it.
+    const personas = [...(slice.personas ?? [])];
+    if (profile.judge_lens && !personas.includes(profile.judge_lens)) {
+        personas.unshift(profile.judge_lens);
+    }
+
+    const selection: SpawnSelection = {
+        task: slice.task,
+        role_mode: profile.role_mode,
+        profile: slice.profile ?? null,
+        personas,
+        knowledge_refs: kept,
+    };
+
+    const reasonParts = [`kind=${slice.kind}`, `tier=${profile.tier}`];
+    if (profile.judge_lens) reasonParts.push(`lens=${profile.judge_lens}`);
+    if (dropped > 0) reasonParts.push(`dropped ${dropped} proprietary (cross-project)`);
+
+    return {
+        selection,
+        judge_lens: profile.judge_lens,
+        tier: profile.tier,
+        dropped_proprietary: dropped,
+        reason: reasonParts.join(' · '),
+    };
+}
+
+/**
+ * Auditable bundle signature for the orchestration-telemetry object — counts +
+ * ids only, never bodies (preserves the audit-log privacy floor).
+ */
+export function bundleAuditLine(b: ResolvedBundle): {
+    role_mode: RoleMode | null;
+    judge_lens: string | null;
+    tier: Tier;
+    knowledge_ref_count: number;
+    dropped_proprietary: number;
+} {
+    return {
+        role_mode: b.selection.role_mode ?? null,
+        judge_lens: b.judge_lens,
+        tier: b.tier,
+        knowledge_ref_count: b.selection.knowledge_refs?.length ?? 0,
+        dropped_proprietary: b.dropped_proprietary,
+    };
+}

package/src/scripts/_lib/subagent_response.ts

@@ -0,0 +1,82 @@
+/**
+ * Structured subagent-response envelope + synthesis helpers (Phase 3 / A3).
+ *
+ * Pure, no-I/O. Pins the body a subagent returns inside the 4-status envelope
+ * (the status stays the envelope; this is the body) and gives the orchestrator
+ * the synthesis duties: surface evidence gaps, and force the full cross-model
+ * judge when a mutating finding is low-confidence.
+ *
+ * Contract: `src/agent-src/contexts/execution/subagent-response-contract.md`.
+ */
+
+export type Confidence = 'low' | 'medium' | 'high';
+
+export interface Finding {
+    title: string;
+    /** Refs (file:line / id / path) backing this finding — never inline bodies. */
+    evidence_refs?: string[];
+    /** Does acting on this finding mutate files / state? */
+    mutating?: boolean;
+}
+
+export interface SubagentResponse {
+    summary: string;
+    findings: Finding[];
+    risks: string[];
+    confidence: Confidence;
+    handoff: string;
+}
+
+const CONFIDENCE: ReadonlySet<string> = new Set<Confidence>(['low', 'medium', 'high']);
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+
+/** Validate the envelope shape. Counts/refs only — reject inline-body evidence. */
+export function validateResponse(input: unknown): ValidationResult {
+    const errors: string[] = [];
+    if (input === null || typeof input !== 'object') {
+        return { valid: false, errors: ['response is not an object'] };
+    }
+    const r = input as Record<string, unknown>;
+    if (typeof r.summary !== 'string') errors.push('summary missing or not a string');
+    if (typeof r.handoff !== 'string') errors.push('handoff missing or not a string');
+    if (!CONFIDENCE.has(r.confidence as string)) errors.push(`confidence must be low|medium|high (got ${String(r.confidence)})`);
+    if (!Array.isArray(r.findings)) errors.push('findings missing or not an array');
+    if (!Array.isArray(r.risks)) errors.push('risks missing or not an array');
+    if (Array.isArray(r.findings)) {
+        for (const [i, f] of (r.findings as Finding[]).entries()) {
+            if (!f || typeof f.title !== 'string') errors.push(`finding[${i}] missing title`);
+            const refs = f?.evidence_refs;
+            if (refs && refs.some((x) => typeof x !== 'string' || x.includes('\n'))) {
+                errors.push(`finding[${i}] evidence_refs must be ref tokens, not bodies`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Synthesis gaps the orchestrator must resolve before adopting the response:
+ * a finding with no evidence ref is an unbacked claim to re-check.
+ */
+export function synthesisGaps(response: SubagentResponse): string[] {
+    const gaps: string[] = [];
+    for (const f of response.findings) {
+        if (!f.evidence_refs || f.evidence_refs.length === 0) {
+            gaps.push(`finding "${f.title}" has no evidence — re-check before adopting`);
+        }
+    }
+    return gaps;
+}
+
+/**
+ * Confidence → verify-budget link. A mutating finding returned at `low`
+ * confidence forces the full cross-model judge (no deterministic-only pass).
+ * Returns true when the full judge is mandatory for this finding.
+ */
+export function forcesJudge(f: Finding, confidence: Confidence): boolean {
+    return f.mutating === true && confidence === 'low';
+}

package/src/scripts/_lib/subagent_routing.ts

@@ -0,0 +1,81 @@
+/**
+ * Subagent routing (Phase 2) — cost/speed downshift + optional quota arbitrage.
+ *
+ * Pure, no-I/O, VENDOR-NEUTRAL. Resolves which model a delegated sub-task runs
+ * on, from the sub-task's declared capability tier, the `subagents.*` settings,
+ * and the host-capability manifest. Contract:
+ * `src/agent-src/contexts/execution/subagent-routing.md`.
+ *
+ * Invariants:
+ * - The orchestrator stays on the session/high tier (this resolves SUB-tasks).
+ * - Downshift off → every sub-task runs on the session tier.
+ * - Downshift on → a sub-task runs on the lowest-capable tier it declares.
+ * - Quota arbitrage is an OPTIONAL bonus: it only prefers the separate pool
+ *   when BOTH the setting and the host manifest allow it. Where unsupported,
+ *   routing is identical minus the quota win — never a hard-coded vendor model.
+ */
+
+export type Tier = 'lite' | 'medium' | 'high' | 'inherit';
+export type QuotaPool = 'separate' | 'shared';
+
+/** Per-tier model alias overrides (empty string = use the tier's runtime default). */
+export interface ModelMap {
+    lite?: string;
+    medium?: string;
+    high?: string;
+}
+
+export interface RoutingInputs {
+    /** The sub-task's declared capability tier. */
+    task_tier: Tier;
+    /** The orchestrator's session tier (used when downshift is off / tier is inherit). */
+    session_tier: Tier;
+    downshift: boolean;
+    quota_arbitrage: boolean;
+    model_map: ModelMap;
+    /** From the host-capability manifest. */
+    separate_quota_pool: boolean;
+}
+
+export interface RoutingDecision {
+    /** Resolved tier the sub-task runs on. */
+    tier: Tier;
+    /** Model alias, or '' meaning "use the tier's runtime default" (no vendor name baked in). */
+    model: string;
+    /** Whether a separate quota pool is used (bonus) or the shared one. */
+    quota_pool: QuotaPool;
+    reason: string;
+}
+
+/** Resolve a model alias for a tier from the map; '' = tier default sentinel. */
+function modelForTier(tier: Tier, map: ModelMap): string {
+    if (tier === 'lite') return map.lite ?? '';
+    if (tier === 'medium') return map.medium ?? '';
+    if (tier === 'high') return map.high ?? '';
+    return ''; // inherit → session default
+}
+
+/**
+ * Resolve routing for one delegated sub-task. Vendor-neutral: returns a tier +
+ * an optional model alias (never a hard-coded provider model) + the quota pool.
+ */
+export function resolveSubagentRouting(inp: RoutingInputs): RoutingDecision {
+    // Downshift off, or an `inherit` task → run on the session tier.
+    const tier: Tier = !inp.downshift || inp.task_tier === 'inherit' ? inp.session_tier : inp.task_tier;
+    const downshifted = inp.downshift && inp.task_tier !== 'inherit' && tier !== inp.session_tier;
+
+    // Quota arbitrage: a bonus, only when BOTH the setting and the host allow it.
+    const useSeparate = inp.quota_arbitrage && inp.separate_quota_pool;
+    const quota_pool: QuotaPool = useSeparate ? 'separate' : 'shared';
+
+    const reasonParts: string[] = [];
+    reasonParts.push(downshifted ? `downshift to ${tier}` : `session tier ${tier}`);
+    reasonParts.push(useSeparate ? 'separate quota pool (bonus)' : 'shared quota pool');
+
+    return {
+        tier,
+        model: modelForTier(tier, inp.model_map),
+        quota_pool,
+        reason: reasonParts.join(' · '),
+    };
+}

package/src/scripts/_lib/subagent_spawn.ts

@@ -0,0 +1,97 @@
+/**
+ * Subagent spawn-brief composition (Phase 3) — task-optimal configuration.
+ *
+ * Pure, no-I/O. Composes a subagent's brief from the existing config seams —
+ * role-mode + profile + persona(s) + a MINIMAL knowledge slice — so each
+ * subagent is configured for its task. Contract:
+ * `src/agent-src/contexts/execution/subagent-spawn-contract.md`.
+ *
+ * Hard invariant (lethal-trifecta-guard): knowledge is passed as a small set of
+ * REFERENCES, never as inline bodies, and is capped. Never bulk-dump context
+ * into a subagent — keep the private-data leg narrow.
+ */
+
+export type RoleMode = 'developer' | 'reviewer' | 'tester' | 'po' | 'incident' | 'planner';
+
+const ROLE_MODES: ReadonlySet<string> = new Set<RoleMode>([
+    'developer',
+    'reviewer',
+    'tester',
+    'po',
+    'incident',
+    'planner',
+]);
+
+/** Max knowledge slice refs handed to one subagent (minimal-slice cap). */
+export const MAX_KNOWLEDGE_REFS = 5;
+/** Max personas overlaid on one subagent. */
+export const MAX_PERSONAS = 2;
+
+export interface SpawnSelection {
+    task: string;
+    /** Role-mode contract the subagent runs under, or null for none. */
+    role_mode?: RoleMode | null;
+    /** Active profile id (e.g. 'developer', 'content_creator'), or null. */
+    profile?: string | null;
+    /** Persona ids (review lenses) cited by the task's skill, capped. */
+    personas?: string[];
+    /** Knowledge slice REFERENCES (ids / paths) — never inline bodies. */
+    knowledge_refs?: string[];
+}
+
+export interface SpawnBrief {
+    task: string;
+    role_mode: RoleMode | null;
+    profile: string | null;
+    personas: string[];
+    knowledge_refs: string[];
+    warnings: string[];
+}
+
+/** A ref is acceptable only if it looks like an id/path token, not a body. */
+function isRefLike(s: unknown): s is string {
+    return typeof s === 'string' && s.length > 0 && s.length <= 200 && !s.includes('\n');
+}
+
+/**
+ * Compose a validated spawn brief. Invalid role-mode → dropped to null;
+ * personas capped at {@link MAX_PERSONAS}; knowledge refs filtered to
+ * ref-like tokens and capped at {@link MAX_KNOWLEDGE_REFS}. Anything dropped is
+ * recorded in `warnings` (surfaced, never silent).
+ */
+export function composeSpawnBrief(sel: SpawnSelection): SpawnBrief {
+    const warnings: string[] = [];
+
+    let role_mode: RoleMode | null = null;
+    if (sel.role_mode != null) {
+        if (ROLE_MODES.has(sel.role_mode)) role_mode = sel.role_mode;
+        else warnings.push(`unknown role_mode '${sel.role_mode}' dropped`);
+    }
+
+    const personasIn = sel.personas ?? [];
+    let personas = personasIn.filter((p) => typeof p === 'string' && p.length > 0);
+    if (personas.length > MAX_PERSONAS) {
+        warnings.push(`personas capped ${personas.length} → ${MAX_PERSONAS}`);
+        personas = personas.slice(0, MAX_PERSONAS);
+    }
+
+    const refsIn = sel.knowledge_refs ?? [];
+    const bodyLike = refsIn.filter((r) => !isRefLike(r));
+    if (bodyLike.length > 0) {
+        warnings.push(`${bodyLike.length} non-ref knowledge entr${bodyLike.length === 1 ? 'y' : 'ies'} rejected (refs only, no bodies)`);
+    }
+    let knowledge_refs = refsIn.filter(isRefLike);
+    if (knowledge_refs.length > MAX_KNOWLEDGE_REFS) {
+        warnings.push(`knowledge refs capped ${knowledge_refs.length} → ${MAX_KNOWLEDGE_REFS}`);
+        knowledge_refs = knowledge_refs.slice(0, MAX_KNOWLEDGE_REFS);
+    }
+
+    return {
+        task: sel.task,
+        role_mode,
+        profile: sel.profile ?? null,
+        personas,
+        knowledge_refs,
+        warnings,
+    };
+}

package/src/scripts/_lib/subagent_steering.ts

@@ -0,0 +1,64 @@
+/**
+ * Subagent steering & guardrails (Phase 5).
+ *
+ * Pure, no-I/O. The guardrails that keep auto-dispatch from becoming a token
+ * sink: the N=3 per-target budget, the kill-switch, and the rollback
+ * guardrail-threshold checks. Contract:
+ * `src/agent-src/contexts/execution/subagent-steering.md`.
+ *
+ * Automatic cohort-level disable is OUT OF SCOPE — a config package runs no
+ * daemon. Breaches are surfaced for the maintainer/user to act on; the only
+ * automatic stop is the per-target N=3 budget.
+ */
+
+/** Max consecutive failed attempts on one validation target before halting. */
+export const MAX_ATTEMPTS_PER_TARGET = 3;
+
+/** Rollback guardrail thresholds (council-defined). */
+export const GUARDRAILS = {
+    /** Token spend vs single-agent baseline. */
+    token_blowup_ratio: 2,
+    /** Subagent spawn-failure rate. */
+    spawn_failure_rate: 0.1,
+    /** Fraction of dispatches that completed without a required verification. */
+    verify_skip_rate: 0.01,
+    /** Fraction of users manually disabling the layer. */
+    user_override_rate: 0.3,
+} as const;
+
+export interface LayerState {
+    enabled: boolean;
+    auto: 'off' | 'ask' | 'on';
+}
+
+/** The kill-switch: layer is disabled when the master switch is off or auto is off. */
+export function isLayerDisabled(state: LayerState): boolean {
+    return !state.enabled || state.auto === 'off';
+}
+
+/** N=3 per-target budget: halt once consecutive failed attempts reach the cap. */
+export function budgetHalt(consecutiveFailures: number): boolean {
+    return consecutiveFailures >= MAX_ATTEMPTS_PER_TARGET;
+}
+
+export interface GuardrailMetrics {
+    /** Observed token spend / single-agent baseline (e.g. 2.4 = 2.4x). */
+    token_ratio: number;
+    spawn_failure_rate: number;
+    verify_skip_rate: number;
+    user_override_rate: number;
+}
+
+/**
+ * Evaluate the rollback guardrails. Returns the list of breached threshold
+ * names (empty = all clear). The orchestrator surfaces a non-empty result —
+ * it does NOT auto-disable (no daemon); the maintainer/user decides.
+ */
+export function breachedGuardrails(m: GuardrailMetrics): string[] {
+    const breached: string[] = [];
+    if (m.token_ratio > GUARDRAILS.token_blowup_ratio) breached.push('token_blowup');
+    if (m.spawn_failure_rate > GUARDRAILS.spawn_failure_rate) breached.push('spawn_failure');
+    if (m.verify_skip_rate > GUARDRAILS.verify_skip_rate) breached.push('verify_skip');
+    if (m.user_override_rate > GUARDRAILS.user_override_rate) breached.push('user_override');
+    return breached;
+}

package/src/scripts/_lib/verify_budget.ts

@@ -0,0 +1,54 @@
+/**
+ * Verification-budget model (Phase 4).
+ *
+ * Pure, no-I/O. Decides HOW a delegated sub-task's output is verified so the
+ * cross-model judge Iron Law and verify-before-complete are preserved WITHOUT
+ * double-costing every trivial delegation. Contract:
+ * `src/agent-src/contexts/execution/verify-budget.md`.
+ *
+ * - Trivial (below the change-size floor, read-only / no file writes) →
+ *   `deterministic` verification (diff + dry-run + structural checks, no LLM).
+ * - Otherwise → `judge` (full cross-model judge per subagent-orchestration).
+ * - A required verification that did not run is a SURFACED safety gap, never a
+ *   silent pass.
+ */
+
+export type VerifyMode = 'deterministic' | 'judge' | 'none';
+
+/** Max changed-line count (inclusive) that still counts as trivial. */
+export const TRIVIAL_CHANGE_FLOOR = 20;
+
+export interface VerifyInputs {
+    /** Changed lines the sub-task produced. */
+    change_size: number;
+    /** Did the sub-task write/modify files? */
+    file_writes: boolean;
+    /** Was the sub-task read-only (query/analysis, no mutation)? */
+    read_only: boolean;
+}
+
+/**
+ * Select the verification mode for a completed sub-task.
+ * Trivial + non-mutating → deterministic; anything else → judge.
+ */
+export function selectVerifyMode(inp: VerifyInputs): VerifyMode {
+    if (inp.read_only) return 'deterministic';
+    const trivial = inp.change_size <= TRIVIAL_CHANGE_FLOOR && !inp.file_writes;
+    return trivial ? 'deterministic' : 'judge';
+}
+
+/**
+ * Detect a verification safety gap: a mode was required but the recorded mode
+ * was `none`. Returns a human-readable gap string, or null when clean.
+ * The orchestrator surfaces a non-null result — it is never a silent pass.
+ */
+export function verificationGap(required: VerifyMode, recorded: VerifyMode): string | null {
+    if (required === 'none') return null;
+    if (recorded === 'none') {
+        return `verification gap: '${required}' required but none recorded`;
+    }
+    if (required === 'judge' && recorded === 'deterministic') {
+        return `verification gap: non-trivial change verified deterministically (judge required)`;
+    }
+    return null;
+}

package/src/scripts/ai_council/advisors.ts

@@ -2,8 +2,10 @@
  * Thinking-style advisors — replace-mode call planning (Phase 6).
  *
  * TypeScript twin of `src/scripts/ai_council/advisors.py` (ADR-200 —
- * Python→TS migration, Phase 1). When `agents/settings/.ai-council.yml`
- * enables an advisor (e.g. `contrarian` bound to `member: anthropic`), the
+ * Python→TS migration, Phase 1). When the user-global
+ * `~/.event4u/agent-config/settings/.ai-council.yml` (always global —
+ * ADR-104) enables an advisor (e.g. `contrarian` bound to
+ * `member: anthropic`), the
  * orchestrator REPLACES the matching plain-member call with an
  * advisor-persona call on the same provider. Same total call count as a
  * plain run; bounded extra cost beyond the persona-prompt token delta.

package/src/scripts/ai_council/clients.ts

@@ -287,12 +287,18 @@ function _curlJsonPost(url: string, extraHeaders: string[], body: unknown): unkn
     for (const h of extraHeaders) {
         args.push('-H', h);
     }
+    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
+    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
+    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
+    // A full 16k-token generation legitimately runs several minutes, so the
+    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
+    args.push('--connect-timeout', '30', '--max-time', '290');
     args.push('-w', '\n%{http_code}', '--data-binary', '@-');
     const r = spawnSync('curl', args, {
         input: JSON.stringify(body),
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
-        timeout: 120_000,
+        timeout: 300_000,
     });
     if (r.error) {
         throw new Error(`curl spawn failed: ${(r.error as Error).message}`);

package/src/scripts/ai_council/config.ts

@@ -6,8 +6,9 @@
  * surface and validation behaviour byte-for-byte: same exported
  * snake_case names, same defaults, same error messages, same precedence.
  *
- * Reads `agents/settings/.ai-council.yml` per the contract in
- * `docs/contracts/ai-council-config.md`. Replaces the fragmented
+ * Reads the user-global `~/.event4u/agent-config/settings/.ai-council.yml`
+ * per the contract in `docs/contracts/ai-council-config.md` (council
+ * config is ALWAYS user-global — ADR-104). Replaces the fragmented
  * `.agent-settings.yml` `ai_council` block (Phase 0 migration).
  *
  * Validation contract (8 rules, all enforced at load time):
@@ -93,7 +94,7 @@ export type PathLike = string;
 
 // ── error type ─────────────────────────────────────────────────────
 
-/** Raised when `agents/settings/.ai-council.yml` violates the schema. */
+/** Raised when the user-global `.ai-council.yml` violates the schema. */
 export class CouncilConfigError extends Error {
     constructor(message: string) {
         super(message);
@@ -562,8 +563,10 @@ export const COUNCIL_CONFIG_USER_GLOBAL_REL = 'settings/.ai-council.yml';
 
 /**
  * Env var pinning the council config to an explicit absolute path, ahead
- * of the project → user-global search. Mirrors `EVENT4U_CONFIG_HOME` but
- * targets the config file itself (tests / power users).
+ * of the user-global default. Mirrors `EVENT4U_CONFIG_HOME` but targets
+ * the config file itself (tests / power users). This is the ONLY escape
+ * from the user-global location — it is an explicit absolute path, never
+ * a "search the project" path.
  */
 export const COUNCIL_CONFIG_ENV = 'AI_COUNCIL_CONFIG';
 
@@ -598,14 +601,24 @@ function _isAbsoluteLikePython(p: string): boolean {
 /**
  * Resolve which `.ai-council.yml` the council reads.
  *
+ * **The council config is ALWAYS user-global.** It is a per-developer
+ * facility configured once and works in every project, worktree, and
+ * CWD — including consumer repos that carry no council file of their
+ * own. The project tree is NEVER searched for council config (ADR-104,
+ * superseding the project-local override kept by ADR-093).
+ *
  * Precedence (first match wins):
  *
  * 1. `$AI_COUNCIL_CONFIG` — explicit absolute override (tests / power
- *    users). Honoured even when the target is absent.
- * 2. Project-local `<project_root>/agents/settings/.ai-council.yml`.
- * 3. User-global `~/.event4u/agent-config/settings/.ai-council.yml`
+ *    users). Honoured even when the target is absent. This is an
+ *    explicit path, not a project search.
+ * 2. User-global `~/.event4u/agent-config/settings/.ai-council.yml`
  *    (with the legacy `~/.config/agent-config/` read-fallback).
  *
+ * `project_root` is accepted for signature stability with callers but is
+ * NOT consulted for config resolution — the council never reads
+ * `<project_root>/agents/settings/.ai-council.yml`.
+ *
  * Always returns a path (never `null`): when nothing exists yet it
  * returns the user-global write target.
  */
@@ -613,20 +626,12 @@ export function resolve_config_path(
     project_root: PathLike,
     options: { env?: user_global_paths.EnvMap | null } = {},
 ): PathLike {
+    void project_root; // intentionally unused — council config is always user-global (ADR-104).
     const env_map = options.env != null ? options.env : process.env;
     const override = env_map[COUNCIL_CONFIG_ENV];
     if (override) {
         return _expanduser(override);
     }
-    const project_path = path.join(
-        project_root,
-        'agents',
-        'settings',
-        COUNCIL_CONFIG_RELNAME,
-    );
-    if (fs.existsSync(project_path)) {
-        return project_path;
-    }
     const found = user_global_paths.resolve_with_fallback(
         COUNCIL_CONFIG_USER_GLOBAL_REL,
         { env: options.env ?? null },