@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/lint_plan_risk_register.ts

@@ -42,6 +42,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { isAcceptanceCriteriaHeading } from './_lib/ac_heading.js';
+import { asOfMs } from './_lib/as_of.js';
 import { workspaceIdentity } from './_lib/git_common_dir.js';
 import { gitEnv } from './_lib/git_env.js';
 import { splitMarkdownRow } from './_lib/md_table.js';
@@ -609,6 +610,12 @@ function _reviewedIn(text: string): string | null {
  * reviewed exactly as the contract asks — every author-today/merge-tomorrow PR
  * reproduces it.
  *
+ * Within the run, a commit dated on or before the stamp is preferred, newest
+ * first: the marker takes a bare date, so a plan changed again the same day it
+ * was reviewed has no later value to write, and the contract (§ 1, "Residual
+ * (accepted)") resolves that same-day pair in favour of passing. A run with no
+ * such commit falls back to the commit that introduced the stamp.
+ *
  * The oldest commit of the run is the honest baseline, and the age matters:
  * comparing against the NEWEST commit carrying the stamp would compare the
  * current content with itself, making every committed file trivially fresh and
@@ -620,12 +627,22 @@ function _stampIntroducedAt(
     reviewed: string,
 ): HistoryEntry | undefined {
     let introduced: HistoryEntry | undefined;
+    let sameDay: HistoryEntry | undefined;
     for (const entry of history) {
         const blob = _blobAt(absPath, entry.sha);
         if (blob === null || _reviewedIn(blob) !== reviewed) break;
         introduced = entry;
+        // History is newest-first, so the first run member dated on or before
+        // the stamp is the newest such commit: a change committed the day the
+        // stamp names is covered by it (contract § 1, accepted residual).
+        if (sameDay === undefined && entry.date <= reviewed) sameDay = entry;
     }
-    return introduced;
+    return sameDay ?? introduced;
+}
+
+/** The latest calendar day anywhere on earth at the as-of instant (UTC+14), so no author's real today reads as future. */
+function _latestToday(now: number = asOfMs()): string {
+    return new Date(now + 14 * 3_600_000).toISOString().slice(0, 10);
 }
 
 export type FileStatus = 'ok' | 'draft-exempt' | 'grandfathered' | 'fail';
@@ -689,6 +706,16 @@ export function checkFile(absPath: string): FileResult {
         };
     }
     const violations = [...content.violations];
+    // A stamp after today would cover every commit made until that date as
+    // "reviewed" — the same-day residual of contract § 1 holds for today only.
+    if (content.reviewed !== null && content.reviewed > _latestToday()) {
+        violations.push({
+            file: absPath,
+            line: 1,
+            kind: 'future_review',
+            detail: `\`reviewed: ${content.reviewed}\` is later than today — stamp the day the review happened`,
+        });
+    }
     // A file with uncommitted modifications has no committed baseline for the
     // current content, so staleness is not judgeable — see
     // hasUncommittedChanges. The committed-history case below is unchanged.

package/src/scripts/lint_positioning.ts

@@ -2,7 +2,7 @@
 /**
  * Positioning consistency lint for event4u/agent-config.
  *
- * Ported from the retired Python `src/scripts/lint_positioning.py` (ADR-200, Phase 4 /
+ * Ported from its retired Python twin (ADR-200, Phase 4 /
  * Wave 4b). Mirrors the CLI contract EXACTLY — the `--quiet` argparse flag,
  * exit codes (0 clean, 1 drift, 2 missing PyYAML — inert here since `yaml`
  * is always present), byte-identical stdout (success line) and stderr
@@ -134,8 +134,8 @@ interface ParsedArgs {
 }
 
 function _argparse_error(message: string): never {
-    process.stderr.write('usage: lint_positioning.py [-h] [--quiet]\n');
-    process.stderr.write(`lint_positioning.py: error: ${message}\n`);
+    process.stderr.write('usage: lint_positioning [-h] [--quiet]\n');
+    process.stderr.write(`lint_positioning: error: ${message}\n`);
     process.exit(2);
 }
 
@@ -145,7 +145,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         if (arg === '--quiet') {
             quiet = true;
         } else if (arg === '-h' || arg === '--help') {
-            process.stdout.write('usage: lint_positioning.py [-h] [--quiet]\n');
+            process.stdout.write('usage: lint_positioning [-h] [--quiet]\n');
             process.exit(0);
         } else {
             _argparse_error(`unrecognized arguments: ${arg}`);

package/src/scripts/lint_provenance.ts

@@ -76,6 +76,7 @@ const WEAK_COPYLEFT_SPDX_IDS = [
     'LGPL-2.1-only', 'LGPL-2.1-or-later', 'LGPL-2.1',
     'LGPL-3.0-only', 'LGPL-3.0-or-later', 'LGPL-3.0',
     'EPL-1.0', 'EPL-2.0', 'CDDL-1.0', 'CDDL-1.1',
+    'OFL-1.1',
 ];
 // The conservative fallback deny set (GPL/AGPL/SSPL family) — see the header
 // comment. Also part of the known-SPDX-id catalog, so a real GPL/AGPL/SSPL

package/src/scripts/lint_roadmap_blockers.ts

@@ -201,6 +201,18 @@ interface TargetIndex {
  */
 const USER_DECISION_OWNER_RE = /^-[ \t]*\*\*Owner:\*\*[ \t]*(maintainer|user|owner)\b/im;
 
+/**
+ * Template rule 20 "Route before you file": a human-owned blocker records the
+ * council verdict that sent it to a human, or why no council could be asked.
+ * Absent is ratcheted (the backlog predates the field); present-but-malformed
+ * is hard, since no entry carried the field on the day it shipped. Counted over
+ * this lint's own scope, so a blocker filed straight into a parked roadmap is
+ * not seen — parking itself is held by check_estate_count's later_roadmaps floor.
+ */
+const ROUTED_FIELD_RE = /^-[ \t]*\*\*Routed:\*\*[ \t]*(.*)$/im;
+const ROUTED_VALUE_RE =
+    /^(?:council[ \t]+\d{4}-\d{2}-\d{2}[ \t]+ESCALATE[ \t]+[—-][ \t]*\S|pending[ \t]+[—-][ \t]*\S)/;
+
 const REQUIRED_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
     ['Status', /^-[ \t]*\*\*Status:\*\*/im],
     ['Owner', /^-[ \t]*\*\*Owner:\*\*/im],
@@ -327,6 +339,8 @@ interface ScanResult {
     hard: Violation[];
     /** Open entries that are not yet decidable — counted against the ratchet. */
     decidability: Violation[];
+    /** Open human-owned entries with no `Routed:` field — counted against its own ratchet. */
+    routing: Violation[];
 }
 
 /** What a scan needs to resolve a qualified reference: who it is, and where it may point. */
@@ -339,6 +353,7 @@ interface ScanContext {
 function _scanBoth(rawText: string, ctx: ScanContext = {}): ScanResult {
     const violations: Violation[] = [];
     const decidability: Violation[] = [];
+    const routing: Violation[] = [];
     const text = _stripFencedCode(rawText);
     const declaredIds = new Set<string>();
     const userDecisionIds = new Set<string>();
@@ -452,6 +467,24 @@ function _scanBoth(rawText: string, ctx: ScanContext = {}): ScanResult {
                         });
                     }
                 }
