@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/lint_hook_manifest.ts

@@ -52,6 +52,33 @@ const DEFAULT_MANIFEST = path.join(
 const HOOKS_DIR = path.join(REPO_ROOT, "src", "scripts", "hooks");
 const DEFAULT_HOST_LOWERING = path.join(HOOKS_DIR, "host_lowering.yaml");
 
+/**
+ * What a concern does to a turn — the closed set `effect:` draws from.
+ *
+ * Read by the neighbour census, which needs to say what sharing an event with
+ * a foreign entry actually risks. A foreign entry's effect is `unknown` unless
+ * its output shape has been observed: no host exposes another package's hook
+ * execution, so the honest default is that the neighbour's effect cannot be
+ * read off its registration.
+ *
+ * - `permission`   can refuse the thing it fires on
+ * - `context`      puts text in front of the model
+ * - `verification` checks a claim or a shape and reports what it found
+ * - `telemetry`    records state, a ledger, a counter
+ * - `memory`       reads or writes the memory layer
+ * - `notification` tells the human something and changes nothing else
+ * - `formatting`   reshapes a command or a generated file
+ */
+export const CONCERN_EFFECTS: ReadonlySet<string> = new Set([
+  "permission",
+  "context",
+  "verification",
+  "telemetry",
+  "memory",
+  "notification",
+  "formatting",
+]);
+
 // Canonical event vocabulary — keep in lock-step with
 // docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
 const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
@@ -159,6 +186,32 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
     if (!_isFile(path.join(REPO_ROOT, script))) {
       errors.push(`concerns.${name}: script not found at '${script}'`);
     }
+    // `effect:` — what this concern DOES to a turn, from a closed set. It is
+    // what lets the neighbour census say "a foreign entry shares this event
+    // with something of ours that can refuse" rather than only "two entries".
+    // Required and enum-checked, which is a stricter rule than the optional
+    // keys below for one reason: a concern with no effect, or with a
+    // misspelled one, would silently drop out of every double-gate comparison
+    // — the warning would stay quiet and read as "no conflict", which is the
+    // wrong answer rather than a missing one. There is no unknown-key guard
+    // on this mapping, so nothing else would catch `effects:`.
+    const effect = spec["effect"];
+    if (typeof effect !== "string" || !CONCERN_EFFECTS.has(effect)) {
+      errors.push(
+        `concerns.${name}: 'effect' must be one of ` +
+          `${[...CONCERN_EFFECTS].sort().join(" | ")} (got ${JSON.stringify(effect)})`,
+      );
+    } else if ((spec["severity"] === "blocking") !== (effect === "permission")) {
+      // The two fields answer the same question from different sides, so a
+      // disagreement is a mistake in one of them, never a shade of meaning:
+      // `blocking` is the dispatcher's word for "this can refuse" and
+      // `permission` is the census's.
+      errors.push(
+        `concerns.${name}: 'effect: ${effect}' contradicts ` +
+          `'severity: ${String(spec["severity"])}' — a concern that can refuse ` +
+          `is 'permission', and only those are 'blocking'`,
+      );
+    }
     // `tools:` — the optional per-concern tool filter the dispatcher applies
     // in-process (`_concern_matches_tool`). Validated because the failure mode
     // is silent: the dispatcher fails toward RUNNING the concern on anything

package/src/scripts/lint_major_migration_sections.ts

@@ -53,6 +53,23 @@ const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
 export const GATE = 'lint_major_migration_sections';
 export const MIGRATION_PATH = path.join('docs', 'MIGRATION.md');
+
+/**
+ * The consumer-facing index of what every major broke.
+ *
+ * The SECOND obligation this gate carries, and it is the same obligation
+ * pointed at a different reader. `docs/MIGRATION.md` answers "what do I have to
+ * do"; this table answers "what happened, and when" — it is the first thing
+ * somebody planning an upgrade across several majors opens, because it is the
+ * only place the breaks are side by side.
+ *
+ * It stopped at 9.0.0 while the archived changelogs carried 10.0.0 through
+ * 16.0.0. Seven majors with no row, and nothing in the tree could see it: the
+ * forward half (`lint_scheduled_deprecations`) looks at commitments, the
+ * backward half looked only at `MIGRATION.md`, and the index was guarded by
+ * nobody. The source that reported it counted the report as its twentieth.
+ */
+export const BREAKING_INDEX_PATH = 'BREAKING_CHANGES.md';
 const CHANGELOG_PATH = 'CHANGELOG.md';
 const ARCHIVE_DIR = path.join('docs', 'archive');
 
@@ -145,8 +162,37 @@ export function migrationVersions(text: string): Set<string> {
     return out;
 }
 
+/**
+ * Versions the breaking-changes index carries a ROW for.
+ *
+ * Reads the FIRST cell only, and that is the load-bearing choice rather than a
+ * parsing convenience. The live table's Migration cells end in pointers like
+ * "See [CHANGELOG 8.0.0](CHANGELOG.md)", so a whole-line scan would hand the
+ * index rows it does not have — and would do it in the direction that makes the
+ * gate green, which is the direction a reader cannot detect.
+ *
+ * The bold spelling the table happens to use is not required: a row is a row.
+ */
+export function indexVersions(text: string): Set<string> {
+    const out = new Set<string>();
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|')) continue;
+        const first = trimmed.slice(1).split('|')[0];
+        if (first === undefined) continue;
+        for (const m of first.matchAll(/(?<![\d.])(\d+)\.0\.0(?![\d.])/g)) {
+            out.add(`${m[1] as string}.0.0`);
+        }
+    }
+    return out;
+}
+
+/** Which of the two obligations a major failed. Never empty on a finding. */
+export type MissingKind = 'migration' | 'index';
+
 export interface Finding {
     readonly section: MajorSection;
+    readonly missing: readonly MissingKind[];
 }
 
 /** Read every changelog file under `root`, newest-era file first. */
