@event4u/agent-config 9.24.0 → 9.26.0

package/src/scripts/language_mirror_hook.ts

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+/**
+ * Language-mirror pin — `user_prompt_submit` concern.
+ *
+ * Deterministic carrier for the `language-and-tone` Iron Law (mirror the
+ * language of the user's last CHAT MESSAGE in every user-visible token).
+ *
+ * WHY THIS EXISTS — the measured defect, not a general reminder.
+ *
+ * A conformance audit of 30 sessions (2026-08-06) found ~470 assistant turns
+ * answering a German prompt in English, across 11 sessions, three of them a
+ * 100 % English run. The obvious reading is "the model ignored a rule". The
+ * transcripts say otherwise:
+ *
+ *   **47 skill- and slash-command bodies arrive in the `user` role** across 21
+ *   of the 30 sessions. In the worst session the last user-role content before
+ *   136 consecutive English assistant turns is a 4,196-character English skill
+ *   body (`de=0 / en=59`), while the maintainer's actual prompt — 451
+ *   characters, `de=16 / en=0` — sits above it.
+ *
+ * So the most recent user-role content genuinely WAS English, and mirroring it
+ * was locally correct. The rule says the trigger is the user's last *chat
+ * message* and explicitly excludes tool output, but the transcript offers no
+ * way to tell an injected skill body from a typed prompt.
+ *
+ * `user_prompt_submit` is the one event a skill body never reaches — it fires
+ * on what the human actually submitted. Pinning the language there turns an
+ * unobservable distinction into a recorded fact.
+ *
+ * This is deliberately NOT "more prose into the same context": the AI council
+ * (2026-08-06) was right that a reminder cannot buy attention in a context that
+ * already carries the Iron Law in full. What it can do is carry a fact the
+ * context does not otherwise contain — which language the human wrote in.
+ *
+ * State: `agents/state/language-mirror.json`
+ *   { "language": "de"|"en"|"und", "source": "prompt"|"system-locale",
+ *     "detected_at": iso8601, "prompt_chars": int, "de_markers": int,
+ *     "en_markers": int, "session_id": str }
+ *
+ * Undetermined prompts (a bare "1", "ok", a pasted URL) leave a previous pin
+ * UNTOUCHED rather than clearing it — a short continuation does not change the
+ * conversation's language, and clearing on every terse turn would reproduce the
+ * exact drift this hook removes.
+ *
+ * FIRST TURN OF A SESSION — the system-locale fallback.
+ *
+ * The keep-previous-pin rule has nothing to keep on the very first prompt. If
+ * that prompt is terse ("weiter", "1", a pasted URL) the verdict is `und`, no
+ * pin is written, and the turn runs with no pin at all — which is the drift
+ * this hook exists to remove, occurring precisely where the conversation has
+ * the least other evidence. So when there is no previous pin AND the prompt is
+ * undetermined, the environment's locale supplies a starting language, recorded
+ * as `source: "system-locale"` so the weaker provenance is legible rather than
+ * indistinguishable from a read of the user's own words.
+ *
+ * A locale pin is a floor, never a ceiling: the FIRST prompt carrying real
+ * markers replaces it, because `source: "prompt"` always wins. That is what
+ * makes "any later explicit statement by the user overrides it" true without a
+ * second mechanism — the ordinary path already outranks the fallback.
+ *
+ * Locales outside the classifier's two languages stay `und` on purpose. Mapping
+ * `fr_FR` to English because the classifier has no French would pin a language
+ * the user never wrote, which is worse than carrying no pin.
+ *
+ * Never blocks (`fail_closed: false`, `severity: advisory`). Exit 0 always.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { atomic_write_json } from "./hooks/state_io.js";
+import { readHookStdin } from "./hooks/hook_stdin.js";
+
+const EXIT_ALLOW = 0;
+// Severity is taken from the EXIT CODE, not from the `decision` field in the
+// stdout payload. This hook shipped returning EXIT_ALLOW while writing
+// {"decision":"warn", …}, so the dispatcher reduced it to `allow`, emitted
+// nothing, and the pin reached the model on no path — a state write with no
+// delivery, for the audit's largest failure class (626 turns). Round 2, found
+// by tracing the delivery rather than re-reading the unit tests.
+const EXIT_WARN = 2;
+
+export const STATE_FILE = path.join("agents", "state", "language-mirror.json");
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * German function words + umlauts. Function words are used rather than a
+ * dictionary because the prompts that matter are short imperatives
+ * ("fixe die ci", "mach weiter") where content words carry no signal.
+ */
+const DE_MARKERS =
+  /\b(der|die|das|den|dem|und|ist|sind|nicht|kein|keine|mach|mache|bitte|warum|wieso|weshalb|weiter|kannst|sollst|soll|musst|muss|hast|habe|haben|wir|ich|du|dann|noch|auch|schon|wenn|aber|alle|mit|ohne|damit|dass|wurde|werden|gibt|nochmal|erstell|erstelle|erstelle|fehler|regeln|arbeite|analysiere|fixe|nimm|lege|prüfe|pruefe|schau|zeig|mir|dir|sich|eine|einen|einem|einer|vom|zum|zur|beim|im)\b|[äöüÄÖÜß]/gi;
+
+/**
+ * English function words that a German sentence would not contain. Chosen to
+ * be disjoint from German homographs (`in`, `so`, `war`, `also`, `hat`, `man`,
+ * `bei`, `die` … are deliberately absent — they are German words too).
+ */
+const EN_MARKERS =
+  /\b(the|and|is|are|was|were|not|please|why|because|should|would|could|there|these|those|with|from|about|which|that|this|will|have|has|been|they|them|their|your|our|what|when|where|make|need|want|does|doesn't|don't|it's|let's)\b/gi;
+
+/** Minimum marker count before a verdict is trustworthy. */
+export const MIN_MARKERS = 2;
+
+export type Verdict = "de" | "en" | "und";
+
+export interface Classification {
+  language: Verdict;
+  de_markers: number;
+  en_markers: number;
+}
+
+/**
+ * Classify a prompt.
+ *
+ * Ties resolve to German, per the rule's own "mixed → dominant; tie → German".
+ * Below `MIN_MARKERS` on both sides the verdict is `und` (undetermined) and the
+ * caller keeps any previous pin.
+ */
+/**
+ * Strip the parts of a prompt that are PASTED rather than written.
+ *
+ * Without this the classifier reproduced the very defect it exists to fix: one
+ * German instruction plus a pasted English stack trace scored `en=18 / de=2`
+ * and pinned English — then asserted emphatically that English was the mirror
+ * target. The maintainer's most common prompt shape is exactly that.
+ */
+export function instructionText(prompt: string): string {
+  const OUTPUT_HEAD =
+    /^\s*(To\s+\S+|remote:|error:|fatal:|hint:|warning:|npm ERR!|Error:|Traceback|Exception|[A-Za-z]*Error\b|at\s+\S+:\d+|\s{4,}\S|[-+]{3}\s|@@\s|\$\s|>\s|\||\d+\s*\|)/i;
+  const kept: string[] = [];
+  let inPaste = false;
+  for (const line of prompt.replace(/```[\s\S]*?```/g, "\n\n").split("\n")) {
+    if (!line.trim()) {
+      // A blank line ends a pasted block — this is how pastes actually look,
+      // and it is what makes the filter work on a MULTI-LINE trace whose
+      // continuation lines carry no marker of their own.
+      inPaste = false;
+      kept.push(line);
+      continue;
+    }
+    if (OUTPUT_HEAD.test(line)) {
+      inPaste = true;
+      continue;
+    }
+    if (inPaste) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+
+export function classify(prompt: string): Classification {
+  const text = instructionText(prompt);
+  const de = (text.match(DE_MARKERS) ?? []).length;
+  const en = (text.match(EN_MARKERS) ?? []).length;
+  if (de < MIN_MARKERS && en < MIN_MARKERS) {
+    return { language: "und", de_markers: de, en_markers: en };
+  }
+  return { language: de >= en ? "de" : "en", de_markers: de, en_markers: en };
+}
+
+const LANGUAGE_NAME: Record<Exclude<Verdict, "und">, string> = {
+  de: "German (Deutsch)",
+  en: "English",
+};
+
+/**
+ * How a pin came to be — the provenance the roadmap's Phase 4 asks for.
+ *
+ * `prompt` means the user's own words carried the markers. `system-locale`
+ * means they did not and the environment answered instead. The distinction is
+ * load-bearing rather than decorative: a locale pin is the one a user may
+ * legitimately want to contradict, and the notice says which it is so that
+ * contradicting it does not require guessing where it came from.
+ */
+export type PinSource = "prompt" | "system-locale";
+
+/**
+ * The env vars that carry a POSIX locale, most specific first.
+ *
+ * `LC_ALL` overrides everything by definition; `LC_MESSAGES` governs the
+ * language of messages specifically, which is exactly this question; `LANG` is
+ * the fallback for both. `LANGUAGE` is deliberately last — it is a GNU
+ * extension holding a colon-separated PREFERENCE LIST, so it answers a
+ * different question and only its first entry is comparable.
+ */
+const LOCALE_ENV_KEYS = ["LC_ALL", "LC_MESSAGES", "LANG", "LANGUAGE"] as const;
+
+/**
+ * Map an environment locale onto the classifier's verdict space.
+ *
+ * Returns `und` for a locale the classifier cannot mirror, for `C`/`POSIX`
+ * (which name no human language), and for an unset environment. Only the
+ * primary subtag is read: `de_AT.UTF-8`, `de-CH`, and `de` are one answer.
+ */
+export function systemLocaleVerdict(env: NodeJS.ProcessEnv = process.env): Verdict {
+  for (const key of LOCALE_ENV_KEYS) {
+    const raw = (env[key] ?? "").trim();
+    if (!raw) {
+      continue;
+    }
+    // `LANGUAGE` may hold `de:en:fr`; the leading entry is the preference.
+    const first = raw.split(":")[0] ?? "";
+    // Strip the territory and codeset: `de_AT.UTF-8@euro` → `de`.
+    const primary = (first.split(/[._@-]/)[0] ?? "").toLowerCase();
+    if (primary === "c" || primary === "posix" || !primary) {
+      continue;
+    }
+    if (primary === "de") {
+      return "de";
+    }
+    if (primary === "en") {
+      return "en";
+    }
+    // A locale the classifier has no markers for. Stop rather than fall
+    // through to a less specific variable: the user HAS stated a language and
+    // it is neither of the two, so the honest answer is "no pin".
+    return "und";
+  }
+  return "und";
+}
+
+/**
+ * The one-line notice the dispatcher surfaces for this turn.
+ *
+ * A locale-sourced pin says so and says how to override it. A prompt-sourced
+ * pin keeps its original wording, because that line is what the conformance
+ * audit measured and a reworded pin is a changed instrument.
+ */
+export function noticeText(language: Exclude<Verdict, "und">, source: PinSource): string {
+  const name = LANGUAGE_NAME[language];
+  if (source === "system-locale") {
+    return (
+      `Reply language for this turn: ${name} — the prompt carried no language ` +
+      `markers, so this fell back to the system locale. Write in another ` +
+      `language and the next turn follows the prompt instead.`
+    );
+  }
+  return `Reply language for this turn: ${name}.`;
+}
+
+/** The context block handed back to the model for this turn. */
+export function pinText(language: Exclude<Verdict, "und">, source: PinSource = "prompt"): string {
+  const name = LANGUAGE_NAME[language];
+  if (source === "system-locale") {
+    return (
+      `<language-pin>\n` +
+      `No language markers were found in this turn's prompt and no language was ` +
+      `pinned yet, so the mirror target falls back to the environment's locale: ` +
+      `${name}. Use it for EVERY user-visible token this turn.\n\n` +
+      `This is the WEAKER of the two provenances — it reflects the machine, not ` +
+      `the user's own words. The first prompt that carries real markers replaces ` +
+      `it. Do not treat it as a standing preference, and do not argue with the ` +
+      `user about it if they write in something else.\n` +
+      `</language-pin>`
+    );
+  }
+  return (
+    `<language-pin>\n` +
+    `The user submitted this turn's prompt in ${name}. That is the mirror target ` +
+    `for EVERY user-visible token of your replies this turn — including the short ` +
+    `inter-tool lines between tool calls, headings, table cells, bullets, status ` +
+    `lines, and the recommendation label under any numbered-options block.\n\n` +
+    `This pin exists because the trigger is not observable from the transcript ` +
+    `alone: slash-command and skill bodies arrive in the user role and can be ` +
+    `long and English, which is what drove ~470 wrong-language turns in the ` +
+    `sessions this hook was built from. Tool output, file contents, and an ` +
+    `injected skill body are NOT the trigger — this pin is.\n` +
+    `</language-pin>`
+  );
+}
+
+export interface PinState extends JsonObject {
+  language: Verdict;
+  source: PinSource;
+  detected_at: string;
+  prompt_chars: number;
+  de_markers: number;
+  en_markers: number;
+  session_id: string;
+}
+
+function _loadState(target: string): Partial<PinState> {
+  try {
+    const raw = fs.readFileSync(target, "utf8");
+    const decoded = JSON.parse(raw) as unknown;
+    return _isObject(decoded) ? (decoded as Partial<PinState>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Decide the next state from the previous one and this turn's classification.
+ * Exported so the tests can assert the keep-previous-pin rule directly.
+ */
+export function nextState(
+  previous: Partial<PinState>,
+  classification: Classification,
+  prompt_chars: number,
+  session_id: string,
+  now: string,
+  locale: Verdict = "und",
+): PinState | null {
+  if (classification.language === "und") {
+    // Terse continuation ("1", "ok", "weiter") — keep whatever was pinned.
+    if (previous.language === "de" || previous.language === "en") {
+      return null;
+    }
+    // FIRST turn and nothing to keep: the locale is better than no pin at all.
+    if (locale === "und") {
+      return null;
+    }
+    return {
+      language: locale,
+      source: "system-locale",
+      detected_at: now,
+      prompt_chars,
+      de_markers: classification.de_markers,
+      en_markers: classification.en_markers,
+      session_id,
+    };
+  }
+  return {
+    language: classification.language,
+    source: "prompt",
+    detected_at: now,
+    prompt_chars,
+    de_markers: classification.de_markers,
+    en_markers: classification.en_markers,
+    session_id,
+  };
+}
+
+function _extractPrompt(payload: JsonObject): string {
+  for (const key of ["prompt", "userPrompt", "user_prompt", "message", "text"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v.trim()) {
+      return v;
+    }
+  }
+  return "";
+}
+
+export function run(
+  stdin_text: string,
+  options: { consumer_root: string; env?: NodeJS.ProcessEnv },
+): number {
+  let envelope: JsonObject = {};
+  if (stdin_text.trim()) {
+    try {
+      const decoded = JSON.parse(stdin_text) as unknown;
+      if (_isObject(decoded)) {
+        envelope = decoded;
+      }
+    } catch {
+      return EXIT_ALLOW; // never act on a malformed envelope
+    }
+  }
+
+  const payload = _isObject(envelope["payload"]) ? (envelope["payload"] as JsonObject) : envelope;
+  const prompt = _extractPrompt(payload);
+  if (!prompt) {
+    return EXIT_ALLOW;
+  }
+
+  const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
+  const target = path.join(options.consumer_root, STATE_FILE);
+  const previous = _loadState(target);
+  const classification = classify(prompt);
+  const next = nextState(
+    previous,
+    classification,
+    prompt.length,
+    session_id,
+    new Date().toISOString(),
+    // Injectable so the suite can pin a locale instead of inheriting the
+    // machine's — a test whose verdict depends on the developer's `LANG` is a
+    // test that passes here and fails in CI for reasons unrelated to the diff.
+    systemLocaleVerdict(options.env ?? process.env),
+  );
+
+  const effective = next?.language ?? (previous.language as Verdict | undefined);
+  // A state file written before `source` existed carries only what the old
+  // version could produce — a prompt reading. Absent is therefore `prompt`,
+  // never "unknown": treating it as unknown would reword the audited notice
+  // for every pre-existing session.
+  const effectiveSource: PinSource =
+    next?.source ?? (previous.source === "system-locale" ? "system-locale" : "prompt");
+  if (next) {
+    try {
+      atomic_write_json(target, next);
+    } catch {
+      // Observability only — a failed state write never blocks the turn.
+    }
+  }
+
+  if (effective === "de" || effective === "en") {
+    process.stdout.write(
+      `${JSON.stringify({ decision: "warn", reason: noticeText(effective, effectiveSource), additional_context: pinText(effective, effectiveSource) })}\n`,
+    );
+    return EXIT_WARN;
+  }
+  return EXIT_ALLOW;
+}
+
+export function main(argv?: string[]): number {
+  const args = argv ?? process.argv.slice(2);
+  let consumer_root = process.cwd();
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "--project-dir" && args[i + 1] !== undefined) {
+      consumer_root = args[i + 1] as string;
+      i += 1;
+    } else if (a !== undefined && a.startsWith("--project-dir=")) {
+      consumer_root = a.slice("--project-dir=".length);
+    }
+  }
+  return run(readHookStdin(), { consumer_root });
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== "undefined" && __AGENT_CONFIG_BUNDLE__) {
+    return false;
+  }
+  if (process.argv[1] === undefined) {
+    return false;
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/lint_abstraction_thresholds.ts

@@ -16,10 +16,18 @@
  *    `abstraction-thresholds` (the canon citation). A bare number is drift.
  *    A heading is its own block; a threshold-stating heading is satisfied
  *    when the block immediately below it carries the citation.
- * 2. PINNING — the six deliberate sites are pinned to their current
- *    number + scope (SITES), and the canon's four table rows are pinned
- *    (CANON_ROWS). Changing either side without the other is a finding:
- *    the canon and its citing sites move together or not at all.
+ * 2. PINNING — every deliberate site is pinned to its current scope
+ *    (SITES), and the canon's four table rows are pinned (CANON_ROWS).
+ *    Changing either side without the other is a finding: the canon and
+ *    its citing sites move together or not at all.
+ *
+ *    The site COUNT is deliberately not written here. This comment and
+ *    the one above `check_pins` both said "six" while `SITES` held seven
+ *    (two entries share `component-oriented-and-oop-development.md`, so
+ *    six distinct files became seven pins). Nothing pinned the literal —
+ *    the test derives its expectation from `SITES.length` — so the number
+ *    was free to rot, and did. Read the count off `SITES`; do not restate
+ *    it in prose that no gate checks.
  *
  * ## Regex tuning record (2026-08-03, measured against the real tree)
  *
@@ -65,12 +73,37 @@ export const CANON_CITATION = 'abstraction-thresholds';
 export const THRESHOLD_VERB = /\b(extract\w*|componenti[sz]\w*|abstraction)\b/i;
 
 /**
- * … and (b) states a numeric repetition bar. Three branches:
+ * … and (b) states a numeric repetition bar. Four branches:
  * cardinal count + repetition-noun · ordinal (repetition|occurrence only —
- * see the tuning record above) · `≥ N` + repetition-noun.
+ * see the tuning record above) · `≥ N` + repetition-noun · a repetition VERB
+ * carrying its count as a word-form adverb (`once` / `twice` / `thrice`).
+ *
+ * The fourth branch closes a measured hole: "extract when duplicated twice"
+ * states a real numeric bar and matched NOTHING. The cardinal branch needs a
+ * numeral from its own alternation immediately before a repetition-noun, and in
+ * that phrasing the count IS the adverb — there is no numeral and no noun. So
+ * the most natural English phrasing of the bar was the one shape that passed
+ * the gate silently.
+ *
+ * It is verb-anchored on purpose. A bare `\b(once|twice|thrice)\b` would fire on
+ * any block that happens to say "run it twice" near the word "extract"; binding
+ * the adverb to a duplication verb keeps the qualitative prose the tuning record
+ * protects finding-free, and adds no allowlist.
+ *
+ * The verb set is narrow because a wider one was MEASURED and rejected. A first
+ * cut also accepted `appears|occurs|used`, ran against the real tree, and
+ * returned exactly one hit: `gated-reach/SKILL.md`'s reddit-parsing gotcha, "one
+ * id **appears twice**, once as the real comment and once as a … stub". Its block
+ * is the whole Gotcha bullet list, which separately contains "extraction" — in
+ * the yt-dlp sense, an unrelated meaning of the word. Both halves fired on
+ * vocabulary coincidence. Dropping the three weak verbs kills that hit without an
+ * allowlist and still catches the reported phrasing (`duplicat\w+` covers
+ * "duplicated twice"). Widening the verb set again means re-measuring: the block
+ * granularity is blank-line-coarse, so a weak verb only has to co-occur with a
+ * homonym of "extract" somewhere in the same paragraph run.
  */
 export const NUMERIC_REPETITION =
-    /(\b(one|two|three|four|five|\d+)\s*(\+|×|x)?\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?)\b)|(\b(second|third|fourth)\s+(real\s+)?(repetitions?|occurrences?)\b)|(≥\s*\d+\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?))/i;
+    /(\b(one|two|three|four|five|\d+)\s*(\+|×|x)?\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?)\b)|(\b(second|third|fourth)\s+(real\s+)?(repetitions?|occurrences?)\b)|(≥\s*\d+\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?))|(\b(duplicat\w+|repeat\w+|recur\w+)\s+(only\s+)?(once|twice|thrice)\b)/i;
 
 /** The canon's four table rows — all must match CANON_FILE. */
 export const CANON_ROWS: ReadonlyArray<{ row: RegExp; why: string }> = [
@@ -249,7 +282,7 @@ export function scan_citations(repoRoot: string): { findings: Finding[]; scanned
     return { findings, scanned };
 }
 
-/** Bidirectional pins: canon rows + the six citing sites. */
+/** Bidirectional pins: canon rows + every citing site in SITES. */
 export function check_pins(repoRoot: string): Finding[] {
     const findings: Finding[] = [];
 

package/src/scripts/lint_agents_layout.ts

@@ -63,6 +63,7 @@ const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
     'notes',        // legacy; new files go to evidence/notes/
     'reports',      // legacy; new files go to evidence/reports/ (see agents-layout.md)
     'overrides',    // * consumer
+    'proposals',    // * consumer — curated self-improvement proposals, tracked
     'recruit-sessions',
     'reference',
     'roadmap-assets',
@@ -88,6 +89,7 @@ const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
     // Optional but legitimate consumer entries (will not trigger warnings)
     'knowledge',
     'memory',
+    'proposals',
     'roadmaps',
     'tmp',
     'tmp.old',