@event4u/agent-config 7.4.0 → 8.0.0

package/src/scripts/check_generated_artefact_headers.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env tsx
+/**
+ * CI gate: every regenerable tracked analysis artefact must carry the
+ * freshness marker `<!-- analyzed: date | commit: sha | files: N -->` in
+ * its first 5 lines.
+ *
+ * Missing marker = warning (the file may not have been regenerated recently).
+ * Missing marker on a file whose generator is known to write it = error.
+ *
+ * Exit codes:
+ *   0 — all artefacts carry the marker
+ *   1 — one or more artefacts are missing the marker
+ */
+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), '..', '..');
+
+// Artefacts that must carry the <!-- analyzed: … --> freshness marker.
+// Source: scripts that write these files (inventory_meta_layers.ts, audit_auto_rules.ts).
+// Add new entries here when a new generator is wired in.
+const GENERATED_ARTEFACTS: ReadonlyArray<{ path: string; writer: string; severity: 'error' | 'warning' }> = [
+    {
+        path: 'agents/evidence/analysis/meta-layer-inventory.md',
+        writer: 'inventory_meta_layers.ts',
+        severity: 'error',
+    },
+    {
+        path: 'agents/reports/auto-rules-audit.md',
+        writer: 'audit_auto_rules.ts',
+        severity: 'warning', // on-demand regen only; marker present after first re-run
+    },
+    {
+        path: 'agents/evidence/metrics/skill-usage-report.md',
+        writer: 'skill_overlap.ts / audit_skill_overlap.ts',
+        severity: 'warning',
+    },
+];
+
+const MARKER_PATTERN = /<!--\s*analyzed:\s*\d{4}-\d{2}-\d{2}/;
+
+function checkFile(p: string): boolean {
+    try {
+        const text = fs.readFileSync(p, 'utf-8');
+        const first5 = text.split('\n').slice(0, 5).join('\n');
+        return MARKER_PATTERN.test(first5);
+    } catch {
+        return true; // file doesn't exist locally (gitignored context) — skip
+    }
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const quiet = args.includes('--quiet');
+
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    for (const entry of GENERATED_ARTEFACTS) {
+        const absPath = path.join(REPO_ROOT, entry.path);
+        if (!fs.existsSync(absPath)) continue; // not present locally — skip
+
+        if (!checkFile(absPath)) {
+            const msg = `${entry.path}: missing freshness marker (<!-- analyzed: date | commit: sha | files: N -->). Writer: ${entry.writer}`;
+            if (entry.severity === 'error') {
+                errors.push(msg);
+            } else {
+                warnings.push(msg);
+            }
+        }
+    }
+
+    if (errors.length > 0) {
+        process.stdout.write(`❌  Generated artefact freshness errors:\n\n`);
+        for (const e of errors) {
+            process.stdout.write(`  - ${e}\n`);
+        }
+        process.stdout.write(
+            `\nThe generator script must write <!-- analyzed: … --> as the first line.\n` +
+                `See docs/contracts/agents-layout.md § Session-leftover discipline.\n`,
+        );
+    }
+
+    if (warnings.length > 0 && !quiet) {
+        process.stdout.write(`⚠️  Generated artefact freshness warnings:\n\n`);
+        for (const w of warnings) {
+            process.stdout.write(`  - ${w}\n`);
+        }
+    }
+
+    if (errors.length === 0 && warnings.length === 0 && !quiet) {
+        process.stdout.write(
+            `✅  All ${GENERATED_ARTEFACTS.length} generated artefacts carry the freshness marker.\n`,
+        );
+    }
+
+    return errors.length > 0 ? 1 : 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, GENERATED_ARTEFACTS };

