@event4u/agent-config 14.22.0 → 15.0.0

package/src/config/rule-stub-ceilings.json

@@ -1,5 +1,5 @@
 {
-    "_comment": "Per-rule stub ceilings (road-to-rule-stub-projection Phase 2). One exact-BPE token ceiling per rule carrying a migration pointer. SHRINK-ONLY: a rule may fall below its ceiling freely, and may not rise above it. Raising a ceiling to clear a failing check is the config-weakening move this repo blocks by construction \u2014 every raise needs a `history` entry whose `reason` is a real sentence. The ceilings are a floor-plus-residue SNAPSHOT taken at adoption, not a target: a rule at its ceiling is not thereby correct, only not worse. Regenerate with `check_rule_stub_ceiling --write-baseline`; never hand-edit the counts.",
+    "_comment": "Per-rule stub ceilings (road-to-rule-stub-projection Phase 2). One exact-BPE token ceiling per rule carrying a migration pointer. SHRINK-ONLY: a rule may fall below its ceiling freely, and may not rise above it. Raising a ceiling to clear a failing check is the config-weakening move this repo blocks by construction — every raise needs a `history` entry whose `reason` is a real sentence. The ceilings are a floor-plus-residue SNAPSHOT taken at adoption, not a target: a rule at its ceiling is not thereby correct, only not worse. Regenerate with `check_rule_stub_ceiling --write-baseline`; never hand-edit the counts.",
     "measured_at_commit": "580cb1138",
     "tokens_exact": true,
     "ceilings": {
@@ -43,7 +43,7 @@
         "skill-quality": 78,
         "slash-command-routing-policy": 77,
         "symfony-routing": 129,
-        "ui-audit-gate": 1491,
+        "ui-audit-gate": 1517,
         "untrusted-input-defense": 934,
         "upstream-proposal": 76
     },
@@ -53,21 +53,21 @@
             "rule": "roadmap-progress-sync",
             "from": 1424,
             "to": 2117,
-            "reason": "Iron Law 3 gained the preservation test that decides WHO resolves a deferred item \u2014 a routing table plus the two council refinements that make it binding (a follow-up naming a roadmap that does not exist yet fails closed to the user; a council resolution is recorded at the item or it did not happen) and the residual limit both authoring seats named. This is obligation surface, not explanation: the table decides a route and the two refinements are the conditions under which the route is legal, so a reader who reaches only the pointer target has already made the decision. It could not move to the pointer target either \u2014 roadmap-progress-mechanics.md sits at the 16,000-char check_depth_budget ceiling in this same change, and pushing prose there reds a count ratchet whose whole job is refusing a fifth over-ceiling file. The section was condensed once before this raise (2201 -> 2117) by turning four prose paragraphs into bullets; further cutting would delete substance, which preservation-guard forbids."
+            "reason": "Iron Law 3 gained the preservation test that decides WHO resolves a deferred item — a routing table plus the two council refinements that make it binding (a follow-up naming a roadmap that does not exist yet fails closed to the user; a council resolution is recorded at the item or it did not happen) and the residual limit both authoring seats named. This is obligation surface, not explanation: the table decides a route and the two refinements are the conditions under which the route is legal, so a reader who reaches only the pointer target has already made the decision. It could not move to the pointer target either — roadmap-progress-mechanics.md sits at the 16,000-char check_depth_budget ceiling in this same change, and pushing prose there reds a count ratchet whose whole job is refusing a fifth over-ceiling file. The section was condensed once before this raise (2201 -> 2117) by turning four prose paragraphs into bullets; further cutting would delete substance, which preservation-guard forbids."
         },
         {
             "date": "2026-08-20",
             "rule": "context-hygiene",
             "from": 2447,
             "to": 2470,
-            "reason": "One sentence, +23 tokens, and it is obligation surface rather than explanation: for CI, do not hand-write the wait loop. The mechanics went to the pointer target where this rule's own migration note already sends them (context-hygiene-mechanics gains the exit codes, the four not-settled states and the measured incident) \u2014 that move is what took the growth from +179 to +23, and the residue is the pointer itself, which cannot live in the guideline because a rule that does not name the helper is a rule nobody follows to it. The incident it encodes: a hand-written `until ! gh pr checks N | grep -q pending` exited when the API failed, because the error text contains no `pending`, and the session reported a settle that had not happened and retracted it in the next reply. The rule's neighbouring waiter law already says one waiter per condition; what it did not say is that the exit condition is the part that gets written wrong, which is why the helper is named here rather than described."
+            "reason": "One sentence, +23 tokens, and it is obligation surface rather than explanation: for CI, do not hand-write the wait loop. The mechanics went to the pointer target where this rule's own migration note already sends them (context-hygiene-mechanics gains the exit codes, the four not-settled states and the measured incident) — that move is what took the growth from +179 to +23, and the residue is the pointer itself, which cannot live in the guideline because a rule that does not name the helper is a rule nobody follows to it. The incident it encodes: a hand-written `until ! gh pr checks N | grep -q pending` exited when the API failed, because the error text contains no `pending`, and the session reported a settle that had not happened and retracted it in the next reply. The rule's neighbouring waiter law already says one waiter per condition; what it did not say is that the exit condition is the part that gets written wrong, which is why the helper is named here rather than described."
         },
         {
             "date": "2026-08-20",
             "rule": "roadmap-progress-sync",
             "from": 2117,
             "to": 2185,
-            "reason": "One sentence in Iron Law 1, +68 tokens, and it is obligation surface rather than explanation: `roadmap:progress` now passes `--archive`, so the law's operational meaning changed \u2014 a complete roadmap is moved by the same run instead of reported to a human, and the two exclusions a reader must know before trusting that (`--check` never archives, the PostToolUse hook never archives) are exactly the part that cannot be deferred to a pointer. The prose was NOT moved to docs/guidelines/agent-infra/roadmap-progress-mechanics.md, which is where this rule's migration note sends its mechanics, because that file has roughly a hundred characters of headroom under the 16,000-char depth ceiling and check_depth_budget is shrink-only with four files already over it \u2014 a FIFTH over-ceiling file reds, so moving 400 characters there would have traded this gate for that one. The full contract, the council record and its recorded dissent live with the code in src/agent-src/scripts/archival_sweep.ts, which is the third home and the one with room."
+            "reason": "One sentence in Iron Law 1, +68 tokens, and it is obligation surface rather than explanation: `roadmap:progress` now passes `--archive`, so the law's operational meaning changed — a complete roadmap is moved by the same run instead of reported to a human, and the two exclusions a reader must know before trusting that (`--check` never archives, the PostToolUse hook never archives) are exactly the part that cannot be deferred to a pointer. The prose was NOT moved to docs/guidelines/agent-infra/roadmap-progress-mechanics.md, which is where this rule's migration note sends its mechanics, because that file has roughly a hundred characters of headroom under the 16,000-char depth ceiling and check_depth_budget is shrink-only with four files already over it — a FIFTH over-ceiling file reds, so moving 400 characters there would have traded this gate for that one. The full contract, the council record and its recorded dissent live with the code in src/agent-src/scripts/archival_sweep.ts, which is the third home and the one with room."
         },
         {
             "date": "2026-08-20",
@@ -95,7 +95,7 @@
             "rule": "design-fidelity",
             "from": 2245,
             "to": 2540,
-            "reason": "One subsection, +295 tokens, for the second axis: artifact MATURITY is a property of the handed-over artifact, instruction MANDATE is a property of the prose, and `strict` on a self-declared wireframe is a structure mandate rather than a pixel mandate. It is an Iron Law plus the two discriminator clauses that decide it -- obligation surface, which this repository's rule/mechanics split puts in the rule by construction. The lookup half ALREADY went to the pointer target in the same change: the maturity-to-spec table and the pinned `daf-wireframe-near-miss` row live in design-fidelity-mechanics.md \u00a7 Artifact maturity, and the rule links them. Pushing the remaining prose there too is the one move that is not available -- that migration is exactly what took the mechanics file from 15,265 to 16,524 chars past check_depth_budget's 16,000 ceiling, and paying for it required splitting the asset & imagery block out into its own guideline in this same commit series. A second push would re-red the ratchet the split just cleared. Raised rather than condensed because the two clauses that would compress are the ones that carry the decision: 'the discriminator reads the ARTEFACT, never the prose' and 'an undeclared artifact is treated as finished' -- drop either and the rule authorises the redesign it exists to prevent."
+            "reason": "One subsection, +295 tokens, for the second axis: artifact MATURITY is a property of the handed-over artifact, instruction MANDATE is a property of the prose, and `strict` on a self-declared wireframe is a structure mandate rather than a pixel mandate. It is an Iron Law plus the two discriminator clauses that decide it -- obligation surface, which this repository's rule/mechanics split puts in the rule by construction. The lookup half ALREADY went to the pointer target in the same change: the maturity-to-spec table and the pinned `daf-wireframe-near-miss` row live in design-fidelity-mechanics.md § Artifact maturity, and the rule links them. Pushing the remaining prose there too is the one move that is not available -- that migration is exactly what took the mechanics file from 15,265 to 16,524 chars past check_depth_budget's 16,000 ceiling, and paying for it required splitting the asset & imagery block out into its own guideline in this same commit series. A second push would re-red the ratchet the split just cleared. Raised rather than condensed because the two clauses that would compress are the ones that carry the decision: 'the discriminator reads the ARTEFACT, never the prose' and 'an undeclared artifact is treated as finished' -- drop either and the rule authorises the redesign it exists to prevent."
         },
         {
             "date": "2026-08-23",
@@ -116,21 +116,28 @@
             "rule": "improve-before-implement",
             "from": 845,
             "to": 1385,
-            "reason": "road-to-evidence-gated-change Phase 3 lands D5 in this rule: the existence question was inert on bug fixes and trivial changes, which are the classes that most often re-add a helper the tree already has. +540 tokens, and each of the four additions is obligation surface rather than lookup material \u2014 the narrowed exclusion (the three heavy checks stay excluded, the one cheap question does not) with the diff-decidable skip that keeps it cheap, the six named verdicts with negative evidence owed for `new`, the two clauses that keep the set from degrading into a ranking or into similarity-driven abstraction, and the recorded reason the gate is not routed through /tdd. Migrating any of it to the pointer target is the one move that is not available: docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md sits at 15,992 of the 16,000-char check_depth_budget ceiling \u2014 eight characters \u2014 and that gate is a shrink-only ratchet already carrying four baseline violations whose own note says a FIFTH over-ceiling file reds. Raised rather than condensed because the clauses that would compress are the ones carrying the decision: drop the heavy/cheap split and the question becomes a tax on the highest-frequency change class (risk-register row 3 of that roadmap), drop the negative-evidence clause and `new` becomes the default verdict again."
+            "reason": "road-to-evidence-gated-change Phase 3 lands D5 in this rule: the existence question was inert on bug fixes and trivial changes, which are the classes that most often re-add a helper the tree already has. +540 tokens, and each of the four additions is obligation surface rather than lookup material — the narrowed exclusion (the three heavy checks stay excluded, the one cheap question does not) with the diff-decidable skip that keeps it cheap, the six named verdicts with negative evidence owed for `new`, the two clauses that keep the set from degrading into a ranking or into similarity-driven abstraction, and the recorded reason the gate is not routed through /tdd. Migrating any of it to the pointer target is the one move that is not available: docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md sits at 15,992 of the 16,000-char check_depth_budget ceiling — eight characters — and that gate is a shrink-only ratchet already carrying four baseline violations whose own note says a FIFTH over-ceiling file reds. Raised rather than condensed because the clauses that would compress are the ones carrying the decision: drop the heavy/cheap split and the question becomes a tax on the highest-frequency change class (risk-register row 3 of that roadmap), drop the negative-evidence clause and `new` becomes the default verdict again."
         },
         {
             "date": "2026-08-27",
             "rule": "artifact-drafting-protocol",
             "from": 680,
             "to": 690,
-            "reason": "road-to-composition-before-creation Phase 3.3 makes Phase B's verdict a WRITTEN record rather than only a reasoned one, so the rule has to name the field that carries it. +74 tokens, 680 -> 754, and the split was deliberate: everything that is lookup material \u2014 the field's YAML shape, the four dispositions with their discriminators, why `none_found` must exist so an author is never pushed to invent an incumbent, why `create_separate` is the value no incumbent vocabulary can express, and what the lint can and cannot check \u2014 went to the pointer target (`docs/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md` \u00a7 Where the answer is written). What stayed is obligation surface and cannot be moved without the rule mandating a field it does not name: that the verdict is written into the artifact, the field's name, and the measurement behind it (1 of the 20 most recently added skills and rules carried a machine-readable record \u2014 `agents/evidence/analysis/authoring-search-record-sample-2026-08-27.md`). Net +10 (680 -> 690), and the drafting history is the part worth recording because the net hides it: the first draft added +248 (to 928) and FOUR shrink passes brought it back -- 928 -> 783 -> 754 -> 690 -- the last one forced by a different gate rather than chosen. An independent review read the earlier wording as contradicting the structured `from: 680, to: 690`; one seat called it cumbersome rather than wrong. Stated both ways now: initial draft +248, final net +10. `check_preamble_payload_budget` reds at 138,212 tokens -- its grace ceiling, set to the exact measured total on 2026-08-24 with zero slack and expiring 2026-11-10 -- and `origin/main` measures 138,195, so this branch had **17 tokens** of headroom for the whole rule payload, not 74. The addition was therefore folded into the existing Phase-B parenthetical instead of added as a paragraph, which is both cheaper and better placed: the field is now named where the phase is described. Measured after: 138,208, four under the ceiling. The ceiling here is the exact measured count with no slack, so the next growth is caught rather than absorbed."
+            "reason": "road-to-composition-before-creation Phase 3.3 makes Phase B's verdict a WRITTEN record rather than only a reasoned one, so the rule has to name the field that carries it. +74 tokens, 680 -> 754, and the split was deliberate: everything that is lookup material — the field's YAML shape, the four dispositions with their discriminators, why `none_found` must exist so an author is never pushed to invent an incumbent, why `create_separate` is the value no incumbent vocabulary can express, and what the lint can and cannot check — went to the pointer target (`docs/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md` § Where the answer is written). What stayed is obligation surface and cannot be moved without the rule mandating a field it does not name: that the verdict is written into the artifact, the field's name, and the measurement behind it (1 of the 20 most recently added skills and rules carried a machine-readable record — `agents/evidence/analysis/authoring-search-record-sample-2026-08-27.md`). Net +10 (680 -> 690), and the drafting history is the part worth recording because the net hides it: the first draft added +248 (to 928) and FOUR shrink passes brought it back -- 928 -> 783 -> 754 -> 690 -- the last one forced by a different gate rather than chosen. An independent review read the earlier wording as contradicting the structured `from: 680, to: 690`; one seat called it cumbersome rather than wrong. Stated both ways now: initial draft +248, final net +10. `check_preamble_payload_budget` reds at 138,212 tokens -- its grace ceiling, set to the exact measured total on 2026-08-24 with zero slack and expiring 2026-11-10 -- and `origin/main` measures 138,195, so this branch had **17 tokens** of headroom for the whole rule payload, not 74. The addition was therefore folded into the existing Phase-B parenthetical instead of added as a paragraph, which is both cheaper and better placed: the field is now named where the phase is described. Measured after: 138,208, four under the ceiling. The ceiling here is the exact measured count with no slack, so the next growth is caught rather than absorbed."
         },
         {
             "date": "2026-09-02",
             "rule": "code-comment-discipline",
             "from": 692,
             "to": 750,
-            "reason": "Three Iron Law lines folded into the rule's existing block: a comment naming where the code came from is evidence in the wrong place, provenance is not a WHY, and a roadmap cannot license a comment this rule forbids. That is obligation surface \u2014 it decides what an author may write \u2014 and preservation-guard forbids condensing an Iron Law further. Everything explanatory went to the pointer target the rule already names: the measured case (509 German comment lines and 21 report- or provenance-shaped comments across 41 of 45 changed source files in a consumer repository, including a 101-line colour-analysis report inside a CSS file), the reason the rule's own keyword triggers miss the write, and the two enforcers. Three condensations took the growth from +546 to +58: move to the guideline, then fold into the existing Iron Law block rather than open a second section. The ceiling is set at the measured body rather than above it \u2014 headroom nobody has a use for is the spendable-surplus failure this file's own comment names."
+            "reason": "Three Iron Law lines folded into the rule's existing block: a comment naming where the code came from is evidence in the wrong place, provenance is not a WHY, and a roadmap cannot license a comment this rule forbids. That is obligation surface — it decides what an author may write — and preservation-guard forbids condensing an Iron Law further. Everything explanatory went to the pointer target the rule already names: the measured case (509 German comment lines and 21 report- or provenance-shaped comments across 41 of 45 changed source files in a consumer repository, including a 101-line colour-analysis report inside a CSS file), the reason the rule's own keyword triggers miss the write, and the two enforcers. Three condensations took the growth from +546 to +58: move to the guideline, then fold into the existing Iron Law block rather than open a second section. The ceiling is set at the measured body rather than above it — headroom nobody has a use for is the spendable-surplus failure this file's own comment names."
+        },
+        {
+            "date": "2026-09-09",
+            "rule": "ui-audit-gate",
+            "from": 1491,
+            "to": 1517,
+            "reason": "road-to-design-intent-conformance 3.3 qualifies this rule's one unqualified sentence. \"Run existing-ui-audit before adding a component because reuse beats duplication\" is correct everywhere except against a provided design artifact, where it is actively harmful: `existing-ui-audit` scores candidates by fuzzy similarity to the INPUT, which answers \"is this like what was asked for\" and never \"does this satisfy the artifact\" -- and a candidate can be an excellent name-and-props match while using the wrong type scale, the wrong control, or a colour the artifact never states. Reused on a port, an unconforming candidate is a fidelity deviation dressed as good hygiene, and nothing anywhere asked the second question before this change. +26 tokens, all of them the exception clause and its pointer. Condensed first, from +38: the \"decision comes after extraction, not before\" half went to the pointer target, because the ORDER is procedure and belongs in the skill. What remains cannot follow it. The unqualified claim lives HERE, in this rule, and a qualification filed in the skill leaves the rule still saying the unqualified thing to every reader who does not open the skill -- which is the same unreachable-arbitration defect this whole roadmap exists to close, reproduced one file over. Raised rather than condensed further because the two surviving clauses are the decision: drop \"except against a provided artifact\" and the exception disappears, drop \"conditional on the candidate conforming\" and it becomes an unactionable warning."
         }
     ]
 }

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -33,8 +33,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ORIGIN_CWD_FALLBACK, resolve_project_root } from '../_lib/agent_settings.js';
 import {
     RECYCLE_ENVELOPE_MAX_BYTES,
-    recycle_consumed_rel,
     recycle_envelope_rel,
+    resolvePredecessor,
 } from '../_lib/recycle_envelope_paths.js';
 import {
     CAPSULE_SCHEMA_VERSION,
@@ -84,30 +84,7 @@ export function templateEnvelope(): Record<string, unknown> {
     };
 }
 
