@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/lint_roadmap_complexity.ts

@@ -21,9 +21,12 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { project_settings_path } from './_lib/agent_settings.js';
+import { asOf } from './_lib/as_of.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { granularity_problems } from './_lib/roadmap_granularity.js';
+import { loadStepSizeBaseline, staleHeld, stepSizeProblems } from './_lib/roadmap_step_size.js';
+import { screenRoadmap } from './roadmap_drain_queue.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 /** Mirror `QUIET = "--quiet" in sys.argv` (computed at import). */
@@ -198,6 +201,12 @@ function _check_no_plate(text: string, problems: string[]): void {
     }
 }
 
+let _stepSizeHeld: Set<string> | null = null;
+function _stepSizeBaseline(): Set<string> {
+    _stepSizeHeld ??= loadStepSizeBaseline(REPO_ROOT);
+    return _stepSizeHeld;
+}
+
 function lint_roadmap(
     p: string,
     horizon_weeks: number,
@@ -222,21 +231,46 @@ function lint_roadmap(
     // here rather than shipped as its own gate; `_lib/roadmap_granularity.ts`
     // carries the reason.
     problems.push(...granularity_problems(text));
+    problems.push(...stepSizeProblems(path.basename(p), text, _stepSizeBaseline()));
+    if (warnings) {
+        for (const key of staleHeld(path.basename(p), text, _stepSizeBaseline())) {
+            warnings.push(`${key} fits under the step cap now — delete it from src/config/roadmap-step-size-baseline.json`);
+        }
+    }
     if (horizon_weeks <= 0) {
         _check_no_plate(text, problems);
     }
     _check_execution_mode(fm, problems);
     _check_relates(fm, problems);
+    _check_cross_file_waits(text, fm, path.dirname(p), problems);
     if (warnings) {
         _check_autonomous_authoring(text, fm, warnings);
         _check_human_gate_steps(text, warnings);
         _check_human_gate_phase_headings(text, warnings);
         _check_human_gate_exit_criteria(text, warnings);
         _check_external_population_gates(text, warnings);
+        _check_dated_waits(text, warnings);
     }
     return problems;
 }
 
+/**
+ * An open step that waits on a future date keeps an otherwise finished roadmap
+ * from reaching zero open steps, so a drain can never close it. Such a step
+ * belongs in a `stubs/` entry with its trigger. Same reading the drain queue
+ * uses, so the lint and the queue cannot disagree on what is time-gated.
+ */
+function _check_dated_waits(text: string, warnings: string[], today?: string): void {
+    const day = today ?? asOf().toISOString().slice(0, 10);
+    for (const step of screenRoadmap('', '', text, day).steps) {
+        if (step.cls !== 'time') continue;
+        warnings.push(
+            `step waits on a future date: "${step.text.slice(0, 80)}" — move it to a ` +
+                'stubs/ entry with its trigger so this roadmap can close when its work is done',
+        );
+    }
+}
+
 // Vague-step patterns (ask-when-uncertain trigger subset) — under
 // execution.mode: autonomous these guarantee mid-run ambiguity halts,
 // so they warn at authoring time instead. Warnings never fail the lint.
@@ -500,6 +534,69 @@ export function _check_relates(fm: string, problems: string[]): void {
     }
 }
 
