@event4u/agent-config 14.21.0 → 14.22.0

package/dist/scripts/condense.js

@@ -232,9 +232,9 @@ export { rule_in_scope } from '../install/ruleInScope.js';
 export { CLAUDE_PATHS_PATTERN_BUDGET, _claude_paths_plan, _escape_claude_bracket, _expanded_pattern_count, _has_non_path_trigger, _is_unresolved_placeholder, derive_trigger_globs, } from '../install/claudePathsPlan.js';
 import { rule_in_scope } from '../install/ruleInScope.js';
 import { pruneEmptyDirs } from './_lib/prune_empty_dirs.js';
-import { commandsWithheld, partitionActive, personaPartition, setPartitionAnnounce } from '../install/partitionEligibility.js'; // ADR-236
+import { claudeLayerHolds, commandWithheld, keepInProjectLayer, personaPartition } from '../install/partitionEligibility.js'; // ADR-236
 import { dedupableRules, partitionRulesForDir } from '../install/ruleLayerPartition.js'; // ADR-236, per-host evidence
-import { _claude_paths_plan, derive_trigger_globs } from '../install/claudePathsPlan.js';
+import { _claude_paths_plan, applies_when, derive_trigger_globs } from '../install/claudePathsPlan.js';
 const _HERE = path.dirname(fileURLToPath(import.meta.url)); // <repo>/src/scripts
 const _DEFAULT_PROJECT_ROOT = path.resolve(_HERE, '..', '..');
 function _deriveState(root) {
@@ -263,7 +263,6 @@ function _deriveState(root) {
     };
 }
 export const MODULE_STATE = _deriveState(_DEFAULT_PROJECT_ROOT);
-setPartitionAnnounce(success); // ADR-236: the mode line must be visible at the default level
 /**
  * Test seam — reassign one or more module-state fields, mirroring the pytest
  * monkeypatch of `condense.<NAME> = ...`. When `PROJECT_ROOT` is overridden,
@@ -1149,7 +1148,7 @@ export function _emit_cursor_mdc(source, target) {
     const globs = always_apply ? [] : derive_trigger_globs(meta);
     const lines = [
         '---',
-        `description: ${_yaml_scalar(description)}`,
+        `description: ${_yaml_scalar(always_apply ? description : applies_when(description, meta))}`,
         `globs: ${globs.join(',')}`,
         `alwaysApply: ${always_apply ? 'true' : 'false'}`,
         '---',
@@ -1170,7 +1169,7 @@ export function _emit_windsurf_rule(source, target) {
     const lines = [
         '---',
         `trigger: ${trigger}`,
-        `description: ${_yaml_scalar(description)}`,
+        `description: ${_yaml_scalar(always_apply ? description : applies_when(description, meta))}`,
         `globs: ${globs.join(',')}`,
         '---',
         '',
@@ -1448,23 +1447,21 @@ function _render_native_model_md(src_md, tier) {
     return text.replace(_MODEL_TIER_RE, `model: ${model}`);
 }
 export function generate_claude_skills(active_skill_names = null) {
-    if (partitionActive(MODULE_STATE.PROJECT_ROOT))
-        active_skill_names = new Set();
     if (!_exists(MODULE_STATE.SKILLS_SOURCE)) {
         process.stderr.write('  ⚠️  dist/agent-src/skills/ not found — skipping skills\n');
         return 0;
     }
-    let skills = _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
+    const all_skills = _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
         .filter((p) => _isDir(p))
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    // ADR-236: withhold every skill `~/.claude/skills` holds — see `keepInProjectLayer`.
+    let skills = keepInProjectLayer('skills', all_skills);
     if (active_skill_names !== null) {
         skills = skills.filter((s) => active_skill_names.has(s));
     }
     const skill_set = new Set(skills);
-    const command_slugs = partitionActive(MODULE_STATE.PROJECT_ROOT)
-        ? new Set()
-        : new Set([...iterCommands()].map(([, slug]) => slug));
+    const command_slugs = _emitted_wrapper_slugs(new Set(all_skills));
     _mkdirp(MODULE_STATE.CLAUDE_SKILLS_DIR);
     const auto = _read_model_auto_switch() === 'auto';
     for (const item of _iterdirSorted(MODULE_STATE.CLAUDE_SKILLS_DIR)) {
@@ -1549,6 +1546,17 @@ function _nested_command_subpath(source_file) {
     const sub = logical.slice('commands/'.length).replace(/\.md$/, '');
     return sub.includes('/') ? sub : null;
 }
+/** The emitter's four skips, in one place — see `emittedWrapperSlugs`. */
+const _wrapper_is_emitted = (f, s, skills) => !skills.has(s) &&
+    _nested_command_subpath(f) === null &&
+    !is_claude_builtin_name(s) &&
+    !claudeLayerHolds('skills', s);
+/** Wrapper slugs the command emitter really writes — see `emittedWrapperSlugs`. */
+function _emitted_wrapper_slugs(skill_names) {
+    return new Set([...iterCommands()]
+        .filter(([f, s]) => _wrapper_is_emitted(f, s, skill_names))
+        .map(([, slug]) => slug));
+}
 /**
  * Project-scope `.claude/commands/<cluster>/<sub>.md` — the colon form.
  *
@@ -1561,15 +1569,12 @@ function _nested_command_subpath(source_file) {
  *
  * Emitting the nested form here lets `generate_claude_commands` stop wrapping
  * the clustered commands: one listing, same reachability, and reachability no
- * longer depends on a global deploy. Dedup AND precedence: `commandsWithheld`.
+ * longer depends on a global deploy. Dedup AND precedence: `commandWithheld`.
  *
  * ADR-003 (colon canonical for clusters) and ADR-044 (flat commands stay
  * hyphenated) both hold: flat commands are untouched and keep their wrapper.
  */
 export function generate_claude_project_commands(active_command_slugs = null) {
-    if (commandsWithheld(MODULE_STATE.PROJECT_ROOT))
-        active_command_slugs = new Set();
-    // Returns before the stale sweep — invariant, see `commandsWithheld`.
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         return 0;
     }