package/src/scripts/check_generator_output_coverage.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env tsx
+/**
+ * CI gate: every generator output root declared in this registry must be
+ * classified in `src/config/agents-paths.yml` (policy = ignored or carve-out)
+ * OR explicitly marked as tracked-generated with a committed carve-out in
+ * the package .gitignore (e.g. `!/dist/agent-src/`).
+ *
+ * This is the guard that would have caught `.claude/agents/` being unclassified:
+ * generate_claude_subagents() writes .claude/agents/, but neither the manifest
+ * nor the package .gitignore had an entry for it.
+ *
+ * Exit codes:
+ *   0 — all generator output roots are classified
+ *   1 — one or more roots are unclassified
+ *   2 — missing file
+ */
+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), '..', '..');
+
+const MANIFEST = path.join(REPO_ROOT, 'src', 'config', 'agents-paths.yml');
+const PACKAGE_GITIGNORE = path.join(REPO_ROOT, '.gitignore');
+
+// Generator output root registry.
+// Maintained here (alongside condense.ts generator list).
+// Each entry: { root, generator, tool? } where root is the directory
+// the generator writes into (relative to repo root).
+//
+// When you add a new generate_* function in condense.ts that writes to a
+// new directory, add an entry here in the same commit.
+const GENERATOR_OUTPUT_ROOTS = [
+    { root: '.claude/rules', generator: 'generate_rule_symlinks', tool: 'claude-code' },
+    { root: '.claude/personas', generator: 'generate_persona_symlinks', tool: 'claude-code' },
+    { root: '.claude/user-types', generator: 'generate_user_type_symlinks', tool: 'claude-code' },
+    { root: '.claude/skills', generator: 'generate_claude_skills + generate_plugin_command_skills', tool: 'claude-code' },
+    { root: '.claude/agents', generator: 'generate_claude_subagents', tool: 'claude-code' },
+    { root: '.augment', generator: 'sync_augment (condense main)', tool: 'augment' },
+    { root: '.cursor/rules', generator: 'generate_cursor_mdc_rules', tool: 'cursor' },
+    { root: '.windsurfrules', generator: 'generate_windsurfrules', tool: 'windsurf' },
+    { root: '.windsurf/rules', generator: 'generate_windsurf_modern_rules', tool: 'windsurf' },
+    { root: 'dist/agent-src', generator: 'condense (main output)', tool: null },
+    { root: 'GEMINI.md', generator: 'generate_gemini_md', tool: 'gemini' },
+] as const;
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Check if a root is classified in agents-paths.yml OR in .gitignore */
+function isClassified(root: string, manifestPaths: Set<string>, gitignoreLines: Set<string>): boolean {
+    // Build all candidates for this root: the root itself plus all ancestor dirs.
+    // gitignore patterns like /.cursor/ cover .cursor/rules because the parent is ignored.
+    const parts = root.split('/');
+    const candidates: string[] = [];
+    for (let i = parts.length; i >= 1; i--) {
+        const sub = parts.slice(0, i).join('/');
+        candidates.push(sub, `/${sub}`, `/${sub}/`, sub + '/');
+    }
+    // Also check negation carve-outs (e.g. !/dist/agent-src/)
+    candidates.push(`!/${root}/`, `!${root}`, `!/${root}`);
+
+    for (const c of candidates) {
+        if (manifestPaths.has(c) || gitignoreLines.has(c)) return true;
+    }
+    return false;
+}
+
+function parseManifestPaths(text: string): Set<string> {
+    const paths = new Set<string>();
+    for (const line of text.split('\n')) {
+        const m = line.match(/^- path:\s*(.+)/);
+        if (m?.[1] !== undefined) paths.add(m[1].trim().replace(/^"|"$/g, ''));
+    }
+    return paths;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const quiet = args.includes('--quiet');
+
+    if (!_isFile(MANIFEST)) {
+        process.stdout.write(`❌  Manifest not found: ${MANIFEST}\n`);
+        return 2;
+    }
+    if (!_isFile(PACKAGE_GITIGNORE)) {
+        process.stdout.write(`❌  .gitignore not found: ${PACKAGE_GITIGNORE}\n`);
+        return 2;
+    }
+
+    const manifestPaths = parseManifestPaths(fs.readFileSync(MANIFEST, 'utf-8'));
+    const gitignoreLines = new Set(
+        fs.readFileSync(PACKAGE_GITIGNORE, 'utf-8')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => Boolean(l) && !l.startsWith('#')),
+    );
+
+    const unclassified: typeof GENERATOR_OUTPUT_ROOTS[number][] = [];
+    for (const entry of GENERATOR_OUTPUT_ROOTS) {
+        if (!isClassified(entry.root, manifestPaths, gitignoreLines)) {
+            unclassified.push(entry);
+        }
+    }
+
+    if (unclassified.length > 0) {
+        process.stdout.write(
+            `❌  Generator output roots not classified in agents-paths.yml or .gitignore:\n\n`,
+        );
+        for (const e of unclassified) {
+            process.stdout.write(`  - ${e.root} (written by ${e.generator})\n`);
+        }
+        process.stdout.write(
+            `\nAdd an entry to src/config/agents-paths.yml (policy: ignored or carve-out)\n` +
+                `or ensure a negation carve-out exists in the package .gitignore.\n` +
+                `Also add the path to the GENERATOR_OUTPUT_ROOTS registry in this script.\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  All ${GENERATOR_OUTPUT_ROOTS.length} generator output roots are classified.\n`,
+        );
+    }
+    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, GENERATOR_OUTPUT_ROOTS };

