@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/sessions_cli.ts

@@ -45,12 +45,14 @@ import { fileURLToPath } from 'node:url';
 
 import { write_atomic } from './_lib/fs_atomic.js';
 import {
+    classify_collisions,
     iso_now,
     read_live_records,
     register_dir,
     safe_stem,
     ttl_is_measured,
     ttl_seconds_for,
+    type SessionRecord,
 } from './_lib/session_register.js';
 import { claim_file, claim_is_stale, claim_read_paths } from './session_register_hook.js';
 
@@ -62,7 +64,7 @@ function usage(): number {
             '                                           live sessions, plus unmerged branches',
             '                                           held by other worktrees (--branches adds',
             '                                           that axis to the JSON form)',
-            '  agent-config sessions:claim <slug>       claim a roadmap for this session',
+            '  agent-config sessions:claim <slug> [--paths <a,b,…>]       claim a roadmap for this session',
             '  agent-config sessions:claim <slug> --force   claim it even though a peer holds it',
             '  agent-config sessions:claim --release    drop this session\'s roadmap claim',
             '',
@@ -168,6 +170,30 @@ export function other_worktree_branches_detailed(
     return { rows, filtered: unmerged !== null };
 }
 
+/**
+ * `PATH OVERLAP` lines for this session against every live peer.
+ *
+ * Kept a separate, separately-labelled line rather than folded into the slug or
+ * branch report, because the three collisions call for three different moves: a
+ * slug collision means stop, a branch collision means coordinate, a path
+ * collision means reorder — take the disjoint steps first if ordering allows,
+ * otherwise name it and continue. The register is advisory and never a lock.
+ *
+ * Pure over the record arrays so the fixture test needs no register on disk.
+ */
+export function path_overlap_lines(
+    others: readonly SessionRecord[],
+    here: { branch: string | null; roadmap_slug: string | null; owned_paths?: readonly string[] },
+): string[] {
+    return classify_collisions(others, here)
+        .filter((c) => c.kind === 'path')
+        .map(
+            (c) =>
+                `  PATH OVERLAP  ${c.record.session_id}  ·  ${(c.paths ?? []).length} shared path(s): ` +
+                `${(c.paths ?? []).join(', ')}`,
+        );
+}
+
 function cmd_list(argv: string[], root: string): number {
     const as_json = argv.includes('--json');
     const dir = register_dir(root);
@@ -229,6 +255,21 @@ function cmd_list(argv: string[], root: string): number {
         );
     }
     write_held_branches(held, filtered);
+    // The path axis. Silent when this session has declared no owned paths, which
+    // is every session that has not run `sessions:claim --paths`.
+    const sid = env_session_id();
+    const mine = sid === null ? undefined : records.find((r) => r.session_id === sid);
+    const overlaps = path_overlap_lines(
+        records.filter((r) => r.session_id !== mine?.session_id),
+        {
+            branch: mine?.branch ?? null,
+            roadmap_slug: mine?.roadmap_slug ?? null,
+            ...(mine?.owned_paths !== undefined ? { owned_paths: mine.owned_paths } : {}),
+        },
+    );
+    if (overlaps.length > 0) {
+        process.stdout.write(`\n${overlaps.join('\n')}\n`);
+    }
     process.stdout.write(
         'Advisory only — this register is not a lock, and an idle session\n' +
             'disappears from it after its TTL although its user may return.\n',
@@ -432,7 +473,15 @@ function cmd_claim(argv: string[], root: string): number {
         );
         return 0;
     }
-    const slug = argv.find((a) => !a.startsWith('-'));
+    const paths_idx = argv.indexOf('--paths');
+    const paths_arg = paths_idx >= 0 ? (argv[paths_idx + 1] ?? '') : '';
+    const owned_paths = paths_arg
+        .split(',')
+        .map((x) => x.trim())
+        .filter((x) => x !== '');
+    // The slug is the first bare token that is not the VALUE of --paths; without
+    // this the comma list would be read as the slug on `claim --paths a,b road-to-x`.
+    const slug = argv.find((a, i) => !a.startsWith('-') && i !== paths_idx + 1);
     if (slug === undefined || slug.trim() === '') {
         return usage();
     }
@@ -476,7 +525,19 @@ function cmd_claim(argv: string[], root: string): number {
     try {
         write_atomic(
             target,
-            `${JSON.stringify({ slug: slug.trim(), written_at: iso_now(), session_id: sid }, null, 2)}\n`,
+            `${JSON.stringify(
+                {
+                    slug: slug.trim(),
+                    written_at: iso_now(),
+                    session_id: sid,
+                    // Absent, not empty, when nothing was declared: the whole
+                    // additive guarantee of `owned_paths` rests on the field not
+                    // being written at all in the ordinary case.
+                    ...(owned_paths.length > 0 ? { paths: owned_paths } : {}),
+                },
+                null,
+                2,
+            )}\n`,
         );
     } catch (exc) {
         process.stderr.write(`sessions:claim: could not write the claim — ${String(exc)}\n`);
@@ -484,6 +545,9 @@ function cmd_claim(argv: string[], root: string): number {
     }
     process.stdout.write(
         `Claimed "${slug.trim()}" for this session. It becomes visible to other\n` +
+            (owned_paths.length > 0
+                ? `Declared ${owned_paths.length} owned path(s); peers sharing one are labelled PATH OVERLAP.\n`
+                : '') +
             'sessions on the next turn, when the heartbeat lifts it into the register.\n' +
             (sid === null
                 ? 'NOTE: this host exports no session id, so the claim is scoped to this\n' +

package/src/scripts/skill_tools/score_skill_relevance.ts

@@ -34,7 +34,17 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { pyRound } from '../_lib/value_ladder.js';
+// The formula, the stopword list and the tokenizer live in one Node-free
+// module so the pure stdio-lite dispatcher can share them instead of growing
+// a second copy (road-to-skill-delivery-over-mcp risk 6). Everything below is
+// the disk half — globbing, frontmatter, the CLI — which stays here.
+import {
+    scoreSkill,
+    skillTerms as _sharedSkillTerms,
+    tokenize as _sharedTokenize,
+    triggerTextFromFlatLines,
+    type RankOptions,
+} from '../../shared/skillRanking.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/skill_tools/score_skill_relevance.ts → parents[3] of the .py
@@ -42,19 +52,6 @@ const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
 export const DEFAULT_SKILLS_DIR = path.join(ROOT, '.agent-src.uncondensed', 'skills');
 
-// re.compile(r"[a-z][a-z0-9]+") — applied to the lowercased text.
-const TOKEN_RE = /[a-z][a-z0-9]+/g;
-
-const STOPWORDS: ReadonlySet<string> = new Set([
-    'the', 'a', 'an', 'and', 'or', 'but', 'of', 'for', 'with', 'to', 'in',
-    'on', 'at', 'by', 'from', 'as', 'is', 'are', 'was', 'were', 'be', 'been',
-    'this', 'that', 'these', 'those', 'it', 'its', 'use', 'when', 'even',
-    'via', 'via:', 'into', 'onto', 'use:', 'skill', 'skills', 'task', 'tasks',
-    'code', 'file', 'files', 'doing', 'make', 'do', 'go', 'get', 'set',
-    'not', 'no', 'yes', 'any', 'some', 'all', 'one', 'two', 'new', 'old',
-    'user', 'users', 'our', 'your', 'their', 'they', 'we', 'you', 'i', 'me',
-]);
-
 /** Mirror Python len(str) — count Unicode code points, not UTF-16 units. */
 function pyLen(s: string): number {
     let n = 0;
@@ -65,16 +62,9 @@ function pyLen(s: string): number {
 }
 
 export function _tokenize(text: string): Set<string> {
-    const out = new Set<string>();
-    // The TOKEN_RE stopwords never contain digits, so the `len(t) > 2`
-    // filter is on code-point length (matches Python `len`).
-    const matches = text.toLowerCase().match(TOKEN_RE) ?? [];
-    for (const t of matches) {
-        if (!STOPWORDS.has(t) && pyLen(t) > 2) {
-            out.add(t);
-        }
-    }
-    return out;
+    // Single-sourced in `src/shared/skillRanking.ts`. Kept as an export because
+    // the CLI-parity suite and the hook path both import this name.
+    return _sharedTokenize(text);
 }
 
 export interface Frontmatter {
@@ -152,6 +142,8 @@ export interface Skill {
     description: string;
     personas: string[];
     terms: Set<string>;
+    /** `triggers[].keyword` / `.phrase` prose. Indexed only under keyword-v2. */
+    triggerText: string[];
 }
 
 function _load_skills(skillsDir: string): Skill[] {
@@ -167,11 +159,16 @@ function _load_skills(skillsDir: string): Skill[] {
             personas = [personas];
         }
         const personaList = [...personas];
+        const rawTriggers = fm['triggers'];
+        const triggerText = Array.isArray(rawTriggers)
+            ? triggerTextFromFlatLines(rawTriggers as string[])
+            : [];
         skills.push({
             name,
             description: desc,
             personas: personaList,
             terms: _tokenize(name + ' ' + desc),
+            triggerText,
         });
     }
     return skills;
@@ -214,43 +211,29 @@ function _globSkillMd(root: string): string[] {
     return dirs.map((name) => path.join(root, name, 'SKILL.md'));
 }
 
-function _score(taskTerms: Set<string>, skill: Skill): number {
-    if (taskTerms.size === 0) {
-        return 0;
-    }
-    const skillTerms = skill.terms;
-    let inter = 0;
-    for (const t of taskTerms) {
-        if (skillTerms.has(t)) {
-            inter++;
-        }
-    }
-    // overlap = |task ∩ skill| / max(|task|, 1)
-    const overlap = inter / Math.max(taskTerms.size, 1);
-    let personaHit = 0.0;
-    // task_lower = " ".join(task_terms) — Set iteration order = insertion order
-    // (matches Python set-iteration only incidentally; the membership tests
-    // below are order-independent so the result is deterministic).
-    const taskLower = [...taskTerms].join(' ');
-    for (const persona of skill.personas) {
-        const slug = String(persona).toLowerCase();
-        const parts = slug.split('-');
-        if (taskLower.includes(slug) || parts.some((part) => taskTerms.has(part))) {
-            personaHit = 1.0;
-            break;
-        }
-    }
-    return pyRound(overlap * 70 + personaHit * 30, 0);
+function _score(taskTerms: Set<string>, skill: Skill, opts: RankOptions = {}): number {
+    // Single-sourced in `src/shared/skillRanking.ts`. Under keyword-v1 (the
+    // default) `skill.terms` is already `tokenize(name + ' ' + description)`, so
+    // the precomputed set is reused unchanged; keyword-v2 re-derives the term
+    // set with the skill's trigger prose folded in.
+    const rankable = {
+        name: skill.name,
+        description: skill.description,
+        personas: skill.personas,
+        triggerText: skill.triggerText,
+    };
+    const terms = opts.includeTriggers ? _sharedSkillTerms(rankable, opts) : skill.terms;
+    return scoreSkill(taskTerms, rankable, terms);
 }
 
 export type RankRow = [string, number, string[]];
 
-export function rank(task: string, skillsDir: string): RankRow[] {
+export function rank(task: string, skillsDir: string, opts: RankOptions = {}): RankRow[] {
     const taskTerms = _tokenize(task);
     const skills = _load_skills(skillsDir);
     const rows: RankRow[] = [];
     for (const s of skills) {
-        const score = _score(taskTerms, s);
+        const score = _score(taskTerms, s, opts);
         if (score > 0) {
             rows.push([s.name, score, [...s.personas]]);
         }

package/src/scripts/tighten_skill_descriptions.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * Tighten skill descriptions toward a cap WITHOUT touching trigger vocabulary.
+ *
+ * The description is the routing surface. `lint_skill_descriptions` gates its
+ * shape, `audit_skill_descriptions` ranks it and `optimize_skill_description`
+ * tunes ONE skill against its own `evals/triggers.json`. None of them shortens
+ * a corpus, which is why this exists — and why it is deliberately timid.
+ *
+ * THE FAILURE IT IS BUILT AGAINST. A rewriter asked to cut N chars strips
+ * trigger vocabulary before it strips filler, because filler is the harder of
+ * the two to identify. A description that loses its trigger phrase costs more
+ * in missed routing than it ever saves in tokens, so this tool never rewrites:
+ * it applies a closed list of audited, meaning-preserving transformations and
+ * then REFUSES to write unless the informative-token set came out identical.
+ *
+ * "Informative token" is mechanical: lowercased, ≥4 chars, not in STOPWORDS.
+ * The set — not the count — must match, so a transformation that swapped one
+ * informative word for another of the same length is rejected too.
+ *
+ * A skill the transformations cannot bring under the cap is reported as a MISS
+ * with the residual filler budget beside it, and left alone. That number is
+ * what separates "a hand rewrite could still find filler here" from "the only
+ * chars left to cut are informative ones" — the second is a genuine
+ * trigger-loss wall and the honest reason to stop, and reporting it is the
+ * point rather than a consolation for having stopped.
+ *
+ * Usage:
+ *   tighten_skill_descriptions --cap 189            # report only (default)
+ *   tighten_skill_descriptions --cap 189 --apply    # write the wins
+ *   tighten_skill_descriptions --self-test
+ *
+ * Exit 0 on report and on apply; 1 only on a self-test failure or a usage
+ * error. This is an authoring tool, not a gate.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { SRC_SKILLS } from './_lib/agent_src.js';
+
+/** Words too short or too common to carry routing signal. */
+const STOPWORDS = new Set([
+    'when', 'with', 'from', 'that', 'this', 'they', 'them', 'then', 'than', 'into', 'over',
+    'your', 'each', 'both', 'only', 'also', 'such', 'been', 'were', 'will', 'would', 'have',
+    'here', 'what', 'which', 'while', 'their', 'there', 'these', 'those', 'about', 'after',
+    'before', 'every', 'other', 'under', 'until', 'using', 'uses', 'used', 'more', 'most',
+    'less', 'least', 'same', 'does', 'doing', 'done', 'make', 'makes', 'made',
+]);
+
+export function informativeTokens(s: string): Set<string> {
+    const out = new Set<string>();
+    for (const raw of s.toLowerCase().split(/[^a-z0-9'’\-]+/)) {
+        const t = raw.replace(/^[-']+|[-']+$/g, '');
+        if (t.length < 4) continue;
+        if (STOPWORDS.has(t)) continue;
+        out.add(t);
+    }
+    return out;
+}
+
+/**
+ * The closed transformation list. Each is meaning-preserving in English and
+ * removes only connective or punctuation characters — never a content word.
+ * `why` is printed in the report so a reviewer can audit the list itself.
+ */
+export const TRANSFORMS: readonly { why: string; apply: (s: string) => string }[] = [
+    { why: '"Use when X" → "When X" (the imperative adds nothing a reader needs)', apply: (s) => s.replace(/^Use when /, 'When ') },
+    { why: '"in order to" → "to"', apply: (s) => s.replace(/\bin order to\b/g, 'to') },
+    { why: 'Oxford comma removed (house style)', apply: (s) => s.replace(/,(\s+)and\b/g, '$1and') },
+    { why: 'collapsed runs of whitespace', apply: (s) => s.replace(/  +/g, ' ') },
+];
+
+/**
+ * Filler still available AFTER the transforms — the chars a hand rewrite could
+ * remove without touching an informative token. Deliberately generous: it
+ * counts every stopword occurrence and every separator run, so a MISS reported
+ * with a small budget is a strong claim and one with a large budget is an
+ * invitation to rewrite by hand, not a wall.
+ */
+export function fillerBudget(s: string): number {
+    let n = 0;
+    for (const raw of s.toLowerCase().split(/([^a-z0-9'’\-]+)/)) {
+        const t = raw.replace(/^[-']+|[-']+$/g, '');
+        if (t.length === 0) continue;
+        if (/^[^a-z0-9]+$/.test(raw) && raw.length > 1) n += raw.length - 1;
+        else if (t.length < 4 || STOPWORDS.has(t)) n += t.length + 1;
+    }
+    return n;
+}
+
+export type Outcome = 'already_under' | 'tightened' | 'miss';
+
+export interface Result {
+    skill: string;
+    before: number;
+    after: number;
+    outcome: Outcome;
+    /** Chars of filler still removable by hand at `after`. Only set on a miss. */
+    filler_left: number;
+    applied: string[];
+    text: string | null;
+}
+
+export function tighten(skill: string, desc: string, cap: number): Result {
+    const before = desc.length;
+    if (before <= cap) {
+        return { skill, before, after: before, outcome: 'already_under', filler_left: 0, applied: [], text: null };
+    }
+    const want = informativeTokens(desc);
+    let cur = desc;
+    const applied: string[] = [];
+    for (const t of TRANSFORMS) {
+        const next = t.apply(cur).trim();
+        if (next === cur) continue;
+        // Reject any transformation that moved the informative set, even if it
+        // shortened the string. A same-length swap is still a routing change.
+        const got = informativeTokens(next);
+        if (got.size !== want.size || [...want].some((w) => !got.has(w))) continue;
+        cur = next;
+        applied.push(t.why);
+    }
+    if (cur.length <= cap) {
+        return { skill, before, after: cur.length, outcome: 'tightened', filler_left: 0, applied, text: cur };
+    }
+    return {
+        skill,
+        before,
+        after: cur.length,
+        outcome: 'miss',
+        filler_left: fillerBudget(cur),
+        applied,
+        text: null,
+    };
+}
+
+const DESC_RE = /^(description:[ \t]*)(.*?)[ \t]*$/m;
+
+function unquote(v: string): { text: string; quote: string } {
+    const q = v.length > 1 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0] ? String(v[0]) : '';
+    return { text: q ? v.slice(1, -1) : v, quote: q };
+}
+
+interface Skill {
+    name: string;
+    file: string;
+    raw: string;
+    desc: string;
+    quote: string;
+}
+
+function collect(root: string): Skill[] {
+    const out: Skill[] = [];
+    if (!fs.existsSync(root)) return out;
+    for (const d of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        const file = path.join(root, d.name, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        const raw = fs.readFileSync(file, 'utf-8');
+        const m = DESC_RE.exec(raw);
+        if (m === null) continue;
+        const { text, quote } = unquote(String(m[2]));
+        out.push({ name: d.name, file, raw, desc: text, quote });
+    }
+    return out;
+}
+
+function selfTest(): number {
+    const cases: { name: string; desc: string; cap: number; outcome: Outcome; after?: number }[] = [
+        { name: 'under cap is untouched', desc: 'Short one.', cap: 189, outcome: 'already_under' },
+        {
+            name: 'the Use-when prefix is the cheapest real win',
+            desc: 'Use when ' + 'x'.repeat(184),
+            cap: 189,
+            outcome: 'tightened',
+            after: 189,
+        },
+        {
+            name: 'nothing to remove is a miss, not a silent truncation',
+            desc: 'sqlinjection '.repeat(16),
+            cap: 100,
+            outcome: 'miss',
+        },
+    ];
+    let pass = 0;
+    let fail = 0;
+    for (const c of cases) {
+        const r = tighten(c.name, c.desc, c.cap);
+        const ok = r.outcome === c.outcome && (c.after === undefined || r.after === c.after);
+        if (ok) pass += 1;
+        else {
+            fail += 1;
+            console.error(`❌ ${c.name}: outcome=${r.outcome} after=${r.after}`);
+        }
+    }
+    // The load-bearing guard: a transformation that changed the informative
+    // set must be refused even though it shortens.
+    const before = informativeTokens('deploy kubernetes manifests');
+    const after = informativeTokens('deploy kubernetes manifest');
+    if (before.size === after.size && [...before].every((t) => after.has(t))) {
+        fail += 1;
+        console.error('❌ informativeTokens: singular/plural must NOT compare equal — the guard would let a word change through');
+    } else {
+        pass += 1;
+    }
+    process.stdout.write(`tighten_skill_descriptions --self-test: ${pass} pass, ${fail} fail\n`);
+    return fail === 0 ? 0 : 1;
+}
+
+function main(argv: string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const capIdx = argv.indexOf('--cap');
+    const cap = capIdx >= 0 && argv[capIdx + 1] !== undefined ? Number(argv[capIdx + 1]) : 189;
+    if (!Number.isInteger(cap) || cap < 40) {
+        process.stderr.write('--cap must be an integer ≥ 40\n');
+        return 1;
+    }
+    const apply = argv.includes('--apply');
+    const skills = collect(SRC_SKILLS());
+    if (skills.length === 0) {
+        process.stderr.write(`no skills found under ${SRC_SKILLS()} — refusing to report a zero\n`);
+        return 1;
+    }
+    const results = skills.map((s) => tighten(s.name, s.desc, cap));
+    const wins = results.filter((r) => r.outcome === 'tightened');
+    const misses = results.filter((r) => r.outcome === 'miss');
+
+    if (apply) {
+        for (const r of wins) {
+            const s = skills.find((x) => x.name === r.skill);
+            if (s === undefined || r.text === null) continue;
+            const replaced = s.raw.replace(DESC_RE, (_m, k: string) => `${k}${s.quote}${String(r.text)}${s.quote}`);
+            fs.writeFileSync(s.file, replaced);
+        }
+    }
+
+    const savedChars = wins.reduce((a, r) => a + (r.before - r.after), 0);
+    process.stdout.write(`cap ${cap} · ${skills.length} skill(s)\n`);
+    process.stdout.write(`tightened: ${wins.length} (${savedChars} chars, ≈${Math.round(savedChars / 4)} tok)${apply ? ' — WRITTEN' : ' — dry run'}\n`);
+    process.stdout.write(
+        `misses:    ${misses.length} (left alone — the closed transformation list did not reach the cap)\n`,
+    );
+    if (misses.length > 0) {
+        const need = Math.max(...misses.map((m) => m.after - cap));
+        const minFiller = Math.min(...misses.map((m) => m.filler_left));
+        process.stdout.write(
+            minFiller > need
+                ? `           read the table: every miss still holds ≥ ${minFiller} chars of filler against a need of ≤ ${need}, ` +
+                      'so these are limits of THIS tool, not trigger-loss walls. A hand rewrite is available.\n'
+                : '           at least one miss is close to its filler floor — there a cut would start taking informative tokens.\n',
+        );
+    }
+    if (misses.length > 0) {
+        process.stdout.write('\n| skill | len | over | filler left |\n|---|---|---|---|\n');
+        for (const m of misses.sort((a, b) => b.after - a.after)) {
+            process.stdout.write(`| \`${m.skill}\` | ${m.after} | +${m.after - cap} | ${m.filler_left} |\n`);
+        }
+    }
+    process.stdout.write(`scanned: ${skills.length}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('tighten_skill_descriptions')) {
+    process.exit(main(process.argv.slice(2)));
+}