@event4u/agent-config 9.27.0 → 9.29.0

package/src/scripts/_cli/cmd_brand_status.ts

@@ -0,0 +1,174 @@
+/**
+ * `agent-config brand:status` — is a consumer brand layer present, and where.
+ *
+ * Phase 2.4 of `road-to-capability-answerability`. `brand-source-of-truth` makes
+ * a precedence claim — a registered brand outranks the curated corpus — and an
+ * agent can only honour it by knowing whether a registered brand EXISTS. Before
+ * this verb the rule named the artefact and no path at all, so "is there a
+ * consumer brand here" was answerable only by guessing a filename, and the
+ * silent failure is the expensive one: the corpus quietly supplies defaults and
+ * the output looks fine.
+ *
+ * ## The filename defect this verb exposes
+ *
+ * The rule names `.tokens.json`, with a leading dot, four times. The only real
+ * resolver in the tree — `BRAND_TOKEN_PATHS` in the UI scaffold directive —
+ * looks for `tokens.json`, without one, in four conventional locations. A
+ * consumer who followed the rule literally would author a file the resolver can
+ * never find, and nothing would report it. So this verb searches the canonical
+ * list AND separately reports a dot-prefixed file sitting beside it, because
+ * "you have a brand file in the wrong place" is a different answer from "you
+ * have no brand".
+ *
+ * The path list is IMPORTED from the resolver rather than restated. A probe with
+ * its own copy of the search order is a second answer waiting to disagree with
+ * the first, which is the whole defect class this roadmap closes.
+ *
+ * Read-only by construction. Exit code is always `0`: "no brand layer" is a
+ * legitimate answer (greenfield), not a failure.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { resolve_project_root } from '../_lib/agent_settings.js';
+import { BRAND_TOKEN_PATHS } from '../../agent-src/templates/scripts/work_engine/directives/ui/scaffold.js';
+
+export interface BrandStatusOptions {
+    cwd: string;
+    json: boolean;
+}
+
+export interface BrandStatusResult {
+    code: 0;
+    out: string[];
+    err: string[];
+}
+
+/** The first canonical path holding a tokens file under `root`, or `null`. */
+export function findBrandTokens(root: string): string | null {
+    for (const rel of BRAND_TOKEN_PATHS) {
+        try {
+            if (fs.statSync(path.join(root, rel)).isFile()) return rel;
+        } catch {
+            continue;
+        }
+    }
+    return null;
+}
+
+/**
+ * Dot-prefixed near-misses — a `.tokens.json` beside each canonical location.
+ *
+ * These are files a consumer plausibly created by following the rule's own
+ * wording, and every one of them is invisible to the resolver.
+ */
+export function findDottedNearMisses(root: string): string[] {
+    const found: string[] = [];
+    for (const rel of BRAND_TOKEN_PATHS) {
+        const dotted = path.join(path.dirname(rel), `.${path.basename(rel)}`);
+        const normalised = dotted.startsWith('./') ? dotted.slice(2) : dotted;
+        try {
+            if (fs.statSync(path.join(root, normalised)).isFile()) found.push(normalised);
+        } catch {
+            continue;
+        }
+    }
+    return found;
+}
+
+export function runBrandStatus(opts: BrandStatusOptions): BrandStatusResult {
+    const out: string[] = [];
+    const [projectRoot] = resolve_project_root(null, { cwd: opts.cwd });
+    const found = findBrandTokens(projectRoot);
+    const nearMisses = findDottedNearMisses(projectRoot);
+
+    if (opts.json) {
+        out.push(
+            JSON.stringify(
+                {
+                    brand_layer_present: found !== null,
+                    tokens_file: found,
+                    searched: [...BRAND_TOKEN_PATHS],
+                    dotted_near_misses: nearMisses,
+                    project_root: projectRoot,
+                },
+                null,
+                2,
+            ),
+        );
+        return { code: 0, out, err: [] };
+    }
+
+    if (found !== null) {
+        out.push(`brand layer   present — ${found}`);
+        out.push('              brand-source-of-truth applies: these tokens outrank the corpus.');
+    } else {
+        out.push('brand layer   none');
+        out.push(`  searched    ${BRAND_TOKEN_PATHS.join(', ')}`);
+        out.push('  meaning     no consumer brand to be authoritative. The corpus is the only');
+        out.push('              ground, and every emitted value is corpus-sourced — which is the');
+        out.push('              greenfield branch of brand-source-of-truth, not a misconfiguration.');
+    }
+
+    if (nearMisses.length > 0) {
+        out.push(
+            '',
+            '⚠️  A dot-prefixed tokens file exists and is NOT read by anything:',
+            ...nearMisses.map((m) => `      ${m}`),
+            '    The resolver searches `tokens.json`, never `.tokens.json`. Rename it to one',
+            '    of the searched paths above, or it stays invisible while looking authored.',
+        );
+    }
+
+    return { code: 0, out, err: [] };
+}
+
+interface ParsedArgv {
+    ok: boolean;
+    message?: string;
+    json?: boolean;
+}
+
+export function parseArgv(argv: readonly string[]): ParsedArgv {
+    let json = false;
+    for (const a of argv) {
+        if (a === '--json') {
+            json = true;
+        } else if (a === '-h' || a === '--help') {
+            return { ok: false, message: 'usage: agent-config brand:status [--json]' };
+        } else {
+            return { ok: false, message: `unknown argument: ${a}` };
+        }
+    }
+    return { ok: true, json };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const parsed = parseArgv(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.message ?? 'usage error'}\n`);
+        return 2;
+    }
+    const result = runBrandStatus({ cwd: process.cwd(), json: parsed.json === true });
+    for (const line of result.out) process.stdout.write(`${line}\n`);
+    for (const line of result.err) process.stderr.write(`${line}\n`);
+    return result.code;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}

package/src/scripts/_cli/cmd_conformance.ts

@@ -10,7 +10,9 @@
  *   (b) router-pointers      — dist/router.json ids + routes_to resolve on disk
  *   (c) hook-dispatcher      — dispatcher answers synthetic session_start/stop
  *   (d) lean-projection      — lean_projection.mode matches projected artifacts
- *   (e) host-manifest        — subagents.host_capabilities parses strictly
+ *   (e) host-manifest        — a leftover subagents.host_capabilities override
+ *                              is deprecated + ignored (always-on orchestration
+ *                              resolves capability from a probe/registry only)
  *
  * All checks are deterministic — no LLM, no network. Exit contract:
  *   0 = every check ok/skipped (warns allowed) and doctor --ci green
@@ -421,14 +423,6 @@ export function _check_lean_projection(
 // Check (e) — host-capability manifest parses strictly + matches detection.
 // ---------------------------------------------------------------------------
 
-const HOST_MANIFEST_KEYS = new Set([
-    'schema_version',
-    'subagent_spawn',
-    'parallel_spawn',
-    'status_polling',
-    'separate_quota_pool',
-]);
-
 export function _check_host_manifest(projectRoot: string): Dict {
     const detected = Object.entries(detectToolPresence(projectRoot))
         .filter(([, v]) => v === true)
@@ -441,7 +435,7 @@ export function _check_host_manifest(projectRoot: string): Dict {
         return {
             id: 'host-manifest',
             status: 'ok',
-            message: `no .agent-settings.yml — safe-default manifest applies (${detectedNote})`,
+            message: `no .agent-settings.yml — host capability is always probe/registry-resolved (${detectedNote})`,
             remedy: '',
         };
     }
@@ -462,44 +456,22 @@ export function _check_host_manifest(projectRoot: string): Dict {
         return {
             id: 'host-manifest',
             status: 'ok',
-            message: `no host_capabilities override — safe-default manifest applies (${detectedNote})`,
+            message: `no host_capabilities override — host capability is always probe/registry-resolved (${detectedNote})`,
             remedy: '',
         };
     }
-    if (typeof manifest !== 'object' || Array.isArray(manifest)) {
-        return {
-            id: 'host-manifest',
-            status: 'fail',
-            message: 'subagents.host_capabilities is not a mapping',
-            remedy: 'use the four boolean fields from the host-capability manifest contract',
-        };
-    }
-    const problems: string[] = [];
-    for (const [key, value] of Object.entries(manifest as Dict)) {
-        if (!HOST_MANIFEST_KEYS.has(key)) {
-            problems.push(`unknown key '${key}'`);
-            continue;
-        }
-        if (key === 'schema_version') {
-            if (value !== 1) problems.push(`schema_version must be 1 (got ${JSON.stringify(value)})`);
-            continue;
-        }
-        if (typeof value !== 'boolean') {
-            problems.push(`'${key}' must be boolean (got ${JSON.stringify(value)})`);
-        }
-    }
-    if (problems.length > 0) {
-        return {
-            id: 'host-manifest',
-            status: 'fail',
-            message: `host_capabilities malformed: ${problems.slice(0, 4).join('; ')}`,
-            remedy: 'only schema_version:1 + four boolean capability fields are valid',
-        };
-    }
+    // Always-on orchestration (road-to-always-on-orchestration Phase 1)
+    // deleted `subagents.host_capabilities` as a live override — capability
+    // now resolves ONLY from the host probe/registry. A leftover key is
+    // therefore inert: its shape no longer matters, so this no longer fails
+    // on an unknown key or a non-boolean value — there is nothing left for a
+    // malformed override to break.
     return {
         id: 'host-manifest',
         status: 'ok',
-        message: `host_capabilities override parses strictly (${detectedNote})`,
+        message:
+            `subagents.host_capabilities is deprecated and ignored — host capability is ` +
+            `always probe/registry-resolved (${detectedNote})`,
         remedy: '',
     };
 }

package/src/scripts/_cli/cmd_doctor.ts

@@ -1050,7 +1050,7 @@ function _check_lockfile_freshness(manifest: Dict): Dict {
 }
 
 /** `shutil.which(name)` — first PATH hit (with PATHEXT on win32). */
-function shutilWhich(name: string): string | null {
+export function shutilWhich(name: string): string | null {
     if (path.dirname(name) !== '.' && (name.includes('/') || name.includes('\\'))) {
         // Has a path component: check directly.
         return isExecutableFile(name) ? name : null;
@@ -2065,6 +2065,31 @@ function osErrorStr(exc: unknown): string {
 const _CLI_PROVIDER_META: Readonly<Record<string, readonly [string, boolean]>> =
     PROVIDER_CLI_META;
 
+/**
+ * m5 fix (independent-review finding) — `MemberConfig.mode` is the RAW
+ * per-member override only (`config.ts::_build_member` never writes the
+ * `defaults.mode`-resolved value back onto it); a member that never sets
+ * `mode:` locally has `member.mode === null` regardless of what the
+ * council's global default is. `defaults.mode` shipped `'auto'` as its own
+ * default (road-to-always-on-orchestration Phase 3.1), so the common,
+ * unconfigured case for every member is `null` here — and `auto` may
+ * legitimately resolve to the `cli` rung, exactly the case
+ * `config.ts::_build_member`'s own binary-override validation already
+ * accounts for ("`auto` may resolve to the cli rung, so a binary override
+ * is legitimate there too"). A check gated on the literal `mode === 'cli'`
+ * misses every `auto`/unset member, honouring neither its binary override
+ * nor its quota — silently, for the majority default shape.
+ */
+function _effectiveMemberMode(member: ai_council_config.MemberConfig, cfg: ai_council_config.CouncilConfig): string {
+    return member.mode ?? cfg.defaults.mode;
+}
+
+/** True when `member` might run over CLI transport — `cli` pinned, or `auto` (which may resolve to it). */
+function _mayRunOverCli(member: ai_council_config.MemberConfig, cfg: ai_council_config.CouncilConfig): boolean {
+    const mode = _effectiveMemberMode(member, cfg);
+    return mode === 'cli' || mode === 'auto';
+}
+
 function _check_council_cli(project_root: string): Dict {
     // Python wraps the council-module import in a try/except ImportError so a
     // broken council install degrades to a `warn` instead of crashing doctor.
@@ -2097,7 +2122,7 @@ function _check_council_cli(project_root: string): Dict {
     }
     const cli_members: Array<[string, ai_council_config.MemberConfig]> = [];
     for (const [name, m] of cfg.members.entries()) {
-        if (m.enabled && m.mode === 'cli' && name in _CLI_PROVIDER_META) {
+        if (m.enabled && _mayRunOverCli(m, cfg) && name in _CLI_PROVIDER_META) {
             cli_members.push([name, m]);
         }
     }
@@ -2216,11 +2241,12 @@ function _codex_home(): string {
 
 /**
  * Codex binary name for the team check — REUSES the council probe's binary
- * discovery: when a council config exists and declares an enabled cli-mode
- * `openai` member with a `binary` override, honour it; else the provider
- * default from `_CLI_PROVIDER_META` (`codex`). Never throws — an unreadable
- * or invalid council config falls back to the default binary (the council-cli
- * check owns reporting that problem).
+ * discovery: when a council config exists and declares an enabled `openai`
+ * member whose effective mode is `cli` (pinned) OR `auto` (may resolve to
+ * `cli` — see `_mayRunOverCli`) with a `binary` override, honour it; else
+ * the provider default from `_CLI_PROVIDER_META` (`codex`). Never throws —
+ * an unreadable or invalid council config falls back to the default binary
+ * (the council-cli check owns reporting that problem).
  */
 function _team_codex_binary_name(project_root: string): string {
     const default_bin = (_CLI_PROVIDER_META['openai'] as [string, boolean])[0];
@@ -2236,21 +2262,12 @@ function _team_codex_binary_name(project_root: string): string {
         return default_bin;
     }
     const member = cfg.members.get('openai');
-    if (member && member.enabled && member.mode === 'cli' && member.binary) {
+    if (member && member.enabled && _mayRunOverCli(member, cfg) && member.binary) {
         return member.binary;
     }
     return default_bin;
 }
 
-/** Settings-flag coercion shared with the tier-usage check (bool or string). */
-function _settings_flag(val: unknown): boolean {
-    if (typeof val === 'boolean') return val;
-    if (typeof val === 'string') {
-        return ['true', 'yes', 'on', '1'].includes(val.trim().toLowerCase());
-    }
-    return false;
-}
-
 /**
  * Decode a JWT payload's `exp` claim (epoch seconds) — base64 decode only,
  * NO signature verification, no network. Non-JWT / undecodable → null.
@@ -2364,9 +2381,16 @@ function _read_ai_team_block(project_root: string): Dict {
  *     loop bound (`max_consecutive_blocks`, Phase 4 — unbuilt) is absent
  *     → WARN.
  *
- * Absent feature ≠ broken feature: with `ai_team` absent or disabled the
- * check reports ok ("team mode not configured (default-off)"); WARN fires
- * only on failing sub-signals or inconsistent half-configured states.
+ * Availability, not a setting (road-to-always-on-orchestration Phase 1,
+ * Step 1.3): `ai_team.enabled` was DELETED — `/team`'s on/off state is the
+ * codex binary + auth facts (a) computes below, mirroring
+ * `checkCodexAvailability()` (`src/scripts/ai_team/availability.ts`).
+ * Absent feature ≠ broken feature: with BOTH the binary and auth absent the
+ * check reports ok ("team unavailable (default) — codex CLI not
+ * installed") — a normal starting state, not a misconfiguration; WARN
+ * fires only when something was set up PARTWAY (binary without auth, a
+ * managed Review-Gate with an invalid bound, …) or a real sub-signal
+ * fails.
  */
 // ---------------------------------------------------------------------------
 // detection check (road-to-zero-ceremony-detection Phases 3 + 4)
@@ -2526,36 +2550,11 @@ function _check_detection(project_root: string): Dict {
 
 function _check_team(project_root: string): Dict {
     const ai_team = _read_ai_team_block(project_root);
-    const enabled = _settings_flag(ai_team['enabled']);
     const gateRaw = ai_team['review_gate'];
     const gate =
         typeof gateRaw === 'object' && gateRaw !== null && !Array.isArray(gateRaw)
             ? (gateRaw as Dict)
             : {};
-    const gate_managed = _settings_flag(gate['managed']);
-
-    if (!enabled) {
-        if (gate_managed) {
-            return {
-                id: 'team',
-                status: 'warn',
-                message:
-                    'half-configured: ai_team.review_gate.managed is on but ' +
-                    'ai_team.enabled is false — the gate never runs',
-                remedy:
-                    'set `ai_team.enabled: true` in .agent-settings.yml, or ' +
-                    'remove `ai_team.review_gate.managed`',
-            };
-        }
-        return {
-            id: 'team',
-            status: 'ok',
-            message: 'team mode not configured (default-off)',
-            remedy:
-                'opt in via `ai_team.enabled: true` in .agent-settings.yml, ' +
-                'then re-run `agent-config doctor --check team`',
-        };
-    }
 
     const remedies: string[] = [];
 
@@ -2563,7 +2562,8 @@ function _check_team(project_root: string): Dict {
     const binary_name = _team_codex_binary_name(project_root);
     const binary_resolved = shutilWhich(binary_name);
     const binary_glyph = binary_resolved !== null ? '✅' : '❌';
-    if (binary_resolved === null) {
+    const binary_missing = binary_resolved === null;
+    if (binary_missing) {
         remedies.push('install the codex CLI: `npm install -g @openai/codex`');
     }
 
@@ -2613,7 +2613,8 @@ function _check_team(project_root: string): Dict {
     // (c) Review-Gate governance (Phase 4) — logic lives in
     // src/scripts/ai_team/review_gate.ts (upstream gate probe + WARN
     // states, incl. plugin-gate-on-while-unmanaged with the quoted
-    // upstream cost warning).
+    // upstream cost warning). Independent of /team's own availability —
+    // `managed` governs the codex PLUGIN's own Stop-hook loop.
     const gate_signal = review_gate_doctor_signal(project_root, gate);
     const gate_str = gate_signal.gate_str;
     remedies.push(...gate_signal.remedies);
@@ -2621,6 +2622,21 @@ function _check_team(project_root: string): Dict {
     const detail =
         `codex binary ${binary_glyph} (${binary_name}) · ` +
         `${auth_str} · ${plugin_str} · ${gate_str}`;
+
+    if (binary_missing && !authed) {
+        // Neither the binary nor auth is present — /team simply is not set
+        // up on this machine yet. CLI-first doctrine (road-to-always-on-
+        // orchestration Phase 1, Step 1.3): this is a normal starting
+        // state, not a misconfiguration — still surface the full detail
+        // (e.g. a `review_gate.managed` left on) so nothing is hidden.
+        return {
+            id: 'team',
+            status: 'ok',
+            message: `team unavailable (default) — codex CLI not installed · ${detail}`,
+            remedy: remedies.join('; '),
+        };
+    }
+
     if (remedies.length > 0) {
         return {
             id: 'team',
@@ -2632,7 +2648,7 @@ function _check_team(project_root: string): Dict {
     return {
         id: 'team',
         status: 'ok',
-        message: `team mode enabled · ${detail}`,
+        message: `team available · ${detail}`,
         remedy: '',
     };
 }
@@ -3556,6 +3572,7 @@ export {
     _foreign_records,
     _check_scope,
     _check_manifest_integrity,
+    _team_codex_binary_name,
     _check_lockfile_freshness,
     _check_global_binary,
     _check_claude_plugin,