@event4u/agent-config 10.4.0 → 12.0.0

package/src/scripts/skill_linter.ts

@@ -254,6 +254,42 @@ const EXTERNAL_EXECUTION_HANDLERS = new Set(['shell', 'php', 'node']);
  * span lines and accept a bare key whose value sits somewhere below it.
  */
 const RUNTIME_REQUIRES_BLOCK_PATTERN = /^runtime_requires:[ \t]*(\{.*)?$/m;
+
+/**
+ * The deprecated free-text `compatibility:` key and its structured successor
+ * `harness_compat:`, both top-level. Anchored at column 0 so a `compatibility:`
+ * nested inside another block (or the word inside a quoted description) is not
+ * read as the frontmatter key — the same reason the neighbouring patterns above
+ * use `^` rather than a bare substring test. A value is required after the colon
+ * so a bare key with the value on the next line is not counted as a declaration.
+ */
+const COMPATIBILITY_KEY_PATTERN = /^compatibility:[ \t]*\S/m;
+const HARNESS_COMPAT_KEY_PATTERN = /^harness_compat:[ \t]*\S/m;
+
+/**
+ * `safety_mode: strict` is a claim made in the frontmatter about a skill whose
+ * execution path may mutate something. Nothing checked that the body honours it,
+ * so the claim could be pure metadata. These patterns recognise the two shapes
+ * the action-reference split allows (`skill-writing` § Action-reference split):
+ * an inline precondition that gates the write, or a deferral of the write-path
+ * steps into the skill's own `references/`.
+ *
+ * Deliberately a warning over a phrase list rather than an error over a required
+ * section: a skill that gates its write path some third way is doing the right
+ * thing, and a hard gate over a corpus of one strict skill would be a gate that
+ * mostly cannot fail — the defect class `road-to-skill-ecosystem-gate-integrity`
+ * exists to remove.
+ */
+const STRICT_WRITE_GATE_PATTERNS = [
+    /--dry-run/i,
+    /\bnever silent[- ]run/i,
+    /\bpropose,? never\b/i,
+    /\bconfirms? before\b/i,
+    /\bexplicit (?:user )?confirmation\b/i,
+    /\basks? (?:the user )?(?:first|before)\b/i,
+];
+const SKILL_REFERENCE_DEFERRAL_PATTERN = /\]\(\.{0,2}\/?references\//;
+
 const VALID_EXECUTION_FIELDS = new Set([
     'type',
     'handler',
@@ -1295,7 +1331,7 @@ function lint_wing4_boundaries(text: string): Issue[] {
  * for an optional parameter — a future caller that forgets it gets a confident
  * error about a declaration it never looked for.
  */
-function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string): Issue[] {
+function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string, body = ''): Issue[] {
     const issues: Issue[] = [];
 
     const execType = execution.type;
@@ -1370,6 +1406,29 @@ function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string)
         );
     }
 
+    // road-to-skill-ecosystem-executable-payloads Phase 5 — the action-reference
+    // split. A strict-mode skill either gates its write path inline, or says it
+    // does not define the mutating workflow and defers those steps to its own
+    // `references/` behind a precondition. Neither present → the strict claim is
+    // frontmatter only, and the body reads like an ordinary skill.
+    if (
+        safetyMode === 'strict' &&
+        body !== '' &&
+        !STRICT_WRITE_GATE_PATTERNS.some((p) => p.test(body)) &&
+        !SKILL_REFERENCE_DEFERRAL_PATTERN.test(body)
+    ) {
+        issues.push(
+            new Issue(
+                'warning',
+                'strict_mode_missing_write_gate',
+                "execution.safety_mode is 'strict' but the body names no precondition on the write " +
+                    'path and defers no write-path steps to the skill\'s references/ — state the gate ' +
+                    'inline (propose-then-confirm, --dry-run) or defer it, per skill-writing ' +
+                    '§ Action-reference split',
+            ),
+        );
+    }
+
     const timeout = execution.timeout_seconds;
     if (timeout !== undefined) {
         if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout <= 0) {
@@ -1583,9 +1642,30 @@ export function lint_skill(p: string, text: string, absPath: string | null = nul
             }
         }
 
+        // `compatibility:` is deprecated in favour of the structured
+        // `harness_compat:` (schema, 2026-08-14). The field is NOT removed — the
+        // schema still accepts it and both existing users still carry it — so this
+        // is a warning, not an error: its job is to stop NEW adoption during the
+        // window, which is the only thing a deprecation notice with no gate cannot
+        // do. Regex, not a YAML parse, to match the file's existing convention.
+        if (
+            COMPATIBILITY_KEY_PATTERN.test(frontmatter) &&
+            !HARNESS_COMPAT_KEY_PATTERN.test(frontmatter)
+        ) {
+            issues.push(
+                new Issue(
+                    'warning',
+                    'deprecated_compatibility_field',
+                    "Frontmatter declares the deprecated free-text 'compatibility:' without the structured " +
+                        "'harness_compat:' that supersedes it — add harness_compat (see skill.schema.json and " +
+                        'docs/MIGRATION.md § Scheduled deprecations); compatibility stays accepted until removal',
+                ),
+            );
+        }
+
         const execution = parseExecutionBlock(frontmatter);
         if (execution !== null) {
-            issues.push(...lint_execution_metadata(execution, frontmatter));
+            issues.push(...lint_execution_metadata(execution, frontmatter, text.replace(FRONTMATTER_PATTERN, '')));
         }
 
         const tierMatch = TIER_PATTERN.exec(frontmatter);

package/src/scripts/worktree_cleanup_check.ts

@@ -34,6 +34,7 @@ import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { read_live_records, register_dir } from './_lib/session_register.js';
 
 export interface CheckResult {
     allowed: boolean;
@@ -304,8 +305,20 @@ function isAncestor(repoPath: string, branch: string, trunk: string): boolean {
     }
 }
 
-export function isStandardLocation(repoPath: string, worktreePath: string): boolean {
-    const rel = path.relative(canonical(repoPath), canonical(worktreePath));
+/**
+ * `basePath` MUST be the main worktree, never the invoking repo path.
+ *
+ * Measured 2026-08-13, and the failure is total rather than partial: called with
+ * a linked worktree as the base, every sibling worktree resolves to `..` and the
+ * safe set collapses to empty. Same binary, same repo, same minute — from inside
+ * `.claude/worktrees/<branch>`: 304 registered, safe 0, 278 "non-standard"; from
+ * the main checkout: safe 181, 81 non-standard. A maintainer who ran the
+ * inventory from a worktree would read "nothing to clean" and conclude the
+ * estate was fine, which is the worst shape a cleanup tool can fail in — it
+ * fails silently, and toward inaction.
+ */
+export function isStandardLocation(basePath: string, worktreePath: string): boolean {
+    const rel = path.relative(canonical(basePath), canonical(worktreePath));
     if (rel.startsWith('..') || path.isAbsolute(rel)) return false;
     return STANDARD_WORKTREE_DIRS.some(
         (dir) => rel === dir || rel.startsWith(`${dir}${path.sep}`),
@@ -348,16 +361,70 @@ function lastGitActivity(worktreePath: string): Date | null {
  * Classify every worktree. `now` is injectable so the live-window boundary is
  * testable rather than wall-clock dependent.
  */
-export function buildInventory(repoPath: string, now: Date = new Date()): Inventory {
+/**
+ * Two conditions the `safe` predicate does NOT carry by default, both off unless
+ * asked for. They exist because an approval can be stricter than the tool, and
+ * silently removing under the looser predicate is the substitution such an
+ * approval is written to prevent.
+ *
+ * `minAgeDays` is a floor on git inactivity, layered ON TOP of the 48-hour live
+ * window rather than replacing it: 48h answers "is someone in it right now", a
+ * 60-day floor answers "is this abandoned". Different questions.
+ *
+ * `excludeLiveSessions` reads the session register — real records with a real
+ * `worktree` path and a real TTL — instead of inferring occupancy from file
+ * mtime, which this module's own header already rules out as a liveness signal.
+ */
+export interface InventoryOptions {
+    now?: Date;
+    minAgeDays?: number | null;
+    excludeLiveSessions?: boolean;
+}
+
+export function buildInventory(
+    repoPath: string,
+    nowOrOptions: Date | InventoryOptions = new Date(),
+): Inventory {
+    const opts: InventoryOptions =
+        nowOrOptions instanceof Date ? { now: nowOrOptions } : nowOrOptions;
+    const now = opts.now ?? new Date();
+    const minAgeDays = opts.minAgeDays ?? null;
+    const ageCutoff = minAgeDays === null ? null : now.getTime() - minAgeDays * 86400 * 1000;
+    return buildInventoryInner(repoPath, now, ageCutoff, minAgeDays, opts.excludeLiveSessions === true);
+}
+
+function buildInventoryInner(
+    repoPath: string,
+    nowArg: Date,
+    ageCutoff: number | null,
+    minAgeDays: number | null,
+    excludeLiveSessions: boolean,
+): Inventory {
+    const now = nowArg;
     const trunk = resolveTrunk(repoPath);
     const entries = listWorktrees(repoPath);
     const mainPath = canonical(entries.length > 0 ? entries[0]!.path : repoPath);
     const liveCutoff = now.getTime() - LIVE_WINDOW_HOURS * 3600 * 1000;
 
+    // Registered session worktrees, canonicalised so the comparison survives a
+    // symlinked checkout root the same way every other path here does. Empty set
+    // when the option is off, when no register directory exists (the normal
+    // state before any session registers), or when every record has expired.
+    const sessionPaths = new Set<string>();
+    if (excludeLiveSessions) {
+        const dir = register_dir(mainPath);
+        if (dir !== null) {
+            for (const rec of read_live_records(dir, { now })) {
+                sessionPaths.add(canonical(rec.worktree));
+            }
+        }
+    }
+
     const rows: InventoryRow[] = entries.map((e) => {
         const resolved = canonical(e.path);
         const isMain = resolved === mainPath;
-        const standardLocation = isMain ? true : isStandardLocation(repoPath, resolved);
+        // `mainPath`, NOT `repoPath` — see isStandardLocation's contract.
+        const standardLocation = isMain ? true : isStandardLocation(mainPath, resolved);
         const reasons: string[] = [];
 
         if (!fs.existsSync(resolved)) {
@@ -389,6 +456,20 @@ export function buildInventory(repoPath: string, now: Date = new Date()): Invent
         if (e.branch === null) {
             reasons.push('detached HEAD — no branch to judge reachability for');
         }
+        if (sessionPaths.has(resolved)) {
+            reasons.push('a live agent session is registered in this worktree');
+        }
+        if (ageCutoff !== null && (activity === null || activity.getTime() >= ageCutoff)) {
+            // `activity === null` disqualifies rather than passes: an unreadable
+            // git-dir mtime is absence of evidence, and under an explicit
+            // minimum-age floor that has to read as "cannot show it is old
+            // enough", never as "old enough".
+            reasons.push(
+                activity === null
+                    ? `git activity unreadable — cannot prove ${minAgeDays}+ days of inactivity`
+                    : `git activity within the last ${minAgeDays} days`,
+            );
+        }
         if (!standardLocation) {
             reasons.push('non-standard location — outside the conventional worktree roots');
         }
@@ -465,7 +546,7 @@ export function removalPlan(inv: Inventory): string[] {
 function usage(): never {
     process.stderr.write(
         'usage: worktree_cleanup_check check <worktree-path> | scope-overlap [repo-path] | ' +
-            'inventory [repo-path] [--json|--plan]\n',
+            'inventory [repo-path] [--json|--plan] [--min-age-days=N] [--exclude-live-sessions]\n',
     );
     process.exit(2);
 }
@@ -509,9 +590,32 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         const rest = argv.slice(1);
         const flags = rest.filter((a) => a.startsWith('--'));
         const positional = rest.filter((a) => !a.startsWith('--'));
-        if (positional.length > 1 || flags.some((f) => f !== '--json' && f !== '--plan')) usage();
+        const KNOWN = ['--json', '--plan', '--exclude-live-sessions'];
+        const ageFlag = flags.find((f) => f.startsWith('--min-age-days='));
+        if (
+            positional.length > 1 ||
+            flags.some((f) => !KNOWN.includes(f) && !f.startsWith('--min-age-days='))
+        ) {
+            usage();
+        }
+        let minAgeDays: number | null = null;
+        if (ageFlag !== undefined) {
+            const raw = ageFlag.slice('--min-age-days='.length);
+            const n = Number(raw);
+            // Refuse rather than silently fall back to null: a typo'd floor that
+            // reads as "no floor" would widen the safe set at exactly the moment
+            // the caller asked to narrow it.
+            if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+                process.stderr.write(`--min-age-days needs a non-negative integer, got '${raw}'\n`);
+                return 2;
+            }
+            minAgeDays = n;
+        }
         const repo = path.resolve(positional[0] ?? '.');
-        const inv = buildInventory(repo);
+        const inv = buildInventory(repo, {
+            minAgeDays,
+            excludeLiveSessions: flags.includes('--exclude-live-sessions'),
+        });
 
         if (flags.includes('--json')) {
             process.stdout.write(`${JSON.stringify(inv, null, 2)}\n`);

package/src/server/schemas/settings.ts

@@ -23,7 +23,6 @@ const accessStyle = z.enum(['getters_setters', 'get_attribute', 'magic_propertie
 const chatFreq = z.enum(['per_turn', 'per_phase', 'per_tool']);
 const qualityCadence = z.enum(['end_of_roadmap', 'per_phase', 'per_step']);
 const regenCadence = z.enum(['per_step', 'every_5_steps', 'phase_boundary']);
-const worktreeMode = z.enum(['off', 'on', 'ask']);
 const fidelityMode = z.enum(['strict', 'structural', 'hard-floor']);
 const crossSourceMode = z.enum(['on', 'auto', 'off']);
 const richSkillsMode = z.enum(['on', 'ask', 'off']);
@@ -351,11 +350,9 @@ export const settingsSchema = z.object({
             'Opt-in adversarial-verification-council mode (subagent-orchestration Mode 9, ADR-122). off (default) = never runs; ask = offer it on an explicit high-risk change; on = auto-run on high-risk changes. Advisory only — a panel of distinct-model skeptics red-teams a real change for defect FINDING coverage and NEVER auto-gates it (Hard Floor). Stays default-off until the adversarial-council-finding-coverage claim is backed.',
         ),
     }),
-    worktrees: z.object({
-        mode: worktreeMode.default('ask').describe(
-            'When the agent considers a parallel `git worktree` for risky / large work. ask (default) = surface a numbered option and wait. on = spawn worktrees autonomously. off = never use worktrees, edit in place.',
-        ),
-    }),
+    // `worktrees.mode` was DELETED (ADR-229). Worktree creation is
+    // instruction-only and hardcoded; there is nothing left to configure. A
+    // leftover key is ignored with one deprecation line via REMOVED_KEYS.
     ai_team: z.object({
         model: z.string().default('auto').describe(
             "Model handed to the codex CLI. 'auto' (default) = pass no --model flag so the CLI's own default applies — tracks the subscription's current strongest model instead of pinning a stale ID. Any other value passes through verbatim as `--model <value>`.",