claude-dev-env 2.2.1 → 2.4.0

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -1,41 +1,141 @@
-# Category O — Docstring / fixture-prose vs implementation drift
-
-**What this category audits:** module docstrings, fixture docstrings, helper-function docstrings, and free-form narrative prose inside docstrings (step ordering, named sentinels, predicate-breadth claims, list-of-responsibilities sentences) whose claims diverge from the implementation they describe. The gate-time `check_docstring_args_match_signature` validator covers only the `Args:` section parameter names; every other docstring claim — module-level `"This module detects X"`, fixture-level `"readability is disabled for these tests"`, predicate-level `"resolves to shared temp only"`, step-ordering narrative `"strip ceremony, then drop blockquotes"` — drifts past it.
-
-**Examples of Category O findings:**
-- A module docstring says the module recovers PR numbers, but a refactor split that logic into a sibling module.
-- A fixture docstring asserts a global disable invariant that sibling tests in the same file explicitly violate.
-- A predicate name and docstring promise a narrow check, but the body also matches a broader input class (HOME/TMP env vars when the docstring says shared-temp only).
-- A docstring lists three responsibilities; only one is implemented, the other two live elsewhere.
-- A docstring describes step ordering `A then B`; the body does `B then A`.
-- A docstring references a sentinel marker (`# pragma: no-tdd-gate`) or filename shape (`test_code-rules-enforcer.py`) that the module body and the repo's naming convention do not use.
-
-**Companion reference:** see `../source-material-section-types.md`.
-
----
-
-## Sub-bucket decomposition (Category O)
-
-Decomposition is by the **kind of docstring claim** that needs to be cross-checked against the implementation.
-
-| ID | Axis name | Concrete checks |
-|---|---|---|
-| O1 | Module-level responsibility verbs | A module docstring uses verbs (`detects`, `validates`, `enforces`, `recovers`, `parses`, `routes`) — every claimed responsibility is implemented by an exported symbol in the same module. Symbols absent from the module body should not appear as this module's responsibilities. |
-| O2 | Fixture docstring vs sibling-test behavior | An autouse / module-scope fixture docstring asserts an invariant (`readability is disabled`, `network is mocked`, `tmp_path is empty`). No sibling test in the same module explicitly opts out of the invariant. |
-| O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
-| O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. A docstring step enumeration that names the body's linear steps but omits a corrective workflow step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`) is also an O4 finding: the reader trusts the step list to be complete and misses the conditional path. The branch-guarded-dispatch shape of this drift — a docstring that names two or more linear-step callees while the body guards a two-or-more-token dispatch callee inside a branch whose name the prose never spells out — is gated deterministically at Write/Edit time by `check_docstring_step_enumeration_dispatch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`), so the audit lane focuses on the step-ordering shapes the gate cannot match (re-ordered steps, plain unguarded steps the prose omits). |
-| O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
-| O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
-| O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
-| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The diagram-first shape carries this best: a summary line, then a `::` example block or a doctest that shows a concrete input and its marked outcome, then a couple of short prose lines. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, and a narrative that runs more than six prose lines with no such block is gated by `check_docstring_prose_wall_without_illustration` in the same module, so this lane carries the judgment the gates cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read, and whether the diagram truly illustrates — a real input, a marked outcome, an `ok:` / `flag:` contrast a reader learns from. See `../../rules/plain-illustrative-docstrings.md`. |
-
----
-
-## Sample prompt
-
-The reusable Variant C template for Category O is in [`../prompts/category-o-docstring-vs-impl-drift.md`](../prompts/category-o-docstring-vs-impl-drift.md). Inline every changed module's docstring (module-level + every helper-function docstring whose function body was touched + every fixture docstring) alongside the symbols defined in the same module under `## Source material`.
-
-## Why Category O matters as its own bucket
-
-Signature-shaped claims — parameter names, return types, exceptions in the `Raises:` block — have a gate-time validator (`check_docstring_args_match_signature`) and signature-oriented audit categories to catch them. Free-form narrative prose in docstrings is the other half of the docstring contract: the part that tells a reader what the module is for, what the fixture does, what the predicate means. When that prose drifts from the body, the gate cannot catch it because there is no signature to compare against. Category O forces the audit teammate to list docstring claims and verify each against the body, the same way signature claims are verified against the body.
+# Category O — Docstring / fixture-prose vs implementation drift
+
+**What this category audits:** module docstrings, fixture docstrings, helper-function docstrings, and free-form narrative prose inside docstrings (step ordering, named sentinels, predicate-breadth claims, list-of-responsibilities sentences) whose claims diverge from the implementation they describe. The gate-time `check_docstring_args_match_signature` validator covers only the `Args:` section parameter names; every other docstring claim — module-level `"This module detects X"`, fixture-level `"readability is disabled for these tests"`, predicate-level `"resolves to shared temp only"`, step-ordering narrative `"strip ceremony, then drop blockquotes"` — drifts past it.
+
+**Examples of Category O findings:**
+- A module docstring says the module recovers PR numbers, but a refactor split that logic into a sibling module.
+- A fixture docstring asserts a global disable invariant that sibling tests in the same file explicitly violate.
+- A predicate name and docstring promise a narrow check, but the body also matches a broader input class (HOME/TMP env vars when the docstring says shared-temp only).
+- A docstring lists three responsibilities; only one is implemented, the other two live elsewhere.
+- A docstring describes step ordering `A then B`; the body does `B then A`.
+- A docstring references a sentinel marker (`# pragma: no-tdd-gate`) or filename shape (`test_code-rules-enforcer.py`) that the module body and the repo's naming convention do not use.
+
+## Division of labor
+
+This file is the **single thick source** for Category O judgment (sub-buckets O1–O9, the write-time gate inventory, free-form checklists, and worked examples).
+
+| Surface | Role |
+|---|---|
+| `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md` | Always-on write-time policy: the policy sentence, a compact checklist a writer applies at Write/Edit, and a pointer here. |
+| **This rubric** | On-demand thick home. The code-quality agent loads it per category. Holds every judgment standard, gate inventory, and worked example. |
+| `packages/claude-dev-env/audit-rubrics/prompts/category-o-docstring-vs-impl-drift.md` | Variant C audit template: source-material slots, forced-exhaustion protocol, adversarial probes, cross-bucket questions, output shape, and a PR worked example. Points here for the judgment standard. |
+
+Plainness for a general developer (diagram-first shape) also lives under O9; the write-time companion rule for that slice is `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`.
+
+**Companion reference:** see `../source-material-section-types.md`.
+
+---
+
+## Sub-bucket decomposition (Category O)
+
+Decomposition is by the **kind of docstring claim** that needs to be cross-checked against the implementation.
+
+| ID | Axis name | Concrete checks |
+|---|---|---|
+| O1 | Module-level responsibility verbs | A module docstring uses verbs (`detects`, `validates`, `enforces`, `recovers`, `parses`, `routes`) — every claimed responsibility is implemented by an exported symbol in the same module. Symbols absent from the module body should not appear as this module's responsibilities. A module whose one-line docstring scopes its contents to user-facing text (`User-facing strings: CLI flag names, help text, and log messages`) also names every category of constant the body holds. When the body also defines serialization field keys (`JSONL_FIELD_*`), run-metadata schema keys (`RUN_METADATA_CLI_ARG_KEY_*`), or runtime config (`STDOUT_ENCODING`, `MAIN_LOGGING_FORMAT_STRING`), the strings-only summary under-describes the module. Broaden the summary to name the data-schema keys and runtime config. The `check_module_docstring_scope_omits_data_schema_constants` gate blocks this drift at Write/Edit time when the summary claims a user-facing-text scope and names no data-schema or runtime-config category. |
+| O2 | Fixture docstring vs sibling-test behavior | An autouse / module-scope fixture docstring asserts an invariant (`readability is disabled`, `network is mocked`, `tmp_path is empty`). No sibling test in the same module explicitly opts out of the invariant. |
+| O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
+| O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. A docstring step enumeration that names the body's linear steps but omits a corrective workflow step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`) is also an O4 finding: the reader trusts the step list to be complete and misses the conditional path. The branch-guarded-dispatch shape of this drift — a docstring that names two or more linear-step callees while the body guards a two-or-more-token dispatch callee inside a branch whose name the prose never spells out — is gated deterministically at Write/Edit time by `check_docstring_step_enumeration_dispatch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`), so the audit lane focuses on the step-ordering shapes the gate cannot match (re-ordered steps, plain unguarded steps the prose omits). |
+| O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a \| b \| c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. A thin delegating method whose docstring names its actions and points at the home of the real body lists the same actions the delegated function's own summary lists; when an edit moves one action out of the delegated body, the same edit rewords both summaries (`check_docstring_delegation_summary_enumeration_drift`). A conditional bullet in the delegated prose also names every exception the body honors — that conditional-completeness slice stays a judgment call for this lane. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds. A dataclass or `TypedDict` field documented in the class `Attributes:` block states what the field means for one record; when the code sets that field the same way for every record (a run-mode flag such as `is_dry_run = not is_execute`), the description states the run-mode meaning, not a per-record outcome (`check_docstring_field_runmode_outcome` covers the single-file shape). Many deterministic O6 shapes are gated at Write/Edit time — see **Write-time gate inventory** below — so the audit lane focuses on the free-form shapes the gates cannot match. |
+| O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
+| O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. A producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) is the deterministic slice of this companion-doc producer/consumer drift (`check_docstring_no_consumer_claim`). |
+| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The diagram-first shape carries this best: a summary line, then a `::` example block or a doctest that shows a concrete input and its marked outcome, then a couple of short prose lines. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, and a narrative that runs more than six prose lines with no such block is gated by `check_docstring_prose_wall_without_illustration` in the same module, so this lane carries the judgment the gates cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read, and whether the diagram truly illustrates — a real input, a marked outcome, an `ok:` / `flag:` contrast a reader learns from. See `../../rules/plain-illustrative-docstrings.md`. |
+
+---
+
+## Write-time gate inventory
+
+Deterministic slices of Category O that fire at Write/Edit. The free-form rest stays judgment (this rubric + the audit prompt).
+
+### Python — `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`
+
+| Gate | Drift it blocks |
+|---|---|
+| `check_docstring_args_match_signature` | `Args:` section parameter names vs the signature. |
+| `check_docstring_delegation_summary_enumeration_drift` | Thin wrapper summary enumerates actions the same-named sibling summary omits (both save directions). |
+| `check_docstring_names_absent_type_checking_gate` | Docstring names a `TYPE_CHECKING` gate or `type-checking-gate` helper family while no identifier in the module carries the `type_checking` marker. |
+| `check_docstring_length_constant_superlative_vs_exact_gate` | Module docstring describes an integer `*_LENGTH` constant with a superlative or range word while every consumer compares `len(...)` with `==`/`!=` (exact-length gate). Scans the constant module's package tree. |
+| `check_docstring_fallback_branch_coverage` | Summary scopes a fallback to one condition while the body routes to that fallback from two or more early-return guards. |
+| `check_class_docstring_names_public_methods` | Class docstring is a single summary line while the class exposes two or more public methods the summary never names. |
+| `check_docstring_no_consumer_claim` | Producer docstring asserts no consumer reads its output yet. |
+| `check_docstring_returns_plural_cardinality` | `Returns:` names a dict-key prefix family with a plural noun while the returned dict holds exactly one key in that family. |
+| `check_docstring_args_single_line_scope_vs_span` | `Args:` scopes a finding to one named line while the body scopes through a `range(...)` span-intersection. |
+| `check_docstring_cardinal_count_matches_constant_family` | Docstring states a cardinal count of an outcome family and lists members, while the module references more members of the same `UPPER_SNAKE` family than the count names. Runs on test modules as well as production. |
+| `check_docstring_raises_unraisable_largezipfile` | `Raises:` names `zipfile.LargeZipFile` while the writer opens with `allowZip64` at its default of True. |
+| `check_docstring_no_network_claim_with_metadata_access` | Docstring promises a path returns without touching the network while the body calls path-metadata methods (`is_file`, `is_dir`, `exists`, `stat`, `lstat`). |
+| `check_docstring_step_enumeration_dispatch_coverage` | Step-enumeration docstring omits a two-or-more-token dispatch step the body guards inside a branch. |
+| `check_docstring_unguarded_malformed_payload_claim` | Docstring promises a malformed payload resolves to None while a payload subscript sits outside the try/except whose handler returns None. |
+| `check_docstring_field_runmode_outcome` | `Attributes:` entry for a run-mode flag field (name carrying `dry_run`) whose description carries a per-record write-outcome phrase and no run-mode phrase. |
+| `check_module_docstring_scope_omits_data_schema_constants` | Module summary claims user-facing-text scope while the body also defines data-schema or runtime-config constants. |
+| `check_module_docstring_names_public_checks` | One-line check-registry module docstring omits a public `check_*` function the module dispatches. |
+| `check_docstring_tuple_enumeration_match` | Docstring enumerates inline-code tokens that drift from the literal string tuple the body reads (a listed token the tuple lacks, or a tuple member the prose omits). |
+| `check_docstring_punctuation_mark_enumeration_coverage` | Docstring names some marks of a punctuation-glyph tuple by their English names but omits one the tuple holds. |
+| `check_docstring_no_inline_literal_claim` | Constants-module docstring asserts no literals appear inline in a companion file. |
+| `check_docstring_names_undefined_constant` | Docstring names an `UPPER_SNAKE` constant identifier nothing in the module backs. |
+| `check_docstring_runon_sentence` | Narrative run-on mark (O9 backstop). |
+| `check_docstring_prose_wall_without_illustration` | Narrative longer than six prose lines with no `::` / doctest illustration (O9 backstop). |
+
+### JavaScript / `.mjs` — `packages/claude-dev-env/hooks/blocking/code_rules_imports_logging.py`
+
+These are the `.mjs` slice of the same Category O standard. The Python AST docstring gates never inspect JavaScript source.
+
+| Gate | Drift it blocks |
+|---|---|
+| `check_js_resume_task_enumeration_coverage` | A `spawn<Role>Agent` JSDoc enumerates sibling `resume<Role>Agent` resume tasks and omits a `task === '<name>'` branch the resume body dispatches on. |
+| `check_js_returns_object_schemaless_branch` | `@returns {Promise<object>}` JSDoc whose body returns the same agent-spawn helper both with a `schema` options object and without one (schema-less branch resolves to a transcript string). |
+| `check_js_sibling_return_object_key_drift` | A `return { ... }` object literal whose key set misses exactly one key of a sibling return in the same function or module scope. Discriminated-union variants and two-or-more-key exit shapes are left alone. |
+| `check_js_bare_flag_return_directive` | A `return <name>: true`/`false` prose directive anywhere in the file that repeats a status flag a stated full-result contract rules out (no proximity or ordering check between the two). |
+
+---
+
+## Free-form judgment checklist (write time and audit)
+
+Read the body and the docstring side by side. Apply each check that matches the prose. When the body changes the set of behaviors it applies, the same edit updates the prose enumeration.
+
+- **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration.
+- **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. Gated form: `check_docstring_fallback_branch_coverage`.
+- **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch. Gated form: `check_docstring_step_enumeration_dispatch_coverage`.
+- **Delegation pointer summaries.** A thin delegating method whose docstring names its actions and points at the home of the real body lists the same actions the delegated function's own summary lists. Gated form: `check_docstring_delegation_summary_enumeration_drift`. A conditional bullet in the delegated prose also names every exception the body honors — judgment for this lane.
+- **JS/`.mjs` resume-task, `@returns` object, sibling return keys, bare-flag directives.** See the JavaScript gate inventory above.
+- **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun matches the count of keys in that family in the returned dict literal. Gated form: `check_docstring_returns_plural_cardinality`.
+- **Length-constant superlative vs exact gate.** A module docstring that describes an integer `*_LENGTH` constant with a superlative or range word matches how the code consumes the constant. Gated form: `check_docstring_length_constant_superlative_vs_exact_gate`.
+- **Args single-line scope vs span body.** An `Args:` entry that scopes a finding to one named line matches the line breadth the body scopes by. Gated form: `check_docstring_args_single_line_scope_vs_span`.
+- **Cardinal-count enumerations.** A docstring that states a count of an outcome family and lists those members names every member of that family the module references. Gated form: `check_docstring_cardinal_count_matches_constant_family`.
+- **Raises-clause reachability for `LargeZipFile`.** A `Raises:` clause that names `zipfile.LargeZipFile` matches a writer the body opens with ZIP64 forbidden. Gated form: `check_docstring_raises_unraisable_largezipfile`.
+- **Module summary scope versus data-schema constants.** A module whose one-line docstring scopes its contents to user-facing text names every category of constant the body holds. Gated form: `check_module_docstring_scope_omits_data_schema_constants`.
+- **Field meaning: run mode versus per record.** A dataclass or `TypedDict` field documented in the class `Attributes:` block states what the field means for one record. When the code sets that field the same way for every record, the description states the run-mode meaning. Gated form: `check_docstring_field_runmode_outcome` (single-file shape); assignment in another module stays judgment.
+- **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags keys the exclusion to the same axis the body's classification keys on. Read the body's actual branch condition, then state the exclusion on that same axis.
+- **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order or its content matches the producer function's docstring and body for that same artifact. The two move together in one commit, even when the producer edit does not touch the `.md` file.
+- **TYPE_CHECKING gate claim vs code.** A docstring that names a `TYPE_CHECKING` gate-detection step matches a module whose code handles TYPE_CHECKING. Gated form: `check_docstring_names_absent_type_checking_gate`.
+
+---
+
+## Worked example (union enumeration)
+
+A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
+
+```python
+read_names = (
+    attribute_read_names
+    | dynamic_literal_names
+    | _match_pattern_attribute_names(tree)
+    | _exported_names(tree)
+)
+```
+
+A docstring that enumerates "attribute read, augmented-assignment target, class-pattern keyword, literal `getattr`/`attrgetter`" but omits the `__all__` source (`_exported_names`) is drifted: a field whose name appears in `__all__` is treated as read, and the prose hides that. The fix adds the missing source to the enumeration so the list matches the union.
+
+---
+
+## Sample prompt
+
+The reusable Variant C template for Category O is in [`../prompts/category-o-docstring-vs-impl-drift.md`](../prompts/category-o-docstring-vs-impl-drift.md). Inline every changed module's docstring (module-level + every helper-function docstring whose function body was touched + every fixture docstring) alongside the symbols defined in the same module under `## Source material`.
+
+## Why Category O matters as its own bucket
+
+Signature-shaped claims — parameter names, return types, exceptions in the `Raises:` block — have a gate-time validator (`check_docstring_args_match_signature`) and signature-oriented audit categories to catch them. Free-form narrative prose in docstrings is the other half of the docstring contract: the part that tells a reader what the module is for, what the fixture does, what the predicate means. When that prose drifts from the body, the gate cannot catch it because there is no signature to compare against. Category O forces the audit teammate to list docstring claims and verify each against the body, the same way signature claims are verified against the body.
+
+A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have.

