@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/lint_roadmap_later_disposition.ts

@@ -23,10 +23,48 @@
  *      sitting in the active tree silently counts as backlog the dashboard and
  *      ``/roadmap:process-*`` would try to execute.
  *
- *   B. Every roadmap under ``agents/roadmaps/later/`` MUST record a **resume
- *      condition** so it never rots without a "when does it come back": either
- *      ``status: later`` frontmatter, or a body line matching
- *      ``Blocked until`` / ``Resume when`` / ``Trigger`` (case-insensitive).
+ *   B. Every parked roadmap MUST record a **wake
+ *      condition** so it never rots without a "when does it come back".
+ *
+ *      Until 2026-09-07 this rule short-circuited on the frontmatter STATUS
+ *      word: ``if (status !== 'later' && !RESUME_RE.test(body))``, so a file
+ *      whose frontmatter said ``status: later`` passed with no resume text
+ *      present at all. Measured over the tree at that date, 63 of 82 parked
+ *      roadmaps passed on the status word alone, 8 on a real ``Blocked until``
+ *      / ``Resume when``, and 11 on the bare word ``trigger`` — so 74 of 82
+ *      carried no machine-readable wake condition. The word ``trigger`` was
+ *      the second hole: a body that merely mentions it in passing ("the
+ *      trigger fires on push") satisfied a governance gate.
+ *
+ *      The corrected contract, in force regardless of ``status``:
+ *
+ *        1. **Structured** — an ``entry_condition:`` MAPPING in the
+ *           frontmatter with three non-empty parts:
+ *
+ *             entry_condition:
+ *               what: what would change the decision
+ *               when: when that could arrive
+ *               who:  who would have to act (``none`` is a legal answer)
+ *
+ *           A condition that cannot be observed is a deferral wearing a
+ *           condition's clothes, which is why all three are required and why
+ *           blankness is not the same answer as ``none``.
+ *
+ *        2. **Legacy** — a body line matching ``Blocked until`` /
+ *           ``Resume when`` / ``blocked-until`` / ``resume-when``. Kept so the
+ *           ratchet below has a floor to walk DOWN toward rather than a tree
+ *           to fail on the day it lands.
+ *
+ *      A malformed ``entry_condition`` (scalar, or missing a part) is a HARD
+ *      finding and is never baselined: it is a defect the author introduced in
+ *      the change that wrote it, not inherited debt.
+ *
+ *   C. Every parked roadmap MUST carry ``review_by``
+ *      in its frontmatter. Ratcheted from the measured count, same reasoning.
+ *
+ *      Both ratchets live in ``src/config/gate-violation-baselines.json`` under
+ *      ``lint_roadmap_later_disposition:wake-condition`` and
+ *      ``…:review-by``: the count may fall and never rise.
  *
  * Rationale: "roadmaps with open tasks deferred for later are always moved to
  * ``later/``" (user directive 2026-06-16). The active tree holds only roadmaps
@@ -44,6 +82,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -64,8 +103,17 @@ function _setRoadmapRootForTest(p: string): void {
 const FRONTMATTER_RE = /^---[ \t\f\v]*\n([\s\S]*?)\n---[ \t\f\v]*\n/;
 // STATUS_RE = re.compile(r"^status:\s*([A-Za-z0-9_-]+)\s*$", re.MULTILINE)
 const STATUS_RE = /^status:[ \t\f\v\r\n]*([A-Za-z0-9_-]+)[ \t\f\v\r]*$/m;
-// RESUME_RE = re.compile(r"\b(blocked until|resume when|trigger|blocked-until|resume-when)\b", re.IGNORECASE)
-const RESUME_RE = /\b(blocked until|resume when|trigger|blocked-until|resume-when)\b/i;
+// The four UNAMBIGUOUS phrases. `trigger` was dropped 2026-09-07: it matched
+// any prose mention of the word, so 11 of 82 parked roadmaps satisfied a
+// governance gate on a sentence about something else entirely.
+const RESUME_RE = /\b(blocked until|resume when|blocked-until|resume-when)\b/i;
+
+/** Ratchet keys in `src/config/gate-violation-baselines.json`. */
+export const WAKE_GATE = 'lint_roadmap_later_disposition:wake-condition';
+export const REVIEW_BY_GATE = 'lint_roadmap_later_disposition:review-by';
+
+/** The three parts a structured `entry_condition` must name. */
+export const ENTRY_CONDITION_PARTS = ['what', 'when', 'who'] as const;
 
 // Non-roadmap files that live in the tree but are not roadmaps.
 const EXCLUDE_NAMES: ReadonlySet<string> = new Set([
@@ -79,6 +127,67 @@ const EXCLUDE_PREFIXES: readonly string[] = ['open-questions'];
 interface Violation {
     file: string;
     reason: string;
+    /**
+     * `hard` fails immediately; `wake` and `review-by` are ratcheted against a
+     * committed baseline. A hard finding is one the AUTHOR introduced (a
+     * malformed structured field, a misplaced `status: later`); a ratcheted one
+     * is debt the corrected gate revealed.
+     */
+    cls: 'hard' | 'wake' | 'review-by';
+}
+
+/**
+ * The three-part reading of a structured `entry_condition`.
+ *
+ * Deliberately parsed from the raw frontmatter text rather than through a YAML
+ * loader: this gate's contract is byte-pinned against a retired Python
+ * implementation and must not acquire a parser dependency whose error
+ * behavior differs. The shape is fixed and shallow, so a line reader is
+ * sufficient and its failure mode is legible.
+ */
+export function entryConditionParts(frontmatter: string): {
+    present: boolean;
+    scalar: boolean;
+    parts: Record<string, string>;
+} {
+    const lines = frontmatter.split('\n');
+    const idx = lines.findIndex((l) => /^entry_condition:/.test(l));
+    if (idx === -1) {
+        return { present: false, scalar: false, parts: {} };
+    }
+    const head = (lines[idx] as string).slice('entry_condition:'.length).trim();
+    if (head !== '') {
+        // `entry_condition: "…"` — the pre-contract scalar form.
+        return { present: true, scalar: true, parts: {} };
+    }
+    const parts: Record<string, string> = {};
+    for (let i = idx + 1; i < lines.length; i++) {
+        const line = lines[i] as string;
+        if (!/^\s+\S/.test(line)) break;
+        const m = /^\s+([a-z_]+):\s*(.*)$/.exec(line);
+        if (m === null) continue;
+        parts[m[1] as string] = _unquote((m[2] as string).trim());
+    }
+    return { present: true, scalar: false, parts };
+}
+
+function _unquote(v: string): string {
+    if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+        return v.slice(1, -1).trim();
+    }
+    return v.trim();
+}
+
+/** Missing / empty part names, `[]` when the field satisfies the contract. */
+export function entryConditionProblems(frontmatter: string): string[] {
+    const read = entryConditionParts(frontmatter);
+    if (!read.present) return ['absent'];
+    if (read.scalar) return ['scalar'];
+    const missing: string[] = [];
+    for (const part of ENTRY_CONDITION_PARTS) {
+        if ((read.parts[part] ?? '').trim() === '') missing.push(part);
+    }
+    return missing;
 }
 
 function _is_roadmap(p: string): boolean {
@@ -167,6 +276,7 @@ function check(root: string): Violation[] {
         if (status === 'later' && !in_later) {
             out.push({
                 file: rel,
+                cls: 'hard',
                 reason:
                     'frontmatter `status: later` but file is not under ' +
                     '`agents/roadmaps/later/` — a blocked-for-later roadmap ' +
@@ -175,19 +285,57 @@ function check(root: string): Violation[] {
             });
         }
 
-        // Rule B — every later/ roadmap records a resume condition.
-        if (in_later) {
-            const body = text.slice(_frontmatter(text).length);
-            if (status !== 'later' && !RESUME_RE.test(body)) {
-                out.push({
-                    file: rel,
-                    reason:
-                        'roadmap under `agents/roadmaps/later/` has no resume ' +
-                        'condition — add `status: later` to the frontmatter or a ' +
-                        '`Blocked until` / `Resume when` / `Trigger` line so it ' +
-                        'records when the work comes back.',
-                });
-            }
+        if (!in_later) {
+            continue;
+        }
+
+        const fm = _frontmatter(text);
+        const body = text.slice(fm.length);
+        const problems = entryConditionProblems(fm);
+        const structured = problems.length === 0;
+
+        // Rule B(1) — a PRESENT entry_condition must satisfy the contract.
+        // Hard, never ratcheted: a malformed field is authored, not inherited.
+        if (!structured && problems[0] !== 'absent') {
+            out.push({
+                file: rel,
+                cls: 'hard',
+                reason:
+                    problems[0] === 'scalar'
+                        ? '`entry_condition` is a scalar string — it must be a mapping naming ' +
+                          '`what` (what would change the decision), `when` (when it could ' +
+                          'arrive) and `who` (who would have to act; `none` is a legal answer).'
+                        : '`entry_condition` is missing or blank in: ' +
+                          problems.join(', ') +
+                          '. A condition that cannot be observed is a deferral wearing a ' +
+                          "condition's clothes; `none` is a legal answer for `who` and " +
+                          'blankness is not.',
+            });
+        }
+
+        // Rule B(2) — a wake condition is required REGARDLESS of `status`.
+        if (!structured && !RESUME_RE.test(body)) {
+            out.push({
+                file: rel,
+                cls: 'wake',
+                reason:
+                    'roadmap under `agents/roadmaps/later/` has no wake condition — the ' +
+                    'frontmatter `status` word no longer satisfies this gate, and neither ' +
+                    'does the bare word `trigger`. Add a structured `entry_condition` ' +
+                    '(`what` / `when` / `who`) or a `Blocked until` / `Resume when` line.',
+            });
+        }
+
+        // Rule C — review_by in the frontmatter of every parked roadmap.
+        if (!/^review_by:\s*\S/m.test(fm)) {
+            out.push({
+                file: rel,
+                cls: 'review-by',
+                reason:
+                    'roadmap under `agents/roadmaps/later/` has no `review_by:` in its ' +
+                    'frontmatter — a park with no review date is indistinguishable from ' +
+                    'an abandonment.',
+            });
         }
     }
     return out;
@@ -337,24 +485,65 @@ function main(argv?: readonly string[]): number {
     }
 
     const violations = check(ROADMAP_ROOT);
+    const hard = violations.filter((v) => v.cls === 'hard');
+    const wake = violations.filter((v) => v.cls === 'wake');
+    const reviewBy = violations.filter((v) => v.cls === 'review-by');
 
     if (args.json) {
-        // json.dumps([asdict(v) for v in violations], indent=2)
-        const payload = violations.map((v) => ({ file: v.file, reason: v.reason }));
+        // The `file` / `reason` pair is the pinned shape; `cls` is additive, so
+        // a consumer reading the two original keys is unaffected.
+        const payload = violations.map((v) => ({ file: v.file, reason: v.reason, cls: v.cls }));
         process.stdout.write(_jsonDumpsIndent2(payload) + '\n');
-    } else if (violations.length) {
+        // A JSON consumer wants the findings, not the ratchet verdict; the exit
+        // code still carries it.
+        return _verdict(hard, wake, reviewBy, true);
+    }
+
+    if (hard.length) {
         process.stdout.write('❌  later/ disposition violations:\n');
-        for (const v of violations) {
+        for (const v of hard) {
             process.stdout.write(`   • ${v.file}\n       ${v.reason}\n`);
         }
-    } else {
+    }
+    return _verdict(hard, wake, reviewBy, false);
+}
+
+/**
+ * Ratcheted verdict. The two revealed-debt classes print their findings either
+ * way — at baseline they are the backlog this gate is walking down, and
+ * printing them is what makes the next lowering possible.
+ */
+function _verdict(
+    hard: readonly Violation[],
+    wake: readonly Violation[],
+    reviewBy: readonly Violation[],
+    quiet: boolean,
+): number {
+    let failed = hard.length > 0;
+    for (const [gate, found] of [
+        [WAKE_GATE, wake],
+        [REVIEW_BY_GATE, reviewBy],
+    ] as const) {
+        const verdict = checkRatchet({ gate, actual: found.length, repoRoot: REPO_ROOT });
+        if (!verdict.ok) {
+            failed = true;
+            if (!quiet) {
+                for (const v of found) {
+                    process.stderr.write(`   • ${v.file}\n       ${v.reason}\n`);
+                }
+                process.stderr.write(`❌  ${verdict.message}\n`);
+            }
+        } else if (!quiet) {
+            process.stdout.write(`✅  ${verdict.message}\n`);
+        }
+    }
+    if (!failed && !quiet) {
         process.stdout.write(
             '✅  later/ disposition: every blocked-for-later roadmap is parked ' +
-                'correctly with a resume condition.\n',
+                'correctly, and both wake-condition ratchets hold.\n',
         );
     }
-
-    return violations.length ? 1 : 0;
+    return failed ? 1 : 0;
 }
 
 function _isCliEntry(): boolean {
@@ -386,6 +575,7 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 export {
     REPO_ROOT,
     ROADMAP_ROOT,
+    type Violation,
     LATER_DIR,
     FRONTMATTER_RE,
     STATUS_RE,

package/src/scripts/lint_skill_frontmatter_safety.ts

@@ -138,9 +138,19 @@ export function grantSurface(rel: string): GrantSurface {
 }
 
 export function _scan(sf: sl.ScannedFile): sl.Finding[] {
-    if (sf.pragma_allows(CHECK)) {
-        return [];
+    // A BOUND pragma suppresses only the matches it fingerprints, so the scan
+    // runs and its output is filtered at the end. An UNBOUND one keeps the old
+    // whole-file bail and reports itself.
+    const pragmaForm = sf.pragma_form(CHECK);
+    if (pragmaForm === 'legacy') {
+        return [sl.legacy_pragma_finding(sf, CHECK)];
     }
+    // EVERY exit from this function goes through `finish`. Wrapping only the
+    // terminal `return` is the defect that shipped for one commit here: this
+    // scan has an early return for an artifact with no `execution:` block, and a
+    // bound pragma silently did not apply to exactly those artifacts.
+    const finish = (hits: sl.Finding[]): sl.Finding[] =>
+        pragmaForm === 'bound' ? sf.filter_bound_pragma(CHECK, hits) : hits;
     const fm = _frontmatter(sf);
     if (!fm) {
         return [];
@@ -261,7 +271,7 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
     }
 
     if (Object.keys(ex).length === 0) {
-        return out;
+        return finish(out);
     }
     const etype = _stripQuotes((ex['type'] ?? [0, ''])[1]);
     const safety = _stripQuotes((ex['safety_mode'] ?? [0, ''])[1]);
@@ -331,15 +341,17 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
             ),
         );
     }
-    return out;
+    return finish(out);
 }
 
 interface Args {
+    /** Scan base for the bounded root mode; absent = the package root. */
+    root?: string;
     json: boolean;
 }
 
 function _argError(msg: string): never {
-    process.stderr.write('usage: lint_skill_frontmatter_safety [-h] [--json]\n');
+    process.stderr.write('usage: lint_skill_frontmatter_safety [-h] [--json] [--root DIR]\n');
     process.stderr.write(`lint_skill_frontmatter_safety: error: ${msg}\n`);
     process.exit(2);
 }
@@ -347,12 +359,28 @@ function _argError(msg: string): never {
 function parse_args(argv: readonly string[]): Args {
     const out: Args = { json: false };
     const extra: string[] = [];
+    let rootPending = false;
     for (const a of argv) {
+        if (rootPending) {
+            out.root = a;
+            rootPending = false;
+            continue;
+        }
         if (a === '-h' || a === '--help') {
-            process.stdout.write('usage: lint_skill_frontmatter_safety [-h] [--json]\n');
+            process.stdout.write('usage: lint_skill_frontmatter_safety [-h] [--json] [--root DIR]\n');
             process.exit(0);
         } else if (a === '--json') {
             out.json = true;
+        } else if (a === '--root' || a.startsWith('--root=')) {
+            // Bounded root mode. Absent, this linter's own default roots stand;
+            // present, the same relative roots resolve against DIR instead. Used by
+            // the scout to scan a quarantined candidate, and by --self-test fixtures.
+            const eq = a.indexOf('=');
+            if (eq !== -1) {
+                out.root = a.slice(eq + 1);
+            } else {
+                rootPending = true;
+            }
         } else {
             extra.push(a);
         }
@@ -365,6 +393,7 @@ function parse_args(argv: readonly string[]): Args {
 
 export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
+    const scanBase = args.root === undefined ? sl.ROOT : path.resolve(args.root);
 
     const findings: sl.Finding[] = [];
     // `src/subagents` is the fourth root, added because its omission is what made
@@ -372,7 +401,7 @@ export function main(argv: readonly string[] | null = null): number {
     // bare shell lives there, and the gate had never read it.
     const roots = ['src/skills', 'src/agent-src', 'src/domains', 'src/subagents'];
     let scanned = 0;
-    for (const sf of sl.iter_corpus(roots, ['.md'])) {
+    for (const sf of sl.iter_corpus(roots, ['.md'], scanBase)) {
         scanned += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
@@ -400,6 +429,13 @@ export function main(argv: readonly string[] | null = null): number {
         throw exc;
     }
 
+    // Publish what this child inspected so the umbrella can aggregate a real
+    // corpus size rather than a count of children. Same number the assertion
+    // above just accepted, so the published figure cannot drift from it.
+    if (args.json) {
+        sl.report_child_scanned(scanned);
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_skill_trigger_contradiction.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env tsx
+/**
+ * A skill may not say "explicit request only" and publish auto-trigger keywords.
+ *
+ * The description is consumed — it is the frontmatter a catalogue and a host
+ * surface read. The keyword section is not: measured across the tree, nothing
+ * in `src/` parses `## Auto-trigger keywords`, so a skill carrying both halves
+ * is not mis-ROUTED, it is mis-DESCRIBED. A reader deciding whether they may
+ * invoke the skill meets two opposite answers in one file, and the half that
+ * looks operational is the half nothing reads.
+ *
+ * Three skills shipped in that state and a human had to notice it. The pair is
+ * mechanically decidable from the file, so noticing it again should not be
+ * anybody's job.
+ *
+ * Deliberately not a judgement about WHICH half is right. Both are legitimate
+ * designs; only the contradiction is a defect, and which way to resolve it is
+ * the author's call.
+ *
+ * Exit codes: 0 no contradiction · 1 at least one file carries both.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const SKILLS_REL = 'src/skills';
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+/** Matched in the description only — the phrase is meaningful there, prose elsewhere. */
+const EXPLICIT_ONLY_RE = /explicit[- ]request[- ]only|explicit request only/i;
+const AUTO_TRIGGER_RE = /^##\s+Auto-trigger keywords\s*$/m;
+
+export function contradicts(text: string): boolean {
+    const fm = FRONTMATTER_RE.exec(text);
+    if (fm === null) return false;
+    // `description:` may be a folded or quoted scalar spanning lines, so the
+    // slice runs to the next top-level key rather than to the next newline.
+    const desc = /^description:([\s\S]*?)(?=\n[a-z_]+:|$)/im.exec(fm[1] as string);
+    if (desc === null) return false;
+    if (!EXPLICIT_ONLY_RE.test(desc[1] as string)) return false;
+    return AUTO_TRIGGER_RE.test(text);
+}
+
+function main(): number {
+    if (process.argv.slice(2).includes('--self-test')) return selfTest();
+    const rootIdx = process.argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (process.argv[rootIdx + 1] ?? ROOT);
+    const dir = path.join(root, SKILLS_REL);
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).sort();
+    } catch {
+        process.stderr.write(`❌  no skills directory under ${root}/${SKILLS_REL}\n`);
+        return 1;
+    }
+    const offenders: string[] = [];
+    let scanned = 0;
+    for (const n of names) {
+        const f = path.join(dir, n, 'SKILL.md');
+        if (!fs.existsSync(f)) continue;
+        scanned += 1;
+        if (contradicts(fs.readFileSync(f, 'utf-8'))) {
+            offenders.push(`${SKILLS_REL}/${n}/SKILL.md`);
+        }
+    }
+    reportScanned({
+        gate: 'lint_skill_trigger_contradiction',
+        scanned,
+        units: 'SKILL.md file(s)',
+        roots: [SKILLS_REL],
+    });
+    if (offenders.length > 0) {
+        for (const o of offenders) {
+            process.stdout.write(
+                `❌  ${o}: description says explicit-request-only AND the body publishes ` +
+                    '`## Auto-trigger keywords` — the two halves say opposite things ' +
+                    'and nothing in src/ parses the keyword half, so the operational-looking ' +
+                    'one is the inert one.\n',
+            );
+        }
+        process.stdout.write(
+            `\n${String(offenders.length)} contradicting skill(s). Resolve by removing whichever ` +
+                'half is not true; the check does not decide which.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `✅  lint_skill_trigger_contradiction: ${String(scanned)} skill(s) inspected, ` +
+            'none claims explicit-request-only while publishing auto-trigger keywords.\n',
+    );
+    return 0;
+}
+
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trigger-contradiction-selftest-'));
+    const write = (name: string, body: string): string => {
+        const dir = path.join(tmp, name, SKILLS_REL, 'sample');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'SKILL.md'), body, 'utf-8');
+        return path.join(tmp, name);
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, 'src/scripts/lint_skill_trigger_contradiction.ts', ['--root', root], root);
+
+    const both =
+        '---\nname: sample\ndescription: Does a thing; explicit request only.\n---\n\n## Auto-trigger keywords\n\nfoo\n';
+    const descOnly = '---\nname: sample\ndescription: Does a thing; explicit request only.\n---\n\nbody\n';
+    const autoOnly = '---\nname: sample\ndescription: Does a thing.\n---\n\n## Auto-trigger keywords\n\nfoo\n';
+
+    try {
+        return runSelfTest({
+            gate: 'lint_skill_trigger_contradiction',
+            minCases: 3,
+            minRejectCases: 1,
+            cases: [
+                {
+                    name: 'a skill carrying BOTH halves is rejected',
+                    expect: 'reject',
+                    run: () => run(write('both', both)),
+                },
+                {
+                    name: 'explicit-request-only with no keyword section passes',
+                    expect: 'accept',
+                    run: () => run(write('desc-only', descOnly)),
+                },
+                {
+                    name: 'auto-trigger keywords with no explicit-only claim passes',
+                    expect: 'accept',
+                    run: () => run(write('auto-only', autoOnly)),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { SKILLS_REL, main };

package/src/scripts/mcp_server/resources.ts

@@ -41,6 +41,10 @@ export interface Resource {
     readonly source: string;
     readonly mime_type: string;
     readonly kind: ResourceKind;
+    /** Frontmatter `type:` (`always` / `auto` / `manual`) where the asset has one. */
+    readonly rule_type?: string;
+    /** File mtime, ISO-8601, for the protocol's `lastModified` annotation. */
+    readonly last_modified?: string;
 }
 
 // Python: re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
@@ -160,9 +164,20 @@ function _load(
         source: meta.source ?? 'package',
         mime_type: MIME_MARKDOWN,
         kind,
+        ...(meta.type === undefined ? {} : { rule_type: meta.type.trim() }),
+        ...(_mtimeIso(p) === null ? {} : { last_modified: _mtimeIso(p) as string }),
     };
 }
 
+/** File mtime as ISO-8601, or `null` when it cannot be read. */
+function _mtimeIso(p: string): string | null {
+    try {
+        return fs.statSync(p).mtime.toISOString();
+    } catch {
+        return null;
+    }
+}
+
 export function scan_rules(root?: string | null): [Resource[], string[]] {
     const base = root ?? _project_root();
     const rules_root = path.join(base, 'dist/agent-src', 'rules');
@@ -256,6 +271,25 @@ function _strCmp(a: string, b: string): number {
     return 0;
 }
 
+/**
+ * Priority in the protocol's 0..1 range.
+ *
+ * The roadmap that asked for this said to derive it "from the existing `tier`".
+ * There is no `tier` on a Resource — measured, not assumed — so it derives from
+ * what does exist: the frontmatter `type:` an always-loaded rule carries, then
+ * the asset kind. A rule the host loads on every turn outranks one it loads on
+ * a trigger, which outranks reference material.
+ *
+ * PROTOCOL CONFORMANCE ONLY. No shipped host is known to consume `priority` for
+ * selection, and this function must not be cited as evidence that one does.
+ */
+export function resourcePriority(resource: Resource): number {
+    if (resource.rule_type === 'always') return 1;
+    if (resource.rule_type === 'auto') return 0.7;
+    if (resource.rule_type === 'manual') return 0.3;
+    return resource.kind === 'rule' ? 0.7 : resource.kind === 'context' ? 0.5 : 0.3;
+}
+
 /** Project a Resource into MCP `Resource` constructor kwargs. */
 export function to_mcp_resource_meta(resource: Resource): Record<string, unknown> {
     return {
@@ -263,6 +297,13 @@ export function to_mcp_resource_meta(resource: Resource): Record<string, unknown
         name: resource.name,
         description: resource.description,
         mimeType: resource.mime_type,
+        // `audience` is the model, not the end user: these are governance
+        // assets a host injects, never something a person reads in a client.
+        audience: ['assistant'],
+        priority: resourcePriority(resource),
+        ...(resource.last_modified === undefined
+            ? {}
+            : { lastModified: resource.last_modified }),
         _meta: { source: resource.source, kind: resource.kind },
     };
 }