@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/_lib/typed_op_watch.ts

@@ -0,0 +1,185 @@
+/**
+ * The guardrail watch over typed ops — `road-to-adversarial-verification-and-long-runs`
+ * 7.1, observation-only floor.
+ *
+ * The eleven typed ops are the Hard Floor's own list: the irreversible and
+ * externally-visible actions `non-destructive-by-default` gates. The layering is
+ * forge protection → the host hook where one is bound → this watch → model
+ * policy, and the watch exists because 7.2 measured the second layer and found
+ * SEVEN of eight hosts carry no refusing `pre_tool_use` binding at all.
+ *
+ * **This mode observes and takes no action. That is a design decision with a
+ * measured precondition, not caution.** K5 of the roadmap kills daemon
+ * enforcement before the observation floor, and the roadmap's own Risk 3 states
+ * the reason: a watchdog reading the reflog and shell history for typed ops can
+ * misclassify, and its enforcing action is stopping the host process — one false
+ * stop costs a twelve-hour run. So enforcement waits behind a measured
+ * false-positive rate under 1 % on the 30-session corpus, and
+ * {@link enforcementAllowed} refuses to unlock without that artefact.
+ *
+ * **What it can and cannot see, said plainly.** It reads lines — reflog entries,
+ * exposed shell history, forge event payloads. A line is not an intention: an op
+ * typed into a comment, a heredoc, or a string literal looks identical to one
+ * about to run. That is precisely why the first mode only writes down what it
+ * saw, and why the false-positive rate is the gate on doing anything more.
+ *
+ * Pure. The I/O — tailing a reflog, reading history, polling an event stream —
+ * belongs to the caller, so every classification is testable offline.
+ */
+
+/** The typed-op classes this watch recognises. */
+export const TYPED_OPS = [
+    'push',
+    'force-push',
+    'merge-to-trunk',
+    'tag-or-release',
+    'deploy',
+    'bulk-delete',
+    'history-rewrite',
+    'send',
+    'publish',
+    'purchase',
+    'submit',
+] as const;
+export type TypedOp = (typeof TYPED_OPS)[number];
+
+/** Where a line came from. Kept because the sources have different reliability. */
+export type WatchSource = 'reflog' | 'shell-history' | 'forge-event';
+
+export interface Observation {
+    readonly op: TypedOp;
+    readonly source: WatchSource;
+    /** The line, truncated. Evidence, never re-executed. */
+    readonly evidence: string;
+}
+
+/**
+ * The recognisers, most specific first.
+ *
+ * ORDER MATTERS and is asserted by a test: `git push --force` is a force-push,
+ * not a push, and a table walked in declaration order gives the specific class
+ * only if it is declared before the general one. A misordered table would report
+ * the milder op for the more dangerous line, which is the wrong direction for
+ * every downstream reader.
+ */
+const RECOGNISERS: readonly (readonly [TypedOp, RegExp])[] = [
+    ['force-push', /\bgit\b[^\n]*\bpush\b[^\n]*(--force\b|--force-with-lease\b|\s-f\b)/],
+    ['history-rewrite', /\bgit\b[^\n]*\b(rebase|filter-repo|filter-branch)\b|\bgit\b[^\n]*reset\s+--hard\b/],
+    ['merge-to-trunk', /\bgit\b[^\n]*\bmerge\b[^\n]*\b(main|master|trunk|production)\b|\bgh\b[^\n]*\bpr\b[^\n]*\bmerge\b/],
+    ['tag-or-release', /\bgit\b[^\n]*\bpush\b[^\n]*\b--tags?\b|\bgh\b[^\n]*\brelease\b[^\n]*\bcreate\b/],
+    ['deploy', /\b(terraform\s+apply|kubectl\s+apply|helm\s+(install|upgrade)|serverless\s+deploy)\b/],
+    ['bulk-delete', /\brm\s+-[a-z]*r[a-z]*f\b|\bgit\b[^\n]*\brm\s+-r\b|\b(DROP\s+TABLE|TRUNCATE)\b/i],
+    ['push', /\bgit\b[^\n]*\bpush\b/],
+    ['purchase', /\b(stripe|checkout|charge|payment)\b[^\n]*\b(create|confirm|capture)\b/i],
+    ['publish', /\bnpm\s+publish\b|\bgh\b[^\n]*\brelease\b[^\n]*\bupload\b/],
+    ['send', /\b(sendmail|mail\s+-s|curl\b[^\n]*\/messages\b)/],
+    ['submit', /\bcurl\b[^\n]*\s-X\s*POST\b[^\n]*\b(submit|apply|order)\b/i],
+];
+
+const EVIDENCE_MAX = 200;
+
+/**
+ * Classify one line, or `null` when nothing matched.
+ *
+ * Deliberately returns at most ONE op. A line is one action, and reporting two
+ * classes for it would double-count in the false-positive denominator the
+ * enforcement gate depends on.
+ */
+export function classifyLine(line: string, source: WatchSource): Observation | null {
+    for (const [op, re] of RECOGNISERS) {
+        if (re.test(line)) {
+            return { op, source, evidence: line.trim().slice(0, EVIDENCE_MAX) };
+        }
+    }
+    return null;
+}
+
+/** Classify a batch, preserving order and dropping non-matches. */
+export function observe(
+    lines: readonly string[],
+    source: WatchSource,
+): Observation[] {
+    return lines
+        .map((l) => classifyLine(l, source))
+        .filter((o): o is Observation => o !== null);
+}
+
+/** The two modes. There is no third, and `enforce` is gated. */
+export type WatchMode = 'observe' | 'enforce';
+
+/** The false-positive measurement the enforcing mode waits behind. */
+export interface FalsePositiveMeasurement {
+    /** Sessions the corpus covered. The roadmap names 30. */
+    readonly sessions: number;
+    readonly observations: number;
+    readonly falsePositives: number;
+    /** Where the artefact lives, so the claim is checkable. */
+    readonly artefact: string;
+}
+
+/** The corpus size the roadmap fixed before any measurement was taken. */
+export const REQUIRED_SESSIONS = 30;
+/** The rate enforcement waits behind. */
+export const MAX_FALSE_POSITIVE_RATE = 0.01;
+
+export interface EnforcementVerdict {
+    readonly allowed: boolean;
+    readonly reason: string;
+}
+
+/**
+ * May the enforcing mode be enabled?
+ *
+ * `null` — no measurement at all — is a refusal with its own reason, never a
+ * pass. A gate that unlocks when it cannot measure is the shape this whole
+ * roadmap is written against, and it is the one an absent-artefact check gets
+ * wrong by default.
+ */
+export function enforcementAllowed(
+    m: FalsePositiveMeasurement | null,
+): EnforcementVerdict {
+    if (m === null) {
+        return {
+            allowed: false,
+            reason:
+                'no false-positive measurement exists. Enforcement stops the host process; a ' +
+                'rate nobody measured is not a control (K5).',
+        };
+    }
+    if (m.sessions < REQUIRED_SESSIONS) {
+        return {
+            allowed: false,
+            reason: `measured over ${String(m.sessions)} session(s), below the ${String(REQUIRED_SESSIONS)} the corpus was fixed at`,
+        };
+    }
+    if (m.observations === 0) {
+        return {
+            allowed: false,
+            reason:
+                'zero observations: a rate over an empty denominator is not a measurement, ' +
+                'and it is the reading a broken recogniser produces',
+        };
+    }
+    const rate = m.falsePositives / m.observations;
+    if (rate >= MAX_FALSE_POSITIVE_RATE) {
+        return {
+            allowed: false,
+            reason: `false-positive rate ${rate.toFixed(4)} is not below ${String(MAX_FALSE_POSITIVE_RATE)}`,
+        };
+    }
+    return { allowed: true, reason: `rate ${rate.toFixed(4)} over ${String(m.observations)} observations in ${m.artefact}` };
+}
+
+/**
+ * What the watch does with an observation, per mode.
+ *
+ * In `observe` the action is always `record` — there is no branch that acts, so
+ * no configuration flips this mode into one that does.
+ */
+export function actionFor(
+    mode: WatchMode,
+    measurement: FalsePositiveMeasurement | null,
+): 'record' | 'record-and-ask' {
+    if (mode === 'observe') return 'record';
+    return enforcementAllowed(measurement).allowed ? 'record-and-ask' : 'record';
+}

