@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/code_graph/types.ts

@@ -17,6 +17,55 @@ export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
 /** Relations the extractor emits. */
 export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member';
 
+/**
+ * HOW an edge's target was arrived at — the mechanism, not the confidence.
+ *
+ * The two axes are independent and conflating them is what this field fixes.
+ * `confidence` says how much to trust the target; `resolved_via` says what
+ * produced it, which is the axis a consumer filters on. Phase 3's verbs accept
+ * an edge when `resolved_via` is not in `{name-lookup, dynamic}` — a rule that
+ * cannot be expressed in the confidence scale at all, because a `name-lookup`
+ * hit and a same-file hit can both be INFERRED.
+ *
+ * Four of the eight occur today, and saying which is the point of an enum that
+ * is wider than its current population:
+ *
+ * · `same-file` — a local declaration in the using file. The language's own
+ *   shadowing rule makes this the strongest binding there is.
+ * · `import-specifier` — an import/`use` binding: the file states where the
+ *   name comes from.
+ * · `name-lookup` — the repo-wide same-name table, or an attempted lookup that
+ *   found nothing and left a `symbol:` pseudo-target. A guess either way, and
+ *   the value that says so.
+ * · `dynamic` — a receiver the extractor cannot type (`$obj->m()`, an
+ *   unresolved `C::m()`), or a hierarchy rooted outside the repository.
+ *
+ * The remaining four are declared and currently unemitted: `path-alias` and
+ * `psr4` arrive with the resolution tiers in step 2.3, and `route-table` /
+ * `test-import` with the relations Phase 3 adds. They are in the union now so
+ * that adding them later is a build change rather than a schema change.
+ */
+export type ResolvedVia =
+    | 'same-file'
+    | 'import-specifier'
+    | 'path-alias'
+    | 'psr4'
+    | 'route-table'
+    | 'test-import'
+    | 'name-lookup'
+    | 'dynamic';
+
+/**
+ * WHICH engine produced the edge.
+ *
+ * One value, and the field exists anyway: an edge with no provider is
+ * indistinguishable from an edge whose provider nobody recorded, and the whole
+ * point of a mixed graph — should one ever exist — is being able to tell them
+ * apart. Kill register K2 forbids an external provider entering `src/`, so this
+ * stays a single-member union until a decision changes that.
+ */
+export type EdgeProvider = 'native';
+
 export interface CodeNode {
     /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
     id: string;
@@ -45,6 +94,14 @@ export interface CodeEdge {
     target: string;
     relation: Relation;
     confidence: EdgeConfidence;
+    /**
+     * REQUIRED. Not optional, so "no edge lacks either field" is a property the
+     * type system enforces at every construction site rather than a rule a
+     * linter has to re-check afterwards.
+     */
+    resolved_via: ResolvedVia;
+    /** REQUIRED, for the same reason. */
+    provider: EdgeProvider;
     /**
      * Present only on AMBIGUOUS / multi-candidate edges: the resolved-target
      * candidates by id. An AMBIGUOUS edge is "correct" when the true target is
@@ -105,6 +162,14 @@ export interface CodeGraph {
 }
 
 /**
+ * Bumped 2 → 3 by `road-to-a-graph-that-is-shipped` 2.2: every `CodeEdge` now
+ * carries `resolved_via` and `provider`. A cached sidecar written at v2 has
+ * neither, so `--update` would reuse untagged edges beside tagged ones and
+ * produce a graph whose `resolved_via` histogram silently under-counts —
+ * exactly the mixed-graph failure the previous bump describes. `readSidecar`
+ * refuses a version mismatch, which is what makes that impossible rather than
+ * merely unlikely.
+ *
  * Bumped 1 → 2 by `road-to-the-graph-that-lies-confidently`: `CodeNode.kind`
  * gained three members, `CodeGraph` gained `suppressed_edge_counts`, and the
  * per-file extract sidecar gained the import specifier. A cached sidecar
@@ -113,7 +178,7 @@ export interface CodeGraph {
  * file — a silently mixed graph. `readSidecar` refuses a version mismatch, so
  * the bump is what makes that impossible rather than merely unlikely.
  */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 /** Deterministic per-file byte cap — files above this become a SKIPPED node. */
 export const MAX_FILE_BYTES = 1_000_000;

package/src/scripts/code_graph/validate.ts

@@ -6,6 +6,19 @@ import type { CodeGraph } from './types.js';
 
 const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
 const CONFIDENCES = new Set(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
+/** Mirrors `ResolvedVia` in types.ts — the full union, including the four
+ * values no build emits yet (2.3 and Phase 3 add them). */
+const RESOLVED_VIA = new Set([
+    'same-file',
+    'import-specifier',
+    'path-alias',
+    'psr4',
+    'route-table',
+    'test-import',
+    'name-lookup',
+    'dynamic',
+]);
+const PROVIDERS = new Set(['native']);
 const KINDS = new Set([
     'file',
     'class',
@@ -57,6 +70,16 @@ export function validateGraph(g: unknown): ValidateResult {
         if (!RELATIONS.has(ee['relation'] as string)) push(`edge[${i}].relation invalid: ${String(ee['relation'])}`);
         if (!CONFIDENCES.has(ee['confidence'] as string))
             push(`edge[${i}].confidence invalid: ${String(ee['confidence'])}`);
+        // Both are REQUIRED (2.2). Checked as presence-and-membership rather
+        // than membership alone, because an absent field and a misspelled one
+        // are different defects: absent means the build did not tag the edge,
+        // misspelled means the taxonomy drifted.
+        if (ee['resolved_via'] === undefined) push(`edge[${i}].resolved_via is required`);
+        else if (!RESOLVED_VIA.has(ee['resolved_via'] as string))
+            push(`edge[${i}].resolved_via invalid: ${String(ee['resolved_via'])}`);
+        if (ee['provider'] === undefined) push(`edge[${i}].provider is required`);
+        else if (!PROVIDERS.has(ee['provider'] as string))
+            push(`edge[${i}].provider invalid: ${String(ee['provider'])}`);
         // a source must be a known node; targets may be unresolved `symbol:` refs
         if (typeof ee['source'] === 'string' && !ids.has(ee['source'] as string))
             push(`edge[${i}].source is not a known node: ${String(ee['source'])}`);

package/src/scripts/condense.ts

@@ -265,9 +265,9 @@ export {
 } from '../install/claudePathsPlan.js';
 import { rule_in_scope } from '../install/ruleInScope.js';
 import { pruneEmptyDirs } from './_lib/prune_empty_dirs.js';
-import { commandsWithheld, partitionActive, personaPartition, setPartitionAnnounce } from '../install/partitionEligibility.js'; // ADR-236
+import { claudeLayerHolds, commandWithheld, keepInProjectLayer, personaPartition } from '../install/partitionEligibility.js'; // ADR-236
 import { dedupableRules, partitionRulesForDir } from '../install/ruleLayerPartition.js'; // ADR-236, per-host evidence
-import { _claude_paths_plan, derive_trigger_globs } from '../install/claudePathsPlan.js';
+import { _claude_paths_plan, applies_when, derive_trigger_globs } from '../install/claudePathsPlan.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url)); // <repo>/src/scripts
 const _DEFAULT_PROJECT_ROOT = path.resolve(_HERE, '..', '..');
@@ -320,7 +320,6 @@ function _deriveState(root: string): ModuleState {
 }
 
 export const MODULE_STATE: ModuleState = _deriveState(_DEFAULT_PROJECT_ROOT);
-setPartitionAnnounce(success); // ADR-236: the mode line must be visible at the default level
 
 /**
  * Test seam — reassign one or more module-state fields, mirroring the pytest
@@ -1299,7 +1298,7 @@ export function _emit_cursor_mdc(source: string, target: string): void {
     const globs = always_apply ? [] : derive_trigger_globs(meta);
     const lines = [
         '---',
-        `description: ${_yaml_scalar(description)}`,
+        `description: ${_yaml_scalar(always_apply ? description : applies_when(description, meta))}`,
         `globs: ${globs.join(',')}`,
         `alwaysApply: ${always_apply ? 'true' : 'false'}`,
         '---',
@@ -1321,7 +1320,7 @@ export function _emit_windsurf_rule(source: string, target: string): void {
     const lines = [
         '---',
         `trigger: ${trigger}`,
-        `description: ${_yaml_scalar(description)}`,
+        `description: ${_yaml_scalar(always_apply ? description : applies_when(description, meta))}`,
         `globs: ${globs.join(',')}`,
         '---',
         '',
@@ -1628,23 +1627,22 @@ function _render_native_model_md(src_md: string, tier: string): string {
 }
 
 export function generate_claude_skills(active_skill_names: ReadonlySet<string> | null = null): number {
-    if (partitionActive(MODULE_STATE.PROJECT_ROOT)) active_skill_names = new Set<string>();
     if (!_exists(MODULE_STATE.SKILLS_SOURCE)) {
         process.stderr.write('  ⚠️  dist/agent-src/skills/ not found — skipping skills\n');
         return 0;
     }
 
-    let skills = _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
+    const all_skills = _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
         .filter((p) => _isDir(p))
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    // ADR-236: withhold every skill `~/.claude/skills` holds — see `keepInProjectLayer`.
+    let skills = keepInProjectLayer('skills', all_skills);
     if (active_skill_names !== null) {
         skills = skills.filter((s) => active_skill_names.has(s));
     }
     const skill_set = new Set(skills);
-    const command_slugs = partitionActive(MODULE_STATE.PROJECT_ROOT)
-        ? new Set<string>()
-        : new Set([...iterCommands()].map(([, slug]) => slug));
+    const command_slugs = _emitted_wrapper_slugs(new Set(all_skills));
 
     _mkdirp(MODULE_STATE.CLAUDE_SKILLS_DIR);
     const auto = _read_model_auto_switch() === 'auto';
@@ -1737,6 +1735,22 @@ function _nested_command_subpath(source_file: string): string | null {
     return sub.includes('/') ? sub : null;
 }
 
+/** The emitter's four skips, in one place — see `emittedWrapperSlugs`. */
+const _wrapper_is_emitted = (f: string, s: string, skills: ReadonlySet<string>): boolean =>
+    !skills.has(s) &&
+    _nested_command_subpath(f) === null &&
+    !is_claude_builtin_name(s) &&
+    !claudeLayerHolds('skills', s);
+
+/** Wrapper slugs the command emitter really writes — see `emittedWrapperSlugs`. */
+function _emitted_wrapper_slugs(skill_names: ReadonlySet<string>): Set<string> {
+    return new Set(
+        [...iterCommands()]
+            .filter(([f, s]) => _wrapper_is_emitted(f, s, skill_names))
+            .map(([, slug]) => slug),
+    );
+}
+
 /**
  * Project-scope `.claude/commands/<cluster>/<sub>.md` — the colon form.
  *
@@ -1749,7 +1763,7 @@ function _nested_command_subpath(source_file: string): string | null {
  *
  * Emitting the nested form here lets `generate_claude_commands` stop wrapping
  * the clustered commands: one listing, same reachability, and reachability no
- * longer depends on a global deploy. Dedup AND precedence: `commandsWithheld`.
+ * longer depends on a global deploy. Dedup AND precedence: `commandWithheld`.
  *
  * ADR-003 (colon canonical for clusters) and ADR-044 (flat commands stay
  * hyphenated) both hold: flat commands are untouched and keep their wrapper.
@@ -1757,8 +1771,6 @@ function _nested_command_subpath(source_file: string): string | null {
 export function generate_claude_project_commands(
     active_command_slugs: ReadonlySet<string> | null = null,
 ): number {
-    if (commandsWithheld(MODULE_STATE.PROJECT_ROOT)) active_command_slugs = new Set<string>();
-    // Returns before the stale sweep — invariant, see `commandsWithheld`.
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         return 0;
     }
@@ -1768,7 +1780,7 @@ export function generate_claude_project_commands(
             continue;
         }
         const sub = _nested_command_subpath(source_file);
-        if (sub !== null) {
+        if (sub !== null && !commandWithheld(`${sub}.md`)) {
             nested.push([source_file, sub]);
         }
     }
@@ -1805,7 +1817,6 @@ export function generate_claude_project_commands(
 }
 
 export function generate_claude_commands(active_command_slugs: ReadonlySet<string> | null = null): number {
-    if (partitionActive(MODULE_STATE.PROJECT_ROOT)) active_command_slugs = new Set<string>();
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         process.stderr.write('  ⚠️  src/domains/ not found — skipping commands\n');
         return 0;
@@ -1826,6 +1837,7 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     let count = 0;
     let skipped = 0;
     let reserved = 0;
+    let withheld = 0;
     let rendered = 0;
     const auto = _read_model_auto_switch() === 'auto';
     for (const [source_file, slug] of iterCommands()) {
@@ -1854,6 +1866,9 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
             reserved += 1;
             continue;
         }
+        // ADR-236 per-name: the INSTALLER re-projects visible flat commands as
+        // `~/.claude/skills/<slug>/SKILL.md` (install.ts:_apply_claude_flat_command_wrappers).
+        if (claudeLayerHolds('skills', slug)) { withheld += 1; continue; }
         current_slugs.add(slug);
 
         const skill_dir = path.join(MODULE_STATE.CLAUDE_SKILLS_DIR, slug);
@@ -1906,6 +1921,9 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     if (reserved) {
         msg += ` (${reserved} withheld — Claude Code built-in name)`;
     }
+    if (withheld > 0) {
+        msg += ` (${withheld} withheld — ~/.claude/skills carries the wrapper)`;
+    }
     if (removed_dirs) {
         msg += ` (${removed_dirs} stale dirs removed)`;
     }
@@ -2244,19 +2262,13 @@ export function generate_persona_symlinks(): number {
         _print('  ⚠️  dist/agent-src/personas/ not found — skipping personas');
         return 0;
     }
-    const personas = _rglobSorted(MODULE_STATE.PERSONAS_SOURCE, '*.md')
-        .filter((p) => _isFile(p) && path.basename(p, '.md') !== 'README')
-        .map((p) => path.basename(p))
-        // glob('*.md') is non-recursive in Python; mirror that — only top level.
-        .filter((name) => _isFile(path.join(MODULE_STATE.PERSONAS_SOURCE, name)));
     // Python uses PERSONAS_SOURCE.glob("*.md") (non-recursive). Re-derive
     // from a direct listing to match exactly.
     const direct = _iterdirSorted(MODULE_STATE.PERSONAS_SOURCE)
         .filter((p) => p.endsWith('.md') && _isFile(p) && path.basename(p, '.md') !== 'README')
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    void personas;
-    const partition = personaPartition(MODULE_STATE.PROJECT_ROOT, direct);
+    const partition = personaPartition(direct);
     const tool_dirs = _filter_tool_dirs(PERSONA_TOOL_DIRS);
     let total = 0;
     for (const [tool_dir, rel_prefix] of Object.entries(tool_dirs)) {

package/src/scripts/corpus_manifest.ts

@@ -23,7 +23,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { partitionActive } from '../install/partitionEligibility.js';
+import { resolveHostLayerVerdict } from '../install/partitionEligibility.js';
 import {
     type CorpusManifest,
     captureManifest,
@@ -126,9 +126,9 @@ export function parseArgs(argv: readonly string[]): Parsed | string {
 /**
  * One real capture over the real tree.
  *
- * This is the one caller for which the process globals `partitionActive` reads
- * — the host layer under the running user's home, and the install lockfile —
- * ARE this run's own host, so it is the one caller that passes the predicate.
+ * This is the one caller for which the process globals `resolveHostLayerVerdict`
+ * reads — the host layer under the running user's home, and the install lockfile
+ * — ARE this run's own host, so it is the one caller that passes the predicate.
  * Everywhere else the field stays `null` rather than recording some other
  * machine's state under this tree's name.
  */
@@ -138,7 +138,7 @@ function capture(limit: number): CorpusManifest {
         userHome: process.env['HOME'] ?? os.homedir(),
         limit,
         enumerationRule: ENUMERATION_RULE_ID,
-        partitionActive,
+        hostLayerVerified: (root) => resolveHostLayerVerdict(root).verified,
     });
 }
 

package/src/scripts/council_cli.ts

@@ -78,8 +78,11 @@ import {
 } from './ai_council/config.js';
 import { AuthCache, select_solo_member } from './ai_council/solo_dispatch.js';
 import { InvalidModeError, resolve_global_mode } from './ai_council/modes.js';
-import { resolveMemberTransport } from './ai_council/transport_resolver.js';
-import { classifyCliFailure, type AbsentReason } from './ai_council/transport_resolver.js';
+import { classifyCliFailure, resolveMemberTransport, type AbsentReason } from './ai_council/transport_resolver.js';
+import {
+    disabledSeats as _disabledSeats,
+    resolvedTransportFor as _resolvedTransportFor,
+} from './ai_council/status_surface.js';
 import { evaluateQuorum, type QuorumResult } from './ai_council/quorum.js';
 import {
     _emitQuorumEvent,
@@ -90,6 +93,7 @@ import {
     _quorum_min_present_from,
     _quorum_setting_from,
 } from './ai_council/quorum_wiring.js';
+import { measureDeliberation, runCallsFrom } from './ai_council/deliberation_metrics.js';
 import { formatQualificationLine, type MemberQualification } from './ai_council/qualification.js';
 import {
     absenceReasonFor,
@@ -2163,31 +2167,6 @@ function _emit_shadow_slo_banner(): void {
  * leaves nothing to infer. Exit is always 0 — this reports a state, it does not
  * gate — and the verdict line is machine-greppable in both directions.
  */
-/**
- * Resolve the concrete transport a member would use on THIS machine right now.
- *
- * `cmd_status` exists to answer "is the council reachable, and will it bill me".
- * Since the transport-mode setting was removed, the second half is not a value
- * anyone can look up in the config — it is a per-machine resolution. Printing a
- * configured mode would be the same class of stale answer the removed setting
- * produced. `mode` is pinned to `auto` because the loader no longer emits
- * anything else.
- */
-function _resolvedTransportFor(
-    name: string,
-    member: { readonly binary: string | null; readonly api_key_ref: string | null },
-    report?: EnvironmentReport,
-): ReturnType<typeof resolveMemberTransport> {
-    return resolveMemberTransport({
-        provider: name,
-        report: report ?? detectEnvironment(),
-        invocationMode: null,
-        memberSettings: null,
-        globalMode: 'auto',
-        binaryOverride: member.binary,
-    });
-}
-
 /** Gather what `fallbackPostureFor` needs; the decision itself is pure. */
 function _posture(
     name: string,
@@ -2263,6 +2242,9 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
                                 transport: t.available ? t.transport : null,
                                 billing: t.available ? t.billing : null,
                                 reason: t.reason,
+                                absent_reason: t.absentReason,
+                                policy_exclusion: m.policy_exclusion,
+                                content_ceiling: m.content_ceiling,
                             },
                         ];
                     }),
@@ -2273,6 +2255,7 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
                         enabledMembers.map(([n, m]) => [n, _posture(n, m)]),
                     ),
                 },
+                disabled_seats: _disabledSeats(cfg),
                 ignored_transport_keys: cfg?.ignored_transport_keys ?? [],
                 qualification: qualificationJson(qualifications),
                 qualified_members: countableSeats(qualifications),
@@ -2310,6 +2293,15 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
             const billing = t.available ? ` · ${t.billing}` : '';
             const detail = t.available ? t.transport : `unavailable — ${t.reason ?? 'no usable transport'}`;
             _stdout(`  transport        ${name}: ${detail}${billing}\n`);
+            // 2.1: the machine-readable half of the refusal.
+            if (!t.available && t.absentReason !== null && t.absentReason.startsWith('policy_')) {
+                _stdout(`  policy           ${name}: ${t.absentReason}\n`);
+            }
+            _stdout(`  content ceiling  ${name}: ${member.content_ceiling}\n`);
+        }
+        // 1.2: a disabled seat was invisible here — `enabled` members only.
+        for (const [name, reason] of Object.entries(_disabledSeats(cfg))) {
+            _stdout(`  disabled seat    ${name}: ${reason}\n`);
         }
         for (const line of renderPostureLines(
             enabledMembers.map(([n, m]) => [n, _posture(n, m)] as const),
@@ -2739,18 +2731,15 @@ function cmd_run(
     }
     const estimated_total = estimates.reduce((acc, e) => acc + _total_usd(e), 0.0);
     let actual_total = 0.0;
-    const all_responses: CouncilResponse[] = [...responses];
-    if (peer_review !== null) {
-        all_responses.push(...peer_review.responses);
-    }
-    if (consensus !== null) {
-        all_responses.push(...consensus.extraction_responses);
-        all_responses.push(...consensus.scoring_responses);
-    }
-    if (chairman !== null && chairman.response !== null) {
-        all_responses.push(chairman.response);
-    }
-    all_responses.push(...stance_repairs);
+    const run_calls = runCallsFrom({
+        deliberation: responses,
+        peerReview: peer_review?.responses ?? null,
+        consensusExtraction: consensus?.extraction_responses ?? null,
+        consensusScoring: consensus?.scoring_responses ?? null,
+        chairman: chairman?.response ?? null,
+        stanceRepairs: stance_repairs,
+    });
+    const all_responses: CouncilResponse[] = run_calls.responses;
     // Billable-aware: a subscription-CLI seat spent nothing, so pricing it at
     // API rates and calling the figure "actual" is a false statement about
     // money. See pricing.ts § billable-aware aggregation.
@@ -2800,6 +2789,7 @@ function cmd_run(
     // one for a machine consumer), even when every field is `null`: the
     // work-order envelope for whatever executes on this verdict next.
     payload['handoff'] = handoff;
+    payload['deliberation'] = measureDeliberation(run_calls.calls);
     const out_path = _validate_council_output_path(args.output as string, {
         kind: 'responses',
         subcommand: 'run',