@event4u/agent-config 9.31.0 → 9.32.0

package/src/scripts/report_carrier_divergence.ts

@@ -52,13 +52,25 @@
  *                    reader acting on that would have believed the host resolves
  *                    something it does not.
  *   frontmatter-only the prose is byte-identical and only the metadata block
- *                    differs. The host delivers the prose without that block, so
- *                    nothing a reader must act on reaches the model differently.
- *                    Split out because it was, measured, the ENTIRE content of
- *                    the `body-diff` class: 109 of 109 on 2026-08-10. Left inside
- *                    body-diff it manufactured the report's only actionable
- *                    class out of a metadata difference — the same mistake the
- *                    `unreadable` branch below already refuses to make.
+ *                    differs. Split out because it was, measured, the ENTIRE
+ *                    content of the `body-diff` class: 109 of 109 on 2026-08-10.
+ *                    Left inside body-diff it manufactured the report's only
+ *                    actionable class out of a metadata difference — the same
+ *                    mistake the `unreadable` branch below already refuses to
+ *                    make.
+ *                    NOT inert as a whole, and an earlier version of this entry
+ *                    wrongly said it was: the `paths:` SUBSET below is reported
+ *                    separately and IS actionable. Only the remainder — keys this
+ *                    host does not read — is safe to ignore.
+ *   `paths:` subset  a `frontmatter-only` pair whose two copies disagree about
+ *                    `paths`, the one frontmatter key the host reads. It decides
+ *                    WHEN a rule loads (matching-file read and no /compact
+ *                    re-injection, versus unconditionally at launch), so the copy
+ *                    without `paths` DEFEATS the other's scoping and an
+ *                    obligation someone deliberately scoped is silently unscoped.
+ *                    Measured 2026-08-10: 24 of the 109, all of them `paths` in
+ *                    the project copy and none in the global one. Identical prose
+ *                    does not make a schedule difference inert.
  *   provenance-only  identical after removing the two installer ownership keys.
  *                    Structural, expected, and decided against closing —
  *                    `agents/settings/contexts/dedup-reachability-refusal.md`.
@@ -83,7 +95,13 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { comparePair, type PairVerdict, proseEqual } from './_lib/carrier_divergence.js';
+import {
+    comparePair,
+    frontmatterPaths,
+    type PairVerdict,
+    proseEqual,
+    splitFrontmatter,
+} from './_lib/carrier_divergence.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -124,6 +142,13 @@ export interface CarrierDivergence {
      * something a reader has to act on.
      */
     frontmatterOnly: string[];
+    /**
+     * A SUBSET of `frontmatterOnly` whose two copies disagree about `paths:` —
+     * the one frontmatter key this host reads. Same prose, different load
+     * schedule, so this one IS actionable and must not be reported as inert
+     * metadata.
+     */
+    pathsScopeDiff: string[];
     bodyDiff: string[];
     projectOnly: string[];
     globalOnly: string[];
@@ -152,7 +177,17 @@ function _listRules(dir: string): string[] {
     }
 }
 