-/**
- * Which session this one continues — read, never composed.
- *
- * The chain is derivable without any new artifact: when this session started,
- * its reader consumed the predecessor's record and MOVED it to this session's
- * consumed path (`recycle_consumed_rel`). So the file sitting there is, by
- * construction, the record this session resumed from, and its `session_id` is
- * the predecessor.
- *
- * Returns the explicit string `none` when there is nothing there. `none` is a
- * CLAIM — "this session starts a chain" — and is deliberately not an empty
- * value: a reader must be able to tell "no predecessor" from "nobody wrote the
- * field", because only the second one is a reason to go looking.
- */
-export function resolvePredecessor(projectRoot: string, sessionId: string | null): string {
-    try {
-        const consumed = path.join(projectRoot, recycle_consumed_rel(sessionId));
-        const raw = JSON.parse(fs.readFileSync(consumed, 'utf-8')) as { session_id?: unknown };
-        const prior = String(raw.session_id ?? '').trim();
-        return prior === '' ? 'none' : prior;
-    } catch {
-        return 'none';
-    }
-}
+export { resolvePredecessor };
 
 interface ParsedArgv {
     ok: boolean;

package/src/scripts/_cli/cmd_settings_get.ts

@@ -44,6 +44,7 @@ import {
     iter_setting_overrides,
     load_agent_settings,
     MERGEABLE_KEYS,
+    user_global_settings_paths,
     USER_GLOBAL_FILENAME,
 } from '../_lib/agent_settings.js';
 import { resolve_with_fallback, write_target } from '../_lib/user_global_paths.js';
@@ -150,15 +151,29 @@ export function carveOutFor(key: string): CarveOutKey | undefined {
  * without telling them which file it was dropped from is half an answer.
  */
 export function userGlobalDrop(key: string): { dropped: boolean; file: string } {
-    const file = resolve_with_fallback(USER_GLOBAL_FILENAME) ?? write_target(USER_GLOBAL_FILENAME);
+    // Probe EVERY user-global layer the loader reads, not just the flat file.
+    // `user_global_settings_paths()` returns the flat `agent-settings.yml` AND
+    // the canonical `settings/.agent-settings.yml` the setup wizard writes, and
+    // this function used to open only the first — so for a wizard user the drop
+    // warning could not fire at all and a filtered key read as a plain "not
+    // set". Highest-precedence layer last, same order as the loader, so the
+    // reported file is the one that actually carried the dropped value
+    // (road-to-design-intent-conformance 2.3).
+    const probed = user_global_settings_paths();
+    const fallbackFile =
+        resolve_with_fallback(USER_GLOBAL_FILENAME) ?? write_target(USER_GLOBAL_FILENAME);
+    const file = probed.length > 0 ? (probed[probed.length - 1] as string) : fallbackFile;
     if (MERGEABLE_KEYS.includes(key)) return { dropped: false, file };
-    let raw: unknown;
-    try {
-        raw = yamlLoad(fs.readFileSync(file, 'utf-8'));
-    } catch {
-        return { dropped: false, file };
+    for (const candidate of [...probed].reverse()) {
+        let raw: unknown;
+        try {
+            raw = yamlLoad(fs.readFileSync(candidate, 'utf-8'));
+        } catch {
+            continue;
+        }
+        if (getSettingsLeaf(raw, key) !== undefined) return { dropped: true, file: candidate };
     }
-    return { dropped: getSettingsLeaf(raw, key) !== undefined, file };
+    return { dropped: false, file };
 }
 
 /**

package/src/scripts/_cli/handoff_sessions.ts

@@ -32,7 +32,13 @@ import * as path from 'node:path';
 
 import { projectStoreSlug } from '../_lib/cc_transcript.js';
 import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
-import { eolSessionKey, readEolCounters, type StoredEolCounters } from '../_lib/session_eol.js';
+import {
+    eolSessionKey,
+    is_substantive,
+    readEolCounters,
+    type StoredEolCounters,
+    SUBSTANTIVE_TOKEN_FLOOR,
+} from '../_lib/session_eol.js';
 
 export const DEFAULT_CAP = 15;
 /**
@@ -42,24 +48,16 @@ export const DEFAULT_CAP = 15;
  * on the observed store 10 of 217 sessions are filtered (~5%), so 3× covers
  * that comfortably while keeping the per-file scan bounded.
  */
+/**
+ * Re-exported from `_lib/session_eol.ts`, where both now live so the Stop-path
+ * hook can reach them without importing this CLI module. Kept exported HERE
+ * because the resume picker is the surface every existing importer names.
+ */
+export { is_substantive, SUBSTANTIVE_TOKEN_FLOOR };
+
 const FETCH_OVERSHOOT = 3;
 const SUMMARY_SNIPPET_CHARS = 120;
 
-/**
- * Committed substantive-content floor, in parsed transcript tokens (billable
- * input of the last main-chain assistant record, per `cc_transcript.ts`) — the
- * OR-arm for a session that produced real discussion without ever calling a
- * tool.
- *
- * Derivation (`agents/evidence/analysis/handoff-substantive-threshold.md`,
- * 217 sessions of the local Claude store, 2026-08-10): 206 of the 207 sessions
- * carrying an assistant record also carry a `tool_use` block, so this arm
- * serves the ~0.5 % tail and the hosts whose transcripts log no tool blocks at
- * all. 10 000 sits **25× below** the p10 of real working sessions (254 939),
- * so it cannot hide one, and above a single trivial exchange. Changing it is a
- * PR citing evidence, never a drive-by edit.
- */
-export const SUBSTANTIVE_TOKEN_FLOOR = 10_000;
 
 export type HandoffSource = 'chat-history' | 'claude-transcript' | 'codex-session';
 
@@ -454,34 +452,6 @@ function _sort_key(s: HandoffSession): string {
     return s.endedAt ?? s.startedAt ?? '';
 }
 
-/**
- * Does this session hold anything worth resuming?
- *
- * `≥ 1 assistant turn AND (≥ 1 tool call OR parsed tokens ≥ the committed
- * floor)`, read from the counts-only session-eol state.
- *
- * **Fail-open, deliberately** (Phase 1.2): absent, unreadable or mis-shaped
- * state LISTS the candidate rather than filtering it, and a `tool_calls` key
- * missing from a state file written before that counter existed reads as
- * *unknown*, never as zero. A wrongly listed candidate is noise the user
- * scrolls past; a wrongly hidden one is data loss they cannot even see.
- */
-export function is_substantive(counters: StoredEolCounters | null): boolean {
-    if (counters === null) return true;
-    // Every "unknown" below is a NUMBER test, not an `=== undefined` test.
-    // Absent, null and NaN are all unknown, and each one reaches this code by
-    // a real path: a state file written before the counter existed is absent,
-    // `JSON.stringify` turns NaN into null on the way to disk, and a
-    // half-written file yields a parseable object with missing keys. Reading
-    // any of them as "counted zero" hides a session that did real work.
-    if (!Number.isFinite(counters.assistant_records)) return true;
-    if ((counters.assistant_records as number) < 1) return false;
-    if (!Number.isFinite(counters.tool_calls)) return true;
-    if ((counters.tool_calls as number) >= 1) return true;
-    if (!Number.isFinite(counters.final_context_tokens)) return true;
-    return (counters.final_context_tokens as number) >= SUBSTANTIVE_TOKEN_FLOOR;
-}
-
 function _derive_tag(id: string): string | null {
     try {
         return derive_session_tag(id);

package/src/scripts/_lib/agent_settings.ts

@@ -293,6 +293,17 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'knowledge.global_sharing.auto_promote_threshold',
     'knowledge.global_sharing.freshness.hypothesis_after_days',
     'knowledge.global_sharing.freshness.stale_after_days',
+    // `design.fidelity_mode` is a per-DEVELOPER working preference, not a
+    // per-project one: whether an agent may deviate from a handed-over design
+    // is a property of how that person works, and a designer who sets it once
+    // expects it in every checkout. `design-fidelity.md` already tells the
+    // reader to resolve it through the cascade — "that file is the project
+    // layer of a cascade that starts user-global" — and the cascade then
+    // filtered it out here, silently, so the rule's own instruction could not
+    // be followed. Class C, so a user still sets it by hand or through the
+    // GUI; whitelisting decides only whether the value SURVIVES the merge
+    // (ADR-271, road-to-design-intent-conformance 2.3).
+    'design.fidelity_mode',
 ];
 
 /** The shipped template, relative to the package root. */
@@ -823,6 +834,80 @@ function _resolve_cascade_paths(
     ];
 }
 
+/** Per-layer read outcome. `absent` and `malformed` are NOT the same fact. */
+export type SettingsLayerState = 'absent' | 'valid' | 'malformed';
+
+export interface SettingsLayerReport {
+    path: string;
+    state: SettingsLayerState;
+}
+
+/**
+ * Probe one settings file WITHOUT merging it, distinguishing absent from broken.
+ *
+ * `_read_yaml` returns `null` for both, which is fine for merging — an absent
+ * layer and an unreadable one contribute nothing either way — and is wrong for
+ * anything that has to decide differently in the two cases. That conflation
+ * silently disabled a documented safety property; see
+ * {@link settings_layer_states}.
+ */
+function _probe_yaml(p: string): SettingsLayerState {
+    if (!_is_file(p)) return 'absent';
+    let YAML: typeof YamlModule;
+    try {
+        YAML = _require('yaml') as typeof YamlModule;
+    } catch {
+        // No parser: this layer cannot be validated, so it is not `valid`.
+        return 'malformed';
+    }
+    try {
+        YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+        return 'valid';
+    } catch (err) {
+        if (_is_yaml_error(err) || _is_os_error(err)) return 'malformed';
+        throw err;
+    }
+}
+
+/**
+ * Per-layer validity for the layers a caller can actually break.
+ *
+ * A repair, not a feature. `load_agent_settings` merges a broken layer as if it
+ * were absent, so a key's resolved value says nothing about whether the user's
+ * own file parsed — measured 2026-09-10, a project `.agent-settings.yml` of
+ * `:\n  - [\n` returns the template's values and throws nothing. Every reader
+ * shaped `try { …read… } catch { } return <default>` therefore has an
+ * UNREACHABLE catch for that case, and its "fails closed" claim is carried by
+ * its default value rather than by its own code. Worked example and the ruling
+ * that required this: `_lib/continuity_writer.ts` § `auto_record_enabled`.
+ *
+ * Scope is the user-global files and the in-project cascade — the layers a
+ * human edits. The shipped template is excluded deliberately: a malformed
+ * template is a package defect that already resolves every key to absent, so
+ * reporting it would blame a tree in which the user did nothing wrong.
+ *
+ * Reports, never decides. What a `malformed` layer MEANS is the key's polarity,
+ * which belongs to the caller.
+ */
+export function settings_layer_states(
+    options: {
+        project_path?: string | null;
+        user_global_path?: string | null;
+        cwd?: string | null;
+    } = {},
+): SettingsLayerReport[] {
+    const project_path = options.project_path ?? null;
+    const cwd = options.cwd ?? null;
+    const user_global = options.user_global_path
+        ? [options.user_global_path]
+        : user_global_settings_paths();
+    const out: SettingsLayerReport[] = [];
+    for (const p of [...user_global, ..._resolve_cascade_paths(cwd, project_path)]) {
+        out.push({ path: p, state: _probe_yaml(p) });
+    }
+    return out;
+}
+
 /**
  * Return the merged settings dict.
  *

package/src/scripts/_lib/agent_src.ts

@@ -44,6 +44,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { iter_guidelines, resolve_guideline } from './guidelines_lane.js';
+
 // --- Path-root configuration (mutable to mirror Python module attributes) ----
 //
 // the retired Python implementation derives ROOT from `Path(__file__).resolve().parents[3]`
@@ -567,6 +569,18 @@ export function* iter_all_sources(): Generator<[string, string]> {
         seen.add(rel);
         yield [p, rel];
     }
+    // `docs/guidelines/` → logical `guidelines/…`. Appended here rather than
+    // added to `_root_specs` on purpose: `_root_specs` defines the artefact
+    // ESTATE, which the discovery manifest and every count/size ratchet walk,
+    // and a guideline is projected content rather than an estate artefact.
+    // Same shape and the same reason as the domains-commands lane above.
+    for (const [p, rel] of iter_guidelines(_roots.ROOT)) {
+        if (seen.has(rel)) {
+            continue;
+        }
+        seen.add(rel);
+        yield [p, rel];
+    }
 }
 
 /**
@@ -645,6 +659,13 @@ export function resolve_logical(logical_rel: string): string | null {
             }
         }
     }
+    // `guidelines/<subpath>.md` is backed by `docs/guidelines/<subpath>.md`.
+    // Paired with the `iter_all_sources` lane above so the projector's
+    // staleness check and its stale-file sweep both resolve a guideline.
+    const guideline = resolve_guideline(_roots.ROOT, rel);
+    if (guideline !== null) {
+        return guideline;
+    }
     return null;
 }