@@ -171,15 +217,23 @@ export interface EvaluateResult {
 }
 
 /**
- * Compare the majors found against the sections MIGRATION.md carries.
+ * Compare the majors found against BOTH records a breaking major owes.
  *
  * Every section reaches exactly one ledger outcome: out of scope below the
- * floor, out of scope with no BREAKING entries, completed when a heading
- * exists, failed when it does not.
+ * floor, out of scope with no BREAKING entries, completed when both records
+ * name it, failed when either does not.
+ *
+ * The two are checked together and reported apart. Together, because they are
+ * one obligation — "a major that broke something is written down where a
+ * consumer looks" — and splitting it across two gates would mean two copies of
+ * `findMajorSections` free to disagree about what a major even is. Apart,
+ * because a finding that says only "17.0.0 is undocumented" leaves the reader
+ * to discover which of two files to open.
  */
 export function evaluate(
     sections: readonly MajorSection[],
     migration: ReadonlySet<string>,
+    index: ReadonlySet<string>,
     ledger: GateLedger,
 ): EvaluateResult {
     const findings: Finding[] = [];
@@ -196,12 +250,24 @@ export function evaluate(
             continue;
         }
         inScope += 1;
-        if (migration.has(s.version)) {
+        const missing: MissingKind[] = [];
+        if (!migration.has(s.version)) missing.push('migration');
+        if (!index.has(s.version)) missing.push('index');
+        if (missing.length === 0) {
             ledger.complete(target);
             continue;
         }
-        ledger.fail(target, `no docs/MIGRATION.md section for ${s.version}`);
-        findings.push({ section: s });
+        ledger.fail(
+            target,
+            missing
+                .map((k) =>
+                    k === 'migration'
+                        ? `no ${MIGRATION_PATH} section for ${s.version}`
+                        : `no ${BREAKING_INDEX_PATH} row for ${s.version}`,
+                )
+                .join('; '),
+        );
+        findings.push({ section: s, missing });
     }
     return { findings, sections: [...sections], inScope };
 }
