@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/council_cli.ts

@@ -117,6 +117,15 @@ import {
 } from './ai_council/consensus.js';
 import * as _shadow from './ai_council/shadow_dispatch.js';
 import * as _lowimpact from './ai_council/low_impact.js';
+import {
+    apply_chairman_override,
+    assign_stances,
+    build_blind_labels,
+    OUTSIDER_STANCE_NAME,
+    parse_chairman_override,
+    render_deanonymization_block,
+    with_chairman_fields,
+} from './ai_council/blind_review.js';
 
 // ── argparse-style exit plumbing ────────────────────────────────────
 // Mirror CPython argparse: a `prog: error: …` line on stderr + exit 2.
@@ -435,6 +444,12 @@ function _synthesize_ai_council_block(cfg: CouncilConfig): Dict {
         if (m.model_ladder && m.model_ladder.length > 0) {
             entry['model_ladder'] = [...m.model_ladder];
         }
+        // road-to-cache-economy Phase 4: forward only an explicit override —
+        // the '5m' default needs no key, keeping the synthesized block
+        // byte-identical to pre-Phase-4 output when nobody opted in.
+        if (m.prompt_cache_ttl !== '5m') {
+            entry['prompt_cache_ttl'] = m.prompt_cache_ttl;
+        }
         members[name] = entry;
     }
     const advisors: Dict = {};
