@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/_lib/host_permission_checks.ts

@@ -0,0 +1,251 @@
+/**
+ * host_permission_checks — report the host permission settings that produce
+ * confirmation prompts, and write none of them.
+ *
+ * WHY REPORT AND NOT WRITE. Three settings decide how often a normal coding
+ * task is interrupted, and all three belong to the consumer:
+ * `permissions.deny` rules that cover reads, the working tree's absence from
+ * `permissions.additionalDirectories`, and `permissions.defaultMode`. Writing
+ * any of them would be this package deciding a consumer's permission posture
+ * from inside their repository, which is the one thing a permission surface
+ * must never do quietly. `src/templates/consumer-settings/claude-settings.json`
+ * carries `enabledPlugins` and `hooks` and zero `permissions` keys; this check
+ * exists so that stays true and the consumer still gets the answer.
+ *
+ * WHY IT NAMES ALL THREE EVEN WHEN ALL THREE ARE ABSENT. Absent is a real
+ * answer and the most common one. A check that goes silent on the default
+ * project reports "nothing found" and "I did not look" identically, which is
+ * the measured-zero-versus-not-measured failure this tree's own report
+ * contracts argue against. So each setting is named on every run, with its
+ * resolved value or the word absent.
+ *
+ * READ ONLY, AND FAILURE-TOLERANT. An unreadable or malformed settings file is
+ * reported, never repaired: a consumer's JSON is theirs, and a doctor that
+ * rewrites what it came to inspect is not a doctor.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { WiringCheck } from "./runtime_wiring_checks.js";
+
+/** Injected so a test never reads the developer's own home directory. */
+export interface HostPermissionDeps {
+    projectRoot: string;
+    homeDir: string;
+    readFile: (p: string) => string | null;
+    isDirectory: (p: string) => boolean;
+}
+
+/** The permission block as the host writes it; every field optional. */
+interface PermissionBlock {
+    allow?: unknown;
+    deny?: unknown;
+    ask?: unknown;
+    additionalDirectories?: unknown;
+    defaultMode?: unknown;
+}
+
+/** One settings layer, in the host's own precedence order. */
+export interface SettingsLayer {
+    label: string;
+    file: string;
+    present: boolean;
+    unreadable: boolean;
+    permissions: PermissionBlock;
+}
+
+/**
+ * Tool names whose every documented effect is a read, plus the read-shaped
+ * `Bash(<cmd>:*)` heads. A deny covering one of these is the class that turns a
+ * category-A call back into a prompt, which is why it is worth naming
+ * separately from a deny on a write.
+ */
+const READ_SHAPED = [
+    "Read", "Glob", "Grep", "LS", "NotebookRead",
+    "Bash(cat", "Bash(ls", "Bash(head", "Bash(tail", "Bash(grep",
+    "Bash(rg", "Bash(find", "Bash(wc", "Bash(git status", "Bash(git log",
+    "Bash(git diff", "Bash(git show",
+];
+
+/** The four `defaultMode` values probed from Claude Code 2.1.263. */
+const KNOWN_MODES = ["default", "acceptEdits", "plan", "bypassPermissions"];
+
+function _strings(value: unknown): string[] {
+    return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
+}
+
+/** Default deps — the only place the real filesystem is touched. */
+export function defaultHostPermissionDeps(projectRoot: string): HostPermissionDeps {
+    return {
+        projectRoot,
+        homeDir: os.homedir(),
+        readFile: (p) => {
+            try {
+                return fs.readFileSync(p, "utf8");
+            } catch {
+                return null;
+            }
+        },
+        isDirectory: (p) => {
+            try {
+                return fs.statSync(p).isDirectory();
+            } catch {
+                return false;
+            }
+        },
+    };
+}
+
+/**
+ * Resolve the three settings layers the host reads, in its precedence order.
+ *
+ * There was no resolver for this before — `security_audit_config.ts` is the
+ * only place all three paths appear together, and only as glob strings — so
+ * this is the first code in the tree that reads `permissions` at all.
+ */
+export function readSettingsLayers(deps: HostPermissionDeps): SettingsLayer[] {
+    const candidates: Array<[string, string]> = [
+        ["user-global", path.join(deps.homeDir, ".claude", "settings.json")],
+        ["project", path.join(deps.projectRoot, ".claude", "settings.json")],
+        ["project-local", path.join(deps.projectRoot, ".claude", "settings.local.json")],
+    ];
+    return candidates.map(([label, file]) => {
+        const raw = deps.readFile(file);
+        if (raw === null) {
+            return { label, file, present: false, unreadable: false, permissions: {} };
+        }
+        try {
+            const parsed = JSON.parse(raw) as Record<string, unknown>;
+            const perms = parsed["permissions"];
+            return {
+                label,
+                file,
+                present: true,
+                unreadable: false,
+                permissions:
+                    perms !== null && typeof perms === "object" ? (perms as PermissionBlock) : {},
+            };
+        } catch {
+            return { label, file, present: true, unreadable: true, permissions: {} };
+        }
+    });
+}
+
+/** Deny rules that cover a read, with the layer each came from. */
+export function readDenyRules(layers: readonly SettingsLayer[]): Array<[string, string]> {
+    const hits: Array<[string, string]> = [];
+    for (const layer of layers) {
+        for (const rule of _strings(layer.permissions.deny)) {
+            if (READ_SHAPED.some((prefix) => rule.startsWith(prefix))) {
+                hits.push([layer.label, rule]);
+            }
+        }
+    }
+    return hits;
+}
+
+/** Every `additionalDirectories` entry across the layers; the host unions them. */
+export function additionalDirectories(layers: readonly SettingsLayer[]): string[] {
+    const seen: string[] = [];
+    for (const layer of layers) {
+        for (const dir of _strings(layer.permissions.additionalDirectories)) {
+            if (!seen.includes(dir)) seen.push(dir);
+        }
+    }
+    return seen;
+}
+
+/** The winning `defaultMode`, or `null` when no layer sets one. */
+export function resolvedDefaultMode(layers: readonly SettingsLayer[]): string | null {
+    let winner: string | null = null;
+    for (const layer of layers) {
+        const mode = layer.permissions.defaultMode;
+        if (typeof mode === "string" && mode.trim()) winner = mode.trim();
+    }
+    return winner;
+}
+
+/**
+ * Is the project root a LINKED worktree?
+ *
+ * A linked worktree's `.git` is a file holding a `gitdir:` pointer, never a
+ * directory. It matters here because a worktree root is a working directory the
+ * host was not started in, which is exactly the case
+ * `additionalDirectories` exists to cover — and the case a consumer is least
+ * likely to have thought about.
+ */
+export function isLinkedWorktree(deps: HostPermissionDeps): boolean {
+    const dotGit = path.join(deps.projectRoot, ".git");
+    const raw = deps.readFile(dotGit);
+    if (raw === null) return false;
+    return !deps.isDirectory(dotGit) && raw.trimStart().startsWith("gitdir:");
+}
+
+/** The copyable snippet — the consumer pastes it, this package never writes it. */
+export function permissionSnippet(projectRoot: string): string {
+    return JSON.stringify(
+        { permissions: { additionalDirectories: [projectRoot], defaultMode: "default" } },
+        null,
+        2,
+    );
+}
+
+/**
+ * The doctor row.
+ *
+ * `warn` when something reportable was found, `ok` otherwise. Never `fail`:
+ * these are the consumer's own choices, and a doctor that fails a build over a
+ * setting it is forbidden to write would be asking for a change it will not
+ * make.
+ */
+export function checkHostPermissionSettings(deps: HostPermissionDeps): WiringCheck {
+    const layers = readSettingsLayers(deps);
+    const unreadable = layers.filter((l) => l.unreadable);
+    const denies = readDenyRules(layers);
+    const dirs = additionalDirectories(layers);
+    const mode = resolvedDefaultMode(layers);
+    const worktree = isLinkedWorktree(deps);
+    const rootListed = dirs.some(
+        (d) => path.resolve(d) === path.resolve(deps.projectRoot),
+    );
+
+    const lines: string[] = [];
+    lines.push(
+        denies.length === 0
+            ? "read-deny rules: absent — no permissions.deny rule covers a read"
+            : `read-deny rules: ${denies.length} — ` +
+              denies.map(([layer, rule]) => `${rule} (${layer})`).join(", "),
+    );
+    lines.push(
+        rootListed
+            ? `working tree in additionalDirectories: present (${deps.projectRoot})`
+            : `working tree in additionalDirectories: absent (${deps.projectRoot}` +
+              `${worktree ? ", a linked worktree" : ""})`,
+    );
+    lines.push(
+        mode === null
+            ? "permissions.defaultMode: absent — the host's own built-in default applies"
+            : `permissions.defaultMode: ${mode}` +
+              (KNOWN_MODES.includes(mode) ? "" : " — not a value this tree has probed"),
+    );
+    for (const layer of unreadable) {
+        lines.push(`unreadable: ${layer.file} (${layer.label}) is not valid JSON`);
+    }
+
+    // A linked worktree unlisted in additionalDirectories is the one finding
+    // worth surfacing on its own: the host was started somewhere else, so every
+    // call into this tree is a call into a directory it was not granted.
+    const reportable =
+        denies.length > 0 || unreadable.length > 0 || (worktree && !rootListed);
+
+    return {
+        id: "host-permission-settings",
+        status: reportable ? "warn" : "ok",
+        message: lines.join("; "),
+        remedy:
+            "agent-config never writes permissions — paste this into " +
+            `${path.join(deps.projectRoot, ".claude", "settings.local.json")} yourself if you want it: ` +
+            permissionSnippet(deps.projectRoot).replace(/\s+/g, " "),
+    };
+}