+                if (USER_DECISION_OWNER_RE.test(body)) {
+                    const routed = ROUTED_FIELD_RE.exec(body);
+                    const at = _lineAt(text, sectionStart + cur.start);
+                    if (routed === null) {
+                        routing.push({
+                            line: at,
+                            message: `blocker '${cur.id}' has a human Owner but no **Routed:** field`,
+                        });
+                    } else if (!ROUTED_VALUE_RE.test((routed[1] as string).trim())) {
+                        violations.push({
+                            line: at,
+                            message:
+                                `blocker '${cur.id}' declares **Routed:** '${(routed[1] as string).trim()}' — ` +
+                                "expected 'council YYYY-MM-DD ESCALATE — <reserved row>' or " +
+                                "'pending — <why the council was unreachable>' (templates/roadmaps.md rule 20)",
+                        });
+                    }
+                }
                 const gaps = DECIDABILITY_FIELDS.filter(([, re]) => !re.test(body)).map(
                     ([name]) => name,
                 );
@@ -518,7 +551,8 @@ function _scanBoth(rawText: string, ctx: ScanContext = {}): ScanResult {
     }
     violations.sort((a, b) => a.line - b.line);
     decidability.sort((a, b) => a.line - b.line);
-    return { hard: violations, decidability };
+    routing.sort((a, b) => a.line - b.line);
+    return { hard: violations, decidability, routing };
 }
 
 interface LocalBlockers {
@@ -534,7 +568,7 @@ interface LocalBlockers {
  * `<roadmap-stem>#<id>` resolves against the in-scope target named — never
  * estate-wide, so an unrelated roadmap adding a same-named blocker cannot change
  * what an existing marker means. A target that is declared but resolved makes
- * the marker STALE: `run-continuation` treats every marker as blocked, so a
+ * the marker STALE: the withdrawn `run-continuation` treated every marker as blocked, so a
  * marker on a resolved blocker would hold a step nothing holds any more.
  * "Superseded" is not a state — the format has no replacement pointer, so a
  * moved blocker is a reference to update, reported here as missing.
@@ -885,13 +919,20 @@ function main(): number {
     const index = _targetIndex();
     let failed = 0;
     const undecidable: Array<{ rel: string; v: Violation }> = [];
+    const unrouted: Array<{ rel: string; v: Violation }> = [];
     for (const roadmap of roadmaps) {
         const rel = _relPosix(roadmap, REPO_ROOT);
         const text = fs.readFileSync(roadmap, 'utf-8');
-        const { hard, decidability } = _scanBoth(text, { selfStem: path.basename(roadmap, '.md'), index });
+        const { hard, decidability, routing } = _scanBoth(text, {
+            selfStem: path.basename(roadmap, '.md'),
+            index,
+        });
         for (const v of decidability) {
             undecidable.push({ rel, v });
         }
+        for (const v of routing) {
+            unrouted.push({ rel, v });
+        }
         if (hard.length) {
             failed += 1;
             process.stderr.write(`❌  ${rel}\n`);
@@ -962,10 +1003,30 @@ function main(): number {
                 '    **What to do:** carrying a command, a path or an enumerated option set.\n' +
                 '    See templates/roadmaps.md rule 20.\n',
         );
+    }
+    const routingVerdict = checkRatchet({
+        gate: 'lint_roadmap_blockers:routing',
+        actual: unrouted.length,
+        repoRoot: REPO_ROOT,
+    });
+    if (!routingVerdict.ok) {
+        process.stderr.write(`❌  ${routingVerdict.message}\n`);
+        for (const { rel, v } of unrouted) {
+            process.stderr.write(`    ${rel}:${v.line}: ${v.message}\n`);
+        }
+        process.stderr.write(
+            '\n    Route a human-owned blocker through the council before filing it, and record\n' +
+                "    **Routed:** council YYYY-MM-DD ESCALATE — <reserved row>, or 'pending — <reason>'\n" +
+                '    when no council could be reached. A DECIDE is a ## Decisions row, not a blocker.\n' +
+                '    See templates/roadmaps.md rule 20 "Route before you file".\n',
+        );
+    }
+    if (!verdict.ok || !routingVerdict.ok) {
         return 1;
     }
     if (!QUIET) {
         process.stdout.write(`\n✅  ${roadmaps.length} roadmap(s) blocker-contract-clean\n`);
+        process.stdout.write(`✅  ${routingVerdict.message}\n`);
         process.stdout.write(
             `✅  0 blocker id(s) open in both an active and an archived roadmap ` +
                 `(${_globArchivedRoadmaps().length} archived file(s) read)\n`,
@@ -998,7 +1059,7 @@ function _isCliEntry(): boolean {
 }
 
 if (_isCliEntry() || process.argv[1] === _HERE) {
-    process.exit(main());
+    process.exitCode = main();
 }
 
 export {

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,
 };