@event4u/agent-config 9.20.0 → 9.21.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/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,
-};

package/src/scripts/lint_workspace_boundary.ts

@@ -1,267 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Workspace-boundary drift check — import-edge enforcement.
- *
- * Ported from the retired Python `src/scripts/lint_workspace_boundary.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is pinned — the
- * `--quiet` flag, the `sorted(repo.glob(WORKSPACE_GLOB))` scan order (pathlib
- * component-wise), the FORBIDDEN-pattern set (Python `re` → JS `RegExp`, all
- * ASCII so a 1:1 translation), the `# boundary-exception:` pragma skip, the
- * per-violation message shape, and the exit codes (0 holds · 1 forbidden
- * import · 2 internal). snake_case is kept on the public surface.
- *
- * Governed by `docs/contracts/workspace-boundary.md` + ADR-095. Fails when a
- * workspace module (`src/cli/python/workspace_*.py`) imports an owner-module of
- * a domain the workspace does NOT own: skill design, profile/pack semantics,
- * video-provider logic, MCP-registry policy, analytics product strategy.
- *
- * Scope (read this before trusting a green run): this enforces **import edges
- * only**. Semantic drift — a workspace module that encodes profile-semantics or
- * analytics-product-strategy judgement without importing anything forbidden — is
- * NOT catchable here and stays doc-governance, enforced in review against the
- * contract. A green run is a supplement to boundary thinking, not a substitute.
- *
- * Allowed: stdlib, third-party deps, intra-workspace imports (`workspace_*`),
- * and any import line carrying a `# boundary-exception: <reason>` pragma.
- *
- * Usage:  python3 src/scripts/lint_workspace_boundary.py [--quiet]
- * Exit:   0 = boundary holds · 1 = a forbidden import was found · 2 = internal.
- *
- * --- Parity notes (ADR-200) ---
- *
- * - The Python source uses `ast.walk` to find every `ast.Import` /
- *   `ast.ImportFrom` at any nesting level and records `node.lineno`. The twin
- *   reproduces that with a small line scanner that recognises top-level AND
- *   indented `import …` / `from … import …` statements (matching the only
- *   shapes Python's grammar admits for these node types), yielding the same
- *   `(module, lineno)` pairs — `lineno` is the line of the `import` / `from`
- *   keyword, exactly as `ast` reports it. A parenthesized multi-line
- *   `from x import (\n…\n)` records the `from` line, like `ast`.
- * - `Path.read_text(encoding="utf-8")` → `fs.readFileSync(p, "utf-8")`; a
- *   decode/read error surfaces as the `unparseable` violation line (the Python
- *   path only hits this on `SyntaxError`, marked `pragma: no cover`).
- * - `process.exitCode` is set; `process.exit()` is never called.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const _HERE = fileURLToPath(import.meta.url);
-
-const WORKSPACE_GLOB = 'src/cli/python/workspace_*.py';
-const PRAGMA = 'boundary-exception:';
-
-// Owner-modules of the NOT-owned domains. Matched against each dotted segment
-// of an imported module name with segment boundaries, so `packaging` does not
-// trip `pack` and `workspace_skills` is handled by the intra-workspace allow.
-const FORBIDDEN: ReadonlyArray<readonly [RegExp, string]> = [
-    [/(?:^|[._-])condense(?:$|[._-])/, 'skill design / condensation'],
-    [/(?:^|[._-])skill_linter(?:$|[._-])/, 'skill design'],
-    [/(?:^|[._-])skill_management(?:$|[._-])/, 'skill design'],
-    [/(?:^|[._-])skill_writing(?:$|[._-])/, 'skill design'],
-    [/(?:^|[._-])discovery_manifest(?:$|[._-])/, 'profile/pack semantics'],
-    [/(?:^|[._-])(?:profiles?|packs?)(?:$|[._-])/, 'profile/pack semantics'],
-    [/ai[_-]?video/, 'video-provider logic'],
-    [/(?:^|[._-])mcp(?:$|[._-])/, 'MCP-registry policy'],
-    [/(?:^|[._-])router(?:$|[._-])/, 'router / projection policy'],
-    [/(?:^|[._-])persona/, 'persona / skill design'],
-];
-
-function _is_intra_workspace(module: string): boolean {
-    const head = module.split('.', 1)[0] as string;
-    return head === 'workspace' || head.startsWith('workspace_');
-}
-
-function _forbidden_reason(module: string): string | null {
-    if (_is_intra_workspace(module)) {
-        return null;
-    }
-    for (const [pat, reason] of FORBIDDEN) {
-        if (pat.test(module)) {
-            return reason;
-        }
-    }
-    return null;
-}
-
-/**
- * Yield `[module_name, lineno]` for every import in `src`, mirroring
- * `ast.walk` over `ast.Import` / `ast.ImportFrom`.
- *
- * `ast` reports the keyword line as `lineno` (1-based). `ast.Import` for
- * `import a.b, c` yields one entry per alias, all on the same line; the module
- * name is the dotted path. `ast.ImportFrom` yields one entry: `node.module`
- * (the dotted module after `from`, `None` for `from . import x`).
- */
-function* _imported_modules(src: string): Generator<[string, number]> {
-    const lines = src.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        const raw = lines[i] as string;
-        const stripped = raw.replace(/^[ \t\f\v]+/, '');
-        const lineno = i + 1;
-
-        // from <module> import …  — module is the dotted path after `from`.
-        // `from . import x` / `from .pkg import y` → ast.module is the part
-        // after leading dots (or None). The leading-dot (relative) form has
-        // module = the text after the dots; a bare `from . import` has
-        // module=None and is skipped (no name to test).
-        const fromMatch = /^from[ \t]+(\.*)([A-Za-z_][\w.]*)?[ \t]+import\b/.exec(stripped);
-        if (fromMatch) {
-            const mod = fromMatch[2];
-            if (mod !== undefined) {
-                yield [mod, lineno];
-            }
-            continue;
-        }
-
-        // import a, b.c, d as e  — one alias per dotted name; ast records the
-        // dotted name (`alias.name`), all on this single keyword line.
-        const importMatch = /^import[ \t]+(.+)$/.exec(stripped);
-        if (importMatch) {
-            // Strip a trailing comment, then split on commas; for each clause
-            // take the dotted module name before any `as` alias.
-            let body = importMatch[1] as string;
-            const hash = body.indexOf('#');
-            if (hash >= 0) {
-                body = body.slice(0, hash);
-            }
-            for (const clause of body.split(',')) {
-                const name = clause.trim().split(/[ \t]+as[ \t]+/)[0]?.trim();
-                if (name) {
-                    yield [name, lineno];
-                }
-            }
-        }
-    }
-}
-
-function check_file(p: string): string[] {
-    let src: string;
-    try {
-        src = fs.readFileSync(p, { encoding: 'utf-8' });
-    } catch (exc) {
-        // pragma: no cover — mirrors the Python SyntaxError path.
-        return [`${p}: unparseable (${(exc as Error).message})`];
-    }
-    const lines = src.split('\n');
-    const out: string[] = [];
-    for (const [module, lineno] of _imported_modules(src)) {
-        const reason = _forbidden_reason(module);
-        if (reason === null) {
-            continue;
-        }
-        const line = lineno > 0 && lineno <= lines.length ? (lines[lineno - 1] as string) : '';
-        if (line.includes(PRAGMA)) {
-            continue; // reviewed, deliberate exception
-        }
-        out.push(
-            `${path.basename(p)}:${lineno}: imports \`${module}\` ` +
-                `(not-owned domain: ${reason})`,
-        );
-    }
-    return out;
-}
-
-/** `sorted(repo.glob("src/cli/python/workspace_*.py"))` — pathlib order. */
-function _globWorkspaceSorted(repo: string): string[] {
-    const dir = path.join(repo, 'src', 'cli', 'python');
-    let entries: string[];
-    try {
-        entries = fs.readdirSync(dir);
-    } catch {
-        return [];
-    }
-    const out: string[] = [];
-    for (const name of entries) {
-        if (name.startsWith('workspace_') && name.endsWith('.py')) {
-            const full = path.join(dir, name);
-            try {
-                if (fs.statSync(full).isFile()) {
-                    out.push(full);
-                }
-            } catch {
-                // ignore
-            }
-        }
-    }
-    out.sort();
-    return out;
-}
-
-function main(argv: readonly string[]): number {
-    const quiet = argv.includes('--quiet');
-    // Path(__file__).resolve().parent.parent.parent — src/scripts → repo root.
-    const repo = path.resolve(path.dirname(_HERE), '..', '..');
-    const files = _globWorkspaceSorted(repo);
-    if (files.length === 0) {
-        process.stdout.write(
-            `⚠️  lint-workspace-boundary: no files match ${WORKSPACE_GLOB}\n`,
-        );
-        return 0;
-    }
-    const violations: string[] = [];
-    for (const f of files) {
-        violations.push(...check_file(f));
-    }
-    if (violations.length) {
-        process.stdout.write(
-            '❌  Workspace-boundary violation(s) — a workspace module imports ' +
-                'an owner-module of a domain the workspace does NOT own ' +
-                '(docs/contracts/workspace-boundary.md):\n',
-        );
-        for (const v of violations) {
-            process.stdout.write(`  🔴 ${v}\n`);
-        }
-        process.stdout.write(
-            '\nFix: move the logic to the owning surface and consume its ' +
-                'output, or add `# boundary-exception: <reason>` if the import is ' +
-                'genuinely justified (reviewed like any boundary change).\n',
-        );
-        return 1;
-    }
-    if (!quiet) {
-        process.stdout.write(
-            `✅  Workspace boundary holds — ${files.length} module(s), ` +
-                'no forbidden imports.\n',
-        );
-    }
-    return 0;
-}
-
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    // A symlinked invocation (e.g. via an installed `.augment/` projection,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the
-    // symlink path. Compare realpaths so the entry guard still fires
-    // (without this the CLI silently no-ops when run through a symlink).
-    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.argv[1] === _HERE) {
-    process.exitCode = main(process.argv.slice(2));
-}
-
-export {
-    WORKSPACE_GLOB,
-    PRAGMA,
-    FORBIDDEN,
-    _is_intra_workspace,
-    _forbidden_reason,
-    _imported_modules,
-    check_file,
-    main,
-};