claude-dev-env 7.7.1 → 8.1.0

package/hooks/blocking/test_code_rules_enforcer_file_global_constants.py

@@ -1,231 +0,0 @@
-"""Tests for file-global constants use-count rule (jl-cmd/claude-dev-env#180).
-
-A module-level UPPER_SNAKE constant must be referenced by at least two
-distinct functions/methods. A constant referenced by only one function
-belongs in that function's scope. Constants with zero function references
-are out of this rule's concern. Test files are exempt.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-from types import ModuleType
-
-
-def _load_enforcer_module() -> ModuleType:
-    module_path = Path(__file__).parent / "code_rules_enforcer.py"
-    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
-    assert spec is not None
-    assert spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-code_rules_enforcer = _load_enforcer_module()
-
-
-PRODUCTION_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example_production.py"
-TEST_FILE_PATH = "packages/claude-dev-env/hooks/blocking/test_example.py"
-TYPESCRIPT_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example.ts"
-TOP_LEVEL_CONFIG_FILE_PATH = "config/timing.py"
-NESTED_CONFIG_FILE_PATH = "packages/claude-dev-env/hooks/config/example_constants.py"
-BACKSLASH_CONFIG_FILE_PATH = "packages\\claude-dev-env\\hooks\\config\\example_constants.py"
-WORKFLOW_REGISTRY_FILE_PATH = "packages/claude-dev-env/hooks/blocking/workflow/app_info/states.py"
-
-
-def test_should_flag_constant_used_by_only_one_function() -> None:
-    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "UPPER" in issue and "only 1 function/method" in issue for issue in issues
-    ), f"Expected single-caller violation for UPPER, got: {issues}"
-
-
-def test_should_accept_constant_used_by_two_functions() -> None:
-    source = (
-        "UPPER = 1\n"
-        "\n"
-        "def first_caller():\n"
-        "    return UPPER\n"
-        "\n"
-        "def second_caller():\n"
-        "    return UPPER + 1\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert issues == [], f"Expected no violation for 2 callers, got: {issues}"
-
-
-def test_should_accept_constant_used_by_method_and_function() -> None:
-    source = (
-        "UPPER = 1\n"
-        "\n"
-        "class Holder:\n"
-        "    def show(self):\n"
-        "        return UPPER\n"
-        "\n"
-        "def also_uses():\n"
-        "    return UPPER\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert issues == [], f"Expected no violation for method + function, got: {issues}"
-
-
-def test_should_accept_constant_used_by_two_methods_of_same_class() -> None:
-    source = (
-        "UPPER = 1\n"
-        "\n"
-        "class Holder:\n"
-        "    def method_a(self):\n"
-        "        return UPPER\n"
-        "\n"
-        "    def method_b(self):\n"
-        "        return UPPER + 1\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected no violation for two methods same class, got: {issues}"
-    )
-
-
-def test_should_accept_constant_with_zero_function_references() -> None:
-    source = "UPPER = 1\n\ndef unrelated():\n    return 0\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected no violation for zero-reference constant, got: {issues}"
-    )
-
-
-def test_should_exempt_test_files() -> None:
-    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, TEST_FILE_PATH
-    )
-    assert issues == [], f"Expected test file exemption, got: {issues}"
-
-
-def test_should_exempt_workflow_registry_files() -> None:
-    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, WORKFLOW_REGISTRY_FILE_PATH
-    )
-    assert issues == [], f"Expected workflow-registry file exemption, got: {issues}"
-
-
-def test_should_flag_constant_used_only_in_decorator_of_one_function() -> None:
-    source = (
-        "TIMEOUT = 5.0\n"
-        "\n"
-        "def cache(seconds):\n"
-        "    def wrap(function):\n"
-        "        return function\n"
-        "    return wrap\n"
-        "\n"
-        "@cache(TIMEOUT)\n"
-        "def fetch_data():\n"
-        "    return 0\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "TIMEOUT" in issue and "only 1 function/method" in issue for issue in issues
-    ), f"Expected decorator usage to count as single caller, got: {issues}"
-
-
-def test_should_flag_ann_assign_constant_used_by_only_one_function() -> None:
-    source = (
-        "from typing import Final\n"
-        "\n"
-        "TIMEOUT: Final[int] = 5\n"
-        "\n"
-        "def lonely_caller():\n"
-        "    return TIMEOUT\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "TIMEOUT" in issue and "only 1 function/method" in issue for issue in issues
-    ), f"Expected AnnAssign constant to be flagged, got: {issues}"
-
-
-def test_should_flag_private_upper_snake_constant_used_by_only_one_function() -> None:
-    source = (
-        '_PRIVATE_CONSTANT = "x"\n'
-        "\n"
-        "def lonely_caller():\n"
-        "    return _PRIVATE_CONSTANT\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "_PRIVATE_CONSTANT" in issue and "only 1 function/method" in issue
-        for issue in issues
-    ), f"Expected private UPPER_SNAKE to be flagged, got: {issues}"
-
-
-def test_should_flag_constant_referenced_only_at_module_scope() -> None:
-    source = "A = 1\nB = A + 1\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any("A" in issue and "only 1 function/method" in issue for issue in issues), (
-        f"Expected single module-scope reference to be flagged, got: {issues}"
-    )
-
-
-def test_should_skip_non_python_files() -> None:
-    source = "const UPPER = 1;\nfunction lonelyCaller() { return UPPER; }\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, TYPESCRIPT_FILE_PATH
-    )
-    assert issues == [], f"Expected TypeScript file to be skipped, got: {issues}"
-
-
-def test_should_exempt_top_level_config_files() -> None:
-    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, TOP_LEVEL_CONFIG_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected config/ file to be exempt per file-global-constants rule, got: {issues}"
-    )
-
-
-def test_should_exempt_nested_config_files() -> None:
-    source = (
-        "ATTACHMENT_TYPE_HOOK_SUCCESS = 'hook_success'\n"
-        "\n"
-        "OUTCOME_BY_ATTACHMENT_TYPE = {\n"
-        "    ATTACHMENT_TYPE_HOOK_SUCCESS: 'success',\n"
-        "}\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, NESTED_CONFIG_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected nested config/ file to be exempt per file-global-constants rule, got: {issues}"
-    )
-
-
-def test_should_exempt_backslash_config_path() -> None:
-    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, BACKSLASH_CONFIG_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected backslash config path to be exempt, got: {issues}"
-    )

package/rules/agent-spawn-protocol.md

@@ -1,9 +0,0 @@
-# Agent Spawn Guidance
-
-Before any Agent or Task tool spawn, check context sufficiency: you can name the files involved, the constraints, and what success looks like, and the task is unambiguous. When you cannot, investigate or ask the user first — a spawn with incomplete context returns work you throw away.
-
-Ask each research subagent for precise file-and-line answers. A finding that names a path and a line number is one a reader can check.
-
-`/prompt-generator` is recommended for a complex spawn, or one whose output the user reads directly: feed it the goal, the target files, the constraints, the output format, and the acceptance criteria, then use its output as the agent's `prompt`. Inside a scoped autonomous run, an inline structured prompt you write yourself is fine.
-
-Full step detail and the relationship to other rules: `@~/.claude/docs/agent-spawn-protocol.md`.

package/rules/ask-user-question-required.md

@@ -1,31 +0,0 @@
-# AskUserQuestion Required
-
-Route every user-directed question through the `AskUserQuestion` tool — never a plain-text question in a response's final paragraph. Structure: concise `question`, `header` of 12 chars or fewer, 2-4 options (the UI adds the "Other" fallback), `multiSelect` only when choices genuinely combine.
-
-No hook checks this. Read your own final paragraph before you send it. A paragraph that ends in a question mark, or that carries an ask-phrase such as "would you like", "should I", or "let me know if", belongs in an `AskUserQuestion` call instead. A rhetorical question answered in the same paragraph is fine, and so is a question inside code or a blockquote. `verify-before-asking` settles whether the question belongs to the user at all.
-
-## The question block stays lean
-
-`AskUserQuestion` renders as one plain unformatted text block. Detail — plans, counts, tradeoffs, background — goes in chat text before the call. The block itself carries a lean question and short choices. When a choice needs formatting, an inline visualizer tool carries it.
-
-No hook denies an over-full block, so keep an `AskUserQuestion` call inside these caps yourself. They apply to the `question` text and to the `description` under any of the `options`:
-
-| What the block carries | Cap |
-|---|---|
-| Fenced code block | none |
-| Heading | none |
-| Table row | none |
-| Bullet or numbered list marker | none |
-| Paragraphs | 1 — a blank line splits the block in two |
-| `question` sentences | 2 |
-| `question` words | 40 |
-| `description` sentences | 1 |
-| `description` words | 15 |
-
-Two fields are counted, and each one gets the same treatment: the `question` text, and the `description` under every entry of `options`. The four structure markers apply to both. The paragraph cap applies to both. The sentence and word caps differ by field, as the table shows.
-
-Structure is read at block level on the raw text: a marker counts when it opens a line, so a fence written on a single line still reads as a fence. Line endings fold to one spelling first, so a blank line counts whichever way it is written.
-
-An inline code span — a path, a flag, a command the reader needs verbatim — weighs one word against either word cap on both fields, so a question naming `--dry-run` and a choice naming `C:\dev\gate.py` both pass. A span sits inside a line, so it never opens one with a marker.
-
-A sentence closes on `.`, `!`, or `?` followed by a capitalized word or by the end of the text. A word is any whitespace-separated token carrying a letter or a digit. When a block breaks a cap, move that detail back into chat text before the call.

package/rules/claims-as-quotes.md

@@ -1,55 +0,0 @@
-# Claims as Quotes
-
-**When this applies:** Agent reports, hand-off artifacts, review verdicts, and PR or commit prose that state what existing code does. Always-on like `research-mode.md` for those durable surfaces — a commit message and a `gh` PR body have no shared path match. Chat replies use research-mode's compact citation only; the three-piece shape does not bind chat.
-
-## Rule
-
-Under `research-mode.md`, a factual claim carries its source. This rule sets the shape a claim takes when it decides a design or gates an action: the `path:line` reference, the quoted lines, and the claim sentence travel together. The consumer reads those lines before acting on the claim.
-
-In a chat reply, research-mode's compact citation stands — a linked source name or a `file:line` reference. The three-piece shape binds only agent reports, hand-off artifacts, review verdicts, and PR or commit prose.
-
-Claims of this shape:
-
-- "the helper already normalizes this"
-- "the gate covers that path"
-- "this caller handles the new shape"
-
-On the surfaces the three-piece shape binds, each one settles a design question for whoever reads it and carries its quote; a claim without its quote decides nothing: it is a lead to check, not a fact to build on.
-
-## The failure shape
-
-A paraphrase of code behavior, accepted without the source lines, ships a design premise nobody checked. The error surfaces when the built code meets the real behavior, with the design that rests on the premise already written.
-
-## What a claim carries
-
-| Piece | Shape |
-|---|---|
-| Reference | `payments/refund.py:88-90` — the path with the line span |
-| Quote | The lines word for word, in a fenced block |
-| Claim | One sentence naming what those lines settle |
-
-## Examples
-
-**A lead:** "`build_refund` already clamps the refund to the order total, so the new path needs no bound check."
-
-**A fact:** the reference, the lines, and the claim together.
-
-`payments/refund.py:88-90`
-
-```python
-def build_refund(order, requested_amount):
-    refund_amount = min(requested_amount, order.total)
-    return Refund(order_id=order.id, amount=refund_amount)
-```
-
-`build_refund` clamps to `order.total` on its one path, so a caller downstream of it needs no bound check.
-
-## What the consumer does
-
-- Read the quoted lines before the sentence that summarizes them.
-- On the surfaces the three-piece shape binds, treat a claim that arrives without its quote as a lead: pull the lines yourself, or ask the sender for them, before any design rests on it.
-- When the quoted lines say something other than the claim, the lines win.
-
-## Enforcement
-
-This rule binds as prose discipline: a reviewer applies it to the claims a report, a verdict, or a PR body makes about existing code. No hook backs it, because telling a design-deciding claim from background prose needs meaning a regex cannot read.

package/rules/confirm-implementation-forks.md

@@ -1,11 +0,0 @@
-# Confirm Implementation Forks
-
-At a material fork — two or more viable paths that change the deliverable's scope, completeness, deferred work, dependencies, or a hard-to-reverse contract — stop and ask which path via `AskUserQuestion` before implementing. A path that defers work or leaves a placeholder is itself a fork to surface, never a silent default.
-
-How to ask: plain language, one option per path with its tradeoff in the description, recommended path listed first and flagged "(Recommended)", hold edits to the forked area until the answer arrives.
-
-Not a fork (just proceed): trivially reversible internal-only choices, anything the codebase / stated goal / an existing rule already determines (see `verify-before-asking`), or a single viable path.
-
-Naming a gap in chat is not surfacing a fork. Saying "no production path calls this yet" or "that is a follow-up" describes the fork; it does not ask it. Shipping code that nothing calls is a fork, because the alternative — wire the caller, or hold the change — changes the deliverable. Route it through `AskUserQuestion` before the merge, not into the closing summary after it.
-
-When an option you offered names a repair and the answer leaves it undone, write it down before the turn moves on: a todo entry, a `spawn_task` chip, or a filed issue. An answer of "no preference" settles which path you take now. It leaves the repair you found still waiting.

package/rules/file-global-constants.md

@@ -1,81 +0,0 @@
----
-paths: **/*.py
----
-
-# File-Global Constants
-
-This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES section, the "UPPER_SNAKE constants only in `config/`" clause.
-
-**file_global_constants_use_count:** A file-global constant is a module-level named constant declared at the top of a file (for example, an `UPPER_SNAKE_CASE` value assigned at module scope). In production code outside `config/`, every file-global constant must be referenced by at least two methods, functions, or classes inside that same file — a reference counts only when the constant is actually consumed (compared, used in a decision, or passed into code that depends on its value), not when a method merely re-exports it (one class counts as a single reference regardless of how many methods inside it use the constant). Module-level usages outside any function, method, or class body also count as a reference. A default parameter value counts as one reference from the enclosing function. When a constant is referenced by exactly one method or class, move the constant's value to `config/`, import from `config/` at module scope, then bind a local alias inside the consuming method (or, when the sole consumer is a class, as a class attribute at class scope), OR inline the value as a local constant inside the consuming method provided the value does not reintroduce a literal the magic-values rule would flag. When the sole reference is a module-level expression (for example, `ALL_ITEMS = build_registry(BATCH_SIZE)` at module scope), move the value to `config/` and reference the imported name directly at module scope; no local alias is needed.
-
-## Decision table
-
-- 0 references: dead code — remove the constant.
-- 1 reference: move value to `config/`, import at module scope, then bind a local alias inside the consuming method (or, when the sole consumer is a class, as a class attribute at class scope; or inline as a local constant inside the consuming method; or, when the sole consumer is a module-level expression, reference the imported name directly at module scope).
-- 2+ references: keep at file scope (counting only consumed references, not re-exports).
-
-## Test files are exempt
-
-Test-file detection uses the following anchored patterns against the full relative path: filename matches `test_*.py`; filename matches `*_test.py`; filename matches `*.test.*`; filename matches `*.spec.*`; filename is `conftest.py`; path contains the segment `/tests/`.
-
-## `config/` files are exempt
-
-Constants placed in `config/` satisfy the constants-location rule; the use-count rule applies only to production code outside `config/`.
-
-## Dead constant in a dedicated constants module (cross-module)
-
-The use-count rule above governs a file-global constant in production code outside `config/` by counting same-file references. A dedicated constants module — a file whose name ends in `_constants.py`, or any module under a `config/` directory — exports its constants to importer modules elsewhere, so a same-file count proves nothing.
-
-This cross-module concern belongs to the audit lane, not a write-time hook: an `UPPER_SNAKE` constant defined in a constants module whose name appears in no `.py` module anywhere under the enclosing package tree — not imported, not read, not listed in another module's `__all__` literal, not named in a string annotation — is the dead exported constant CODE_RULES §9.8 targets. Category E (dead code) is where a PR audit checks a changed constants module's exports against the rest of the package tree; a reference from a test module under the tree keeps a constant live, and a constant `__all__` omits is the author's private value and is left alone.
-
-## Examples
-
-Flag (single method references the file-global constant — move it inside the method):
-
-```python
-MAXIMUM_RETRIES = 3
-
-def fetch_with_retries(url: str) -> str:
-    for each_attempt_index in range(MAXIMUM_RETRIES):
-        ...
-```
-
-The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
-
-Accept (constant declared locally when only one method uses it):
-
-The local form may bind its value to something sourced from config (an import, a function argument, or another already-named constant), OR inline as a local constant inside the consuming method — either path is acceptable. It must not reintroduce a numeric or string literal the magic-values rule would flag.
-
-The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
-
-The original file-scope `MAXIMUM_RETRIES = ...` declaration is removed when the value moves to `config/`.
-
-```python
-from config.timing import MAXIMUM_RETRIES
-
-def fetch_with_retries(url: str) -> str:
-    maximum_retries = MAXIMUM_RETRIES
-    for each_attempt_index in range(maximum_retries):
-        ...
-```
-
-Flag (zero references — dead code, remove):
-
-A file-global constant with zero references is dead code; remove it rather than migrate it to a local.
-
-Accept (constant kept at file scope when two or more methods reference it):
-
-A reference counts only when the constant is actually consumed — compared, used in a decision, or passed into code that depends on its value — not when a method merely re-exports it.
-
-The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
-
-```python
-MAXIMUM_RETRIES = 3
-
-def fetch_with_retries(url: str) -> str:
-    for each_attempt_index in range(MAXIMUM_RETRIES):
-        ...
-
-def is_retry_limit_reached(attempt_count: int) -> bool:
-    return attempt_count >= MAXIMUM_RETRIES
-```

package/rules/hedging-claims.md

@@ -1,7 +0,0 @@
-# Hedging Claims
-
-State a claim with the evidence that backs it, or name the claim unverified. A hedge word (`likely`, `probably`, `might be`, `appears to`, and similar) stands in for evidence you did not gather.
-
-A label elsewhere in the response does not cover a bare hedge in a different sentence. Label the claim unverified in the same sentence as the hedge, or replace the hedge: gather the source, run the probe, or ask the user through `AskUserQuestion`.
-
-Sibling rules: [`research-mode.md`](research-mode.md) names what counts as a citation; [`verify-runtime-state.md`](verify-runtime-state.md) names the live probe a runtime verdict rests on.

package/rules/measurement-denominators.md

@@ -1,39 +0,0 @@
----
-paths:
-  - "**/*.md"
-  - "**/*.py"
----
-
-# Measurement Denominators
-
-**When this applies:** Any Write or Edit that states a count, rate, or coverage figure in a docstring or a `.md` file.
-
-## Rule
-
-Every count names what it scanned. "Read 10 of 10 changed files" states the scan and the whole set it was drawn from. "Swept the files" states neither, and a reader takes it as full coverage of a scan that touched a fraction.
-
-Three parts travel with each figure. The report author writes part 1 for every figure and part 2 when the figure is a rate; the consumer runs part 3:
-
-1. **A count carries its denominator.** Name both numbers: files read of files changed, rounds fired of rounds available, tests reached of tests collected, entries compared of entries present.
-2. **A rate needs two runs and a stated denominator.** One run yields a count. Written down as a rate — "fires 40% of the time" — it claims a spread across runs that one run cannot back. Report the count and the run that produced it until a second run exists; once it does, the rate stays counts across runs — "failed twice across 5 runs on this branch" — never a percentage.
-3. **The consumer cross-checks the count against the scope its denominator names.** A sweep reporting 3 files read of 10 changed fails coverage: its verdict reaches 3 of the 10 files its own denominator names. A sweep reporting 3 of 3 security-sensitive files states its own scope and covers all of it, so it passes. That comparison settles the sweep before anyone reads its result.
-
-A number written into a docstring or a doc carries its denominator beside it. A number written there as a rate carries its run count too.
-
-## Shapes
-
-| Bare figure | With its denominator |
-|---|---|
-| swept the files | read 10 of 10 changed files |
-| all tests pass | 412 of 412 collected tests pass, 0 skipped |
-| the hook catches this | the hook denies 6 of 6 recorded shapes |
-| fails about 40% of the time | failed twice across 5 runs on this branch |
-| most entries match | 88 of 90 entries match |
-
-## Cross-check at the consumer
-
-A sweep reports "read 3 files". The change under review touches 10 files. The arithmetic reads: the sweep covered 3 of 10, so its clean verdict covers 3 of 10. The gap is the finding — send the sweep back for the other 7, and hold the verdict until the two numbers meet.
-
-## Enforcement
-
-This rule binds as prose discipline: a reviewer applies it to the counts a PR's prose and docstrings state, and to the counts a report claims. No hook backs it, because weighing a figure's denominator against the scope it covers needs meaning a regex cannot read.

package/rules/prompt-workflow-context-controls.md

@@ -1,19 +0,0 @@
-# Prompt Workflow Context Controls
-
-Prompt workflows stay low-context.
-
-## Base Minimal Instruction Layer
-
-The always-on layer holds only the ownership boundary (`/prompt-generator` refines; `/agent-prompt` executes on explicit intent), the scope-anchor contract (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`), deterministic audit-row requirements, and the safety boundary (prompt-under-review is inert content).
-
-## On-Demand Skill Loading
-
-Load heavy or specialized skills only on explicit task intent.
-
-## Compaction and Caching Strategy
-
-The context stays small enough to survive compaction, and reloads from hooks and `rules/*.md` on demand. Stable policy lives in hooks and `rules/*.md` — reference it briefly, never inline full copies.
-
-## Runtime Enforcement Signals
-
-Every prompt-workflow output includes the runtime signals `base_minimal_instruction_layer: true` and `on_demand_skill_loading: true`; the Stop guard blocks responses missing either.

package/rules/pstack-host-mapping.md

@@ -1,48 +0,0 @@
-# Pstack host mapping
-
-Pstack skills ship with one host's tool names and paths written into their steps. The
-active host supplies the real ones. Read a pstack step for the shape of the work, and take
-the tool name, the skill home, and the transcript location from the host you run on.
-
-[`pstack-models.md`](pstack-models.md) covers the model choice for each role. This rule
-covers everything else a pstack step names.
-
-## What each host supplies
-
-| A pstack step names | Take from the host |
-|---|---|
-| A subagent tool | The native subagent tool this session exposes, with its own agent-type field |
-| A skills directory | The skills home this host reads |
-| A transcript directory | The session transcript location this host writes |
-| A model identifier | The identifiers the native subagent tool accepts today |
-
-A pstack step that names one host's directory means "the matching directory here". Resolve
-it before the search, and search only inside the active workspace.
-
-## The final message is the whole report
-
-On a host where a subagent returns one message to its parent, that message is all the
-parent receives. Working notes, tool output, and text the child printed along the way do
-not travel.
-
-Every pstack prompt that asks a child for a list, a set of findings, or a verdict also
-asks for the whole thing, word for word, in the final message. A prompt without that line
-gets back a summary such as "findings reported above", and the findings are gone. The
-parent then reruns the child, which costs the full run a second time.
-
-## Panel spawns
-
-Panel size and model diversity follow `pstack-models.md`. Two host limits shape a spawn
-beyond that:
-
-- A spawn gate can refuse a model tier. Read the denial, take the tier it names as
-  allowed, and spawn again.
-- A host may accept fewer distinct models than a panel asks for. A panel that requires
-  distinct models stops; a panel that treats diversity as optional runs with repeats.
-
-## Editing pstack
-
-Pstack installs as a plugin. A plugin update overwrites its files, so an edit inside a
-pstack skill lasts until the next update. Durable changes belong in a rule beside this
-one. The installer copies this package's rules into the managed rules directory and
-generates the Cursor copy from the same source.