@event4u/agent-config 7.5.0 → 8.1.0

package/src/scripts/janitor.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env tsx
+/**
+ * Janitor — retention sweep for volatile/TTL directories.
+ *
+ * Supported TTL directories (per docs/contracts/agents-layout.md):
+ *   agents/tmp.old/     — processed inbox archive (TTL: 30 days)
+ *   agents/runtime/     — volatile runtime artefacts (TTL: 7 days for council/tmp)
+ *
+ * NEVER auto-sweeps agents/tmp/ (user inbox — user-owned, no TTL).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/janitor          — dry-run report only
+ *   ./scripts-run src/scripts/janitor --apply  — delete expired files
+ *   ./scripts-run src/scripts/janitor --report — same as default (dry-run)
+ *
+ * Exit codes:
+ *   0 — report generated (dry-run) or sweep completed (--apply)
+ *   2 — invalid args
+ */
+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 REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
+
+// TTL configuration per directory (days)
+const TTL_CONFIG: ReadonlyArray<{ dir: string; ttlDays: number; description: string }> = [
+    {
+        dir: 'agents/tmp.old',
+        ttlDays: 30,
+        description: 'Processed inbox archive (consumed agents/tmp/ files)',
+    },
+    {
+        dir: 'agents/runtime/tmp',
+        ttlDays: 7,
+        description: 'Agent scratch / runtime tmp',
+    },
+    {
+        dir: 'agents/runtime/council/responses',
+        ttlDays: 7,
+        description: 'Council response cache',
+    },
+];
+
+// Directories that must NEVER be auto-swept
+const PROTECTED_DIRS: ReadonlySet<string> = new Set([
+    'agents/tmp',          // user inbox — user-owned, no TTL
+    'agents/knowledge',    // committed curated pages
+    'agents/memory',       // promotion pipeline (committed YAML)
+    'agents/decisions',    // permanent durable records
+    'agents/evidence',     // permanent durable evidence
+    'agents/roadmaps',     // tracked roadmaps
+]);
+
+interface FileStat {
+    relPath: string;
+    absPath: string;
+    ageDays: number;
+    size: number;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _walkFiles(dir: string): string[] {
+    const results: string[] = [];
+    if (!_isDir(dir)) return results;
+    for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const stat = fs.statSync(full);
+        if (stat.isFile()) {
+            results.push(full);
+        } else if (stat.isDirectory()) {
+            results.push(..._walkFiles(full));
+        }
+    }
+    return results;
+}
+
+function _ageDays(p: string): number {
+    try {
+        const stat = fs.statSync(p);
+        const ageMs = Date.now() - stat.mtimeMs;
+        return ageMs / (1000 * 60 * 60 * 24);
+    } catch {
+        return 0;
+    }
+}
+
+function _humanSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}kB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+function report(apply: boolean): void {
+    const now = new Date();
+    process.stdout.write(`\n🗂️  Janitor report — ${now.toISOString().slice(0, 10)}\n\n`);
+
+    // Inbox status (never swept, report only)
+    const inboxDir = path.join(REPO_ROOT, 'agents/tmp');
+    if (_isDir(inboxDir)) {
+        const files = _walkFiles(inboxDir);
+        if (files.length === 0) {
+            process.stdout.write(`✅  agents/tmp/ (user inbox) — empty\n`);
+        } else {
+            const oldest = files.map((f) => _ageDays(f)).reduce((a, b) => Math.max(a, b), 0);
+            const totalSize = files.reduce((s, f) => {
+                try { return s + fs.statSync(f).size; } catch { return s; }
+            }, 0);
+            process.stdout.write(
+                `📥  agents/tmp/ (user inbox) — ${files.length} file(s), ` +
+                    `oldest: ${oldest.toFixed(0)}d, size: ${_humanSize(totalSize)}\n` +
+                    `    (user-owned; never auto-swept)\n`,
+            );
+        }
+    }
+
+    process.stdout.write('\n');
+
+    // Harvest-local size note
+    const harvestDir = path.join(REPO_ROOT, 'agents/.harvest-local');
+    if (_isDir(harvestDir)) {
+        const files = _walkFiles(harvestDir);
+        const totalSize = files.reduce((s, f) => {
+            try { return s + fs.statSync(f).size; } catch { return s; }
+        }, 0);
+        process.stdout.write(
+            `📦  agents/.harvest-local/ — ${_humanSize(totalSize)} ` +
+                `(source-confidentiality evidence; retain, never auto-deleted)\n\n`,
+        );
+    }
+
+    let totalExpired = 0;
+    let totalSize = 0;
+
+    for (const { dir, ttlDays, description } of TTL_CONFIG) {
+        const absDir = path.join(REPO_ROOT, dir);
+        if (!_isDir(absDir)) continue;
+
+        // Safety: never sweep protected dirs
+        if (PROTECTED_DIRS.has(dir)) {
+            process.stdout.write(`🔒  ${dir} — protected, skipping\n`);
+            continue;
+        }
+
+        const files = _walkFiles(absDir);
+        const expired: FileStat[] = [];
+
+        for (const absPath of files) {
+            const ageDays = _ageDays(absPath);
+            if (ageDays >= ttlDays) {
+                let size = 0;
+                try { size = fs.statSync(absPath).size; } catch { /* */ }
+                expired.push({ relPath: path.relative(REPO_ROOT, absPath), absPath, ageDays, size });
+            }
+        }
+
+        if (files.length === 0) {
+            process.stdout.write(`✅  ${dir}/ — empty\n`);
+            continue;
+        }
+
+        const dirSize = files.reduce((s, f) => {
+            try { return s + fs.statSync(f).size; } catch { return s; }
+        }, 0);
+        process.stdout.write(
+            `📁  ${dir}/ — ${files.length} file(s), ${_humanSize(dirSize)} total, ` +
+                `TTL: ${ttlDays}d (${description})\n`,
+        );
+
+        if (expired.length === 0) {
+            process.stdout.write(`    ✅  No expired files.\n`);
+        } else {
+            const expiredSize = expired.reduce((s, f) => s + f.size, 0);
+            process.stdout.write(
+                `    ⚠️  ${expired.length} expired file(s), ${_humanSize(expiredSize)} reclaimable:\n`,
+            );
+            for (const f of expired.slice(0, 10)) {
+                process.stdout.write(
+                    `       ${f.relPath} (${f.ageDays.toFixed(0)}d old, ${_humanSize(f.size)})\n`,
+                );
+            }
+            if (expired.length > 10) {
+                process.stdout.write(`       … and ${expired.length - 10} more\n`);
+            }
+
+            if (apply) {
+                for (const f of expired) {
+                    try { fs.unlinkSync(f.absPath); } catch { /* ignore */ }
+                }
+                // Remove empty dirs
+                for (const f of expired) {
+                    let dir = path.dirname(f.absPath);
+                    while (dir.startsWith(absDir) && dir !== absDir) {
+                        try {
+                            if (fs.readdirSync(dir).length === 0) {
+                                fs.rmdirSync(dir);
+                            }
+                        } catch { /* */ }
+                        dir = path.dirname(dir);
+                    }
+                }
+                process.stdout.write(`    🗑️  Deleted ${expired.length} expired file(s).\n`);
+            } else {
+                process.stdout.write(
+                    `    → Run with --apply to delete. All files stay on disk in dry-run mode.\n`,
+                );
+            }
+
+            totalExpired += expired.length;
+            totalSize += expired.reduce((s, f) => s + f.size, 0);
+        }
+        process.stdout.write('\n');
+    }
+
+    if (!apply && totalExpired > 0) {
+        process.stdout.write(
+            `Total reclaimable: ${totalExpired} file(s), ${_humanSize(totalSize)}\n` +
+                `Run \`./scripts-run src/scripts/janitor --apply\` to delete.\n`,
+        );
+    } else if (apply && totalExpired > 0) {
+        process.stdout.write(`Total deleted: ${totalExpired} file(s), ${_humanSize(totalSize)} freed.\n`);
+    }
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(
+            'Usage: janitor [--apply] [--report]\n' +
+                '  (no flags)  — dry-run report\n' +
+                '  --report    — same as no flags\n' +
+                '  --apply     — delete expired files\n',
+        );
+        return 0;
+    }
+
+    const apply = args.includes('--apply');
+    report(apply);
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main, TTL_CONFIG, PROTECTED_DIRS };