package/audit-rubrics/prompts/category-o-docstring-vs-impl-drift.md

@@ -1,5 +1,21 @@
+# Category O audit prompt (Variant C)
+
+**Judgment standard (thick source):** `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
+
+This file is the audit **template** only: source-material slots, forced-exhaustion protocol, adversarial probes, cross-bucket questions, output shape, and a worked example. For every sub-bucket's judgment standard, gate inventory, and free-form checklist, read the thick rubric above. Do not treat this prompt as a second full copy of the standard.
+
+## Division of labor
+
+| Surface | Role |
+|---|---|
+| Category O rubric | Single thick judgment source (O1–O9, gates, checklists, examples). |
+| **This prompt** | Variant C protocol shell that points at the rubric for judgment. |
+| `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md` | Always-on write-time policy + compact checklist. |
+
 Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
+Apply each sub-bucket's **judgment standard** from the thick rubric. The bullets under each sub-bucket here are protocol probes only.
+
 [ARTIFACT METADATA — include every changed module's docstring AND the exported symbols of that module so the audit can compare claim vs body]
 
 - Title / one-line summary: [TITLE]
@@ -20,39 +36,39 @@ ID prefix: `find`.
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **O1. Module-level responsibility verbs** ⭐ canonical O case
-- For every changed module, list the verbs the docstring uses (`detects`, `validates`, `enforces`, `recovers`, `parses`, `routes`). For each verb, name the exported symbol that delivers that responsibility. Verbs without a matching exported symbol are O1 findings.
-- Adversarial probes: (a) grep for the verb's noun-form in sibling modules — did a refactor move the responsibility out; (b) inspect the module's `__all__` (if present) — does every claimed responsibility appear; (c) check git log for recent splits — does the docstring still describe the pre-split scope.
+- Judgment: thick rubric O1 (responsibility verbs + user-facing-text vs data-schema scope).
+- Adversarial probes: (a) grep for the verb's noun-form in sibling modules — did a refactor place the responsibility elsewhere; (b) inspect the module's `__all__` (if present) — does every claimed responsibility appear; (c) check git log for recent splits — does the docstring still describe the pre-split scope.
 
 **O2. Fixture docstring vs sibling-test behavior**
-- For every changed fixture (especially `autouse=True` or module-scope), parse the fixture's docstring claims. For each claim, walk every test function in the same module — does any test explicitly opt out of the claimed invariant via a different fixture, `monkeypatch.setattr`, or environment override?
+- Judgment: thick rubric O2.
 - Adversarial probes: (a) grep for the fixture's invariant-setting call in test bodies — does any test re-call it with a different argument; (b) check for `pytest.mark.parametrize` arguments that reach a code path the fixture claim says is disabled; (c) check for explicit teardown / reset calls inside tests that contradict the fixture's blanket scope.
 
 **O3. Predicate-name and -docstring vs body breadth**
-- For every changed boolean helper, compare the helper's name and docstring to the body's `return True` branches. Every branch's True path must be consistent with the promised name.
+- Judgment: thick rubric O3.
 - Adversarial probes: (a) walk each `return True` branch and ask whether the input that reached it satisfies the name's promise; (b) construct an input class outside the named promise that still returns True — that is an O3 finding; (c) check the name against neighboring helpers — is one of them the better home for the broader case.
 
 **O4. Step-ordering narrative**
-- For every changed helper whose docstring describes processing as `step A then step B then step C`, trace the body and confirm the call order matches.
+- Judgment: thick rubric O4 (includes branch-guarded dispatch; gated form `check_docstring_step_enumeration_dispatch_coverage`).
 - Adversarial probes: (a) read the body strictly top-to-bottom and label each call A/B/C against the docstring's named steps; (b) check for early returns that reorder visible steps; (c) check for `try/finally` blocks where the finally clause is itself one of the named steps and runs out of declared order.
 
 **O5. Named-sentinel / filename references**
-- For every docstring mention of a sentinel marker (`# pragma: ...`), environment variable name, filename, or magic string, grep the module body and the broader repo for the named token. Tokens not present anywhere are O5 findings.
+- Judgment: thick rubric O5.
 - Adversarial probes: (a) grep the exact sentinel string in this module and sibling modules; (b) grep the named filename against the repo's naming convention (underscore vs hyphen); (c) check for case-sensitivity mismatches between the docstring and the body.
 
 **O6. Free-form `Args:`-adjacent claims**