@@ -220,6 +286,7 @@ export function pendingMajorFinding(
     target: string,
     changelogEntry: string,
     migrationText: string,
+    indexText: string,
 ): string | null {
     const m = /^(\d+)\.0\.0$/.exec(target.trim());
     if (m === null) return null;
@@ -227,12 +294,19 @@ export function pendingMajorFinding(
     const breaking = sections.reduce((n, s) => n + s.breaking, 0);
     if (breaking === 0) return null;
     if (Number(m[1]) < FLOOR_MAJOR) return null;
-    if (migrationVersions(migrationText).has(target)) return null;
+    const owed: string[] = [];
+    if (!migrationVersions(migrationText).has(target)) {
+        owed.push(`${MIGRATION_PATH} has no "## " heading naming ${target}`);
+    }
+    if (!indexVersions(indexText).has(target)) {
+        owed.push(`${BREAKING_INDEX_PATH} has no row naming ${target}`);
+    }
+    if (owed.length === 0) return null;
     return (
         `the ${target} entry carries ${String(breaking)} BREAKING CHANGES entr(y/ies) and ` +
-        `docs/MIGRATION.md has no "## " heading naming ${target}. Add one before the cut — ` +
-        'a section stating that the change asks nothing of a consumer satisfies this, and is ' +
-        'the right answer when it is true. What is not acceptable is silence.'
+        `${owed.join(', and ')}. Add them before the cut — a section stating that the change ` +
+        'asks nothing of a consumer satisfies the first, and is the right answer when it is ' +
+        'true. What is not acceptable is silence.'
     );
 }
 
@@ -264,14 +338,28 @@ function selfTest(): number {
             '',
         ].join('\n');
 
+    const indexTable = (versions: readonly string[]): string =>
+        [
+            '# Breaking Changes',
+            '',
+            '## Breaking changes by major',
+            '',
+            '| Version | Date | What broke | Migration |',
+            '|---|---|---|---|',
+            ...versions.map((v) => `| **${v}** | 2026-01-01 | something | do a thing |`),
+            '',
+        ].join('\n');
+
     const fixture = (
         name: string,
         changelogText: string,
         migrationHeadings: readonly string[],
+        indexRows: readonly string[] = [],
     ): number => {
         const dir = path.join(root, name);
         fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
         fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), changelogText, 'utf8');