package/src/scripts/check_gitignore_freshness.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env tsx
+/**
+ * CI gate: every `policy: ignored` entry in `src/config/agents-paths.yml`
+ * that applies to consumer or both scopes must be present in
+ * `src/config/gitignore-block.txt`.
+ *
+ * This is a read-only freshness check — it does NOT generate either file.
+ * Full generation (Phase 3.2/3.3 of road-to-agents-dir-and-gitignore-hygiene)
+ * is a future enhancement; this check prevents silent drift in the meantime.
+ *
+ * Exit codes:
+ *   0 — all consumer-scoped ignored paths are covered in the block
+ *   1 — one or more paths are missing from the block
+ *   2 — invalid args or missing file
+ */
+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), '..', '..');
+
+const MANIFEST = path.join(REPO_ROOT, 'src', 'config', 'agents-paths.yml');
+const BLOCK = path.join(REPO_ROOT, 'src', 'config', 'gitignore-block.txt');
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Minimal YAML parser for the agents-paths.yml structure:
+ * list of objects with `path`, `scope`, `policy` keys.
+ * Handles the literal string list entries (- key: value form).
+ */
+function parseManifest(text: string): Array<{ path: string; scope: string; policy: string }> {
+    const entries: Array<{ path: string; scope: string; policy: string }> = [];
+    const lines = text.split('\n');
+    let cur: Record<string, string> | null = null;
+
+    for (const raw of lines) {
+        const line = raw.trimEnd();
+        // New list item starts with "- path:"
+        if (/^- path:/.test(line)) {
+            if (cur && cur['path'] && cur['scope'] && cur['policy']) {
+                entries.push({ path: cur['path'], scope: cur['scope'], policy: cur['policy'] });
+            }
+            cur = {};
+            const m = line.match(/^- path:\s*(.+)/);
+            if (m?.[1] !== undefined) cur['path'] = m[1].trim().replace(/^"|"$/g, '');
+        } else if (cur && /^\s+scope:/.test(line)) {
+            const m = line.match(/scope:\s*(.+)/);
+            if (m?.[1] !== undefined) cur['scope'] = m[1].trim();
+        } else if (cur && /^\s+policy:/.test(line)) {
+            const m = line.match(/policy:\s*(.+)/);
+            if (m?.[1] !== undefined) cur['policy'] = m[1].trim();
+        }
+    }
+    if (cur && cur['path'] && cur['scope'] && cur['policy']) {
+        entries.push({ path: cur['path'], scope: cur['scope'], policy: cur['policy'] });
+    }
+    return entries;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const quiet = args.includes('--quiet');
+
+    if (!_isFile(MANIFEST)) {
+        process.stdout.write(`❌  Manifest not found: ${MANIFEST}\n`);
+        return 2;
+    }
+    if (!_isFile(BLOCK)) {
+        process.stdout.write(`❌  Consumer block not found: ${BLOCK}\n`);
+        return 2;
+    }
+
+    const manifestText = fs.readFileSync(MANIFEST, 'utf-8');
+    const blockText = fs.readFileSync(BLOCK, 'utf-8');
+    const blockLines = new Set(blockText.split('\n').map((l) => l.trim()).filter(Boolean));
+
+    const entries = parseManifest(manifestText);
+    const missing: string[] = [];
+
+    for (const e of entries) {
+        if (e.policy !== 'ignored') continue;
+        if (e.scope !== 'consumer' && e.scope !== 'both') continue;
+        // Carve-out negations (path starts with !) are separately tracked
+        if (e.path.startsWith('!')) continue;
+        if (!blockLines.has(e.path)) {
+            missing.push(e.path);
+        }
+    }
+
+    if (missing.length > 0) {
+        process.stdout.write(
+            `❌  gitignore-block.txt is missing consumer-scoped ignored paths from agents-paths.yml:\n\n`,
+        );
+        for (const m of missing) {
+            process.stdout.write(`  - ${m}\n`);
+        }
+        process.stdout.write(
+            `\nAdd these patterns to src/config/gitignore-block.txt ` +
+                `(or update agents-paths.yml if the scope/policy is wrong).\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  gitignore-block.txt covers all ${entries.filter((e) => e.policy === 'ignored' && (e.scope === 'consumer' || e.scope === 'both')).length} consumer-scoped ignored paths.\n`,
+        );
+    }
+    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 };