-- For every docstring `Returns:` / `Raises:` / `Note:` / `Example:` section, extract each claim sentence. Verify each against the body. (The gate-time validator only checks `Args:` parameter names, not these adjacent sections.)
+- Judgment: thick rubric O6 (unions, suppressors, exclusion axis, delegation summaries, Returns/Raises/Note claims, run-mode field meaning). Gate inventory and free-form checklist live in the rubric.
 - Adversarial probes: (a) check `Returns:` claims against every `return` statement in the body — is the documented return shape the actual return shape; (b) check `Raises:` claims against every `raise` and propagating callee — is every documented raise reachable; (c) check `Example:` snippets — does the snippet actually compile against the signature.
 
 **O7. Module-doc-vs-split-module after refactor**
-- When the diff includes a module split (one file becomes two), verify both modules' docstrings describe the responsibility each one actually owns after the split.
-- Adversarial probes: (a) for each module in the split, list its exported symbols and compare to the docstring's claimed responsibilities; (b) grep the responsibility's verb against the originating module — does the originating docstring still claim what moved; (c) check for cross-module imports that reveal which file hosts each responsibility.
+- Judgment: thick rubric O7.
+- Adversarial probes: (a) for each module in the split, list its exported symbols and compare to the docstring's claimed responsibilities; (b) grep the responsibility's verb against the originating module — does the originating docstring still claim what left; (c) check for cross-module imports that reveal which file hosts each responsibility.
 
 **O8. Companion-doc ordering/content vs producer**