-/** `type:` from a rule's frontmatter, or `''` when unreadable / absent. */
+/**
+ * `type:` from a rule's frontmatter, or `''` when unreadable / absent.
+ *
+ * Reads the shared fence parser rather than re-implementing one. It used to
+ * carry its own, and the two disagreed on an unterminated fence: this one
+ * treated the WHOLE file as frontmatter, so a `type:` line anywhere in the prose
+ * could be read as the rule's type. Now an unterminated fence yields no
+ * frontmatter and therefore no type — the conservative answer, since attributing
+ * a rule to the ADR-004 manual filter on a malformed read would hide it from the
+ * drift list.
+ */
 function _ruleType(file: string): string {
     let text: string;
     try {
@@ -160,10 +195,7 @@ function _ruleType(file: string): string {
     } catch {
         return '';
     }
-    if (!text.startsWith('---')) return '';
-    const end = text.indexOf('\n---', 3);
-    const fm = end === -1 ? text : text.slice(0, end);
-    const m = /^type:\s*"?([a-z]+)"?/m.exec(fm);
+    const m = /^type:\s*"?([a-z]+)"?/m.exec(splitFrontmatter(text).frontmatter);
     return m === null ? '' : (m[1] as string);
 }
 
@@ -193,6 +225,7 @@ export function compareCarriers(
         identical: [],
         provenanceOnly: [],
         frontmatterOnly: [],
+        pathsScopeDiff: [],
         bodyDiff: [],
         projectOnly: [],
         globalOnly: [],
@@ -218,12 +251,12 @@ export function compareCarriers(
         }
         out.shared += 1;
         let verdict: PairVerdict;
-        let proseSame: boolean;
+        let projectCopy: Buffer;
+        let globalCopy: Buffer;
         try {
-            const projectCopy = fs.readFileSync(path.join(projectDir, rule));
-            const globalCopy = fs.readFileSync(path.join(globalDir, rule));
+            projectCopy = fs.readFileSync(path.join(projectDir, rule));
+            globalCopy = fs.readFileSync(path.join(globalDir, rule));
             verdict = comparePair(projectCopy, globalCopy);
-            proseSame = proseEqual(projectCopy.toString('utf-8'), globalCopy.toString('utf-8'));
         } catch {
             // An unreadable copy is not a body difference and must not be
             // reported as one — a permission error would otherwise manufacture
@@ -236,8 +269,23 @@ export function compareCarriers(
         }
         if (verdict === 'identical') out.identical.push(rule);
         else if (verdict === 'provenance-only') out.provenanceOnly.push(rule);
-        else if (proseSame) out.frontmatterOnly.push(rule);
-        else out.bodyDiff.push(rule);
+        else {
+            // Only this branch consumes the prose comparison, so it is computed
+            // here rather than beside `comparePair`: on an `identical` or
+            // `provenance-only` pair the two `toString` conversions and two fence
+            // scans are work whose result is never read.
+            const projectText = projectCopy.toString('utf-8');
+            const globalText = globalCopy.toString('utf-8');
+            if (proseEqual(projectText, globalText)) {
+                out.frontmatterOnly.push(rule);
+                // `paths:` is the one key the host reads, so a disagreement here
+                // is a load-schedule difference, not inert metadata. Recorded as
+                // a subset so the count stays reconcilable with `frontmatterOnly`.
+                if (frontmatterPaths(projectText) !== frontmatterPaths(globalText)) {
+                    out.pathsScopeDiff.push(rule);
+                }
+            } else out.bodyDiff.push(rule);
+        }
     }
     return out;
 }
@@ -269,6 +317,7 @@ export function render(d: CarrierDivergence): string {
     lines.push(`    byte-identical                     ${d.identical.length}`);
     lines.push(`    differ ONLY in the install stamp   ${d.provenanceOnly.length}`);
     lines.push(`    differ ONLY in frontmatter         ${d.frontmatterOnly.length}`);
+    lines.push(`      of which disagree on \`paths:\`    ${d.pathsScopeDiff.length}  ← ACTIONABLE`);
     lines.push(`    differ in PROSE                    ${d.bodyDiff.length}`);
     if (d.unreadable.length > 0) {
         lines.push(`    unreadable on one side             ${d.unreadable.length}  (${d.unreadable.join(', ')})`);
@@ -295,16 +344,28 @@ export function render(d: CarrierDivergence): string {
         lines.push('');
     }
 
-    if (d.frontmatterOnly.length > 0) {
-        lines.push(`  ${String(d.frontmatterOnly.length)} pair(s) differ ONLY in the frontmatter block — prose byte-identical.`);
-        lines.push('  Not a governed-text difference and nothing to act on: the host delivers the');
-        lines.push('  prose without that block, and none of the keys in it is one this host reads');
-        lines.push('  (claude-code-rules-dir-contract.md: it reads `paths`, and agent-config\'s own');
-        lines.push('  vocabulary is not read at all). Two writers, two frontmatter policies —');
-        lines.push('  `generate-tools` emits `paths` where a rule is path-scoped and nothing');
-        lines.push('  otherwise; `install.ts` writes the full vocabulary plus its ownership stamp.');
-        lines.push('  Reported as a count on purpose: naming every pair would bury the class');
-        lines.push('  above, which is the one a reader must act on.');
+    if (d.pathsScopeDiff.length > 0) {
+        lines.push(`  \`paths:\` SCOPE DISAGREEMENT (${String(d.pathsScopeDiff.length)}) — same prose, different load schedule.`);
+        lines.push('  ACT ON THESE. `paths` is the one frontmatter key this host reads: with it, a');
+        lines.push('  rule fires when a matching file is read and is NOT re-injected after');
+        lines.push('  /compact; without it, the rule loads unconditionally at launch. So the copy');
+        lines.push('  that lacks `paths` DEFEATS the other copy\'s scoping — the rule the project');
+        lines.push('  layer meant to deliver conditionally is delivered always, and an obligation');
+        lines.push('  a maintainer deliberately scoped is silently unscoped on any machine that');
+        lines.push('  carries both. Identical prose does not make this inert.');
+        for (const r of d.pathsScopeDiff) lines.push(`    - ${r}`);
+        lines.push('');
+    }
+
+    const inert = d.frontmatterOnly.length - d.pathsScopeDiff.length;
+    if (inert > 0) {
+        lines.push(`  ${String(inert)} further pair(s) differ ONLY in frontmatter the host does not read —`);
+        lines.push('  prose byte-identical, `paths` in agreement, nothing to act on. Two writers,');
+        lines.push('  two policies: `generate-tools` emits `paths` where a rule is path-scoped and');
+        lines.push('  nothing otherwise; `install.ts` writes agent-config\'s own vocabulary plus its');
+        lines.push('  ownership stamp, and none of those keys is one this host reads');
+        lines.push('  (claude-code-rules-dir-contract.md). Reported as a count on purpose: naming');
+        lines.push('  every pair would bury the two classes above, which are the actionable ones.');
         lines.push('');
     }
 
@@ -346,6 +407,10 @@ export function render(d: CarrierDivergence): string {
     if (d.bodyDiff.length === 0) {
         lines.push('');
         lines.push('  No prose divergence — no rule\'s governed text differs between the carriers.');
+        if (d.pathsScopeDiff.length > 0) {
+            lines.push('  NOT an all-clear: the `paths:` disagreements above are still open, and they');
+            lines.push('  change when a rule loads rather than what it says.');
+        }
         lines.push('  The condition is transient — it returns whenever the checkout moves ahead of');
         lines.push('  the installed release — so this is a reading of right now, not a property of');
         lines.push('  the repo. Re-run it, do not cite it. That holds doubly here: the reading also');

package/src/scripts/report_conformance_funnel.ts

@@ -147,7 +147,7 @@ export function render(r: FunnelReport): string {
     } else {
         lines.push(
             `    Divergence: ${d.shared} shared · ${d.bodyDiff.length} prose-diff · ` +
-                `${d.frontmatterOnly.length} frontmatter-only · ` +
+                `${d.frontmatterOnly.length} frontmatter-only (${d.pathsScopeDiff.length} on \`paths:\`) · ` +
                 `${d.provenanceOnly.length} provenance-only · ${d.projectOnly.length} project-only · ` +
                 `${d.globalOnly.length} global-only` +
                 (d.manualOnlyGlobal.length > 0 ? ` (${d.manualOnlyGlobal.length} by design, ADR-004 manual)` : ''),
@@ -159,9 +159,16 @@ export function render(r: FunnelReport): string {
             lines.push('    (claude-code-rules-dir-contract.md). The project copy is merely the');
             lines.push('    newer one — recency, not precedence.');
         }
-        if (d.frontmatterOnly.length > 0) {
-            lines.push(`    ${String(d.frontmatterOnly.length)} pair(s) differ only in frontmatter — prose byte-identical, nothing`);
-            lines.push('    to act on; the host delivers the prose without that block.');
+        if (d.pathsScopeDiff.length > 0) {
+            lines.push(`    \`paths:\` SCOPE DISAGREEMENT (${String(d.pathsScopeDiff.length)}) — same prose, different load`);
+            lines.push('    schedule. `paths` is the one frontmatter key the host reads, so the copy');
+            lines.push('    without it defeats the other copy\'s scoping: a deliberately scoped');
+            lines.push('    obligation is delivered unconditionally. Act on these.');
+        }
+        const inertFm = d.frontmatterOnly.length - d.pathsScopeDiff.length;
+        if (inertFm > 0) {
+            lines.push(`    ${String(inertFm)} further pair(s) differ only in frontmatter the host does not read —`);
+            lines.push('    prose byte-identical, `paths` in agreement, nothing to act on.');
         }
         if (d.unreadable.length > 0) {
             lines.push(`    Unreadable on one side (${d.unreadable.length}) — a broken install, not a disagreement.`);

package/src/scripts/routing_doctor.ts

@@ -54,8 +54,9 @@ import {
 import * as hooks_status from "./hooks_status.js";
 import { load_agent_settings } from "./_lib/agent_settings.js";
 import {
-  probeHostCapabilities,
+  describeHostCapabilities,
   type HostCapabilityManifest,
+  type HostCapabilitySources,
 } from "./_lib/host_capability.js";
 import {
   classifyLookup,
@@ -124,6 +125,17 @@ export interface OrchestrationReport {
    */
   host_platform: string;
   host_platform_assumed: boolean;
+  /**
+   * Per-field provenance for `host_manifest` — `registry` (a committed
+   * observation about this host), `live-probe` (established in this process),
+   * or `default` (nothing answered; the all-false safe default applied).
+   *
+   * Without it the six booleans read alike, and `false` cannot be told apart
+   * from "no answer". That distinction is the whole difference between "this
+   * host cannot spawn subagents" and "nobody has ever checked this host" —
+   * and this command is the one a user runs precisely to find out which.
+   */
+  host_manifest_sources: HostCapabilitySources;
   /** Verdict of the real activation gate for a canonical delegable probe. */
   activation: { action: string; reason: string };
   cost_budgets: Record<string, unknown>;
@@ -326,7 +338,8 @@ export function collect_orchestration(
   const emergency = (settings["emergency"] ?? {}) as Record<string, unknown>;
   const halted = emergency["orchestration_halt"] === true;
   const downshift = sub["downshift"] !== false;
-  const host_manifest = probeHostCapabilities(platform);
+  const { manifest: host_manifest, sources: host_manifest_sources } =
+    describeHostCapabilities(platform);
   const activationInputs: ActivationInputs = {
     halted,
     subagent_spawn: host_manifest.subagent_spawn,
@@ -372,6 +385,7 @@ export function collect_orchestration(
     host_manifest,
     host_platform: platform,
     host_platform_assumed: platform_assumed,
+    host_manifest_sources,
     activation: { action: probe.action, reason: probe.reason },
     cost_budgets,
     ledger_present,
@@ -611,6 +625,15 @@ function _render(report: DoctorReport): string {
         `and the capability registry is keyed on it. Pass --platform <host> to check another.`,
     );
   }
+  const provenanceBits = Object.entries(o.host_manifest_sources).map(
+    ([field, src]) =>
+      `${field}=${o.host_manifest[field as keyof HostCapabilityManifest]}(${src})`,
+  );
+  lines.push(`  capability provenance: ${provenanceBits.join(" · ")}`);
+  lines.push(
+    `  registry = committed observation about this host, not a live check · ` +
+      `default = nobody answered, rendered as false`,
+  );
   const tierBits = Object.entries(o.tier_budgets).map(([t, s]) => {
     const cap = s.ceiling_usd === null ? "no cap" : `$${s.ceiling_usd}`;
     const cool = s.cooldown_until_ms > 0 ? " COOLING" : "";

package/src/scripts/schemas/dod.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dod.schema.json",
+  "title": "Executable definition of done",
+  "description": "The `dod[]` slot a refined ticket or prompt envelope may carry. `dod` is EXECUTABLE by construction: every item names the command that proves it, so the engine can report which items are still unproven without asking a human to interpret prose. Prose acceptance criteria stay where they are (`acceptance_criteria`) — this is the machine-checkable subset, not a replacement. The slot is OPTIONAL: a ticket without `dod` behaves exactly as before, which is why the `refine` gate validates the shape only when the key is present. Consumed by `work_engine/directives/backend/refine.ts` (shape gate) and reported by `work_engine/directives/backend/_self_fix.ts` at the PARTIAL exit.",
+  "type": "object",
+  "required": [
+    "dod"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "dod": {
+      "type": "array",
+      "description": "May be empty. An empty array means the author declared no machine-checkable done-condition, which is different from omitting the key: omission means the question was never asked. Both are legal and neither blocks.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "check"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable identifier, unique within the array. Used verbatim in the self-fix PARTIAL exit so a reader can match an unproven item back to the ticket without re-reading the whole envelope."
+          },
+          "check": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The command that proves this item — a test filter, a linter invocation, a curl probe. Prose here defeats the point of the slot: the engine never runs it (the dispatcher spawns no subprocesses, per the delegation contract), it hands it to the agent, and an agent cannot run a sentence."
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional human sentence for the halt surface. Absent is fine — `check` is already the falsifiable half."
+          },
+          "proven": {
+            "type": "boolean",
+            "description": "Set by the agent once `check` has actually been run green. Absent or `false` both mean unproven; the engine never infers `true` from a passing suite, because a suite passing is not evidence that THIS check ran."
+          }
+        }
+      }
+    }
+  }
+}

package/dist/cli-delegate/chunk-RVGBH4XK.js

@@ -1,142 +0,0 @@
-import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
-
-// src/scripts/_lib/recycle_envelope_paths.ts
-import * as path from "node:path";
-var RECYCLE_ENVELOPE_REL = path.join("agents", "runtime", "state", "recycle-envelope.json");
-var RECYCLE_CONSUMED_REL = path.join(
-  "agents",
-  "runtime",
-  "state",
-  "recycle-envelope.consumed.json"
-);
-var RECYCLE_MAX_AGE_HOURS = 48;
-var RECYCLE_ENVELOPE_MAX_BYTES = 6144;
-
-// src/scripts/_lib/subagent_capsule.ts
-var EPISTEMIC_STATES = ["verified", "assumed", "gap"];
-var EPISTEMIC = new Set(EPISTEMIC_STATES);
-var MAX_REF_CHARS = 200;
-var MAX_LINE_CHARS = 240;
-var MAX_ENTRIES = 40;
-var CAPSULE_SCHEMA_VERSION = 2;
-function isShortLine(value, max) {
-  return typeof value === "string" && value.length > 0 && value.length <= max && !value.includes("\n");
-}
-function checkList(errors, field, value, max, required) {
-  if (value === void 0) {
-    if (required) errors.push(`${field} is required`);
-    return;
-  }
-  if (!Array.isArray(value)) {
-    errors.push(`${field} must be an array`);
-    return;
-  }
-  if (value.length > MAX_ENTRIES) {
-    errors.push(`${field} carries ${value.length} entries (max ${MAX_ENTRIES}) \u2014 a capsule is a handoff, not a transcript`);
-  }
-  const bad = value.filter((x) => !isShortLine(x, max));
-  if (bad.length > 0) {
-    errors.push(
-      `${field} carries ${bad.length} entr${bad.length === 1 ? "y" : "ies"} that are not single lines of \u2264 ${max} chars (refs and short lines only, never bodies)`
-    );
-  }
-}
-var RECYCLE_ENVELOPE_KEYS = /* @__PURE__ */ new Set([
-  "capsule_version",
-  "variant",
-  "summary",
-  "task",
-  "workspace",
-  "written_at",
-  "acceptance_criteria",
-  "remaining",
-  "not_carried_forward",
-  "decisions",
-  "constraints",
-  "open_worker_envelopes",
-  "artifact_paths",
-  "assumptions"
-]);
-function validateRecycleEnvelope(input) {
-  const errors = [];
-  if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    return ["not an object"];
-  }
-  const e = input;
-  for (const key of Object.keys(e)) {
-    if (!RECYCLE_ENVELOPE_KEYS.has(key)) {
-      errors.push(
-        `unknown field "${key}" \u2014 a recycle envelope carries selection and pointers only; free-form additions (prose summaries included) are schema-invalid by construction`
-      );
-    }
-  }
-  if (e["capsule_version"] !== CAPSULE_SCHEMA_VERSION) {
-    errors.push(`capsule_version must be ${CAPSULE_SCHEMA_VERSION}`);
-  }
-  if (e["variant"] !== "main_session") {
-    errors.push("variant must be 'main_session'");
-  }
-  if (!isShortLine(e["summary"], MAX_LINE_CHARS)) {
-    errors.push(`summary must be a single line of 1\u2013${MAX_LINE_CHARS} chars`);
-  }
-  if (!isShortLine(e["task"], MAX_LINE_CHARS)) {
-    errors.push(`task must be a single line of 1\u2013${MAX_LINE_CHARS} chars`);
-  }
-  if (!isShortLine(e["workspace"], MAX_REF_CHARS)) {
-    errors.push(`workspace must be a path ref of \u2264 ${MAX_REF_CHARS} chars`);
-  }
-  const writtenAt = e["written_at"];
-  if (typeof writtenAt !== "string" || Number.isNaN(Date.parse(writtenAt))) {
-    errors.push("written_at must be a parseable ISO-8601 timestamp");
-  }
-  checkList(errors, "acceptance_criteria", e["acceptance_criteria"], MAX_LINE_CHARS, true);
-  if (Array.isArray(e["acceptance_criteria"]) && e["acceptance_criteria"].length === 0) {
-    errors.push('acceptance_criteria must carry at least one entry \u2014 the successor cannot know "done" without it');
-  }
-  checkList(errors, "remaining", e["remaining"], MAX_LINE_CHARS, true);
-  checkList(errors, "not_carried_forward", e["not_carried_forward"], MAX_LINE_CHARS, true);
-  checkList(errors, "decisions", e["decisions"], MAX_LINE_CHARS, false);
-  checkList(errors, "constraints", e["constraints"], MAX_LINE_CHARS, false);
-  checkList(errors, "open_worker_envelopes", e["open_worker_envelopes"], MAX_REF_CHARS, false);
-  checkList(errors, "artifact_paths", e["artifact_paths"], MAX_REF_CHARS, false);
-  const assumptions = e["assumptions"];
-  if (assumptions !== void 0) {
-    if (!Array.isArray(assumptions)) {
-      errors.push("assumptions must be an array");
-    } else {
-      if (assumptions.length > MAX_ENTRIES) {
-        errors.push(`assumptions carries ${assumptions.length} entries (max ${MAX_ENTRIES})`);
-      }
-      for (const [i, raw] of assumptions.entries()) {
-        errors.push(...validateAssumption(raw, `assumptions[${i}]`));
-      }
-    }
-  }
-  return errors;
-}
-function validateAssumption(input, label = "assumption") {
-  const errors = [];
-  if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    return [`${label} is not an object`];
-  }
-  const a = input;
-  if (!isShortLine(a["statement"], MAX_LINE_CHARS)) {
-    errors.push(`${label}.statement must be a single line of 1\u2013${MAX_LINE_CHARS} chars`);
-  }
-  if (!isShortLine(a["basis"], MAX_REF_CHARS)) {
-    errors.push(`${label}.basis must be a ref token (file:line, id, path, command) of \u2264 ${MAX_REF_CHARS} chars`);
-  }
-  if (typeof a["epistemic_state"] !== "string" || !EPISTEMIC.has(a["epistemic_state"])) {
-    errors.push(`${label}.epistemic_state must be one of ${EPISTEMIC_STATES.join(" | ")}`);
-  }
-  return errors;
-}
-
-export {
-  RECYCLE_ENVELOPE_REL,
-  RECYCLE_CONSUMED_REL,
-  RECYCLE_MAX_AGE_HOURS,
-  RECYCLE_ENVELOPE_MAX_BYTES,
-  CAPSULE_SCHEMA_VERSION,
-  validateRecycleEnvelope
-};