+const BLOCKED_BY_FILE_PAT = /<!--[ \t]*blocked-by:[ \t]*((?:(?:later|stubs|archive)\/)?road-to-[a-z0-9-]+)#/g;
+
+function _relates_rows(fm: string): Array<{ slug: string; relation: string }> {
+    const rows: Array<{ slug: string; relation: string }> = [];
+    for (const chunk of fm.split(/^[ \t]*-[ \t]+slug:/m).slice(1)) {
+        const slug = /^[ \t]*['"]?([^\s'"#]+)/.exec(chunk)?.[1];
+        const relation = /^[ \t]+relation:[ \t]*['"]?([^\s'"#]+)/m.exec(chunk)?.[1];
+        if (slug && relation) rows.push({ slug, relation });
+    }
+    return rows;
+}
+
+function _is_archived(slug: string, roadmap_dir: string): boolean {
+    if (slug.startsWith('archive/')) return true;
+    const base = slug.replace(/^(?:later|stubs)\//, '');
+    return (
+        !fs.existsSync(path.join(roadmap_dir, `${slug}.md`)) &&
+        fs.existsSync(path.join(roadmap_dir, 'archive', `${base}.md`))
+    );
+}
+
+/**
+ * A step that waits on another roadmap says so twice or not at all: an inline
+ * `blocked-by: road-to-X#…` marker needs a `relates:` row for X with
+ * `relation: depends`, and a `depends` row may not name an archived file,
+ * which can no longer land the thing waited on. Both halves fail. The archived
+ * half warned rather than failed until 2026-10-17, while one active file still
+ * carried such a row; that row is now `extends` and the active glob carries
+ * none, so road-to-an-intake-the-queue-can-carry 1.2's flip condition is met.
+ * Neither half warns any more, so this check no longer takes a `warnings`
+ * sink; `lint_roadmap` still has one for the checks that do.
+ */
+export function _check_cross_file_waits(
+    text: string,
+    fm: string,
+    roadmap_dir: string,
+    problems: string[],
+): void {
+    const rows = _relates_rows(fm);
+    const strip = (s: string): string => s.replace(/^(?:later|stubs|archive)\//, '');
+    const depends = new Set(rows.filter((r) => r.relation === 'depends').map((r) => strip(r.slug)));
+    const seen = new Set<string>();
+    BLOCKED_BY_FILE_PAT.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = BLOCKED_BY_FILE_PAT.exec(text)) !== null) {
+        const target = strip(m[1]!);
+        if (seen.has(target) || depends.has(target)) continue;
+        seen.add(target);
+        problems.push(
+            `blocked-by marker names '${target}' but no relates: row declares it ` +
+                'with relation: depends (templates/roadmaps.md rule 18)',
+        );
+    }
+    for (const r of rows) {
+        if (r.relation === 'depends' && _is_archived(r.slug, roadmap_dir)) {
+            problems.push(
+                `depends row names '${r.slug}', which is under archive/ — an archived ` +
+                    'file lands nothing; drop the row or depend on its successor',
+            );
+        }
+    }
+}
+
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
         // Absent is VALID and stays valid — but it no longer means "interactive".
@@ -774,6 +871,7 @@ export {
     _frontmatter,
     _read_horizon_weeks,
     _read_complexity,
+    _check_dated_waits,
     lint_roadmap,
     main,
 };

package/src/scripts/lint_skill_link_reach.ts

@@ -24,6 +24,20 @@
  * not close the pattern: a two-link blind spot in a link checker is a link
  * checker that reports clean while missing exactly the shape most likely to rot.
  *
+ * Relative links resolve against their own file. A link inside `references/*.md`
+ * (recursively) is resolved against that file's directory, and a `SKILL.md`
+ * link into the skill's own `references/`, `scripts/`, `assets/` or `examples/`
+ * is resolved against the skill directory. A link that climbs out to `docs/` is
+ * its own reported class — `docs/` is not delivered, and
+ * `measure_docs_dead_links` owns that question. A link inside a fenced block or
+ * an inline code span, or one carrying an angle-bracket placeholder, is not a
+ * link. Any other `SKILL.md` link that leaves the skill directory and resolves
+ * to nothing in the delivered tree is checked against the skill's SOURCE
+ * directory (`src/skills/<slug>/`): a target that exists there is the named
+ * repo-only class — real, but not delivered — and is reported; a target that
+ * exists in neither tree is broken and fails (road-to-steps-the-skill-cannot-skip
+ * AC-1).
+ *
  * Exit codes: 0 clean · 1 unresolved link(s) · 2 usage / dead corpus.
  */
 import * as fs from 'node:fs';
@@ -49,6 +63,107 @@ export const DELIVERED_SKILLS_ROOT = 'dist/agent-src/skills';
  */
 const CROSS_SKILL_LINK = /\]\(\.\.\/([a-z0-9-]+)\/SKILL\.md/g;
 
+/** The same shape as a bare target — already checked against the delivered set. */
+const CROSS_SKILL_TARGET = /^\.\.\/[a-z0-9-]+\/SKILL\.md(?:#.*)?$/;
+
+/**
+ * Links from one reference file to a sibling reference of the same skill.
+ *
+ * A reference stays one level deep, so every reference is reached from the
+ * head. The ceiling is the count on 2026-10-16 and only moves down: above it
+ * fails, below it prints the lower figure to record.
+ */
+export const SIBLING_LINK_CEILING = 7;
+
+/**
+ * A procedure's step files (road-to-steps-the-skill-cannot-skip Phase 4) are the
+ * body split in order, not reference material, so the links they carry are the
+ * head's links and none of them counts as a sibling link.
+ */
+const STEPS_DIR = path.join('references', 'steps');
+
+/** The skill subdirectories a `SKILL.md` link may point into. */
+const OWN_SKILL_DIRS = /^(?:\.\/)?(?:references|scripts|assets|examples)\//;
+
+/** Where a delivered skill's source lives, relative to the repo root. */
+const SOURCE_SKILLS_ROOT = 'src/skills';
+
+/** A link that climbs out to `docs/`, which the installer does not deliver. */
+const DOCS_TARGET = /^(?:\.\.\/)+docs\//;
+
+/** Every inline markdown link target; a quoted title after it is tolerated. */
+const MARKDOWN_LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+/** Body text with fenced blocks and inline code spans removed. */
+export function linkableText(source: string): string {
+    const out: string[] = [];
+    let fence: string | null = null;
+    for (const line of source.split('\n')) {
+        const m = /^\s*(`{3,}|~{3,})/.exec(line);
+        const marker = m?.[1];
+        if (fence !== null) {
+            if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+            continue;
+        }
+        if (marker !== undefined) {
+            fence = marker;
+            continue;
+        }
+        out.push(line.replace(/`[^`]*`/g, ''));
+    }
+    return out.join('\n');
+}
+
+/** Relative link targets worth resolving: no scheme, no bare anchor, no placeholder. */
+export function relativeTargets(source: string): string[] {
+    const targets: string[] = [];
+    for (const m of linkableText(source).matchAll(MARKDOWN_LINK)) {
+        const target = m[1] as string;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('#') || target.startsWith('/')) continue;
+        if (/[<>]/.test(target)) continue;
+        targets.push(target);
+    }
+    return targets;
+}
+
+/** The absolute path a relative target names, or null for a bare anchor. */
+function resolveTarget(fromDir: string, target: string): string | null {
+    const bare = target.split('#')[0]?.split('?')[0] ?? '';
+    if (bare === '') return null;
+    let decoded = bare;
+    try {
+        decoded = decodeURIComponent(bare);
+    } catch {
+        // A malformed escape is checked under its raw spelling.
+    }
+    return path.resolve(fromDir, decoded);
+}
+
+function targetExists(fromDir: string, target: string): boolean {
+    const resolved = resolveTarget(fromDir, target);
+    return resolved === null || fs.existsSync(resolved);
+}
+
+/** Every markdown file under a skill's `references/`, recursively, sorted. */
+function referenceFiles(skillDir: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries.sort((x, y) => x.name.localeCompare(y.name))) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) walk(full);
+            else if (e.name.endsWith('.md')) out.push(full);
+        }
+    };
+    walk(path.join(skillDir, 'references'));
+    return out;
+}
+
 export interface UnresolvedLink {
     /** Skill whose body carries the link. */
     from: string;
@@ -62,6 +177,22 @@ export interface ReachReport {
     /** Cross-skill links examined. */
     links: number;
     unresolved: UnresolvedLink[];
+    /** Gated relative links resolved against their own file. */
+    fileLinks: number;
+    unresolvedFiles: UnresolvedFileLink[];
+    /** Links into `docs/` — not delivered; reported, never failing. */
+    docsLinks: number;
+    /** `SKILL.md` links whose target exists only in the source repository — reported, never failing. */
+    repoOnlyLinks: UnresolvedFileLink[];
+    /** Reference files linking a sibling reference of their own skill. */
+    siblingLinks: UnresolvedFileLink[];
+}
+
+export interface UnresolvedFileLink {
+    /** File carrying the link, relative to the delivered skills root. */
+    file: string;
+    /** The target exactly as written. */
+    target: string;
 }
 
 /** Every skill directory in the delivered tree. */
@@ -83,10 +214,17 @@ export function run(root: string, ledger?: GateLedger): ReachReport {
     const slugs = deliveredSkills(root);
     const present = new Set(slugs);
     const unresolved: UnresolvedLink[] = [];
+    const unresolvedFiles: UnresolvedFileLink[] = [];
+    const siblingLinks: UnresolvedFileLink[] = [];
+    const repoOnlyLinks: UnresolvedFileLink[] = [];
     let links = 0;
+    let fileLinks = 0;
+    let docsLinks = 0;
+    const skillsRoot = path.join(root, DELIVERED_SKILLS_ROOT);
     for (const slug of slugs) {
         ledger?.plan(slug);
-        const file = path.join(root, DELIVERED_SKILLS_ROOT, slug, 'SKILL.md');
+        const skillDir = path.join(skillsRoot, slug);
+        const file = path.join(skillDir, 'SKILL.md');
         let source: string;
         try {
             source = fs.readFileSync(file, 'utf-8');
@@ -106,10 +244,61 @@ export function run(root: string, ledger?: GateLedger): ReachReport {
                 bad += 1;
             }
         }
-        if (bad > 0) ledger?.fail(slug, `${String(bad)} unresolved cross-skill link(s)`);
+        for (const target of relativeTargets(source)) {
+            if (CROSS_SKILL_TARGET.test(target)) continue;
+            if (DOCS_TARGET.test(target)) {
+                docsLinks += 1;
+                continue;
+            }
+            const exists = targetExists(skillDir, target);
+            fileLinks += 1;
+            if (!exists && !OWN_SKILL_DIRS.test(target) && targetExists(path.join(root, SOURCE_SKILLS_ROOT, slug), target)) {
+                repoOnlyLinks.push({ file: `${slug}/SKILL.md`, target });
+                continue;
+            }
+            if (!exists) {
+                unresolvedFiles.push({ file: `${slug}/SKILL.md`, target });
+                bad += 1;
+            }
+        }
+        for (const ref of referenceFiles(skillDir)) {
+            const rel = path.relative(skillsRoot, ref).split(path.sep).join('/');
+            for (const target of relativeTargets(fs.readFileSync(ref, 'utf-8'))) {
+                if (DOCS_TARGET.test(target)) {
+                    docsLinks += 1;
+                    continue;
+                }
+                fileLinks += 1;
+                if (!targetExists(path.dirname(ref), target)) {
+                    unresolvedFiles.push({ file: rel, target });
+                    bad += 1;
+                    continue;
+                }
+                const resolved = resolveTarget(path.dirname(ref), target);
+                if (
+                    resolved !== null &&
+                    resolved !== ref &&
+                    resolved.endsWith('.md') &&
+                    resolved.startsWith(path.join(skillDir, 'references') + path.sep) &&
+                    !ref.startsWith(path.join(skillDir, STEPS_DIR) + path.sep)
+                ) {
+                    siblingLinks.push({ file: rel, target });
+                }
+            }
+        }
+        if (bad > 0) ledger?.fail(slug, `${String(bad)} unresolved link(s)`);
         else ledger?.complete(slug);
     }
-    return { delivered: slugs.length, links, unresolved };
+    return {
+        delivered: slugs.length,
+        links,
+        unresolved,
+        fileLinks,
+        unresolvedFiles,
+        docsLinks,
+        repoOnlyLinks,
+        siblingLinks,
+    };
 }
 
 /** Self-test. The rejecting case is a link to a skill that is not delivered. */
@@ -128,8 +317,8 @@ function selfTest(): number {
     try {
         return runSelfTest({
             gate: 'lint_skill_link_reach',
-            minCases: 4,
-            minRejectCases: 2,
+            minCases: 5,
+            minRejectCases: 3,
             cases: [
                 {
                     name: 'a link to a skill that is NOT delivered is rejected',
@@ -149,6 +338,19 @@ function selfTest(): number {
                         return invoke();
                     },
                 },
+                {
+                    name: 'a references/ link one ../ short is rejected',
+                    expect: 'reject',
+                    run: () => {
+                        fresh();
+                        mk('a', 'body\n');
+                        mk('b', 'body\n');
+                        const refs = path.join(tmp, DELIVERED_SKILLS_ROOT, 'a', 'references');
+                        fs.mkdirSync(refs, { recursive: true });
+                        fs.writeFileSync(path.join(refs, 'r.md'), 'see [b](../b/SKILL.md)\n', 'utf-8');
+                        return invoke();
+                    },
+                },
                 {
                     name: 'a link to a delivered skill is accepted',
                     expect: 'accept',
@@ -188,6 +390,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const root = rootArg === undefined ? REPO_ROOT : path.resolve(rootArg);
     const quiet = argv.includes('--quiet');
     const isFixture = root !== REPO_ROOT;
+    const ceilingIdx = argv.indexOf('--sibling-ceiling');
+    const siblingCeiling = ceilingIdx >= 0 ? Number(argv[ceilingIdx + 1]) : SIBLING_LINK_CEILING;
+    if (!Number.isInteger(siblingCeiling) || siblingCeiling < 0) {
+        process.stderr.write('lint_skill_link_reach: --sibling-ceiling takes a non-negative integer\n');
+        return 2;
+    }
 
     const ledger = isFixture ? undefined : new GateLedger('lint_skill_link_reach');
     const report = run(root, ledger);
@@ -214,8 +422,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         throw e;
     }
 
-    if (report.unresolved.length > 0) {
-        if (!quiet) {
+    if (report.unresolved.length > 0 || report.unresolvedFiles.length > 0) {
+        if (!quiet && report.unresolved.length > 0) {
             process.stderr.write(
                 `❌  lint_skill_link_reach: ${String(report.unresolved.length)} cross-skill link(s) ` +
                     `do not resolve inside ${DELIVERED_SKILLS_ROOT}:\n`,
@@ -228,14 +436,48 @@ export function main(argv: string[] = process.argv.slice(2)): number {
                     '   delivered set, or the link should point at something that is.\n',
             );
         }
+        if (!quiet && report.unresolvedFiles.length > 0) {
+            process.stderr.write(
+                `❌  lint_skill_link_reach: ${String(report.unresolvedFiles.length)} relative link(s) ` +
+                    `resolve to nothing against their own file inside ${DELIVERED_SKILLS_ROOT}:\n`,
+            );
+            for (const u of report.unresolvedFiles) process.stderr.write(`   ${u.file} → ${u.target}\n`);
+            process.stderr.write(
+                '   A link inside references/ resolves against references/, so it needs one more\n' +
+                    '   ../ than the same link written in SKILL.md.\n',
+            );
+        }
+        ledger?.report(quiet ? () => undefined : undefined);
+        return 1;
+    }
+    const siblings = report.siblingLinks.length;
+    if (siblings > siblingCeiling) {
+        if (!quiet) {
+            process.stderr.write(
+                `❌  lint_skill_link_reach: ${String(siblings)} reference-to-sibling-reference link(s), ` +
+                    `ceiling ${String(siblingCeiling)}. A reference file links no sibling reference of its ` +
+                    'own skill — link it from SKILL.md instead:\n',
+            );
+            for (const s of report.siblingLinks) process.stderr.write(`   ${s.file} → ${s.target}\n`);
+        }
         ledger?.report(quiet ? () => undefined : undefined);
         return 1;
     }
+    if (!quiet && siblings < siblingCeiling) {
+        process.stdout.write(
+            `   sibling-reference links fell to ${String(siblings)} — lower SIBLING_LINK_CEILING ` +
+                `from ${String(siblingCeiling)} to ${String(siblings)}.\n`,
+        );
+    }
     ledger?.report(quiet ? () => undefined : undefined);
     if (!quiet) {
         process.stdout.write(
-            `✅  lint_skill_link_reach: ${String(report.links)} cross-skill link(s) across ` +
-                `${String(report.delivered)} delivered skill(s) all resolve.\n`,
+            `✅  lint_skill_link_reach: ${String(report.links)} cross-skill link(s) and ` +
+                `${String(report.fileLinks)} relative link(s) across ` +
+                `${String(report.delivered)} delivered skill(s) all resolve.\n` +
+                `   reported, not gated: ${String(report.docsLinks)} link(s) into docs/ (not delivered — ` +
+                `measure_docs_dead_links owns them) · ${String(report.repoOnlyLinks.length)} SKILL.md ` +
+                `link(s) to a repo-only target (exists in the source repository, not delivered).\n`,
         );
     }
     return 0;