@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/sync_gitignore.ts

@@ -31,243 +31,37 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-export const SECTION_HEADER = '# event4u/agent-config';
-export const SECTION_FOOTER = '# event4u/agent-config — END';
-export const DEFAULT_GITIGNORE = '.gitignore';
+export {
+    SECTION_HEADER,
+    SECTION_FOOTER,
+    DEFAULT_GITIGNORE,
+    DEFAULT_TEMPLATE,
+    LEGACY_PATTERNS,
+    TemplateNotFoundError,
+    load_template,
+    find_block,
+    block_entries,
+    template_entries,
+    build_fresh_block,
+    sync_block,
+    cleanup_legacy,
+    format_file,
+} from './_lib/gitignore_block.js';
+import {
+    DEFAULT_GITIGNORE,
+    DEFAULT_TEMPLATE,
+    TemplateNotFoundError,
+    load_template,
+    cleanup_legacy,
+    format_file,
+    sync_block,
+    template_entries,
+    _isFile,
+    _splitlines,
+    _strip,
+} from './_lib/gitignore_block.js';
 
 const _HERE = fileURLToPath(import.meta.url);
-// _HERE === <repo>/src/scripts/sync_gitignore.ts ; parents[2] of the .py file
-// is the repo root — two dirs up from src/scripts. the retired Python implementation derives
-// DEFAULT_TEMPLATE = <file>.parent.parent.parent / "src" / "config" /
-// "gitignore-block.txt".
-export const DEFAULT_TEMPLATE = path.join(
-    path.dirname(_HERE),
-    '..',
-    '..',
-    'src',
-    'config',
-    'gitignore-block.txt',
-);
-
-// Legacy patterns that lived in older versions of src/config/gitignore-block.txt
-// before runtime artefacts moved under /agents/runtime/ (May 2026). They get
-// stripped wherever they appear in the consumer's .gitignore — inside the
-// managed block or outside (older installers / hand-edits). Current canonical
-// equivalents (e.g. /agents/runtime/.agent-prices.md) come from the template
-// and are NOT affected. Leading-slash variants are matched defensively.
-//
-// Authoritative source: src/config/agents-paths.yml entries with `legacy: true`.
-// Manual sync until the generation step from the manifest is implemented
-// (road-to-agents-dir-and-gitignore-hygiene Phase 3.2 follow-on).
-export const LEGACY_PATTERNS: readonly string[] = [
-    '.agent-chat-history',
-    '.agent-chat-history.bak',
-    '.agent-chat-history.*.bak',
-    '.agent-prices.md',
-    '.council-tmp/',
-    // 2.x intermediate: prices cache lived directly under agents/ before
-    // consolidating under agents/runtime/.
-    'agents/.agent-prices.md',
-    // Budget history JSONLs — previously listed explicitly at project
-    // root or under agents/; now covered by the /agents/runtime/
-    // catch-all in the managed block.
-    '.augment-budget-history.jsonl',
-    '.rule-budget-history.jsonl',
-    'agents/.augment-budget-history.jsonl',
-    'agents/.rule-budget-history.jsonl',
-];
-
-function _strip(ln: string): string {
-    // Python: ln.rstrip("\n").rstrip() — strip a trailing newline, then strip
-    // all trailing whitespace.
-    return ln.replace(/\n+$/, '').replace(/\s+$/, '');
-}
-
-function _is_entry(ln: string): boolean {
-    // Non-empty, non-comment line = a path/pattern entry.
-    const s = _strip(ln).replace(/^\s+/, '');
-    return Boolean(s) && !s.startsWith('#');
-}
-
-/** Error raised when the template file is missing (→ exit 2 in main). */
-export class TemplateNotFoundError extends Error {
-    constructor(p: string) {
-        super(`template not found: ${p}`);
-        this.name = 'TemplateNotFoundError';
-    }
-}
-
-function _isFile(p: string): boolean {
-    try {
-        return fs.statSync(p).isFile();
-    } catch {
-        return false;
-    }
-}
-
-/** Python str.splitlines() — split on universal newlines, no trailing empty. */
-function _splitlines(text: string): string[] {
-    if (text === '') return [];
-    // str.splitlines() splits on \n, \r, \r\n (and more) and does NOT keep a
-    // trailing empty element. The targets here only ever contain \n / \r\n.
-    const parts = text.split(/\r\n|\r|\n/);
-    if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
-    return parts;
-}
-
-export function load_template(p: string): string[] {
-    if (!_isFile(p)) {
-        throw new TemplateNotFoundError(p);
-    }
-    const text = fs.readFileSync(p, 'utf-8');
-    // Keep trailing newlines stripped; we splice explicit newlines.
-    return _splitlines(text).map(_strip);
-}
-
-/**
- * Locate the managed block; return [start_idx, end_idx_exclusive] or null.
- *
- * `start_idx` points at the SECTION_HEADER line.
- * `end_idx_exclusive` points one past the last line of the block.
- * Honors explicit SECTION_FOOTER when present; otherwise treats the
- * block as extending to EOF or to the next non-managed section.
- */
-export function find_block(lines: readonly string[]): [number, number] | null {
-    for (let i = 0; i < lines.length; i += 1) {
-        if (_strip(lines[i] as string) === SECTION_HEADER) {
-            const start = i;
-            // Explicit footer?
-            for (let j = i + 1; j < lines.length; j += 1) {
-                if (_strip(lines[j] as string) === SECTION_FOOTER) {
-                    return [start, j + 1];
-                }
-            }
-            // Legacy: extend to EOF or next non-managed section break.
-            let end = lines.length;
-            for (let j = i + 1; j < lines.length; j += 1) {
-                const s = _strip(lines[j] as string).replace(/^\s+/, '');
-                if (
-                    s.startsWith('#') &&
-                    !s.startsWith('# Agent config') &&
-                    s !== SECTION_HEADER
-                ) {
-                    end = j;
-                    while (end > i + 1 && _strip(lines[end - 1] as string) === '') {
-                        end -= 1;
-                    }
-                    break;
-                }
-            }
-            return [start, end];
-        }
-    }
-    return null;
-}
-
-/** Return entries (paths/patterns) present in the given block. */
-export function block_entries(block_lines: readonly string[]): string[] {
-    return block_lines
-        .filter((ln) => _is_entry(ln))
-        .map((ln) => _strip(ln).replace(/^\s+/, ''));
-}
-
-export function template_entries(template_lines: readonly string[]): string[] {
-    return template_lines.filter((ln) => _is_entry(ln)).map((ln) => ln.replace(/^\s+/, ''));
-}
-
-/** Return a fresh, fully-managed block with START + body + END. */
-export function build_fresh_block(template_lines: readonly string[]): string[] {
-    return [SECTION_HEADER, ...template_lines, SECTION_FOOTER];
-}
-
-/**
- * Return [new_lines, added_entries].
- *
- * - If block missing: append fresh block (preceded by a blank line if the
- *   file's last line is not already empty).
- * - If block present and replace=true: rewrite block in full.
- * - If block present and replace=false: append any missing managed entries
- *   before the END marker (adding END if absent). User-added lines inside the
- *   block are preserved.
- */
-export function sync_block(
-    existing_lines: readonly string[],
-    template_lines: readonly string[],
-    options: { replace?: boolean } = {},
-): [string[], string[]] {
-    const replace = options.replace ?? false;
-    const loc = find_block(existing_lines);
-    const fresh = build_fresh_block(template_lines);
-
-    // Missing block → append with leading blank if needed.
-    if (loc === null) {
-        const newLines = [...existing_lines];
-        if (newLines.length > 0 && _strip(newLines[newLines.length - 1] as string) !== '') {
-            newLines.push('');
-        }
-        newLines.push(...fresh);
-        return [newLines, template_entries(template_lines)];
-    }
-
-    const [start, end] = loc;
-    const head = existing_lines.slice(0, start);
-    let block = existing_lines.slice(start, end);
-    const tail = existing_lines.slice(end);
-
-    if (replace) {
-        const existing = new Set(block_entries(block));
-        const added = template_entries(template_lines).filter((e) => !existing.has(e));
-        return [[...head, ...fresh, ...tail], added];
-    }
-
-    // Append-only mode.
-    const existing_entries = new Set(block_entries(block));
-    const missing = template_entries(template_lines).filter((e) => !existing_entries.has(e));
-    if (missing.length === 0) {
-        return [[...existing_lines], []];
-    }
-
-    // Ensure block ends with SECTION_FOOTER; insert missing entries right
-    // before it.
-    let insert_at: number;
-    if (block.length > 0 && _strip(block[block.length - 1] as string) === SECTION_FOOTER) {
-        insert_at = block.length - 1;
-    } else {
-        block = [...block, SECTION_FOOTER];
-        insert_at = block.length - 1;
-    }
-    const new_block = [...block.slice(0, insert_at), ...missing, ...block.slice(insert_at)];
-    return [[...head, ...new_block, ...tail], missing];
-}
-
-/**
- * Strip legacy entries from anywhere in the file.
- *
- * A line is legacy when its stripped, leading-whitespace-trimmed content
- * matches a `LEGACY_PATTERNS` entry — with or without a leading slash.
- * Comments and blank lines are untouched; current managed entries (e.g.
- * `/agents/.agent-chat-history`) are not in the legacy set and survive.
- */
-export function cleanup_legacy(lines: readonly string[]): [string[], string[]] {
-    const legacy = new Set(LEGACY_PATTERNS);
-    const kept: string[] = [];
-    const removed: string[] = [];
-    for (const ln of lines) {
-        const s = _strip(ln).replace(/^\s+/, '');
-        if (legacy.has(s) || (s.startsWith('/') && legacy.has(s.slice(1)))) {
-            removed.push(s);
-            continue;
-        }
-        kept.push(ln);
-    }
-    return [kept, removed];
-}
-
-/** Join lines with newlines and enforce exactly one trailing newline. */
-export function format_file(lines: readonly string[]): string {
-    const text = lines.join('\n');
-    return text.replace(/\n+$/, '') + '\n';
-}
 
 /** Python difflib.unified_diff(..., n=3) over keepends-split lines. */
 export function render_diff(old_text: string, new_text: string, p: string): string {

package/src/scripts/trigger_eval_grandfather.json

@@ -9,7 +9,6 @@
     "agent-docs-writing",
     "agents-md-thin-root",
     "ai-council",
-    "api-design",
     "api-endpoint",
     "api-testing",
     "artisan-commands",
@@ -44,7 +43,6 @@
     "dependency-upgrade",
     "description-assist",
     "design-review",
-    "design-system-capture",
     "devcontainer",
     "developer-like-execution",
     "discovery-interview",
@@ -153,7 +151,6 @@
     "repomix-packer",
     "requesting-code-review",
     "retention-loops",
-    "review-routing",
     "rice-prioritization",
     "risk-officer",
     "roadmap-management",
@@ -169,7 +166,6 @@
     "security",
     "sentry-integration",
     "sequential-thinking",
-    "skill-improvement-pipeline",
     "skill-management",
     "skill-reviewer",
     "song-to-script",
@@ -180,7 +176,6 @@
     "subagent-orchestration",
     "symfony-workflow",
     "systematic-debugging",
-    "tailwind-engineer",
     "tech-debt-tracker",
     "technical-specification",
     "terraform",

package/src/server/schemas/settings.ts

@@ -323,6 +323,11 @@ export const settingsSchema = z.object({
         fidelity_mode: 'strict',
         approximation: { enabled: false, tolerance: { color: null, length: null } },
     }),
+    code_graph: z.object({
+        consumer_index_paths: z.array(z.string()).default([]).describe(
+            "Extra project-relative paths where THIS project keeps a code-graph index another tool wrote. The built-in list is deliberately vendor-neutral (graph.json, code-graph.json, .code-graph/graph.json) and names no tool, so a tool that writes its index elsewhere is named here rather than waited for. A graph found this way LOADS and answers query and explain with every edge tagged read-from-elsewhere; the gate verbs (impact, untested, dead) refuse a graph made only of such edges and say so, because an empty answer from a gate must not read as 'nothing found' when it means 'nothing trusted'. Absolute paths and paths escaping the project root are ignored.",
+        ),
+    }).default({}),
     consistency: z.object({
         cross_source: crossSourceMode.default('on').describe(
             'Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.',
@@ -590,6 +595,11 @@ export const settingsSchema = z.object({
                 'When a hook exceeds hooks.concern_budget.max_per_event, fail the run (true) instead of warning and continuing (false, default). Turn on in CI when you want hook quality to gate merges.',
             ),
         }),
+        verify_before_complete: z.object({
+            touched_file_quality: z.enum(['off', 'shadow', 'warn']).default('off').describe(
+                "Stop-slot pass that runs the project's OWN quality commands — the ones resolve_toolchain() already reports — over the files this turn edited. Default off. `shadow` records a per-run result and emits nothing; `warn` adds ONE advisory line of at most 200 bytes. Never blocks and never counts as verification: a command recorded here never reaches _lib/verification_command.ts, so a clean eslint run cannot let a turn claim it verified anything. A writing command runs only in its check form (pint --test) or not at all, and a command with no per-file form is skipped rather than run project-wide at every stop.",
+            ),
+        }).default({}),
         injection_scan: z.object({
             enabled: z.boolean().default(false).describe(
                 'PostToolUse prompt-injection scanner (road-to-security-pillar.md P3.2). Default off. When on, scans tool output (file reads, web fetches, MCP responses) for injection signatures and WARNS in context (never blocks). Runtime backstop on top of the always-on untrusted-input-defense rule; detection is probabilistic.',

package/src/shared/skillRanking.ts

@@ -24,10 +24,13 @@
  * `score_skill_relevance` CLI's argparse-parity suite is the check that the move
  * changed nothing.
  *
- * THE ONE ADDITION is `triggerTerms`, off by default. Phase 3.1 of the same
- * roadmap indexes `triggers.keyword` / `triggers.phrase` text; it is an opt-in
- * parameter rather than a second function so the two rankers can be measured
- * against each other on one corpus.
+ * THE ADDITIONS ARE ALL OFF BY DEFAULT and live in one {@link RankOptions}
+ * object: three that widen the indexed TERM SOURCE (trigger prose, the skill's
+ * own `## When to use` section, the body's headings) and one that changes the
+ * WEIGHTING (inverse document frequency over the catalogue). They are opt-in
+ * parameters rather than separate functions so two configurations can be
+ * measured against each other on one corpus without becoming two rankers. With
+ * every flag off the arithmetic is the ported one, unchanged.
  *
  * Pure — no imports, no I/O, no clock.
  */
@@ -115,36 +118,136 @@ export interface RankableSkill {
     personas?: readonly string[];
     /** `triggers[].keyword` / `triggers[].phrase` text. Indexed only on request. */
     triggerText?: readonly string[];
+    /** The skill's own `## When to use` prose. Indexed only on request. */
+    whenToUseText?: string;
+    /** The skill body's `##` / `###` heading lines. Indexed only on request. */
+    headingText?: readonly string[];
 }
 
+/**
+ * The candidate signals, each off by default and each measurable alone.
+ *
+ * `road-to-a-ranker-that-routes` 2.2 requires exactly this shape: one flag per
+ * signal, default off, so a configuration is a named set of flags and two
+ * readings of "the ranker" are never two different rankers under one name. With
+ * every flag off the score is byte-identical to the Python-parity scorer, which
+ * is what the CLI parity suite pins.
+ */
 export interface RankOptions {
-    /** Phase 3.1: fold `triggerText` into the indexed terms. Default false (keyword-v1). */
+    /** Fold `triggerText` into the indexed terms. Default false (keyword-v1). */
     includeTriggers?: boolean;
+    /** Fold the skill's own `## When to use` prose into the indexed terms. */
+    includeWhenToUse?: boolean;
+    /** Fold the body's section headings into the indexed terms. */
+    includeHeadings?: boolean;
+    /**
+     * Weight each matched term by its inverse document frequency over the
+     * catalogue, instead of counting every term alike.
+     *
+     * Needs {@link TermStats}. Setting it WITHOUT one throws, rather than
+     * quietly taking the unweighted branch: a weighting that falls back to
+     * unweighted on a missing input produces a baseline number under a
+     * configuration's name, which is the one failure the whole flag table
+     * exists to prevent.
+     */
+    idfWeighting?: boolean;
 }
 
 /** The indexed term set for one skill, under the given options. */
 export function skillTerms(skill: RankableSkill, opts: RankOptions = {}): Set<string> {
     const parts = [skill.name, skill.description];
     if (opts.includeTriggers && skill.triggerText) parts.push(...skill.triggerText);
+    if (opts.includeWhenToUse && skill.whenToUseText) parts.push(skill.whenToUseText);
+    if (opts.includeHeadings && skill.headingText) parts.push(...skill.headingText);
     return tokenize(parts.join(' '));
 }
 
+/** True when `opts` turns on at least one term source beyond name + description. */
+export function widensTermSource(opts: RankOptions): boolean {
+    return Boolean(opts.includeTriggers || opts.includeWhenToUse || opts.includeHeadings);
+}
+
+/**
+ * How many indexed skills carry each term, and how many skills there are.
+ *
+ * Derived from the catalogue under the SAME options the ranking uses — a
+ * document frequency computed over one term source and applied to another
+ * would weight terms by how rare they are somewhere they were never read.
+ */
+export interface TermStats {
+    df: ReadonlyMap<string, number>;
+    skills: number;
+}
+
+/**
+ * @param termSets the per-skill term sets, in the same order as `skills`.
+ *   Required rather than derived, so the catalogue is tokenized ONCE per call
+ *   instead of once here and again at the scoring loop. Tokenizing ~300 skills
+ *   twice per prompt is invisible next to re-reading them from disk, which is
+ *   exactly why it would have stayed invisible.
+ */
+export function buildTermStats(
+    skills: readonly RankableSkill[],
+    termSets: readonly ReadonlySet<string>[],
+): TermStats {
+    const df = new Map<string, number>();
+    for (const terms of termSets) {
+        for (const t of terms) df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    return { df, skills: skills.length };
+}
+
+/**
+ * The weight one matched term carries.
+ *
+ * `ln(1 + skills / (1 + df))`, the smoothed textbook form: a term on every
+ * skill tends to zero, a term on one skill carries the most. Unknown terms are
+ * treated as df 0 — a task term no skill indexes cannot be matched anyway, so
+ * its weight only affects the denominator, where counting it fully is right:
+ * failing to cover a rare term should cost more than failing to cover a common
+ * one.
+ */
+export function idf(term: string, stats: TermStats): number {
+    return Math.log(1 + stats.skills / (1 + (stats.df.get(term) ?? 0)));
+}
+
 /**
  * The score. `taskTerms` is `tokenize(task)`; `terms` is `skillTerms(skill)`.
  *
  * Both are passed in rather than derived here so a caller ranking N skills
  * tokenizes the task once and each skill once, which is what makes this usable
- * on a per-prompt hook path.
+ * on a per-prompt hook path. `opts` and `stats` are optional and, with them
+ * absent or every flag off, the arithmetic is exactly the Python-parity one.
  */
 export function scoreSkill(
     taskTerms: ReadonlySet<string>,
     skill: RankableSkill,
     terms: ReadonlySet<string>,
+    opts: RankOptions = {},
+    stats?: TermStats,
 ): number {
+    if (opts.idfWeighting && !stats) {
+        throw new Error(
+            'scoreSkill: idfWeighting is set but no TermStats was passed — scoring unweighted here ' +
+                'would publish a baseline number under the idf label. Build stats with buildTermStats.',
+        );
+    }
     if (taskTerms.size === 0) return 0;
-    let inter = 0;
-    for (const t of taskTerms) if (terms.has(t)) inter++;
-    const overlap = inter / Math.max(taskTerms.size, 1);
+    let overlap: number;
+    if (opts.idfWeighting && stats) {
+        let hit = 0;
+        let total = 0;
+        for (const t of taskTerms) {
+            const w = idf(t, stats);
+            total += w;
+            if (terms.has(t)) hit += w;
+        }
+        overlap = total > 0 ? hit / total : 0;
+    } else {
+        let inter = 0;
+        for (const t of taskTerms) if (terms.has(t)) inter++;
+        overlap = inter / Math.max(taskTerms.size, 1);
+    }
     let personaHit = 0;
     const taskLower = [...taskTerms].join(' ');
     for (const persona of skill.personas ?? []) {
@@ -173,9 +276,12 @@ export function rankSkills(
     opts: RankOptions = {},
 ): RankedSkill[] {
     const taskTerms = tokenize(task);
+    const termSets = skills.map((s) => skillTerms(s, opts));
+    const stats = opts.idfWeighting ? buildTermStats(skills, termSets) : undefined;
     const rows: RankedSkill[] = [];
-    for (const skill of skills) {
-        const score = scoreSkill(taskTerms, skill, skillTerms(skill, opts));
+    for (let i = 0; i < skills.length; i += 1) {
+        const skill = skills[i] as RankableSkill;
+        const score = scoreSkill(taskTerms, skill, termSets[i] as ReadonlySet<string>, opts, stats);
         if (score > 0) rows.push({ name: skill.name, score, personas: [...(skill.personas ?? [])] });
     }
     rows.sort((a, b) => (b.score - a.score) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));