@@ -1579,7 +1584,7 @@ export function generate_claude_project_commands(active_command_slugs = null) {
             continue;
         }
         const sub = _nested_command_subpath(source_file);
-        if (sub !== null) {
+        if (sub !== null && !commandWithheld(`${sub}.md`)) {
             nested.push([source_file, sub]);
         }
     }
@@ -1613,8 +1618,6 @@ export function generate_claude_project_commands(active_command_slugs = null) {
     return count;
 }
 export function generate_claude_commands(active_command_slugs = null) {
-    if (partitionActive(MODULE_STATE.PROJECT_ROOT))
-        active_command_slugs = new Set();
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         process.stderr.write('  ⚠️  src/domains/ not found — skipping commands\n');
         return 0;
@@ -1630,6 +1633,7 @@ export function generate_claude_commands(active_command_slugs = null) {
     let count = 0;
     let skipped = 0;
     let reserved = 0;
+    let withheld = 0;
     let rendered = 0;
     const auto = _read_model_auto_switch() === 'auto';
     for (const [source_file, slug] of iterCommands()) {
@@ -1658,6 +1662,12 @@ export function generate_claude_commands(active_command_slugs = null) {
             reserved += 1;
             continue;
         }
+        // ADR-236 per-name: the INSTALLER re-projects visible flat commands as
+        // `~/.claude/skills/<slug>/SKILL.md` (install.ts:_apply_claude_flat_command_wrappers).
+        if (claudeLayerHolds('skills', slug)) {
+            withheld += 1;
+            continue;
+        }
         current_slugs.add(slug);
         const skill_dir = path.join(MODULE_STATE.CLAUDE_SKILLS_DIR, slug);
         _mkdirp(skill_dir);
@@ -1706,6 +1716,9 @@ export function generate_claude_commands(active_command_slugs = null) {
     if (reserved) {
         msg += ` (${reserved} withheld — Claude Code built-in name)`;
     }
+    if (withheld > 0) {
+        msg += ` (${withheld} withheld — ~/.claude/skills carries the wrapper)`;
+    }
     if (removed_dirs) {
         msg += ` (${removed_dirs} stale dirs removed)`;
     }
@@ -2019,19 +2032,13 @@ export function generate_persona_symlinks() {
         _print('  ⚠️  dist/agent-src/personas/ not found — skipping personas');
         return 0;
     }
-    const personas = _rglobSorted(MODULE_STATE.PERSONAS_SOURCE, '*.md')
-        .filter((p) => _isFile(p) && path.basename(p, '.md') !== 'README')
-        .map((p) => path.basename(p))
-        // glob('*.md') is non-recursive in Python; mirror that — only top level.
-        .filter((name) => _isFile(path.join(MODULE_STATE.PERSONAS_SOURCE, name)));
     // Python uses PERSONAS_SOURCE.glob("*.md") (non-recursive). Re-derive
     // from a direct listing to match exactly.
     const direct = _iterdirSorted(MODULE_STATE.PERSONAS_SOURCE)
         .filter((p) => p.endsWith('.md') && _isFile(p) && path.basename(p, '.md') !== 'README')
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    void personas;
-    const partition = personaPartition(MODULE_STATE.PROJECT_ROOT, direct);
+    const partition = personaPartition(direct);
     const tool_dirs = _filter_tool_dirs(PERSONA_TOOL_DIRS);
     let total = 0;
     for (const [tool_dir, rel_prefix] of Object.entries(tool_dirs)) {

package/docs/MIGRATION.md

@@ -17,7 +17,7 @@ releaser here on every `release:major`.
 | Surface | Committed | Deprecation notice due | Removal due | Reversal condition |
 |---|---|---|---|---|
 | Free-text `compatibility` skill-frontmatter field (`src/scripts/schemas/skill.schema.json`) | 2026-08-14 | shipped 2026-08-14 — `deprecated: true` + superseded-by note in the schema; `harness_compat` lands beside it, additively | next major after the notice — **not pinned here** (removal date is maintainer-owned, same stance as the manifest `tier` entry, whose `sunset` shipped `null`) | The public Agent-Skills spec makes `compatibility` load-bearing for cross-host portability, or an external consumer is found reading it. `harness_compat` is package-local; `compatibility` mirrors the public spec, so keeping the mirror stays cheaply reversible. Superseded by `harness_compat` (class) + `runtime_requires` (probeable detail); both users (`docx-authoring`, `pdf-tools`) already carry both fields, so nothing breaks on removal day. |
-| `code_graph` native code-graph engine (`code_graph.enabled`, the `code-intelligence` skill's native arm, `code_graph_nudge_hook`) | 2026-07-28 | next major after 9.x | **REVISED 2026-08-15 — no removal date; see below** | A consumer case the graph answers and disciplined grep cannot. Measured null: recall 0.365 vs grep 0.797 (`docs/CLAIMS.md` `code-graph-retrieval-null`), measured 2026-07-28 against a build predating the 2026-08-22 extractor repair. `enabled: false` stays the DEFAULT — "permanent" is retracted here on 2026-08-26, because this row's own revision below withdraws the removal commitment and a withdrawn schedule cannot leave a permanence behind it. **Revision (ADR-232 track, maintainer decision 2026-08-15).** The original row committed removal to 11.0; the tree reached 12.0.0 with the runtime paths still registered, i.e. the commitment was missed. Rather than quietly re-dating it, the commitment is withdrawn with its reason recorded, because the measurement changed what removal is worth: **the payload this deprecation existed for has already shipped** — the parser pair (`web-tree-sitter@0.24.7` / `tree-sitter-wasms@0.1.13`, ~51 MB unpacked) moved from `dependencies` to `devDependencies` ahead of schedule, so no consumer installs it. What source removal would still free is ~112 K against a 27 M tree (0.4 %). Against that it costs a breaking change across four consumer-visible surfaces (CLI verb, `code-intelligence` skill, `external-code-graph-interop` rule, `hooks.code_graph.enabled`) plus one surface that is re-plumbing rather than deletion: `_lib/auto_dispatch.ts` routes the `definition` / `references` lookup classes to `primitive: 'code-graph-query'`, and `_lib/judgment_ladder.ts` calls that live at Rung 0. There is also no cheap middle — `code_graph/detect.ts` handles the `consumer` / `scip` / `native` source kinds in one type union, so stripping only the native engine while keeping consumer-index interop is a redesign. **New commitment:** the surfaces stay registered and disabled; removal happens when a concrete reason appears (a maintenance cost that bites, a conflicting redesign, or a consumer asking), not on a date. This row stays in the table so the decision is visible rather than forgotten — a withdrawn commitment recorded is not the folklore this table exists to prevent; an unrecorded one would be. |
+| `code_graph` native code-graph engine (`code_graph.enabled`, the `code-intelligence` skill's native arm, `code_graph_nudge_hook`) | 2026-07-28 | next major after 9.x | **REVISED 2026-08-15 — no removal date; see below** | A consumer case the graph answers and disciplined grep cannot. Measured null: recall 0.365 vs grep 0.797 (`docs/CLAIMS.md` `code-graph-retrieval-null`), measured 2026-07-28 against a build predating the 2026-08-22 extractor repair. `enabled: false` stays the DEFAULT — "permanent" is retracted here on 2026-08-26, because this row's own revision below withdraws the removal commitment and a withdrawn schedule cannot leave a permanence behind it. **Revision (ADR-232 track, maintainer decision 2026-08-15).** The original row committed removal to 11.0; the tree reached 12.0.0 with the runtime paths still registered, i.e. the commitment was missed. Rather than quietly re-dating it, the commitment is withdrawn with its reason recorded, because the measurement changed what removal is worth: **the payload this deprecation existed for has already shipped** — the parser pair (`web-tree-sitter@0.24.7` / `tree-sitter-wasms@0.1.13`, ~51 MB unpacked) moved from `dependencies` to `devDependencies` ahead of schedule, so no consumer installed it. **REVERSED 2026-09-07 by ADR-259 (as amended) — this clause no longer holds and is kept only so the reversal is legible.** Delivery and measurement are decoupled: `web-tree-sitter` is a runtime `dependency` again and the three loadable grammars are vendored at `src/vendor/grammars/`, so a consumer now DOES install the engine. The measured null above is untouched and `enabled: false` stays the default — what changed is that the reopen trigger ("a consumer case the graph answers") became reachable at all, which it was not while no consumer could receive the engine. The install delta is recorded below under "14.21.x — the code-graph engine ships to consumers". What source removal would still free is ~112 K against a 27 M tree (0.4 %). Against that it costs a breaking change across four consumer-visible surfaces (CLI verb, `code-intelligence` skill, `external-code-graph-interop` rule, `hooks.code_graph.enabled`) plus one surface that is re-plumbing rather than deletion: `_lib/auto_dispatch.ts` routes the `definition` / `references` lookup classes to `primitive: 'code-graph-query'`, and `_lib/judgment_ladder.ts` calls that live at Rung 0. There is also no cheap middle — `code_graph/detect.ts` handles the `consumer` / `scip` / `native` source kinds in one type union, so stripping only the native engine while keeping consumer-index interop is a redesign. **New commitment:** the surfaces stay registered and disabled; removal happens when a concrete reason appears (a maintenance cost that bites, a conflicting redesign, or a consumer asking), not on a date. This row stays in the table so the decision is visible rather than forgotten — a withdrawn commitment recorded is not the folklore this table exists to prevent; an unrecorded one would be. |
 | `telegraph-speak` condenser (`telegraph.speak`, `src/rules/telegraph-speak.md`, `src/scripts/_lib/compile_time_toggles.ts`, `src/scripts/validate_telegraph_carveouts.ts`) | 2026-07-29 | shipped 2026-07-29 — dormant by default, `speak` defaults `false` | **not pinned here** — removal is authorized in principle and deliberately not executed (ADR `telegraph/0002` § Decision part 3), pending a `prose_only` bench (~$0.80). The date is maintainer-owned, same stance as the `compatibility` row above | An output-side bench clears the kill-criterion bar, at which point `telegraph.speak: true` restores the feature intact. Measured basis for dormancy: median vs_terse **−9.27 %** (API) / −5.47 % (exact `cl100k_base`) — the condenser emits MORE than a plain "be terse". Tracked as a row rather than left dormant-and-unlisted: dormancy without a row is untracked in *both* directions, neither scheduled nor recorded as a keep. Deliberately NOT a due version (that would invent a commitment ADR 0002 declined to make) and NOT a permanent keep (that would contradict its authorized removal). |
 
 ### Row status — what is currently late, and who owns it
@@ -42,6 +42,54 @@ reason, which no arithmetic can.
 or that promises a future breaking removal, gets a row here in the same commit
 that makes the promise. A promise with no row is not tracked and will be missed.
 
+## 14.21.x — the code-graph engine ships to consumers
+
+💡 advisory · 🔄 automatic — no action required.
+
+`npm install @event4u/agent-config` now carries everything the native
+code-graph engine needs, so `agent-config code-graph build` works on the next
+command with no manual parser install (ADR-259, as amended 2026-09-07).
+
+### What changed
+
+- `web-tree-sitter@0.24.7` moved from `devDependencies` to `dependencies`.
+- Three compiled tree-sitter grammars are **vendored** in the published tarball
+  at `src/vendor/grammars/` — php, typescript (which also serves `.tsx`), and
+  javascript. These are the three `GRAMMAR_WASM` entries the engine can load.
+- `tree-sitter-wasms` stays a `devDependency`. It is the source the vendored
+  copies are refreshed from, not a runtime dependency, so consumers do **not**
+  receive the 36-grammar pack.
+
+### Install delta, measured
+
+Measured on 2026-09-07 with `npm pack --dry-run --json --ignore-scripts`,
+against the same tree with the vendored directory excluded from `files[]`:
+
+| Axis | Before | After | Delta |
+|---|---|---|---|
+| Compressed tarball | 9,821,600 B | 10,195,522 B | **+373,922 B** (+0.357 MiB) |
+| Vendored grammars, on disk | 0 B | 3,802,618 B | **+3,802,618 B** (+3.63 MiB) |
+| `web-tree-sitter` in `node_modules` | 0 B (dev-only) | ~389,120 B | **+~380 KiB** |
+
+Per-grammar, uncompressed: `tree-sitter-php.wasm` 812,594 B ·
+`tree-sitter-typescript.wasm` 2,342,690 B · `tree-sitter-javascript.wasm`
+647,334 B.
+
+For contrast, the two rejected shapes: depending on `tree-sitter-wasms`
+directly would have delivered all 36 grammars (51,765,657 B apparent, 49 MiB on
+disk), and the 13-grammar set ADR-259 originally named measures 9,085,798 B
+apparent / 1,016,804 B compressed — the latter would have put the tarball at
+~10.84 MB. Only three grammars are loadable today, so the other ten would have
+been payload with no reader.
+
+### Rolling back
+
+Set `hooks.code_graph.enabled: false` — which is already the default; the
+engine ships disabled. Nothing runs the parsers unless you build a graph. To
+drop the payload entirely, remove `src/vendor/grammars/` from `files[]` and
+move `web-tree-sitter` back to `devDependencies`; the loader falls back to the
+`tree-sitter-wasms` pack, which is this repository's own dev path.
+
 ## 8.x → 9.0.0 — consumer rule projection scoped by default
 
 9.0.0 flips the consumer rule-projection default to **scoped**: fresh

package/docs/contracts/settings-classes.md

@@ -558,7 +558,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.runtime_journal.enabled` | C | `false` | configures code that runs on every dispatched hook event | consent |
 | `hooks.ui_route_nudge.enabled` | C | `false` | configures code that runs on every tool call | derivable — the UI-surface predicate plus the hook's own two-nudges-per-session cap |
 | `hooks.design_pass.enabled` | C | `false` | C-test 1 — it configures code that runs on every tool call and at every turn end, and unlike its two `hooks.*` neighbours its stop pass can BLOCK rather than warn | policy — whether an operator accepts a gate that can refuse a turn is a risk preference, not a fact the tree can compute. The two neighbours are `derivable` because they only ever warn; the block is the discriminator. `road-to-frontend-power` transfers the default flip to the owner for the same reason |
-| `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call | derivable — the index-detection probe the nudge already runs; no index means silence |
+| `hooks.code_graph.enabled` | C | `false` | INERT since 2026-09-07 — the nudge it gated was replaced by `code-graph-context`, which reads no flag. The KEY stays registered because `docs/MIGRATION.md` commits to exactly that ("the surfaces stay registered and disabled"): removing it is a breaking change for any consumer who set it, and the row was briefly marked REMOVED, which left the template's own leaf unclassified. Classified, not deleted. | derivable — the index-detection probe the replacement hook already runs; no index means silence |
 | `hooks.suggestion_capture.enabled` | C | `false` | configures code that runs at every turn end and every prompt | consent |
 | `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it | derivable — the engine's own active-gate state; there is nothing to surface when no gate fired |
 | `decision_engine.min_confidence` | C | `"off"` | the confidence gate | derivable — the confidence band the scoring engine already computes at the plan phase |

package/docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md

@@ -166,3 +166,76 @@ reviewer has to untangle.
 
 - `minimal-safe-diff` (rule) — Iron Law, the rule, the pre-fix shared-path repair clause, own-orphan cleanup. The pre-diff checklist, the red-flag catalog and the when-in-doubt line live HERE since A1.
 - [`active-remediation-mechanics`](active-remediation-mechanics.md) — the fix-now / note+ask / follow-up-PR ladder detail.
+
+## Re-derive the requirement, don't inherit the shape
+
+```
+A REPAIR INHERITS THE SHAPE OF WHAT IT REPAIRS UNLESS YOU ASK OTHERWISE.
+STATE THE REQUIREMENT IN ONE LINE, THEN ASK WHETHER THE CURRENT FORM
+*CAN* EXPRESS IT. A FORM THAT CANNOT IS NOT A PARAMETER BUG.
+```
+
+Applies to a downstream repair — clearing a red, or fixing what your own diff
+broke — where the smallest change is a different VALUE and the form is
+unexamined.
+
+### Why this is a guideline section and not a rule clause
+
+It was drafted as a clause in `minimal-safe-diff` on 2026-09-07 and moved here
+the same day, on the gate's own evidence rather than on preference.
+`check_preamble_payload_budget` measured the clause at +460 delivered tokens,
+then +271, then +180 after two rounds of cutting — a floor set by the Iron-Law
+block itself. That payload is re-written on EVERY subagent spawn, and the rule it
+would have lived in is `type: auto`: it fires on prompt keywords, not on tool
+output, so a red test nobody mentioned never loads it.
+
+Certain per-spawn cost against an activation path that misses the case the clause
+was written for is a bad trade, and the deterministic half does not depend on it
+— see § Honest limit below. The rule already routes here
+(`routes_to: guideline:agent-infra/minimal-safe-diff-mechanics`), which is the
+same reachability every other migrated body in this repository has.
+
+### Worked failure — 2026-09-07
+
+A change emptied `<repo>/.claude/skills` of skills and left ~49 flat-command
+wrappers behind. `resolveSkillsRoot` tried two workspace-relative roots and took
+the first non-empty one, so it resolved the wrappers, and the skill ranker ranked
+49 command wrappers instead of 299 skills.
+
+The repair chosen was to swap the ORDER of the two roots. The requirement was
+*"rank every catalogue the session can reach"*, which **no ordering of a
+first-hit loop can satisfy** — and the host-global root the whole task was about
+appeared in neither position. The evidence had been measured an hour earlier and
+sat in the same session's own notes: `~/.claude/skills` 307, `.claude/skills` 49,
+`src/skills` 299.
+
+Two things made it easy to miss, and both are the shape of the trap rather than
+this instance of it:
+
+- **The docstring framed the question.** It read *"First existing catalogue root
+  … `.claude/skills` before `src/skills` because a CONSUMER install carries the
+  former"* — i.e. it asked *which root wins*, and that question was answered. A
+  docstring records what the code decided; it never records whether that was the
+  decision to make.
+- **The same docstring contained the premise of the correct answer.** If
+  consumers carry their own skills *and* the package ships skills, both must be
+  read. The sentence was read, used to justify an ordering, and its consequence
+  was not drawn.
+
+### Why the pre-work rules do not cover it
+
+[`improve-before-implement`](../../../src/rules/improve-before-implement.md) does
+not activate for bug fixes ("the problem is already defined") and
+[`invite-challenge`](../../../src/rules/invite-challenge.md) excludes "evidenced
+bug fixes". Both exclusions are right for the case they were written for and
+wrong for a downstream repair, which presents as a defined problem while its
+definition came from the broken code.
+
+### Honest limit
+
+The rule is `type: auto`, so it fires on prompt keywords and not on tool output:
+a red test nobody prompted about does not load it. The clause is the
+model-carried half. The deterministic half is a comparison of the two lists that
+diverged — `tests/contracts/catalogue_layer_parity.test.ts`, which reds when a
+directory the delivery side treats as an artifact source is not a root the reader
+reads, and which was measured to catch this exact defect on the pre-change tree.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.21.0",
+    "version": "14.22.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,
@@ -48,6 +48,7 @@
         "src/agent-src/scripts/",
         "src/agent-src/templates/scripts/",
         "src/templates/",
+        "src/vendor/grammars/",
         "tests/fixtures/hooks/",
         "AGENTS.md",
         "CHANGELOG.md",
@@ -80,13 +81,15 @@
         "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:cli-delegate": "esbuild src/scripts/_cli/cmd_*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
+        "build:agent-src-delegate": "esbuild src/agent-src/scripts/*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
+        "build:delegate-aux": "esbuild src/scripts/_lib/pin_resolver.ts src/scripts/check_update_banner.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outbase=src/scripts --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:ui": "vite build",
         "tokens:build": "node tokens/build-ac.mjs && node tokens/build-as.mjs",
         "tokens:check": "node tokens/build-ac.mjs --check && node tokens/build-as.mjs --check && node tokens/check-contrast.mjs",
         "build:discovery": "./scripts-run src/scripts/build_discovery_manifest --write --strict",
         "build:mcp-manifest": "./scripts-run src/scripts/build_mcp_registry_manifest --write --strict",
         "build:mcp-catalog": "./scripts-run src/scripts/build_mcp_catalog --write --strict",
-        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:ui",
+        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:agent-src-delegate && npm run build:delegate-aux && npm run build:ui",
         "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
         "lint:ts": "eslint --cache --max-warnings 0 'src/**/*.ts'",
         "test:ts": "vitest run",
@@ -116,8 +119,7 @@
         "tsx": "^4.23.1",
         "typescript": "^5.9.3",
         "vite": "^5.4.21",
-        "vitest": "^2.1.9",
-        "web-tree-sitter": "0.24.7"
+        "vitest": "^2.1.9"
     },
     "dependencies": {
         "@fastify/static": "^10.1.2",
@@ -129,6 +131,7 @@
         "js-yaml": "^5.2.0",
         "open": "^11.0.0",
         "preact": "^10.29.0",
+        "web-tree-sitter": "0.24.7",
         "yaml": "^2.9.0",
         "zod": "^3.25.0",
         "zod-to-json-schema": "^3.25.0"

package/src/agent-src/scripts/_cli_entry.ts

@@ -0,0 +1,51 @@
+/**
+ * "Was this module invoked as the command?" — one definition for the scripts
+ * under `agents/scripts` that both run directly and are imported by siblings.
+ *
+ * Five of them carried a byte-identical copy of this logic, and the copies were
+ * about to gain a sixth clause each. The interesting part is why the obvious
+ * one-liner is not enough:
+ *
+ *  - `--splitting` in `build:agent-src-delegate` can move a module body into a
+ *    shared chunk, where `import.meta.url` names the CHUNK. The URL comparison
+ *    then never matches and the command exits 0 having done nothing — measured
+ *    on `update_roadmap_progress` before this guard existed. Inside the bundle
+ *    the invoked file name is the reliable signal, so the delegate branch runs
+ *    first and a miss falls through rather than returning false.
+ *  - A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
+ *    macOS `/var` → `/private/var`) makes the raw URLs differ: `import.meta.url`
+ *    is the resolved real path while `argv[1]` keeps the symlink. Hence the
+ *    realpath comparison last.
+ *
+ * `moduleUrl` is the caller's own `import.meta.url` — it cannot be read from
+ * here, which is why it is a parameter rather than a lookup.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** Defined only by the esbuild delegate builds; `undefined` under tsx and node. */
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
+export function isCliEntry(moduleUrl: string, name: string): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    if (
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' &&
+        __AGENT_CONFIG_CLI_DELEGATE__ &&
+        path.basename(argv1, '.js') === name
+    ) {
+        return true;
+    }
+    const argvPath = path.resolve(argv1);
+    if (moduleUrl === pathToFileURL(argvPath).href) {
+        return true;
+    }
+    try {
+        return fs.realpathSync(fileURLToPath(moduleUrl)) === fs.realpathSync(argvPath);
+    } catch {
+        return false;
+    }
+}

package/src/agent-src/scripts/archive_completed_roadmaps.ts

@@ -56,11 +56,13 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { collect } from './update_roadmap_progress.js';
 import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
+import { isCliEntry } from './_cli_entry.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 interface CompletedProcess {
@@ -638,6 +640,16 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     if (dry_run) {
         return;
     }
+    // Inside `dist/cli-delegate/` the twin sits next to us as a precompiled
+    // bundle, and plain `node` runs it — the tsx walk below would otherwise
+    // reach `npx tsx`, which resolves against the CONSUMER's npm config and
+    // hard-fails on a mismatched `engines`/`devEngines` pin (the very class
+    // ADR-204 removed from the dispatcher and left standing here).
+    const bundledTwin = path.join(path.dirname(_HERE), 'update_roadmap_progress.js');
+    if (_isFile(bundledTwin)) {
+        spawnSync(process.execPath, [bundledTwin], { cwd: root, encoding: 'utf-8' });
+        return;
+    }
     const script = path.join(path.dirname(_HERE), 'update_roadmap_progress.ts');
     // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
     // dashboard generator twin through the same `tsx` runtime, cwd=root.
@@ -800,28 +812,7 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the symlink
-    // path. Compare realpaths so the entry guard still fires (without this the
-    // archival sweep silently no-ops when run through the symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'archive_completed_roadmaps')) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/src/agent-src/scripts/roadmap_gates.ts

@@ -65,7 +65,7 @@
  */
 
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import * as fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 
@@ -80,6 +80,8 @@ import { execute } from './gate_execute.js';
 import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
 import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
+import { isCliEntry } from './_cli_entry.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
@@ -928,26 +930,8 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvPath = path.resolve(process.argv[1]);
-    if (import.meta.url === pathToFileURL(argvPath).href) {
-        return true;
-    }
-    // A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
-    // macOS /var → /private/var) makes the raw URLs differ: import.meta.url is
-    // the resolved real path while argv[1] keeps the symlink. Compare realpaths
-    // so the entry guard still fires through the projection.
-    try {
-        return fs.realpathSync(_HERE) === fs.realpathSync(argvPath);
-    } catch {
-        return false;
-    }
-}
 
-if (_isCliEntry()) {
+if (isCliEntry(import.meta.url, 'roadmap_gates')) {
     process.exitCode = main();
 }
 

package/src/agent-src/scripts/roadmap_set_step.ts

@@ -30,7 +30,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -246,8 +248,9 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 }
 
+
 /* c8 ignore start */
-if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+if (isCliEntry(import.meta.url, 'roadmap_set_step')) {
     process.exit(main());
 }
 /* c8 ignore stop */

package/src/agent-src/scripts/stubs_due.ts

@@ -42,7 +42,9 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const STUB_DIR = path.join('agents', 'roadmaps', 'stubs');
 
@@ -459,24 +461,8 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
 
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'stubs_due')) {
     process.exitCode = main();
 }