+        fs.writeFileSync(path.join(dir, BREAKING_INDEX_PATH), indexTable(indexRows), 'utf8');
         fs.writeFileSync(
             path.join(dir, 'docs', 'MIGRATION.md'),
             ['# Migration Guide', '', ...migrationHeadings.flatMap((h) => [h, '', 'body', ''])].join(
@@ -293,28 +381,48 @@ function selfTest(): number {
             // one half proves the refusal fires, the other that the heading is
             // what clears it, so neither can be satisfied by a gate that always
             // reds or always passes.
-            name: 'the same major passes once the heading exists',
+            name: 'the same major passes once the heading and the index row exist',
             expect: 'accept',
             run: () =>
-                fixture('present', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 17.0.0 — what to do',
-                ]),
+                fixture(
+                    'present',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 17.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
         },
         {
             name: 'a heading naming a DIFFERENT major does not satisfy the requirement',
             expect: 'reject',
             run: () =>
-                fixture('wrong-version', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 16.0.0 — what to do',
+                fixture(
+                    'wrong-version',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 16.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
+        },
+        {
+            // The index half of the same pair. Section present, row absent —
+            // so this case can only pass by checking the index, and the
+            // 'present' case above can only pass by accepting a correct one.
+            name: 'a major with a migration section but no index row is refused',
+            expect: 'reject',
+            run: () =>
+                fixture('no-index-row', changelog('17.0.0', ['**x:** drop y']), [
+                    '## 17.0.0 — what to do',
                 ]),
         },
         {
             name: 'an arrow-form heading naming the version satisfies it',
             expect: 'accept',
             run: () =>
-                fixture('arrow', changelog('17.0.0', ['**x:** drop y']), [
-                    '## 16.x → 17.0.0 — what to do',
-                ]),
+                fixture(
+                    'arrow',
+                    changelog('17.0.0', ['**x:** drop y']),
+                    ['## 16.x → 17.0.0 — what to do'],
+                    ['17.0.0'],
+                ),
         },
         {
             name: 'a major BELOW the floor is forgiven',
@@ -336,6 +444,10 @@ function selfTest(): number {
                 const dir = path.join(root, 'no-changelog');
                 fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
                 fs.writeFileSync(path.join(dir, 'docs', 'MIGRATION.md'), '# Migration Guide\n', 'utf8');
+                // The index IS present, so the refusal below can only be the
+                // dead-scan-root one. Without it this case would reject on a
+                // missing file and stop testing what it is named for.
+                fs.writeFileSync(path.join(dir, BREAKING_INDEX_PATH), indexTable([]), 'utf8');
                 return runGateCli(repo, script, ['--root', dir, '--quiet'], repo);
             },
         },
@@ -381,6 +493,15 @@ export function main(argv: readonly string[]): number {
         return 1;
     }
     const migration = migrationVersions(fs.readFileSync(migrationFile, 'utf-8'));
+    // An absent index reds rather than skipping the index half. A missing
+    // comparand that silently narrows the comparison is how a gate reports
+    // "nothing wrong" about a question it stopped asking.
+    const indexFile = path.join(root, BREAKING_INDEX_PATH);
+    if (!fs.existsSync(indexFile)) {
+        process.stderr.write(`❌  ${GATE}: ${BREAKING_INDEX_PATH} not found under ${root}\n`);
+        return 1;
+    }
+    const index = indexVersions(fs.readFileSync(indexFile, 'utf-8'));
 
     const sources = changelogSources(root);
     const sections: MajorSection[] = [];
@@ -389,7 +510,7 @@ export function main(argv: readonly string[]): number {
     }
 
     const ledger = new GateLedger(GATE);
-    const result = evaluate(sections, migration, ledger);
+    const result = evaluate(sections, migration, index, ledger);
     const tally = ledger.finalize();
 
     try {
@@ -400,7 +521,7 @@ export function main(argv: readonly string[]): number {
             gate: GATE,
             scanned: tally.planned,
             units: 'major changelog section(s)',
-            roots: [CHANGELOG_PATH, ARCHIVE_DIR],
+            roots: [CHANGELOG_PATH, ARCHIVE_DIR, MIGRATION_PATH, BREAKING_INDEX_PATH],
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {
@@ -412,13 +533,22 @@ export function main(argv: readonly string[]): number {
 
     if (result.findings.length > 0) {
         for (const f of result.findings) {
+            const owed = f.missing
+                .map((k) =>
+                    k === 'migration'
+                        ? `${MIGRATION_PATH} carries no "## " heading naming it`
+                        : `${BREAKING_INDEX_PATH} carries no row naming it`,
+                )
+                .join(', and ');
             process.stderr.write(
                 `❌  ${GATE}: ${f.section.version} ships ${String(f.section.breaking)} BREAKING ` +
                     `CHANGES entr(y/ies) (${f.section.source}:${String(f.section.line)}) and ` +
-                    `${MIGRATION_PATH} carries no "## " heading naming it.\n` +
-                    `    Add a section for ${f.section.version}. A section stating that the change\n` +
-                    '    asks nothing of a consumer satisfies this and is the right answer when it\n' +
-                    '    is true — the requirement is a stated answer, never a procedure.\n',
+                    `${owed}.\n` +
+                    `    Add what is missing for ${f.section.version}. A migration section stating\n` +
+                    '    that the change asks nothing of a consumer satisfies that half and is the\n' +
+                    '    right answer when it is true — the requirement is a stated answer, never a\n' +
+                    `    procedure. The ${BREAKING_INDEX_PATH} row is one line in the by-major table,\n` +
+                    '    linking the changelog section it came from.\n',
             );
         }
         return 1;
@@ -429,7 +559,7 @@ export function main(argv: readonly string[]): number {
         process.stdout.write(
             `✅  ${GATE}: ${String(tally.planned)} major section(s) read, ` +
                 `${String(result.inScope)} in scope (major >= ${String(FLOOR_MAJOR)} with BREAKING ` +
-                'CHANGES), each with a migration section' +
+                'CHANGES), each with a migration section and an index row' +
                 (result.inScope === 0
                     ? ' — NONE in scope this run, so no comparison ran. Green here means\n' +
                       '    "nothing to compare", not "the comparison passed".\n'

package/src/scripts/lint_pack_boundaries.ts

@@ -34,10 +34,19 @@
  *   this gate now matches that definition.
  * - **BROKEN deliberately:** exit code 2 is new (dead scan scope). 0 and 1
  *   keep their meanings.
+ * - **BROKEN deliberately (2026-10-01):** the always-installed set is the
+ *   hard-coded `core` PLUS every pack flagged `always_on: true`. The original
+ *   knew only `core`, so it reported a violation for a target the resolver
+ *   provably does install — the same defect shape as the direct-vs-transitive
+ *   `requires` comparison above. `config/packs.resolve_active_packs` seeds the
+ *   active set with the always-on packs before expanding any selection, and
+ *   `docs/contracts/capability-packs.md` § Always-on packs states such a pack
+ *   "cannot be deselected". One-way: a link OUT of an always-on pack into a
+ *   gated one still dangles and is still reported.
  * - **STILL HOLDS:** the CLI surface (`--format text|json`, `--quiet`, `-h`),
  *   the link regex and its fragment/query stripping, link-resolution semantics
  *   (external / absolute / out-of-tree targets ignored), the allow rule
- *   (same pack · `core` · declared `requires`), the per-violation text and
+ *   (same pack · always-installed · declared `requires`), the per-violation text and
  *   JSON shapes, the stdout/stderr split, and exit 0 clean / 1 violations.
  *
  * ## Where the `requires` graph is read from
@@ -115,6 +124,47 @@ const LINK_RE = /\[[^\]]*\]\(([^)#?]+)(?:[#?][^)]*)?\)/g;
 /** A pack every install carries — a link into it can never dangle. */
 const ALWAYS_INSTALLED = 'core';
 
+/**
+ * Packs every projection carries, so a link INTO one can never dangle.
+ *
+ * `core` is the hard-coded floor. Beyond it, `always_on: true` in the pack
+ * vocabulary means exactly this: `config/packs.resolve_active_packs` seeds the
+ * active set with every always-on pack BEFORE expanding the selected profile's
+ * `requires` closure, and `docs/contracts/capability-packs.md` § Always-on
+ * packs states the pack "is never gated by the selected profile, workspace, or
+ * pack set, and it cannot be deselected".
+ *
+ * Reading only `core` was the same class of defect this file's header already
+ * records for the direct-vs-transitive `requires` comparison: the gate reported
+ * a violation for a target the resolver provably does install. The direction is
+ * one-way — a link OUT of an always-on pack into a gated one still dangles and
+ * is still a violation.
+ */
+function _always_installed_packs(): Set<string> {
+    const out = new Set<string>([ALWAYS_INSTALLED]);
+    if (_exists(VOCAB)) {
+        const vocab = parseYaml(fs.readFileSync(VOCAB, 'utf-8'), { version: '1.1' });
+        if (Array.isArray(vocab)) {
+            for (const entry of vocab) {
+                if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+                    const e = entry as Record<string, unknown>;
+                    if (typeof e['id'] === 'string' && e['always_on'] === true) {
+                        out.add(e['id']);
+                    }
+                }
+            }
+        }
+    }
+    for (const dir of _pack_home_dirs()) {
+        const meta = _load_pack_meta(dir);
+        if (meta['always_on'] === true) {
+            const id = typeof meta['id'] === 'string' ? meta['id'] : path.basename(dir);
+            out.add(id);
+        }
+    }
+    return out;
+}
+
 type ViolationKind =
     /** Link crosses into a pack the source pack does not require. */
     | 'cross-pack'
@@ -479,11 +529,16 @@ function _scan_file(p: string): string[] {
     return out;
 }
 
-function _is_allowed(source_pack: string, target_pack: string, requires: string[]): boolean {
+function _is_allowed(
+    source_pack: string,
+    target_pack: string,
+    requires: string[],
+    always_installed: ReadonlySet<string> = new Set([ALWAYS_INSTALLED]),
+): boolean {
     if (source_pack === target_pack) {
         return true;
     }
-    if (target_pack === ALWAYS_INSTALLED) {
+    if (always_installed.has(target_pack)) {
         return true;
     }
     return (requires || []).includes(target_pack);
@@ -501,10 +556,11 @@ function _link_allowed(
     source_packs: readonly string[],
     target_packs: readonly string[],
     closureOf: (pack: string) => Set<string>,
+    always_installed: ReadonlySet<string> = new Set([ALWAYS_INSTALLED]),
 ): boolean {
     return source_packs.every((s) => {
         const reach = [...closureOf(s)];
-        return target_packs.some((t) => _is_allowed(s, t, reach));
+        return target_packs.some((t) => _is_allowed(s, t, reach, always_installed));
     });
 }
 
@@ -597,6 +653,7 @@ function main(argv?: readonly string[]): number {
     }
 
     const pack_requires = _pack_requires();
+    const always_installed = _always_installed_packs();
     const closureCache = new Map<string, Set<string>>();
     const closureOf = (pack: string): Set<string> => {
         let c = closureCache.get(pack);
@@ -635,7 +692,7 @@ function main(argv?: readonly string[]): number {
             if (target_packs === undefined) {
                 continue; // docs/, scripts/, root files, unassigned — not pack-scoped
             }
-            if (_link_allowed(src_packs, target_packs, closureOf)) {
+            if (_link_allowed(src_packs, target_packs, closureOf, always_installed)) {
                 continue;
             }
             violations.push({
@@ -743,6 +800,7 @@ export {
     _build_artefact_index,
     _resolve_link,
     _scan_file,
+    _always_installed_packs,
     _is_allowed,
     _link_allowed,
     _load_pack_meta,