package/src/scripts/lint_agents_layout.ts

@@ -14,7 +14,11 @@
  * uses the cwd-relative `agents/` root exactly as the Python does, so the
  * printed paths (`agents/<name>`) match byte-for-byte.
  *
- * No behaviour changes.
+ * Extended (road-to-agents-dir-and-gitignore-hygiene Phase 2.3):
+ * - In source-repo mode, unknown TOP-LEVEL DIRECTORIES also become errors.
+ *   Whitelist is ALLOWED_SOURCE_DIRS (see docs/contracts/agents-layout.md).
+ * - CONSUMER_EXPECTED_ENTRIES extended with the full consumer-scope subset
+ *   from the contract (knowledge/, memory/, roadmaps/, tmp/, tmp.old/).
  */
 
 import * as fs from 'node:fs';
@@ -33,12 +37,57 @@ const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     '.event4u-bridge.yml',
     '.agent-tools.yml',
     '.maintainer-workspace.md',
+    // Gitignored local-only files (present in working tree, never committed).
+    // NOTE: if any of these are tracked (appear in `git ls-files`), that is a
+    // separate violation caught by check_tracked_but_ignored.ts.
+    '.ai-video.xml',       // operator AI-video config; gitignored per .gitignore § AI Video
+    'installed-tools.lock', // installer per-user inventory; gitignored per ADR-020
+    '.event4u-bridge.yml',  // consumer bridge marker; ADR-020 (should only be in consumers)
+]);
+
+// All directories allowed at the agents/ root in the SOURCE REPO.
+// Entries marked (* consumer) are also allowed in consumer projects.
+// Contract: docs/contracts/agents-layout.md § Directory table.
+const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
+    'decisions',
+    'evidence',
+    'features',
+    'knowledge',    // * consumer
+    'memory',       // * consumer
+    'notes',        // legacy; new files go to evidence/notes/
+    'reports',      // legacy; new files go to evidence/reports/ (see agents-layout.md)
+    'overrides',    // * consumer
+    'recruit-sessions',
+    'reference',
+    'roadmap-assets',
+    'roadmaps',     // * consumer
+    'roles',
+    'runtime',      // local-only, gitignored
+    'settings',
+    'state',        // local-only, gitignored
+    'templates',
+    'tickets',
+    'tmp',          // local-only, gitignored (* consumer)
+    'tmp.old',      // local-only, gitignored (* consumer)
+    '.harvest-local', // local-only, gitignored
 ]);
 
 const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