-- When the diff changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the diff never touched the `.md` file, because the behavior change orphaned the doc claim.
+- Judgment: thick rubric O8 (order/content claims vs producer; `check_docstring_no_consumer_claim` for the producer-only assertion slice).
 - Adversarial probes: (a) for each changed producer, name the artifact it builds and grep the skill's `SKILL.md` and sibling `.md` files for any sentence naming that artifact; (b) walk the producer body's build step — does it sort, or does it merge stored names and append in file order — and compare against the doc's order word (`sorted`, `alphabetical`); (c) check whether the doc's content claim (`just the at-risk names`, `only the current set`) hides merged-in prior entries the producer carries over from the stored file.
 
 **O9. Python docstring plainness for a general developer**
-- For every changed module / class / public-function docstring, read the narrative prose before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section as a stranger to the code. Flag a narrative that stacks abstract machinery nouns into a single wall, that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence past the word limit while joining clauses with an em-dash or a semicolon. The run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence`, so this lane judges the part the gate cannot: whether the prose paints a concrete scene — the moment the code matters, the input it sees, the outcome it produces — that a general developer follows on the first read.
+- Judgment: thick rubric O9 (and `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`). Run-on and prose-wall gates backstop the deterministic marks.
 - Adversarial probes: (a) read each changed narrative and name the concrete moment, input, and outcome it paints — a narrative that names none is an O9 finding; (b) count the longest sentence's words and check for an em-dash or semicolon join — over the limit with a join is the wall mark the gate also catches; (c) rewrite each "is not" clause as a positive statement — a clause that resists rewriting because the body offers no positive description is an O9 finding.
 
 ## Cross-bucket questions to answer at the end
@@ -65,7 +81,7 @@ Q3: Of the changed docstrings, which one most clearly shows a refactor was incom
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O9, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O9, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation left during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 
@@ -77,6 +93,6 @@ PR #522 split `pr_description_command_parser.py` into two modules — the origin
 
 Expected findings on PR #522:
 - **O1 finding:** `pr_description_body_audit.py:8` docstring uses verb `detects`, but the only exported symbol prepares input for a regex scan that fires in a different module. Body line(s) showing `_extract_vague_scan_text` returning normalized text without a detection call.
-- **O7 finding:** `pr_description_command_parser.py` module docstring still names PR-number recovery as a responsibility; the split moved that to `pr_description_pr_number.py`. The originating docstring needs an O7-shaped rewrite to drop the moved claim.
+- **O7 finding:** `pr_description_command_parser.py` module docstring still names PR-number recovery as a responsibility; the split placed that in `pr_description_pr_number.py`. The originating docstring needs an O7-shaped rewrite to drop the claim that left.
 - **O2 finding:** `test_pr_description_enforcer_readability.py` autouse fixture docstring claims readability is globally disabled `for these tests`; sibling tests in the same module explicitly re-enable readability through a different state path.
 - **O5 finding:** `code_rules_magic_values.py` docstring references a `# pragma: no-tdd-gate` sentinel and a hyphenated `test_code-rules-enforcer.py` filename; neither token exists in the module body or matches the repo's underscore-only test-file naming convention.

