@event4u/agent-config 14.13.0 → 14.14.1

package/src/scripts/_cli/_doctor_strict.ts

@@ -0,0 +1,163 @@
+/**
+ * `doctor --strict` — the failing exit mode, its threshold, and its kill switch.
+ *
+ * A separate module rather than more lines in `cmd_doctor.ts`, which is already
+ * far past the source-size budget: every line added there is counted excess by
+ * `check_source_size_budget`, and a ratchet that only turns one way is a
+ * standing instruction to put new code somewhere else.
+ */
+/** Structural, so this module needs no import from its caller. */
+type Dict = Record<string, unknown>;
+interface StrictOptions {
+    strict: boolean;
+    strict_level: string;
+}
+
+function eprint(msg: string): void {
+    process.stderr.write(`${msg}\n`);
+}
+
+/** Raised on an unknown `--strict-level`; the caller maps it to its argparse exit. */
+export class StrictLevelError extends Error {}
+
+/**
+ * `--strict` — the failing exit mode, and the ONE decision behind it.
+ *
+ * `doctor-exit-contract` was resolved by AI council on 2026-09-03 (members
+ * anthropic, openai), unanimously **(b)**: `doctor` keeps its exit contract and
+ * a separate strict mode carries the failing exit, leaving current callers
+ * untouched at the cost of one more surface. ADR-041 governs verb growth, so a
+ * flag rather than a verb; and the existing contract is load-bearing for callers
+ * that run `doctor` for information rather than for permission.
+ *
+ * WHAT WAS ALREADY TRUE, measured rather than assumed. The originating roadmap
+ * says `doctor` "writes nothing and always exits zero". Half of that is wrong:
+ * the default run already returns 1 on DRIFT (`return drift_present ? 1 : 0`),
+ * and `--ci` already folds check failures in on top. What is genuinely missing
+ * is a failing exit for check failures OUTSIDE the `--ci` JSON contract — `--ci`
+ * forces `opts.json = true`, so there is no human-readable strict run — and that
+ * gap is what `--strict` closes. Recorded here because a comment claiming to
+ * implement a premise the code contradicts is worse than no comment.
+ *
+ * SEVERITY IS CONFIGURABLE, per a condition both council seats attached:
+ * `--strict-level fail` (default) fails on `fail` rows; `--strict-level warn`
+ * also fails on `warn`. A caller adopting strict picks its own bar rather than
+ * inheriting one.
+ *
+ * THE KILL SWITCH is `AGENT_CONFIG_DOCTOR_NO_FAIL=1`, the other condition both
+ * seats attached: an immediate way to disable failing exits that is not a code
+ * rollback. When set, `--strict` still REPORTS every finding and still emits
+ * `can_proceed: false`; only the exit code is suppressed, and the suppression is
+ * announced on stderr so a green run cannot be silently bought. A switch that
+ * hid the finding as well would be the "warning ignored eighteen times" shape
+ * this repository already documents.
+ */
+export const STRICT_DEFAULT_LEVEL = 'fail';
+export const STRICT_LEVELS: ReadonlySet<string> = new Set(['fail', 'warn']);
+/** Env var that suppresses the failing exit without suppressing the finding. */
+export const STRICT_KILL_SWITCH = 'AGENT_CONFIG_DOCTOR_NO_FAIL';
+
+/** Statuses that trip `--strict` at the given level. */
+export function strictTripping(level: string): ReadonlySet<string> {
+    return level === 'warn' ? new Set(['fail', 'warn']) : new Set(['fail']);
+}
+
+/**
+ * The machine-readable "may I proceed" answer — nothing in this tree carried
+ * one before (`grep -rc can_proceed src` returned zero hits tree-wide).
+ *
+ * Deliberately independent of `--strict`: a caller asking the JSON whether it
+ * may proceed gets the same answer whether or not the exit code was configured
+ * to fail, because the two questions are different. The exit code is a policy;
+ * `can_proceed` is a fact.
+ */
+export function canProceed(driftPresent: boolean, checks: readonly Dict[]): boolean {
+    return !driftPresent && !checks.some((c) => c['status'] === 'fail');
+}
+
+export function validateStrictLevel(level: string): void {
+    if (!STRICT_LEVELS.has(level)) {
+        throw new StrictLevelError(
+            `argument --strict-level: invalid choice: '${level}' (choose from 'fail', 'warn')`,
+        );
+    }
+}
+
+/**
+ * The `--strict` verdict, or `null` when strict is off.
+ *
+ * Factored out because `main` has TWO exit paths and only one of them was
+ * obvious: a project with no install manifest returns through
+ * `_run_no_manifest` long before the drift branch, so a strict check written
+ * only in the drift branch silently never fires there. Measured, not guessed —
+ * the first implementation exited 0 on a tree carrying a `fail` check row and a
+ * `can_proceed: false` payload, because this repository has no manifest of its
+ * own. Both paths call this now, so the two cannot diverge again.
+ */
+export function strictExit(
+    opts: StrictOptions,
+    checks: readonly Dict[],
+    driftPresent: boolean,
+): number | null {
+    if (!opts.strict) {
+        return null;
+    }
+    const tripping = strictTripping(opts.strict_level);
+    const tripped = checks.filter((c) => tripping.has(c['status'] as string));
+    if (!driftPresent && tripped.length === 0) {
+        return 0;
+    }
+    if (process.env[STRICT_KILL_SWITCH] === '1') {
+        // The finding is NEVER suppressed — only the exit code is, and the
+        // suppression announces itself. A switch that hid the finding as well
+        // would be the ignored-warning shape this repository already documents.
+        eprint(
+            `⚠️  doctor --strict: ${String(tripped.length)} finding(s) at or above ` +
+                `'${opts.strict_level}'` +
+                (driftPresent ? ' plus manifest drift' : '') +
+                `, but ${STRICT_KILL_SWITCH}=1 suppressed the failing exit. ` +
+                'The findings above still stand; unset it to restore the gate.',
+        );
+        return 0;
+    }
+    return 1;
+}
+
+/**
+ * The `can_proceed` / `status` pair, written onto a `--json` payload.
+ *
+ * Lives here rather than inline in `_emit_json` for the source-budget reason
+ * this whole module exists for. `status` is the roll-up a human reads;
+ * `can_proceed` is the boolean a caller branches on without parsing prose. Both
+ * are facts about the tree and never about the exit policy — a caller running
+ * with the kill switch set still gets `can_proceed: false`.
+ */
+export function attachProceedFields(
+    payload: Dict,
+    driftPresent: boolean,
+    checks: readonly Dict[],
+): void {
+    const proceed = canProceed(driftPresent, checks);
+    payload['can_proceed'] = proceed;
+    payload['status'] = proceed
+        ? checks.some((c) => c['status'] === 'warn')
+            ? 'warn'
+            : 'ok'
+        : 'fail';
+}
+
+/** Argv wiring, exported as fragments so the caller spends one line each. */
+export const STRICT_STORE_TRUE = { '--strict': 'strict' } as const;
+export const STRICT_VALUE_FLAGS = { '--strict-level': 'strict_level' } as const;
+export const STRICT_DEFAULTS = { strict: false, strict_level: STRICT_DEFAULT_LEVEL } as const;
+export const STRICT_USAGE = '                           [--strict] [--strict-level {fail,warn}]\n';
+
+/** Validate, mapping the module's error onto the caller's argparse exit. */
+export function validateStrictLevelOr(level: string, onError: (msg: string) => never): void {
+    try {
+        validateStrictLevel(level);
+    } catch (e) {
+        if (e instanceof StrictLevelError) onError(e.message);
+        throw e;
+    }
+}