package/src/scripts/_lib/model_tier.ts

@@ -11,7 +11,7 @@
  * - the repo generator (`condense.py generate_claude_skills`), which
  *   builds the package's own `.claude/skills/` tree, and
  * - the consumer install finalizer
- *   (`install.py finalize_claude_model_tiers`), which rewrites the
+ *   (the installer's `finalize_claude_model_tiers`), which rewrites the
  *   installed `.claude/skills/` tree so Claude Code performs the
  *   per-turn model switch on a consumer with `model.auto_switch: auto`.
  *

package/src/scripts/_lib/obligation_frequency.ts

@@ -275,7 +275,7 @@ export function slot_frequency(platform: string, slot: Slot): Frequency {
 }
 
 /**
- * Platforms with no hook surface at all.
+ * Platforms this package binds nothing on.
  *
  * Copilot declares `fallback_only: true` in the manifest — concerns route
  * through rule-only fallback and the dispatcher no-ops. Every hook-declared
@@ -294,7 +294,7 @@ export function is_hook_capable(platform_block: Record<string, unknown>): boolea
 export interface PlatformBinding {
     /** Platform id → slot → concern ids bound in that slot. */
     slots: Map<string, Map<Slot, string[]>>;
-    /** Platform ids that carry no hook surface at all. */
+    /** Platform ids declared `fallback_only` — this package binds nothing there. */
     fallback_only: Set<string>;
 }
 