package/docs/CLAUDE.md

@@ -17,6 +17,7 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 | `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
 | `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
 | `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
+| `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
 
 ## Subdirectory
 

package/docs/references/CLAUDE.md

@@ -7,6 +7,7 @@ Pointer documents to external sources and standard terminology. Files here are l
 | File | Purpose |
 |---|---|
 | `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
+| `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
 
 ## Role
 

package/docs/references/code-review-enforcement.md

@@ -0,0 +1,97 @@
+# Code-review enforcement
+
+This feature ties two git actions to a clean run of the built-in
+`/code-review --fix`:
+
+- **`git push`** needs a clean review at effort **low** or higher.
+- **Pull-request creation** (`gh pr create` and the MCP `create_pull_request`
+  tool) needs a clean review at effort **xhigh** or higher.
+
+The gates follow the same shape as the `verified_commit` gate family.
+
+## How a stamp works
+
+A stamp is a small JSON file that records one fact: a clean `/code-review` pass
+ran against an exact branch surface at a given effort. Each work tree keeps one
+file under `~/.claude/code-review-stamps/`, named by a hash of the resolved
+work-tree path.
+
+The stamp binds to a **branch-surface hash** — the hash of every changed path
+and untracked file, each bound by its content digest, measured against the
+merge base. When any byte of the change surface moves, the live hash stops
+matching the stored hash, so the stamp stops covering the surface and the gate
+asks for a fresh review.
+
+A gate allows the action only when a stored stamp matches the live hash exactly
+and its effort ranks at or above the effort the action needs. A missing,
+unreadable, or malformed stamp reads as no coverage, so the gate fails closed.
+
+## The single sanctioned minter
+
+Only `invoke_code_review.py --record-stamp` writes a stamp. It forces a headless
+`/code-review <effort> --fix` run, then mints a stamp only when the review
+returns a clean exit code and leaves the branch surface unchanged in the same
+pass. A pass that applies fixes mints nothing; the run loops on the new surface
+up to a capped number of passes and mints only on a stable clean pass.
+
+## Two layers guard the stamp directory
+
+The gates trust one rule: only the sanctioned minter writes stamp files. Two
+layers hold that rule.
+
+1. **File-tool deny in `settings.json`.** `Write`, `Edit`, and `MultiEdit`
+   under `~/.claude/code-review-stamps/` are denied. This layer covers work
+   inside the repository. The installer merges hook groups into a user's
+   `settings.json` and does not ship this package's `permissions.deny`, so on a
+   user's machine this layer protects contributor work, at parity with the
+   `verified_commit` gate's own file-tool deny.
+2. **`code_review_stamp_directory_write_blocker` hook.** This hook ships through
+   `hooks.json`, so it reaches every install. It has two arms:
+   - a shell arm that denies any Bash or PowerShell command naming the stamp
+     directory, or importing the stamp store module, or calling its mint
+     function — while it lets the sanctioned minter command through;
+   - a file-tool arm that denies any `Write`, `Edit`, or `MultiEdit` whose path
+     resolves under the stamp directory. This arm closes the plain file-tool
+     forge on every shipped install, which the package `settings.json` deny
+     cannot reach on its own.
+
+## What the gates block
+
+- **Casual and accidental forges.** A plain file-tool write to the stamp
+  directory, and a casual shell write to it, are both denied.
+- **Hidden-path and split-step shell forges.** A shell command that assembles
+  the stamp path from hex, base64, or character math is decoded and denied. A
+  command that splits the directory change across steps to walk into the stamp
+  directory is traced and denied.
+- **Lazy skips.** A push or a pull-request creation cannot go ahead without a
+  stamp that matches the live surface at the needed effort.
+
+## What the gates do not block
+
+The chain-mode `/code-review` runs as a subprocess spawn of the `claude`
+binary, not a harness-recorded subagent, so there is no signed sidecar to
+anchor a forgery-proof mint. The stamp reaches the same posture the
+`verified_commit` gate holds, and no further. These bypass surfaces stay open:
+
+- **Pull requests that skip the tool paths.** A PR opened through
+  `gh api -X POST .../pulls` or the GitHub web page never triggers the
+  create-PR gate.
+- **`git push --no-verify`.** This flag tells git to skip the native pre-push
+  hook, so the native backstop does not run.
+- **A rebuilt store.** A script that re-implements the stamp store in memory
+  and writes a matching file can mint a stamp the gates accept.
+
+In short: these gates stop casual forges and lazy skips. They do not stop a
+determined attacker who sets out to defeat them.
+
+## Where the pieces live
+
+- Gates: `hooks/blocking/code_review_push_gate.py`,
+  `hooks/blocking/code_review_pr_create_gate.py`.
+- Stamp store: `hooks/blocking/code_review_stamp_store.py`.
+- Directory guard: `hooks/blocking/code_review_stamp_directory_write_blocker.py`.
+- Shared constants: `hooks/blocking/config/code_review_enforcement_constants.py`.
+- Native backstop: `hooks/git-hooks/pre_push.py` reuses the push gate's
+  `deny_reason_for_directory` so the native hook and the Claude gate share one
+  decision source.
+- Minter: `scripts/invoke_code_review.py --record-stamp`.