@@ -474,6 +489,7 @@ function _synthesize_ai_council_block(cfg: CouncilConfig): Dict {
             max_output_tokens: cfg.cost_budget.max_output_tokens,
             max_calls: cfg.cost_budget.max_calls,
             max_total_usd: cfg.cost_budget.max_total_usd,
+            daily_limit_usd: cfg.cost_budget.daily_limit_usd,
         },
         consensus_scoring: {
             enabled: cfg.consensus_scoring.enabled,
@@ -608,9 +624,16 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             // Council opts in explicitly (caching is client-default OFF): on
             // unless the operator sets `prompt_cache: false` on the member.
             const enable_prompt_cache = cfg['prompt_cache'] !== false;
+            // road-to-cache-economy Phase 4: absent → AnthropicClient's own
+            // '5m' default; only an explicit '1h' override reaches here.
+            const prompt_cache_ttl = (cfg['prompt_cache_ttl'] as '5m' | '1h' | undefined) ?? undefined;
             for (const sib_model of siblings[name] as string[]) {
                 members.push(
-                    _construct_api_member(name, sib_model, { api_key_ref, enable_prompt_cache }),
+                    _construct_api_member(name, sib_model, {
+                        api_key_ref,
+                        enable_prompt_cache,
+                        prompt_cache_ttl,
+                    }),
                 );
             }
             continue;
@@ -623,6 +646,8 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
                     // Council opts in explicitly (client-default OFF); on unless
                     // the operator sets `prompt_cache: false`.
                     enable_prompt_cache: cfg['prompt_cache'] !== false,
+                    // road-to-cache-economy Phase 4 — see the siblings branch above.
+                    prompt_cache_ttl: (cfg['prompt_cache_ttl'] as '5m' | '1h' | undefined) ?? undefined,
                 }),
             );
         } else if (mode === 'cli' && _CLI_PROVIDERS.has(name)) {
@@ -757,7 +782,11 @@ function _format_advisor_summary(
 function _construct_api_member(
     name: string,
     model: string | null,
-    opts: { api_key_ref?: string | null; enable_prompt_cache?: boolean | undefined } = {},
+    opts: {
+        api_key_ref?: string | null;
+        enable_prompt_cache?: boolean | undefined;
+        prompt_cache_ttl?: '5m' | '1h' | undefined;
+    } = {},
 ): ExternalAIClient {
     const api_key_ref = opts.api_key_ref ?? null;
     if (name === 'anthropic') {
@@ -768,6 +797,7 @@ function _construct_api_member(
             model: model || 'claude-sonnet-4-5',
             api_key,
             enable_prompt_cache: opts.enable_prompt_cache,
+            prompt_cache_ttl: opts.prompt_cache_ttl,
         });
     }
     if (name === 'openai') {
@@ -1168,16 +1198,36 @@ function _maybe_run_chairman(
             response: null,
         };
     }
-    // Transcript WITH identities (the chairman judges attributed positions) +
-    // the lens synthesis template as the authoring instruction.
-    const transcript = responses
-        .filter((r) => r.error === null && r.text.trim() !== '')
-        .map((r) => `## ${r.provider} - ${r.model}\n\n${r.text.trim()}`)
-        .join('\n\n---\n\n');
-    const synth_prompt =
-        `You are the council CHAIRMAN. You did not deliberate. Author the synthesis ` +
-        `of the attributed member positions below, following the template.\n\n` +
-        `${synthesis_template(question.mode)}\n\n---\n\n${transcript}`;
+    // road-to-council-blind-review Phase 1 (Ü1): --blind-chairman shuffles the
+    // transcript deterministically (seeded by the question text) and strips
+    // identity to Response-A/B/… labels, reusing the EXISTING
+    // `consensus.anonymize_responses` seam. The default path below (transcript
+    // WITH identities — "the chairman judges attributed positions") is
+    // byte-identical to today.
+    const blind = args.blind_chairman === true;
+    let transcript: string;
+    let blind_label_to_source: Map<string, string> | null = null;
+    const successful = responses.filter((r) => r.error === null && r.text.trim() !== '');
+    if (blind) {
+        const pairs: Array<[string, string]> = successful.map((r) => [`${r.provider}:${r.model}`, r.text]);
+        const built = build_blind_labels(question.user_prompt, pairs);
+        transcript = built.transcript;
+        blind_label_to_source = built.label_to_source;
+    } else {
+        transcript = successful
+            .map((r) => `## ${r.provider} - ${r.model}\n\n${r.text.trim()}`)
+            .join('\n\n---\n\n');
+    }
+    // Ü3: --chairman-fields appends the two mandatory trailing sections.
+    const template =
+        args.chairman_fields === true ? with_chairman_fields(synthesis_template(question.mode)) : synthesis_template(question.mode);
+    const synth_prompt = blind
+        ? `You are the council CHAIRMAN. You did not deliberate. Author the synthesis ` +
+          `of the anonymized member positions below (labels A–E). Do not guess ` +
+          `identities.\n\n${template}\n\n---\n\n${transcript}`
+        : `You are the council CHAIRMAN. You did not deliberate. Author the synthesis ` +
+          `of the attributed member positions below, following the template.\n\n` +
+          `${template}\n\n---\n\n${transcript}`;
     const synthQ = new CouncilQuestion({
         mode: question.mode,
         user_prompt: synth_prompt,
@@ -1197,7 +1247,13 @@ function _maybe_run_chairman(
             response: r,
         };
     }
-    return { member: sel.member, annotation: sel.annotation, text: r.text, response: r };
+    // Blind is only at decision time — de-anonymization lands in the audit
+    // artifact immediately after the verdict, never fed back into a prompt.
+    const final_text =
+        blind && blind_label_to_source !== null
+            ? `${r.text.trim()}\n\n${render_deanonymization_block('### De-anonymization (post-verdict)', blind_label_to_source)}`
+            : r.text;
+    return { member: sel.member, annotation: sel.annotation, text: final_text, response: r };
 }
 
 function _maybe_run_peer_review(
@@ -1840,6 +1896,15 @@ function _apply_solo_dispatch(members: ExternalAIClient[]): [ExternalAIClient[],
     ];
 }
 
+/** `--chairman` value → parsed override, or `ArgumentTypeError` on malformed input. */
+function _resolved_chairman_override(raw: string | null) {
+    try {
+        return parse_chairman_override(raw);
+    } catch (exc) {
+        throw new ArgumentTypeError(exc instanceof Error ? exc.message : String(exc));
+    }
+}
+
 function cmd_run(
     args: Args,
     opts: { settings?: Dict | null; members?: ExternalAIClient[] | null; table?: PriceTable | null } = {},
@@ -1850,7 +1915,12 @@ function cmd_run(
     if (settings === null) {
         settings = load_settings();
     }
-    const ai_cfg = _isDict(settings) ? ((settings['ai_council'] as Dict) || {}) : {};
+    // road-to-council-blind-review Phase 1: `--chairman host|auto|member:NAME`
+    // is a pure runtime override, never a config write.
+    const ai_cfg = apply_chairman_override(
+        _isDict(settings) ? ((settings['ai_council'] as Dict) || {}) : {},
+        _resolved_chairman_override(_getattr<string | null>(args, 'chairman', null)),
+    ) as Dict;
     const advisor_plans = _build_advisor_plans(ai_cfg, REPO_ROOT);
     const explicit_overrides = _parse_model_overrides(_getattr<string[] | null>(args, 'model', null));
     const skipped: Dict[] = [];
@@ -1971,6 +2041,11 @@ function cmd_run(
         max_output_tokens: _pyInt(cost_cfg['max_output_tokens'] ?? 20_000, 20_000),
         max_calls: _pyInt(cost_cfg['max_calls'] ?? 10, 10),
         max_total_usd: _pyFloat(cost_cfg['max_total_usd'] ?? 0.0, 0.0) || 0.0,
+        // Rolling 24h cap. Unwired until now: the field existed on CostBudget and
+        // gated the spend-ledger append, but no caller ever passed it, so the
+        // ledger could not be written at all — an archived acceptance criterion
+        // claimed otherwise. 0 keeps the cap disabled, which stays the default.
+        daily_limit_usd: _pyFloat(cost_cfg['daily_limit_usd'] ?? 0.0, 0.0) || 0.0,
     });
     const rounds = _resolve_rounds(args, ai_cfg);
     // Phase 1: stance tally — defensive read; malformed/absent block reads as off.
@@ -1978,6 +2053,21 @@ function cmd_run(
         _isDict(ai_cfg) &&
         _isDict(ai_cfg['stance_tally']) &&
         (ai_cfg['stance_tally'] as Dict)['enabled'] === true;
+    // road-to-council-blind-review Phase 1 (Ü2): five orthogonal stances
+    // rotated deterministically over the config-ordered member list; the
+    // outsider seat additionally drops project_context. Default off.
+    const stances_on = args.stances === true;
+    const stance_assignment = stances_on ? assign_stances(members.map((m) => m.name), question.user_prompt) : null;
+    const member_prompt_suffix = stance_assignment
+        ? new Map(Array.from(stance_assignment.entries()).map(([name, s]) => [name, s.prompt]))
+        : null;
+    const no_project_context_members = stance_assignment
+        ? new Set(
+              Array.from(stance_assignment.entries())
+                  .filter(([, s]) => s.name === OUTSIDER_STANCE_NAME)
+                  .map(([name]) => name),
+          )
+        : null;
     const stance_repairs: CouncilResponse[] = [];
     const responses = consult(members, question, budget, {
         table,
@@ -1986,6 +2076,8 @@ function cmd_run(
         rounds,
         advisor_plans,
         stance_tally: stance_tally_on,
+        member_prompt_suffix,
+        no_project_context_members,
         // Interactive one-line confirm (cmd_run has no --auto-continue); the
         // repaired-call cost is collected so cost_usd_actual stays honest.
         on_stance_repair: stance_tally_on
@@ -2009,6 +2101,22 @@ function cmd_run(
     );
     const consensus = _maybe_run_consensus(ai_cfg, question, members, responses, budget, table, project, args);
     const chairman = _maybe_run_chairman(ai_cfg, question, members, responses, budget, table, project, args);
+    // road-to-council-blind-review Phase 1 (Ü1), host-path only: when no
+    // member chairman ran (mode === 'host'), the blind mapping is computed
+    // here (seeded from the question text) and persisted for a later
+    // `council:render` to blind the response headers. The member-chairman
+    // path (below, inside `_maybe_run_chairman`) blinds inline instead.
+    const blind_chairman_on = args.blind_chairman === true;
+    const chairman_fields_on = args.chairman_fields === true;
+    let blind_review_map: Map<string, string> | null = null;
+    if (blind_chairman_on && chairman === null) {
+        const pairs: Array<[string, string]> = responses
+            .filter((r) => r.error === null && r.text.trim() !== '')
+            .map((r) => [`${r.provider}:${r.model}`, r.text]);
+        if (pairs.length > 0) {
+            blind_review_map = build_blind_labels(question.user_prompt, pairs).label_to_source;
+        }
+    }
     const estimated_total = estimates.reduce((acc, e) => acc + _total_usd(e), 0.0);
     let actual_total = 0.0;
     const all_responses: CouncilResponse[] = [...responses];
@@ -2043,6 +2151,9 @@ function cmd_run(
         cost_usd_estimated: _pyRound(estimated_total, 6),
         cost_usd_actual: _pyRound(actual_total, 6),
         stance_tally: stance_tally_on,
+        stances: stances_on,
+        blind_chairman: blind_chairman_on,
+        chairman_fields: chairman_fields_on,
         responses: _serialise_responses(responses),
     };
     if (peer_review !== null) {
@@ -2054,6 +2165,9 @@ function cmd_run(
     if (chairman !== null) {
         payload['chairman'] = { member: chairman.member, annotation: chairman.annotation, text: chairman.text };
     }
+    if (blind_review_map !== null) {
+        payload['blind_review_map'] = _mapToObject(blind_review_map);
+    }
     const out_path = _validate_council_output_path(args.output as string, {
         kind: 'responses',
         subcommand: 'run',
@@ -2096,6 +2210,11 @@ function _write_debate_round(
         table: PriceTable;
         prompt_mode: string | null;
         prose_synthesis: boolean | null;
+        // road-to-cache-economy Phase 4: the observed wall-clock gap (ms)
+        // between the previous round finishing and this round starting —
+        // `null`/absent on round 1, since nothing was written to the
+        // prompt cache yet. See `run_debate`'s `on_round_complete`.
+        cache_gap_ms_since_previous_round?: number | null | undefined;
     },
 ): string {
     fs.mkdirSync(_resolveTarget(out_dir), { recursive: true });
@@ -2119,6 +2238,7 @@ function _write_debate_round(
         debate_total_rounds: opts.total_planned_rounds,
         rounds: 1,
         cost_usd_actual: _pyRound(actual_total, 6),
+        prompt_cache_round_gap_ms: opts.cache_gap_ms_since_previous_round ?? null,
         responses: _serialise_responses(responses),
     };
     const out_path = path.join(_resolveTarget(out_dir), _debate_round_filename(round_number));
@@ -2322,6 +2442,11 @@ function cmd_debate(
         max_output_tokens: _pyInt(cost_cfg['max_output_tokens'] ?? 20_000, 20_000),
         max_calls: _pyInt(cost_cfg['max_calls'] ?? 10, 10),
         max_total_usd: _pyFloat(cost_cfg['max_total_usd'] ?? 0.0, 0.0) || 0.0,
+        // Rolling 24h cap. Unwired until now: the field existed on CostBudget and
+        // gated the spend-ledger append, but no caller ever passed it, so the
+        // ledger could not be written at all — an archived acceptance criterion
+        // claimed otherwise. 0 keeps the cap disabled, which stays the default.
+        daily_limit_usd: _pyFloat(cost_cfg['daily_limit_usd'] ?? 0.0, 0.0) || 0.0,
     });
 
     const out_dir = _validate_council_output_path(args.output as string, {
@@ -2339,7 +2464,11 @@ function cmd_debate(
 
     const written: string[] = [];
 
-    const _on_round_complete = (round_number: number, results: CouncilResponse[]): void => {
+    const _on_round_complete = (
+        round_number: number,
+        results: CouncilResponse[],
+        cache_gap_ms_since_previous_round?: number | null,
+    ): void => {
         const p = _write_debate_round(out_dir, round_number, results, {
             question,
             members: members as ExternalAIClient[],
@@ -2349,6 +2478,7 @@ function cmd_debate(
             table: table as PriceTable,
             prompt_mode: 'debate',
             prose_synthesis: _getattr<boolean | null>(args, 'prose_synthesis', null),
+            cache_gap_ms_since_previous_round,
         });
         written.push(p);
         const errors = results.filter((r) => r.error);
@@ -2452,12 +2582,18 @@ function cmd_render(args: Args): number {
     }
     const consensus = _deserialise_consensus(payload['consensus'] as Dict);
     const peer_review = _deserialise_peer_review(payload['peer_review'] as Dict);
+    // road-to-council-blind-review Phase 1: a persisted `blind_review_map`
+    // means `--blind-chairman` ran on the host path (no member chairman) —
+    // blind the response headers + append the de-anonymization map.
+    const blind_map_raw = payload['blind_review_map'];
     const body = render(_deserialise_responses(items), {
         mode: mode ?? null,
         prose_synthesis: prose,
         consensus,
         peer_review,
         stance_tally: payload['stance_tally'] === true,
+        chairman_fields: payload['chairman_fields'] === true,
+        blind: _isDict(blind_map_raw) ? { label_to_source: _objToMap(blind_map_raw as Dict) } : null,
         chairman: _isDict(payload['chairman'])
             ? (payload['chairman'] as { member: string | null; annotation: string; text: string | null })
             : null,
@@ -2672,6 +2808,11 @@ interface Args {
     auto_continue: boolean;
     restate?: boolean;
     continue_as_debate: string | null;
+    // road-to-council-blind-review Phase 1 — flag-gated, default-off (`run` only)
+    chairman: string | null;
+    blind_chairman: boolean;
+    stances: boolean;
+    chairman_fields: boolean;
     // render / replay
     responses?: string | null;
     include_member_arguments: boolean | null;
@@ -2726,6 +2867,15 @@ function _defaultArgs(): Args {
         prose_synthesis: null,
         auto_continue: false,
         continue_as_debate: null,
+        chairman: null,
+        // Ü1 ADOPTED (road-to-council-blind-review Phase 3, 2026-07-28):
+        // blind synthesis is the default — 0/10 + 0/10 pre-registered
+        // degradation triggers on the n=10 A/B; opt out per-invocation
+        // with --no-blind-chairman (the audit artifact always keeps the
+        // post-verdict de-anonymization map either way).
+        blind_chairman: true,
+        stances: false,
+        chairman_fields: false,
         responses: null,
         include_member_arguments: null,
         low_impact_stats: false,
@@ -2788,6 +2938,12 @@ function _specsFor(cmd: string): { positionals: string[]; opts: OptSpec[]; requi
                     { flag: '--single', takesValue: false, apply: (o) => (o.single = true) },
                     { flag: '--prose-synthesis', takesValue: false, apply: (o) => (o.prose_synthesis = true) },
                     { flag: '--no-prose-synthesis', takesValue: false, apply: (o) => (o.prose_synthesis = false) },
+                    // road-to-council-blind-review Phase 1 — flag-gated, default-off.
+                    { flag: '--chairman', takesValue: true, apply: (o, v) => (o.chairman = v) },
+                    { flag: '--blind-chairman', takesValue: false, apply: (o) => (o.blind_chairman = true) },
+                    { flag: '--no-blind-chairman', takesValue: false, apply: (o) => (o.blind_chairman = false) },
+                    { flag: '--stances', takesValue: false, apply: (o) => (o.stances = true) },
+                    { flag: '--chairman-fields', takesValue: false, apply: (o) => (o.chairman_fields = true) },
                 ],
                 requiredOpts: ['--output'],
             };

package/src/scripts/detect_target_license.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * detect_target_license — deterministic SPDX license detection + derived
+ * borrow-compatibility policy (road-to-provenance-and-license-governance
+ * S1.2). CLI wrapper — the actual detection/matrix/invalidation/override
+ * logic lives in `./_lib/detect_target_license.ts` (that module does the
+ * filesystem I/O too; detection is inherently a file-read job). This file
+ * owns only argv parsing, stdout/stderr shaping, schema validation, and the
+ * `--write` side effect.
+ *
+ * Usage:
+ *   npx tsx src/scripts/detect_target_license.ts [repo-path] [--write] [--json]
+ *   npx tsx src/scripts/detect_target_license.ts --help
+ *
+ * Default (no --write): report only, nothing written to disk.
+ * --write   create/update license-policy.yaml in the target repo, unless
+ *           escalation is required or the existing file is derived_from: manual.
+ *
+ * Exit codes: 0 success (including the warn-only "nothing detectable"
+ * path); 1 usage/IO/schema error; 2 escalation required — a human decision,
+ * never an auto-pick (source disagreement, or a divergent workspace license).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+import {
+    buildLicensePolicyDocument,
+    checkInvalidation,
+    detectTargetLicense,
+    mergeOverride,
+    type LicensePolicyDoc,
+} from './_lib/detect_target_license.js';
+import { load_schema, validate, type YamlValue } from './validate_frontmatter.js';
+
+export const POLICY_FILENAME = 'license-policy.yaml';
+
+const USAGE = `usage: detect_target_license [repo-path] [--write] [--json] [-h|--help]
+
+Deterministic SPDX license detection + derived borrow-compatibility policy.
+
+  repo-path   target repo root (default: .)
+  --write     write/update ${POLICY_FILENAME} in the target repo (skipped on
+              escalation, or when the existing file is derived_from: manual)
+  --json      machine-readable report on stdout
+
+Exit codes: 0 success, 1 usage/IO/schema error, 2 escalation required.
+`;
+
+export interface CliArgs {
+    repoPath: string;
+    write: boolean;
+    json: boolean;
+    help: boolean;
+}
+
+export function parseArgs(argv: string[]): CliArgs {
+    let repoPath = '.';
+    let write = false;
+    let json = false;
+    let help = false;
+    for (const a of argv) {
+        if (a === '-h' || a === '--help') help = true;
+        else if (a === '--write') write = true;
+        else if (a === '--json') json = true;
+        else if (!a.startsWith('--')) repoPath = a;
+    }
+    return { repoPath, write, json, help };
+}
+
+export function serializeLicensePolicy(doc: LicensePolicyDoc): string {
+    return stringifyYaml(doc, { indent: 2 });
+}
+
+export function parseLicensePolicyFile(text: string): LicensePolicyDoc {
+    return parseYaml(text) as LicensePolicyDoc; // caller schema-validates before trusting this
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+
+    const repoRoot = path.resolve(args.repoPath);
+    if (!fs.existsSync(repoRoot) || !fs.statSync(repoRoot).isDirectory()) {
+        process.stderr.write(`detect_target_license: error: not a directory: ${repoRoot}\n`);
+        return 1;
+    }
+
+    const detection = detectTargetLicense(repoRoot);
+
+    if (detection.escalate) {
+        if (args.json) {
+            process.stdout.write(JSON.stringify({
+                escalate: true,
+                reason: detection.escalateReason,
+                spdx_id: detection.spdxId,
+                warnings: detection.warnings,
+            }) + '\n');
+        } else {
+            process.stdout.write(`detect_target_license: ESCALATE — ${detection.escalateReason ?? 'unspecified'}\n`);
+            for (const w of detection.warnings) process.stdout.write(`  warning: ${w}\n`);
+            process.stdout.write(`No ${POLICY_FILENAME} written. This needs a human decision, never an auto-pick.\n`);
+        }
+        return 2;
+    }
+
+    const nowIso = new Date().toISOString();
+    const freshDoc = buildLicensePolicyDocument(detection, nowIso);
+    const policyPath = path.join(repoRoot, POLICY_FILENAME);
+
+    let finalDoc: LicensePolicyDoc = freshDoc;
+    let rejectedOverrides: string[] = [];
+    let action: 'derived' | 'kept-manual' | 're-derived' | 'merged' | 'unchanged' = 'derived';
+
+    if (fs.existsSync(policyPath)) {
+        let existing: LicensePolicyDoc | null = null;
+        try {
+            existing = parseLicensePolicyFile(fs.readFileSync(policyPath, 'utf8'));
+        } catch (err) {
+            process.stderr.write(
+                `detect_target_license: warning: failed to parse existing ${POLICY_FILENAME}, ` +
+                `treating as absent: ${err instanceof Error ? err.message : String(err)}\n`,
+            );
+        }
+
+        if (existing) {
+            const invalidation = checkInvalidation(existing, detection);
+            if (invalidation.action === 'escalate') {
+                if (args.json) {
+                    process.stdout.write(JSON.stringify({ escalate: true, reason: invalidation.reason }) + '\n');
+                } else {
+                    process.stdout.write(`detect_target_license: ESCALATE — ${invalidation.reason}\n`);
+                    process.stdout.write(`${POLICY_FILENAME} left unchanged. This needs a human decision, never an auto-pick.\n`);
+                }
+                return 2;
+            }
+            if (existing.derived_from === 'manual') {
+                finalDoc = existing;
+                action = 'kept-manual';
+            } else if (invalidation.action === 're-derive') {
+                finalDoc = freshDoc;
+                action = 're-derived';
+            } else {
+                const merge = mergeOverride(existing, freshDoc);
+                finalDoc = merge.doc;
+                rejectedOverrides = merge.rejectedOverrides;
+                action = rejectedOverrides.length > 0 || JSON.stringify(merge.doc.policy) !== JSON.stringify(existing.policy)
+                    ? 'merged'
+                    : 'unchanged';
+            }
+        }
+    }
+
+    if (action !== 'kept-manual') {
+        const schema = load_schema('license-policy');
+        const errors = validate(finalDoc as unknown as YamlValue, schema);
+        if (errors.length > 0) {
+            process.stderr.write('detect_target_license: refused — derived policy fails schema validation:\n');
+            for (const e of errors) process.stderr.write(`  - ${e.format()}\n`);
+            return 1;
+        }
+    }
+
+    const willWrite = args.write && action !== 'kept-manual';
+    if (willWrite) {
+        fs.writeFileSync(policyPath, serializeLicensePolicy(finalDoc), 'utf8');
+    }
+
+    if (args.json) {
+        process.stdout.write(JSON.stringify({
+            escalate: false,
+            action,
+            wrote: willWrite,
+            policy_path: policyPath,
+            doc: finalDoc,
+            rejected_overrides: rejectedOverrides,
+        }) + '\n');
+    } else {
+        process.stdout.write(
+            `detect_target_license: detected ${detection.spdxId ?? '(none)'} -> ` +
+            `target_class=${detection.targetClass} workspace_scope=${detection.workspaceScope}\n`,
+        );
+        for (const w of detection.warnings) process.stdout.write(`  warning: ${w}\n`);
+        for (const r of rejectedOverrides) process.stdout.write(`  rejected override: ${r}\n`);
+        process.stdout.write(
+            willWrite
+                ? `wrote ${policyPath} (${action})\n`
+                : `(dry run — pass --write to update ${policyPath}; action would be: ${action})\n`,
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === invokedUrl) process.exit(main());
+}