package/src/scripts/_lib/release_highlights.ts

@@ -25,7 +25,15 @@
  */
 import { spawnSync } from 'node:child_process';
 
-import { CURATED_HEAD_INSTRUCTION } from './release_material.js';
+import {
+    CURATED_HEAD_INSTRUCTION,
+    MIX_RESPONSE_MARKER,
+    MIX_RESPONSE_PLACEHOLDERS,
+    PROMISE_OUTCOMES,
+    PROMISE_PHRASE,
+    PROMISE_READBACK_MARKER,
+    extract_changelog_section,
+} from './release_material.js';
 
 /** The five curated labels, in the order an operator reads them. */
 export const HEAD_LABELS: readonly string[] = [
@@ -398,6 +406,7 @@ export function publication_blockers(
     sectionBody: string,
     version: string,
     where = '`main`',
+    mix: MixObligation | null = null,
 ): string[] {
     const out: string[] = [];
     if (sectionBody.includes(DERIVED_MARKER)) {
@@ -414,9 +423,264 @@ export function publication_blockers(
                 'comment line from the section and re-run.',
         );
     }
+    out.push(...mix_response_blockers(sectionBody, version, where, mix));
     return out;
 }
 
+/**
+ * Everything that makes a whole SECTION unpublishable — the head-level
+ * blockers above plus the two obligations that only exist for a full section.
+ *
+ * Two levels and not one, because `publication_blockers` is legitimately called
+ * with a bare curated head (the prefill tests do exactly that), and a head
+ * fragment has no tests footer by construction. Folding a section obligation
+ * into the head predicate would make those callers red on a rule that does not
+ * apply to what they passed.
+ *
+ * The TWO cheapest guard sites call this one — `guard_release_curation` (before
+ * any commit) and `guard_release_branch_push` (before any remote state). The
+ * two publication sites reached through `_refuse_unpublishable` (the annotated
+ * tag and the GitHub Release) stay on the head-level predicate: by then the
+ * section has already shipped in a merged PR, and adding a refusal there would
+ * block a resumed publication over an obligation the release cannot still act
+ * on. Stated rather than implied, because "the guard sites call this one" read
+ * as all four and is not true of any of them but the two named here.
+ */
+export function section_publication_blockers(
+    sectionBody: string,
+    version: string,
+    where = '`main`',
+    mix: MixObligation | null = null,
+): string[] {
+    const out = publication_blockers(sectionBody, version, where, mix);
+    if (!TEST_FOOTER_RE.test(sectionBody)) {
+        out.push(
+            `the ${version} section carries no \`Tests: N (+M since PREV)\` footer. ` +
+                '`_render_test_trend_line` degrades to `null` when the vitest collection ' +
+                'fails, so a missing line means the collection failed during `task release`. ' +
+                'Fix the collection, then render the number and put it on the section — ' +
+                `the release commit already exists on ${where}, so amend it there. Do not ` +
+                'invent the count: `npx vitest list | wc -l` is the same probe the writer runs.',
+        );
+    }
+    return out;
+}
+
+/**
+ * The tests-footer convention, in force for every release since 9.1.0.
+ *
+ * Duplicated from `release-validation.yml`'s inline check until 2026-09-05,
+ * where it was the ONLY copy — so the absence was red at release-PR time and
+ * invisible before it. 9.8.0 shipped without the line. The regex is the same
+ * one the workflow uses; the workflow's own comment already recorded that the
+ * writer "degrades SILENTLY to null on collection failure", which is exactly a
+ * defect a local guard should see first.
+ */
+const TEST_FOOTER_RE = /^Tests: \d+/mu;
+
+/**
+ * The measured governance-versus-product level, as the writer and the guards
+ * both receive it.
+ *
+ * A plain record and not the measurement itself: this module is reached by the
+ * push guard, the pre-commit ask and the CI gate, and only the callers have git
+ * to measure with. Passing the reading in keeps the predicate pure and keeps
+ * `measure_release_mix`'s git access out of a module three guards import.
+ */
+export interface MixObligation {
+    triggered: boolean;
+    level: string;
+}
+
+/** Minimum written characters after the marker — a bare marker is not an answer. */
+export const MIX_RESPONSE_MIN_CHARS = 40;
+
+/**
+ * The ONE predicate for the governance-versus-product obligation.
+ *
+ * `check_release_highlights` refuses this from the CI side and
+ * `guard_release_branch_push` from the local side, and until 2026-09-05 only
+ * the first of the two knew the obligation existed. That asymmetry is what the
+ * contract itself recorded — *"the earliest refusal for this one obligation is
+ * the PR, not the push"* (`docs/contracts/CHANGELOG-conventions.md`) — and what
+ * cost 14.17.0 a red release PR. Both sides now read this function, so a change
+ * to the obligation cannot reach one guard and miss the other.
+ *
+ * `null` means the measurement did not run (shallow clone, missing tag). That
+ * degrades to no blocker, matching the gate's documented stance: this is a
+ * governance signal, not a correctness control, and an environment fact must
+ * not block a release.
+ */
+export function mix_response_blockers(
+    sectionBody: string,
+    version: string,
+    where = '`main`',
+    mix: MixObligation | null = null,
+): string[] {
+    if (!mix || !mix.triggered) {
+        return [];
+    }
+    const idx = sectionBody.indexOf(MIX_RESPONSE_MARKER);
+    if (idx === -1) {
+        return [
+            `the ${version} section owes a governance-versus-product response ` +
+                `(${mix.level}) and carries none. Add one \`> ${MIX_RESPONSE_MARKER}\` line ` +
+                `immediately under the curated head on ${where}, naming the next cycle's ` +
+                'consumer work or a maintainer justification.',
+        ];
+    }
+    const block = mix_response_block(sectionBody, idx);
+    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
+    if (left.length > 0) {
+        return [
+            `the ${version} governance-versus-product response still carries the writer's ` +
+                `placeholder(s) (${left.map((t) => `\`${t}\``).join(', ')}) — the measured level ` +
+                'is the generator\'s, the answer is not, and `CHANGELOG.md` is published to npm. ' +
+                `Name the next cycle's consumer work (or the justification) on ${where} and re-run.`,
+        ];
+    }
+    if (human_answer(block, mix.level).length < MIX_RESPONSE_MIN_CHARS) {
+        return [
+            `the ${version} governance-versus-product response carries no written answer ` +
+                `beyond the measured level (${mix.level}). The level is the generator's; the ` +
+                `response has to name the next cycle's consumer work or a maintainer ` +
+                `justification. Write it on ${where}, in the \`> \` block under the marker.`,
+        ];
+    }
+    return [];
+}
+
+/**
+ * The promise the PREVIOUS release head made, or null when it made none.
+ *
+ * Scoped to that section's governance-response block, not to its whole body: a
+ * product line that happens to contain the phrase is not a promise the project
+ * made about the next cycle.
+ */
+export function previous_promise(changelogText: string, previousVersion: string): string | null {
+    const section = extract_changelog_section(changelogText, previousVersion);
+    if (section === null) return null;
+    const idx = section.body.indexOf(MIX_RESPONSE_MARKER);
+    if (idx === -1) return null;
+    const block = mix_response_block(section.body, idx);
+    return block.includes(PROMISE_PHRASE) ? block : null;
+}
+
+/**
+ * The ONE predicate for "did this head answer the previous head's promise?".
+ *
+ * The defect: `_lib/release_material.ts` generates a `Next cycle ships …` line
+ * and nothing has ever read the previous one back, so an unmet promise can be
+ * restated indefinitely at zero cost — the debt is booked and never called. A
+ * promise nobody reads is not a commitment, it is a sentence.
+ *
+ * Three outcomes are accepted and one of them must be chosen, which is the
+ * whole mechanism: it does not require the promise to have been KEPT, and no
+ * ratio, deadline or count is enforced here. Refusing an unkept promise would
+ * make the honest answer the expensive one and teach an author to promise less
+ * rather than to answer truthfully.
+ *
+ * Length floor and placeholder scan reuse the governance-response discipline
+ * for the same reason it exists there: a bare marker, or the writer's own
+ * scaffolding, is not an answer a human wrote.
+ */
+export function promise_readback_blockers(
+    sectionBody: string,
+    version: string,
+    previousVersion: string,
+    promise: string | null,
+    where = '`main`',
+): string[] {
+    if (promise === null) return [];
+    const idx = sectionBody.indexOf(PROMISE_READBACK_MARKER);
+    if (idx === -1) {
+        return [
+            `the ${version} section does not answer the ${previousVersion} head's ` +
+                `\`${PROMISE_PHRASE}\` promise. Add one \`> ${PROMISE_READBACK_MARKER}\` line ` +
+                `immediately under the curated head on ${where}, naming the promise and whether ` +
+                `it ${PROMISE_OUTCOMES.join(', ')} (the last one with its reason).`,
+        ];
+    }
+    const block = mix_response_block(sectionBody, idx);
+    const left = MIX_RESPONSE_PLACEHOLDERS.filter((t) => block.includes(t));
+    if (left.length > 0) {
+        return [
+            `the ${version} previous-cycle answer still carries the writer's placeholder(s) ` +
+                `(${left.map((t) => `\`${t}\``).join(', ')}). \`CHANGELOG.md\` is published to npm. ` +
+                `Write the outcome on ${where} and re-run.`,
+        ];
+    }
+    const lower = block.toLowerCase();
+    const named = PROMISE_OUTCOMES.filter((o) => lower.includes(o));
+    if (named.length === 0) {
+        return [
+            `the ${version} previous-cycle answer names no outcome. It has to say which of ` +
+                `${PROMISE_OUTCOMES.join(', ')} applies to the ${previousVersion} promise — an ` +
+                'answer that restates the promise without resolving it is the failure this reads ' +
+                'back for.',
+        ];
+    }
+    if (readback_answer(block).length < MIX_RESPONSE_MIN_CHARS) {
+        return [
+            `the ${version} previous-cycle answer is shorter than a written answer ` +
+                `(${String(MIX_RESPONSE_MIN_CHARS)} characters after the marker). Name what was ` +
+                `promised and what became of it on ${where}, not the outcome word alone.`,
+        ];
+    }
+    return [];
+}
+
+/** What the author wrote under the read-back marker, marker and quoting removed. */
+export function readback_answer(block: string): string {
+    return block
+        .replace(PROMISE_READBACK_MARKER, '')
+        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
+        .replace(/[>\s]+/gu, ' ')
+        .trim();
+}
+
+/**
+ * The whole response block: the marker's line plus every blockquote line under it.
+ *
+ * Reading only the FIRST line after the marker was wrong in both directions, and
+ * both were reproduced before this was written. It **accepted** a section whose
+ * placeholder line had simply been deleted, because the machine-written level
+ * alone is 54 characters and cleared the floor — the smuggled auto-approval the
+ * placeholder exists to prevent. And it **refused** the writer's own two-line
+ * template, where the level sits on line 1 and the answer on line 2.
+ *
+ * Scoping to the block also fixes the placeholder scan, which searched the
+ * entire section body: a legitimate changelog line containing
+ * `<roadmap or issue>` blocked the release.
+ */
+export function mix_response_block(sectionBody: string, markerIdx: number): string {
+    const lines = sectionBody.slice(markerIdx).split('\n');
+    const out: string[] = [lines[0] ?? ''];
+    for (const line of lines.slice(1)) {
+        if (!line.trimStart().startsWith('>')) break;
+        out.push(line);
+    }
+    return out.join('\n');
+}
+
+/**
+ * What is left of the response block once the generator's own contribution is
+ * removed — i.e. the part a human had to write.
+ *
+ * The measured level is stripped because the writer emitted it; a floor that
+ * counted it would be satisfied by the tool on the author's behalf, which is
+ * the whole failure this obligation guards against.
+ */
+export function human_answer(block: string, level: string): string {
+    return block
+        .replace(MIX_RESPONSE_MARKER, '')
+        .split(level)
+        .join('')
+        .replace(/^[>\s.]+|[>\s.]+$/gu, '')
+        .replace(/[>\s]+/gu, ' ')
+        .trim();
+}
+
 /** Labels whose curated value is still the generator's unedited draft. */
 export function stale_draft_labels(
     curated: Readonly<Record<string, string>>,