package/src/scripts/check_knowledge_pages.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env tsx
+/**
+ * Warn-only lint for the lifecycle-typed knowledge pages —
+ * road-to-knowledge-system Phase 2. Scans
+ * `agents/knowledge/{sessions,concepts,procedures,decisions}/*.md`.
+ *
+ * Deliberately SEPARATE from `check_knowledge_cards.ts` (a byte-faithful
+ * parity twin of its retired Python original — never touched here) and
+ * deliberately warn-only: schema-as-contract for these pages is explicitly
+ * deferred (2026-07-05 council verdict) until real team usage data exists.
+ * This script never fails the build; it surfaces drift for a human to act
+ * on during consolidation.
+ *
+ * Checks:
+ *   - `type` (if present) is one of concept|procedure|session|decision
+ *   - `scope` (if present) is one of user|project|global
+ *   - `visibility` (if present) is one of private|project|team
+ *   - `review_after` (if present): valid YYYY-MM-DD; flagged if in the past
+ *   - `contested` (if present): flagged when it carries >= 2 entries
+ *   - page body (excluding frontmatter) is <= 200 lines
+ *
+ * Usage: check_knowledge_pages.ts [--dir <repo-root>] [--format text|json] [--quiet]
+ * Exit codes: 0 = ran cleanly (warnings do not fail the build), 1 = usage
+ * error, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const PROG = 'check_knowledge_pages.ts';
+const PAGE_LINE_BUDGET = 200;
+const CONTESTED_WARN_COUNT = 2;
+
+const TYPED_DIRS = ['sessions', 'concepts', 'procedures', 'decisions'] as const;
+const VALID_TYPE = new Set(['concept', 'procedure', 'session', 'decision']);
+const VALID_SCOPE = new Set(['user', 'project', 'global']);
+const VALID_VISIBILITY = new Set(['private', 'project', 'team']);
+
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export interface Warning {
+    file: string; // path relative to --dir
+    rule: string;
+    message: string;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function readFrontmatter(body: string): Record<string, unknown> {
+    const m = FRONTMATTER_RE.exec(body);
+    if (m?.[1] === undefined) return {};
+    try {
+        const parsed = YAML.parse(m[1]);
+        return isPlainObject(parsed) ? parsed : {};
+    } catch {
+        return {};
+    }
+}
+
+function bodyLineCount(body: string): number {
+    const withoutFrontmatter = body.replace(FRONTMATTER_RE, '');
+    // Trailing newline shouldn't count as an extra "line".
+    const trimmed = withoutFrontmatter.replace(/\n$/, '');
+    return trimmed.length === 0 ? 0 : trimmed.split('\n').length;
+}
+
+/** Lint a single page's already-read content. Pure — no filesystem access — for direct unit testing. */
+export function lintPage(relPath: string, content: string, today: Date = new Date()): Warning[] {
+    const warnings: Warning[] = [];
+    const fm = readFrontmatter(content);
+
+    const type = fm.type;
+    if (typeof type === 'string' && !VALID_TYPE.has(type)) {
+        warnings.push({ file: relPath, rule: 'type', message: `unknown type "${type}" (expected one of concept|procedure|session|decision)` });
+    }
+
+    const scope = fm.scope;
+    if (typeof scope === 'string' && !VALID_SCOPE.has(scope)) {
+        warnings.push({ file: relPath, rule: 'scope', message: `unknown scope "${scope}" (expected one of user|project|global)` });
+    }
+
+    const visibility = fm.visibility;
+    if (typeof visibility === 'string' && !VALID_VISIBILITY.has(visibility)) {
+        warnings.push({
+            file: relPath,
+            rule: 'visibility',
+            message: `unknown visibility "${visibility}" (expected one of private|project|team)`,
+        });
+    }
+
+    const reviewAfter = fm.review_after;
+    if (typeof reviewAfter === 'string') {
+        if (!DATE_RE.test(reviewAfter)) {
+            warnings.push({ file: relPath, rule: 'review_after', message: `review_after "${reviewAfter}" is not YYYY-MM-DD` });
+        } else {
+            const due = new Date(`${reviewAfter}T00:00:00Z`);
+            if (!Number.isNaN(due.getTime()) && due.getTime() < today.getTime()) {
+                warnings.push({ file: relPath, rule: 'review_after', message: `review_after ${reviewAfter} is in the past — due for review` });
+            }
+        }
+    }
+
+    const contested = fm.contested;
+    if (Array.isArray(contested) && contested.length >= CONTESTED_WARN_COUNT) {
+        warnings.push({
+            file: relPath,
+            rule: 'contested',
+            message: `${contested.length} unresolved contested entries — needs consolidation attention`,
+        });
+    }
+
+    const lineCount = bodyLineCount(content);
+    if (lineCount > PAGE_LINE_BUDGET) {
+        warnings.push({ file: relPath, rule: 'size', message: `${lineCount} lines exceeds the ${PAGE_LINE_BUDGET}-line page budget` });
+    }
+
+    return warnings;
+}
+
+function listMarkdownFiles(dirPath: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+        .map((e) => e.name)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+export function lintAll(knowledgeRoot: string, today: Date = new Date()): Warning[] {
+    const warnings: Warning[] = [];
+    for (const dir of TYPED_DIRS) {
+        const scanDir = path.join(knowledgeRoot, dir);
+        for (const file of listMarkdownFiles(scanDir)) {
+            const relPath = `${dir}/${file}`;
+            let content: string;
+            try {
+                content = fs.readFileSync(path.join(scanDir, file), 'utf8');
+            } catch {
+                continue;
+            }
+            warnings.push(...lintPage(relPath, content, today));
+        }
+    }
+    return warnings;
+}
+
+function printUsage(): void {
+    process.stdout.write(`usage: ${PROG} [--dir DIR] [--format text|json] [--quiet]\n`);
+}
+
+export function main(argv: string[]): number {
+    let dir = process.cwd();
+    let format: 'text' | 'json' = 'text';
+    let quiet = false;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--dir') {
+            dir = argv[++i] ?? dir;
+        } else if (arg === '--format') {
+            const value = argv[++i];
+            if (value !== 'text' && value !== 'json') {
+                process.stderr.write(`${PROG}: error: --format must be text or json\n`);
+                return 1;
+            }
+            format = value;
+        } else if (arg === '--quiet') {
+            quiet = true;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 1;
+        }
+    }
+
+    const knowledgeRoot = path.join(dir, 'agents', 'knowledge');
+    const warnings = lintAll(knowledgeRoot);
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(warnings, null, 2) + '\n');
+        return 0;
+    }
+
+    if (warnings.length === 0) {
+        if (!quiet) process.stdout.write(`${PROG}: no warnings.\n`);
+        return 0;
+    }
+
+    for (const w of warnings) {
+        process.stdout.write(`🟡 ${w.file}: [${w.rule}] ${w.message}\n`);
+    }
+    if (!quiet) process.stdout.write(`${PROG}: ${warnings.length} warning(s) — non-blocking.\n`);
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}