+    // Required consumer entries
     'overrides',
     '.event4u-bridge.yml',
     '.gitkeep',
+    // Optional but legitimate consumer entries (will not trigger warnings)
+    'knowledge',
+    'memory',
+    'roadmaps',
+    'tmp',
+    'tmp.old',
+    // Flat files that are tracked in consumers
+    'index.md',
+    'roadmaps-progress.md',
+    '.agent-tools.yml',
+    '.maintainer-workspace.md',
 ]);
 
 const MIGRATE_HINT =
@@ -99,26 +148,35 @@ function is_source_repo(projectRoot: string): boolean {
     return false;
 }
 
-function find_violations(root: string): string[] {
+function find_violations(root: string, sourceRepo = false): string[] {
     const unknown: string[] = [];
     if (!_isDir(root)) {
         return unknown;
     }
     for (const p of _iterdirSorted(root)) {
-        if (!_isFile(p)) {
-            continue;
-        }
         const name = path.basename(p);
-        if (ALLOWED_FLAT_FILES.has(name)) {
-            continue;
+        if (_isFile(p)) {
+            if (ALLOWED_FLAT_FILES.has(name)) {
+                continue;
+            }
+            unknown.push(
+                `${p}: flat file not in agents/ whitelist — move to a typed ` +
+                    'subdirectory (runtime/, evidence/, decisions/, settings/, ' +
+                    'audits/, roadmaps/, policies/, contexts/, …) or add to ' +
+                    'ALLOWED_FLAT_FILES in scripts/lint_agents_layout.ts with ' +
+                    'rationale.',
+            );
+        } else if (_isDir(p) && sourceRepo) {
+            // In source-repo mode, unknown top-level directories are also errors.
+            // See docs/contracts/agents-layout.md § Directory table.
+            if (!ALLOWED_SOURCE_DIRS.has(name)) {
+                unknown.push(
+                    `${p}: unknown top-level directory in agents/ — ` +
+                        'add to ALLOWED_SOURCE_DIRS in lint_agents_layout.ts ' +
+                        '(with rationale) AND to docs/contracts/agents-layout.md.',
+                );
+            }
         }
-        unknown.push(
-            `${p}: flat file not in agents/ whitelist — move to a typed ` +
-                'subdirectory (runtime/, evidence/, decisions/, settings/, ' +
-                'audits/, roadmaps/, policies/, contexts/, …) or add to ' +
-                'ALLOWED_FLAT_FILES in scripts/lint_agents_layout.py with ' +
-                'rationale.',
-        );
     }
     return unknown;
 }
@@ -149,8 +207,8 @@ function main(argv?: readonly string[]): number {
     const quiet = args.includes('--quiet');
 
     const projectRoot = process.cwd();
-    const unknown = find_violations(AGENTS_ROOT);
     const consumerMode = !is_source_repo(projectRoot);
+    const unknown = find_violations(AGENTS_ROOT, !consumerMode);
     const warnings = consumerMode ? find_consumer_warnings(AGENTS_ROOT) : [];
 
     if (unknown.length > 0) {
@@ -196,6 +254,7 @@ if (_isCliEntry || process.argv[1] === _HERE) {
 export {
     AGENTS_ROOT,
     ALLOWED_FLAT_FILES,
+    ALLOWED_SOURCE_DIRS,
     CONSUMER_EXPECTED_ENTRIES,
     MIGRATE_HINT,
     is_source_repo,

package/src/scripts/lint_bench_ab.ts

@@ -32,7 +32,10 @@ const REQUIRED_SECTIONS = [
     // bench_ab_v2_stats.py --markdown). The v1 Headline/Track-A/Track-B/History
     // structure was retired with the v1 binary-capability frame.
     '## Honesty labels',
-    '## Gate verdict',
+    // Since the 2026-07 per-host split the verdict lives inside per-host h2
+    // headings ("## Weak host (…) — Gate verdict: **PASS**"), so match the
+    // verdict label rather than a standalone "## Gate verdict" section.
+    'Gate verdict:',
     '## Methodology',
 ] as const;
 

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -480,7 +480,7 @@
     {
       "file": ".agent-src.uncondensed/rules/architecture.md",
       "lines": [
-        71
+        69
       ],
       "reason": "Multi-framework module-system enumeration (Laravel, Turborepo, NestJS, Go) — comparative example, no project mandate"
     },
@@ -515,14 +515,14 @@
     {
       "file": ".agent-src.uncondensed/rules/architecture.md",
       "lines": [
-        76
+        74
       ],
       "reason": "Single Laravel-shape example showing how `{module_root}/*/{agent_folder}/` resolves on a Laravel HMVC project (road-to-configurable-modules Phase D)"
     },
     {
       "file": ".agent-src.uncondensed/rules/roadmap-ci-steps-policy.md",
       "lines": [
-        101
+        99
       ],
       "reason": "Single Laravel-shape example showing module-scoped roadmap path (road-to-configurable-modules Phase D)"
     },
@@ -598,6 +598,29 @@
         29
       ],
       "reason": "Cross-stack UI-stack enumeration (React, Blade, Tailwind)"
+    },
+    {
+      "file": "src/skills/code-review/SKILL.md",
+      "lines": [
+        79,
+        88,
+        90
+      ],
+      "reason": "Cross-stack security-review checklist rows naming Laravel/Symfony/NestJS/DTO peers side-by-side (allowed multi-ecosystem documentation, not a mandate)"
+    },
+    {
+      "file": "src/skills/context-document/SKILL.md",
+      "lines": [
+        83
+      ],
+      "reason": "Module-path resolution table citing the Laravel shape as one named example next to the generic modules.root_paths mechanism"
+    },
+    {
+      "file": "src/skills/verify-completion-evidence/SKILL.md",
+      "lines": [
+        183
+      ],
+      "reason": "Carve-out pointer to the quality-tools skill (the sanctioned one-line handoff shape from framework-neutrality-in-generic-skills)"
     }
   ]
 }