package/src/scripts/_cli/cmd_doctor.ts

@@ -3049,6 +3049,8 @@ function _run_no_manifest(
         }
         return fail_check ? 1 : 0;
     }
+    const sx = strictExit(opts, checks, false); // no manifest: keep the 2, never soften to 1
+    if (sx !== null) return bridge_present ? sx : 2;
     if (opts.ci && bridge_present) {
         // Same fold as the manifest path: check failures are red under --ci.
         return fail_check ? 1 : 0;
@@ -3077,6 +3079,8 @@ function _emit_json(
     }
     if (checks !== null) {
         payload['checks'] = checks;
+        const drift = missing.length + modified.length + foreign.length + tag_drift.length;
+        attachProceedFields(payload, drift > 0, checks);
         // The detection section rides along whenever checks ran, so the agent /
         // GUI contract carries the full provider → transport → billing table
         // and not just the one-line check row.
@@ -3117,48 +3121,16 @@ function _emit_detection_text(project_root: string, checks: Dict[]): void {
     print('');
 }
 
-function _emit_text(
-    project_root: string,
-    missing: Dict[],
-    modified: Dict[],
-    foreign: Dict[],
-    tag_drift: Dict[],
-): void {
-    const total = missing.length + modified.length + foreign.length + tag_drift.length;
-    if (total === 0) {
-        print(`✅  doctor: manifest matches filesystem under ${project_root}`);
-        return;
-    }
-    print(`⚠️   doctor: ${total} drift item(s) under ${project_root}`);
-    const groups: ReadonlyArray<[string, Dict[]]> = [
-        ['missing', missing],
-        ['modified', modified],
-        ['foreign', foreign],
-        ['tag-drift', tag_drift],
-    ];
-    for (const [label, items] of groups) {
-        if (items.length === 0) {
-            continue;
-        }
-        print(`\n  ${label} (${items.length}):`);
-        for (const it of items) {
-            const tool = (it['tool'] as string) || '?';
-            print(`    · [${tool}] ${it['path']}`);
-            if (label === 'tag-drift') {
-                const found = (it['found'] as string) || '(missing)';
-                const expected = 'expected' in it ? it['expected'] : PACKAGE_TAG_ID;
-                print(`        expected: ${expected}`);
-                print(`        found:    ${found}`);
-            }
-            print(`        fix: ${it['fix']}`);
-        }
-    }
-}
+
+// `--strict` lives in `_doctor_strict.ts`; the drift renderer in `_doctor_emit.ts`.
+import { STRICT_DEFAULTS, STRICT_STORE_TRUE, STRICT_USAGE, STRICT_VALUE_FLAGS, attachProceedFields, strictExit, validateStrictLevelOr } from './_doctor_strict.js';
+import { _emit_text } from './_doctor_emit.js';
 
 interface Options {
     project: string | null;
     json: boolean;
     ci: boolean;
+    strict: boolean; strict_level: string; // see `_doctor_strict.ts`
     check: string | null;
     trace_root: boolean;
     context: boolean;
@@ -3173,18 +3145,21 @@ const PROG = 'agent-config doctor';
 // terminal width; golden tests assert the `usage:` token + exit code only.
 const USAGE =
     `usage: ${PROG} [-h] [--project PROJECT] [--json] [--ci] [--check ID]\n` +
+    STRICT_USAGE +
     '                           [--trace-root] [--context] [--anatomy]\n' +
     '                           [--repair ID]\n';
 
 const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--json': 'json',
     '--ci': 'ci',
+    ...STRICT_STORE_TRUE,
     '--trace-root': 'trace_root',
     '--context': 'context',
     '--anatomy': 'anatomy',
 };
 
 const _VALUE_FLAGS: Record<string, keyof Options> = {
+    ...STRICT_VALUE_FLAGS,
     '--project': 'project',
     '--check': 'check',
     '--repair': 'repair',
@@ -3201,6 +3176,7 @@ function _parse(argv: string[]): Options {
         project: null,
         json: false,
         ci: false,
+        ...STRICT_DEFAULTS,
         check: null,
         trace_root: false,
         context: false,
@@ -3430,6 +3406,7 @@ function _run_repair(opts: Options): number {
 
 function main(argv: string[] | null = null): number {
     const opts = _parse(argv !== null ? Array.from(argv) : process.argv.slice(2));
+    validateStrictLevelOr(opts.strict_level, _argError);
     if (opts.ci) {
         // `--ci` = machine-readable consumer-CI contract: JSON payload on
         // stdout, zero interactive output, and check failures fold into the
@@ -3502,6 +3479,8 @@ function main(argv: string[] | null = null): number {
         // · 2 unresolvable environment (handled above via ProjectRootError).
         return drift_present || fail_check ? 1 : 0;
     }
+    const strict = strictExit(opts, checks, drift_present);
+    if (strict !== null) return strict;
     return drift_present ? 1 : 0;
 }
 

package/src/scripts/_dispatch.bash

@@ -290,6 +290,12 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              last dispatcher feedback per concern, missing trampolines.
                              Wraps hooks:status. Read-only.
                              Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:effect               Does a bound concern actually FIRE on this host? Dispatches
+                             each eligible concern against a scratch root and reports the
+                             observed state. Not hooks:doctor: that reads the manifest,
+                             this reads what happened. Read-only.
+                             Flags: --host <name>, --format text|json, --root <path>,
+                             --limit <n>, --help (prints both verdict vocabularies)
   routing:doctor             Live routing diagnosis: per-gate ACTIVE/INACTIVE with the
                              concern's own reason (read-only probes), session_start chain,
                              router + projection freshness, host bridge status.
@@ -764,10 +770,6 @@ cmd_roadmap_progress() {
 # The parked estate's front door — read-only, and deliberately so. It authors
 # nothing under `agents/roadmaps/stubs/`, which is what keeps it clear of the
 # 2026-08-21 council verdict that deleted the hand-maintained index there.
-cmd_stubs_due() {
-  exec_ts "$PACKAGE_ROOT/src/scripts/stubs_due.ts" "$@"
-}
-
 cmd_roadmap_progress_check() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
@@ -980,6 +982,10 @@ cmd_hooks_doctor() {
   exec_hook "src/scripts/hooks_doctor" "$@"
 }
 
+cmd_hooks_effect() {
+  exec_hook "src/scripts/hook_effect_doctor" "$@"
+}
+
 cmd_routing_doctor() {
   exec_hook "src/scripts/routing_doctor" "$@"
 }
@@ -1537,6 +1543,7 @@ main() {
     dispatch:hook)           cmd_dispatch_hook "$@" ;;
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
+    hooks:effect)            cmd_hooks_effect "$@" ;;
     routing:doctor)          cmd_routing_doctor "$@" ;;
     workspace:doctor)        cmd_workspace_doctor "$@" ;;
     route:explain)           cmd_route_explain "$@" ;;

package/src/scripts/_lib/activation_ladder.ts

@@ -43,6 +43,26 @@ export const LADDER_RUNGS = [
 ] as const;
 export type LadderRung = (typeof LADDER_RUNGS)[number];
 
+/**
+ * The receipt-bearing cascade stage that reads each rung, in ladder order.
+ *
+ * Derived from {@link LADDER_RUNGS} rather than written out, so a rung cannot
+ * exist without its stage and the two orders cannot drift. Named here rather
+ * than in the cascade because the RUNGS are this module's, and a second module
+ * spelling `receipt-<rung>` would be a second source of truth for the same
+ * enum.
+ *
+ * The cascade consumes these; nothing here imports the cascade. That direction
+ * is the one `docs/contracts/activation-receipt-trust-boundary.md` TB-1 fixes.
+ */
+export const RECEIPT_STAGES = LADDER_RUNGS.map((r) => `receipt-${r}` as const);
+export type ReceiptStage = (typeof RECEIPT_STAGES)[number];
+
+/** The rung a receipt-bearing stage reads. Total over {@link ReceiptStage}. */
+export function rungForReceiptStage(stage: ReceiptStage): LadderRung {
+    return stage.slice('receipt-'.length) as LadderRung;
+}
+
 /**
  * Which failure family a stall at each rung belongs to.
  *
@@ -171,10 +191,34 @@ export function rungState(receipt: ActivationReceipt, rung: LadderRung): RungSta
  * and the caller gets `null`.
  */
 export function classifyFailure(receipt: ActivationReceipt): FailureFamily | null {
-    for (const spec of LADDER) {
+    return firstStall(receipt)?.family ?? null;
+}
+
+/** Where a receipt stopped climbing, and the family that stall belongs to. */
+export interface LadderStall {
+    /** The rung the walk stopped at. */
+    readonly rung: LadderRung;
+    /** The receipt-bearing cascade stage that reads {@link rung}. */
+    readonly stage: ReceiptStage;
+    /** `unknown` when the rung was never observed; the rung's family otherwise. */
+    readonly family: FailureFamily;
+}
+
+/**
+ * The first rung a receipt did not reach, with its stage and its family.
+ *
+ * {@link classifyFailure} is a projection of this, and delegates to it rather
+ * than walking the ladder a second time. Two walks of the same ladder applying
+ * the same short-circuit rule is two places to change it — and the cascade needs
+ * the STAGE as well as the family, which is the only reason this exists
+ * separately at all.
+ */
+export function firstStall(receipt: ActivationReceipt): LadderStall | null {
+    for (const [i, spec] of LADDER.entries()) {
         const state = rungState(receipt, spec.rung);
-        if (state === 'unknown') return 'unknown';
-        if (state === 'not-reached') return spec.family;
+        const stage = RECEIPT_STAGES[i] as ReceiptStage;
+        if (state === 'unknown') return { rung: spec.rung, stage, family: 'unknown' };
+        if (state === 'not-reached') return { rung: spec.rung, stage, family: spec.family };
     }
     return null;
 }