package/docs/wsl-docker-cowork-starter-matrix.md

@@ -0,0 +1,89 @@
+# WSL / Docker / Cowork starter matrix
+
+Attribution and policy surface for host memory consumers that sit under WSL2, Docker Desktop, and the Claude Cowork HCS VM. Source evidence: forensic capture summarized on [issue #256](https://github.com/jl-cmd/claude-dev-env/issues/256) (`results/05-wsl-who-started.md` in the local ram-process-sprawl evidence pack). This file records supported starters, whether each component is required for day-to-day agent work, and how to shut it down. It does **not** apply a `.wslconfig` memory cap.
+
+## Hard rules
+
+1. **No unmeasured `.wslconfig` memory cap.** Do not set `memory=` (or other hard caps) in `%UserProfile%\.wslconfig` until (a) the owner of the WSL VM commit is known for the workload under test and (b) a before/after private-working-set measurement is recorded on the same host boot window. A blind cap is out of scope for this matrix.
+2. **Proven starters only.** Rows below use only process-parent, service, HCS owner, registry, and product-log evidence from the capture. Proximity without a parent edge is labeled **unknown**, not a starter claim.
+3. **Two HCS VMs are not one.** Owner=`WSL` maps to `vmmemWSL`. Owner=`cowork-vm-*` maps to plain `vmmem`. Treat them as separate shutdown and policy targets.
+
+## Starter matrix
+
+| Component | Starter / owner (supported) | Required for daily agent work? | Shutdown / stop |
+|-----------|----------------------------|--------------------------------|-----------------|
+| **WSLService** (`wslservice.exe`) | Windows service **WSLService**, StartMode=Auto, parent `services.exe` since boot | **Platform yes** if any WSL2 distro is used; leave Auto unless WSL is retired on the host | `Stop-Service WSLService` only when deliberately disabling WSL; normal idle path is distro shutdown, not service kill |
+| **`vmmemWSL`** (WSL2 utility VM) | HCS VM Owner=`WSL`; worker chain `vmcompute` → `vmwp` → `vmmemWSL` | **Yes while any distro is Running** (`wsl -l -v`) | `wsl --shutdown` (stops all WSL2 distros and the WSL utility VM; disrupts Docker's WSL backend too) |
+| **First user wake of WSL VM** | **Unknown** in the capture (no Security 4688; no surviving user `wsl.exe` from the create second). Docker was **not** up yet at that create time | N/A — attribution gap | Same as `vmmemWSL` once running |
+| **Docker Desktop / `com.docker.backend`** | Docker Desktop launches backend (product log). **HKCU Run** key registers Docker Desktop for logon. Windows service `com.docker.service` was **Stopped** / Manual — engine path is Desktop/backend user-mode | **Only when containers or Docker tooling are in active use** | Quit Docker Desktop (tray → Quit); confirm `com.docker.backend` gone. Optional: remove or disable the HKCU Run value named `Docker Desktop` so logon does not relaunch it |
+| **Live `wsl.exe` for `docker-desktop` + Ubuntu integration** | Parent **`com.docker.backend.exe` (services)** | Same as Docker Desktop | Stop Docker Desktop; or `wsl --shutdown` (broader blast radius) |
+| **Live `wsl.exe` for `code-index-mcp`** | Parent **`codex.exe`** ← **ChatGPT.exe** ← explorer. Command shape: `wsl.exe …/code-index-mcp` | **Only while Codex/ChatGPT needs the Ubuntu MCP indexer** | Exit Codex / ChatGPT app-server session; confirm no `wsl.exe` whose command line is `code-index-mcp` |
+| **Plain `vmmem` (cowork HCS VM)** | HCS VM Owner=`cowork-vm-*` (name match). Chain `vmcompute` → `vmwp` → `vmmem`. **Exact user process that created the VM is unknown** (no live parent edge). Claude Desktop cmdlines carry `cowork-*` schemes; that is label association, not a proven create edge | **Only while Claude Cowork VM features are in use** | Quit Claude Desktop / Cowork UI that owns the session; if the HCS VM remains Running, treat full stop as an open procedure (see open questions). Do **not** assume `wsl --shutdown` stops this VM — it is not Owner=`WSL` |
+| **grok as WSL parent** | **None** in the capture (high-confidence negative) | N/A | N/A |
+| **claude as parent of live `wsl.exe`** | **None** in the capture (high-confidence negative) | N/A for WSL shells; see cowork row for the separate HCS VM | N/A for `wsl.exe` |
+
+### Capture facts that stay fixed for this matrix
+
+These are host-capture facts the matrix must not rewrite:
+
+- Docker autostart comes from the **HKCU `Run` key** entry for Docker Desktop (not the stopped `com.docker.service`).
+- **Codex `code-index-mcp`** is a live holder of `wsl.exe`; it is not the create-time owner of `vmmemWSL` when Codex starts hours later.
+- **cowork-vm** is a **separate** HCS VM and plain `vmmem` consumer; it is not `vmmemWSL`.
+- **grok** and **claude** were **not** parents of any live `wsl.exe` in the capture.
+
+## Open questions
+
+Named gaps only — do not fill these with guesses in policy or code:
+
+1. **Exact user-mode process that first woke the WSL VM** at the `vmmemWSL` create second (Security 4688 / Sysmon not available in the capture).
+2. **Exact process that created HCS `cowork-vm-*` / plain `vmmem`** (parent chain ends at `vmwp` / `vmcompute`).
+3. **Whether a given Docker start was pure logon Run vs interactive tray open** (Run key proves Docker can autostart; a dead parent PID on the backend does not by itself prove which path fired).
+4. **Identity of dead parents** of mid-session Ubuntu `wslhost` processes whose PPID is already recycled.
+5. **Documented, safe idle-stop for the cowork HCS VM** when Claude UI is gone but `hcsdiag` still lists Owner=`cowork-vm-*` Running.
+6. **Whether historical sessions of grok/claude started WSL earlier in a boot** — unprovable without process-creation audit history; live snapshot negatives do not extend backward.
+
+To close (1), (2), (4), or (6): enable process-creation audit (Security 4688) or Sysmon with filters on `wsl.exe`, `vmwp.exe`, and Docker/Claude/Codex image paths, then re-capture on a clean boot.
+
+## Policy options (with costs)
+
+Choose explicitly. None of these options includes an unmeasured `.wslconfig` `memory=` write.
+
+| Option | Action | RAM / sprawl effect (directional) | Cost / risk |
+|--------|--------|-----------------------------------|-------------|
+| **P0 — Observe only** | Keep matrix; no host change | None until a component is stopped | Continues dual-VM + Docker + Codex WSL hold when those apps run |
+| **P1 — Docker on demand** | Remove or disable HKCU Run `Docker Desktop`; start Desktop only when containers are needed | Avoids Docker backend + docker-desktop/Ubuntu integration `wsl.exe` on boots/sessions that never use Docker | Manual start latency; first container work pays cold start; any script that assumes Docker is already up fails until launch |
+| **P2 — Docker fully off when idle** | Quit Docker Desktop after use; optional P1 | Frees backend private set and Docker-held WSL distro activity | Must re-open Desktop before compose/build; `wsl -l -v` may still show Running until `wsl --shutdown` or Docker stops holding distros |
+| **P3 — Codex indexer off when idle** | Exit ChatGPT/Codex app-server when not reviewing; disable code-index MCP if product settings allow | Drops Codex-held `wsl.exe … code-index-mcp` edges | Codex features that need the Ubuntu indexer fail until restart; does **not** by itself tear down `vmmemWSL` if Docker or another client still holds a distro |
+| **P4 — WSL idle shutdown** | When no Docker/Codex/other WSL client is needed: `wsl --shutdown` | Tears down Ubuntu + docker-desktop distros and `vmmemWSL` | **Breaks** any live Docker WSL backend and any in-distro MCP until restart; never use mid-task if containers or WSL MCP are active |
+| **P5 — Cowork VM idle policy** | Quit Claude Cowork/Desktop when the VM is not needed; re-check `hcsdiag list` for Owner=`cowork-vm-*` | Targets plain `vmmem` (~multi-GB private in the capture) without touching Owner=`WSL` | Create/stop procedure for a leftover Running cowork VM is still an open question; wrong kill path can disrupt Cowork artifacts |
+| **P6 — Process-creation audit** | Turn on 4688 or Sysmon for wsl/vmwp/Docker/Claude/Codex | No direct RAM win; closes open questions (1)(2)(4)(6) | Audit volume, privacy review, and storage for event logs |
+| **P7 — `.wslconfig` memory cap** | Set `memory=` under `[wsl2]` | Caps WSL utility VM commit **only after** measured before/after on this host | **Blocked here until measured.** Risk: OOM inside distros, Docker backend instability, false “fix” that leaves cowork `vmmem` untouched |
+
+### Measurement gate for P7 (and any memory cap)
+
+Before any `.wslconfig` memory write:
+
+1. Record `wsl -l -v`, `hcsdiag list`, and private working set for `vmmemWSL` / plain `vmmem` / `com.docker.backend`.
+2. Name which component the cap is meant to bound (Owner=`WSL` only — cowork is outside `.wslconfig`).
+3. Apply cap; reboot or `wsl --shutdown` + re-start workload as required for the setting to apply.
+4. Re-record the same counters under the same workload.
+5. Commit the before/after note next to the policy decision (issue comment or evidence pack). Without that note, leave `.wslconfig` without a memory cap.
+
+## Quick identification commands
+
+Read-only checks agents and operators use on Windows:
+
+```text
+wsl -l -v
+hcsdiag list
+Get-CimInstance Win32_Service -Filter "Name='WSLService'"
+Get-ItemProperty HKCU:\Software\Microsoft\Windows\CurrentVersion\Run
+Get-CimInstance Win32_Process -Filter "Name='wsl.exe'" | Select ProcessId, ParentProcessId, CommandLine
+```
+
+Resolve each `wsl.exe` ParentProcessId to an image name before blaming an agent binary. A missing parent is **unknown**, not proof of a named starter.
+
+## Related
+
+- Issue: [jl-cmd/claude-dev-env#256](https://github.com/jl-cmd/claude-dev-env/issues/256) (child of epic #252)
+- Local forensic write-up: `results/05-wsl-who-started.md` under the host evidence pack path named in the issue body

package/hooks/blocking/CLAUDE.md

@@ -9,6 +9,7 @@ PreToolUse hooks that deny (block) tool calls when a rule is violated. The main
 | `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
 | `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
 | `verified_commit_gate_parts/` | Concern modules the `verified_commit_gate.py` entry hook wires together: command tokenization, directory-change resolution, gated git-invocation resolution, deny-reason resolution, and deny-payload assembly |
+| `code_review_stamp_write_blocker_parts/` | Concern modules the `code_review_stamp_directory_write_blocker.py` entry hook wires together: the split directory-change-into-stamp matcher and the obfuscated-stamp-path-write matcher |
 | `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
 | `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
 | `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |
@@ -71,7 +72,10 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `block_main_commit.py` | PreToolUse (Bash) | `git commit`/`git push` directly to `main` |
 | `bot_mention_comment_blocker.py` | PreToolUse (Write/Edit) | PR review comments that @-mention a bot |
 | `claude_md_orphan_file_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | Per-directory `CLAUDE.md` table cells naming a bare filename absent from the directory subtree |
-| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line |
+| `code_review_pr_create_gate.py` | PreToolUse (Bash/MCP GitHub) | `gh pr create` or the MCP `create_pull_request` tool without a clean `xhigh` code-review stamp covering the branch surface |
+| `code_review_push_gate.py` | PreToolUse (Bash/PowerShell) | `git push` without a clean `low` code-review stamp covering the branch surface |
+| `code_review_stamp_directory_write_blocker.py` | PreToolUse (Bash/PowerShell/Write/Edit/MultiEdit) | Shell or file-tool writes into `~/.claude/code-review-stamps/`, and shell references to the stamp store module or its mint call, outside the sanctioned invoker |
+| `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line, or the CODE_RULES engine fails to load |
 | `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
 | `conventional_pr_title_gate.py` | PreToolUse (Bash) | `gh pr create`/`gh pr edit` with a `--title` that is not a Conventional Commit, in a repo whose CI runs a semantic-pull-request title check |
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
@@ -121,6 +125,9 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
+| `code_review_enforcement_config_bootstrap.py` | Binds `config.code_review_enforcement_constants` to the sibling `config/` file by explicit location, so the code-review gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
+| `code_review_gate_deny.py` | Shared deny scaffold for the push and PR-create code-review gates: the `hookSpecificOutput` deny-payload builder and the log-and-emit helper, so both gates share one deny shape |
+| `code_review_stamp_store.py` | Reads and writes the per-work-tree code-review stamp files under `~/.claude/code-review-stamps/`, and decides whether a clean stamp at the needed effort covers the live branch surface |
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |