@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/skill_usage_collect.ts

@@ -25,6 +25,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/skill_usage_collect.ts → parents[2] of the .py file is repo root.
@@ -405,6 +407,25 @@ export function main(argv: string[] | null = null): number {
         return 0;
     }
     const known = load_known_slugs(REPO);
+    // The asserted unit is the in-repo slug vocabulary, not the session files
+    // above: sessions live under $HOME and are legitimately absent on a fresh
+    // clone or in CI (handled by the early return), whereas a vanished skills
+    // projection silently degrades every mention to the path-regex subset and
+    // still reports a successful collection.
+    try {
+        assertScanned({
+            gate: 'skill_usage_collect',
+            scanned: known.size,
+            units: 'known skill slug(s)',
+            roots: ['.augment/skills', '.claude/skills', 'dist/agent-src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const seen = new Set<string>();
     fs.mkdirSync(path.dirname(args.out), { recursive: true });
     if (fs.existsSync(args.out)) {

package/src/scripts/skill_usage_report.ts

@@ -18,6 +18,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_usage_report.py)
 // is the repo root — two dirs up from src/scripts.
@@ -332,6 +334,25 @@ export function main(argv?: string[]): number {
     const now = new Date();
     const per = aggregate(records, now, args.window);
     const known = all_known_slugs(REPO);
+    // Same split as `skill_usage_collect`: the JSONL is legitimately empty
+    // before any turn is recorded, but a vanished skills projection makes the
+    // report list only the slugs that happen to appear in the metrics — and a
+    // report certifying over nothing is the same lie in a quieter voice.
+    try {
+        assertScanned({
+            gate: 'skill_usage_report',
+            scanned: known.size,
+            units: 'known skill slug(s)',
+            roots: ['.augment/skills', '.claude/skills', 'dist/agent-src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 is the only non-zero code this CLI has (argparse errors).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     fs.mkdirSync(path.dirname(args.out), { recursive: true });
     fs.writeFileSync(args.out, render(per, known), 'utf-8');
     if (!args.quiet) {

package/src/scripts/sweep_dead_scan_roots.ts

@@ -103,6 +103,7 @@ import { fileURLToPath } from 'node:url';
 
 import * as agentSrc from './_lib/agent_src.js';
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { matchesGatePattern } from './_lib/gate_population.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
@@ -110,8 +111,15 @@ const DEFAULT_SCRIPTS = path.join(REPO, 'src', 'scripts');
 const DEFAULT_LEDGER = path.join(REPO, 'agents', 'evidence', 'sweep-dispositions.json');
 const LEDGER_CAP = 15;
 
-/** Population: the gate-name prefix convention the census uses. */
-const GATE_RE = /^(lint|audit|check|verify)_.*\.ts$/;
+/**
+ * Population: shared with the ratchet and the registration test.
+ *
+ * This file used to carry its own `(lint|audit|check|verify)_` regex and the
+ * three sites disagreed — 223 / 225 / 232 gates. Reading one definition is what
+ * makes "the census covers every gate the ratchet counts" a fact rather than a
+ * hope; see `_lib/gate_population.ts` for what the filter deliberately includes.
+ */
+const isGateFile = matchesGatePattern;
 
 /** Identifiers accepted as a repo-root base for a literal join. */
 const BASE_IDS: ReadonlySet<string> = new Set([
@@ -806,7 +814,7 @@ export function main(argv: string[]): number {
     }
 
     const pop = fs.existsSync(args.scripts)
-        ? fs.readdirSync(args.scripts).filter((f) => GATE_RE.test(f)).sort()
+        ? fs.readdirSync(args.scripts).filter(isGateFile).sort()
         : [];
     // Census needs every gate's roots; the finding report needs only the ones
     // with hits. Keep both, and filter at the point of use rather than dropping

package/src/scripts/verify_physical_move.ts

@@ -25,6 +25,7 @@ import {
     _SKIP_NAMES,
     type Snapshot,
 } from './snapshot_agent_outputs.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -362,6 +363,29 @@ export function main(argv: string[] | null = null): number {
     const before = JSON.parse(fs.readFileSync(args.snapshot, 'utf-8')) as Obj;
     const after: Snapshot = _build_snapshot();
 
+    // The live half of the comparison. If both projection trees are gone the
+    // diff has nothing to disagree about and the gate reports "byte-identity
+    // OK — 0 files". Summed rather than asserted per tree: a worktree that
+    // never had `.augment` generated is a normal state, an empty BOTH is not.
+    // Exit 2 is the existing "an input is not there" code (snapshot-missing
+    // above); 1 stays "a regression was found".
+    try {
+        assertScanned({
+            gate: 'verify_physical_move',
+            scanned:
+                Object.keys(after.trees['dist/agent-src'] ?? {}).length +
+                Object.keys(after.trees['.augment'] ?? {}).length,
+            units: 'projected file(s)',
+            roots: ['dist/agent-src', '.augment'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`ERROR: ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     _normalise_loaded_snapshot(before);
 
     const beforeTrees = _asObj(before['trees']) ?? {};

package/src/scripts/worktree_cleanup_check.ts

@@ -16,11 +16,18 @@
  *   scope-overlap           Scan every worktree's .worktree-scope.md and
  *                           report pairwise `owns:` overlaps (the hazard
  *                           /worktree status + verify must surface).
+ *   inventory               Classify EVERY worktree safe / review / live and
+ *                           report the counts, the review reasons, and a
+ *                           prepared removal plan for the safe set. Reporting
+ *                           only — it never removes anything, because bulk
+ *                           worktree + branch deletion is a Hard-Floor action
+ *                           (`non-destructive-by-default`) that needs the
+ *                           user's explicit this-turn approval.
  *
  * Reachability counts ALL other refs — local branches, remotes, AND tags
  * (a branch whose only other ref is a tag is still reachable elsewhere).
- * Exit codes: 0 = allowed / no overlap, 1 = refused / overlap found,
- * 2 = usage error, 3 = internal error.
+ * Exit codes: 0 = allowed / no overlap / inventory reported, 1 = refused /
+ * overlap found, 2 = usage error, 3 = internal error.
  */
 
 import { execFileSync } from 'node:child_process';
@@ -53,6 +60,17 @@ function tryGit(cwd: string, args: string[]): string | null {
     }
 }
 
+/**
+ * `git status` with the index left alone. Plain `git status` refreshes the
+ * on-disk index, which bumps its mtime — and the inventory mode reads that
+ * mtime as the "another session is working here" signal. Without
+ * `--no-optional-locks` the check corrupts the very signal it is measured
+ * against: two consecutive inventory runs moved 10 worktrees from safe to live.
+ */
+function statusPorcelain(cwd: string): string {
+    return git(cwd, ['--no-optional-locks', 'status', '--porcelain']);
+}
+
 /** Refs (heads + remotes + tags) EXCLUDING the given branch's own head ref. */
 function otherRefs(cwd: string, branch: string): string[] {
     const out = git(cwd, ['for-each-ref', '--format=%(refname)']);
@@ -77,7 +95,7 @@ export function checkWorktree(worktreePath: string): CheckResult {
     }
     const branch = headRef.trim().replace(/^refs\/heads\//, '');
 
-    const status = git(worktreePath, ['status', '--porcelain']);
+    const status = statusPorcelain(worktreePath);
     if (status.trim().length > 0) {
         const files = status
             .trimEnd()
@@ -194,9 +212,260 @@ export function findScopeOverlaps(repoPath: string): ScopeOverlap[] {
     return overlaps;
 }
 
+/**
+ * A worktree is "live" when another session may be working in it. Git touches
+ * the per-worktree index on almost every command, so its mtime is the cheapest
+ * available activity signal.
+ */
+export const LIVE_WINDOW_HOURS = 48;
+
+/**
+ * The two conventional worktree roots, relative to the repo. Anything else is
+ * a non-standard location: it is not wrong, but it is excluded from the safe
+ * set on purpose — worktrees that sit beside the repo can be mistaken for
+ * sibling packages, so their removal is a judgement the maintainer makes.
+ */
+export const STANDARD_WORKTREE_DIRS = ['.claude/worktrees', '.worktrees'] as const;
+
+/**
+ * Symlink-resolved absolute path, falling back to a plain resolve when the
+ * path is gone. Git reports worktree paths as realpaths, so a repo reached
+ * through a symlinked parent (`/tmp` → `/private/tmp` on macOS, or any
+ * symlinked checkout root) would otherwise fail every path comparison and
+ * mis-report conventional worktrees as non-standard.
+ */
+function canonical(p: string): string {
+    const abs = path.resolve(p);
+    const tail: string[] = [];
+    let head = abs;
+    for (;;) {
+        try {
+            // Resolve the longest existing ancestor, then re-append the rest —
+            // a registration pointing at an already-deleted directory still has
+            // to classify its location correctly.
+            const real = fs.realpathSync(head);
+            return tail.length === 0 ? real : path.join(real, ...tail);
+        } catch {
+            const parent = path.dirname(head);
+            if (parent === head) return abs;
+            tail.unshift(path.basename(head));
+            head = parent;
+        }
+    }
+}
+
+export type Classification = 'safe' | 'review' | 'live';
+
+export interface InventoryRow {
+    path: string;
+    branch: string | null;
+    classification: Classification;
+    /** Why it is not safe. Empty exactly when `classification === 'safe'`. */
+    reasons: string[];
+    /** The branch is an ancestor of the trunk, so `git branch -d` is safe. */
+    mergedIntoTrunk: boolean;
+    standardLocation: boolean;
+    /** Main worktree — never removable, and never counted as residue. */
+    isMain: boolean;
+}
+
+export interface Inventory {
+    trunk: string;
+    rows: InventoryRow[];
+    counts: {
+        total: number;
+        safe: number;
+        review: number;
+        live: number;
+        /** Review rows grouped by reason, highest first. */
+        reviewReasons: Record<string, number>;
+    };
+}
+
+/** First existing trunk ref, preferring the remote (the merge authority). */
+export function resolveTrunk(repoPath: string): string {
+    for (const ref of [
+        'refs/remotes/origin/main',
+        'refs/remotes/origin/master',
+        'refs/heads/main',
+        'refs/heads/master',
+    ]) {
+        if (tryGit(repoPath, ['rev-parse', '--verify', '--quiet', ref]) !== null) return ref;
+    }
+    return 'HEAD';
+}
+
+function isAncestor(repoPath: string, branch: string, trunk: string): boolean {
+    try {
+        git(repoPath, ['merge-base', '--is-ancestor', branch, trunk]);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function isStandardLocation(repoPath: string, worktreePath: string): boolean {
+    const rel = path.relative(canonical(repoPath), canonical(worktreePath));
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return false;
+    return STANDARD_WORKTREE_DIRS.some(
+        (dir) => rel === dir || rel.startsWith(`${dir}${path.sep}`),
+    );
+}
+
+/**
+ * Per-worktree git-dir mtime, or null when it cannot be read. A linked
+ * worktree's `.git` is a file holding `gitdir: <path>`; the main worktree's is
+ * a directory.
+ */
+function lastGitActivity(worktreePath: string): Date | null {
+    const dotGit = path.join(worktreePath, '.git');
+    let gitDir: string;
+    try {
+        const st = fs.statSync(dotGit);
+        if (st.isDirectory()) {
+            gitDir = dotGit;
+        } else {
+            const m = fs.readFileSync(dotGit, 'utf-8').match(/^gitdir:\s*(.+)$/m);
+            if (!m) return null;
+            gitDir = path.resolve(worktreePath, m[1]!.trim());
+        }
+    } catch {
+        return null;
+    }
+    let newest: number | null = null;
+    for (const name of ['index', 'HEAD']) {
+        try {
+            const t = fs.statSync(path.join(gitDir, name)).mtimeMs;
+            if (newest === null || t > newest) newest = t;
+        } catch {
+            /* absent is not an error — the other candidate may still exist */
+        }
+    }
+    return newest === null ? null : new Date(newest);
+}
+
+/**
+ * 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 {
+    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;
+
+    const rows: InventoryRow[] = entries.map((e) => {
+        const resolved = canonical(e.path);
+        const isMain = resolved === mainPath;
+        const standardLocation = isMain ? true : isStandardLocation(repoPath, resolved);
+        const reasons: string[] = [];
+
+        if (!fs.existsSync(resolved)) {
+            return {
+                path: e.path,
+                branch: e.branch,
+                classification: 'review',
+                reasons: ['registration points at a missing directory — `git worktree prune` clears it'],
+                mergedIntoTrunk: false,
+                standardLocation,
+                isMain,
+            };
+        }
+
+        const activity = lastGitActivity(resolved);
+        if (activity !== null && activity.getTime() >= liveCutoff) {
+            return {
+                path: e.path,
+                branch: e.branch,
+                classification: 'live',
+                reasons: [`git activity within the last ${LIVE_WINDOW_HOURS}h — another session may hold it`],
+                mergedIntoTrunk: e.branch !== null && isAncestor(resolved, e.branch, trunk),
+                standardLocation,
+                isMain,
+            };
+        }
+
+        if (isMain) reasons.push('main worktree — cannot be removed');
+        if (e.branch === null) {
+            reasons.push('detached HEAD — no branch to judge reachability for');
+        }
+        if (!standardLocation) {
+            reasons.push('non-standard location — outside the conventional worktree roots');
+        }
+
+        const mergedIntoTrunk = e.branch !== null && isAncestor(resolved, e.branch, trunk);
+
+        // A branch that is an ancestor of the trunk has every commit reachable
+        // from the trunk ref, so the expensive rev-list gate cannot find a
+        // unique commit. Only run it for the branches that are NOT merged —
+        // that is where it can actually refuse.
+        if (e.branch !== null && !mergedIntoTrunk) {
+            reasons.push(`branch is not an ancestor of ${trunk} — unmerged work`);
+            const gate = checkWorktree(resolved);
+            if (!gate.allowed) reasons.push(...gate.reasons);
+        } else if (e.branch !== null) {
+            const status = statusPorcelain(resolved);
+            if (status.trim().length > 0) {
+                const n = status.trimEnd().split('\n').length;
+                reasons.push(`unsaved work — ${n} dirty or untracked path(s)`);
+            }
+        }
+
+        return {
+            path: e.path,
+            branch: e.branch,
+            classification: reasons.length === 0 ? 'safe' : 'review',
+            reasons,
+            mergedIntoTrunk,
+            standardLocation,
+            isMain,
+        };
+    });
+
+    const reviewReasons: Record<string, number> = {};
+    for (const r of rows) {
+        if (r.classification !== 'review') continue;
+        // Group by the first reason: it is the primary disqualifier, and the
+        // per-row reasons stay available in --json for the full picture.
+        const key = (r.reasons[0] ?? 'unknown').split('\n')[0]!;
+        reviewReasons[key] = (reviewReasons[key] ?? 0) + 1;
+    }
+
+    return {
+        trunk,
+        rows,
+        counts: {
+            total: rows.length,
+            safe: rows.filter((r) => r.classification === 'safe').length,
+            review: rows.filter((r) => r.classification === 'review').length,
+            live: rows.filter((r) => r.classification === 'live').length,
+            reviewReasons: Object.fromEntries(
+                Object.entries(reviewReasons).sort((a, b) => b[1] - a[1]),
+            ),
+        },
+    };
+}
+
+/**
+ * The removal commands for the safe set — printed for a human to review and
+ * run, never executed here. `git branch -d` (never `-D`) so git itself
+ * re-checks the merge before the branch goes.
+ */
+export function removalPlan(inv: Inventory): string[] {
+    return inv.rows
+        .filter((r) => r.classification === 'safe')
+        .map((r) => {
+            const remove = `git worktree remove ${JSON.stringify(r.path)}`;
+            return r.branch !== null && r.mergedIntoTrunk
+                ? `${remove} && git branch -d ${JSON.stringify(r.branch)}`
+                : remove;
+        });
+}
+
 function usage(): never {
     process.stderr.write(
-        'usage: worktree_cleanup_check check <worktree-path> | scope-overlap [repo-path]\n',
+        'usage: worktree_cleanup_check check <worktree-path> | scope-overlap [repo-path] | ' +
+            'inventory [repo-path] [--json|--plan]\n',
     );
     process.exit(2);
 }
@@ -236,6 +505,52 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         }
         return 1;
     }
+    if (mode === 'inventory') {
+        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 repo = path.resolve(positional[0] ?? '.');
+        const inv = buildInventory(repo);
+
+        if (flags.includes('--json')) {
+            process.stdout.write(`${JSON.stringify(inv, null, 2)}\n`);
+            return 0;
+        }
+        if (flags.includes('--plan')) {
+            const plan = removalPlan(inv);
+            if (plan.length === 0) {
+                process.stdout.write('# no safe worktrees — nothing to propose.\n');
+                return 0;
+            }
+            process.stdout.write(
+                `# Prepared removal plan for ${plan.length} safe worktree(s).\n` +
+                    '# NOT executed: bulk worktree + branch deletion is a Hard-Floor action that\n' +
+                    '# needs the maintainer\'s explicit approval. Review, then run deliberately.\n',
+            );
+            process.stdout.write(`${plan.join('\n')}\n`);
+            return 0;
+        }
+
+        const c = inv.counts;
+        process.stdout.write(
+            `worktree inventory · ${c.total} registered · trunk ${inv.trunk}\n` +
+                `  safe    ${c.safe}\n` +
+                `  review  ${c.review}\n` +
+                `  live    ${c.live}\n`,
+        );
+        if (c.review > 0) {
+            process.stdout.write('\nreview reasons (primary disqualifier):\n');
+            for (const [reason, n] of Object.entries(c.reviewReasons)) {
+                process.stdout.write(`  ${String(n).padStart(4)}  ${reason}\n`);
+            }
+        }
+        process.stdout.write(
+            '\nThis mode reports only. `--plan` prints the removal commands for the safe set;\n' +
+                'running them is a Hard-Floor action needing the maintainer\'s explicit approval.\n',
+        );
+        return 0;
+    }
     usage();
 }
 

package/src/scripts/check_bite_sized_granularity.ts

@@ -1,116 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Bite-sized task granularity gate for structural roadmaps (P1.5).
- *
- * Ported from the retired Python `src/scripts/check_bite_sized_granularity.py` (ADR-200,
- * Phase 4 / Wave 4c). This module is a pure library (no CLI / main); the
- * Python module is imported as a test surface. The exported API mirrors the
- * Python public API EXACTLY:
- *
- *     read_complexity(text)   -> 'structural' | 'lightweight' | null
- *     scan_placeholders(text) -> Placeholder[]
- *     check_granularity(text) -> Result(complexity, gated, violations)
- *
- * `gated` is true only when `complexity === 'structural'`. Violations are
- * empty when the gate is not active, regardless of placeholder presence.
- * No behaviour changes — placeholder patterns, frontmatter slice, and the
- * task-bullet prefixes are replicated.
- */
-
-// Placeholder patterns in (kind, regex) order. Mirrors Python re flags:
-// IGNORECASE for the angle/tbd patterns. JS uses `i`. The angle pattern
-// is global-less here; we use `.test()` per line (re.search semantics).
-const PLACEHOLDER_PATTERNS: ReadonlyArray<[string, RegExp]> = [
-    ['angle-placeholder', /<[a-z][a-z0-9 _\-/]*>/i],
-    ['todo', /\bTODO\b/],
-    ['fixme', /\bFIXME\b/],
-    ['xxx', /\bXXX\b/],
-    ['tbd', /\btbd\b/i],
-    ['triple-question', /\?\?\?/],
-];
-
-const COMPLEXITY_PAT = /^complexity:\s*(lightweight|structural)\s*$/m;
-
-interface Placeholder {
-    kind: string;
-    line: number;
-    text: string;
-}
-
-interface Result {
-    complexity: string | null;
-    gated: boolean;
-    violations: Placeholder[];
-}
-
-function _frontmatter(text: string): string {
-    if (!text.startsWith('---\n')) {
-        return '';
-    }
-    const end = text.indexOf('\n---\n', 4);
-    return end !== -1 ? text.slice(4, end) : '';
-}
-
-function read_complexity(text: string): string | null {
-    const fm = _frontmatter(text);
-    if (fm === '') {
-        return null;
-    }
-    const m = COMPLEXITY_PAT.exec(fm);
-    return m ? m[1]! : null;
-}
-
-const _TASK_PREFIXES = ['- [ ]', '- [x]', '- [/]', '- [-]'];
-
-/** Mirror Python `str.lstrip()` — strip leading whitespace (incl. tabs). */
-function _lstrip(s: string): string {
-    return s.replace(/^\s+/, '');
-}
-
-/** Mirror Python `str.rstrip()` — strip trailing whitespace. */
-function _rstrip(s: string): string {
-    return s.replace(/\s+$/, '');
-}
-
-function scan_placeholders(text: string): Placeholder[] {
-    const hits: Placeholder[] = [];
-    const lines = text.split('\n');
-    for (let idx = 0; idx < lines.length; idx++) {
-        const line_no = idx + 1;
-        const line = lines[idx]!;
-        const stripped = _lstrip(line);
-        if (!_TASK_PREFIXES.some((p) => stripped.startsWith(p))) {
-            continue;
-        }
-        for (const [kind, pat] of PLACEHOLDER_PATTERNS) {
-            if (pat.test(line)) {
-                hits.push({ kind, line: line_no, text: _rstrip(line) });
-                break;
-            }
-        }
-    }
-    return hits;
-}
-
-function check_granularity(text: string): Result {
-    const complexity = read_complexity(text);
-    const gated = complexity === 'structural';
-    if (!gated) {
-        return { complexity, gated: false, violations: [] };
-    }
-    return {
-        complexity,
-        gated: true,
-        violations: scan_placeholders(text),
-    };
-}
-
-export {
-    type Placeholder,
-    type Result,
-    PLACEHOLDER_PATTERNS,
-    COMPLEXITY_PAT,
-    read_complexity,
-    scan_placeholders,
-    check_granularity,
-};