@event4u/agent-config 7.5.0 → 8.0.0

package/src/scripts/check_quality_regression.ts

@@ -33,8 +33,17 @@
  *   ./scripts-run src/scripts/check_quality_regression            # gate (inert w/o run data)
  *   ./scripts-run src/scripts/check_quality_regression --json
  *   ./scripts-run src/scripts/check_quality_regression --threshold 0.48
+ *   ./scripts-run src/scripts/check_quality_regression --as-flip-gate
  *
- * Exit codes: 0 ok / inert · 1 file error · 2 quality regression (win-rate < threshold).
+ * Flip-gate hardening (token-proof-and-story Phase 0):
+ *   - A report with `dry_run: true` is NEVER an unlock — exit 2 in every mode.
+ *     A mock report must not be indistinguishable from a pass in a script chain.
+ *   - `--as-flip-gate` (used by the falsification checklist / the thin/scoped
+ *     flip decision): "no report" and "no decisive pairs — inconclusive" are
+ *     NOT unlocks → exit 2. Without the flag the CI-inert path keeps exit 0.
+ *
+ * Exit codes: 0 ok / inert · 1 file error · 2 quality regression, dry-run
+ * report, or (under --as-flip-gate) missing/inconclusive report.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -166,16 +175,27 @@ export function gateVerdict(agg: QualityAggregate): 0 | 2 {
 
 interface RunReport {
   threshold?: number;
+  dry_run?: boolean;
   results?: PairResult[];
 }
 
 function main(argv: string[]): number {
   let asJson = false;
+  let asFlipGate = false;
   let threshold = DEFAULT_THRESHOLD;
+  let reportPath = RUN_REPORT;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--json') asJson = true;
-    else if (a === '--threshold') {
+    else if (a === '--as-flip-gate') asFlipGate = true;
+    else if (a === '--report') {
+      const v = argv[(i += 1)];
+      if (!v) {
+        process.stderr.write('error: --report requires a path\n');
+        return 1;
+      }
+      reportPath = path.resolve(v);
+    } else if (a === '--threshold') {
       const v = Number(argv[(i += 1)]);
       if (!Number.isFinite(v) || v < 0 || v > 1) {
         process.stderr.write('error: --threshold must be in [0,1]\n');
@@ -183,7 +203,9 @@ function main(argv: string[]): number {
       }
       threshold = v;
     } else if (a === '-h' || a === '--help') {
-      process.stdout.write('usage: check_quality_regression [--json] [--threshold F]\n');
+      process.stdout.write(
+        'usage: check_quality_regression [--json] [--threshold F] [--as-flip-gate] [--report PATH]\n',
+      );
       return 0;
     } else {
       process.stderr.write(`error: unknown argument: ${a}\n`);
@@ -191,9 +213,17 @@ function main(argv: string[]): number {
     }
   }
 
-  if (!fs.existsSync(RUN_REPORT)) {
+  if (!fs.existsSync(reportPath)) {
+    if (asFlipGate) {
+      const msg =
+        `❌  flip gate: no quality-run report (${path.relative(REPO_ROOT, reportPath)}) — ` +
+        'a flip requires a real judge run. NOT an unlock.';
+      if (asJson) process.stdout.write(JSON.stringify({ verdict: 'no-data', flip_gate: true, unlock: false }, null, 2) + '\n');
+      else process.stdout.write(msg + '\n');
+      return 2;
+    }
     const msg =
-      `⚠️  no quality-run report (${path.relative(REPO_ROOT, RUN_REPORT)}) — ` +
+      `⚠️  no quality-run report (${path.relative(REPO_ROOT, reportPath)}) — ` +
       'gate inert. Produce it with a thin-vs-eager judge run (operator/cost gate).';
     if (asJson) process.stdout.write(JSON.stringify({ verdict: 'no-data', inert: true }, null, 2) + '\n');
     else process.stdout.write(msg + '\n');
@@ -202,17 +232,27 @@ function main(argv: string[]): number {
 
   let report: RunReport;
   try {
-    report = JSON.parse(fs.readFileSync(RUN_REPORT, 'utf-8')) as RunReport;
+    report = JSON.parse(fs.readFileSync(reportPath, 'utf-8')) as RunReport;
   } catch (e) {
-    process.stderr.write(`error: cannot parse ${path.relative(REPO_ROOT, RUN_REPORT)}: ${(e as Error).message}\n`);
+    process.stderr.write(`error: cannot parse ${path.relative(REPO_ROOT, reportPath)}: ${(e as Error).message}\n`);
     return 1;
   }
+
+  if (report.dry_run === true) {
+    const msg =
+      '❌  quality-run report is a DRY-RUN mock (`dry_run: true`) — a mock is never an unlock.\n' +
+      '   Re-run the judge live (bench_quality_run without --dry-run) or delete the mock report.';
+    if (asJson) process.stdout.write(JSON.stringify({ verdict: 'dry-run', unlock: false }, null, 2) + '\n');
+    else process.stdout.write(msg + '\n');
+    return 2;
+  }
+
   const results = Array.isArray(report.results) ? report.results : [];
   const thr = typeof report.threshold === 'number' ? report.threshold : threshold;
   const agg = aggregate(results, thr);
 
   if (asJson) {
-    process.stdout.write(JSON.stringify({ ...agg, threshold: thr }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ ...agg, threshold: thr, flip_gate: asFlipGate }, null, 2) + '\n');
   } else {
     process.stdout.write(
       `quality run: ${agg.total} pairs · thin ${agg.thin_wins} / eager ${agg.eager_wins} / ` +
@@ -225,12 +265,18 @@ function main(argv: string[]): number {
     if (agg.verdict === 'regression') {
       process.stdout.write(`❌  quality regression: thin win-rate below ${(thr * 100).toFixed(0)}%.\n`);
     } else if (agg.verdict === 'no-data') {
-      process.stdout.write(`⚠️  no decisive pairs — inconclusive.\n`);
+      if (asFlipGate) {
+        process.stdout.write(`❌  flip gate: no decisive pairs — inconclusive is NOT an unlock.\n`);
+      } else {
+        process.stdout.write(`⚠️  no decisive pairs — inconclusive.\n`);
+      }
     } else {
       process.stdout.write(`✅  quality held: thin win-rate within tolerance.\n`);
     }
   }
-  return gateVerdict(agg);
+  const code = gateVerdict(agg);
+  if (code === 0 && asFlipGate && agg.verdict === 'no-data') return 2;
+  return code;
 }
 
 const _IS_MAIN =

package/src/scripts/check_references.ts

@@ -58,7 +58,8 @@ const SKIP_DIRS = [
     'agents/reports', // transient run reports — historical/scratch refs, not stable artefacts
     'agents/roadmaps/skipped', // skipped roadmaps — abandoned plans w/ forward-refs that never shipped
     'agents/runtime', // volatile / machine-generated artefacts (gitignored)
-    'agents/tmp', // transient working docs (gitignored) — pr-bodies, council questions, manual-step scratchpads
+    'agents/tmp', // user inbox (gitignored) — user-dropped notes/todos; agents only read + move to tmp.old/
+    'agents/tmp.old', // processed inbox archive (gitignored) — consumed tmp/ files; janitor TTL 30 days
     'agents/.harvest-local', // deliberate gitignored evidence store (source-confidentiality) — refs to it can never resolve in CI
 ];
 
@@ -167,6 +168,7 @@ const EXAMPLE_PATH_PATTERNS: RegExp[] = [
     /agents\/ownership-map\.yml/, // consumer-project routing data
     /agents\/historical-bug-patterns\.yml/, // consumer-project routing data
     /agents\/memory\//, // consumer-project memory data
+    /agents\/knowledge\//, // consumer-project knowledge cards + typed pages (road-to-knowledge-system)
     /agents\/learnings\//, // consumer-project learning notes
     /agents\/proposals\//, // consumer-project self-improvement proposals
     /agents\/drafts\//, // consumer-project artefact drafts

package/src/scripts/check_release_pr_shape.ts

@@ -31,6 +31,10 @@ const ALLOWLIST_GLOBS = [
     'src/domains/*/pack.yaml',
     'src/domains/*/README.md',
     'docs/archive/CHANGELOG-pre-*.md',
+    // Project-settings template pin — bumped by release.ts set_template_pin and
+    // its regenerated dist twin (kept in lockstep with package.json.version).
+    'src/agent-src/templates/agents/agent-project-settings.example.yml',
+    'dist/agent-src/templates/agents/agent-project-settings.example.yml',
 ] as const;
 
 /**

package/src/scripts/check_site_links.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * B4 — CI link-checker for the built Starlight site (no new dependency).
+ *
+ * Astro `build` completes even with dangling internal links, so a plain build is
+ * NOT a link gate. This scans the built `site/dist/**` HTML for internal links
+ * (`href` / `src`) and verifies every one resolves to a real file in `dist/` —
+ * accounting for the `base` prefix (`/agent-config`), trailing-slash dirs
+ * (`…/x/` → `…/x/index.html`), and `#fragment` / `?query` stripping. External
+ * (`http(s):`, `mailto:`, `data:`, protocol-relative `//`) links and pure `#`
+ * anchors are skipped — this gate owns *internal* integrity only.
+ *
+ * Read-only. Exit 0 clean / 1 on any broken internal link, 2 if the site has not
+ * been built yet (run `cd site && npm run build` first).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_site_links            # scan site/dist
+ *   ./scripts-run src/scripts/check_site_links --dist DIR --base /prefix
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _FILE = fileURLToPath(import.meta.url);
+export const REPO = path.resolve(path.dirname(_FILE), '..', '..');
+
+/** Read `base:` from site/astro.config.mjs (default '/agent-config'). */
+export function readBase(repo: string = REPO): string {
+    const cfg = path.join(repo, 'site', 'astro.config.mjs');
+    if (fs.existsSync(cfg)) {
+        const m = /base:\s*['"]([^'"]+)['"]/.exec(fs.readFileSync(cfg, 'utf-8'));
+        if (m && m[1]) return m[1].replace(/\/+$/, '');
+    }
+    return '/agent-config';
+}
+
+function _walkHtml(dir: string): string[] {
+    const out: string[] = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory()) stack.push(full);
+            else if (e.isFile() && e.name.endsWith('.html')) out.push(full);
+        }
+    }
+    return out.sort();
+}
+
+const _LINK_RE = /(?:href|src)\s*=\s*"([^"]*)"/gi;
+const _EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|mailto:|tel:|data:)/i;
+
+/** Resolve one internal link to a candidate dist-relative file, or null to skip. */
+export function resolveTarget(link: string, base: string): string | null {
+    let l = link.trim();
+    if (l === '' || _EXTERNAL.test(l)) return null;
+    // Strip fragment + query.
+    l = l.split('#')[0]!.split('?')[0]!;
+    if (l === '') return null;
+    if (!l.startsWith('/')) return null; // relative links are rare in Astro output; skip (not internal-root)
+    // Strip the base prefix.
+    if (base && (l === base || l.startsWith(base + '/'))) {
+        l = l.slice(base.length);
+    }
+    if (l === '' || l === '/') return 'index.html';
+    l = l.replace(/^\/+/, '');
+    if (l.endsWith('/')) return l + 'index.html';
+    return l;
+}
+
+export function findBrokenLinks(distDir: string, base: string): Array<{ page: string; link: string }> {
+    const broken: Array<{ page: string; link: string }> = [];
+    const seenOk = new Set<string>();
+    for (const html of _walkHtml(distDir)) {
+        const text = fs.readFileSync(html, 'utf-8');
+        const pageRel = path.relative(distDir, html);
+        let m: RegExpExecArray | null;
+        _LINK_RE.lastIndex = 0;
+        const linksInPage = new Set<string>();
+        while ((m = _LINK_RE.exec(text)) !== null) {
+            const raw = m[1] as string;
+            const target = resolveTarget(raw, base);
+            if (target === null) continue;
+            if (linksInPage.has(raw)) continue;
+            linksInPage.add(raw);
+            const cacheKey = target;
+            if (seenOk.has(cacheKey)) continue;
+            const candidates = [
+                path.join(distDir, target),
+                path.join(distDir, target, 'index.html'), // extensionless dir link
+            ];
+            if (candidates.some((c) => fs.existsSync(c) && fs.statSync(c).isFile())) {
+                seenOk.add(cacheKey);
+            } else {
+                broken.push({ page: pageRel, link: raw });
+            }
+        }
+    }
+    return broken;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const quiet = argv.includes('--quiet');
+    const distArg = argv.indexOf('--dist');
+    const baseArg = argv.indexOf('--base');
+    const distDir = distArg !== -1 && argv[distArg + 1] ? path.resolve(argv[distArg + 1] as string) : path.join(REPO, 'site', 'dist');
+    const base = baseArg !== -1 && argv[baseArg + 1] ? (argv[baseArg + 1] as string).replace(/\/+$/, '') : readBase();
+
+    if (!fs.existsSync(distDir)) {
+        process.stderr.write(`❌  site not built: ${distDir} is missing. Run \`cd site && npm ci && npm run build\` first.\n`);
+        return 2;
+    }
+    const broken = findBrokenLinks(distDir, base);
+    if (broken.length > 0) {
+        process.stdout.write(`❌  ${broken.length} broken internal link(s) in the built site:\n`);
+        for (const b of broken) process.stdout.write(`  - ${b.page}: ${b.link}\n`);
+        return 1;
+    }
+    if (!quiet) {
+        const pages = _walkHtml(distDir).length;
+        process.stdout.write(`✅  site links: ${pages} page(s), no broken internal links (base ${base}).\n`);
+    }
+    return 0;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());

package/src/scripts/check_skill_gaps.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * B6 — the falsifiability lock for per-skill honest-null `gaps:`.
+ *
+ * Every `gaps[].witness` in a skill's frontmatter must point at a test file that
+ * EXISTS (pointer integrity). The witness *passing* — and going red when the gap
+ * is fixed (the stale-gap audit) — is enforced by the ordinary test suite; this
+ * script guarantees the pointer never rots and the shape is well-formed, so the
+ * proof page's "Known Limits" can never cite a phantom witness.
+ *
+ * Read-only over `src/skills/*\/SKILL.md`. Exit 0 clean / 1 on any broken pointer
+ * or malformed entry.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+
+export interface Gap {
+    description: string;
+    witness: string;
+}
+export interface SkillGaps {
+    skill: string;
+    file: string;
+    gaps: Gap[];
+}
+
+/** Parse `gaps:` from every SKILL.md that declares them. */
+export function collectSkillGaps(skillsDir: string = SKILLS_DIR): SkillGaps[] {
+    const out: SkillGaps[] = [];
+    let names: string[];
+    try {
+        names = fs.readdirSync(skillsDir).sort();
+    } catch {
+        return out;
+    }
+    for (const name of names) {
+        const file = path.join(skillsDir, name, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        const m = FRONTMATTER_RE.exec(fs.readFileSync(file, 'utf-8'));
+        if (!m) continue;
+        let fm: Record<string, unknown> | null;
+        try {
+            fm = parseYaml(m[1] as string) as Record<string, unknown> | null;
+        } catch {
+            continue;
+        }
+        if (!fm || !Array.isArray(fm.gaps) || fm.gaps.length === 0) continue;
+        out.push({ skill: name, file, gaps: fm.gaps as Gap[] });
+    }
+    return out;
+}
+
+export function findBrokenPointers(entries: SkillGaps[], root: string = ROOT): string[] {
+    const errs: string[] = [];
+    for (const e of entries) {
+        e.gaps.forEach((g, i) => {
+            if (typeof g?.description !== 'string' || !g.description.trim()) {
+                errs.push(`${e.skill}: gaps[${i}] missing/empty description`);
+            }
+            if (typeof g?.witness !== 'string' || !g.witness.trim()) {
+                errs.push(`${e.skill}: gaps[${i}] missing/empty witness`);
+                return;
+            }
+            if (!fs.existsSync(path.join(root, g.witness))) {
+                errs.push(`${e.skill}: gaps[${i}] witness not found: ${g.witness}`);
+            }
+        });
+    }
+    return errs;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const quiet = argv.includes('--quiet');
+    const entries = collectSkillGaps();
+    const errs = findBrokenPointers(entries);
+    if (errs.length > 0) {
+        process.stdout.write('❌ skill gaps:\n');
+        for (const e of errs.sort()) process.stdout.write(`  - ${e}\n`);
+        return 1;
+    }
+    const gapCount = entries.reduce((n, e) => n + e.gaps.length, 0);
+    if (!quiet) {
+        process.stdout.write(
+            `✅  skill gaps: ${gapCount} gap(s) across ${entries.length} skill(s), all witness pointers resolve.\n`,
+        );
+    }
+    return 0;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());