@event4u/agent-config 14.20.0 → 14.22.0

package/dist/scripts/ai_council/content_ceiling.js

@@ -0,0 +1,63 @@
+/**
+ * One binary content ceiling per seat — road-to-admissible-council-seats 2.2.
+ *
+ * Redaction today is a SECRETS floor and says so
+ * (`src/skills/ai-council/references/cost-and-redaction.md`). Nothing above it
+ * could express "this project's diff may not go to that seat", which is a
+ * different question with a different answer: a diff carrying no secret at all
+ * is still the consumer's private source.
+ *
+ * Deliberately BINARY. A graded scale invites a middle value nobody can define
+ * and every caller reads differently; two values force the decision at
+ * authoring time, where it belongs.
+ *
+ *   public-artifact  — repo-owned artefacts: skill descriptions, the trigger
+ *                      corpus, rule text, bench fixtures. Already public.
+ *   project-content  — everything a consumer supplies. The DEFAULT, so an
+ *                      unclassified payload is treated as private rather than
+ *                      as publishable.
+ *
+ * A seat's ceiling is the most sensitive class it may receive. `public-artifact`
+ * is therefore the NARROWER seat: it admits public artefacts only.
+ */
+export const CONTENT_CLASSES = ['public-artifact', 'project-content'];
+/** The default for anything not explicitly classified: private, not public. */
+export const DEFAULT_CONTENT_CLASS = 'project-content';
+/** The default seat ceiling: unchanged behaviour for every existing seat. */
+export const DEFAULT_SEAT_CEILING = 'project-content';
+const _SET = new Set(CONTENT_CLASSES);
+/**
+ * Any configured value → a content class. Unrecognised input becomes
+ * `project-content`, the RESTRICTIVE value: a typo must narrow what a seat may
+ * receive, never widen it.
+ */
+export function classifyContentClass(raw, fallback = DEFAULT_CONTENT_CLASS) {
+    if (typeof raw === 'string' && _SET.has(raw)) {
+        return raw;
+    }
+    return fallback;
+}
+/**
+ * Does a seat whose ceiling is `seatCeiling` admit a payload of `contentClass`?
+ *
+ * The one refusal is `project-content` into a `public-artifact` seat. Every
+ * other pairing is admitted, including public artefacts into a
+ * `project-content` seat — a seat cleared for private content is trivially
+ * cleared for public content, and refusing that would be a nonsense that
+ * disables the default seat for its own repo's fixtures.
+ *
+ * Refusal is a GREEN path (this roadmap's 2.2 verify): the caller drops the
+ * seat and the run continues. It is not an error, because a policy working as
+ * designed is not a failure.
+ */
+export function admitsContent(seatCeiling, contentClass) {
+    if (seatCeiling === 'public-artifact' && contentClass === 'project-content') {
+        return {
+            admitted: false,
+            reason: "seat ceiling is 'public-artifact'; the payload is classified " +
+                "'project-content' (consumer-supplied)",
+        };
+    }
+    return { admitted: true, reason: null };
+}
+//# sourceMappingURL=content_ceiling.js.map

package/dist/scripts/ai_council/seat_policy.js

@@ -0,0 +1,106 @@
+import { classifyContentClass as _classifyContentClass, DEFAULT_SEAT_CEILING as _DEFAULT_SEAT_CEILING, } from './content_ceiling.js';
+/**
+ * Seat policy — the vocabulary for refusing a route that IS reachable.
+ *
+ * road-to-admissible-council-seats 2.1. `AbsentReason` was exactly four values
+ * — `no_binary | no_auth | timeout | quota` — and every one of them means "the
+ * route is not reachable". A route that is reachable and **must not be used**
+ * had no name at all, so the resolver could not fail closed on terms, privacy,
+ * unproven cost, or a served model that is not the requested one. The absence
+ * of a word was the absence of the refusal: `resolveTransport`'s `api`/`cli`
+ * branches return `available: true` unconditionally, so anything the four
+ * reachability reasons could not express resolved OPEN.
+ *
+ * Fail closed on the unknown, which is the whole point.
+ * `classifyPolicyExclusion` maps anything it does not recognise to
+ * `policy_unknown`, and `policy_unknown` is an ABSENT reason like every other
+ * member of this union. An unrecognised policy token is the case where the
+ * config is trying to say something the code cannot understand; resolving it
+ * to "available" would make a typo an authorisation. This is the roadmap's own
+ * Risk 3 — "a new refusal vocabulary defaults open instead of closed".
+ *
+ * What this is NOT. It is not a secrets floor. Redaction (`skills/ai-council/references/
+ * cost-and-redaction.md`) still runs underneath and is not replaced. It is not
+ * an authorisation either: nothing here ever makes a seat available that was
+ * not already available — every value in the union only ever subtracts.
+ */
+/** Reachable-but-refused reasons. Every value means ABSENT. */
+export const POLICY_EXCLUSIONS = [
+    /** The provider's terms forbid this use of the route. */
+    'policy_terms',
+    /** A privacy constraint forbids sending to this route. */
+    'policy_privacy',
+    /** The route's cost property is asserted rather than proven. */
+    'policy_unproven_cost',
+    /** The route serves a model other than the one requested. */
+    'policy_model_mismatch',
+    /** 2.2 — the payload's content class exceeds the seat's ceiling. */
+    'policy_content_ceiling',
+    /** The config named an exclusion this build does not understand. */
+    'policy_unknown',
+];
+const _SET = new Set(POLICY_EXCLUSIONS);
+/** True for a value this build can act on. `policy_unknown` included: it is a
+ *  real, actionable verdict (refuse), not a parse failure. */
+export function isPolicyExclusion(v) {
+    return typeof v === 'string' && _SET.has(v);
+}
+/**
+ * Any configured value → a verdict. Unrecognised input, including `null` used
+ * where a string was meant, becomes `policy_unknown` — never `null`, because a
+ * `null` return would put the caller back in the position of deciding what an
+ * unreadable policy means, which is where the open default came from.
+ *
+ * `undefined` and `null` are the two ways of saying "no exclusion configured"
+ * and are the ONLY inputs that return `null`. Everything else is a refusal.
+ */
+export function classifyPolicyExclusion(raw) {
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    return isPolicyExclusion(raw) ? raw : 'policy_unknown';
+}
+/** One-line human reason for a refusal. `council:status` prints this. */
+export function policyExclusionReason(p, provider) {
+    const who = provider === undefined ? 'this seat' : provider;
+    switch (p) {
+        case 'policy_terms':
+            return `${who} is excluded by policy: the route's terms forbid this use`;
+        case 'policy_privacy':
+            return `${who} is excluded by policy: a privacy constraint forbids this route`;
+        case 'policy_unproven_cost':
+            return `${who} is excluded by policy: the route's cost property is asserted, not proven`;
+        case 'policy_model_mismatch':
+            return `${who} is excluded by policy: the route serves a model other than the one requested`;
+        case 'policy_content_ceiling':
+            return `${who} is excluded by policy: the payload exceeds the seat's content ceiling`;
+        case 'policy_unknown':
+            return `${who} is excluded by policy: an exclusion this build does not understand (failing closed)`;
+    }
+}
+export function parseSeatFields(name, raw) {
+    const dr = raw['disabled_reason'];
+    let disabled_reason = null;
+    if (dr !== undefined && dr !== null) {
+        if (typeof dr !== 'string' || dr.trim() === '') {
+            return {
+                error: `members.${name}.disabled_reason must be a non-empty string when set ` +
+                    `(got ${JSON.stringify(dr)}).`,
+            };
+        }
+        disabled_reason = dr.trim();
+    }
+    // Both of the next two fail CLOSED on an unreadable value: an unknown
+    // exclusion token becomes `policy_unknown` (which resolves ABSENT) and an
+    // unknown ceiling falls back to the RESTRICTIVE one. Throwing instead would
+    // be defensible, but a config typo would then take the whole council down
+    // rather than the one seat it names.
+    return {
+        fields: {
+            disabled_reason,
+            policy_exclusion: classifyPolicyExclusion(raw['policy_exclusion']),
+            content_ceiling: _classifyContentClass(raw['content_ceiling'], _DEFAULT_SEAT_CEILING),
+        },
+    };
+}
+//# sourceMappingURL=seat_policy.js.map

package/dist/scripts/ai_council/transport_resolver.js

@@ -40,6 +40,8 @@
  */
 import { classifyBilling, isCommunityCli, strongestAuth, PROVIDER_CLI_META, } from '../_lib/environment_detector.js';
 import { resolve_mode } from './modes.js';
+import { admitsContent, DEFAULT_SEAT_CEILING, } from './content_ceiling.js';
+import { policyExclusionReason } from './seat_policy.js';
 /** The accepted values of the `mode` key, including the resolver-only `auto`. */
 export const VALID_TRANSPORT_MODES = new Set([
     'api',
@@ -84,6 +86,22 @@ export function resolveTransport(opts) {
     const auth = strongestAuth(report, provider);
     const authSource = auth?.source ?? null;
     const billing = classifyBilling(provider, authSource);
+    // Policy first (2.1). Before the mode dispatch, because `api` and `cli`
+    // below return `available: true` UNCONDITIONALLY — a refusal placed after
+    // them would be unreachable for exactly the seats it exists to stop.
+    const exclusion = opts.policyExclusion ?? null;
+    if (exclusion !== null) {
+        return unavailable(provider, billing, policyExclusionReason(exclusion, provider), exclusion);
+    }
+    // Content ceiling (2.2). Only runs when the caller declared what it would
+    // send; an undeclared pass is unchanged, not silently refused.
+    const contentClass = opts.contentClass ?? null;
+    if (contentClass !== null) {
+        const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
+        if (!verdict.admitted) {
+            return unavailable(provider, billing, `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`, 'policy_content_ceiling');
+        }
+    }
     if (mode === 'manual') {
         return {
             available: true,
@@ -173,6 +191,9 @@ export function resolveMemberTransport(opts) {
         // optional-boolean field, so the key is omitted entirely rather than
         // forwarded as `apiKeyPresent: undefined`.
         ...(opts.apiKeyPresent !== undefined ? { apiKeyPresent: opts.apiKeyPresent } : {}),
+        policyExclusion: opts.policyExclusion ?? null,
+        seatCeiling: opts.seatCeiling ?? null,
+        contentClass: opts.contentClass ?? null,
     });
     return { ...resolved, configuredMode };
 }

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.