diff --git a/.devflow/features/bundler-plugins/KNOWLEDGE.md b/.devflow/features/bundler-plugins/KNOWLEDGE.md
new file mode 100644
index 0000000..fe655e1
--- /dev/null
+++ b/.devflow/features/bundler-plugins/KNOWLEDGE.md
@@ -0,0 +1,187 @@
+---
+feature: bundler-plugins
+name: Bundler Plugins (bundler-utils + Vite/Rollup/Webpack/Rspack)
+description: "Use when adding a new bundler integration, modifying the emitted-module contract, debugging HMR behavior, working on the CJS compatibility shim, updating the transformer/loader factory, registering a new package in the release pipeline, or investigating why a .mds file emits unexpected output. Keywords: createMdsTransformer, createMdsLoader, bundler-utils, vite-plugin, rollup-plugin, webpack-loader, rspack-loader, addWatchFile, addDependency, handleHotUpdate, emitted module contract, export default string, export default Message[], safeJsonForJs, escapeForJs, metadata, kind, markdown, messages, discriminated union, mds.d.ts, MdsMessage, string | MdsMessage[]."
+category: component-patterns
+directories: ["packages/bundler-utils/", "packages/vite-plugin/", "packages/rollup-plugin/", "packages/webpack-loader/", "packages/rspack-loader/"]
+referencedFiles:
+  - packages/bundler-utils/src/transform.ts
+  - packages/bundler-utils/src/types.ts
+  - packages/bundler-utils/src/loader.ts
+  - packages/bundler-utils/src/frontmatter.ts
+  - packages/bundler-utils/src/lazy-init.ts
+  - packages/bundler-utils/mds.d.ts
+  - packages/bundler-utils/src/index.ts
+  - packages/vite-plugin/src/index.ts
+  - packages/rollup-plugin/src/index.ts
+  - packages/webpack-loader/src/index.ts
+  - packages/rspack-loader/src/index.ts
+created: 2026-06-26
+updated: 2026-06-26
+---
+
+# Bundler Plugins (bundler-utils + Vite/Rollup/Webpack/Rspack)
+
+## Overview
+
+`packages/bundler-utils/` is the shared transformation layer consumed by four bundler plugins: `vite-plugin`, `rollup-plugin`, `webpack-loader`, `rspack-loader`. It implements `createMdsTransformer` (used by Vite/Rollup) and `createMdsLoader` (used by Webpack/Rspack). After the intrinsic-output refactor, the emitted JS module branches on the compiled `kind` — a markdown `.mds` emits a string default export, a messages `.mds` emits a `Message[]` default export. The published `mds.d.ts` ambient declaration reflects this widened type.
+
+## Core Responsibilities
+
+- `transform.ts`: compile `.mds` files via `MdsApi.compileFile`, emit the JS module source (`export default`), serialize metadata
+- `loader.ts`: webpack/rspack integration via `createMdsLoader`
+- `frontmatter.ts`: `shouldTransform(id)` — decides if a module ID refers to an `.mds` file
+- `lazy-init.ts`: `LazyInit<T>` — ensures `mds.init()` is awaited exactly once per transformer instance
+- Does NOT: implement compilation logic, manage caching, handle HMR (delegated to plugin wrappers)
+
+## Standard Structure
+
+### Emitted module contract (post-refactor)
+
+The emitted JS module branches on `result.kind`:
+
+```typescript
+// transform.ts — inside transform()
+let defaultExport: string;
+if (result.kind === 'markdown') {
+  // Escape the string for embedding in a double-quoted JS literal
+  defaultExport = `export default "${escapeForJs(result.output)}";\n`;
+} else {
+  // kind === 'messages' — serialize the messages array as safe inline JSON
+  defaultExport = `export default ${safeJsonForJs(result.messages)};\n`;
+}
+
+const code =
+  defaultExport +
+  `export const metadata = ${safeJsonForJs({ warnings: result.warnings, dependencies: result.dependencies })};\n`;
+```
+
+So for a markdown `.mds`: `export default "..."` (string)
+For a messages `.mds`: `export default [{role:"...", content:"..."}]` (array literal)
+
+Both emit `export const metadata = { warnings: [...], dependencies: [...] };`
+
+### safeJsonForJs vs escapeForJs
+
+These two serializers have different contracts and must not be swapped:
+
+- `escapeForJs(str: string): string` — escapes special chars for embedding inside a double-quoted JS string literal (`"..."`)
+- `safeJsonForJs(value: unknown): string` — `JSON.stringify` + escapes `<`, U+2028, U+2029 for safe inline `<script>` embedding; used for array/object literals in `export default`
+
+```typescript
+// escapeForJs handles: \, ", \n, \r, \0, U+2028, U+2029
+export default "${escapeForJs(result.output)}"  // for strings
+
+// safeJsonForJs handles: <, U+2028, U+2029 (JSON.stringify handles the rest)
+export default ${safeJsonForJs(result.messages)} // for objects/arrays
+```
+
+`safeJsonForJs` is exported from `transform.ts` so tests can verify escape behavior directly.
+
+### U+2028/U+2029 construction pattern
+
+Literal U+2028 (line separator) and U+2029 (paragraph separator) cannot appear in regex literals or object key literals — the JS parser treats them as line terminators. Always use:
+
+```typescript
+// Regex: use new RegExp() string
+const JS_ESCAPE_RE = new RegExp('[\\\\\"\\n\\r\\0\\u2028\\u2029]', 'g');
+
+// Map keys: computed property assignment after the literal
+JS_ESCAPE_MAP[String.fromCodePoint(0x2028)] = '\\u2028';
+JS_ESCAPE_MAP[String.fromCodePoint(0x2029)] = '\\u2029';
+```
+
+### Published type declaration (mds.d.ts)
+
+```typescript
+// packages/bundler-utils/mds.d.ts
+interface MdsMessage { role: string; content: string; }
+
+declare module '*.mds' {
+  // Widened to union: string for markdown, MdsMessage[] for messages
+  const content: string | MdsMessage[];
+  export default content;
+  export const metadata: { warnings: string[]; dependencies: string[] };
+}
+```
+
+TypeScript consumers must narrow on `Array.isArray(content)` or similar to distinguish the two variants. The declaration uses a local `MdsMessage` interface (not importing from `@mdscript/mds`) to avoid a dependency cycle.
+
+### MdsApi interface (bundler-utils/src/types.ts)
+
+```typescript
+export interface MdsApi {
+  compileFile(path: string, options?: { vars?: Record<string, unknown> }): Promise<CompileResult>;
+  init(): Promise<void>;
+}
+
+export type CompileResult = MarkdownResult | MessagesResult;
+
+export interface MarkdownResult {
+  kind: 'markdown'; output: string; warnings: string[]; dependencies: string[];
+}
+export interface MessagesResult {
+  kind: 'messages'; messages: Message[]; warnings: string[]; dependencies: string[];
+}
+```
+
+The `MdsApi` interface intentionally omits `InitOptions` (bundler plugins always call `init()` with no arguments).
+
+### createMdsTransformer
+
+```typescript
+// Returns: { shouldTransform(id): boolean, transform(id): Promise<TransformResult> }
+export function createMdsTransformer(mds: MdsApi, options?: MdsPluginOptions): { ... }
+```
+
+Stateful: `LazyInit<void>` ensures `mds.init()` is awaited once. The `id` passed to `transform(id)` is trusted (sourced from bundler module pipeline); query/hash stripping is the plugin's responsibility.
+
+## Dependency Patterns
+
+Bundler plugin factories (`vite-plugin`, etc.) import `createMdsTransformer` or `createMdsLoader` from `bundler-utils` and pass in the `@mdscript/mds` module import. The `MdsApi` structural type means the real package satisfies it without an `implements` declaration.
+
+Test mocks for `MdsApi.compileFile` must return the new discriminated-union shape:
+
+```javascript
+// Correct mock for transform tests
+compileFile: async (id) => ({ kind: 'markdown', output: '# Test', warnings: [], dependencies: [] })
+// or
+compileFile: async (id) => ({ kind: 'messages', messages: [{role:'user',content:'hi'}], warnings: [], dependencies: [] })
+```
+
+Old mocks returning `{ output: ..., warnings: [], deps: [] }` (flat shape) are wrong — update them.
+
+## Error Handling
+
+Compilation errors from `mds.compileFile()` propagate through `transform()` as thrown exceptions. The bundler plugin wrappers (Vite, Rollup, Webpack) catch them and format them into bundler-specific error reporting via `FormattedError`.
+
+## Anti-Patterns
+
+- **Using `escapeForJs` for objects/arrays** — only valid for string values inside `"..."`. Use `safeJsonForJs` for `export default [{...}]`.
+- **Using `safeJsonForJs` for string default exports** — it won't add JS string literal quotes; use `escapeForJs` and wrap in `"..."`.
+- **Using literal U+2028/U+2029 in regex or map keys** — JS parser treats them as line terminators; use `new RegExp()` and `String.fromCodePoint()`.
+- **Importing `Message` type from `@mdscript/mds` in `mds.d.ts`** — creates a dependency cycle; use the local `MdsMessage` interface.
+- **Emitting `export default null` or `export default undefined` for messages** — the inactive case must be omitted at the napi level; the transformer always has a real messages array.
+- **Calling `mds.init()` unconditionally on every transform** — `LazyInit` ensures it's called once; re-calling it is wasteful and may break WASM backends.
+
+## Gotchas
+
+- `metadata` is emitted as a named export on BOTH kinds. Consumers that only use `metadata.dependencies` for HMR registration don't need to branch on kind.
+- The `shouldTransform(id)` function (`frontmatter.ts`) checks the file extension; it does NOT read file content. A `.mds` file with type-mds frontmatter is handled by `shouldTransform` returning true for the extension alone.
+- Watch mode: `addWatchFile` / `addDependency` are called with `result.dependencies` from the transform result, regardless of kind. HMR works identically for markdown and messages mode.
+- `LazyInit` stores state per transformer instance. Each call to `createMdsTransformer` creates an independent lazy initializer — `D3 createMdsLoader factory independent state`.
+- Linux HMR e2e tests are gated behind `MDS_HMR=1` env var; they are timing-sensitive and may flake on re-run.
+
+## Key Files
+
+- `packages/bundler-utils/src/transform.ts` — `createMdsTransformer`, `safeJsonForJs`, `escapeForJs`, kind-branching emit logic
+- `packages/bundler-utils/src/types.ts` — `MdsApi`, `CompileResult`, `MarkdownResult`, `MessagesResult`, `Message`, `TransformResult`
+- `packages/bundler-utils/mds.d.ts` — ambient `*.mds` module declaration; `string | MdsMessage[]` default export type
+- `packages/bundler-utils/src/loader.ts` — `createMdsLoader` (Webpack/Rspack variant)
+- `packages/bundler-utils/src/index.ts` — re-exports `MarkdownResult`, `MessagesResult`, `Message` from types
+
+## Related
+
+- Feature: mds-js — the `@mdscript/mds` package that implements `MdsApi`; `CompileResult` union defined in `packages/mds/src/types.ts` mirrors the `MdsApi.compileFile` return type
+- Feature: mds-napi — the native backend that produces the discriminated-union result consumed via `MdsApi`
+- Feature: mds-compiler — `CompiledOutput::Messages(Vec<Message>)` is the Rust type that drives messages mode; its wire format shapes the JS `MessagesResult`
diff --git a/.devflow/features/mds-cli/KNOWLEDGE.md b/.devflow/features/mds-cli/KNOWLEDGE.md
new file mode 100644
index 0000000..3c26741
--- /dev/null
+++ b/.devflow/features/mds-cli/KNOWLEDGE.md
@@ -0,0 +1,222 @@
+---
+feature: mds-cli
+name: MDS CLI (mds-cli)
+description: "Use when adding new subcommands, changing output-path resolution logic, modifying the watch architecture, adding new compile paths, updating mds.json config handling, debugging stdout/stderr stream separation, investigating exit codes, adding directory-mode build/check support, or working on stale-output cleanup. Keywords: mds build, mds check, mds watch, mds init, OutputKind, run_build, run_watch, build.rs, output.rs, watch.rs, mds.json, output_dir, resolve_output_base, OutputBase, output_path_for, compile_and_write, compile_to_content, intrinsic extension, run_build_directory, run_check_directory, is_partial, collect_mds_files, probe_and_remove_stale, canonicalize_out_dir, output_base_no_ext, continue-on-error, subtree mirror, symlink guard, 10 MiB cap."
+category: component-patterns
+directories: ["crates/mds-cli/"]
+referencedFiles:
+  - crates/mds-cli/src/main.rs
+  - crates/mds-cli/src/build.rs
+  - crates/mds-cli/src/output.rs
+  - crates/mds-cli/src/watch.rs
+  - crates/mds-cli/tests/cli_build.rs
+  - crates/mds-cli/tests/dir_build.rs
+  - crates/mds-cli/tests/intrinsic_output.rs
+  - crates/mds-cli/Cargo.toml
+created: 2026-06-26
+updated: 2026-06-26
+---
+
+# MDS CLI (mds-cli)
+
+## Overview
+
+`crates/mds-cli/` implements the `mds` binary with four subcommands: `build`, `check`, `watch`, and `init`. The CLI delegates all compilation to `mds-core`; its job is input resolution, output routing, config loading, and process lifecycle. After the intrinsic-output refactor, **the output extension is derived from the compiled result's kind** — there is no `--format` flag. Markdown templates produce `.md` files; messages templates produce `.json` files.
+
+The CLI now supports both single-file and directory modes for `build` and `check`. Directory mode (`mds build <dir>` / `mds check <dir>`) recursively compiles all non-partial `.mds` files under the given root, mirrors the subtree into an optional `--out-dir`, and continues on error with a final summary.
+
+## Core Responsibilities
+
+- Subcommand dispatch: `main.rs` parses args (clap) and calls `run_build`, `run_check`, `run_watch`
+- `build.rs`: single-file and directory build logic, output-path resolution, shared helpers (`compile_to_content`, `compile_and_write`)
+- `output.rs`: directory-mode shared machinery (`OutputBase`, `output_path_for`, `collect_mds_files`, `is_partial`, `probe_and_remove_stale`, `canonicalize_out_dir`)
+- `watch.rs`: file/directory watch loop; derives extension from `kind.extension()` after compile
+- Does NOT: implement compiler logic, manage modules, or handle imports
+
+## Standard Structure
+
+### OutputKind — intrinsic extension derivation
+
+```rust
+// In build.rs
+pub(crate) enum OutputKind { Markdown, Messages }
+
+impl OutputKind {
+    pub(crate) fn extension(self) -> &'static str { "md" | "json" }
+}
+
+impl From<&CompiledOutput> for OutputKind { ... }
+```
+
+All callers derive the extension via `OutputKind::from(&compiled.output).extension()` — never hardcode `"md"` for a possibly-messages template.
+
+### compile_to_content — pure compile without write
+
+```rust
+pub(crate) fn compile_to_content(
+    input: &Path,
+    runtime_vars: Option<HashMap<String, mds::Value>>,
+    quiet: bool,
+) -> Result<CompileOutput>
+```
+
+Returns `CompileOutput { content: String, kind: OutputKind, dependencies: Vec<String> }`. The `content` is already serialized: markdown as-is, messages as pretty-printed JSON array with trailing newline. Used by the watch loop for content-based dedup and by `run_build_directory`.
+
+### compile_and_write — single-file compile+route+write
+
+```rust
+pub(crate) fn compile_and_write(
+    input: &Path, output: &Option<String>, out_dir: &Option<PathBuf>,
+    config: &Option<(MdsConfig, PathBuf)>,
+    runtime_vars: Option<HashMap<String, mds::Value>>, quiet: bool,
+) -> Result<(Option<PathBuf>, Vec<String>)>
+```
+
+This is "compile-then-route": compiles first, derives the output path from `kind`, then writes. The output path is unknown until after compilation for the intrinsic extension case.
+
+### Output path precedence (single-file mode)
+
+1. `-o -` → stdout
+2. `-o <path>` → verbatim path (warns on extension mismatch if `kind` disagrees — AC-FUNC-11)
+3. Stdin with no `-o`/`--out-dir` → stdout
+4. `--out-dir <dir>` → `<dir>/<stem>.<ext>` where `<ext>` is from `kind`
+5. `mds.json build.output_dir` → `<config_dir>/<output_dir>/<stem>.<ext>`
+6. Default → source directory + `<stem>.<ext>`
+
+`-o` rejected in directory mode. Use `--out-dir` for directories.
+
+### output.rs — directory-mode shared machinery
+
+```rust
+// OutputBase describes where directory-mode output files land
+pub(crate) enum OutputBase {
+    Dir(PathBuf),     // subtree mirror under this dir
+    NextToSource,     // next to source file
+}
+
+// Compute output base (precedence: --out-dir > mds.json > next-to-source)
+pub(crate) fn resolve_output_base(abs_out_dir, config) -> Result<OutputBase>
+
+// Canonicalize --out-dir before resolve_output_base
+pub(crate) fn canonicalize_out_dir(out_dir: Option<&PathBuf>) -> Option<PathBuf>
+
+// 4-arg canonical output path computation (always pass kind.extension() as ext)
+pub(crate) fn output_path_for(source: &Path, root: &Path, base: &OutputBase, ext: &str) -> PathBuf
+
+// Recursively collect .mds files (skips symlinks and exclude_prefix subtree)
+pub(crate) fn collect_mds_files(root, max_depth, exclude_prefix) -> Vec<PathBuf>
+
+// True if filename starts with '_' (partial convention — skipped in build)
+pub(crate) fn is_partial(path: &Path) -> bool
+
+// Remove the wrong-extension sibling after a write (fire-and-forget)
+pub(crate) fn probe_and_remove_stale(base_no_ext: &Path, kind: OutputKind)
+
+// Build the extension-free path for probe_and_remove_stale
+pub(crate) fn output_base_no_ext(source, root, base) -> PathBuf
+```
+
+### Directory mode patterns
+
+**Continue-on-error** — all non-partial files are attempted; compile errors are printed to stderr; counters track `ok_count`/`fail_count`; non-zero exit when `fail_count > 0`:
+
+```rust
+for file in &files {
+    if is_partial(file) { continue; }
+    match compile_to_content(file, runtime_vars.clone(), quiet) {
+        Ok(compiled) => { /* write + stale cleanup */ ok_count += 1; }
+        Err(e) => { eprintln!("{e:?}"); fail_count += 1; }
+    }
+}
+eprintln!("{ok_count} built, {fail_count} failed");
+if fail_count > 0 { std::process::exit(1); }
+```
+
+**Stale cleanup** — after each successful write, probe and remove the wrong-extension sibling:
+
+```rust
+let base_no_ext = output_base_no_ext(file, dir, &output_base);
+probe_and_remove_stale(&base_no_ext, compiled.kind);
+```
+
+**Deletion in watch mode** — when a source `.mds` is deleted, kind is unknown; probe BOTH extensions:
+
+```rust
+let base = output_base_no_ext(&src, root, &output_base);
+for ext in ["md", "json"] {
+    let p = base.with_extension(ext);
+    if p.exists() { let _ = fs::remove_file(&p); }
+}
+```
+
+**Symlink guard** — directory root must not be a symlink (checked BEFORE `collect_mds_files`):
+
+```rust
+if input.symlink_metadata().map(|m| m.file_type().is_symlink()).unwrap_or(false) {
+    return Err(miette::miette!("directory argument must not be a symlink: {}", input.display()));
+}
+```
+
+`collect_mds_files` additionally skips symlinked files AND symlinked directories inside the tree (build parity with single-file mode).
+
+**Exclude output dir from collection** — when `out_dir` is nested inside the source root, pass it as `exclude_prefix` to `collect_mds_files`:
+
+```rust
+let exclude_prefix = match &output_base {
+    OutputBase::Dir(d) if d.starts_with(dir) => Some(d.clone()),
+    _ => None,
+};
+```
+
+**AC-M7 path-escape guard** — `output_path_for` has a runtime containment check: if the computed output path somehow escapes `Dir(base)` (e.g. via a malformed strip_prefix result), it falls back to `base/<stem>.<ext>`. A `debug_assert!(false, ...)` fires in debug builds so tests catch regressions.
+
+### Resource limits
+
+- `MAX_FILE_SIZE` (10 MiB): enforced by `mds-core` for file inputs; enforced in `read_stdin()` for stdin
+- `MAX_TRAVERSAL_DEPTH`: `mds.json` upward walk cap (from `mds-core`)
+- `MAX_DEPTH = 64`: hardcoded local cap in `run_build_directory` for directory recursion
+
+## Dependency Patterns
+
+The CLI uses `mds::compile_with_deps` and `mds::compile_str_with_deps` (never bare `std::fs::read_to_string`). All file reads go through `mds-core`'s resolver, which enforces `MAX_FILE_SIZE` and the symlink guard.
+
+## Error Handling
+
+Exit codes:
+- 0: success
+- 1: compile/logic error, or `fail_count > 0` in directory mode (`std::process::exit(1)`)
+- 2: I/O or filesystem error (`MdsError::Io`, `FileNotFound`, `NotMdsFile`)
+- 3: resource limit exceeded (`MdsError::ResourceLimit`)
+
+`run_build_directory` calls `std::process::exit(1)` directly (not via the `Result` chain) when fail_count > 0, matching other CLI exit points in `build.rs`.
+
+## Anti-Patterns
+
+- **Using `--format` flag** — deleted; does not exist in the CLI anymore. Using it as a clap argument will produce "unknown argument". Tests in `intrinsic_output.rs` assert this.
+- **Calling `run_build_messages` or `run_build_markdown`** — deleted; only `run_build` exists, which dispatches to `run_build_directory` for dir inputs.
+- **Calling `read_build_input` or `reject_directory_input`** — deleted.
+- **Using 3-arg `output_path_for`** — the canonical signature is 4-arg with `ext: &str`. Never revert to a hardcoded extension.
+- **Using `-o` with a directory input** — rejected with an error; use `--out-dir`.
+
+## Gotchas
+
+- `probe_and_remove_stale` is fire-and-forget (soft-warn on failure, never propagates). A stale sibling is an annoyance, not a correctness bug — so failures are non-fatal.
+- `canonicalize_out_dir` resolves relative paths against `current_dir` and then canonicalizes. It must be called BEFORE `resolve_output_base` so that `starts_with` checks inside `run_build_directory` are reliable across relative/absolute paths.
+- Watch mode derives the extension from `compiled.kind.extension()` after each compile. On deletion it must probe both `.md` and `.json` since the kind is not known.
+- The `CompileOutput` struct in `build.rs` is a local CLI struct (content + kind + deps) — not the same as `mds::CompiledOutput` (the Rust enum). The naming is similar but they are different types.
+- `mds.json build.output_dir` rejects `..` components at parse time to prevent path traversal. This check runs in both single-file and directory mode.
+
+## Key Files
+
+- `crates/mds-cli/src/main.rs` — clap argument parsing; `run_build`/`run_check`/`run_watch` dispatch; `mod output`
+- `crates/mds-cli/src/build.rs` — `OutputKind`, `compile_to_content`, `compile_and_write`, `run_build`, `run_build_directory`, all output-path helpers for single-file mode
+- `crates/mds-cli/src/output.rs` — `OutputBase`, `resolve_output_base`, `output_path_for`, `collect_mds_files`, `is_partial`, `probe_and_remove_stale`, `canonicalize_out_dir`, `output_base_no_ext`
+- `crates/mds-cli/src/watch.rs` — watch loop; uses `compiled.kind.extension()` and `probe_and_remove_stale`
+- `crates/mds-cli/tests/dir_build.rs` — 14 integration tests for directory mode (T-CLI-12–21 / FUNC-16–26)
+- `crates/mds-cli/tests/intrinsic_output.rs` — tests asserting `--format` is rejected
+
+## Related
+
+- Feature: mds-compiler — provides `mds::CompileResult`, `mds::CompiledOutput`, `mds::compile_with_deps`
+- Feature: mds-napi — parallel consumer of `CompileResult`; uses the same `kind` discriminant
+- Feature: bundler-plugins — parallel consumer of the kind-based branch for bundler emitted modules
diff --git a/.devflow/features/mds-compiler/KNOWLEDGE.md b/.devflow/features/mds-compiler/KNOWLEDGE.md
new file mode 100644
index 0000000..9536ab5
--- /dev/null
+++ b/.devflow/features/mds-compiler/KNOWLEDGE.md
@@ -0,0 +1,222 @@
+---
+feature: mds-compiler
+name: MDS Compiler Core (mds-core)
+description: "Use when working on the MDS compilation pipeline, adding directives, modifying scope/variable handling, extending the module system, debugging output rendering, working with @message blocks, the intrinsic output format, CompiledOutput, CompileResult, or mixed-content errors. Keywords: lexer, parser, evaluator, resolver, validator, scope, frontmatter, interpolation, directive, import, include, define, for, if, message, @message, CompiledOutput, CompileResult, into_markdown, into_messages, intrinsic, mixed_content, MixedContent, has_message_block, process_module_intrinsic, collect_messages_strict, evaluate_messages_intrinsic, TextNode.offset."
+category: domain-knowledge
+directories: ["crates/mds-core/"]
+referencedFiles:
+  - crates/mds-core/src/lib.rs
+  - crates/mds-core/src/evaluator.rs
+  - crates/mds-core/src/resolver.rs
+  - crates/mds-core/src/error.rs
+  - crates/mds-core/src/ast.rs
+  - crates/mds-core/src/resolver/inheritance.rs
+  - crates/mds-core/src/resolver/frontmatter.rs
+  - crates/mds-core/src/limits.rs
+  - crates/mds-core/src/scope.rs
+  - crates/mds-core/src/value.rs
+created: 2026-06-26
+updated: 2026-06-26
+---
+
+# MDS Compiler Core (mds-core)
+
+## Overview
+
+`mds-core` is the Rust library crate at `crates/mds-core/`. Every other layer (CLI, NAPI bindings, WASM bindings) calls into it. It compiles `.mds` template files to either Markdown or structured chat-message arrays — the distinction is **intrinsic** to the template: the presence of any `@message` block causes the compiler to produce `CompiledOutput::Messages`; templates without `@message` blocks always produce `CompiledOutput::Markdown`. Callers do not specify a format at call time.
+
+The pipeline is: lexer → parser → validator → resolver (imports, inheritance, frontmatter) → evaluator → output wrapping. All error codes carry the `mds::` prefix (e.g. `mds::mixed_content`, `mds::syntax`, `mds::undefined_variable`).
+
+## Business Context
+
+The intrinsic output model replaced a previous `--format messages` flag and a separate `compile_messages_*` API family. Those symbols are deleted. The key invariant: a template is either a "markdown template" or a "messages template" — it cannot be both. Top-level text content intermixed with `@message` blocks is a hard error (`mds::mixed_content`), not a warning.
+
+## Core Business Rules
+
+### Intrinsic Output Rule
+
+The compiled output kind is determined by `process_module_intrinsic` in `resolver.rs`. It calls `has_message_block` on the resolved AST; if any `@message` node exists at the entry module level the output is Messages, otherwise Markdown.
+
+- `CompiledOutput::Markdown(String)` — no `@message` blocks in template
+- `CompiledOutput::Messages(Vec<Message>)` — at least one `@message` block
+
+Mixed content (top-level text/interpolation AND `@message` blocks in the same module) is rejected with `MdsError::MixedContent`.
+
+### CompileResult — the only public output type
+
+Every `compile*` entry point returns `Result<CompileResult, MdsError>`:
+
+```rust
+pub struct CompileResult {
+    pub output: CompiledOutput,   // Markdown(String) or Messages(Vec<Message>)
+    pub warnings: Vec<String>,
+    pub dependencies: Vec<String>, // depth-first, excludes entry module itself
+}
+
+impl CompileResult {
+    pub fn into_markdown(self) -> Result<String, MdsError>  // Err: ExpectedMarkdown
+    pub fn into_messages(self) -> Result<Vec<Message>, MdsError> // Err: ExpectedMessages
+}
+```
+
+`dependencies` is in first-resolution (depth-first) order and excludes the entry module itself.
+
+### Public Entry Points (all return `Result<CompileResult, MdsError>`)
+
+```rust
+mds::compile(path, runtime_vars)
+mds::compile_str(source)
+mds::compile_str_with(source, base_dir, runtime_vars)
+mds::compile_file(path)            // path as &str
+mds::compile_collecting_warnings(path, runtime_vars)
+mds::compile_str_collecting_warnings(source, base_dir, runtime_vars)
+mds::compile_virtual(modules, entry, runtime_vars)
+mds::compile_virtual_collecting_warnings(modules, entry, runtime_vars)
+mds::compile_with_deps(path, runtime_vars)
+mds::compile_str_with_deps(source, base_dir, runtime_vars)
+mds::compile_virtual_with_deps(modules, entry, runtime_vars)
+```
+
+Check functions — signature unchanged externally, now route through intrinsic dispatch internally (rejects mixed content):
+
+```rust
+mds::check(path, runtime_vars) -> Result<(), MdsError>
+mds::check_str(source) -> Result<(), MdsError>
+mds::check_str_with(source, base_dir, runtime_vars)
+mds::check_collecting_warnings(path, runtime_vars) -> Result<((), Vec<String>), MdsError>
+mds::check_str_collecting_warnings(source, base_dir, runtime_vars)
+mds::check_virtual(modules, entry, runtime_vars)
+mds::check_virtual_collecting_warnings(modules, entry, runtime_vars)
+```
+
+### Consuming CompileResult
+
+Two patterns for obtaining the payload:
+
+```rust
+// Pattern 1: match on output (non-consuming if you need warnings/deps too)
+match result.output {
+    CompiledOutput::Markdown(s) => { /* use s */ }
+    CompiledOutput::Messages(msgs) => { /* use msgs: Vec<Message> */ }
+}
+
+// Pattern 2: typed helpers (consume result — warnings/deps are discarded)
+let s: String = result.into_markdown()?;       // Err if Messages
+let msgs: Vec<Message> = result.into_messages()?; // Err if Markdown
+```
+
+### MdsError Variants Added by Intrinsic Refactor
+
+```rust
+// code: mds::mixed_content
+// help: "move all text and interpolations inside @message blocks…"
+MixedContent { span: Option<SourceSpan>, src: Option<Arc<NamedSource<String>>> }
+
+// code: mds::expected_markdown   (into_markdown called on Messages result)
+ExpectedMarkdown
+
+// code: mds::expected_messages   (into_messages called on Markdown result)
+ExpectedMessages
+```
+
+Constructors (private to the crate):
+- `MdsError::mixed_content()` — span-less version (used by evaluator in most cases)
+- `MdsError::mixed_content_at(file, source, offset, len)` — span version (defined; not yet used by code paths in this PR)
+
+### AST Change: TextNode.offset
+
+```rust
+pub struct TextNode { pub text: String, pub offset: usize }
+```
+
+The `offset` field is a byte offset from the start of the source. It exists for future diagnostic spans on mixed-content errors. All TextNode constructions use `offset: 0` unless the construction site has a real offset from lexer/parser output.
+
+### Internal Intrinsic Dispatch (resolver.rs)
+
+`process_module_intrinsic` is the internal resolver method called by all `compile*` functions. It:
+1. Calls `has_message_block` on the module AST
+2. Dispatches to `evaluate_messages_intrinsic` (messages path) or the existing markdown evaluator (markdown path)
+3. `evaluate_messages_intrinsic` — strict; errors on orphan top-level Text/Interpolation; `EscapedBrace` is inert; `@include` in message context emits a warning
+
+### Deleted Public Symbols
+
+These are removed and must not be referenced anywhere:
+- `CompileMessagesOutput` struct
+- `CompileOutput` struct
+- `compile_messages_str`, `compile_messages_str_with_deps`, `compile_messages_virtual`, `compile_messages_virtual_with_deps`, `compile_messages_file`, `compile_messages_file_with_deps`
+- `ModuleCache::resolve_path_messages`, `resolve_key_messages`, `resolve_source_messages`
+
+`evaluate_messages` (evaluator.rs) — was public; is now private/unused dead code from the deleted messages path.
+
+### Internal ModuleCache Methods Added
+
+```rust
+pub fn resolve_path_intrinsic(&mut self, path, vars, warnings) -> Result<CompiledOutput, MdsError>
+pub fn resolve_source_intrinsic(&mut self, source, base_dir, vars, warnings) -> Result<CompiledOutput, MdsError>
+pub fn resolve_key_intrinsic(&mut self, key, vars, warnings) -> Result<CompiledOutput, MdsError>
+```
+
+These are what the `compile_*` lib.rs functions call internally.
+
+## State Transitions
+
+Template compilation follows: parse → resolve imports → evaluate → intrinsic-dispatch output wrapping. The intrinsic dispatch is a one-way gate: once `has_message_block` returns true the evaluator is `evaluate_messages_intrinsic` and any orphan text triggers `MixedContent`.
+
+## Technical Implementation Patterns
+
+### Test-only shims (not public API)
+
+```rust
+#[cfg(test)]
+pub(crate) fn compile_str_md(source) -> Result<String, MdsError>
+pub(crate) fn compile_str_with_md(source, base_dir, vars) -> Result<String, MdsError>
+pub(crate) fn compile_virtual_md(modules, entry, vars) -> Result<String, MdsError>
+```
+
+These `pub(crate)` helpers exist so the large body of pre-intrinsic markdown unit tests can keep asserting on `String` without being rewritten. They compose the public `compile_*` functions with `.into_markdown()`.
+
+### serde serialization of CompiledOutput
+
+`CompiledOutput` uses adjacently-tagged serialization:
+
+```rust
+#[serde(tag = "kind", content = "value", rename_all = "lowercase")]
+pub enum CompiledOutput { Markdown(String), Messages(Vec<Message>) }
+```
+
+JSON shape: `{"kind":"markdown","value":"..."}` or `{"kind":"messages","value":[...]}`. The NAPI layer does NOT use this derive — it builds the wire object field-by-field to control the payload key name (`output` vs `messages`, not `value`).
+
+## Error Handling and Recovery
+
+Mixed-content errors surface as `mds::mixed_content` from both `compile*` and `check*` paths. There is no lenient mode; the error is always fatal. The error carries a `help` string directing users to move text into `@message` blocks.
+
+`ExpectedMarkdown` / `ExpectedMessages` are only produced by `into_markdown()` / `into_messages()` on a result whose kind doesn't match. These do not carry span or help text.
+
+## Anti-Patterns
+
+- **Calling `compile_messages_*` functions** — deleted; use `compile*` and match on `.output`
+- **Checking `OutputFormat` enum** — deleted; the format is intrinsic
+- **Constructing TextNode without `offset`** — must include `offset: 0` (or real offset); omitting causes a compile error since the struct field is public
+- **Using `evaluate_messages` directly** — private; use `process_module_intrinsic` via the resolver
+- **Calling `resolve_path_messages`** — deleted; use `resolve_path_intrinsic`
+
+## Gotchas
+
+- `check_*` functions now run full intrinsic dispatch including `has_message_block`. They will return `MixedContent` errors on templates that would have passed the old check (which used the markdown path only). This is a breaking behavior change.
+- `dependencies` in `CompileResult` excludes the entry module. Downstream callers must not add the entry path manually.
+- The `collect_messages_strict` internal name appears in some internal call chains; externally the only symbol exposed is `evaluate_messages_intrinsic`.
+- The adjacently-tagged serde shape (`kind`/`value`) is for Rust-to-Rust serialization only. The NAPI wire format uses `output`/`messages` (not `value`) as the payload key — built explicitly in `build_canonical_result`.
+
+## Key Files
+
+- `crates/mds-core/src/lib.rs` — all public entry points; `CompileResult`, `CompiledOutput`, `Message` types
+- `crates/mds-core/src/error.rs` — `MdsError` variants including `MixedContent`, `ExpectedMarkdown`, `ExpectedMessages`
+- `crates/mds-core/src/resolver.rs` — `process_module_intrinsic`, `has_message_block`, `resolve_*_intrinsic`
+- `crates/mds-core/src/evaluator.rs` — `evaluate_messages_intrinsic`, `EvalMessage`
+- `crates/mds-core/src/ast.rs` — `TextNode` with `offset: usize` field
+
+## Related
+
+- Feature: mds-cli — consumes `CompileResult` and `CompiledOutput`; derives output extension from `OutputKind::from(&compiled.output)`
+- Feature: mds-napi — builds the canonical discriminated-union wire object from `CompileResult` via `build_canonical_result`
+- Feature: mds-js — TypeScript `CompileResult = MarkdownResult | MessagesResult` union mirrors this Rust type
diff --git a/.devflow/features/mds-fmt/KNOWLEDGE.md b/.devflow/features/mds-fmt/KNOWLEDGE.md
new file mode 100644
index 0000000..7f747de
--- /dev/null
+++ b/.devflow/features/mds-fmt/KNOWLEDGE.md
@@ -0,0 +1,251 @@
+---
+feature: mds-fmt
+name: mds fmt — Opinionated Safety-Gated Formatter
+description: "Use when modifying the mds fmt formatter engine (crates/mds-core/src/formatter.rs), the mds fmt CLI subcommand (crates/mds-cli/src/fmt.rs), any change to mds-core's output model (clean_output, evaluate_nodes, @message/@define body evaluation, the lexer's fence recognition) that could silently break the formatter's compile-equivalence guarantee, or changes to the shared directory walker (output.rs). Keywords: mds fmt, format_str, format_str_with, format_str_named, FormatterInvariant, clean_output, compile-equivalence, idempotent, assert_equivalent, structural_equivalent, strip_trailing_insignificant_text, in_raw_content, raw_content_spans, protected_spans, R1 R2 R3 R4, safety gate, token lossiness, @message body, @define body, @block body, FmtConfig, FmtFlags, interior-verbatim contract, try_scan_fence_at, FenceMatch, deep_merge_yaml, RESERVED_MERGE_KEYS, is_default_excluded_dir, is_within_default_excluded_dir, walker exclusions, node_modules, hidden dirs, effective_parent, bare filename, atomic_write_file."
+category: domain-knowledge
+directories: ["crates/mds-core/src", "crates/mds-cli/src"]
+referencedFiles:
+  - crates/mds-core/src/formatter.rs
+  - crates/mds-core/src/lib.rs
+  - crates/mds-core/src/evaluator.rs
+  - crates/mds-core/src/lexer.rs
+  - crates/mds-core/src/parser.rs
+  - crates/mds-core/src/error.rs
+  - crates/mds-core/src/resolver.rs
+  - crates/mds-core/src/resolver/frontmatter.rs
+  - crates/mds-core/src/fs.rs
+  - crates/mds-cli/src/fmt.rs
+  - crates/mds-cli/src/main.rs
+  - crates/mds-cli/src/output.rs
+  - crates/mds-cli/src/build.rs
+  - crates/mds-cli/src/watch.rs
+created: 2026-07-03
+updated: 2026-07-19
+---
+
+# mds fmt — Opinionated Safety-Gated Formatter
+
+## Overview
+
+`mds fmt` (PR #137 / issue #60) rewrites `.mds` **source text** in place: `crates/mds-core/src/formatter.rs` (`format_str`/`format_str_named`, ~865 lines) is the engine, `crates/mds-cli/src/fmt.rs` is the CLI subcommand. It is CLI-only — as of this writing, no napi/wasm/python binding exposes `format_str_named` or `MdsError::FormatterInvariant` (verified: no match in `crates/mds-napi/src`, `crates/mds-wasm/src`, `crates/mds-python/src`). The public API surface is `format_str`, `format_str_with`, and `format_str_named` — all exported at `lib.rs:60` and pinned in `crates/mds-core/tests/api_surface.rs`.
+
+What makes this feature different from a typical formatter: its correctness bar isn't an independent style guide, it's **whatever `mds-core`'s own compiled-output normalizer (`clean_output`) already does**. Every rule the formatter applies must be provable-safe against that normalizer's *exact* behavior — not its doc comment, its actual character-by-character logic — because a wrong rule doesn't just look ugly, it silently changes what an LLM receives at render time. All of the facts below were obtained by reading `clean_output` and `evaluator.rs` line-by-line and writing tests that pipe strings through the real compiler (`tests/fmt.rs` comments repeatedly say "verified empirically against the live compiler, not just inferred from its doc comment" — take that literally when touching this code: re-verify, don't assume the prose is still accurate).
+
+This KB is domain-specific to the formatter's safety model. For the compiler pipeline it depends on (lexer/parser/resolver/evaluator, `CompileResult`, intrinsic output dispatch), see [[mds-compiler]]. For general CLI conventions (exit codes, `resolve_input`, `MAX_FILE_SIZE`, directory-mode machinery) it reuses, see [[mds-cli]]. **Neither of those KBs currently documents `clean_output`'s exact semantics or the `@message`/`@define` raw-body bypass — this file is the authoritative source for both**, even though they live in `mds-core`, not in the formatter.
+
+## Business Context
+
+MDS is a *content* language: whitespace in the compiled output is the product (Markdown hard breaks, message JSON payloads), not incidental formatting. That inverts the usual formatter assumption. The one non-negotiable business rule (stated in `formatter.rs`'s module doc, lines 1-13):
+
+> Any tool that rewrites `.mds` source must produce byte-identical compile output (`compile(fmt(src)).output == compile(src).output`) and must be idempotent (`fmt(fmt(src)) == fmt(src)`).
+
+This is enforced at **runtime**, per call, not just by test coverage — see "State Transitions" below. A future agent adding a new formatting rule who only adds unit tests (and skips understanding *why* the gate exists) is missing the point: the gate is what lets this ship at all despite the token stream being unable to prove correctness statically (see "Technical Implementation Patterns" below).
+
+## Core Business Rules
+
+### Rule 1 — `clean_output` is the ceiling on what the formatter may ever change
+
+`clean_output` (`crates/mds-core/src/lib.rs:665-681`) is the compiler's own output normalizer, run on every markdown-mode body. Its exact logic, read directly from source (v0.4, post-interior-verbatim contract, PRs #150/#151):
+
+```rust
+pub(crate) fn clean_output(s: &str) -> String {
+    // Strip \r unconditionally (Windows line endings).
+    let no_cr: std::borrow::Cow<str> = if s.as_bytes().contains(&b'\r') {
+        std::borrow::Cow::Owned(s.chars().filter(|&c| c != '\r').collect())
+    } else {
+        std::borrow::Cow::Borrowed(s)
+    };
+
+    // Trailing-edge normalisation: trim all trailing whitespace, then add one \n.
+    let trimmed = no_cr.trim_end();
+    if trimmed.is_empty() {
+        return String::new();
+    }
+    let mut out = trimmed.to_string();
+    out.push('\n');
+    out
+}
+```
+
+**IMPORTANT CHANGE from v1**: The old `clean_output` (pre-#150/#151) had a `newline_count` loop that (a) stripped leading blank lines via `trim_start_matches` and (b) capped blank-line runs at `min(N, 2)`. Both behaviors are now **gone**. The current `clean_output` does exactly two things: (1) strip `\r` unconditionally and (2) a single `trim_end()` + forced final `\n`. It does NOT collapse interior blank lines, does NOT strip leading blank lines, and does NOT impose any structure on the body beyond "ends with exactly one newline." This is the interior-verbatim contract: the compiler passes block body content through verbatim (after CRLF normalization and final newline normalization), and the formatter must match that ceiling exactly.
+
+**Whitespace contract at a glance (v0.4.0)** — three body-content paths, one deleted rule:
+
+| Path | Compile-time treatment | Formatter treatment |
+|---|---|---|
+| Ordinary markdown-mode body **and** `@if`/`@for`/`@block` bodies | `clean_output` — trim-only / **interior-verbatim** (`\r` strip + trailing `trim_end` + one final `\n`) | R1 (`\r` strip) + R2 (final `\n`); interior blank runs copied verbatim |
+| `@message` / `@define` bodies | **bypass `clean_output`** — edge-trimmed via `.trim()` only (spec §4.11) | raw-content spans — copied byte-for-byte (no R1, no R2), `\r` and interior blank runs both survive |
+| ~~R3 blank-run collapse~~ | — | **DELETED** in v0.4.0 (#150/#151); no path caps blank-line runs anymore |
+
+**Takeaways**: (1) the formatter must NOT add or remove blank lines anywhere in body content — interior blank lines are now the template author's exclusive domain; (2) the formatter must NOT strip trailing whitespace from a body-content line, including a whitespace-only one — two trailing spaces are a Markdown hard break; (3) `\r` is unconditionally deleted here, so removing it from the raw source up front is always safe, anywhere; (4) the old R3 rule (blank-run capping) has been **removed from the formatter** because `clean_output` no longer caps blank-line runs — applying it would change compiled output.
+
+### Rule 2 — the THIRD protected region: `@message`/`@define` bodies bypass `clean_output` entirely
+
+Frontmatter and code-fence content are the two "obviously protected" regions (they're reattached/copied verbatim around the parts of the pipeline that call `clean_output`). The formatter needed a third, non-obvious one, discovered by reading the evaluator rather than inferring it: `@message` body content is produced by (`crates/mds-core/src/evaluator.rs:845`, inside `collect_single_message`):
+
+```rust
+let content = evaluate_nodes(&block.body, scope, ctx)?.trim().to_string();
+```
+
+That's a plain `.trim()` — edge-trim once, per spec §4.11 — with **no `clean_output` call anywhere in this path**. Confirmed empirically (and locked in by `mds-core/tests/fmt.rs::message_body_carriage_return_is_preserved_not_stripped` and `::ec_blank_lines_inside_define_message_block_bodies_preserved`): `@message user:\r\nHi\r\nthere\r\n@end\r\n` compiles to message content `"Hi\r\nthere"` (the `\r` survives into the JSON), and 4 raw newlines inside a message body survive as 4. `@define` bodies get the identical conservative treatment — not because their evaluation bypasses `clean_output` (a function's own body content is subject to whatever call site renders it), but because a `@define`d function can be invoked from a markdown-mode site (where `clean_output` applies downstream) **or** from inside a `@message` body (where it does not), and the formatter has no call-graph analysis to tell which. So both `@message` and `@define` bodies are treated as **raw content**: copied byte-for-byte, no R1 (`\r` strip) applied, even to a code fence nested inside one (`formatter.rs::code_fence_nested_inside_message_body_is_fully_raw_not_just_r1_protected` locks this priority in).
+
+`@if`/`@for`/`@block` do **not** bypass `clean_output` — they are **not** raw-content spans; only `@message`/`@define` bodies are. A standalone `@block` body therefore still flows through `clean_output` (it gets R1 `\r` strip + R2 trailing-edge normalization), whereas `@message`/`@define` bodies get **neither**. **Under the interior-verbatim contract (#150/#151), `clean_output` no longer caps blank-line runs, so a standalone `@block` body's *interior* blank runs are now preserved verbatim too** — the same observable blank-run behavior as `@message`/`@define`, reached by a different mechanism. This is locked in by `ec_blank_lines_inside_define_message_block_bodies_preserved` (`mds-core/tests/fmt.rs`), whose `@block instructions:\nStep one\n\n\n\nStep two\n@end\n` case now asserts the 4-newline run **survives** and recompiles identically. `@if`/`@for`/`@block` only inherit raw-content status when lexically nested inside a `@message`/`@define` span (the outer span's byte range structurally covers them). And critically, `@block` **cannot** nest inside a `@message` at all — the parser rejects it at parse time (`crates/mds-core/src/parser.rs:565-568`, one of three explicit top-level-only guards) — so a message body can never contain a nested `@block`.
+
+**Region priority** (`rewrite_body`, `formatter.rs:382-507`), checked in this exact order per line: **directive line > raw-content (`@message`/`@define` body) > protected (frontmatter/code-fence) > ordinary content.** Directive lines win even inside a raw-content span because directive text (the `@message user:` line itself) is never part of *any* compiled output, markdown or messages mode — R4 always applies there.
+
+### Rule 3 — the v2 safe ruleset (R1, R2, R4) and what was removed
+
+| Rule | Effect | Why it's provably safe |
+|---|---|---|
+| **R1** | Strip every `\r`, including inside protected regions (the one rule allowed to cross that boundary) | `clean_output` strips `\r` unconditionally (Rule 1 above); frontmatter lexing already filters `\r` from its own captured content; directive matching trims `\r` before comparison. No downstream consumer of a `\r` byte can ever observe it, so removing it up front changes nothing. Not applied inside raw-content (`@message`/`@define`) spans. |
+| **R2** | Exactly one final `\n`; whitespace-only/empty input → `""` | Matches `clean_output`'s `trim_end` + forced final `\n` exactly (`clean_output("   \n") == ""`, verified). |
+| ~~**R3**~~ | ~~A run of N raw `\n` keeps `min(N, 2)`; leading blank lines at body start are elided entirely~~ | **REMOVED in v2 (#150, #151).** `clean_output` no longer caps blank-line runs or strips leading blank lines. Applying R3 would change compiled output under the interior-verbatim contract. |
+| **R4** | Strip trailing whitespace on directive lines | The parser calls `dir.trim()` before matching a directive keyword, so trailing whitespace on that line is discarded pre-parse and never reaches any output — safe even inside a `@message`/`@define` body. |
+
+**Deliberately deferred** (see `formatter.rs` module doc): frontmatter key sorting, `@import` grouping/reordering, interpolation `{ x }` → `{x}` trimming, blank-line insertion around directive blocks, body hard-break normalization, and directive-internal spacing.
+
+**Deliberately NOT implemented**: stripping trailing whitespace from any whitespace-only "blank" line. The regression test `r4_whitespace_only_line_in_middle_of_document_is_preserved_verbatim` (`mds-core/tests/fmt.rs`) locks this in.
+
+## State Transitions — the safety-gate decision tree
+
+`assert_equivalent` (`formatter.rs:446-492`) is called once per `format_str_named` invocation, after the rewrite, and is the actual enforcement point:
+
+1. **Original compiles standalone** (`compile_str_collecting_warnings(source, base_dir, None)` succeeds) → compile the *formatted* string the same way. Outputs equal → `Ok`. Outputs differ, or formatted now fails to compile → `Err(MdsError::FormatterInvariant)`. This is the strong path: a real recompile-and-diff.
+2. **Original fails with `MdsError::Syntax`** → propagate that exact error, unconditionally. The `Syntax` error is rebuilt as `MdsError::Syntax { src: Some(NamedSource::new(file_name, source)) }` so the diagnostic names the file (using the `file_name` parameter threaded from `format_str_named`). This means an unclosed block or unmatched code fence is surfaced as the real author-facing syntax error, not misreported as `FormatterInvariant`. Locked in by `mds-core/tests/fmt.rs::syntax_error_unclosed_directive_blocks_surface_syntax_not_formatter_invariant`.
+3. **Original fails with anything else** (undefined runtime variable/function is the common case) → the token stream is well-formed, only later analysis failed, so the template is still legitimately formattable. Falls back to `structural_equivalent` (`formatter.rs:565-615`): re-tokenize both strings, compare token-for-token using rule-aware normalization.
+
+   **`structural_equivalent` post-v0.4.0 remediation** has two key behaviors worth knowing:
+
+   - **`fmt_raw_content` is recomputed for the formatted stream** (line 575): `raw_content` uses SOURCE byte offsets, which are not valid against the FORMATTED token offsets. The function calls `raw_content_spans(&fmt_tokens, formatted)` to get a separate span vector for the formatted stream before doing the per-token comparison.
+   - **`strip_trailing_insignificant_text`** (formatter.rs ~506-537) is called on **both** token streams before the length comparison (lines 580-581). It pops trailing `Text` tokens whose (a) offset is outside every raw-content span and (b) `crate::clean_output(text).is_empty()` — whitespace-only tokens that contribute nothing to compiled output. This prevents R2's `trim_end()` deletion of a trailing blank-line `Text` token from producing a spurious token-count mismatch when a trailing blank appears after a final directive in a non-compiling source (release blocker 3). Interior tokens are never touched by this helper, so real bugs (dropped interior content) still trip the count or content checks.
+
+   Per-token comparison: `Text` tokens outside raw-content spans are compared via `crate::clean_output`; `Text` tokens inside raw-content spans are compared byte-exact (not via `clean_output`, which would incorrectly treat some byte differences as insignificant); `Directive` content compared after `.trim()`; Frontmatter/Code content compared after `\r` removal. Span membership via `in_raw_content` binary search (O(log S)).
+
+## Technical Implementation Patterns
+
+### Token lossiness forces a span-guided string rewriter, not an AST pretty-printer
+
+Read directly in `crates/mds-core/src/lexer.rs`, the lexer permanently discards information a naive "reconstruct from tokens" formatter would need:
+
+- **Interpolation inner whitespace is trimmed at lex time** — `Token::Interpolation(content.trim().to_string(), start)` (`lexer.rs:272`). `{ name }` and `{name}` produce the identical token; the original spacing is gone.
+- **The newline after a directive line is consumed and never stored** — `scan_directive` (`lexer.rs:195-209`) advances `self.pos` past the line's own `\n` before pushing the `Directive` token.
+- **The newline after a code fence line is likewise consumed** — `scan_code_fence` calls `skip_newline(...)` after both the opening and closing fence.
+- **Frontmatter `\r` is filtered during lexing** — `FrontmatterContent`'s captured string has `\r` removed before it's even stored as a token (`lexer.rs:99`).
+
+Because of this, **you cannot reconstruct source from tokens/AST without inventing or dropping whitespace the author actually wrote.** The formatter tokenizes *only* to classify byte ranges of the ORIGINAL source string, then rewrites that original string region-by-region in one left-to-right, O(n) pass, copying any byte it lacks a proven-safe rule for verbatim. It never builds output from token contents.
+
+### `format_str_named` — the canonical public API
+
+`format_str_named(source, base_dir, file_name)` (`formatter.rs:135`) is the canonical entry point. `format_str_with(source, base_dir)` is a thin wrapper passing `"<source>"` as the `file_name`. `format_str(source)` is a thin wrapper passing `None` for `base_dir`.
+
+`file_name` is used in two places inside `format_str_named`:
+1. **Lexer**: `lexer::tokenize(source, file_name)` — error spans in any `Syntax` error raised at the lex level will name the file.
+2. **`assert_equivalent`'s Syntax arm** (path 2 above): when the original source fails with `MdsError::Syntax`, the error is rebuilt with `NamedSource::new(file_name, source)` so the miette diagnostic shows the correct filename (the internally-used blank label is replaced here).
+
+The CLI calls it via the private `format_source_named` helper in `fmt.rs`, which passes:
+- `path.display()` for single-file and directory mode
+- `"<stdin>"` for stdin mode
+
+In directory mode (`format_one_file`), both error branches (`read_source_file` failure and `format_source_named` failure) print `{file_name}: {error}`, so errors always name the file even without an explicit path in the miette span.
+
+Pinned in `crates/mds-core/tests/api_surface.rs`: the test fixture checks the three-argument signature `fn(&str, Option<&Path>, &str) -> Result<String, MdsError>` so any signature change is caught at compile time.
+
+### Shared walker exclusions (`is_default_excluded_dir`)
+
+`is_default_excluded_dir` (`crates/mds-cli/src/output.rs:164`) and `is_within_default_excluded_dir` (`output.rs:177`) apply PF-004 (parallel-path enforcement) to directory traversal.
+
+`is_default_excluded_dir(name)` returns `true` when a **directory** name starts with `'.'` (hidden dirs like `.git`, `.cache`) or equals `"node_modules"`. Exclusion semantics:
+
+- **Recursion only**: the root directory explicitly passed to `collect_mds_files` is always processed, even if its own name starts with `.`. Hidden *files* (e.g. `.dotfile.mds`) at any traversed level are still collected.
+- **All subcommands**: `run_fmt_directory`, `run_build_directory`, `run_check_directory`, and `run_lint_directory` all call `collect_mds_files` from `output.rs` — the exclusion is inherited automatically. This is what closes the "fmt writes into node_modules" bug: `collect_mds_files` never yields those paths, so `run_fmt_directory` never visits them.
+
+`is_within_default_excluded_dir(root, path)` checks whether a `path` is *inside* a default-excluded subdirectory of `root` — used by watch's two additional guards (PF-004: the limit must be enforced on the parallel event-processing path too):
+
+1. **Event drop** (`handle_fs_event_dir`, `watch.rs:1547`): `changed.retain(|p| !is_within_default_excluded_dir(&ctx.root, p))` — filesystem events from excluded dirs are dropped before they trigger a rebuild. Without this, `npm install` writing to `node_modules/` would trigger spurious full re-scans.
+2. **External-dep treatment** (`process_dir_batch`, `watch.rs:2053`): paths inside excluded subdirs that are nonetheless under root are compiled for dep-graph refresh only (quiet mode, no output emitted), matching the initial walker's behavior.
+
+### Fence recognition widened in #149 — a strict superset of backtick fences
+
+`try_scan_fence_at` (`lexer.rs:409-439`) and its `FenceMatch` struct (`lexer.rs:396-400`) define what the lexer counts as a code fence. As of #149 it scans an **optional `[ \t>]*` prefix** and then requires **≥ 3 consecutive `` ` `` *or* `~`** markers. This makes it recognize indented fences, tilde fences, and blockquoted fences. All of these produce `CodeContent` tokens (interpolation suppressed) and become `protected_spans`. A stray/decorative fence-looking line that never closes now raises `MdsError::syntax_at("unclosed code fence")` (`lexer.rs:371-379`) instead of tokenizing as plain text — in `mds fmt` that lands in `assert_equivalent`'s Syntax path (path 2 above) and is propagated as the author's real error.
+
+### CLI integration (`crates/mds-cli/src/fmt.rs`)
+
+Notable divergences worth knowing before touching this file:
+
+- **`FmtFlags { check, diff, quiet }`** (`fmt.rs:43-48`) is a named struct passed to every per-input helper. Avoids the silent transposition hazard; callers destructure it explicitly.
+- **`format_one_file(file, flags) -> FileOutcome`** (`fmt.rs:232-282`) is a helper that encapsulates the read → format → diff → (optional write) cycle for a single file in directory mode. Error and status lines are printed as side effects so the directory loop only tallies `FileOutcome`.
+- **`MAX_DEPTH = 64`** is declared as a function-local constant inside `run_fmt_directory` (line 297), matching `run_build_directory`/`run_check_directory`.
+- **Raw-text read**: `read_source_file` (`fmt.rs:110-118`) cannot go through `mds::compile*`. It reuses `mds::NativeFs::check_symlink` for the TOCTOU-safe canonicalize+symlink check.
+- **Channel discipline**: formatted content (stdin filter mode) and `--diff` output go to **stdout**; every status line, summary, and error goes to **stderr**; `--quiet` suppresses status/summaries but never errors.
+- **`--check` directory summary** is `"{changed_count} would reformat, {unchanged_count} unchanged, {fail_count} failed"` (`fmt.rs:335`). The `changed_count > 0` disjunct in the summary print was removed; only `fail_count > 0` forces a summary under `--quiet`.
+- **`--diff`** renders via the `similar` crate's unified diff, ANSI-colorized only when `std::io::stdout().is_terminal()`. The colorizer (`colorize_unified_diff`, `fmt.rs:396-430`) uses an `in_hunk` state-machine flag set on the first `@@` marker, correctly handling content lines that themselves start with `---` or `+++`.
+- **Write-only-if-changed** preserves mtime on already-clean files.
+- **Directory mode formats partials** (`_`-prefixed files) — a deliberate divergence from `run_build_directory`/`run_check_directory`, which skip them. Formatting rewrites *source*, and a partial's source is just as reformattable as any other file.
+- **`FmtConfig { sort_frontmatter_keys: bool }`** (`build.rs:36-65`) is forward-compat scaffolding: parsed and validated but **not consulted by any formatting behavior** — a deliberate no-op.
+- **After-help stdin demo** (`main.rs`) uses `printf '@if ready:   \nGo\n@end\n' | mds fmt -`. The trailing spaces on the directive line are stripped by R4, so this IS input that `mds fmt` actually changes — verified that after_help was updated from a no-op example.
+
+## Error Handling and Recovery
+
+`MdsError::FormatterInvariant { message: String }` (`error.rs:335-345`, code `mds::formatter_invariant`, constructed via the private `MdsError::formatter_invariant()` helper at `error.rs:686-692`) means **the formatter itself has a bug** — the CLI must never write the file when this occurs. The field name is `message`, matching all other free-form-string variants in `MdsError`. Both `FormatterInvariant` and `Syntax` map to the generic `_ => 1` arm in `exit_code` (`build.rs:372-382`) — no new exit codes were added for `fmt`. The CLI-level contract: `format_str_named` returns `Err`, never a garbled `Ok(String)`, so `fmt.rs` only ever reaches its write call with a value that already passed the gate.
+
+## Anti-Patterns
+
+- **Reconstructing formatted output from tokens or the AST.** The lexer is lossy — this will silently invent or drop whitespace the author wrote.
+- **Stripping whitespace from any line that "looks blank."** A whitespace-only line in the middle of a document is body content — two trailing spaces are a Markdown hard break.
+- **Adding blank-line collapsing (R3) back to the formatter.** R3 was removed in v2 (#150/#151) because `clean_output` no longer caps blank-line runs. This applies to `@block` bodies too.
+- **Applying R1 (`\r` strip) inside a `raw_content_spans` range.** `@message`/`@define` bodies bypass `clean_output` entirely — removing `\r` from them would change compiled JSON content.
+- **Treating `structural_equivalent` as equivalent in strength to a real recompile.** It's a token-comparison approximation used only when the source doesn't compile standalone. Never use it as a substitute for path 1.
+- **Using `raw_content` (source offsets) to check tokens from the formatted string.** `structural_equivalent` recomputes `fmt_raw_content` from the formatted token stream because source byte offsets are not valid against formatted-string token offsets.
+- **Adding a new formatting rule without empirically re-verifying `clean_output`/`evaluate_nodes` behavior first.** The doc comment on `clean_output` is not authoritative — read the source code.
+- **Assuming `@define` bodies are safe to collapse because they look like ordinary markdown-mode content.** They're conservatively treated as raw because the formatter cannot statically determine whether a given `@define`d function is ever called from inside a `@message` body.
+
+## Gotchas
+
+- **`@block` bodies now preserve interior blank runs.** A standalone `@block` body is NOT a raw-content span (it still goes through `clean_output`, unlike `@message`/`@define`), but because `clean_output` is now interior-verbatim, its interior blank runs survive. Do not "fix" a `@block` that keeps a 4-newline run — that is now correct behavior.
+- **`effective_parent` (fs.rs ~287) fixes bare-filename resolution everywhere.** `Path::parent()` returns `Some("")` (an empty path) for bare relative filenames like `"hello.mds"`, NOT `None`. Passing an empty path to `canonicalize` produces a file-not-found error. `effective_parent` maps both `Some("")` and `None` to `Path::new(".")`, so bare filenames resolve from the current working directory. This was release blocker 1 (before the fix, `mds fmt hello.mds` with no directory prefix would fail). `check_symlink` explicitly calls `effective_parent` in its parent-directory step. `atomic_write_file` also calls `effective_parent` for the same reason.
+- **`strip_trailing_insignificant_text` is tail-only, not interior.** The helper only pops from the END of the token stream. An interior blank-line `Text` token (e.g. after a `@if` block in the middle of a file) is never touched. A false `FormatterInvariant` that triggers for a trailing blank line after a final directive (on a source that only compiles with runtime vars) was release blocker 3 — fixed by this helper.
+- **Frontmatter deep-merge (`@extends`, #153) lives outside `formatter.rs` but shares the reserved-key vocabulary.** `deep_merge_yaml` is in `crates/mds-core/src/resolver/frontmatter.rs` (not `resolver.rs`), and its reserved-key strip (`RESERVED_MERGE_KEYS = ["imports", "type", "extends"]`) is gated on **`depth == 0`**. The raw frontmatter block is copied verbatim by the formatter, so `sort_frontmatter_keys` staying a no-op keeps the formatter clear of this logic.
+- **FIXED (PF-003 / #133, #146): the resolver's `<source>` path-sentinel is eliminated.** `resolve_source`/`resolve_source_intrinsic` now pass the canonical directory string directly as `ctx.base_dir` and call `fs.normalize_in_dir(ctx.base_dir, rel)` — no synthetic path constructed. `SOURCE_LABEL` const is display/cycle-detection only. Locked in by `resolver_tests.rs::pf003_parent_dir_strips_on_windows_verbatim_path`.
+- **`FmtConfig.sort_frontmatter_keys` parses but does nothing.** Don't "wire it up" opportunistically.
+- **Adding a field to `MdsConfig` ripples into unrelated existing tests.** The `fmt: FmtConfig` field addition required `..Default::default()` in pre-existing struct-literal test sites in `build.rs` and `watch.rs`.
+- **Partials are reformatted but `is_partial` still gates output emission elsewhere.** Don't conflate the two meanings of "partial" across `fmt` vs. `build`/`check`.
+- **Hidden FILES are still collected by the walker.** `is_default_excluded_dir` excludes hidden *directories* from recursion, not hidden `.mds` files at the traversed level. A `.dotfile.mds` at the root of a traversed directory is collected and formatted.
+- **`atomic_write_file` is the write primitive — not `std::fs::write`.** `fmt.rs` calls `atomic_write_file` from `output.rs` (shared with `lint.rs`). It provides a TOCTOU guard, Unix permission preservation (`mode & 0o7777`), and `sync_all()` + atomic rename. This means a failed write leaves the original file intact — it does NOT leave a partially-written file.
+
+## Deferred follow-ups (recorded to avoid re-flagging as new debt)
+
+These items were consciously deferred and have back-ref comments in source:
+
+- **A1 — block-opener keyword const centralization**: `raw_content_spans` in `formatter.rs` and the parser's `parse_block` both contain the same list of block-opener keywords inline. Extracting a shared const was deferred (requires deciding where in the crate the const lives without a circular module dependency). Still deferred as of 2026-07-19.
+- **R3 — `write_stderr` broken-pipe helper**: the `write_stdout` helper in `fmt.rs` handles broken pipe cleanly, but equivalent stderr writes still use bare `eprintln!`. Still deferred as of 2026-07-19.
+- **End-to-end `FormatterInvariant` gate test**: a test that forces `assert_equivalent` to return `FormatterInvariant` at the CLI level (a deliberate formatter bug scenario) remains deferred. See `cli_fmt.rs:131` for the comment. The new `strip_trailing_insignificant_text` fix for release blocker 3 is tested (`cli_fmt.rs:992`) — that test verifies the false-positive is gone, not the true-positive path.
+- **D1 — systematic license attribution**: no per-file SPDX headers yet; deferred pending a crate-wide audit pass.
+- **D2 — cargo-deny / cargo-audit CI gate**: not yet added to release or PR CI.
+- **S1 — openat/O_NOFOLLOW write-path hardening**: `fmt.rs` now calls `atomic_write_file` (from `output.rs`), which is atomic (TOCTOU guard + `effective_parent` + temp-file rename). The "not atomic" sub-item is resolved. However, `O_NOFOLLOW` is still not used for the actual write file descriptor — the read-side `NativeFs::check_symlink` provides partial mitigation. The remaining gap is the write-side file descriptor; `openat` / `O_NOFOLLOW` hardening is still deferred.
+
+## Key Files
+
+- `crates/mds-core/src/formatter.rs` — the entire engine: `format_str_named` (~line 135), region computation, the rewrite pass, `strip_trailing_insignificant_text` (~line 522), `in_raw_content` binary-search helper, `assert_equivalent` (~line 446), and `structural_equivalent` (~line 565)
+- `crates/mds-core/src/lib.rs:60` — `pub use formatter::{format_str, format_str_named, format_str_with}` (the public re-export); `:665-681` — `clean_output`
+- `crates/mds-core/src/fs.rs:287` — `effective_parent` (bare-filename fix, maps `Some("")`/`None` → `"."`)
+- `crates/mds-cli/src/output.rs:164,177` — `is_default_excluded_dir` / `is_within_default_excluded_dir` (shared walker exclusions; applies to all subcommands and both watch paths); `:432` — `atomic_write_file` (shared write primitive: TOCTOU guard + permissions restore + sync_all + atomic rename; used by both `fmt.rs` and `lint.rs`)
+- `crates/mds-core/src/evaluator.rs:845` — the `evaluate_nodes(...).trim()` call (spec §4.11 edge-trim) that makes `@message` bodies bypass `clean_output`
+- `crates/mds-core/src/resolver/frontmatter.rs:53-129` — `deep_merge_yaml` (`@extends` frontmatter merge)
+- `crates/mds-core/src/parser.rs:545-594` — `parse_block`; the `@block`-cannot-nest-in-`@message` guard
+- `crates/mds-core/src/lexer.rs` — token-lossiness sites and fence recognition (`try_scan_fence_at`/`FenceMatch`, `fence_closes`, unclosed-fence error)
+- `crates/mds-core/src/error.rs:335-345, 686-692` — `FormatterInvariant { message: String }`
+- `crates/mds-cli/src/fmt.rs` — the `fmt` subcommand: `FmtFlags`, `format_source_named` calling `mds::format_str_named`, `format_one_file`, channel discipline, diff colorizer; calls `atomic_write_file` (not `std::fs::write`)
+- `crates/mds-cli/src/build.rs:16-65` — `MdsConfig`/`FmtConfig`/`BuildConfig`; `:372-382` — `exit_code`
+- `crates/mds-core/tests/api_surface.rs:14` — compile-time pin of `format_str_named` signature
+- `crates/mds-core/tests/fmt.rs`, `crates/mds-cli/tests/cli_fmt.rs` — every empirically-verified claim above is locked in as a regression test here
+
+## Related
+
+- [[mds-compiler]] — the compilation pipeline the formatter's safety gate re-invokes (`compile_str_collecting_warnings`, `CompileResult`, intrinsic Markdown/Messages dispatch).
+- [[mds-cli]] — command dispatch, exit-code mapping, `resolve_input`/`auto_detect_mds_file`, directory-mode machinery (`collect_mds_files`, `MAX_DEPTH`), and `MAX_FILE_SIZE` enforcement.
+- ADR-001 (compile-equivalence gate) — the architectural decision behind `assert_equivalent`: every formatter call must produce byte-identical compiled output, enforced at runtime per call, not just by test coverage.
+- ADR-002 (verbatim whitespace contract) — the architectural decision behind the removal of R3: `clean_output` is interior-verbatim, so the formatter must pass interior blank lines through unchanged.
+- PF-004 (parallel-path enforcement) — the pitfall behind `is_default_excluded_dir` appearing in both `collect_mds_files_inner` and watch's `handle_fs_event_dir` / `process_dir_batch`: the same limit must be enforced on every path (initial walker and event-processing path) or events from excluded dirs slip through to trigger spurious rebuilds.
+- PF-003 — **RESOLVED** (PRs #133/#146): Windows verbatim-path `@import` pitfall in the resolver. The `<source>` path-sentinel is eliminated; `resolve_source`/`resolve_source_intrinsic` now use `FileSystem::normalize_in_dir`. No longer in the active pitfalls set.
+- `.devflow/features/mds-lint/KNOWLEDGE.md` — `mds lint` knowledge base; `--fix` write path shares `atomic_write_file` from `output.rs`.
+- `.devflow/features/source-map-security/KNOWLEDGE.md` — source map path-containment choke-point (`relativize_source`), `FileSystem::source_root()`, `CompileOptions.source_map_base`. Not directly relevant to `mds fmt` today (fmt is CLI-only and does not emit source maps), but relevant if source-map output is ever added to `mds build`.
diff --git a/.devflow/features/mds-js/KNOWLEDGE.md b/.devflow/features/mds-js/KNOWLEDGE.md
new file mode 100644
index 0000000..b4a6bd3
--- /dev/null
+++ b/.devflow/features/mds-js/KNOWLEDGE.md
@@ -0,0 +1,193 @@
+---
+feature: mds-js
+name: MDS JavaScript Package (@mdscript/mds)
+description: "Use when modifying the JS/TS public API surface, adding backend methods, changing result types, updating the backend contract, working on WASM/native backend validation, or debugging why a backend result is rejected. Keywords: compileFile, compile, check, checkFile, CompileResult, MarkdownResult, MessagesResult, CheckResult, CompileMessagesResult, assertResultShape, validateBackendMethods, BASE_METHODS, NODE_METHODS, WASM_EXPORTS, discriminated union, kind, mds::invalid_backend_result, native.ts, wasm.ts, contract.ts, types.ts, node.ts, browser.ts."
+category: component-patterns
+directories: ["packages/mds/"]
+referencedFiles:
+  - packages/mds/src/types.ts
+  - packages/mds/src/backend/contract.ts
+  - packages/mds/src/backend/native.ts
+  - packages/mds/src/backend/wasm.ts
+  - packages/mds/src/node.ts
+  - packages/mds/src/browser.ts
+  - packages/mds/src/index.ts
+  - packages/mds/__test__/intrinsic-output.spec.mjs
+  - packages/mds/__test__/backend-contract.spec.mjs
+created: 2026-06-26
+updated: 2026-06-26
+---
+
+# MDS JavaScript Package (@mdscript/mds)
+
+## Overview
+
+`packages/mds/` is the universal JS/TS package. It wraps either the native NAPI addon (Node.js) or the WASM module (browser/WASM Node) behind a unified API. After the intrinsic-output refactor, `compile` and `compileFile` return a **discriminated union** (`CompileResult = MarkdownResult | MessagesResult`), not a flat string. The `compileMessages`/`compileMessagesFile`/`CompileMessagesResult` symbols are deleted.
+
+## Core Responsibilities
+
+- Export `compile`, `compileFile`, `check`, `checkFile`, `init`, `getBackend`, `isMdsError` to consumers
+- Validate that the loaded backend (native addon or WASM module) exposes the required method names
+- Validate that each compile/check call returns the correct result shape (shallow O(1) check)
+- Re-export all public types (`CompileResult`, `MarkdownResult`, `MessagesResult`, `CheckResult`, `Message`, etc.)
+- Does NOT implement compilation — delegates entirely to the backend
+
+## Standard Structure
+
+### CompileResult — the discriminated union type
+
+```typescript
+// packages/mds/src/types.ts
+export interface MarkdownResult {
+  kind: 'markdown';
+  output: string;         // rendered Markdown — present only on markdown results
+  warnings: string[];
+  dependencies: string[];
+}
+
+export interface MessagesResult {
+  kind: 'messages';
+  messages: Message[];    // array of {role, content} — present only on messages results
+  warnings: string[];
+  dependencies: string[];
+}
+
+export type CompileResult = MarkdownResult | MessagesResult;
+
+export interface CheckResult {
+  warnings: string[];
+  // NOTE: no dependencies — check does not expose deps
+}
+```
+
+Branch on `result.kind` to narrow to the specific variant:
+
+```typescript
+if (result.kind === 'markdown') {
+  // result.output is string here
+} else {
+  // result.messages is Message[] here
+}
+```
+
+### Method manifests in contract.ts
+
+```typescript
+// contract.ts
+export const BASE_METHODS = ['compile', 'check'] as const;
+export const NODE_METHODS = ['compileFile', 'checkFile'] as const;
+export const WASM_EXPORTS = [...BASE_METHODS, 'scanImports'] as const;
+// WASM_EXPORTS does NOT include compileMessages — it was deleted from the wasm binding
+```
+
+`createNativeBackend` validates `[...BASE_METHODS, ...NODE_METHODS]`; `createWasmBackend` validates `WASM_EXPORTS`. Any missing method throws a plain `Error` (not an `mds::` coded error) naming the missing method.
+
+### assertResultShape — O(1) shallow validator
+
+```typescript
+export function assertResultShape(result: unknown, kind: ResultKind): void
+```
+
+- `kind='compile'`: branches on `result.kind`; checks `output` is string (markdown) or `messages` is array (messages); asserts the **inactive field is absent** (`'messages' in r` for markdown, `'output' in r` for messages); asserts `warnings` and `dependencies` are arrays
+- `kind='check'`: only asserts `warnings` is array
+- Throws `Error` with `code: 'mds::invalid_backend_result'` on shape violation
+- PERF-04 constraint: uses only `Array.isArray()` — never accesses array elements or indexes. A Proxy must observe zero numeric-index reads.
+- Extra fields on valid results are silently tolerated
+
+### Deleted exports
+
+These symbols are removed and must not be re-exported anywhere:
+- `compileMessages` (from `node.ts`, `browser.ts`, `index.ts`)
+- `compileMessagesFile` (from `node.ts`, `index.ts`)
+- `CompileMessagesResult` type (from `types.ts`, `index.ts`)
+
+The test files `compile-messages.spec.mjs` and `wasm-compileMessages.spec.mjs` are also deleted. The new test `intrinsic-output.spec.mjs` (U-IO-1..U-IO-22) asserts that the deleted exports are absent:
+
+```javascript
+// U-IO-21/22 — these must pass
+assert.strictEqual(typeof module.compileMessages, 'undefined');
+assert.strictEqual(typeof module.compileMessagesFile, 'undefined');
+```
+
+### NapiAddon interface (native.ts)
+
+```typescript
+interface NapiAddon {
+  compile(source: string, opts?: unknown): unknown;
+  check(source: string, opts?: unknown): unknown;
+  compileFile(path: string, opts?: unknown): unknown;  // async via JS wrapper
+  checkFile(path: string, opts?: unknown): unknown;
+  // NO compileMessages, NO compileMessagesFile
+}
+```
+
+All methods return `unknown` (the actual value is `serde_json::Value` from PR-2). `assertResultShape` validates the shape before returning to the caller.
+
+### WasmModule interface (wasm.ts)
+
+```typescript
+interface WasmModule {
+  compile(source: string, opts?: unknown): unknown;
+  check(source: string, opts?: unknown): unknown;
+  scanImports(source: string): unknown;
+  default?: () => Promise<void>; // optional initializer
+  // NO compileMessages
+}
+```
+
+### ResultKind type
+
+```typescript
+export type ResultKind = 'compile' | 'check';
+```
+
+Used as the discriminant for `assertResultShape`. The `'compile'` case covers both `MarkdownResult` and `MessagesResult` — the function branches internally on `result.kind`.
+
+## Dependency Patterns
+
+Mock MDS APIs in tests must return the new discriminated-union shape:
+
+```javascript
+// Correct mock shape (not the old flat { output: ... })
+{ kind: 'markdown', output: '...', warnings: [], dependencies: [] }
+// or
+{ kind: 'messages', messages: [{role:'user', content:'hi'}], warnings: [], dependencies: [] }
+```
+
+## Error Handling
+
+`compile`/`compileFile` propagate `mds::mixed_content` from the backend when the source file has mixed content. The JS package does not catch or transform these errors — they pass through to the caller.
+
+`assertResultShape` errors have `code: 'mds::invalid_backend_result'` — distinguishable from compiler errors (`mds::*` from `mds-core`) so callers can tell "shape problem" from "compile error".
+
+## Anti-Patterns
+
+- **Accessing `result.output` without branching on `result.kind`** — TypeScript will catch this at compile time since `CompileResult` is a union; `output` is only on `MarkdownResult`
+- **Re-exporting `compileMessages` or `CompileMessagesResult`** — deleted; test spec has negative assertions
+- **Calling `Array.isArray()` then accessing elements in assertResultShape** — PERF-04 violation; the validator must be O(1); never access `[0]` or iterate
+- **Including `compileMessages` in `WASM_EXPORTS` or `BASE_METHODS`** — deleted from WASM binding; adding it here will cause validateBackendMethods to throw on valid WASM modules
+- **Returning `{ kind: 'markdown', output: ..., messages: [] }` from mocks** — inactive field must be absent; assertResultShape rejects it
+
+## Gotchas
+
+- `CheckResult` has only `{ warnings: string[] }` — no `dependencies`. This matches the napi wire (check returns warnings only). Not a regression — pre-change CheckResult was the same shape.
+- `WASM_EXPORTS` includes `scanImports` (needed for JS-side file resolution) but `BASE_METHODS` does not. Don't copy `WASM_EXPORTS` content into `BASE_METHODS`.
+- The `assertReady()` error message is "Call await init() before using compile" — this exact string appears in tests; don't change it without updating the tests.
+- Mock MDS APIs in older tests may still return the old `{ output: string, warnings, deps }` shape. Update them to `{ kind: 'markdown', output: ..., warnings: [], dependencies: [] }`.
+
+## Key Files
+
+- `packages/mds/src/types.ts` — `Message`, `MarkdownResult`, `MessagesResult`, `CompileResult`, `CheckResult`, `MdsBaseBackend`, `MdsNodeBackend`
+- `packages/mds/src/backend/contract.ts` — `BASE_METHODS`, `NODE_METHODS`, `WASM_EXPORTS`, `ResultKind`, `assertResultShape`, `validateBackendMethods`
+- `packages/mds/src/backend/native.ts` — `NapiAddon` interface, `createNativeBackend`
+- `packages/mds/src/backend/wasm.ts` — `WasmModule` interface, `createWasmBackend`
+- `packages/mds/src/node.ts` — `wrapWithFileOps`, public `compileFile`/`checkFile`; exports `MarkdownResult`, `MessagesResult`
+- `packages/mds/src/browser.ts` — browser-safe re-exports; exports `Message`, `MarkdownResult`, `MessagesResult`
+- `packages/mds/__test__/intrinsic-output.spec.mjs` — U-IO-1..U-IO-22; tests for kind branching + absence assertions
+- `packages/mds/__test__/backend-contract.spec.mjs` — U-BC1..U-BC20; assertResultShape shape + absence tests
+
+## Related
+
+- Feature: mds-napi — the native backend; `compile`/`compileFile` return the discriminated union this package types
+- Feature: bundler-plugins — imports `compileFile` from this package via the `MdsApi` interface in `bundler-utils/src/types.ts`
+- Feature: mds-compiler — the Rust `CompileResult`/`CompiledOutput` types that drive the wire format
diff --git a/.devflow/features/mds-napi/KNOWLEDGE.md b/.devflow/features/mds-napi/KNOWLEDGE.md
new file mode 100644
index 0000000..7bfa3f6
--- /dev/null
+++ b/.devflow/features/mds-napi/KNOWLEDGE.md
@@ -0,0 +1,156 @@
+---
+feature: mds-napi
+name: MDS Native Node.js Bindings (mds-napi)
+description: "Use when modifying the native addon API surface, adding new napi exports, debugging FFI marshaling, working on error serialization, understanding the discriminated-union wire format, or investigating why a JS caller gets unexpected result shapes. Keywords: mds-napi, napi-rs, compile, compileFile, check, checkFile, build_canonical_result, CheckResult, serde_json::Value, ToNapiValue, discriminated union, kind, output, messages, absent field, mds::mixed_content, mds::internal, mds::invalid_options, mds::resource_limit, throw_mds_error, run_catching, catch_unwind."
+category: component-patterns
+directories: ["crates/mds-napi/"]
+referencedFiles:
+  - crates/mds-napi/src/lib.rs
+  - crates/mds-napi/Cargo.toml
+  - crates/mds-napi/__test__/index.spec.mjs
+  - crates/mds-napi/__test__/fixtures/messages.mds
+  - crates/mds-napi/__test__/fixtures/mixed.mds
+created: 2026-06-26
+updated: 2026-06-26
+---
+
+# MDS Native Node.js Bindings (mds-napi)
+
+## Overview
+
+`crates/mds-napi/` is the native Node.js addon built with napi-rs. It exposes four `#[napi]` functions to JavaScript: `compile`, `compileFile`, `check`, and `checkFile`. All compilation logic lives in `mds-core`; the napi layer handles FFI marshaling, options parsing, resource-limit enforcement, and structured error throwing.
+
+After the intrinsic-output refactor, `compile` and `compileFile` return a **discriminated union object** built field-by-field. The inactive payload field is structurally absent (no null injection). `check` and `checkFile` remain unchanged — they return `{ warnings: string[] }`.
+
+## Core Responsibilities
+
+- Expose `compile`, `compileFile`, `check`, `checkFile` to Node.js as native functions
+- Build the canonical discriminated-union result object from `mds::CompileResult`
+- Marshal Rust errors into JS errors with `.code`, `.help`, `.span` properties
+- Enforce the 10 MiB source size limit at the napi boundary (before calling mds-core)
+- Validate and parse the optional `opts` object (`basePath`, `vars` for `compile`; `vars` only for `compileFile`)
+- Does NOT implement any compilation logic
+
+## Standard Structure
+
+### Exported napi functions
+
+```rust
+// Returns serde_json::Value (discriminated union)
+#[napi] pub fn compile(env: Env, source: String, opts: Option<Object>) -> napi::Result<serde_json::Value>
+#[napi(js_name = "compileFile")] pub fn compile_file(env: Env, path: String, opts: Option<Object>) -> napi::Result<serde_json::Value>
+
+// Returns CheckResult { warnings: Vec<String> }
+#[napi] pub fn check(env: Env, source: String, opts: Option<Object>) -> napi::Result<CheckResult>
+#[napi(js_name = "checkFile")] pub fn check_file(env: Env, path: String, opts: Option<Object>) -> napi::Result<CheckResult>
+```
+
+### build_canonical_result — the wire-format builder
+
+This private function is the single point of truth for the JS wire format:
+
+```rust
+fn build_canonical_result(result: mds::CompileResult) -> serde_json::Value {
+    // Field-by-field construction: inactive field is ABSENT, not null
+    match result.output {
+        mds::CompiledOutput::Markdown(text) => serde_json::json!({
+            "kind": "markdown",
+            "output": text,       // "output" key, NOT "value"
+            "warnings": warnings,
+            "dependencies": dependencies,
+        }),
+        mds::CompiledOutput::Messages(msgs) => serde_json::json!({
+            "kind": "messages",
+            "messages": messages, // "messages" key, NOT "value"
+            "warnings": warnings,
+            "dependencies": dependencies,
+        }),
+    }
+}
+```
+
+Key design decisions:
+- `serde_json::Value` implements `ToNapiValue` in napi-rs 3.x via the `serde-json` feature. This is the correct owned return type for dynamic objects — it avoids `Object<'env>` lifetime issues.
+- The `serde_json::json!()` macro lists fields explicitly — no serde derive inference that might inject extra fields.
+- The payload key for markdown is `output` (not `value`) and for messages is `messages` (not `value`). This differs from the Rust-level adjacently-tagged serde shape (`content`/`value`).
+
+### Wire shapes
+
+Markdown:
+```json
+{ "kind": "markdown", "output": "<string>", "warnings": [], "dependencies": [] }
+```
+
+Messages:
+```json
+{ "kind": "messages", "messages": [{"role":"...","content":"..."}], "warnings": [], "dependencies": [] }
+```
+
+Check result (unchanged):
+```json
+{ "warnings": [] }
+```
+
+### Deleted exports
+
+These must not be re-exposed:
+- `compileMessages(source, opts)` — deleted
+- `compileMessagesFile(path, opts)` — deleted
+- `CompileMessagesResult` struct — deleted
+
+The napi test spec has `AC-API-05` tests that assert `typeof addon.compileMessages === 'undefined'` and same for `compileMessagesFile`.
+
+### Error codes
+
+Errors thrown at the napi boundary carry a `.code` property:
+
+| Code | Source |
+|------|--------|
+| `mds::*` (e.g. `mds::syntax`, `mds::mixed_content`) | from `mds-core` via `throw_mds_error` |
+| `mds::internal` | napi-only; unexpected panic caught by `run_catching` |
+| `mds::invalid_options` | napi-only; malformed options object |
+| `mds::resource_limit` | napi-only; source string exceeds 10 MiB |
+
+The `throw_mds_error` path serializes `MdsError` and attaches `.help` and `.span` properties using raw N-API calls (`raw_create_error`, `raw_set_string_prop`).
+
+### Panic safety
+
+All `#[napi]` functions wrap their `mds-core` call in `run_catching` + `catch_unwind`. The workspace panic strategy must remain `unwind` (see `CLAUDE.md` gotchas). The `debug-panics` Cargo feature gates leak of panic details — it must never ship enabled.
+
+## Dependency Patterns
+
+`Cargo.toml` must have `serde_json = { workspace = true, features = ["std"] }` and the napi `serde-json` feature enabled for `serde_json::Value` to implement `ToNapiValue`.
+
+Options parsing uses direct napi property access (`obj.get_named_property_unchecked`) rather than bulk deserialization to give precise error messages for each invalid field. `reject_unknown_napi_keys` enumerates all keys and reports all unknown ones at once.
+
+## Error Handling
+
+`check` / `checkFile` now run full intrinsic dispatch via `mds-core`. They will return `mds::mixed_content` for templates with orphan content alongside `@message` blocks. This is a behavior change from before the refactor.
+
+`compile` / `compileFile` accept `vars` with special characters; these round-trip byte-identical through FFI in both messages and markdown modes (K-VARS-1 test).
+
+## Anti-Patterns
+
+- **Returning `Object<'env>` from `#[napi]` for dynamic objects** — use `serde_json::Value` instead; `Object<'env>` has lifetime issues that prevent returning the constructed object
+- **Using serde derive on the napi return type** — the wire format has different key names from the Rust adjacently-tagged shape; always use `build_canonical_result` with explicit `json!()` fields
+- **Exposing `compileMessages` or `compileMessagesFile`** — deleted; assertions in test spec guard against re-adding them
+- **Constructing `CheckResult` with a `dependencies` field** — `CheckResult` has only `warnings`; no deps are returned from check operations
+
+## Gotchas
+
+- The napi-generated `index.d.ts` is git-ignored; it is regenerated in CI. If you need to inspect the current type shape, check `crates/mds-napi/__test__/index.spec.mjs` assertions or `packages/mds/src/types.ts` (which mirrors the intended shapes).
+- `basePath` option is accepted by `compile`/`check` but rejected by `compileFile`/`checkFile` (base directory is derived from the file path). The `parse_file_opts` function explicitly checks for and rejects `basePath`.
+- Empty `basePath` string is rejected (`throw_options_error`).
+- The `MAX_SOURCE_SIZE` constant at the napi boundary mirrors `mds::MAX_FILE_SIZE` because string-based `compile` calls bypass the file layer.
+
+## Key Files
+
+- `crates/mds-napi/src/lib.rs` — the entire napi implementation; `build_canonical_result`, all `#[napi]` exports, error helpers
+- `crates/mds-napi/Cargo.toml` — must have `serde-json` feature for napi-rs and `serde_json` workspace dep
+- `crates/mds-napi/__test__/index.spec.mjs` — 65 JS tests; "intrinsic output shape" group (K-MD-*, K-MSG-*, K-MIXED-*, K-VARS-*); AC-API-05 deletion assertions
+
+## Related
+
+- Feature: mds-compiler — `mds::CompileResult`, `mds::CompiledOutput`, `mds::compile_with_deps` are the core inputs to `build_canonical_result`
+- Feature: mds-js — the JS package that re-exports these shapes as TypeScript types; `MarkdownResult`/`MessagesResult` union matches the wire format exactly
+- Feature: bundler-plugins — also consumes `compileFile` return shape via `MdsApi` interface
diff --git a/.devflow/features/source-map-security/KNOWLEDGE.md b/.devflow/features/source-map-security/KNOWLEDGE.md
new file mode 100644
index 0000000..e1598f3
--- /dev/null
+++ b/.devflow/features/source-map-security/KNOWLEDGE.md
@@ -0,0 +1,190 @@
+---
+feature: source-map-security
+name: Source Map Security and Path Containment
+description: "Use when working with Source Map v3 generation, sources[] path relativization, the relativize_source choke-point, FileSystem::source_root(), CompileOptions.source_map_base, cross-surface source-map parity tests, or the Windows verbatim UNC path fix. Keywords: source map, sources[], relativize_source, source_map_base, source_root, path containment, basename fallback, PF-005, ADR-005, SEC-3, Windows verbatim UNC, path_to_unified, compute_source_map_base, apply_source_map_file_label, CF-SM2, V-SM1, differential test, two-level anchoring, map-relative, root-relative."
+category: domain-knowledge
+directories:
+  - crates/mds-core/src
+  - crates/mds-cli/src
+  - packages/mds/src
+created: 2026-07-19
+updated: 2026-07-19
+---
+
+# Source Map Security and Path Containment
+
+## Overview
+
+Source Map v3 generation (`ADR-005`) is opt-in via `CompileOptions::source_map`. When enabled, `sources[]` entries must never expose absolute paths, machine-layout information, or paths outside the project root — failing to enforce this is a disclosure vulnerability (`PF-005`). The entire enforcement is funneled through a single choke-point function, `relativize_source` in `crates/mds-core/src/source_path.rs`, applied unconditionally at BOTH `finalize` sites in `resolver.rs`.
+
+The security model is **project-root containment, not "no `../`"**. A source file at `/proj/src/a.mds` with the map in `/proj/build/` legitimately produces `../src/a.mds` — that path is inside the project root and is correct SMv3 output. The guard fires only when the resolved path escapes above the root, in which case the entry collapses to a bare basename.
+
+## Business Context
+
+The guard closes three disclosure classes: (1) paths above the project root leaking system-level directories; (2) absolute paths embedding machine layout; (3) Windows verbatim extended-length paths (`\\?\C:\...`) surviving as-is into published source maps. All invariants are enforced unconditionally at runtime — never as `debug_assert!` (which is compiled out in release builds; see `PF-005`).
+
+## Core Business Rules
+
+### The Containment Rule
+
+The decision tree, checked in this order:
+
+1. **Sentinel**: `source` starts with `<` and ends with `>` (e.g. `<stdin>`) → return verbatim. These are diagnostic labels, not filesystem paths.
+2. **Separator unification first**: replace `\` with `/` before any other check — closes the backslash-on-Unix bypass where `..\..\Users\alice\secret.mds` would otherwise pass every subsequent `/`-based check.
+3. **Verbatim-prefix strip**: remove `//?/UNC/` or `//?/` — closes Windows `canonicalize()` producing verbatim paths that misalign component lists (see "Windows UNC gotcha" below).
+4. **Classify absolute** (leading `/` or drive-qualified `C:\`, `C:/`, `C:`).
+5. **Lexical normalization into components** — resolves `.`, `..` — closes `./../../` and interior-dot-dot bypasses.
+6. **`root = None` branch** (VirtualFs / WASM): no containment concept. Absolute/drive-qualified keys → basename; relative keys whose first component is `..` → basename; anything else passes through unified.
+7. **Resolve against `base` (or `root`)** if not absolute.
+8. **Containment check** (component-wise): source must be a descendant of `root`. If not → basename.
+9. **Emit relative to `b`** where `b = base` if base is inside root, else `b = root`. Round-trip re-check before returning; on failure → basename.
+10. **Basename fallback** uses the last non-`..` component of the NORMALIZED component list — never `Path::file_name()` on the raw string, which on Unix returns the whole string for backslash paths like `..\..\secret.mds`.
+
+The discriminating test pair in `source_path.rs` that both must pass simultaneously:
+- `core_rule_map_relative`: `/proj/src/a.mds`, base `/proj/build`, root `/proj` → `"../src/a.mds"` (inside root, map-relative)
+- `core_rule_source_outside_root`: `/proj/src/a.mds`, base `/proj/build`, root `/proj/build` → `"a.mds"` (outside that root, fallback)
+
+A prior fix (`a7ef84f`) got this backwards (treating any `../` as an escape) and was reverted. The correct rule is containment relative to root, not the absence of `..`.
+
+### Two-Level Anchoring (CLI vs. Bindings)
+
+`sources[]` paths are anchored to different locations depending on the surface:
+
+| Surface | `source_map_base` | Anchoring | Example |
+|---------|-------------------|-----------|---------|
+| CLI (`mds build -o build/out.md`) | `Some(build/)` — output file's parent directory | Map-relative (`../src/x.mds`) | SMv3 spec §3 |
+| CLI stdin / `-o -` | `Some(cwd())` | Map-relative against CWD | |
+| napi, Python, WASM | `None` | Root-relative (`src/x.mds`) | |
+
+When `base = None`, `relativize_source` anchors against root directly. This means CLI writing a sidecar into `build/` legitimately yields `../src/x.mds` while bindings yield `src/x.mds` — that is two correct values for two different anchors, not divergence.
+
+### `FileSystem::source_root()` — defaulted trait method
+
+```rust
+// crates/mds-core/src/fs.rs
+// Default returns None — safe for VirtualFs / WASM.
+// NativeFs overrides: returns the path from init_root (walk-up from entry-point dir).
+fn source_root(&self) -> Option<String> {
+    None
+}
+```
+
+`VirtualFs` inherits the default (`None`). `NativeFs` overrides it to return the project root established by the walk-up from the entry-point directory's `normalize()` call.
+
+**Critical gotcha**: because `source_root()` is a *defaulted* method returning `None`, any external `FileSystem` implementor that forgets to override it silently lands on the `root = None` branch (step 6 above). That branch still enforces "never absolute, never drive-qualified" but skips the containment check. `resolver.rs` has a defense-in-depth guard for this:
+
+```rust
+// resolver.rs — at both finalize sites, before calling relativize_source:
+// Defense-in-depth: if root was not established yet, establish it now.
+// No-op for VirtualFs (source_root() always None, ctx.base_dir empty).
+if self.fs.source_root().is_none() && !ctx.base_dir.is_empty() {
+    let _ = self.fs.set_root(ctx.base_dir);
+}
+```
+
+## Technical Implementation Patterns
+
+### `source_path.rs` — the single choke-point
+
+`pub fn relativize_source(source: &str, base: Option<&Path>, root: Option<&Path>) -> String` in `crates/mds-core/src/source_path.rs` is the ONLY place where absolute source paths are converted to relative map entries. Re-exported from `crates/mds-core/src/lib.rs`. Called exactly twice — once per finalize site in `resolver.rs` — both calls unconditional.
+
+**Do not add a third call site.** The `PF-004` single-choke-point principle is what makes the security guarantee structural rather than incidental. Any new code path that emits `sources[]` entries must flow through this function.
+
+### `CompileOptions.source_map_base`
+
+```rust
+// crates/mds-core/src/sourcemap.rs
+#[derive(Debug, Clone, Default)]
+pub struct CompileOptions {
+    pub source_map: bool,
+    pub include_sources_content: bool,
+    pub source_map_base: Option<std::path::PathBuf>,  // new field (PR #196)
+}
+```
+
+`CompileOptions` does NOT carry `#[non_exhaustive]` (deliberately). That attribute would forbid struct-literal and `..Default::default()` construction from other crates, breaking all three bindings. Callers outside this crate that construct `CompileOptions` by field must use `..Default::default()` to stay forward-compatible.
+
+CLI sets `source_map_base = Some(compute_source_map_base(...))`. Bindings leave it `None`.
+
+### `compute_source_map_base` in `crates/mds-cli/src/build.rs`
+
+A pure pre-compile directory oracle. It mirrors the output-directory rules of `resolve_output_path_for_kind` without creating directories:
+
+```
+-o - or stdin → Some(cwd())
+-o <file>     → Some(abs(effective_parent(Path::new(output_file))))
+--out-dir <d> → Some(abs(dir))
+mds.json output_dir → Some(abs(config_dir.join(output_dir)))
+default       → Some(abs(effective_parent(input)))
+```
+
+**Must use `compute_output_dir_path_for_kind`, NOT `prepare_output_dir_for_kind`**: `prepare_output_dir_for_kind` calls `create_dir_all` and would leave an empty output directory behind if the compile fails. Directory-mode `opts` is built per-file so each file gets its own base.
+
+### `apply_source_map_file_label` in `crates/mds-cli/src/build.rs`
+
+The CLI's only post-`relativize_source` source-map work (renamed from `relativize_source_map_fields`). Two jobs only:
+1. `sm.file = output_basename` — the SMv3 `file` field names the generated artifact; core always emits `file: None`.
+2. `<stdin>` relabel: maps `STRING_SOURCE_MAP_LABEL` (`"input.mds"`) → `"<stdin>"` for stdin builds. This is a pure label swap — no path logic.
+
+The old `relativize_source_path` and `relative_path` CLI helpers are deleted. Everything path-related now happens inside `relativize_source`.
+
+### Cross-Surface Parity Tests
+
+Two differential tests enforce that surfaces agree with each other, not just with their own golden:
+
+- **`V-SM1`** (`packages/mds/__test__/source-map.spec.mjs`): WASM `compile()` with explicit filename + empty modules produces the same `sources[]` as native napi. Virtual keys are relative by construction — guards that `relativize_source`'s `root = None` branch does not accidentally mutate them.
+- **`CF-SM2`** (same file): napi, WASM, CLI, and Python all produce identical `sources[]` for a nested `@import` fixture. **Hard-fails in CI** (`process.env.CI`) if any surface is unavailable — a silently-skipped parity test reads as green and is worse than no test.
+
+In CI the JS job must:
+- Build `mds-cli` (Rust binary) before running the JS tests.
+- `pip install ./crates/mds-python` to supply the Python surface.
+- Expose `MDS_CLI_BIN` and `MDS_PYTHON_BIN` env vars so the test's surface-discovery logic finds them.
+
+## Anti-Patterns
+
+- **Adding a second call site for `sources[]` relativization**: The entire security guarantee rests on the single choke-point. A second inline call bypasses the 10-step guard algorithm partially or entirely.
+
+- **Using `Path::file_name()` on a raw source string as a basename fallback**: On Unix, `Path::file_name()` returns the entire string verbatim for paths like `..\..\Users\alice\secret.mds` (no `/` components). The correct fallback uses the last non-`..` component of the NORMALIZED component list after unification and lexical normalization.
+
+- **Treating `root = None` as "no security needed"**: The `root = None` branch (VirtualFs / WASM) still enforces "never absolute / never drive-qualified". Omitting those guards because "there is no root" is incorrect — the invariants must hold on all branches.
+
+- **Using `debug_assert!` to enforce path-containment invariants**: They are compiled out in release builds. All invariants in `source_path.rs` use `assert!` or runtime checks, never `debug_assert!` (avoids PF-005).
+
+- **Using `prepare_output_dir_for_kind` inside `compute_source_map_base`**: That function creates the directory on disk. `compute_source_map_base` is a pure oracle; it must never create directories.
+
+- **Adding `#[non_exhaustive]` to `CompileOptions`**: It would break all three binding crates' field-literal construction. Use `..Default::default()` in callers instead.
+
+## Gotchas
+
+**Windows verbatim UNC root** (`path_to_unified` fix): `std::fs::canonicalize` on Windows returns verbatim UNC paths (`\\?\C:\proj`). After `replace('\\', "/")` this becomes `//?/C:/proj`, and `normalize_abs` yields components `["?", "C:", "proj", ...]`. But the source path after the same treatment yields `["C:", "proj", ...]`. The prefix `"?"` causes the first-component comparison to fail → containment always fails → EVERY source map entry degrades to its basename. `path_to_unified` now strips `//?/UNC/` then `//?/` before normalizing, so root components match source components. This bug is invisible on Unix CI.
+
+**`source_root()` returns `None` before any `normalize()` call**: `NativeFs::source_root()` returns `None` until at least one `normalize()` or explicit `set_root()` call establishes the project root. The defense-in-depth guard in `resolver.rs` catches this, but external callers that skip `normalize()` and jump straight to `compile_with_deps_opts` will land on the `root = None` branch.
+
+**Directory-mode `opts` must be per-file**: In directory mode (`run_build_directory`), each file has a different output directory, so `source_map_base` differs per file. Constructing `opts` as loop-invariant (outside the per-file loop) would give every file the same anchor, producing incorrect relative paths for all but one file.
+
+**`sources[]` anchored to the MAP FILE location, per SMv3**: The CLI writing a sidecar map into `build/` legitimately yields `../src/x.mds` while bindings yield `src/x.mds`. Both are correct for their respective anchors. Do not normalize these to the same value when writing cross-surface parity tests — assert them each against their own expected value within CF-SM2, comparing the set across surfaces only when anchor offsets are controlled.
+
+**`STRING_SOURCE_MAP_LABEL` (`"input.mds"`)**: The internal sentinel for stdin source. Core canonicalizes the source entry at `MapBuilder::new` / `source_index`, so the exact-string check in `apply_source_map_file_label` always matches. Do not change the sentinel string without updating both the core constant and all three binding surface golden tests.
+
+**Rebuild stale binding artifacts before any cross-surface comparison**: Checked-in binding artifacts (`.node`, `.wasm`, Python wheel) can be stale. CF-SM2 tests the installed binaries. Rebuild before running cross-surface tests or you are testing an old binary.
+
+**pytest marker filter**: Use `pytest -m "not perf"`, never `pytest -k "not perf"`. The `-k` flag matches substrings of the full test node id and silently deselects test functions whose name merely contains "perf" (avoids PF-008).
+
+## Key Files
+
+- `crates/mds-core/src/source_path.rs` — `relativize_source` (the single choke-point; 10-step guard algorithm; `path_to_unified` with verbatim-prefix strip; `basename_fallback` using normalized components; `core_rule_map_relative` and `core_rule_source_outside_root` discriminating test pair)
+- `crates/mds-core/src/fs.rs:111-132` — `FileSystem::source_root()` (defaulted `None`; NativeFs override at line 522)
+- `crates/mds-core/src/resolver.rs:865-884, 943-963` — two finalize sites; both call `relativize_source` unconditionally; both include the defense-in-depth `set_root` guard
+- `crates/mds-core/src/sourcemap.rs:424-446` — `CompileOptions` struct (`source_map_base: Option<PathBuf>` at line 445); `SourceMap` struct carries `#[non_exhaustive]` (line 121), `CompileOptions` does not
+- `crates/mds-cli/src/build.rs:848-916` — `compute_source_map_base` (pure oracle; uses `compute_output_dir_path_for_kind`); `:932-` — `apply_source_map_file_label` (two-job post-processor: `sm.file` + `<stdin>` relabel)
+- `packages/mds/__test__/source-map.spec.mjs` — V-SM1 (WASM↔native virtual parity), CF-SM2 (four-surface differential test; hard-fails in CI if any surface missing)
+
+## Related
+
+- **ADR-005** (Source Map v3 generation): overall architecture decision; global-cursor `MapBuilder`; two-level anchoring (map-relative CLI, root-relative bindings); `MAX_SOURCEMAP_SEGMENTS=1M`; messages-mode yields `None`; SMv3 source paths are NEVER absolute.
+- **PF-004** (parallel-path enforcement): the single choke-point principle. All `sources[]` relativization must flow through `relativize_source`. No alternate path.
+- **PF-005** (security invariants must be unconditional, never `debug_assert!`): every guard in `source_path.rs` is a runtime check in release builds.
+- **PF-007** (per-surface goldens cannot catch cross-surface divergence): V-SM1 and CF-SM2 are the differential tests this pitfall required. CF-SM2 hard-fails in CI if any surface is unavailable.
+- **PF-008** (pytest `-k` vs `-m`): use `-m "not perf"` when running Python parity tests.
+- `.devflow/features/mds-lint/KNOWLEDGE.md` — lint's `atomic_write_file` (unrelated to source maps but shares `output.rs`).
+- `.devflow/features/mds-fmt/KNOWLEDGE.md` — fmt does not emit source maps (CLI-only), but shares `output.rs` and `effective_parent`.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index aafa980..34aa185 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -22,5 +22,5 @@ PR titles follow Conventional Commits (feat:, fix:, refactor:, chore:, docs:, ..
 - [ ] No new compiler/linter warnings
 - [ ] Source hygiene: `node scripts/verify-no-control-bytes.mjs` exits 0
 - [ ] **Before any `--admin` merge**: run `node scripts/verify-pr-checks.mjs <pr-number>`
-      and use the `gh pr merge --squash --match-head-commit <sha>` command it emits
+      and use the `gh pr merge --squash --admin --match-head-commit <sha>` command it emits
       (PF-017: a cancelled run reads as green without this check)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3ff1c2c..e17e1f2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -362,4 +362,4 @@ jobs:
       - name: Scan tracked source for hazardous codepoints
         run: node scripts/verify-no-control-bytes.mjs
       - name: Run positive-control and class-completeness suite
-        run: node --test scripts/__test__/*.spec.mjs
+        run: npm run test:gates
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5ff47a4..b35a98b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,13 +33,13 @@ jobs:
       # #288: Source-hygiene gate — also runs on tag pushes via this job.
       # ci.yml does not run on tag pushes, so these two steps ensure the full
       # gate (scanner + positive-control suite) is enforced at release time.
-      # The positive-control suite pins HAZARD_RANGES (D-CB1a) so a silently-
-      # narrowed hazard class cannot exit 0 on the release path (ADR-009/PF-013).
+      # test:gates enforces a minimum spec count (>=3) so the suite cannot
+      # be silently skipped on the release path (ADR-009/PF-013).
       # Uses the same Node 22 install above.
       - name: "Assert no hazardous codepoints in tracked source"
         run: node scripts/verify-no-control-bytes.mjs
       - name: "Run positive-control and class-completeness suite"
-        run: node --test scripts/__test__/*.spec.mjs
+        run: npm run test:gates
 
   # ---------------------------------------------------------------------------
   # A6 — cross-compile the native addon for all 7 targets.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d65d760..083c0ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -300,14 +300,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Pre-merge check verifier** (#289): `scripts/verify-pr-checks.mjs` guards
   against PF-017 (a cancelled CI run reads as "not failing" to `gh pr merge
-  --admin`). It evaluates three tiers: Tier A asserts every required
-  branch-protection context is `completed+success`; Tier B fails on any
-  non-required check-run that concluded
+  --admin`). It evaluates four tiers: Tier A asserts every required
+  branch-protection context is `completed+success`; Tier A+ (`EXPECTED_CONTEXTS`)
+  asserts locally-named jobs are present and passing regardless of branch
+  protection — absence is FAIL, not advisory (ADR-009, PF-013); Tier B fails on
+  any non-required check-run that concluded
   `failure/cancelled/timed_out/action_required/stale`; Tier C (legacy commit
-  statuses) is advisory. It emits a `gh pr merge --squash --match-head-commit
-  <sha>` command pinned to the verified SHA. Exit 0: Tier A and Tier B pass;
-  exit 1: any Tier A/B failure or zero check-runs found; exit 2:
-  tool/permission errors.
+  statuses) is advisory. It emits a `gh pr merge --squash --admin
+  --match-head-commit <sha>` command pinned to the verified SHA. Exit 0: Tier A,
+  Tier A+, and Tier B pass; exit 1: any Tier A, Tier A+, or Tier B failure, or
+  zero check-runs found; exit 2: tool/permission errors.
 
 
 ### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
index ccf141a..77e144c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,4 +49,4 @@ See @RELEASING.md for the full runbook.
 - Local Python dev: `maturin develop` needs an active **virtualenv** + `python3` on PATH; CI has no venv so it uses `pip install ./crates/mds-python` (the maturin PEP 517 backend). Wheels are `cp311-abi3` (one per platform)
 - `crates/mds-python` is free-threading ready (frozen result classes, `#[pymodule(gil_used = false)]`, GIL released around each compile); the `cp314t` free-threaded wheel is a separate ABI and is deferred with the wheel matrix + PyPI publishing (follow-up to #132)
 - **Source hygiene gate** (#288): `node scripts/verify-no-control-bytes.mjs` scans tracked source for hazardous codepoints (C0, C1, bidi, BOM). BSD grep has no `-P` (exits 2, empty output reads as clean) — never use grep to verify absence of control bytes; the gate uses pure Node codepoint iteration. When writing codepoints in source or docs, use numeric notation (U+202E, 0x202e) rather than `\uXXXX` escapes — the edit tooling decodes 4-hex `\uXXXX` to live bytes (PF-018).
-- **Pre-merge check verifier** (#289, PF-017): a CANCELLED GitHub Actions run reads as "not failing" to `gh pr merge --admin`, which can merge an unverified head. Before any `--admin` merge, run `node scripts/verify-pr-checks.mjs <pr-number>` and use the `gh pr merge --squash --match-head-commit <sha>` command it emits. This verifies all required contexts are `completed+success` and pins the SHA.
+- **Pre-merge check verifier** (#289, PF-017): a CANCELLED GitHub Actions run reads as "not failing" to `gh pr merge --admin`, which can merge an unverified head. Before any `--admin` merge, run `node scripts/verify-pr-checks.mjs <pr-number>` and use the `gh pr merge --squash --admin --match-head-commit <sha>` command it emits verbatim. This verifies all required contexts are `completed+success` and pins the SHA.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f151a40..b6f731b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -65,7 +65,10 @@ MDS_BACKEND=wasm   npm test -w @mdscript/mds
 ### Source hygiene
 
 All tracked source must be free of hazardous codepoints. The gate runs
-automatically in CI (`source-hygiene` job) and can be run locally:
+automatically in CI (job key `source-hygiene`, display name `Source hygiene`;
+`scripts/verify-pr-checks.mjs` matches on the display name — renaming it in
+`ci.yml` requires updating `EXPECTED_CONTEXTS` in that script) and can be run
+locally:
 
 ```bash
 node scripts/verify-no-control-bytes.mjs          # full tracked-tree scan
@@ -78,6 +81,13 @@ for non-vacuity), `1` hazard found or scan failed closed (zero files scanned,
 unreadable path, stale allowlist entry, git not on PATH), `2` indeterminate
 (a git subcommand failed unexpectedly — never treat `2` as clean).
 
+Note on exit-code symmetry: the scanner folds a missing `git` executable into
+its fail-closed exit 1 (a known, named failure — the tool can say definitively
+it could not run), whereas the verifier (`verify-pr-checks.mjs`) treats a missing
+or outdated `gh` as indeterminate exit 2 (the tool cannot assess merge safety).
+Both refuse to report success; they differ in whether tool absence is a named
+failure (exit 1) or an indeterminate error (exit 2).
+
 **Opt-in pre-commit hook** (replaces `.git/hooks` wholesale — document your
 existing local hooks before enabling):
 
@@ -124,30 +134,44 @@ node scripts/verify-pr-checks.mjs <pr-number>
 
 The verifier reads required contexts from live branch protection, checks that
 every context is `status=completed` AND `conclusion=success`, and on pass
-emits a `gh pr merge --squash --match-head-commit <sha>` command pinned to
-the verified SHA (closes the TOCTOU window).
-
-Exit codes are a contract: `0` all Tier A and Tier B checks passed, `1` any
-Tier A failure (required context missing or non-success), any Tier B failure
-(non-required check-run concluded failure/cancelled/timed_out/action_required/
-stale), or zero check-runs found, `2` the tool could not tell (protection
-unreadable, no required contexts configured, `gh` older than 2.31, incomplete
-pagination). **Only `0` means verified** — never read `2` as a pass.
-
-Tier B is load-bearing: `source-hygiene` is not among `main`'s required
-branch-protection contexts, so Tier B is the sole mechanism that makes a
-failing `source-hygiene` run block an `--admin` merge.
+emits a `gh pr merge --squash --admin --match-head-commit <sha>` command pinned
+to the verified SHA (closes the TOCTOU window). Copy it verbatim — hand-editing
+the command is where `--match-head-commit` gets dropped.
+
+Exit codes are a contract: `0` all Tier A, Tier A+, and Tier B checks passed,
+`1` any Tier A failure (required context missing or non-success), any Tier A+
+failure (a job listed in `EXPECTED_CONTEXTS` is absent or non-success), any
+Tier B failure (non-required check-run concluded
+failure/cancelled/timed_out/action_required/stale), or zero check-runs found,
+`2` the tool could not tell (protection unreadable, no required contexts
+configured, `gh` older than 2.31, incomplete pagination). **Only `0` means
+verified** — never read `2` as a pass.
+
+Tier A+ is the binding mechanism for the `Source hygiene` gate: the CI job key
+is `source-hygiene` (ci.yml), but its display name — `Source hygiene` — is what
+GitHub reports as the check-run name and what `EXPECTED_CONTEXTS` in
+`scripts/verify-pr-checks.mjs` matches. The job is not among `main`'s required
+branch-protection contexts. Tier B alone cannot make it binding: Tier B only
+iterates check-runs that already exist in the check-run list — an absent job has
+nothing to iterate. Tier A+ (`EXPECTED_CONTEXTS`) closes this gap by asserting
+presence and passing with the same semantics as Tier A, so an absent, renamed,
+or pre-start-cancelled `Source hygiene` run is FAIL, not a pass (applies
+ADR-009, avoids PF-013). Tier B still applies when the run exists but concluded
+badly. **Renaming the display `name:` in `ci.yml` requires updating
+`EXPECTED_CONTEXTS` in `scripts/verify-pr-checks.mjs` to match.**
 
 Scope, stated so it is not assumed: the verifier checks the checks *on one
 commit*. It does **not** assert that the head is up to date with the base
 branch, so a stale-but-green head can still be merged under `--admin` even
 after the verifier passes. Keep the branch rebased. It does **not** assert that
 `source-hygiene` is a required context — `--admin` bypasses required-status
-enforcement outright for non-required checks, and Tier B is the binding
-mechanism. Tier B skips non-required check-runs still `queued` or `in_progress`:
-a verifier pass issued while `source-hygiene` is still running has verified
-nothing about source hygiene. Ensure all jobs have completed before running the
-verifier.
+enforcement outright for non-required checks, so Tier A+ (`EXPECTED_CONTEXTS`)
+and Tier B are complementary binding mechanisms for non-required jobs — Tier A+
+covers absent and renamed jobs (Tier B cannot: it only iterates existing
+check-runs); Tier B covers existing runs that concluded badly. Tier B fails on
+non-required check-runs that are still `queued` or `in_progress` — a
+non-completed run is not evidence of success (avoids PF-017). Ensure all jobs
+have completed before running the verifier.
 
 If the base branch is unprotected (e.g. a wave branch), supply `--required-from`:
 
diff --git a/RELEASING.md b/RELEASING.md
index e32f3c2..847c370 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -68,7 +68,8 @@ grep -rn 'since = ' crates/ --include='*.rs'
 node scripts/verify-no-control-bytes.mjs
 npm run test:gates                           # positive-control spec suite
 # Before any --admin merge (PF-017 guard — cancelled runs read as green):
-node scripts/verify-pr-checks.mjs <pr-number>
+PR_NUMBER=NNN  # replace NNN with the bump PR number
+node scripts/verify-pr-checks.mjs "$PR_NUMBER"
 
 # Packaging spot-check (inspect tarball contents)
 npm pack -w @mdscript/mds --dry-run
@@ -108,11 +109,12 @@ The release is driven by pushing a `vX.Y.Z` tag. This is how all versions have s
    ```
    On exit 0 the script prints the exact merge command — copy and run it verbatim:
    ```bash
-   gh pr merge --squash --match-head-commit <headSha>
+   gh pr merge --squash --admin --match-head-commit <headSha>
    ```
-   (`main` is protected; the sole code-owner can't self-approve so `--admin` is
-   required. `--match-head-commit` closes the TOCTOU window between verification
-   and merge.)
+   (`--admin` is required because `main` is protected and the sole code-owner
+   cannot self-approve. `--match-head-commit` closes the TOCTOU window between
+   verification and merge. Both flags are emitted by the script — copy the
+   printed command without modification.)
 3. **Tag the merged commit and push:**
    ```bash
    git tag -a vX.Y.Z -m vX.Y.Z
diff --git a/package.json b/package.json
index 2362a57..837ea9d 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,6 @@
   "workspaces": ["packages/*", "crates/mds-napi"],
   "engines": { "node": ">=22.0.0" },
   "scripts": {
-    "test:gates": "node --test scripts/__test__/*.spec.mjs"
+    "test:gates": "count=$(ls scripts/__test__/*.spec.mjs 2>/dev/null | wc -l | tr -d '[:space:]'); [ \"$count\" -ge 3 ] || { echo 'expected >=3 spec files, found '$count' -- refusing a vacuous pass (ADR-009/PF-013)' >&2; exit 1; }; node --test scripts/__test__/*.spec.mjs"
   }
 }
diff --git a/scripts/__test__/verify-no-control-bytes.spec.mjs b/scripts/__test__/verify-no-control-bytes.spec.mjs
index 01c8679..86678f1 100644
--- a/scripts/__test__/verify-no-control-bytes.spec.mjs
+++ b/scripts/__test__/verify-no-control-bytes.spec.mjs
@@ -13,7 +13,7 @@
 
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, writeFileSync, rmSync, readFileSync, symlinkSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, readdirSync, symlinkSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawnSync, execFileSync } from 'node:child_process';
@@ -240,6 +240,46 @@ describe('AC-7 AC-8 AC-9: positive controls and clean-file checks', () => {
     } finally { cleanup(dir); }
   });
 
+  test('AC-7 PC-6: planted U+FEFF (BOM) at offset 0 → exits 1 naming U+FEFF', () => {
+    // U+FEFF is the most likely codepoint to be special-cased by a future
+    // change to the decoder (BOM-stripping is a common optimization) and must
+    // therefore be exercised end-to-end through the full decode → predicate →
+    // report pipeline, not only via the table-driven isHazardous unit tests.
+    //
+    // UTF-8 encoding of U+FEFF: 0xEF 0xBB 0xBF (3 bytes).
+    // Bytes constructed at runtime from hex — no backslash-u escape (PF-018).
+    const { dir, git } = mkTempGitRepo();
+    try {
+      const bom = Buffer.from([0xef, 0xbb, 0xbf]);
+      writeFileSync(join(dir, 'bom.mjs'), Buffer.concat([bom, Buffer.from('export const x = 1;')]));
+      git('add', 'bom.mjs');
+      const r = runScanner([], { cwd: dir });
+      assert.equal(r.status, 1, 'scanner must exit 1 on U+FEFF (BOM) at offset 0');
+      assert.ok(r.stderr.includes('bom.mjs'), 'error must name the file');
+      assert.ok(r.stderr.includes('U+FEFF'), 'error must include U+FEFF codepoint');
+    } finally { cleanup(dir); }
+  });
+
+  test('AC-7 PC-7: planted U+2028 (Line Separator) mid-file → exits 1 naming U+2028', () => {
+    // U+2028 (LINE SEPARATOR) is the second codepoint most likely to be
+    // special-cased by a future change to scanBuffer (it looks like a line
+    // break and some decoders treat it as whitespace).  Exercise it
+    // end-to-end through the full pipeline.
+    //
+    // UTF-8 encoding of U+2028: 0xE2 0x80 0xA8 (3 bytes).
+    // Bytes constructed at runtime from hex — no backslash-u escape (PF-018).
+    const { dir, git } = mkTempGitRepo();
+    try {
+      const ls = Buffer.from([0xe2, 0x80, 0xa8]);
+      writeFileSync(join(dir, 'ls.md'), Buffer.concat([Buffer.from('before'), ls, Buffer.from('after')]));
+      git('add', 'ls.md');
+      const r = runScanner([], { cwd: dir });
+      assert.equal(r.status, 1, 'scanner must exit 1 on U+2028 (Line Separator) mid-file');
+      assert.ok(r.stderr.includes('ls.md'), 'error must name the file');
+      assert.ok(r.stderr.includes('U+2028'), 'error must include U+2028 codepoint');
+    } finally { cleanup(dir); }
+  });
+
   test('AC-9 NEG-1: clean international text (accented Latin, CJK, emoji) → exits 0', () => {
     const { dir, git } = mkTempGitRepo();
     try {
@@ -321,11 +361,16 @@ describe('AC-11: git ls-files discovery path', () => {
       // Remove from git tracking (but keep on disk as untracked)
       git('rm', '--cached', 'tracked.md');
       const r2 = runScanner([], { cwd: dir });
-      // With zero tracked files, non-vacuity guard fires (exit 1) — which is correct.
-      // The scanner proves it reads the tracked set: the hostile file is on disk but untracked.
-      // If it read the working tree, it would still find the hostile byte even after `git rm --cached`.
-      // Since zero tracked files → non-vacuity exit 1, we know the scanner used git ls-files.
-      // To confirm: add a clean file and verify the scanner passes.
+      // Zero tracked files → non-vacuity guard fires (exit 1), proving the scanner
+      // reads the git-tracked set rather than the working tree directory.
+      // The hostile file is still on disk but is now untracked; a working-tree
+      // scanner would still find it and exit 1 for the wrong reason.
+      assert.equal(r2.status, 1, 'zero tracked files (hostile file on disk but untracked) → non-vacuity guard exits 1');
+      assert.ok(
+        r2.stderr.includes('zero files scanned') || r2.stderr.includes('empty scan'),
+        `non-vacuity message must mention zero files; got: ${r2.stderr}`
+      );
+      // Add a clean tracked file; hostile file is still on disk but untracked.
       writeFileSync(join(dir, 'clean.md'), 'clean content\n');
       git('add', 'clean.md');
       const r3 = runScanner([], { cwd: dir });
@@ -372,12 +417,13 @@ describe('AC-5 AC-6: full-tree scan and non-vacuity', () => {
     } finally { cleanup(dir); }
   });
 
-  test('AC-6 --staged: no staged content (amend/nothing staged) → exits 0 with explicit message', () => {
-    // D-CB5's non-vacuity guard applies to full-tree mode only. In --staged mode
-    // an empty ACMR-filtered set is a legitimate state — `git commit --amend
-    // --no-edit` and `--allow-empty` produce exactly this. Exiting 1 here blocks
-    // valid commits and trains contributors to reach for --no-verify, which
-    // disables the gate for ALL commits. Fix: exit 0 with an explicit message.
+  test('D-CB5 --staged carve-out from AC-6: no staged content (amend/nothing staged) → exits 0 with explicit message', () => {
+    // AC-6 requires exit 1 when the scanned file set is empty in FULL-TREE mode.
+    // --staged mode has an explicit carve-out: an empty ACMR-filtered set is a
+    // LEGITIMATE state — `git commit --amend --no-edit` and `--allow-empty`
+    // produce exactly this. Exiting 1 here blocks valid commits and trains
+    // contributors to reach for --no-verify, which disables the gate for ALL
+    // commits. Documented exception: exit 0 with an explicit message.
     const { dir } = mkTempGitRepo();
     try {
       // Nothing staged — `git diff --cached` returns empty.
@@ -390,10 +436,12 @@ describe('AC-5 AC-6: full-tree scan and non-vacuity', () => {
     } finally { cleanup(dir); }
   });
 
-  test('AC-6 --staged: deletion-only commit → exits 0 with deletion count', () => {
-    // A commit that removes files only (git rm) yields zero ACMR-filtered paths
-    // because D = deletion is excluded from the ACMR filter. The scanner must
-    // exit 0, not 1. D-CB5 non-vacuity applies to full-tree mode only.
+  test('D-CB5 --staged carve-out from AC-6: deletion-only commit → exits 0 with deletion count', () => {
+    // AC-6 requires exit 1 when the scanned file set is empty in FULL-TREE mode.
+    // --staged mode carve-out: a commit that removes files only (git rm) yields
+    // zero ACMR-filtered paths because D = deletion is excluded from the ACMR
+    // filter. The scanner must exit 0, not 1. D-CB5 non-vacuity applies to
+    // full-tree mode only.
     const { dir, git } = mkTempGitRepo();
     try {
       // Commit a clean file, then stage its deletion
@@ -411,6 +459,55 @@ describe('AC-5 AC-6: full-tree scan and non-vacuity', () => {
     } finally { cleanup(dir); }
   });
 
+  test('D-CB5 --staged carve-out from AC-6: amend-message-only (prior commit + nothing newly staged) → exits 0', () => {
+    // Regression for the empirically-confirmed bug: `git commit --amend -m "..."` was
+    // rejected with exit 1 by the pre-commit hook. During a message-only amend the
+    // index is identical to HEAD, so `git diff --cached --diff-filter=ACMR` returns
+    // zero paths. The non-vacuity guard (D-CB5) MUST NOT fire in --staged mode for
+    // this legitimate git state.
+    //
+    // This test uses a repo with a real prior commit (unlike the fresh-repo test above)
+    // to faithfully simulate the amend scenario where HEAD exists.
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // Establish a prior commit — this is the HEAD that an amend would rewrite.
+      writeFileSync(join(dir, 'initial.md'), 'initial content\n');
+      git('add', 'initial.md');
+      git('commit', '-m', 'initial commit');
+      // Index == HEAD: `git diff --cached` returns nothing. Simulates --amend -m.
+      const r = runScanner(['--staged'], { cwd: dir });
+      assert.equal(r.status, 0,
+        '--staged with index == HEAD must exit 0 (amend -m "..." is a valid workflow)');
+      assert.ok(
+        r.stdout.includes('nothing to scan') || r.stdout.includes('no staged'),
+        `stdout must explain why scanning was skipped; got: ${r.stdout}`
+      );
+    } finally { cleanup(dir); }
+  });
+
+  test('D-CB5 --staged carve-out from AC-6: allow-empty commit (nothing staged, prior commit) → exits 0', () => {
+    // Regression for the empirically-confirmed bug: `git commit --allow-empty` was
+    // rejected with exit 1 by the pre-commit hook. An allow-empty commit intentionally
+    // carries no staged content; `git diff --cached --diff-filter=ACMR` returns zero
+    // paths, which is a LEGITIMATE state. The scanner must exit 0 with an explicit
+    // message so the contributor knows the gate ran and found nothing to check.
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // Establish a prior commit so HEAD exists (matching typical allow-empty usage).
+      writeFileSync(join(dir, 'initial.md'), 'initial content\n');
+      git('add', 'initial.md');
+      git('commit', '-m', 'initial commit');
+      // Nothing staged — simulates `git commit --allow-empty`.
+      const r = runScanner(['--staged'], { cwd: dir });
+      assert.equal(r.status, 0,
+        '--staged with nothing staged must exit 0 (allow-empty is a valid workflow)');
+      assert.ok(
+        r.stdout.includes('nothing to scan') || r.stdout.includes('no staged'),
+        `stdout must explain why scanning was skipped; got: ${r.stdout}`
+      );
+    } finally { cleanup(dir); }
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -512,6 +609,40 @@ describe('AC-18: --staged mode reads index blob, not working tree', () => {
     } finally { cleanup(dir); }
   });
 
+  test('Case C: type-change (T) staged blob with hostile content exits 1 (ACMRT positive control)', () => {
+    // A git type-change (T) occurs when a tracked symlink is replaced by a regular
+    // file (or vice versa) and the result is staged.  --diff-filter=ACMR excludes T,
+    // which silently bypasses the pre-commit hook for any hostile content in that blob.
+    // D-CB5b fix: --diff-filter=ACMRT captures T-type changes for scanning.
+    //
+    // This test is the positive control required by ADR-009 / PF-013: it proves the
+    // scanner DETECTS hostile content in a T-type staged blob.
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // 1. Commit a symlink (mode 120000) so victim.md is tracked as a symlink.
+      writeFileSync(join(dir, 'target.txt'), 'clean target\n');
+      symlinkSync('target.txt', join(dir, 'victim.md'));
+      git('add', 'target.txt', 'victim.md');
+      git('commit', '-m', 'add symlink');
+
+      // 2. Replace the symlink with a regular file containing ESC (0x1B).
+      //    rmSync removes the symlink inode; writeFileSync creates a regular file.
+      rmSync(join(dir, 'victim.md'));
+      const esc = Buffer.from([0x1b]); // ESC constructed at runtime, not a literal (PF-018)
+      writeFileSync(join(dir, 'victim.md'), Buffer.concat([Buffer.from('evil '), esc]));
+      // git add produces T (type-change): victim.md was symlink (120000), now regular (100644)
+      git('add', 'victim.md');
+
+      // Pre-delta (ACMR filter): would exit 0, silently passing a hostile blob.
+      // Post-fix (ACMRT filter): blob is scanned and exits 1.
+      const r = runScanner(['--staged'], { cwd: dir });
+      assert.equal(r.status, 1,
+        'T-type staged change (symlink to file) with hostile ESC must exit 1 (ACMRT positive control)');
+      assert.ok(r.stderr.includes('victim.md'), `error must name the file; got: ${r.stderr}`);
+      assert.ok(r.stderr.includes('U+001B'), `error must name U+001B; got: ${r.stderr}`);
+    } finally { cleanup(dir); }
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -540,15 +671,30 @@ describe('AC-15: scanner source is self-clean', () => {
     // The forbidden grep invocation is 'grep' joined with ' -P'; split here so
     // the contiguous substring is absent from this source file.
     const grepPFlag = 'grep' + ' -P';
-    // 0x5C = backslash, then 'u' and 4 hex digits:
+    // 0x5C = backslash. Doubling it (bs + bs) yields two backslash chars as a
+    // string value; the RegExp constructor interprets that pair as an escaped
+    // literal backslash, producing /\\u[0-9a-fA-F]{4}/ — a pattern that matches
+    // an actual backslash followed by 'u' and four hex digits. A single bs would
+    // compile to /\u[0-9a-fA-F]{4}/ where \u is an Annex-B identity escape and
+    // matches bare 'u' — the false-positive trap identified in review finding #4.
     const bs = String.fromCodePoint(0x5c);
-    const bsUPattern = new RegExp(bs + 'u[0-9a-fA-F]{4}');
-
+    const bsUPattern = new RegExp(bs + bs + 'u[0-9a-fA-F]{4}');
+
+    // Auto-discover all spec files so new files added to scripts/__test__/ are
+    // automatically covered. A hardcoded list silently under-covers when files
+    // are added (the gap that let code-of-conduct.spec.mjs escape — review
+    // findings #1/#2). A minimum-count assertion catches accidental narrowing.
+    const specFiles = readdirSync(join(ROOT, 'scripts/__test__'))
+      .filter(f => f.endsWith('.spec.mjs'))
+      .map(f => `scripts/__test__/${f}`);
+    assert.ok(
+      specFiles.length >= 3,
+      `expected at least 3 spec files in scripts/__test__; got ${specFiles.length}: ${specFiles.join(', ')}`,
+    );
     const fileSet = [
       'scripts/verify-no-control-bytes.mjs',
       'scripts/verify-pr-checks.mjs',
-      'scripts/__test__/verify-no-control-bytes.spec.mjs',
-      'scripts/__test__/verify-pr-checks.spec.mjs',
+      ...specFiles,
       'scripts/hooks/pre-commit',
     ];
 
@@ -569,17 +715,26 @@ describe('AC-15: scanner source is self-clean', () => {
 
 // ---------------------------------------------------------------------------
 // AC-30: hex context stored per hit as a pre-computed string, not as the raw
-//        buffer — one-file-at-a-time memory discipline, verified by code shape.
+//        buffer — hazardHits never retains file buffers; verified by code shape.
 //
 // AC-30 has three clauses:
 //   (a) Wall-clock full-tree scan < 5 s — asserted with Date.now() in the
 //       AC-5 test above (generous CI-safe bound).
-//   (b) --staged mode < 2 s for a 20-file commit — not directly timed here;
-//       the same structural bound holds (git cat-file reads one blob at a time).
-//   (c) MUST NOT hold more than one file's contents in memory at a time —
-//       verified by code shape: at verify-no-control-bytes.mjs:473,
+//   (b) --staged mode < 2 s for a 20-file commit — not directly timed here.
+//       NOTE: readAllIndexBlobs() collapses N per-file `git cat-file blob`
+//       spawns into ONE `git cat-file --batch` call. The entire staged set is
+//       materialized into a single r.stdout buffer; out.slice(pos, pos+size)
+//       returns Buffer views that pin that buffer. --staged mode therefore holds
+//       all staged file contents in memory simultaneously, bounded by the 256 MB
+//       maxBuffer cap (r.error -> exit 2). This is a known trade-off (spawn cost
+//       vs memory) that was accepted when readAllIndexBlobs() replaced readIndexBlob().
+//   (c) hazardHits MUST NOT retain file buffers — verified by code shape:
 //       hazardHits.push stores { hexCtx } (a pre-computed string) not { buf }
-//       (the raw buffer), so the buffer is GC-eligible after each iteration.
+//       (the raw buffer). In full-tree mode buf is GC-eligible after each loop
+//       iteration. In --staged mode buf is a view into the already-pinned blobMap
+//       buffer (clause b), so GC-eligibility at the hazardHits level is academic
+//       there — but the key property holds: hazardHits does NOT additionally
+//       retain file buffers.
 //
 // This describe block tests clause (c) indirectly: by proving the correct
 // hexCtx string reaches the output across multiple files, it demonstrates
@@ -590,10 +745,13 @@ describe('AC-30: hex context stored as string per hit, not as file buffer', () =
 
   test('scanner reports hex context for every hazard across multiple files', () => {
     // Verify that hexCtx is computed and stored correctly for each hit.
-    // Memory discipline (clause c) is by code shape: hazardHits stores { hexCtx }
-    // not { buf } (scanner:473), so buf is GC-eligible after each file's iteration.
-    // This test proves the correct context string reaches the output regardless
-    // of how many files are scanned.
+    // Memory discipline (clause c) is by code shape: hazardHits.push stores
+    // { hexCtx } (a pre-computed string) not { buf } (the raw buffer), so buf
+    // is not additionally retained in hazardHits. In full-tree mode buf is
+    // GC-eligible after each iteration; in --staged mode buf is a view into
+    // the blobMap buffer (all blobs held simultaneously per clause b). This
+    // test proves the correct context string reaches the output regardless of
+    // how many files are scanned.
     const { dir, git } = mkTempGitRepo();
     try {
       // Construct two files each with an ESC at a known position
@@ -707,6 +865,89 @@ describe('AC-17: allowlist entries are self-invalidating', () => {
     } finally { cleanup(dir); }
   });
 
+  /**
+   * D-CB6a: staleness is a whole-tree claim, so it is adjudicated in full-tree
+   * mode only. --staged scans a SUBSET; judging staleness there reports every
+   * allowlisted file the commit did not happen to touch as "no longer tracked"
+   * and rejects the commit. That would make the pre-commit hook unusable from
+   * the first legitimate allowlist entry onward and push contributors to
+   * --no-verify, which disables the gate for ALL commits.
+   *
+   * Case 4 is paired with an explicit positive control (Case 5) so the fix
+   * cannot be satisfied by simply deleting the staleness check
+   * (applies ADR-009, avoids PF-013).
+   */
+  test('Case 4: --staged does not misreport an untouched allowlisted file as stale', () => {
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // evil.md carries its declared hazard and stays tracked but UNTOUCHED
+      // by the staged change.
+      writeFileSync(join(dir, 'evil.md'), Buffer.concat([Buffer.from('x '), Buffer.from([0x1b])]));
+      writeFileSync(join(dir, 'notes.md'), 'first\n');
+      const target = writePatchedScanner(dir, "{ path: 'evil.md', codepoints: [0x1b], reason: 'test fixture' }");
+      git('add', 'evil.md', 'notes.md', 'scan.mjs');
+      git('commit', '-m', 'init');
+
+      // Stage an edit to a DIFFERENT, clean file — the ordinary commit shape.
+      writeFileSync(join(dir, 'notes.md'), 'second\n');
+      git('add', 'notes.md');
+
+      const r = spawnSync(process.execPath, [target, '--staged'],
+        { cwd: dir, encoding: 'utf8', timeout: 30000 });
+      assert.equal(r.status, 0,
+        'a commit that does not touch the allowlisted file must not be rejected; ' +
+        `stdout: ${r.stdout} stderr: ${r.stderr}`);
+      assert.ok(!/stale/.test(r.stderr),
+        `evil.md is still tracked, so "stale" is a false claim; got: ${r.stderr}`);
+    } finally { cleanup(dir); }
+  });
+
+  test('Case 5 (positive control): the same entry IS reported stale by the full-tree scan', () => {
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // Identical patched scanner and identical entry as Case 4 — but here
+      // evil.md is genuinely absent, so full-tree mode must still catch it.
+      // Without this control, Case 4 would also pass if staleness detection
+      // were removed outright rather than scoped to full-tree mode.
+      writeFileSync(join(dir, 'notes.md'), 'first\n');
+      const target = writePatchedScanner(dir, "{ path: 'evil.md', codepoints: [0x1b], reason: 'test fixture' }");
+      git('add', 'notes.md', 'scan.mjs');
+
+      const r = runPatched(dir, target);
+      assert.equal(r.status, 1, 'full-tree mode must still adjudicate staleness');
+      assert.ok(r.stderr.includes('stale'), `must identify the entry as stale; got: ${r.stderr}`);
+      assert.ok(r.stderr.includes('evil.md'), 'must name the stale path');
+    } finally { cleanup(dir); }
+  });
+
+  test('Case 6: --staged still SUPPRESSES an allowlisted hazard in a staged file', () => {
+    const { dir, git } = mkTempGitRepo();
+    try {
+      // Suppression is path-keyed and unaffected by D-CB6a: staging the
+      // allowlisted file itself must still pass, while an identical hazard in a
+      // NON-allowlisted staged file must still fail (the discriminating half).
+      writeFileSync(join(dir, 'notes.md'), 'first\n');
+      const target = writePatchedScanner(dir, "{ path: 'evil.md', codepoints: [0x1b], reason: 'test fixture' }");
+      git('add', 'notes.md', 'scan.mjs');
+      git('commit', '-m', 'init');
+
+      writeFileSync(join(dir, 'evil.md'), Buffer.concat([Buffer.from('x '), Buffer.from([0x1b])]));
+      git('add', 'evil.md');
+      const allowed = spawnSync(process.execPath, [target, '--staged'],
+        { cwd: dir, encoding: 'utf8', timeout: 30000 });
+      assert.equal(allowed.status, 0,
+        `an allowlisted staged file must pass; stdout: ${allowed.stdout} stderr: ${allowed.stderr}`);
+
+      writeFileSync(join(dir, 'other.md'), Buffer.concat([Buffer.from('x '), Buffer.from([0x1b])]));
+      git('add', 'other.md');
+      const denied = spawnSync(process.execPath, [target, '--staged'],
+        { cwd: dir, encoding: 'utf8', timeout: 30000 });
+      assert.equal(denied.status, 1,
+        'the same hazard in a NON-allowlisted staged file must still fail');
+      assert.ok(denied.stderr.includes('other.md'), `must name the offending path; got: ${denied.stderr}`);
+    } finally { cleanup(dir); }
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -761,6 +1002,65 @@ describe('AC-20: symlinks are skipped and counted, not read', () => {
     } finally { cleanup(dir); }
   });
 
+  test('AC-20: a staged gitlink (mode 160000) is skipped in --staged mode, not reported as an error', () => {
+    // Regression test for the pre-fix bug: without mode-aware skip in getStagedFiles(),
+    // a staged gitlink (submodule) would reach readAllIndexBlobs(), and
+    // `git cat-file --batch` would return 'missing' (gitlinks store a commit SHA,
+    // not a blob), causing exit 2 with the misleading message
+    // "staged path not in index: <submodule-name>".
+    //
+    // Fix (D-CB5a): getStagedFiles() now uses `git diff --cached --raw -z`
+    // to obtain the new-file mode for each staged entry. Entries with new-mode
+    // 160000 (gitlink) are marked skip:true before they reach readAllIndexBlobs(),
+    // consistent with full-tree mode's AC-20 behavior.
+    //
+    // A real commit SHA is required because git validates the SHA format when
+    // updating the index via --cacheinfo. We harvest a SHA from a sibling temp
+    // repo to avoid network access and keep the test hermetic.
+    const { dir, git } = mkTempGitRepo();
+    const innerDir = mkdtempSync(join(tmpdir(), 'mds-inner-'));
+    try {
+      // Create an inner repo and commit one file to get a real commit SHA.
+      execFileSync('git', ['init'], { cwd: innerDir, stdio: 'pipe' });
+      execFileSync('git', ['config', 'user.email', 'test@test.test'], { cwd: innerDir, stdio: 'pipe' });
+      execFileSync('git', ['config', 'user.name', 'Test'], { cwd: innerDir, stdio: 'pipe' });
+      writeFileSync(join(innerDir, 'inner.md'), 'inner\n');
+      execFileSync('git', ['add', 'inner.md'], { cwd: innerDir, stdio: 'pipe' });
+      execFileSync('git', ['commit', '-m', 'inner'], { cwd: innerDir, stdio: 'pipe' });
+      const innerSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: innerDir, encoding: 'utf8', stdio: 'pipe',
+      }).trim();
+
+      // Stage a clean regular file alongside a gitlink (mode 160000) in the outer repo.
+      // `git update-index --cacheinfo 160000,<sha>,<path>` injects a gitlink entry
+      // directly into the index without requiring a real .gitmodules or disk presence.
+      writeFileSync(join(dir, 'clean.md'), 'clean content\n');
+      git('add', 'clean.md');
+      execFileSync('git', [
+        'update-index', '--add', '--cacheinfo', `160000,${innerSha},sub`,
+      ], { cwd: dir, stdio: 'pipe' });
+
+      // Confirm the gitlink is actually in the index at mode 160000.
+      const modes = execFileSync('git', ['ls-files', '-s'], { cwd: dir, encoding: 'utf8' });
+      assert.ok(modes.includes('160000'), 'fixture must actually stage a gitlink at mode 160000');
+
+      // --staged mode: the gitlink must be skipped (not cause an error), and the
+      // regular file must be scanned and pass.
+      const r = runScanner(['--staged'], { cwd: dir });
+      assert.equal(r.status, 0,
+        `staged gitlink must be skipped without error; stderr: ${r.stderr}`);
+      // The success output must report the skipped gitlink count.
+      assert.ok(r.stdout.includes('symlink/gitlink skipped'),
+        `output must report the skipped gitlink; got: ${r.stdout}`);
+      // The regular file must be scanned (not silently dropped with the gitlink).
+      assert.ok(/Scanned 1 file\(s\)/.test(r.stdout),
+        `must scan the one regular file; got: ${r.stdout}`);
+    } finally {
+      cleanup(dir);
+      cleanup(innerDir);
+    }
+  });
+
 });
 
 // ---------------------------------------------------------------------------
diff --git a/scripts/__test__/verify-pr-checks.spec.mjs b/scripts/__test__/verify-pr-checks.spec.mjs
index 4f6a379..4290617 100644
--- a/scripts/__test__/verify-pr-checks.spec.mjs
+++ b/scripts/__test__/verify-pr-checks.spec.mjs
@@ -18,7 +18,14 @@ import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
-import { evaluateChecks, main, fetchRequiredContexts } from '../verify-pr-checks.mjs';
+import {
+  evaluateChecks,
+  main,
+  fetchRequiredContexts,
+  fetchStatuses,
+  parseGhStderrHttpStatus,
+  EXPECTED_CONTEXTS,
+} from '../verify-pr-checks.mjs';
 
 const ROOT = resolve(fileURLToPath(import.meta.url), '../../..');
 const FIXTURES = join(ROOT, 'scripts/__test__/fixtures');
@@ -54,14 +61,22 @@ const HEAD_113F472 = '113f472684d6ee7e398d54c1aadc22b2ad747ae1';
 const HEAD_F168944 = 'f168944'; // PR #239
 const HEAD_E9DACE1 = 'e9dace1'; // PR #240
 
+// A synthetic Source hygiene run (D-PR3b). The 113f472 fixture predates the
+// source-hygiene job (#288); tests that verify a PASSING run today must inject one.
+const SOURCE_HYGIENE_PASS = { name: 'Source hygiene', status: 'completed', conclusion: 'success' };
+
 // ---------------------------------------------------------------------------
 // AC-22: Historical fixtures reproduce correctly
 // ---------------------------------------------------------------------------
 describe('AC-21 AC-22: historical fixture evaluation', () => {
 
-  test('113f472 (main baseline, 18 check-runs, all success) → PASS (exit 0)', () => {
-    const checkRuns = loadCheckRuns('checks-main-113f472.json');
-    assert.equal(checkRuns.length, 18, 'fixture must have 18 check-runs');
+  test('113f472 (main baseline + Source hygiene) → PASS (exit 0)', () => {
+    // The 113f472 fixture predates the source-hygiene job (added in #288).
+    // A passing run today requires Source hygiene to be present and successful
+    // (D-PR3b, EXPECTED_CONTEXTS). We inject a synthetic run to represent the
+    // current expected state.
+    const checkRuns = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    assert.equal(checkRuns.length, 19, 'fixture must have 18+1 check-runs');
     const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns, statuses: [], headSha: HEAD_113F472 });
     assert.equal(result.exitCode, 0, `expected PASS; lines: ${result.lines.join('\n')}`);
     assert.ok(result.pass, 'evaluateChecks must return pass=true');
@@ -106,14 +121,14 @@ describe('AC-21 AC-22: historical fixture evaluation', () => {
 // ---------------------------------------------------------------------------
 describe('AC-23: partial case (5 of 6 required present)', () => {
 
-  test('17 of 18 check-runs (MSRV deleted) → FAIL naming MSRV', () => {
+  test('17 of 18 check-runs (MSRV deleted) + Source hygiene → FAIL naming MSRV', () => {
     // Synthesize by removing the MSRV check-run from the 113f472 fixture.
     // This is the case `gh pr checks --required` exits 0 on (all present checks are green)
     // but the tool catches: a required context is absent.
     const allRuns = loadCheckRuns('checks-main-113f472.json');
     const msrvName = 'MSRV (Rust 1.88)';
-    const withoutMsrv = allRuns.filter(cr => cr.name !== msrvName);
-    assert.equal(withoutMsrv.length, 17, 'should have 17 runs after removing MSRV');
+    const withoutMsrv = [...allRuns.filter(cr => cr.name !== msrvName), SOURCE_HYGIENE_PASS];
+    assert.equal(withoutMsrv.length, 18, 'should have 17+1 runs after removing MSRV');
 
     const result = evaluateChecks({
       requiredContexts: REQUIRED,
@@ -136,9 +151,9 @@ describe('AC-23: partial case (5 of 6 required present)', () => {
 // ---------------------------------------------------------------------------
 describe('AC-24: non-success states → FAIL, quoting the observed state', () => {
 
-  // Build a passing baseline from the 113f472 fixture, then mutate one required check
+  // Build a passing baseline from the 113f472 fixture + Source hygiene.
   function buildPassingRuns() {
-    return loadCheckRuns('checks-main-113f472.json').map(cr => ({ ...cr }));
+    return [...loadCheckRuns('checks-main-113f472.json').map(cr => ({ ...cr })), { ...SOURCE_HYGIENE_PASS }];
   }
 
   const NON_SUCCESS_CASES = [
@@ -171,12 +186,190 @@ describe('AC-24: non-success states → FAIL, quoting the observed state', () =>
     });
   }
 
-  test('control: all-success baseline still exits 0 (suite is not failing unconditionally)', () => {
+  test('control: all-success baseline (with Source hygiene) still exits 0 (suite is not failing unconditionally)', () => {
     const runs = buildPassingRuns();
     const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
     assert.equal(result.exitCode, 0, 'all-success baseline must pass');
   });
 
+  // D-PR3b: non-required check in queued/in_progress must also FAIL (Tier B fix).
+  // PoC from the review: "6 required contexts completed+success plus
+  // {name:'Source hygiene', status:'queued', conclusion:null} → exits 0" — WRONG.
+  // After the fix, Tier B FAILs on any non-completed non-required run.
+  test('non-required check with status=queued → FAIL (Tier B, D-PR3 fix)', () => {
+    const runs = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { name: 'Source hygiene', status: 'queued', conclusion: null },
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1,
+      'a non-required queued run must prevent PASS (Tier B fix, D-PR3)');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('Source hygiene'), `must name the pending job; got: ${allLines}`);
+    assert.ok(allLines.includes('queued'), `must quote the observed status; got: ${allLines}`);
+  });
+
+  test('non-required check with status=in_progress → FAIL (Tier B, D-PR3 fix)', () => {
+    const runs = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { name: 'Some other job', status: 'in_progress', conclusion: null },
+      { ...SOURCE_HYGIENE_PASS },
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'a non-required in_progress run must prevent PASS');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('in_progress'), `must quote the observed status; got: ${allLines}`);
+  });
+
+});
+
+// ---------------------------------------------------------------------------
+// D-PR3b: EXPECTED_CONTEXTS (Source hygiene) — absence detection
+// Closing the gap: source-hygiene ABSENT → exit 0 was the described PoC.
+// ---------------------------------------------------------------------------
+describe('D-PR3b: Source hygiene absence detection (EXPECTED_CONTEXTS)', () => {
+
+  test('EXPECTED_CONTEXTS entries each match a job name: in .github/workflows/ci.yml', () => {
+    // avoids PF-013: pinning the constant against itself is a tautology — it proves nothing
+    // about the real CI workflow. Renaming the job in ci.yml must make this test fail so the
+    // developer knows EXPECTED_CONTEXTS needs updating too, rather than silently shipping a
+    // verifier that reports "never ran" at merge time with a misleading diagnosis.
+    const ciYml = readFileSync(join(ROOT, '.github/workflows/ci.yml'), 'utf8');
+    // Job-level names appear at exactly 4-space indent: "    name: ..."
+    // Step-level names have a leading dash:             "      - name: ..."
+    const jobNames = ciYml
+      .split('\n')
+      .filter(line => /^    name: /.test(line))
+      .map(line => line.replace(/^    name:\s+/, '').trim());
+    assert.ok(EXPECTED_CONTEXTS.length > 0, 'EXPECTED_CONTEXTS must be non-empty');
+    for (const ctx of EXPECTED_CONTEXTS) {
+      assert.ok(
+        jobNames.includes(ctx),
+        `EXPECTED_CONTEXTS entry "${ctx}" must be a job name: in .github/workflows/ci.yml; ` +
+        `found job names: ${jobNames.join(', ')}`,
+      );
+    }
+  });
+
+  test('Source hygiene ABSENT from check-runs → FAIL (the described PoC, D-PR3b)', () => {
+    // PoC: 6 required contexts completed+success, Source hygiene absent entirely.
+    // Before the fix, Tier B had nothing to iterate and emitted exitCode=0.
+    // After the fix (EXPECTED_CONTEXTS with Tier A semantics), absence = FAIL.
+    const checkRuns = loadCheckRuns('checks-main-113f472.json'); // no Source hygiene
+    const result = evaluateChecks({
+      requiredContexts: REQUIRED,
+      checkRuns,
+      statuses: [],
+      headSha: HEAD_113F472,
+    });
+    assert.equal(result.exitCode, 1,
+      'Source hygiene absent must exit 1, not 0 (PoC from the review finding)');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('Source hygiene'),
+      `failure must name "Source hygiene"; got: ${allLines}`);
+    // The absence message must indicate the job was not found
+    assert.ok(
+      allLines.includes('not found') || allLines.includes('never ran') || allLines.includes('absence'),
+      `failure must indicate the job was not found; got: ${allLines}`,
+    );
+  });
+
+  test('Source hygiene queued → FAIL (Tier A+ catches non-completed expected run)', () => {
+    const checkRuns = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { name: 'Source hygiene', status: 'queued', conclusion: null },
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'queued expected run must FAIL');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('Source hygiene'), `must name the job; got: ${allLines}`);
+    assert.ok(allLines.includes('queued'), `must quote the status; got: ${allLines}`);
+  });
+
+  test('Source hygiene in_progress → FAIL (Tier A+ catches non-completed expected run)', () => {
+    const checkRuns = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { name: 'Source hygiene', status: 'in_progress', conclusion: null },
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'in_progress expected run must FAIL');
+  });
+
+  test('Source hygiene failure → FAIL (Tier A+ catches failed expected run)', () => {
+    const checkRuns = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { name: 'Source hygiene', status: 'completed', conclusion: 'failure' },
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'failed expected run must FAIL');
+  });
+
+  test('Source hygiene present+success → does not fail (Tier A+ does not false-fail)', () => {
+    const checkRuns = [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      SOURCE_HYGIENE_PASS,
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 0, 'present-and-successful Source hygiene must not fail');
+  });
+
+  test('Source hygiene already in requiredContexts → not double-reported by Tier A+', () => {
+    // If Open Decision 1 is applied and Source hygiene enters branch protection,
+    // it appears in both requiredContexts and EXPECTED_CONTEXTS. The Tier A+
+    // loop must skip it (already handled in Tier A), not double-fail it.
+    const requiredWithHygiene = [...REQUIRED, 'Source hygiene'];
+    const checkRuns = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    const result = evaluateChecks({ requiredContexts: requiredWithHygiene, checkRuns, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 0, 'Source hygiene in required set must not be double-reported');
+    const allLines = result.lines.join('\n');
+    const tierAplusCount = (allLines.match(/Tier A\+/g) ?? []).length;
+    assert.equal(tierAplusCount, 0, 'Tier A+ must not fire when context is already in Tier A');
+  });
+
+});
+
+// ---------------------------------------------------------------------------
+// D-PR2a: Tier A checks BOTH namespaces independently (not if/else-if)
+// A failing commit status must not be masked by a passing check-run.
+// ---------------------------------------------------------------------------
+describe('D-PR2a: Tier A checks both check-runs AND statuses independently', () => {
+
+  test('required context in check-runs (success) AND statuses (failure) → FAIL', () => {
+    // Before the fix, if/else-if meant the status branch was only reached when
+    // no check-run existed. A failing status was silently ignored when a
+    // check-run of the same name was green (narrow divergence from GitHub's
+    // enforcement model per D-PR2a).
+    const allRuns = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    const msrvName = 'MSRV (Rust 1.88)';
+    // MSRV exists in check-runs (success), also in statuses (failure)
+    const statuses = [{ context: msrvName, state: 'failure' }];
+    const result = evaluateChecks({
+      requiredContexts: REQUIRED,
+      checkRuns: allRuns,
+      statuses,
+      headSha: HEAD_113F472,
+    });
+    assert.equal(result.exitCode, 1,
+      'failing status must not be masked by passing check-run (D-PR2a)');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes(msrvName), `must name the failing context; got: ${allLines}`);
+    assert.ok(allLines.includes('failure'), `must quote the failing state; got: ${allLines}`);
+  });
+
+  test('required context in check-runs (success) AND statuses (success) → PASS', () => {
+    const allRuns = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    const msrvName = 'MSRV (Rust 1.88)';
+    const statuses = [{ context: msrvName, state: 'success' }];
+    const result = evaluateChecks({
+      requiredContexts: REQUIRED,
+      checkRuns: allRuns,
+      statuses,
+      headSha: HEAD_113F472,
+    });
+    assert.equal(result.exitCode, 0,
+      'required context in both namespaces (both success) must pass (D-PR2a)');
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -198,7 +391,7 @@ describe('AC-25: zero check-runs never passes', () => {
   });
 
   test('output always includes counts (applies ADR-009)', () => {
-    const runs = loadCheckRuns('checks-main-113f472.json');
+    const runs = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
     const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
     const allLines = result.lines.join('\n');
     // Counts must appear whether pass or fail
@@ -213,14 +406,18 @@ describe('AC-25: zero check-runs never passes', () => {
 // ---------------------------------------------------------------------------
 describe('AC-26 AC-27: exit codes and merge command', () => {
 
-  test('PASS → exit 0 with --match-head-commit <sha> in output', () => {
-    const runs = loadCheckRuns('checks-main-113f472.json');
+  test('PASS → exit 0 with --admin --match-head-commit <sha> in output', () => {
+    const runs = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
     const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
     assert.equal(result.exitCode, 0);
     assert.ok(result.mergeCommand, 'PASS must produce a mergeCommand');
-    // D-PR5: merge command must include --match-head-commit <headSha>
+    // D-PR5: merge command must include --match-head-commit <headSha> (TOCTOU protection)
     assert.ok(result.mergeCommand.includes('--match-head-commit'), 'merge command must include --match-head-commit');
     assert.ok(result.mergeCommand.includes(HEAD_113F472), 'merge command must include the verified SHA');
+    // --admin is required: main is protected and the sole code-owner cannot self-approve.
+    // Emitting it here ensures the operator can copy the command verbatim — hand-editing
+    // is where --match-head-commit gets dropped (avoids PF-017 recurrence).
+    assert.ok(result.mergeCommand.includes('--admin'), 'merge command must include --admin');
   });
 
   test('FAIL → exit 1 (not 0, not 2)', () => {
@@ -237,7 +434,7 @@ describe('AC-26 AC-27: exit codes and merge command', () => {
 
     const passResult = evaluateChecks({
       requiredContexts: REQUIRED,
-      checkRuns: loadCheckRuns('checks-main-113f472.json'),
+      checkRuns: [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS],
       statuses: [],
       headSha: HEAD_113F472,
     });
@@ -260,7 +457,13 @@ const OK_GH_VERSION = () => ({ major: 2, minor: 88 });
 /**
  * Build a gh runner stub from a route table. Each entry is matched against the
  * API path by substring; the value is either a JSON object (success) or an
- * `{ __error: true, status }` shape mirroring defaultGhRunner's failure return.
+ * error shape mirroring defaultGhRunner's output.
+ *
+ * Error shape uses `httpStatus` (not `status`) for HTTP error codes — the
+ * process exit code is always 1 regardless of HTTP status, so `status` alone
+ * cannot distinguish 404 from 403. The stub mirrors the parsed shape that
+ * defaultGhRunner produces after fixing the medium finding (avoids PF-013:
+ * dead branches that only trigger on a value the runner never produces).
  */
 function stubRunner(routes, callLog = []) {
   return (args) => {
@@ -271,7 +474,7 @@ function stubRunner(routes, callLog = []) {
         return typeof value === 'function' ? value(url) : value;
       }
     }
-    return { __error: true, status: 404, stderr: `no stub route for ${url}` };
+    return { __error: true, httpStatus: 404, stderr: `no stub route for ${url}` };
   };
 }
 
@@ -279,24 +482,35 @@ const PR_OK = { head: { sha: HEAD_113F472 }, base: { ref: 'main' } };
 const PROTECTION_OK = JSON.parse(readFileSync(join(FIXTURES, 'protection-main.json'), 'utf8'));
 const CHECKS_OK = JSON.parse(readFileSync(join(FIXTURES, 'checks-main-113f472.json'), 'utf8'));
 
+// CHECKS_OK_WITH_HYGIENE: the 113f472 fixture + Source hygiene run, for happy-path
+// tests that drive main() and expect exit 0. The 113f472 fixture predates #288;
+// a PASS today requires Source hygiene to be present (D-PR3b, EXPECTED_CONTEXTS).
+const CHECKS_OK_WITH_HYGIENE = {
+  ...CHECKS_OK,
+  check_runs: [...CHECKS_OK.check_runs, SOURCE_HYGIENE_PASS],
+  total_count: CHECKS_OK.total_count + 1,
+};
+
 describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
 
   test('happy path → exit 0', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
-      ['/check-runs', CHECKS_OK],
-      ['/status', { statuses: [] }],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 0);
   });
 
   test('AC-29: unprotected base (404 on protection) → exit 2, never 0', () => {
+    // httpStatus mirrors what defaultGhRunner produces after parsing "(HTTP NNN)"
+    // from gh's stderr — the process exit code is always 1, not 404.
     const runner = stubRunner([
       ['/pulls/', PR_OK],
-      ['/protection', { __error: true, status: 404, stderr: 'Not Found' }],
-      ['/check-runs', CHECKS_OK],
-      ['/status', { statuses: [] }],
+      ['/protection', { __error: true, httpStatus: 404, stderr: 'gh: Not Found (HTTP 404)' }],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2);
   });
@@ -304,7 +518,7 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
   test('AC-29: --required-from branch also unprotected → exit 2', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
-      ['/protection', { __error: true, status: 404, stderr: 'Not Found' }],
+      ['/protection', { __error: true, httpStatus: 404, stderr: 'gh: Not Found (HTTP 404)' }],
     ]);
     assert.equal(main(['1', '--required-from', 'nope'], runner, OK_GH_VERSION), 2);
   });
@@ -312,11 +526,23 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
   test('AC-26: protection unreadable (403) → exit 2', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
-      ['/protection', { __error: true, status: 403, stderr: 'Forbidden' }],
+      ['/protection', { __error: true, httpStatus: 403, stderr: 'gh: Forbidden (HTTP 403)' }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2);
   });
 
+  test('AC-29: message for unprotected base names the branch and suggests --required-from', () => {
+    // Drives fetchRequiredContexts 404 path directly to verify message content.
+    const runner = (_args) => ({ __error: true, httpStatus: 404, stderr: 'gh: Not Found (HTTP 404)' });
+    const result = fetchRequiredContexts('wave/v0.4.0-wave1', null, runner);
+    assert.ok(!result.ok);
+    assert.equal(result.exitCode, 2);
+    assert.ok(result.message.includes('wave/v0.4.0-wave1'),
+      `message must name the base branch; got: ${result.message}`);
+    assert.ok(result.message.includes('--required-from'),
+      `message must mention --required-from; got: ${result.message}`);
+  });
+
   test('AC-26: gh older than 2.31 → exit 2 before any API call', () => {
     const calls = [];
     const runner = stubRunner([['/pulls/', PR_OK]], calls);
@@ -344,8 +570,8 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
       ['/protection', { required_status_checks: { contexts: [], checks: [] } }],
-      ['/check-runs', CHECKS_OK],
-      ['/status', { statuses: [] }],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2);
   });
@@ -362,8 +588,8 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
       ['/protection', onlyChecks],
-      ['/check-runs', CHECKS_OK],
-      ['/status', { statuses: [] }],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 0);
 
@@ -385,7 +611,7 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
       ['/check-runs', () => { pages++; return fullPage; }],
-      ['/status', { statuses: [] }],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2, 'page cap must exit 2');
     assert.ok(pages <= 20, `pagination must be bounded; issued ${pages} page requests`);
@@ -398,7 +624,7 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
       ['/check-runs', truncated],
-      ['/status', { statuses: [] }],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2);
   });
@@ -408,20 +634,32 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
-      ['/check-runs', CHECKS_OK],
-      ['/status', { statuses: [] }],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [], total_count: 0 }],
     ], calls);
+    const start = Date.now();
     assert.equal(main(['1'], runner, OK_GH_VERSION), 0);
+    const elapsed = Date.now() - start;
+    // AC-30 (clause b): verifier must complete in under 15 s wall-clock.
+    // With a synchronous stub runner, elapsed time reflects the verifier's own
+    // CPU cost and any unexpected loops — network latency is zero.
+    assert.ok(elapsed < 15000,
+      `verifier must complete in < 15 s wall-clock (AC-30 clause b); took ${elapsed}ms`);
     assert.equal(calls.length, 4, `expected 4 API calls (pr, protection, checks, status); got ${calls.length}`);
     const checkCall = calls.find(u => u.includes('/check-runs'));
     assert.ok(checkCall.includes('filter=latest'), 'filter=latest must be pinned explicitly (D-PR4a)');
+    // D-PR4a parity: combined-status endpoint must request per_page=100 so a context
+    // at position 31+ is not silently absent from the set (low finding fix).
+    const statusCall = calls.find(u => u.includes('/status'));
+    assert.ok(statusCall && statusCall.includes('per_page=100'),
+      `status URL must include per_page=100 (D-PR4a parity); got: ${statusCall}`);
   });
 
   test('check-runs API error → exit 2 (indeterminate), not 1', () => {
     const runner = stubRunner([
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
-      ['/check-runs', { __error: true, status: 500, stderr: 'server error' }],
+      ['/check-runs', { __error: true, httpStatus: 500, stderr: 'server error' }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 2);
   });
@@ -431,11 +669,158 @@ describe('AC-26 AC-28 AC-29: live path exit codes (injected runner)', () => {
       ['/pulls/', PR_OK],
       ['/protection', PROTECTION_OK],
       ['/check-runs', { total_count: 0, check_runs: [] }],
-      ['/status', { statuses: [] }],
+      ['/status', { statuses: [], total_count: 0 }],
     ]);
     assert.equal(main(['1'], runner, OK_GH_VERSION), 1);
   });
 
+  // D-PR4a parity: fetchStatuses total_count guard.
+  // The combined-status endpoint caps at 30 statuses. If total_count > returned
+  // count, a required context beyond position 30 would be falsely absent — fail
+  // closed rather than silently evaluate a partial set (consistent with D-PR4a).
+  test('fetchStatuses: total_count > returned statuses → exit 2 (partial set)', () => {
+    const runner = stubRunner([
+      ['/pulls/', PR_OK],
+      ['/protection', PROTECTION_OK],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      // total_count claims 35 but only 2 are returned (API cap at 30 simulated)
+      ['/status', { total_count: 35, statuses: [
+        { context: 'foo', state: 'success' },
+        { context: 'bar', state: 'success' },
+      ] }],
+    ]);
+    assert.equal(main(['1'], runner, OK_GH_VERSION), 2,
+      'truncated status list (total_count > returned) must exit 2');
+  });
+
+  test('fetchStatuses: total_count === returned statuses → proceeds normally', () => {
+    // Non-truncated status response — should not block a passing run.
+    const runner = stubRunner([
+      ['/pulls/', PR_OK],
+      ['/protection', PROTECTION_OK],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { total_count: 1, statuses: [{ context: 'foo', state: 'success' }] }],
+    ]);
+    assert.equal(main(['1'], runner, OK_GH_VERSION), 0,
+      'non-truncated status list must not block a passing run');
+  });
+
+  test('fetchStatuses: status omitting total_count → proceeds (no false-fail)', () => {
+    // Some stubs (and older fixtures) omit total_count; guard must not
+    // fire when total_count is absent.
+    const runner = stubRunner([
+      ['/pulls/', PR_OK],
+      ['/protection', PROTECTION_OK],
+      ['/check-runs', CHECKS_OK_WITH_HYGIENE],
+      ['/status', { statuses: [] }],  // no total_count
+    ]);
+    assert.equal(main(['1'], runner, OK_GH_VERSION), 0,
+      'missing total_count must not cause a false exit 2');
+  });
+
+});
+
+// ---------------------------------------------------------------------------
+// High finding: parseGhStderrHttpStatus — pin stub contract to production parsing.
+//
+// defaultGhRunner calls parseGhStderrHttpStatus (an exported pure function) to
+// extract the HTTP code from gh's stderr. Testing it here with captured real gh
+// stderr strings ensures the stubs used throughout this file mirror the value the
+// production runner actually produces (applies ADR-009, avoids PF-013: dead
+// branches that only trigger on a value the runner never produces).
+//
+// Stub shape reminder: stubRunner error objects use `httpStatus: 404` (not
+// `status: 404`). The process exit code is always 1 regardless of HTTP status;
+// `status` alone cannot distinguish 404 from 403. The stubRunner JSDoc documents
+// this contract; these tests pin the parser output that defines it.
+// ---------------------------------------------------------------------------
+describe('high finding: parseGhStderrHttpStatus parses real gh stderr format', () => {
+
+  test('extracts 404 from the real gh Not Found format', () => {
+    // Captured from: gh api /repos/dean0x/mdl/branches/nonexistent-xyz/protection
+    // stderr output: "gh: Not Found (HTTP 404)"
+    assert.equal(parseGhStderrHttpStatus('gh: Not Found (HTTP 404)'), 404,
+      'must extract 404 from real gh stderr format');
+  });
+
+  test('extracts 403 from the real gh Forbidden format', () => {
+    // Captured from: gh api on a branch with insufficient permissions
+    // stderr output: "gh: Forbidden (HTTP 403)"
+    assert.equal(parseGhStderrHttpStatus('gh: Forbidden (HTTP 403)'), 403,
+      'must extract 403 from real gh stderr format');
+  });
+
+  test('returns null for a non-HTTP error (e.g. connection refused)', () => {
+    // Connection errors have no "(HTTP NNN)" suffix — must not crash or return
+    // a wrong code that triggers the 404/403 branch accidentally.
+    assert.equal(parseGhStderrHttpStatus('connection refused'), null);
+  });
+
+  test('returns null for empty string', () => {
+    assert.equal(parseGhStderrHttpStatus(''), null);
+  });
+
+  test('returns null for null/undefined (guard against caller passing undefined stderr)', () => {
+    assert.equal(parseGhStderrHttpStatus(null), null);
+    assert.equal(parseGhStderrHttpStatus(undefined), null);
+  });
+
+});
+
+// ---------------------------------------------------------------------------
+// Medium finding: defaultGhRunner populates httpStatus from stderr, not status.
+// fetchRequiredContexts must branch on httpStatus (not the process exit code).
+// Stubs mirror the parsed shape (applies ADR-009, avoids PF-013 dead branches).
+// ---------------------------------------------------------------------------
+describe('medium finding: fetchRequiredContexts branches on httpStatus, not process exit code', () => {
+
+  test('httpStatus:404 → 404-specific message branch (not generic protection API error)', () => {
+    const runner = (_args) => ({ __error: true, httpStatus: 404, stderr: 'gh: Not Found (HTTP 404)' });
+    const result = fetchRequiredContexts('some-branch', null, runner);
+    assert.ok(!result.ok);
+    assert.equal(result.exitCode, 2);
+    // The 404 branch must fire — not the generic fallthrough
+    assert.ok(result.message.includes('no protection') || result.message.includes('404'),
+      `must use the 404 branch; got: ${result.message}`);
+    assert.ok(!result.message.includes('protection API error'),
+      `must NOT fall through to generic error; got: ${result.message}`);
+  });
+
+  test('httpStatus:403 → 403-specific message branch (not generic protection API error)', () => {
+    const runner = (_args) => ({ __error: true, httpStatus: 403, stderr: 'gh: Forbidden (HTTP 403)' });
+    const result = fetchRequiredContexts('some-branch', null, runner);
+    assert.ok(!result.ok);
+    assert.equal(result.exitCode, 2);
+    assert.ok(result.message.includes('403') || result.message.includes('permissions'),
+      `must use the 403 branch; got: ${result.message}`);
+    assert.ok(!result.message.includes('protection API error'),
+      `must NOT fall through to generic error; got: ${result.message}`);
+  });
+
+  test('httpStatus:null (no HTTP code in stderr) → generic error branch', () => {
+    // Simulates a non-API error (e.g. connection refused) where gh prints no HTTP code.
+    // This is what the OLD runner returned for ALL errors (always status:1, never 404).
+    // The fix: only the generic branch fires when httpStatus is null.
+    const runner = (_args) => ({ __error: true, status: 1, httpStatus: null, stderr: 'connection refused' });
+    const result = fetchRequiredContexts('some-branch', null, runner);
+    assert.ok(!result.ok);
+    assert.equal(result.exitCode, 2);
+    assert.ok(result.message.includes('protection API error'),
+      `non-HTTP error must fall through to generic branch; got: ${result.message}`);
+  });
+
+  test('httpStatus:undefined (old-shape stub) → generic error branch, not a throw', () => {
+    // Backward-compat: a stub that only sets status (not httpStatus) must not
+    // accidentally trigger the 404 or 403 branch via undefined === 404 → false.
+    const runner = (_args) => ({ __error: true, status: 404, stderr: 'Not Found' });
+    const result = fetchRequiredContexts('some-branch', null, runner);
+    assert.ok(!result.ok);
+    assert.equal(result.exitCode, 2);
+    // httpStatus is undefined → neither 404 nor 403 branch fires → generic
+    assert.ok(result.message.includes('protection API error'),
+      `undefined httpStatus must not trigger the 404 branch; got: ${result.message}`);
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -463,6 +848,109 @@ describe('the verifier runs from a spaced / symlinked path', () => {
 
 });
 
+// ---------------------------------------------------------------------------
+// Tier B: non-required, non-expected check-runs
+//
+// Tier B FAILs on:  failure, cancelled, timed_out, action_required, stale
+//                   queued, in_progress (non-completed = indeterminate → FAIL)
+// Tier B advises on: skipped, neutral (reported but not fatal)
+//
+// Coverage requirement (from review finding): explicit tests for each category
+// so `grep -c "Tier B"` on this file is non-zero for every shape, and the
+// positive control (advisory case → PASS) confirms the suite is not
+// unconditionally failing.
+// ---------------------------------------------------------------------------
+describe('Tier B: non-required non-expected check-run states', () => {
+
+  // Helper: 6 required contexts pass + Source hygiene passes; inject one extra.
+  function baseRunsWith(extra) {
+    return [
+      ...loadCheckRuns('checks-main-113f472.json'),
+      { ...SOURCE_HYGIENE_PASS },
+      extra,
+    ];
+  }
+
+  test('queued (non-completed) → FAIL (avoids PF-017: indeterminate ≠ success)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'queued', conclusion: null });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: queued non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('queued'), `must quote observed status; got: ${allLines}`);
+    assert.ok(allLines.includes('Some background job'), `must name the job; got: ${allLines}`);
+  });
+
+  test('in_progress (non-completed) → FAIL (avoids PF-017: indeterminate ≠ success)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'in_progress', conclusion: null });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: in_progress non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('in_progress'), `must quote observed status; got: ${allLines}`);
+  });
+
+  test('failure (completed) → FAIL', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'failure' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: completed/failure non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('failure'), `must quote conclusion; got: ${allLines}`);
+  });
+
+  test('cancelled (completed) → FAIL', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'cancelled' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: completed/cancelled non-required run must exit 1');
+  });
+
+  test('skipped (completed) → advisory only, PASS (Tier B does not fatal-fail skipped)', () => {
+    // skipped/neutral are ADVISORY in Tier B — the run completed, just not with work.
+    // This positive control proves the describe block is not unconditionally failing.
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'skipped' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 0, 'Tier B: skipped is advisory — must not block PASS');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('skipped'), `advisory line must name the conclusion; got: ${allLines}`);
+  });
+
+  test('neutral (completed) → advisory only, PASS (Tier B does not fatal-fail neutral)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'neutral' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 0, 'Tier B: neutral is advisory — must not block PASS');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('neutral'), `advisory line must name the conclusion; got: ${allLines}`);
+  });
+
+  // Critical finding (parameterized over all five TIER_B_FAIL conclusions):
+  // The original mutation test replaced TIER_B_FAIL = new Set([]) and all tests
+  // still passed, proving the set was unexercised for the remaining 3 conclusions.
+  // These tests close that gap and make any future removal detectable.
+  test('timed_out (completed) → FAIL (all five TIER_B_FAIL conclusions covered)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'timed_out' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: completed/timed_out non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('timed_out'), `must quote conclusion; got: ${allLines}`);
+    assert.ok(allLines.includes('Some background job'), `must name the job; got: ${allLines}`);
+  });
+
+  test('action_required (completed) → FAIL (all five TIER_B_FAIL conclusions covered)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'action_required' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: completed/action_required non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('action_required'), `must quote conclusion; got: ${allLines}`);
+  });
+
+  test('stale (completed) → FAIL (all five TIER_B_FAIL conclusions covered)', () => {
+    const runs = baseRunsWith({ name: 'Some background job', status: 'completed', conclusion: 'stale' });
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1, 'Tier B: completed/stale non-required run must exit 1');
+    const allLines = result.lines.join('\n');
+    assert.ok(allLines.includes('stale'), `must quote conclusion; got: ${allLines}`);
+  });
+
+});
+
 // ---------------------------------------------------------------------------
 // Duplicate check-run names must not mask a failure
 // ---------------------------------------------------------------------------
@@ -474,6 +962,7 @@ describe('duplicate check-run names are all evaluated', () => {
       ...loadCheckRuns('checks-main-113f472.json').filter(cr => cr.name !== ctx),
       { name: ctx, status: 'completed', conclusion: 'failure' },
       { name: ctx, status: 'completed', conclusion: 'success' },
+      SOURCE_HYGIENE_PASS,
     ];
     const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
     assert.equal(result.exitCode, 1,
@@ -481,6 +970,26 @@ describe('duplicate check-run names are all evaluated', () => {
     assert.ok(result.lines.join('\n').includes('failure'), 'must quote the observed conclusion');
   });
 
+  test('loop index is printed correctly when multiple runs share a name', () => {
+    // Review finding: the message hardcoded "(1 of N)" for every run.
+    // After fix: each failing run shows its own 1-based index.
+    const ctx = REQUIRED[0];
+    const runs = [
+      ...loadCheckRuns('checks-main-113f472.json').filter(cr => cr.name !== ctx),
+      { name: ctx, status: 'completed', conclusion: 'failure' },
+      { name: ctx, status: 'completed', conclusion: 'failure' },
+      { name: ctx, status: 'completed', conclusion: 'failure' },
+      SOURCE_HYGIENE_PASS,
+    ];
+    const result = evaluateChecks({ requiredContexts: REQUIRED, checkRuns: runs, statuses: [], headSha: HEAD_113F472 });
+    assert.equal(result.exitCode, 1);
+    const allLines = result.lines.join('\n');
+    // All three runs share the name; each must show its own position.
+    assert.ok(allLines.includes('1 of 3'), `first failing run must show "1 of 3"; got: ${allLines}`);
+    assert.ok(allLines.includes('2 of 3'), `second failing run must show "2 of 3"; got: ${allLines}`);
+    assert.ok(allLines.includes('3 of 3'), `third failing run must show "3 of 3"; got: ${allLines}`);
+  });
+
 });
 
 // ---------------------------------------------------------------------------
@@ -511,7 +1020,7 @@ describe('D-PR2a: required context satisfied by commit status', () => {
     // but that context is present in commit statuses as success.
     const allRuns = loadCheckRuns('checks-main-113f472.json');
     const msrvName = 'MSRV (Rust 1.88)';
-    const withoutMsrv = allRuns.filter(cr => cr.name !== msrvName);
+    const withoutMsrv = [...allRuns.filter(cr => cr.name !== msrvName), SOURCE_HYGIENE_PASS];
 
     // Simulate MSRV being satisfied via commit status instead
     const statuses = [{ context: msrvName, state: 'success' }];
@@ -526,3 +1035,54 @@ describe('D-PR2a: required context satisfied by commit status', () => {
       'required context satisfied via commit status must pass (D-PR2a)');
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tier C: pending statuses are reported as advisory, not silently dropped
+// ---------------------------------------------------------------------------
+describe('Tier C: pending non-required status is reported as advisory', () => {
+
+  test('state=pending non-required status emits an advisory line (not silently ignored)', () => {
+    // A pending non-required status is the same indeterminate condition as a
+    // non-completed Tier B run — both are "not yet resolved". Tier B now FAILs
+    // on queued/in_progress (same delta). Tier C is advisory-only, but the
+    // operator must still be able to see it, not have it vanish silently.
+    const runs = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    const statuses = [{ context: 'security/snyk (dean0x)', state: 'pending' }];
+    const result = evaluateChecks({
+      requiredContexts: REQUIRED,
+      checkRuns: runs,
+      statuses,
+      headSha: HEAD_113F472,
+    });
+    // PASS overall (non-required, advisory only)
+    assert.equal(result.exitCode, 0, `pending non-required status must not cause FAIL; lines: ${result.lines.join('\n')}`);
+    const allLines = result.lines.join('\n');
+    // The advisory line must be present so the operator sees the pending status
+    assert.ok(
+      allLines.includes('advisory (Tier C)') && allLines.includes('pending'),
+      `must emit an advisory line for pending non-required status; got:\n${allLines}`,
+    );
+  });
+
+  test('state=error non-required status still emits advisory (regression guard)', () => {
+    // Guard against the Tier C rewrite accidentally dropping non-pending errors.
+    const runs = [...loadCheckRuns('checks-main-113f472.json'), SOURCE_HYGIENE_PASS];
+    const statuses = [{ context: 'security/snyk (dean0x)', state: 'error' }];
+    const result = evaluateChecks({
+      requiredContexts: REQUIRED,
+      checkRuns: runs,
+      statuses,
+      headSha: HEAD_113F472,
+    });
+    assert.equal(result.exitCode, 0, 'non-required error status must not cause FAIL');
+    const allLines = result.lines.join('\n');
+    assert.ok(
+      allLines.includes('advisory (Tier C)') && allLines.includes('error'),
+      `must emit an advisory line for error non-required status; got:\n${allLines}`,
+    );
+  });
+
+});
+
+// Code of Conduct tests (AC-1, AC-2) live in code-of-conduct.spec.mjs —
+// split in commit 2e9482f to follow the one-spec-per-module convention.
diff --git a/scripts/verify-no-control-bytes.mjs b/scripts/verify-no-control-bytes.mjs
index 85099d6..f87716c 100644
--- a/scripts/verify-no-control-bytes.mjs
+++ b/scripts/verify-no-control-bytes.mjs
@@ -23,10 +23,25 @@
  *
  * D-CB5: Fails closed. In full-tree mode, zero-files-scanned is exit 1, not
  * exit 0 (avoids PF-016 — an empty scan masquerades as clean). In --staged
- * mode, an empty ACMR-filtered set is a legitimate state (deletion-only
+ * mode, an empty ACMRT-filtered set is a legitimate state (deletion-only
  * commits, amend with no content changes) and exits 0 with an explicit
  * message; the full-tree scan is the authoritative non-vacuity gate.
  *
+ * AC-6 AMENDMENT (--staged mode): AC-6 requires exit 1 when the scanned
+ * file set is empty. --staged mode intentionally exits 0 for a legitimately-
+ * empty content-bearing set (deletion-only commits via `git rm`, `git commit
+ * --amend -m`, `git commit --allow-empty`). Exiting 1 there would train
+ * contributors toward `--no-verify`, which disables the gate for ALL commits
+ * — the opposite of the security goal. No bypass exists: any staged file with
+ * hazardous content appears under the ACMRT filter. This amendment is
+ * deliberate, tested (see spec test "D-CB5 --staged carve-out from AC-6"),
+ * and leaves the full-tree CI scan as the authoritative AC-6 gate.
+ *
+ * D-CB6a: allowlist STALENESS is adjudicated in full-tree mode only. Staleness
+ * is a claim about the whole tracked tree, and --staged / explicit-path modes
+ * scan a subset that cannot support it. Hazard SUPPRESSION by an allowlist
+ * entry still applies in every mode. See the stale-allowlist block in main().
+ *
  * D-CB8: --staged mode reads file content from the git index via a single
  * `git cat-file --batch` subprocess (all staged blobs at once), never from
  * the working tree. Staging a clean file then modifying the working copy
@@ -67,7 +82,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
  * @param {string} metaUrl — the caller's import.meta.url
  * @returns {boolean}
  */
-export function isMainModule(metaUrl) {
+function isMainModule(metaUrl) {
   const entry = process.argv[1];
   if (!entry) return false;
   const modulePath = fileURLToPath(metaUrl);
@@ -185,22 +200,33 @@ function hexContext(buf, offset) {
   return hex.join(' ');
 }
 
-
 // ---------------------------------------------------------------------------
 // git helpers
 // ---------------------------------------------------------------------------
 
 function gitExec(args, cwd = process.cwd()) {
-  const result = spawnSync('git', args, { cwd, encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+  // Hard per-call bound: an index lock or credential prompt must not hang the
+  // pre-commit hook indefinitely. ETIMEDOUT is indeterminate → exit 2, never 0.
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'buffer',
+    maxBuffer: 64 * 1024 * 1024,
+    timeout: 30_000,
+  });
   if (result.error) {
     if (result.error.code === 'ENOENT') {
       // AC-16: fail-closed (exit 1) — "git missing" is a known, named failure,
       // not an indeterminate tool error.
       console.error('✖ verify-no-control-bytes: git is not on PATH');
       process.exit(1);
+    } else if (result.error.code === 'ETIMEDOUT') {
+      // Timeout is indeterminate — a hung git call is not evidence of a clean tree.
+      console.error('✖ verify-no-control-bytes: git timed out after 30 s — indeterminate, not clean');
+      process.exit(2);
+    } else {
+      console.error(`✖ verify-no-control-bytes: git error: ${result.error.message}`);
+      process.exit(2);
     }
-    console.error(`✖ verify-no-control-bytes: git error: ${result.error.message}`);
-    process.exit(2);
   }
   return result;
 }
@@ -252,15 +278,36 @@ function getTrackedFiles(cwd) {
 
 /**
  * Get staged file list for --staged mode.
- * Uses `git diff --cached --name-only -z --diff-filter=ACMR` for paths.
+ * Uses `git diff --cached --raw -z --diff-filter=ACMRT` to obtain both paths
+ * and git mode information so that gitlinks (160000) and symlinks (120000) can
+ * be skipped consistently with full-tree mode's AC-20 behavior.
  * D-CB8: content is fetched later in batch via readAllIndexBlobs().
+ *
+ * D-CB5a: mode-aware skip for staged mode. Unlike `git diff --cached
+ * --name-only`, the `--raw` format carries the new-file mode (octal) for each
+ * staged entry. Entries with new-mode 120000 (symlink) or 160000 (gitlink) are
+ * marked skip:true — identical to full-tree mode's AC-20 treatment. This
+ * resolves the pre-fix divergence where gitlinks reaching readAllIndexBlobs()
+ * would trigger a misleading "staged path not in index" error because
+ * `git cat-file --batch` returns 'missing' for a commit-typed index entry.
+ *
+ * D-CB5b: include T (type-change) in the diff-filter so a tracked symlink
+ * (120000) replaced by a regular file (100644) containing a hazard codepoint
+ * is not silently excluded. The raw format carries the new mode, so a T-change
+ * landing on mode 100644 is scanned; one landing on 120000 or 160000 is
+ * skipped. A T-change landing on 160000 would previously have caused a
+ * misleading error — it is now skipped cleanly.
+ *
+ * Raw diff format (git diff --cached --raw -z), per entry:
+ *   :<old-mode> <new-mode> <old-sha> <new-sha> <status>\0<path>\0
+ * Rename/copy (status starts with R or C):
+ *   :<old-mode> <new-mode> <old-sha> <new-sha> Rscore\0<old-path>\0<new-path>\0
  */
 function getStagedFiles(cwd) {
-  const r = gitExec(['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR'], cwd);
+  const r = gitExec(['diff', '--cached', '--raw', '-z', '--diff-filter=ACMRT'], cwd);
   if (r.status !== 0) {
-    // D-CB5: fail closed. `git diff --cached` exits 0 even when nothing is
-    // staged, so a non-zero status is a real tool failure (corrupt index,
-    // unreadable object). Treating it as "no staged files" would let the
+    // D-CB5: fail closed — a non-zero status is a real tool failure (corrupt
+    // index, unreadable object). Treating it as "no staged files" would let the
     // pre-commit hook report success on a scan that never happened.
     console.error(
       `✖ verify-no-control-bytes: git diff --cached failed (status ${r.status}): ` +
@@ -268,8 +315,38 @@ function getStagedFiles(cwd) {
     );
     process.exit(2);
   }
-  const paths = r.stdout.toString('utf8').split('\0').filter(s => s.length > 0);
-  return paths.map(p => ({ path: p, mode: 0o100644, skip: false, staged: true }));
+
+  const parts = r.stdout.toString('utf8').split('\0');
+  const files = [];
+  let i = 0;
+  while (i < parts.length) {
+    const header = parts[i];
+    // Raw diff headers start with ':'. Skip empty parts and non-header tokens.
+    if (!header || !header.startsWith(':')) { i++; continue; }
+    // `:old-mode new-mode old-sha new-sha status`
+    const fields = header.slice(1).split(' ');
+    const newMode = parseInt(fields[1], 8); // new-mode is octal (e.g. "100644")
+    const status = fields[4] || '';
+    i++;
+    // Rename (R) and copy (C) entries have two paths: old-path then new-path.
+    // Advance past old-path and use new-path (the content we care about).
+    if (status.startsWith('R') || status.startsWith('C')) {
+      i++; // skip old-path
+    }
+    const path = parts[i] || '';
+    i++;
+    if (!path) continue;
+    // AC-20: skip symlinks (120000) and gitlinks (160000) — identical to
+    // full-tree mode. A gitlink's cat-file lookup returns 'missing' (commit
+    // object, not a blob) and would otherwise cause a misleading "staged path
+    // not in index" error. Symlink blobs contain the target path; POSIX permits
+    // any byte except NUL and '/' in symlink targets, so control bytes are
+    // theoretically possible and scanning them could produce false-positive gate
+    // failures. Skipping keeps the gate focused on source-file content (avoids PF-015).
+    const skip = newMode === 0o120000 || newMode === 0o160000;
+    files.push({ path, mode: newMode, skip, staged: true });
+  }
+  return files;
 }
 
 /**
@@ -288,16 +365,27 @@ function getStagedFiles(cwd) {
 function readAllIndexBlobs(paths, cwd) {
   if (paths.length === 0) return new Map();
 
-  // Input: ":<path>\n" for every staged path
-  const stdin = Buffer.from(paths.map(p => `:${p}\n`).join(''), 'utf8');
-  const r = spawnSync('git', ['cat-file', '--batch'], {
+  // Input: ":<path>\0" for every staged path.
+  // Use NUL as delimiter (matching getStagedFiles' -z output) so that git paths
+  // containing a literal LF do not split into two batch requests and
+  // desynchronize the response parser.
+  const stdin = Buffer.from(paths.map(p => `:${p}\0`).join(''), 'utf8');
+  // Hard bound: mirrors gitExec's contract. An index lock, network-FS hang, or
+  // stuck git subprocess in the pre-commit hook must not block indefinitely.
+  // ETIMEDOUT is indeterminate → exit 2, never 0.
+  const r = spawnSync('git', ['cat-file', '--batch', '-z'], {
     cwd,
     input: stdin,
     encoding: 'buffer',
     maxBuffer: 256 * 1024 * 1024,
+    timeout: 30_000,
   });
   if (r.error) {
-    console.error(`✖ verify-no-control-bytes: git cat-file --batch: ${r.error.message}`);
+    if (r.error.code === 'ETIMEDOUT') {
+      console.error('✖ verify-no-control-bytes: git cat-file --batch timed out after 30 s — indeterminate, not clean');
+    } else {
+      console.error(`✖ verify-no-control-bytes: git cat-file --batch: ${r.error.message}`);
+    }
     process.exit(2);
   }
   if (r.status !== 0) {
@@ -446,6 +534,11 @@ function main() {
 
   const cwd = process.cwd();
 
+  // Full-tree mode is the only mode in which `fileEntries` is the COMPLETE
+  // tracked set. --staged and explicit-path modes scan a subset, which changes
+  // what the allowlist staleness check below can legitimately conclude.
+  const isFullTree = explicitPaths.length === 0 && !isStaged;
+
   // Verify git is accessible and we are in a repo (D-CB5)
   assertGitRepo(cwd);
 
@@ -463,8 +556,12 @@ function main() {
       absolutePath: resolve(cwd, p),
     }));
   } else if (isStaged) {
-    // D-CB8: staged mode — read from git index
-    fileEntries = getStagedFiles(cwd).map(e => ({ ...e, absolutePath: null }));
+    // D-CB8: staged mode — read from git index.
+    // getStagedFiles() now provides mode info; skip gitlinks and symlinks
+    // exactly as full-tree mode does (AC-20, D-CB5a).
+    const all = getStagedFiles(cwd);
+    skippedCount = all.filter(e => e.skip).length;
+    fileEntries = all.filter(e => !e.skip).map(e => ({ ...e, absolutePath: null }));
   } else {
     // Default: full tracked tree
     const all = getTrackedFiles(cwd);
@@ -476,8 +573,8 @@ function main() {
 
   // ---- D-CB5: Non-vacuity guard (AC-6) ----
   // Full-tree mode: zero tracked files means path discovery broke — fail closed.
-  // --staged mode: an empty ACMR-filtered set is a LEGITIMATE state:
-  //   • deletion-only commit (git rm): ACMR excludes deletions; files ARE staged.
+  // --staged mode: an empty ACMRT-filtered set is a LEGITIMATE state:
+  //   • deletion-only commit (git rm): ACMRT excludes deletions; files ARE staged.
   //   • amend with no content changes: index equals HEAD; diff is empty.
   // In both cases exit 0 with an explicit message. The full-tree scan is the
   // authoritative non-vacuity gate; the hook must not block valid commits.
@@ -487,21 +584,25 @@ function main() {
       console.error('  If this is a new repo with no commits, run `git add` first.');
       process.exit(1);
     }
-    // --staged: check unfiltered diff to provide an accurate message.
-    const rAll = gitExec(['diff', '--cached', '--name-only', '-z'], cwd);
-    if (rAll.status !== 0) {
+    // --staged: query actual deletions via --diff-filter=D rather than
+    // inferring from the unfiltered diff.  Using the unfiltered set is wrong
+    // when a T (type-change) is the only staged path: ACMRT already captures
+    // T-type content-bearing blobs, so if we arrive here the staged set truly
+    // contains only deletions (D) or nothing at all.
+    const rDel = gitExec(['diff', '--cached', '--name-only', '-z', '--diff-filter=D'], cwd);
+    if (rDel.status !== 0) {
       console.error(
-        `✖ verify-no-control-bytes: git diff --cached (unfiltered) failed: ` +
-        `${rAll.stderr.toString('utf8').trim()}`,
+        `✖ verify-no-control-bytes: git diff --cached (deletions) failed: ` +
+        `${rDel.stderr.toString('utf8').trim()}`,
       );
       process.exit(2);
     }
-    const allPaths = rAll.stdout.toString('utf8').split('\0').filter(s => s.length > 0);
-    if (allPaths.length > 0) {
+    const deletionPaths = rDel.stdout.toString('utf8').split('\0').filter(s => s.length > 0);
+    if (deletionPaths.length > 0) {
       // Staged changes exist but are all deletions — nothing for the content scanner to do.
       console.log(
         `✓ source-hygiene gate: 0 content-bearing staged paths` +
-        ` (${allPaths.length} deletion(s)) — nothing to scan`,
+        ` (${deletionPaths.length} deletion(s)) — nothing to scan`,
       );
     } else {
       // Index equals HEAD (amend --no-edit, reword, --allow-empty, etc.).
@@ -569,28 +670,51 @@ function main() {
         exercisedAllowlist.add(`${entry.path}:${hit.codepoint}`);
       } else {
         // AC-30: compute hex context now so buf is not retained after this iteration.
-        hazardHits.push({ path: entry.path, codepoint: hit.codepoint, byteOffset: hit.byteOffset, hexCtx: hexContext(buf, hit.byteOffset) });
+        hazardHits.push({
+          path: entry.path,
+          codepoint: hit.codepoint,
+          byteOffset: hit.byteOffset,
+          hexCtx: hexContext(buf, hit.byteOffset),
+        });
       }
     }
   }
 
   // ---- Stale allowlist check (D-CB6) ----
-  for (const entry of BINARY_ALLOWLIST) {
-    const exists = fileEntries.some(e => e.path === entry.path);
-    if (!exists) {
-      errors.push(`BINARY_ALLOWLIST: stale entry "${entry.path}" — file is no longer tracked`);
+  //
+  // D-CB6a: FULL-TREE MODE ONLY. Staleness is a claim about the whole tracked
+  // tree ("this entry no longer corresponds to anything"), and only full-tree
+  // mode holds the evidence for it. In --staged and explicit-path modes
+  // `fileEntries` is a SUBSET, so every allowlist entry outside that subset
+  // would be reported as "no longer tracked" — a factually false message that
+  // fails every commit not touching the allowlisted file. That turns the
+  // pre-commit hook into a wall the moment a first legitimate entry is added,
+  // and trains contributors toward `--no-verify`, which disables the gate for
+  // ALL commits — the same reasoning that drives the AC-6 --staged carve-out
+  // above. The full-tree CI scan is the authoritative allowlist validator, and
+  // it runs on every pull_request and on every tag push.
+  //
+  // Hazard SUPPRESSION is unaffected and still applies in every mode:
+  // hazardAllowMap is keyed by path, so an allowlisted file staged with its
+  // declared codepoints still passes. Only the staleness verdict is deferred.
+  if (isFullTree) {
+    for (const entry of BINARY_ALLOWLIST) {
+      const exists = fileEntries.some(e => e.path === entry.path);
+      if (!exists) {
+        errors.push(`BINARY_ALLOWLIST: stale entry "${entry.path}" — file is no longer tracked`);
+      }
     }
-  }
-  for (const entry of HAZARD_ALLOWLIST) {
-    const exists = fileEntries.some(e => e.path === entry.path);
-    if (!exists) {
-      errors.push(`HAZARD_ALLOWLIST: stale entry "${entry.path}" — file is no longer tracked`);
-    } else {
-      // Verify the declared codepoints actually occur in the file
-      for (const cp of entry.codepoints) {
-        const key = `${entry.path}:${cp}`;
-        if (!exercisedAllowlist.has(key)) {
-          errors.push(`HAZARD_ALLOWLIST: stale entry "${entry.path}" cp U+${cp.toString(16).toUpperCase().padStart(4, '0')} — codepoint not found in file`);
+    for (const entry of HAZARD_ALLOWLIST) {
+      const exists = fileEntries.some(e => e.path === entry.path);
+      if (!exists) {
+        errors.push(`HAZARD_ALLOWLIST: stale entry "${entry.path}" — file is no longer tracked`);
+      } else {
+        // Verify the declared codepoints actually occur in the file
+        for (const cp of entry.codepoints) {
+          const key = `${entry.path}:${cp}`;
+          if (!exercisedAllowlist.has(key)) {
+            errors.push(`HAZARD_ALLOWLIST: stale entry "${entry.path}" cp U+${cp.toString(16).toUpperCase().padStart(4, '0')} — codepoint not found in file`);
+          }
         }
       }
     }
diff --git a/scripts/verify-pr-checks.mjs b/scripts/verify-pr-checks.mjs
index 3601244..a23f9c0 100644
--- a/scripts/verify-pr-checks.mjs
+++ b/scripts/verify-pr-checks.mjs
@@ -16,12 +16,23 @@
  * is a vacuous green, and vacuous greens are what PF-017 was made of.
  *
  * D-PR2a: A required context is resolved against the UNION of check-runs AND
- * commit statuses (GitHub branch protection accepts either namespace).
+ * commit statuses (GitHub branch protection accepts either namespace). Both
+ * namespaces are checked independently: a failing commit status is not masked
+ * by a passing check-run under the same name.
  *
  * D-PR3: Three tiers:
- *   Tier A (required): MUST be completed+success — missing/cancelled/etc = FAIL
- *   Tier B (non-required check-runs): failure/cancelled/timed_out = FAIL
- *   Tier C (legacy commit statuses): advisory unless the context is required
+ *   Tier A  (required):          MUST be completed+success — missing/cancelled/etc = FAIL
+ *   Tier A+ (expected, local):   Same semantics as Tier A, but sourced from EXPECTED_CONTEXTS
+ *                                rather than branch protection. Absence = FAIL (not advisory).
+ *   Tier B  (non-required runs): failure/cancelled/timed_out = FAIL; not-yet-completed = FAIL
+ *   Tier C  (legacy statuses):   advisory unless the context is required
+ *
+ * D-PR3b: EXPECTED_CONTEXTS lists jobs that must be present and passing even though
+ * they are not (yet) in branch protection. Currently: ['Source hygiene'] — the
+ * control-byte gate added in #288. Tier B alone cannot make it binding because Tier B
+ * only iterates runs that ALREADY EXIST in the check-run list; an absent job has
+ * nothing to iterate. Tier A+ fills this gap by asserting presence (applies ADR-009,
+ * avoids PF-013: absence is never evidence of success).
  *
  * D-PR4: Non-vacuity guard — zero check-runs = FAIL (the #239 case).
  *        Counts are always printed on every run (avoids PF-013).
@@ -30,9 +41,10 @@
  *         `filter=latest` is pinned explicitly (default today, but implicit
  *         defaults can change and this gate's verdict depends on it).
  *
- * D-PR5: On PASS the tool prints a merge command with --match-head-commit
- *        <headSha>, closing the TOCTOU window where the verified SHA diverges
- *        from HEAD by the time the merge runs.
+ * D-PR5: On PASS the tool prints `gh pr merge --squash --admin --match-head-commit
+ *        <headSha>` so the operator copies it verbatim. --admin is required for
+ *        protected main; --match-head-commit closes the TOCTOU window where the
+ *        verified SHA diverges from HEAD by the time the merge runs (avoids PF-017).
  *
  * D-PR6: Exit codes — 0 PASS, 1 FAIL, 2 indeterminate. "Cannot tell" is
  *        never 0.
@@ -80,31 +92,84 @@ const MAX_PAGES = 20;
 const MIN_GH_MAJOR = 2;
 const MIN_GH_MINOR = 31;
 
+/**
+ * D-PR3b: Locally-expected contexts — enforced with Tier A semantics regardless
+ * of whether they appear in branch protection. An absent job is FAIL, not
+ * advisory (applies ADR-009, avoids PF-013).
+ *
+ * 'Source hygiene' is the control-byte gate added in #288. It is not yet a
+ * required context in branch protection (Open Decision 1), so Tier B is the
+ * only thing making it binding — but Tier B only iterates runs that ALREADY
+ * APPEAR in the check-run list. When the job is absent (renamed, deleted, not
+ * yet started, or cancelled before reporting), Tier B has nothing to iterate
+ * and the verifier would emit a PASS. EXPECTED_CONTEXTS closes this gap by
+ * asserting presence, mirroring Tier A semantics.
+ */
+export const EXPECTED_CONTEXTS = ['Source hygiene'];
+
 // ---------------------------------------------------------------------------
 // gh runner (thin IO shim; injected in tests for offline operation)
 // ---------------------------------------------------------------------------
 
+/**
+ * Extract the HTTP status code from gh's stderr string.
+ *
+ * gh prints errors in the format "gh: <message> (HTTP NNN)" for API errors.
+ * The process exit code is always 1 regardless of the HTTP status, so `status`
+ * alone cannot distinguish 404 from 403. This pure function is exported so
+ * tests can pin the stub contract to the production parsing contract (avoids
+ * PF-013: dead branches that only trigger on a value the runner never produces).
+ *
+ * @param {string|null|undefined} stderr
+ * @returns {number|null} HTTP status code, or null if not found
+ */
+export function parseGhStderrHttpStatus(stderr) {
+  if (!stderr) return null;
+  const m = stderr.match(/\(HTTP (\d+)\)/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
 /**
  * Default runner: calls `gh api` and returns parsed JSON.
+ *
+ * On error, returns `{ __error: true, status: <process-exit>, httpStatus: <HTTP-code|null>, stderr }`.
+ * `httpStatus` is parsed from gh's stderr format "gh: <message> (HTTP NNN)" and is the
+ * value callers should branch on for 404/403 distinctions — the process exit code is
+ * always 1 regardless of the HTTP status, so `status` alone cannot distinguish 404 from 403.
+ *
  * @param {string[]} args
  * @returns {any}
  */
 function defaultGhRunner(args) {
-  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  // AC-30: hard wall per gh invocation so a hung or throttled connection cannot
+  // block the tool indefinitely (avoids PF-017: indeterminate ≠ success).
+  // ETIMEDOUT maps to the __error path, which callers classify as exit 2.
+  const r = spawnSync('gh', args, {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: 30_000,
+  });
   if (r.error) {
-    const stderr = r.error.code === 'ENOENT'
-      ? 'gh is not on PATH'
-      : `gh error: ${r.error.message}`;
-    return { __error: true, status: -1, stderr };
+    let stderr;
+    if (r.error.code === 'ENOENT') {
+      stderr = 'gh is not on PATH';
+    } else if (r.error.code === 'ETIMEDOUT') {
+      stderr = 'gh timed out after 30 s (AC-30: indeterminate, not clean)';
+    } else {
+      stderr = `gh error: ${r.error.message}`;
+    }
+    return { __error: true, status: -1, httpStatus: null, stderr };
   }
   if (r.status !== 0) {
-    // Return status code so caller can handle 404/403
-    return { __error: true, status: r.status, stderr: r.stderr };
+    // parseGhStderrHttpStatus is tested separately so the stub contract and
+    // the production parsing contract are pinned to each other (avoids PF-013).
+    const httpStatus = parseGhStderrHttpStatus(r.stderr);
+    return { __error: true, status: r.status, httpStatus, stderr: r.stderr };
   }
   try {
     return JSON.parse(r.stdout);
   } catch {
-    return { __error: true, status: r.status, raw: r.stdout, stderr: r.stderr };
+    return { __error: true, status: r.status, httpStatus: null, raw: r.stdout, stderr: r.stderr };
   }
 }
 
@@ -129,6 +194,7 @@ function defaultGhRunner(args) {
  *   checkRuns: CheckRun[];
  *   statuses: CommitStatus[];
  *   headSha: string;
+ *   expectedContexts?: string[];  // defaults to EXPECTED_CONTEXTS
  * }} EvaluateInput
  *
  * @typedef {{
@@ -149,7 +215,13 @@ function defaultGhRunner(args) {
  * @param {EvaluateInput} input
  * @returns {EvaluateResult}
  */
-export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha }) {
+export function evaluateChecks({
+  requiredContexts,
+  checkRuns,
+  statuses,
+  headSha,
+  expectedContexts = EXPECTED_CONTEXTS,
+}) {
   const lines = [];
   const failures = [];
   let pass = true;
@@ -208,31 +280,41 @@ export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha
   }
 
   // ---- Tier A: required contexts ----
-  // D-PR2a: resolved against the UNION of check-runs and commit statuses.
+  // D-PR2a: resolved against BOTH check-runs AND commit statuses independently.
+  // GitHub branch protection enforcement considers both namespaces; a failing
+  // commit status is not masked by a passing check-run under the same name.
   // avoids PF-017: must be status=completed AND conclusion=success.
   for (const ctx of requiredContexts) {
     const crs = checksByName.get(ctx);
     const st = statusByContext.get(ctx);
+    let found = false;
 
     if (crs) {
-      // Found in check-runs namespace — EVERY run under this name must pass.
-      for (const cr of crs) {
+      found = true;
+      // Every run under this name must pass — keeping only the last entry would
+      // let a later success mask an earlier failure from a different check-suite.
+      for (const [idx, cr] of crs.entries()) {
         if (cr.status !== 'completed' || cr.conclusion !== 'success') {
           failures.push(
             `Tier A (required): "${ctx}" — status=${cr.status}, conclusion=${cr.conclusion ?? 'null'}` +
-            (crs.length > 1 ? ` (1 of ${crs.length} runs sharing this name)` : '') +
+            (crs.length > 1 ? ` (${idx + 1} of ${crs.length} runs sharing this name)` : '') +
             ` (avoids PF-017: cancelled/skipped/in_progress are not success)`,
           );
           pass = false;
         }
       }
-    } else if (st) {
-      // Found in commit statuses namespace
+    }
+    if (st) {
+      // Always check the status namespace too, even when a check-run was found.
+      // D-PR2a: both namespaces are checked independently so a failing status
+      // is not silently ignored when a check-run of the same name is green.
+      found = true;
       if (st.state !== 'success') {
         failures.push(`Tier A (required): "${ctx}" — status.state=${st.state} (must be "success")`);
         pass = false;
       }
-    } else {
+    }
+    if (!found) {
       // Not found in either namespace
       failures.push(`Tier A (required): "${ctx}" — not found in check-runs or statuses (never ran)`);
       pass = false;
@@ -241,15 +323,76 @@ export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha
 
   const requiredSet = new Set(requiredContexts);
 
+  // ---- Tier A+: locally-expected contexts (Tier A semantics, protection-independent) ----
+  // D-PR3b: jobs in EXPECTED_CONTEXTS must be present and passing regardless of
+  // whether they appear in branch protection. 'Source hygiene' is the primary
+  // example: it is not yet a required context (Open Decision 1), so without
+  // this tier, an absent or renamed job would yield exitCode=0. Absence is FAIL,
+  // not advisory — applies ADR-009, avoids PF-013.
+  for (const ctx of expectedContexts) {
+    if (requiredSet.has(ctx)) continue; // Already enforced in Tier A with full context
+    const crs = checksByName.get(ctx);
+    const st = statusByContext.get(ctx);
+    let found = false;
+
+    if (crs) {
+      found = true;
+      for (const cr of crs) {
+        if (cr.status !== 'completed' || cr.conclusion !== 'success') {
+          failures.push(
+            `Tier A+ (expected): "${ctx}" — status=${cr.status}, conclusion=${cr.conclusion ?? 'null'} ` +
+            `(locally-expected job must be completed+success, D-PR3b)`,
+          );
+          pass = false;
+        }
+      }
+    }
+    if (st) {
+      found = true;
+      if (st.state !== 'success') {
+        failures.push(`Tier A+ (expected): "${ctx}" — status.state=${st.state} (must be "success", D-PR3b)`);
+        pass = false;
+      }
+    }
+    if (!found) {
+      // ABSENCE IS FAIL — this is the central defect this tier exists to close.
+      // When source-hygiene is absent from check-runs, Tier B has nothing to
+      // iterate and would have emitted a PASS. Tier A+ prevents that.
+      failures.push(
+        `Tier A+ (expected): "${ctx}" — not found in check-runs or statuses (never ran). ` +
+        `This job must exist and pass; its absence is not evidence of success (D-PR3b, avoids PF-013)`,
+      );
+      pass = false;
+    }
+  }
+
   // ---- Tier B: non-required check-runs ----
   // failure/cancelled/timed_out/action_required/stale = FAIL
+  // not-yet-completed (queued/in_progress) = FAIL: a PASS must not be emitted
+  //   while an active check is still outstanding; the outstanding check might
+  //   later fail, rendering the verified SHA stale and the merge command unsafe.
+  //   avoids PF-017: indeterminate state must never read as success.
   // skipped/neutral = advisory (reported but not fatal)
   const TIER_B_FAIL = new Set(['failure', 'timed_out', 'cancelled', 'action_required', 'stale']);
   const TIER_B_ADVISORY = new Set(['skipped', 'neutral']);
 
   for (const cr of checkRuns) {
     if (requiredSet.has(cr.name)) continue; // Already handled in Tier A
-    if (cr.status !== 'completed') continue; // Still running — skip advisory
+    // Also skip if already handled in Tier A+
+    if (expectedContexts.includes(cr.name)) continue;
+
+    if (cr.status !== 'completed') {
+      // Non-completed non-required run: a queued or in_progress check means the
+      // CI suite is still running. Emitting a PASS while checks are outstanding
+      // would defeat the gate — the outstanding check might later fail.
+      // avoids PF-017: indeterminate state (not-yet-completed) is never success.
+      failures.push(
+        `Tier B (non-required): "${cr.name}" — status=${cr.status} (not yet completed; ` +
+        `must not merge while checks are still running)`,
+      );
+      pass = false;
+      continue;
+    }
     if (cr.conclusion == null) continue;
 
     if (TIER_B_FAIL.has(cr.conclusion)) {
@@ -266,7 +409,12 @@ export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha
   // in state=error due to account-plan limits — not a workflow in this repo.
   for (const st of statuses) {
     if (requiredSet.has(st.context)) continue; // Already handled in Tier A
-    if (st.state !== 'success' && st.state !== 'pending') {
+    if (st.state === 'pending') {
+      // Asymmetric with Tier B (which FAILs on not-yet-completed runs): a
+      // non-required pending status is advisory only, but it must not be
+      // silently swallowed — the caller cannot know if this is benign.
+      lines.push(`  advisory (Tier C): "${st.context}" — state=pending (not yet resolved)`);
+    } else if (st.state !== 'success') {
       lines.push(`  advisory (Tier C): "${st.context}" — state=${st.state}`);
     }
   }
@@ -277,7 +425,11 @@ export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha
   }
 
   if (pass) {
-    const cmd = `gh pr merge --squash --match-head-commit ${headSha}`;
+    // D-PR5: --admin is required because main is protected and the sole
+    // code-owner cannot self-approve. Emit it here so the operator can
+    // copy the command verbatim without hand-editing (avoids PF-017: a
+    // hand-edited command is where --match-head-commit gets dropped).
+    const cmd = `gh pr merge --squash --admin --match-head-commit ${headSha}`;
     lines.push(`✓ PASS — all ${nRequired} required contexts completed+success`);
     lines.push(`  Verified SHA: ${headSha}`);
     lines.push(`  Merge command: ${cmd}`);
@@ -302,7 +454,9 @@ export function evaluateChecks({ requiredContexts, checkRuns, statuses, headSha
 // ---------------------------------------------------------------------------
 
 function ghVersion() {
-  const r = spawnSync('gh', ['--version'], { encoding: 'utf8' });
+  // Short timeout: --version is a local binary probe with no network I/O.
+  // ETIMEDOUT sets r.error → null return → main() exits 2 (indeterminate).
+  const r = spawnSync('gh', ['--version'], { encoding: 'utf8', timeout: 10_000 });
   if (r.error || r.status !== 0) return null;
   // Output: "gh version 2.88.1 (2026-07-17)"
   const m = r.stdout.match(/gh version (\d+)\.(\d+)/);
@@ -365,15 +519,40 @@ export function fetchCheckRuns(headSha, runner) {
 
 /**
  * Fetch commit statuses for a sha.
+ *
+ * The combined-status endpoint caps at 30 statuses per response and offers no
+ * pagination. If total_count exceeds what was returned, a required context
+ * backed by a status beyond position 30 would be falsely reported as 'never
+ * ran'. Fail closed (exit 2) rather than silently evaluate a partial set —
+ * consistent with D-PR4a's total_count assertion on check-runs.
+ *
  * @returns {{ ok: true, statuses: CommitStatus[] } | { ok: false, exitCode: 2, message: string }}
  */
 export function fetchStatuses(headSha, runner) {
-  const url = `/repos/{owner}/{repo}/commits/${headSha}/status`;
+  // per_page=100 requests the maximum from the combined-status endpoint so that
+  // a context at position 31+ is not silently missed. D-PR4a parity: assert
+  // returned count against total_count and fail closed on any shortfall.
+  const url = `/repos/{owner}/{repo}/commits/${headSha}/status?per_page=100`;
   const data = runner(['api', url]);
   if (data.__error) {
     return { ok: false, exitCode: 2, message: `commit-status API error: ${data.stderr}` };
   }
-  return { ok: true, statuses: data.statuses ?? [] };
+  const statuses = data.statuses ?? [];
+  // D-PR4a parity: combined-status returns at most 30 statuses with no pagination.
+  // If total_count exceeds the returned count, we have a partial view and must
+  // fail closed rather than evaluate an incomplete set.
+  const totalCount = data.total_count ?? statuses.length;
+  if (totalCount > statuses.length) {
+    return {
+      ok: false,
+      exitCode: 2,
+      message:
+        `commit-status endpoint returned ${statuses.length} of ${totalCount} statuses — ` +
+        `at least one status may be missing (API cap at 30). ` +
+        `A required context beyond position 30 would be falsely reported as never-ran.`,
+    };
+  }
+  return { ok: true, statuses };
 }
 
 /**
@@ -386,6 +565,10 @@ export function fetchStatuses(headSha, runner) {
  * deprecated `contexts` would silently yield an empty required set — and an
  * empty required set is a vacuous pass, not a pass.
  *
+ * Error objects from defaultGhRunner carry `httpStatus` (parsed from gh's stderr
+ * format "gh: <message> (HTTP NNN)") rather than the process exit code, which
+ * is always 1 regardless of the HTTP status. Callers branch on `httpStatus`.
+ *
  * @returns {{ ok: true, contexts: string[], resolvedBranch: string, notes: string[] }
  *          | { ok: false, exitCode: 2, message: string }}
  */
@@ -395,7 +578,7 @@ export function fetchRequiredContexts(baseBranch, requiredFrom, runner) {
   const data = runner(['api', url]);
 
   if (data.__error) {
-    if (data.status === 404) {
+    if (data.httpStatus === 404) {
       const message = requiredFrom
         ? `--required-from branch "${requiredFrom}" has no protection (404)`
         : `base branch "${baseBranch}" has no protection (404). ` +
@@ -403,7 +586,7 @@ export function fetchRequiredContexts(baseBranch, requiredFrom, runner) {
           `(AC-29: an unprotected base is not a pass — D-PR2)`;
       return { ok: false, exitCode: 2, message };
     }
-    if (data.status === 403) {
+    if (data.httpStatus === 403) {
       return {
         ok: false,
         exitCode: 2,