package/src/scripts/ai_council/config.ts

@@ -543,6 +543,7 @@ export type QuorumMinPresent = number;
 
 export type { FallbackConfig } from './fallback_config.js';
 import { buildFallback, buildSecondModel, type FallbackConfig as _FallbackConfig } from './fallback_config.js';
+import { OWNERSHIP_CLASSES, allOwnerLocked, defaultModeFor, ownershipModeError } from './ownership_classes.js';
 import {
     _f,
     _pyOct,
@@ -1182,13 +1183,7 @@ const _LOCKED_IMPACT_CLASSES: ReadonlySet<string> = new Set([
     'user_required',
 ]);
 
-const _DEFAULT_RESOLUTION_MODES: Readonly<Record<string, string>> = {
-    trivial: 'agent',
-    low_impact: 'agent',
-    medium_impact: 'council',
-    high_impact: 'user',
-    user_required: 'user',
-};
+const _ALL_OWNER_LOCKED = allOwnerLocked(_LOCKED_IMPACT_CLASSES);
 
 function _build_decision_resolution(d: Dict): DecisionResolutionConfig {
     if (!_isDict(d)) {
@@ -1207,14 +1202,14 @@ function _build_decision_resolution(d: Dict): DecisionResolutionConfig {
         );
     }
     const classes = new Map<string, DecisionResolutionEntry>();
-    for (const cls of _IMPACT_CLASSES) {
+    for (const cls of [..._IMPACT_CLASSES, ...OWNERSHIP_CLASSES]) {
         const entry_raw = _orEmpty(classes_raw[cls] ?? null);
         if (!_isDict(entry_raw)) {
             throw new CouncilConfigError(
                 `\`decision_resolution.classes.${cls}\` must be a mapping.`,
             );
         }
-        const mode = _get(entry_raw, 'mode', _DEFAULT_RESOLUTION_MODES[cls] as string);
+        const mode = _get(entry_raw, 'mode', defaultModeFor(cls));
         if (!(_isStr(mode) && _VALID_RESOLUTION_MODES.has(mode))) {
             throw new CouncilConfigError(
                 `decision_resolution.classes.${cls}.mode=${_pyRepr(mode)} not in ` +
@@ -1230,10 +1225,12 @@ function _build_decision_resolution(d: Dict): DecisionResolutionConfig {
                     `the user.`,
             );
         }
+        const ownErr = ownershipModeError(cls, mode, _pyRepr);
+        if (ownErr !== null) throw new CouncilConfigError(ownErr);
         // Iron Law: `dispatch` is not configurable for locked classes
         // (step-9 P8/P11 · U3). Any nested `dispatch` key — including
         // smuggled-in YAML anchor merges — is a hard schema error.
-        if (_LOCKED_IMPACT_CLASSES.has(cls) && 'dispatch' in entry_raw) {
+        if (_ALL_OWNER_LOCKED.has(cls) && 'dispatch' in entry_raw) {
             throw new CouncilConfigError(
                 `decision_resolution.classes.${cls}.dispatch=` +
                     `${_pyRepr(entry_raw.dispatch)}: dispatch is not ` +
@@ -1251,7 +1248,7 @@ function _build_decision_resolution(d: Dict): DecisionResolutionConfig {
         // UOTL Phase 4.1 — the optional local rung, REFUSED on a locked
         // class rather than ignored: a dropped key reads as configured.
             const second_model = buildSecondModel(
-            entry_raw as Record<string, unknown>, cls, _LOCKED_IMPACT_CLASSES, _FALLBACK_DEPS);
+            entry_raw as Record<string, unknown>, cls, _ALL_OWNER_LOCKED, _FALLBACK_DEPS);
         classes.set(cls, { mode, confidence_threshold: threshold, second_model });
     }
     const fast_path_raw = _getOr(d, 'fast_path', {});

package/src/scripts/ai_council/fallback_config.ts

@@ -107,9 +107,11 @@ export function buildSecondModel(
     if (locked.has(cls)) {
         throw d.error(
             `decision_resolution.classes.${cls}.second_model=${d.repr(entry['second_model'])}: ` +
-                `a second-model rung is not configurable for high-impact / user-required ` +
-                `decisions — those classes are LOCKED to \`user\` (Iron Law) and never resolve ` +
-                `on a model of any kind.`,
+                `a second-model rung is not configurable for an owner-routed class ` +
+                `(high-impact / user-required on the impact axis; product-owned / ` +
+                `business-owned / destructive-owned on the ownership axis) — those ` +
+                `classes are LOCKED to \`user\` (Iron Law) and never resolve on a ` +
+                `model of any kind.`,
         );
     }
     const raw = entry['second_model'];

package/src/scripts/ai_council/ownership_classes.ts

@@ -0,0 +1,118 @@
+/**
+ * The ownership axis of `decision_resolution` (ADR-268 § 10).
+ *
+ * A separate module rather than more constants in `config.ts`, for two
+ * reasons. That file is 700+ lines over the source ceiling already, so every
+ * line added there moves a ratchet; and these sets are read by the loader AND
+ * by the roadmap-side gate, which has no business importing the council's
+ * whole schema to learn eight class names.
+ *
+ * The axis changes from IMPACT to OWNERSHIP: a technical decision does not
+ * become owner-owned because it is hard or high-impact. The five impact names
+ * stay accepted for one minor so no installed `.ai-council.yml` fails to load,
+ * and they keep their own (impact-axis) Iron Law — they are deliberately NOT
+ * in this module.
+ */
+
+/** The eight ownership classes, in table order. */
+export const OWNERSHIP_CLASSES: readonly string[] = [
+    'deterministic',
+    'reversible-technical',
+    'contested-technical',
+    'critical-technical',
+    'product-owned',
+    'business-owned',
+    'destructive-owned',
+    'spend-exhaustion',
+];
+
+/**
+ * Iron Law: ONLY these three are locked to `user`. `critical-technical` is
+ * deliberately absent — locking it is the § 0 break ADR-268 names by hand
+ * ("routing a technical decision to the owner because it is hard or
+ * high-impact"), so the absence is load-bearing rather than an oversight.
+ */
+export const OWNER_LOCKED_CLASSES: ReadonlySet<string> = new Set([
+    'product-owned',
+    'business-owned',
+    'destructive-owned',
+]);
+
+/**
+ * Iron Law: `spend-exhaustion` PAUSES AND REPORTS (ADR-268 § 8). It is never
+ * routed to the owner as a question, so `mode: user` on it is a hard schema
+ * error rather than an unusual-but-legal setting.
+ */
+export const NEVER_OWNER_CLASSES: ReadonlySet<string> = new Set(['spend-exhaustion']);
+
+/**
+ * Both owner-routed sets as one, given the impact axis's own locked set.
+ *
+ * A function rather than a constant because the impact half lives in the
+ * loader: importing it here would make this module depend on the schema it is
+ * imported BY, which is the cycle the split exists to avoid.
+ */
+export function allOwnerLocked(impactLocked: ReadonlySet<string>): ReadonlySet<string> {
+    return new Set<string>([...impactLocked, ...OWNER_LOCKED_CLASSES]);
+}
+
+/**
+ * Default `mode` per class, BOTH axes — the resolver column of each table.
+ *
+ * The five impact rows moved here with the eight ownership ones so there is
+ * exactly one place a reader asks "what does this class do when nobody
+ * configured it", rather than one map per axis drifting against the other.
+ */
+export const DEFAULT_RESOLUTION_MODES: Readonly<Record<string, string>> = {
+    trivial: 'agent',
+    low_impact: 'agent',
+    medium_impact: 'council',
+    high_impact: 'user',
+    user_required: 'user',
+    deterministic: 'agent',
+    'reversible-technical': 'agent',
+    'contested-technical': 'council',
+    'critical-technical': 'council',
+    'product-owned': 'user',
+    'business-owned': 'user',
+    'destructive-owned': 'user',
+    'spend-exhaustion': 'agent',
+};
+
+/** The default `mode` for a class, or `agent` for a name neither axis knows. */
+export function defaultModeFor(cls: string): string {
+    return DEFAULT_RESOLUTION_MODES[cls] ?? 'agent';
+}
+
+/**
+ * The ownership axis's mode check, as one function.
+ *
+ * Both Iron Laws live here rather than at the call site so the loader carries
+ * three lines instead of twenty-four — and so a reader looking for "which
+ * classes are locked" finds the rule next to the sets it reads.
+ *
+ * Returns the error message, or `null` when the mode is legal. `repr` is the
+ * caller's own value formatter, so the message reads identically to every
+ * other schema error in the loader.
+ */
+export function ownershipModeError(
+    cls: string,
+    mode: string,
+    repr: (v: unknown) => string,
+): string | null {
+    if (OWNER_LOCKED_CLASSES.has(cls) && mode !== 'user') {
+        return (
+            `decision_resolution.classes.${cls}.mode=${repr(mode)}: ` +
+            `class \`${cls}\` is LOCKED to \`user\` (Iron Law) — product, business and ` +
+            `destructive decisions are owner-owned and never resolve on a model.`
+        );
+    }
+    if (NEVER_OWNER_CLASSES.has(cls) && mode === 'user') {
+        return (
+            `decision_resolution.classes.${cls}.mode=${repr(mode)}: ` +
+            `class \`${cls}\` is never owner-routed (Iron Law) — spend exhaustion ` +
+            `pauses and reports, it does not ask.`
+        );
+    }
+    return null;
+}