@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/self_review_gate.ts

@@ -83,9 +83,9 @@ export function isReviewablePath(p: string): boolean {
     return !SKIP_PREFIXES.some((pre) => p.startsWith(pre));
 }
 
-function changedFiles(baseRef: string): string[] {
+function changedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
     const r = spawnSync('git', ['diff', '--name-only', `${baseRef}...HEAD`], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
     });
     if (r.status !== 0) {
@@ -98,10 +98,10 @@ function changedFiles(baseRef: string): string[] {
         .filter(isReviewablePath);
 }
 
-function diffText(baseRef: string, files: string[]): string {
+function diffText(baseRef: string, files: string[], cwd: string = REPO_ROOT): string {
     if (files.length === 0) return '';
     const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', ...files], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
         maxBuffer: 32 * 1024 * 1024,
     });
@@ -109,10 +109,10 @@ function diffText(baseRef: string, files: string[]): string {
 }
 
 /** Sum of added+deleted lines across `files` (binary files count 0). */
-function changedLineCount(baseRef: string, files: string[]): number {
+function changedLineCount(baseRef: string, files: string[], cwd: string = REPO_ROOT): number {
     if (files.length === 0) return 0;
     const r = spawnSync('git', ['diff', '--numstat', `${baseRef}...HEAD`, '--', ...files], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
         maxBuffer: 32 * 1024 * 1024,
     });
@@ -124,6 +124,94 @@ function changedLineCount(baseRef: string, files: string[]): number {
     return total;
 }
 
+// ── Release-PR detection (road-to-feedback-9.2.0-followups Phase 3) ────
+/**
+ * A release PR is detected from its own packaging diff (baseRef...HEAD,
+ * scoped to CHANGELOG.md + package.json): an added changelog heading and an
+ * added package.json version bump, agreeing on the same version. Pure over
+ * the patch text — no git call — so it is unit-testable with synthetic
+ * patches. See docs/design/release-pr-review-mode.md.
+ */
+export function detectReleaseVersion(patchText: string): string | null {
+    const addedLines = patchText
+        .split('\n')
+        .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+        .map((l) => l.slice(1));
+
+    let changelogVersion: string | null = null;
+    let packageVersion: string | null = null;
+    for (const line of addedLines) {
+        const changelogMatch = /^##\s*\[(\d+\.\d+\.\d+)\]/.exec(line);
+        if (changelogMatch) changelogVersion = changelogMatch[1] ?? null;
+        const packageMatch = /^\s*"version"\s*:\s*"(\d+\.\d+\.\d+)"/.exec(line);
+        if (packageMatch) packageVersion = packageMatch[1] ?? null;
+    }
+    if (changelogVersion && packageVersion && changelogVersion === packageVersion) {
+        return changelogVersion;
+    }
+    return null;
+}
+
+function releaseDetectionPatch(baseRef: string, cwd: string): string {
+    const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', 'CHANGELOG.md', 'package.json'], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return (r.stdout ?? '').toString();
+}
+
+/** Impure wrapper: collects the packaging patch via git, then detects. */
+export function detectReleaseVersionFromGit(baseRef: string, cwd: string = REPO_ROOT): string | null {
+    return detectReleaseVersion(releaseDetectionPatch(baseRef, cwd));
+}
+
+/** `major.minor.patch`, tolerating an optional `v` prefix; null if not semver-shaped. */
+function parseSemver(raw: string): [number, number, number] | null {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(raw.trim());
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function semverLessThan(a: [number, number, number], b: [number, number, number]): boolean {
+    const [aMajor, aMinor, aPatch] = a;
+    const [bMajor, bMinor, bPatch] = b;
+    if (aMajor !== bMajor) return aMajor < bMajor;
+    if (aMinor !== bMinor) return aMinor < bMinor;
+    return aPatch < bPatch;
+}
+
+/**
+ * Highest semver-shaped tag strictly below `version`, or null if none. Pure
+ * over the supplied tag list — no git call. Non-semver tags (branch-backup
+ * names etc.) are ignored rather than throwing.
+ */
+export function pickPreviousTag(version: string, tags: readonly string[]): string | null {
+    const target = parseSemver(version);
+    if (!target) return null;
+    let best: { raw: string; parsed: [number, number, number] } | null = null;
+    for (const raw of tags) {
+        const parsed = parseSemver(raw);
+        if (!parsed) continue;
+        if (!semverLessThan(parsed, target)) continue;
+        if (!best || semverLessThan(best.parsed, parsed)) best = { raw, parsed };
+    }
+    return best ? best.raw : null;
+}
+
+function listGitTags(cwd: string): string[] {
+    const r = spawnSync('git', ['tag'], { cwd, encoding: 'utf8' });
+    return (r.stdout ?? '')
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+
+/** Impure wrapper: lists tags via git, then picks the previous one. */
+export function resolvePreviousTagFromGit(version: string, cwd: string = REPO_ROOT): string | null {
+    return pickPreviousTag(version, listGitTags(cwd));
+}
+
 // ── Escalation classifier (large / claim-affecting → full ai-council) ──
 /**
  * A large or claim-affecting diff warrants the FULL `ai-council` (advisor
@@ -157,9 +245,31 @@ function loadSkillBody(name: string): string {
     return readFileSync(p, 'utf8');
 }
 
-function buildSystemPrompt(): string {
+/** Info about a detected release PR — see docs/design/release-pr-review-mode.md. */
+export interface ReleaseInfo {
+    version: string;
+    previousTag: string;
+    /** Files touched by the packaging diff (baseRef...HEAD) — for context only. */
+    packagingFiles: string[];
+}
+
+/**
+ * Release-mode note appended to the system prompt so the model analyzes the
+ * feature range instead of reporting release features as "not in the diff"
+ * (the PR #957 false-advisory shape — see docs/design/release-pr-review-mode.md).
+ */
+function releaseNoteText(release: ReleaseInfo, baseRef: string): string {
+    const fileList = release.packagingFiles.length > 0 ? release.packagingFiles.join(', ') : '(none)';
+    return (
+        `\n\nRelease PR for ${release.version}: analysis range is ${release.previousTag}...HEAD ` +
+        `(the full release commit range). The packaging diff vs ${baseRef} touches: ${fileList}. ` +
+        "Do NOT report a feature as 'not in the diff' when it is present in the release range."
+    );
+}
+
+function buildSystemPrompt(release?: ReleaseInfo, baseRef?: string): string {
     const bodies = REVIEW_SKILLS.map((s) => `# Skill: ${s}\n\n${loadSkillBody(s)}`).join('\n\n---\n\n');
-    return [
+    const base = [
         'You are the self-review gate for an AI-agent governance package. Apply the',
         'two skills below to the supplied PR diff. Return ONLY a JSON object of the',
         'shape {"findings":[{"severity":"critical|high|medium|low",',
@@ -170,6 +280,7 @@ function buildSystemPrompt(): string {
         '',
         bodies,
     ].join('\n');
+    return release && baseRef ? base + releaseNoteText(release, baseRef) : base;
 }
 
 // ── Plan (dry-run) ────────────────────────────────────────────────────
@@ -179,22 +290,47 @@ export interface ReviewPlan {
     promptChars: number;
     note: string;
     escalation: string[];
+    /** The base actually analyzed for `files`/diff: `baseRef`, or `release.previousTag`. */
+    analysisBase: string;
+    /** Present iff a release PR was detected — see docs/design/release-pr-review-mode.md. */
+    release?: ReleaseInfo;
 }
 
-export function buildPlan(baseRef: string): ReviewPlan {
-    const files = changedFiles(baseRef);
-    const diff = diffText(baseRef, files);
-    const escalation = escalationReasons(files, changedLineCount(baseRef, files));
+export function buildPlan(baseRef: string, cwd: string = REPO_ROOT): ReviewPlan {
+    const packagingFiles = changedFiles(baseRef, cwd);
+    const releaseVersion = detectReleaseVersionFromGit(baseRef, cwd);
+
+    let release: ReleaseInfo | undefined;
+    let analysisBase = baseRef;
+    if (releaseVersion) {
+        const previousTag = resolvePreviousTagFromGit(releaseVersion, cwd);
+        if (previousTag) {
+            release = { version: releaseVersion, previousTag, packagingFiles };
+            analysisBase = previousTag;
+        } else {
+            process.stdout.write(
+                `::notice::self-review-gate — release ${releaseVersion} detected but no previous tag ` +
+                    `found; falling back to the normal base (${baseRef}).\n`,
+            );
+        }
+    }
+
+    const files = analysisBase === baseRef ? packagingFiles : changedFiles(analysisBase, cwd);
+    const diff = diffText(analysisBase, files, cwd);
+    const escalation = escalationReasons(files, changedLineCount(analysisBase, files, cwd));
+    const systemPrompt = buildSystemPrompt(release, baseRef);
     return {
         skills: [...REVIEW_SKILLS],
         files,
-        promptChars: buildSystemPrompt().length + diff.length,
+        analysisBase,
+        ...(release ? { release } : {}),
+        promptChars: systemPrompt.length + diff.length,
         escalation,
         note:
             files.length === 0
                 ? 'No reviewable (non-generated) files changed — the live review would no-op.'
                 : `${files.length} reviewable file(s); live review would send ~${Math.ceil(
-                      (buildSystemPrompt().length + diff.length) / 4,
+                      (systemPrompt.length + diff.length) / 4,
                   )} input tokens.`,
     };
 }
@@ -302,6 +438,10 @@ export function main(argv: string[]): 0 | 2 {
         process.stdout.write(
             `self-review-gate (dry-run — no spend, advisory):\n` +
                 `  skills: ${plan.skills.join(', ')}\n` +
+                (plan.release
+                    ? `  mode:   release (${plan.release.version}; feature range ${plan.release.previousTag}...HEAD; ` +
+                      `packaging diff ${plan.release.packagingFiles.length} file(s))\n`
+                    : '') +
                 `  files:  ${plan.files.length}\n` +
                 `  ${plan.note}\n` +
                 (plan.escalation.length
@@ -341,7 +481,7 @@ export function main(argv: string[]): 0 | 2 {
     // findings returns 2 — an error is not a finding.)
     try {
         const client = new AnthropicClient({ api_key: key });
-        const resp = client.ask(buildSystemPrompt(), diffText(baseRef, plan.files), 4096);
+        const resp = client.ask(buildSystemPrompt(plan.release, baseRef), diffText(plan.analysisBase, plan.files), 4096);
         if (resp.error) {
             process.stdout.write(
                 `::warning::self-review-gate NEUTRAL — model call did not complete (${resp.error}); ` +

package/src/scripts/session_canary_hook.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * Session-canary injection — `session_start` hook.
+ *
+ * Deterministic backstop for the `session-canary` rule. When the consumer has
+ * set `personal.canary_name` in `.agent-settings.yml`, every NEW session gets a
+ * `<session-canary>` context block injected at start (same mechanism as
+ * hot-context: `{"decision":"allow","context":"<block>"}` on stdout; the
+ * dispatcher forwards `context` on session_start so the host adds it to the
+ * session context).
+ *
+ * Why a hook and not just the rule: the canary contract (greet the user by
+ * name at task start; reply-close markers at the end of work replies) is a
+ * liveness signal — the user watches it like a canary in a coal mine, and its
+ * silent disappearance means the context window is degrading. A trigger-routed
+ * rule alone is exactly the kind of surface that is dropped in fresh
+ * conversations (found RED baseline on the reply-close PR-URL contract,
+ * 2026-07-27); the session_start injection makes the contract present in every
+ * new conversation on hook-capable hosts. Copilot (no hook surface) falls back
+ * to the rule alone.
+ *
+ * Gate: `personal.canary_name` non-empty. Missing settings file, missing key,
+ * or empty value → clean no-op (exit 0, no stdout). Never blocks
+ * (fail_closed: false).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readHookStdin } from "./hooks/hook_stdin.js";
+
+const EXIT_ALLOW = 0;
+
+export const SETTINGS_FILE = ".agent-settings.yml";
+
+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);
+}
+
+/**
+ * Minimal line-walker for `personal.canary_name` — no YAML dependency, same
+ * approach as onboarding_gate_hook._read_onboarded. Returns the raw scalar or
+ * null when the section/key is absent.
+ */
+export function read_canary_name(settings_path: string): string | null {
+  let text: string;
+  try {
+    if (!fs.statSync(settings_path).isFile()) {
+      return null;
+    }
+    text = fs.readFileSync(settings_path, "utf-8");
+  } catch {
+    return null;
+  }
+  let in_personal = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^personal\s*:\s*(?:#.*)?$/.test(line)) {
+      in_personal = true;
+      continue;
+    }
+    if (in_personal && /^\S/.test(line)) {
+      in_personal = false; // left the personal: block
+    }
+    if (in_personal) {
+      const m = /^\s+canary_name\s*:\s*(.*?)\s*(?:#.*)?$/.exec(line);
+      if (m && m[1] !== undefined) {
+        return m[1].trim();
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The name is user-owned config, but it lands verbatim in model context —
+ * strip quotes, collapse whitespace, drop markup-significant characters, and
+ * cap the length so a mangled settings file cannot smuggle a paragraph in.
+ */
+export function sanitize_name(raw: string | null): string {
+  if (raw === null) {
+    return "";
+  }
+  let name = raw.trim();
+  if (
+    (name.startsWith('"') && name.endsWith('"')) ||
+    (name.startsWith("'") && name.endsWith("'"))
+  ) {
+    name = name.slice(1, -1);
+  }
+  name = name.replace(/[<>&`]/g, "").replace(/\s+/g, " ").trim();
+  return name.slice(0, 64);
+}
+
+export function build_canary_block(name: string): string {
+  return [
+    `<session-canary settings-key="personal.canary_name">`,
+    `The user has configured a session canary. Two obligations, this whole conversation:`,
+    `1. OPENING CANARY — the first reply of this session, and the first reply of each` +
+      ` NEW task within it, opens by addressing the user by name: "${name}". One natural` +
+      ` mention in the user's language; intermediate replies of the same task do not re-greet.`,
+    `2. CLOSING CANARY — a reply that landed substantial work ends with ONE compact` +
+      ` end-summary, and a PR created or updated this turn puts its raw URL as the` +
+      ` LITERAL LAST LINE (reply-close contract of the direct-answers rule).`,
+    `Purpose: the user watches these markers like a canary in a mine — their silent` +
+      ` disappearance signals context degradation. Never fake continuity: if you notice` +
+      ` you dropped a canary, say so and suggest a fresh session or /agent-handoff.`,
+    `</session-canary>`,
+  ].join("\n");
+}
+
+function _workspaceRoot(envelope: JsonObject): string {
+  const v = envelope["workspace_root"];
+  if (typeof v === "string" && v) {
+    return v;
+  }
+  return process.cwd();
+}
+
+export function main(): number {
+  let envelope: JsonValue = {};
+  try {
+    const raw = _readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    // malformed stdin — still try cwd-based settings below; never block
+  }
+  const env: JsonObject = _isObject(envelope) ? envelope : {};
+
+  // Only session_start carries context-injection semantics; other events no-op.
+  const event = env["event"];
+  if (typeof event === "string" && event !== "" && event !== "session_start") {
+    return EXIT_ALLOW;
+  }
+
+  const root = _workspaceRoot(env);
+  const name = sanitize_name(read_canary_name(path.join(root, SETTINGS_FILE)));
+  if (!name) {
+    return EXIT_ALLOW; // canary not configured — clean no-op
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "allow",
+      reason: `session-canary: active for "${name}"`,
+      context: build_canary_block(name),
+    })}\n`,
+  );
+  return EXIT_ALLOW;
+}
+
+function _readStdin(): string {
+  return readHookStdin();
+}
+
+// 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/skill_linter.ts

@@ -3327,6 +3327,50 @@ export function check_structural_malice(text: string): Issue[] {
     return issues;
 }
 
+// --- Anti-nag check ---
+//
+// A skill may describe a capability; it may not nag the agent into re-invoking
+// it, obligate an update check the package cannot honour offline, or claim
+// unconditional primacy over sibling skills. The token list below IS the
+// contract — greppable on purpose, so an author can see exactly what is refused
+// without reading the linter.
+//
+// Measured before wiring: 0 hits across all 281 shipped skills. This is a
+// regression guard, not a cleanup task — so any hit is a new violation and
+// `error` is the honest severity. A skill that must quote one of these phrases
+// as a negative example belongs in prose docs, not in a SKILL.md body.
+
+const _NAG_UPDATE_CHECK = /(?:check\s+(?:for\s+)?(?:updates?|(?:a\s+)?(?:newer|later|latest)\s+version))/i;
+const _NAG_STAY_CURRENT = /(?:(?:ensure|make sure)\s+(?:you(?:\s+are|\s*'re)?\s+)?(?:on|running|using)\s+the\s+latest)/i;
+const _NAG_SELF_PROMO = /(?:(?:always|you\s+must)\s+use\s+this\s+skill)/i;
+const _NAG_BEST_SKILL = /(?:this\s+skill\s+is\s+the\s+(?:best|only|preferred))/i;
+const _NAG_MUST_USE = /\bMUST[- ]USE\b/;
+const _NAG_ALWAYS_USE = /\bALWAYS\s+USE\s+THIS\b/i;
+
+const _NAG_PATTERNS: Array<[string, RegExp]> = [
+    ['update_check', _NAG_UPDATE_CHECK],
+    ['stay_current', _NAG_STAY_CURRENT],
+    ['self_promo', _NAG_SELF_PROMO],
+    ['best_skill', _NAG_BEST_SKILL],
+    ['must_use', _NAG_MUST_USE],
+    ['always_use', _NAG_ALWAYS_USE],
+];
+
+export function check_skill_nag(text: string): Issue[] {
+    const issues: Issue[] = [];
+    const lines = splitlines(text);
+    lines.forEach((raw, idx) => {
+        const lineno = idx + 1;
+        for (const [name, pattern] of _NAG_PATTERNS) {
+            const match = pattern.exec(raw);
+            if (match) {
+                issues.push(new Issue('error', `nag:${name}`, `${lineno}:${match[0].trim()}`));
+            }
+        }
+    });
+    return issues;
+}
+
 // --- Output-schema check ---
 
 const _OUTPUT_SCHEMA_KEY_PATTERN = /^(\w+):\s*(.*?)\s*$/;
@@ -3529,6 +3573,17 @@ export function lint_file(p: string, repoRoot: string | null = null): LintResult
         }
     }
 
+    // Skills only: rules legitimately carry unconditional MUST language (that is
+    // what an Iron Law is), so applying the nag list to rules would fight the
+    // rule layer's own register.
+    if (artifactType === 'skill') {
+        const nagIssues = check_skill_nag(text);
+        if (nagIssues.length > 0) {
+            result.issues.push(...nagIssues);
+            result.status = classify_status(result.issues);
+        }
+    }
+
     const frugalityIssues = lint_frugality_writer_cite(displayPath, text, artifactType);
     if (frugalityIssues.length > 0) {
         result.issues.push(...frugalityIssues);

package/src/scripts/smoke_quickstart.ts

@@ -78,8 +78,8 @@ function _checkInstallerRuns(tmpdir: string): [number, string | null] {
     ];
     // ADR-020: --project is reserved for maintainers; CI is a maintainer context.
     const env = { ...process.env, AGENT_CONFIG_DEV_MODE: '1' };
-    // Run the installer's `.ts` twin via the repo-local tsx binary (was
-    // `python3 install.py`; the retired Python implementation is deleted).
+    // Run the installer's `.ts` twin via the repo-local tsx binary (the
+    // retired Python implementation is deleted, ADR-200).
     const result = spawnSync(TSX_BIN, cmd, {
         encoding: 'utf-8',
         timeout: 60000,

package/src/scripts/surface_probe_hook.ts

@@ -28,6 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { is_replay_mode } from './hooks/state_io.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
 
 const CHECK_WINDOW_MS = 24 * 60 * 60 * 1000;
 const STATE_REL = ['agents', 'runtime', 'state', 'surface-probe.json'] as const;
@@ -50,13 +51,7 @@ function _package_root(): string {
 }
 
 function _readStdinIfNotTty(): void {
-    try {
-        if (!process.stdin.isTTY) {
-            fs.readFileSync(0, 'utf-8');
-        }
-    } catch {
-        /* ignore */
-    }
+    readHookStdin();
 }
 
 function _exists(p: string): boolean {
@@ -209,7 +204,13 @@ export function main(argv?: string[], opts: ProbeOptions = {}): number {
     }
 }
 
+// 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;
     }