@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/code-craft-markdown.md

@@ -0,0 +1,138 @@
+---
+name: "code-craft-markdown"
+description: "Per-language code-craft for Markdown / prose artifacts — purpose-driven structure, sentence-level justification, precision over politeness, active-voice construction, hedge-elimination per the clean-room generation projection. Honors host's ratified Markdown linter (markdownlint, vale, prose-linter) and frontmatter conventions; passes the host's lint clean."
+pathFilter: "**/*.md, **/*.markdown"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Code Craft — Markdown
+
+## What this rule enforces
+
+This rule binds **M13 — Code Craft Conventions** at the **Markdown / prose per-language tier**. Every Markdown artifact the agent produces — README, ADR, RFC, design document, runbook, contributing guide, changelog entry, documentation page, response prose, commit-message body — MUST meet a sentence-level craft floor: **purpose-driven structure** (shape derived from communication purpose, not a generic template); **sentence-level justification** (every sentence advances the purpose; removable sentences MUST NOT exist); **precision over politeness** (exact words; pre-landing hedges removed); **active-voice construction** (concrete subjects, specific verbs); **hedge-elimination** in prescriptive contexts. The rule extends `rules/clean-room-generation.md` §5 (Prose and Documentation) into the per-language code-craft surface.
+
+## Pre-conditions
+
+Applies whenever a Markdown artifact (any file matching the `pathFilter` globs — `*.md`, `*.markdown`) is authored, modified, or reviewed. Fenced code blocks remain governed by the per-language code-craft rule for the block's language (`python` → `rules/code-craft-python.md`; `bash` → `rules/code-craft-shell.md`); this rule governs the surrounding prose, document structure, link discipline, and frontmatter.
+
+## Required behavior
+
+### 1. Purpose-Driven Structure
+
+Every Markdown artifact has a communication purpose; structure follows purpose:
+
+| Purpose class | Structure shape | Why |
+|---|---|---|
+| **Tutorial** | Sequential walkthrough; reader proceeds top-to-bottom | The reader's mental model is built incrementally |
+| **How-to guide** | Goal-then-steps; prerequisites, then ordered steps | The reader knows what they want and seeks the recipe |
+| **Reference** | Random-access entries; alphabetical or topical index | The reader looks up a specific item, not a sequence |
+| **Explanation** | Concept-then-elaboration; progressive disclosure | The reader builds understanding from primitives outward |
+| **Architecture document (ADR / RFC / design)** | Context · Decision · Consequences · Alternatives | The reader audits the reasoning behind a structural choice |
+| **Runbook** | Trigger · Diagnosis · Action · Verification · Rollback | The reader is on-call and needs the next step under pressure |
+
+The structure is **not** imported from a template "because documents like this usually have them". When a section's content does not advance the purpose, the section is removed. When an unconventional section is required by the purpose, the section is added with a purpose-explanatory header rather than forced into a generic shape.
+
+### 2. Sentence-Level Justification
+
+Every sentence MUST advance the purpose. Three failure classes are eliminated at authoring time:
+
+- **Filler.** "In this section, we will discuss …" / "It is important to note that …" / "As mentioned earlier …" — meta-commentary about the document, not substance. Remove.
+- **Throat-clearing.** "Before diving in …" / "Without further ado …" / "Let's begin by …" — openings that delay substance. Remove, or replace with the substantive opening.
+- **Restatement.** A sentence re-stating the prior one in different words. Compress to one.
+
+The test: remove the sentence — does the document still advance the purpose? Yes → it was filler; remove it. No → it is load-bearing; keep it.
+
+#### 2.1 Prose-over-lists default; one question per turn
+
+Prose is the default carrier; a list earns its place only when the content is **genuinely enumerable** — a set of parallel items, an ordered sequence of steps, a lookup table — where the list structure makes the parallelism or order legible. A conversational answer, an explanation, or a single recommendation stays prose: a bulleted list of one or two items, or a list that fragments a continuous argument into disconnected stubs, is a list imposed where prose carries the meaning better. The reach for a list is justified by the content's structure, not by the habit of bulleting.
+
+When prose elicits a decision, ask **at most one question per turn**. Batching several questions into one turn forces the reader to track and answer them in parallel and buries the load-bearing one; surface the single most decision-blocking question, resolve it, then surface the next. (Structured-inquiry invocations route through `rules/interactive-questions.md` and carry their own option-set shape; this is the prose-surface floor for the conversational case.)
+
+### 3. Precision Over Politeness
+
+Exact words. Specific claims. Numbers with units. Conditions stated:
+
+- **Right:** "The function returns null when the key is missing."
+- **Wrong:** "The function may return null in certain cases."
+
+Hedge words that soften a binding prescription MUST be removed. The hedging-vocabulary discipline at `rules/definitiveness.md` (M8) applies in full: **maybe · might · could · should probably · usually · generally · typically · mostly · often · perhaps · possibly · somewhat · fairly · roughly · broadly** are eliminated where binding prescription is possible. Where the claim genuinely is conditional, the conditions are enumerated explicitly: "The function returns null when the key is missing OR when the value is `None`."
+
+Content-free qualifiers ("very", "quite", "somewhat", "rather", "fairly", "kind of") are noise — remove them; the unqualified claim is stronger and shorter.
+
+### 4. Active-Voice Construction
+
+Active voice. Concrete subjects. Specific verbs.
+
+- **Right:** "The scheduler assigns tasks to workers."
+- **Wrong:** "Tasks are assigned to workers by the scheduler."
+- **Worse:** "Tasks are assigned to workers." (passive without actor — responsibility undiagnosable.)
+
+Passive voice is permitted in two cases only: (a) the actor is genuinely unknown or irrelevant ("The configuration is loaded from disk at startup"); (b) the patient is the topical focus and inverting would obscure the topic ("The bug was introduced in commit abc123"). Outside these cases, use active voice.
+
+### 5. Frontmatter Discipline
+
+When the host's Markdown corpus uses frontmatter (the artifact's first non-empty line is `---`), the frontmatter MUST conform to the host's discovered schema:
+
+- **Required fields per artifact class.** The host's per-class contract (rule files require `name` + `description`; skill files require `name` + `description`; documentation pages may require `title` + `summary` + `tags`) is honored per `rules/host-discovery.md`.
+- **Field shape.** Every required field is non-empty (per the PreToolUse Write hook validation at the hooks pipeline). Booleans are `true` / `false` (not `yes` / `no` unless the host's discovered convention uses them). Lists use the host's ratified shape (block `- item` or flow `[item, item]`).
+- **Field order.** Sibling frontmatter ordering is preserved; new fields land at the host-ratified position, not at top or bottom by default.
+
+### 6. Link Discipline
+
+Every link MUST be **resolvable** at emission time:
+
+- **Internal links.** Links to host files resolve to existing files; anchors resolve to existing headings. When documenting placeholder link syntax, spell it `text -> path/to/file.md` or `text -> path/to/file.md#section` (not as a live link).
+- **External links.** Permalinked where possible — commit-pinned over branch-pointed; archived versions where the canonical source may rot.
+- **Cited material.** Quotes and paraphrases carry the source as a link or footnote citation. Folklore claims (no source) are removed or sourced.
+
+Stale links are findings per `rules/visual-leverage.md` §4 staleness-check pattern: a link whose target has moved or been removed is stale, and staleness is repaired in the same change-set as the prose modification, never deferred.
+
+### 7. Code Block Discipline
+
+- **Language tag.** Every fenced block declares its language (` ```python `, ` ```bash `, ` ```yaml `, ` ```json `). An untagged block forgoes syntax highlighting; the missing tag is a finding.
+- **Per-language code-craft.** Block contents honor the per-language sibling rule (Python → `code-craft-python.md`; Shell → `code-craft-shell.md`; other languages → host-discovered convention via `code-craft-conventions.md`).
+- **Runnable examples.** Examples claiming to be runnable MUST run as-shown. Pseudocode is labeled (` ```python title="pseudocode" ` or a comment marker) so the reader is not misled.
+- **Inline-code discipline.** Backticks for symbols, paths, command names, file names; plain prose for natural-language usage. `pathlib.Path` (symbol) is backticked; "the path object" (noun) is not.
+
+### 8. Heading Hierarchy
+
+Heading levels carry semantic weight:
+
+- **One H1 per file.** The H1 is the primary title; subsequent sections use H2 and below.
+- **No skipped levels.** H2 → H3 is allowed; H2 → H4 is not (the missing H3 breaks document outliners).
+- **Headings are anchors.** Every referenced heading becomes an anchor (Markdown auto-generates the anchor from heading text per the host's rules — kebab-case-of-heading is the common shape).
+- **Sentence case or title case.** The host's convention is honored uniformly; mixed casing across siblings is a finding.
+
+### 9. Linting & Static Analysis (M13.7)
+
+The artifact MUST pass the host's ratified Markdown linter clean:
+
+- **markdownlint** (or `markdownlint-cli2` / `markdownlint-cli`) — the host's `.markdownlint.json` / `.markdownlint.yaml` is honored. Common rules: MD013 (line length — host-configured; 80 / 100 / 120 the prevalent values), MD024 (no duplicate headings), MD033 (inline HTML allowed by config), MD041 (first line is a top-level heading).
+- **vale** or another prose-linter — when configured, the host's `.vale.ini` and styles (`Microsoft`, `write-good`, custom dictionaries) apply; the artifact passes the configured severity threshold clean.
+
+### 10. Length Discipline
+
+Long Markdown artifacts (above 200 lines / 2000 tokens) MUST honor the incremental generation protocol per `rules/large-file-generation.md`. Sections growing beyond the artifact's coherence threshold are split into cross-linked sibling files, never left as monolithic walls of prose.
+
+## Disclosure surface
+
+Every Markdown artifact emission, restructure, or hedge-elimination is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Discovery — source: .markdownlint.json | .vale.ini | sibling-md-files; value: <ruleset | style>; honored]` for lint-config and prose-linter discoveries.
+- `[Discovery — source: sibling-frontmatter-schema; value: <field-list>; honored]` for frontmatter-schema discoveries.
+- `[Refinement — improvement: clarity; intercepted: <hedge-form | passive-voice | filler-sentence>; replacement: <revised-form>]` for hedge / passive / filler interceptions.
+- `[Default — applied: <auto-decision>; class: pure-formatting-normalization]` for markdownlint / prettier-md normalizations on existing files where the host has a ratified style.
+
+## Failure tells
+
+A README that opens with "This document describes …" (filler — the title declares what the document describes). An ADR with a "Background" section running ten paragraphs of throat-clearing before the decision (purpose-drift). A how-to guide structured as a sequential narrative ("First we'll explore the concept, then we'll see how it works …") instead of goal-then-steps (purpose-shape mismatch). Hedging vocabulary in prescriptive prose: "users should generally commit small changes" / "the function might return null in some cases" / "this is typically the safer approach" (M8 violation). Passive voice obscuring the actor: "It was decided that …" / "The bug was fixed" without naming who decided / who fixed (responsibility opaque). Content-free qualifiers in prescription: "very important", "fairly safe", "rather slow" (no information). Untagged fenced code blocks (`` ``` `` followed by code with no language tag — markdownlint MD040 violation). Internal links pointing to moved or removed files (link rot). External links pointing to mutable refs (`main` / `master` / `latest`) where commit-pinned is available (volatile reference). Heading hierarchy with skipped levels (H2 → H4) breaking document outliners. Multiple H1 headings in a single file (one-H1 violation). Frontmatter fields missing the host-ratified required set (`description` non-empty per the hooks pipeline hook validation). A 500-line Markdown artifact authored as a single monolithic write rather than via the incremental generation protocol (CM-23 / `rules/large-file-generation.md` violation).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every Markdown artifact's quality floor across every host project (purpose-driven structure, sentence-level justification, precision over politeness, active-voice construction, hedge-elimination). ● Every documentation page, ADR, RFC, runbook, README, CONTRIBUTING, CHANGELOG entry. ● The frontmatter validation surface at the hooks pipeline PreToolUse Write hook (the hook enforces non-empty `description` on rules / skills / agents / commands). ◐ The link discipline at every cross-rule citation in the ecosystem.
+- **Satisfies →** ● the fifteen-mandate registry row **M13 — Code Craft** at the Markdown per-language tier. ● the rules registry row "Code Craft — Markdown".
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M13). ● The CommonMark and GitHub Flavored Markdown specifications (the upstream syntax standards). ● `markdownlint` rules catalog and `vale` style inventories (the upstream prose-linter rulebooks this rule projects).
+- **Gated by ←** ● The path-filter (`*.md`, `*.markdown`) — this rule activates only on Markdown-language artifact touches. ● the trivial-vs-non-trivial threshold (trivial-scope Markdown edits run an abbreviated check covering link-resolution and frontmatter-presence only).
+- **Cross-bound with ↔** ↔ `rules/code-craft-conventions.md` (universal-delegation stub yields to this rule when the artifact's path matches; the universal floor M13.1–M13.11 is materialized here in prose idioms). ↔ `rules/code-craft-python.md` + `rules/code-craft-shell.md` (sibling per-language code-craft rules — code blocks in Markdown delegate to these per the §7 fenced-block discipline; consistent body shape across the trio). ↔ `rules/clean-room-generation.md` §5 Prose and Documentation (this rule is the per-language projection of §5; sentence-level justification, precision over politeness, active-voice construction are inherited from §5.1–§5.4). ↔ `rules/definitiveness.md` (M8 — hedge-elimination discipline applies in full to Markdown prescriptive prose). ↔ `rules/large-file-generation.md` (CM-23 — long-Markdown incremental-generation protocol). ↔ `rules/visual-leverage.md` (M9 — diagram + prose pairing inside Markdown structural artifacts).

package/src/apothem/rules/code-craft-python.md

@@ -0,0 +1,154 @@
+---
+name: "code-craft-python"
+description: "Per-language code-craft for Python — strict SOLID compliance, modern type hinting (3.10+ syntax, no Any), Google-style docstrings, specific exception handling, pytest discipline, security guardrails (no hardcoded secrets, no shell injection, no unsafe deserialization), and architectural anti-pattern interception. Path-filtered to Python source files and configuration manifests."
+pathFilter: "**/*.py, **/pyproject.toml, **/setup.py, **/setup.cfg, **/requirements*.txt, **/Pipfile, **/tox.ini, **/pytest.ini, **/conftest.py, **/.flake8, **/mypy.ini, **/ruff.toml, **/.ruff.toml, **/uv.toml, **/uv.lock, **/.python-version, **/pyrightconfig.json"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Code Craft — Python
+
+## What this rule enforces
+
+This rule binds **M13 — Code Craft Conventions** at the **Python per-language tier**. Every Python artifact the agent produces — script, hook, helper, library, test, configuration generator, migration script, deployment manifest, snippet — MUST meet a Senior-Architect floor: strict SOLID compliance, modern type hinting (Python 3.10+ syntax with conditional fallbacks per `python_requires`), Google-style docstrings, specific-exception handling, pytest-only test discipline, security-conscious code (no hardcoded secrets, no shell injection, no unsafe deserialization), and proactive anti-pattern interception. Correctness and readability supersede premature optimization. Output is clean, robust, scalable, maintainable, and idiomatically Pythonic.
+
+## Pre-conditions
+
+Applies whenever a Python artifact matching the `pathFilter` glob list — Python source, lockfiles, lint / format / type-check / test configurations, `python_requires` manifests, virtualenv pinning files — is authored, modified, or reviewed. The §6 seriousness scaling sets the FLOOR per level: any Python file touch activates at least the EXPLORING row even when the surrounding session is EXPLORING globally — never lower. Ecosystem-internal Python under `tools/`, `hooks/`, and `tests/` honors this rule alongside host-project Python.
+
+## Required behavior
+
+### 1. Strict SOLID Compliance
+
+Non-negotiable in every non-trivial Python module:
+
+- **SRP.** Every class, function, and module has exactly one reason to change. If a class name requires "and" to describe its purpose, it violates SRP — split it.
+- **OCP.** Open for extension via composition, `Protocol`, and strategy patterns — closed for modification. Use registries, plugin patterns, and dispatch tables over growing `if/elif` chains.
+- **LSP.** Every subclass perfectly substitutable for its parent — no weakened postconditions, no strengthened preconditions, no unexpected exceptions. If overriding tempts you to change the contract, use composition instead.
+- **ISP.** `Protocol` classes with narrow interfaces over monolithic ABCs. A `Readable` protocol with `read()` beats a `FileHandler` ABC with `read()`, `write()`, `delete()`, `rename()`.
+- **DIP.** High-level modules never import low-level modules — both depend on `Protocol` / `ABC` abstractions, with concrete implementations injected at composition root (`main()` or a DI container) and never constructed inside the consumer. Cross-layer injection discipline (which language-agnostic patterns to apply where) lives in `rules/clean-architecture-layers.md` §2.3 — this rule covers Python materialization only (`Protocol` / `ABC` choice, composition-root wiring style, `from __future__ import annotations` for forward references in interface modules).
+
+### 2. Implementation & Style
+
+#### 2.1 Version Detection
+
+Before generating Python code, determine the project's minimum supported version from, in priority order: `python_requires` in `pyproject.toml` / `setup.cfg`, `.python-version`, `tox.ini` envlist, CI matrix. If undetermined, assume 3.10. Below 3.10: use `Optional[X]` not `X | None`, `Union[A, B]` not `A | B`, and omit `match`/`case`. Below 3.11: omit `Self`, and use `asyncio.gather` not `TaskGroup`. The (3.10+) / (3.11+) annotations below are conditional — emit modern syntax only when the detected target supports it.
+
+#### 2.2 Formatting & Naming (M13.2)
+
+- **PEP 8** baseline. Assume **`ruff`** for linting and formatting (preferred) or `black` (88 chars) + `isort`: (1) stdlib, (2) third-party, (3) local. Absolute imports only.
+- `snake_case` functions / variables / modules, `PascalCase` classes / type aliases, `UPPER_SNAKE_CASE` constants, `_leading_underscore` internal / private.
+- No single-char names except `i / j / k` in loops, `x` in lambdas, `_` for discarded. Names reveal intent: `calculate_portfolio_risk()` not `process_data()`.
+
+#### 2.3 Type Hinting
+
+Mandatory, strict, modern on ALL signatures, class attributes, and module-level variables:
+
+- Modern syntax (3.10+): `list[int]`, `dict[str, T]`, `X | None` — never `List`, `Dict`, `Optional` from `typing`.
+- **Ban `Any`** — use `Protocol`, `TypeVar`, `Generic`, or `@overload` instead. Narrow exceptions: third-party boundary types with incomplete stubs, JSON deserialization results pre-validation, and `**kwargs` forwarding to external APIs. Each use requires a justifying comment (`# Any: <reason>`).
+- Use `TypeAlias` for complex types, `Literal` for constrained strings, `Final` for constants, `ClassVar` for class-level, `Self` (3.11+) for builder returns.
+- `Protocol` over `ABC` for structural subtyping. Return type annotations mandatory including `-> None`.
+
+#### 2.4 Documentation (M13.1, M13.11)
+
+- **Google Style docstrings** (`Args:`, `Returns:`, `Raises:`) for all public entities. Private: docstring when logic is non-obvious.
+- Inline comments explain **"why"**, never "what." No commented-out code (source control is the canonical archive). Module docstrings describe purpose and public API.
+
+#### 2.5 Error & Resource Management (M13.3)
+
+- Catch **specific exceptions** — never bare `except:` or generic `except Exception:` (unless re-raising at outermost boundary).
+- `try / except / else / finally` used logically. Custom exception hierarchies rooted in project-level base. Exceptions carry context in message and attributes.
+- Never raise exceptions as a signaling mechanism between layers (Python's EAFP idiom for guard checks is acceptable). Use `contextlib.suppress()` over empty `except` blocks.
+- **Always context managers (`with`)** for I/O and resources. `@contextmanager` or `__enter__` / `__exit__` for custom lifecycle. `ExitStack` for dynamic resource counts. Never rely on GC for cleanup.
+
+#### 2.6 Modern Patterns
+
+- **`dataclasses` / `attrs`** for data-holding classes — never manual `__init__` / `__repr__` / `__eq__`. Use `field(default_factory=...)` for mutable defaults.
+- **Pydantic** for external data validation. **`Enum`** for fixed constant sets — never magic strings / ints (M13.10).
+- **`pathlib.Path`** over `os.path`. **f-strings** only. **`functools.cache` / `lru_cache`** for expensive pure functions.
+- **`itertools` + generators** for lazy evaluation. **`__slots__`** for memory-dense classes. **`match` / `case`** (3.10+) for complex dispatch.
+- **`asyncio`** for I/O-bound concurrency (M13.9). Never block the event loop with sync I/O. Use `TaskGroup` (3.11+) for structured concurrency. `async with` / `async for` for async resources and iterators.
+- **`logging.getLogger(__name__)`** per module (M13.5). Structured logging via `structlog` for production. Never `print()` for operational output.
+
+### 3. Testing Directives (M13.6)
+
+- **`pytest` exclusively** — never `unittest.TestCase`. Test files mirror source: `src/domain/user.py` → `tests/domain/test_user.py`.
+- **Arrange-Act-Assert** in every test, separated by blank lines. One behavior per test. Names describe behavior: `test_calculate_risk_raises_on_insufficient_data`.
+- Cover **happy paths, edge cases** (boundary, empty, None, Unicode), and **failure modes** (invalid input, missing deps, timeouts). Every bug fix ships a regression test in the same change-set.
+- **Fixtures** scoped to the narrowest sufficient scope. **`parametrize`** when input varies but the assertion pattern is constant. **`pytest.raises(match=...)`** for exception testing.
+- **`unittest.mock.patch`** at the import site, not the definition. **`tmp_path`** for filesystem. **`monkeypatch`** for env vars. **Factory functions** for complex test data.
+- Test behavior, never implementation details. Never mock what you do not own — wrap it in an adapter and mock the adapter. Never `sleep()` — mock the clock.
+
+### 4. Security Directives (M13.8)
+
+#### 4.1 Secrets & Configuration
+
+- **Zero hardcoded secrets.** Keys, passwords, tokens from env vars or secret managers. `os.environ["KEY"]` (hard fail), never `get("KEY", "default")` for secrets.
+- `.env` in `.gitignore`. Always verify before commit.
+
+#### 4.2 Input Validation & Injection Prevention
+
+- **Validate all external data** at system boundaries. **SQL**: parameterized queries only. **Commands**: never `shell=True` with untrusted input — use `subprocess.run(["cmd", arg])`.
+- **Paths**: `pathlib.Path.resolve()` + verify within bounds. **Deserialization**: never `pickle` / `yaml.load()` for untrusted data — use `json` / `yaml.safe_load()` / Pydantic.
+- **Templates**: auto-escaping (Jinja2 `autoescape=True`). **Regex**: avoid catastrophic backtracking; timeout user-supplied patterns.
+
+#### 4.3 Dependency & Runtime Safety
+
+- **Pin deps** in production (`==`). Ranges only in library `pyproject.toml`. **Audit** regularly (`pip-audit`, `safety`). Prefer **`uv`** for environment and dependency management.
+- Never log secrets / PII. Structured logging with sanitized messages. Minimal privilege — never root unless required.
+
+### 5. Architectural Guardrails
+
+#### 5.1 Quality Audit
+
+Audit for missing abstractions, leaky abstractions, god objects, feature envy (methods using another class's data more than their own), primitive obsession (raw `str` / `int` / `dict` where domain types add safety), inappropriate intimacy — triggered when reading, reviewing, or modifying a class / module of 150+ lines, or when a symbol recurs across 3+ files. Refactor immediately when detected; do not defer.
+
+#### 5.2 Refactoring & Output
+
+- **Concrete, scoped refactorings** — never vague. Atomic: one structural change per refactoring. Preserve all tests. Update all affected type hints, docstrings, imports.
+- **Output**: concise working solution first → brief architectural rationale → surgical changes matching surrounding codebase conventions.
+
+#### 5.3 Anti-Pattern Interception
+
+Intercept during design: `isinstance` chains → `Protocol` / strategy. Mutable defaults → `field(default_factory=...)`. Global state → injected dependency. Circular imports → redesign boundaries. `import *` → explicit. String constants → `Enum`. `os.path` → `pathlib`. `print()` → `logging`. Sync I/O in async → flag.
+
+### 6. Seriousness Scaling
+
+| Level | Enforcement |
+| ----- | ----------- |
+| EXPLORING | PEP 8 + type hints + specific exceptions. SOLID awareness only |
+| PERSONAL_USE | Full style. SOLID on public API. Public docstrings. AAA tests. No hardcoded secrets |
+| SHARED | All sections enforced. Design violations are findings. Full test coverage. Security audit |
+| PUBLIC_LAUNCH | Full + `mypy --strict`. 100% public API docs. Dependency audit. Security as quality gate |
+
+### 7. Anti-Patterns
+
+- **DON'T** use bare `except:` or `except Exception:` (unless re-raising at the outermost boundary) — **BECAUSE** it swallows errors and masks bugs.
+- **DON'T** declare mutable defaults (`def f(items=[])`) — **BECAUSE** the default is shared across calls.
+- **DON'T** use `Any` type hints — **BECAUSE** it disables type checking where you need it most.
+- **DON'T** subclass built-ins (`dict`, `list`) — **BECAUSE** C methods bypass overrides. Use `UserDict` / `UserList`.
+- **DON'T** write monolithic test functions with multiple Act-Assert pairs — **BECAUSE** the first failure masks the rest.
+- **DON'T** suppress with `# type: ignore` without an error code + justifying comment — **BECAUSE** blanket suppression hides real errors.
+- **DON'T** inherit concrete classes for reuse — **BECAUSE** brittle hierarchies. Use composition + `Protocol`.
+
+## Disclosure surface
+
+Every Python artifact emission, refit, or anti-pattern interception is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Discovery — source: pyproject.toml | setup.cfg | .python-version | tox.ini; value: <python_requires>; honored]` for every version-detection outcome that shapes type-hint syntax.
+- `[Discovery — source: ruff.toml | .ruff.toml | pyproject.toml [tool.ruff]; value: <ruleset>; honored]` for honored lint-config discoveries.
+- `[Refinement — improvement: maintainability; intercepted: <anti-pattern>; refactor: <description>]` for proactive anti-pattern interceptions during design.
+- `[Default — applied: <auto-decision>; class: pure-formatting-normalization]` for ruff / black formatter normalizations on existing files where the host has a ratified style.
+
+## Failure tells
+
+`def f(items=[])` (mutable default — shared across calls). `except:` / `except Exception: pass` (silent swallow — M13.3 violation). `Any` type hint without `# Any: <reason>` justifying comment (typecheck disabled where it matters most). `from typing import Optional, Union` in a project with `python_requires = ">=3.10"` (legacy syntax where modern is available). `subprocess.run(cmd, shell=True)` with untrusted input (shell injection — M13.8). `pickle.loads(untrusted_bytes)` (deserialization attack surface). `yaml.load(untrusted)` without `Loader=yaml.SafeLoader` (RCE attack surface). `print()` for operational output (M13.5 — should be `logging.getLogger(__name__).info(...)`). Tests written as `unittest.TestCase` subclasses in a project with `pytest` configured (test-framework drift — M13.6). `# TODO: fix this` without a tracking issue (open marker per `rules/definitiveness.md` M8). `os.path.join(a, b)` in a 3.10+ codebase (legacy API — should be `pathlib.Path(a) / b`). Magic numbers in business logic without named constants (M13.10). Public function with no docstring (M13.11). A test using `time.sleep(3)` to wait for a side effect (timing dependency instead of mocking time).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every Python artifact's quality floor across every host project (SOLID enforcement, type-hint discipline, docstring requirement, pytest convention, security guardrails). ● Every `tools/*.py` and `hooks/*.py` and `tests/*.py` touch under the path-filter. ● Every Python-language manifestation of the Senior Software Architect role declared at `rules/cognitive-identity.md` §1. ◐ The Python-language materialization of clean architecture layer discipline (the §1 DIP discussion cross-references `rules/clean-architecture-layers.md` §2.3).
+- **Satisfies →** ● the fifteen-mandate registry row **M13 — Code Craft** at the Python per-language tier. ● CM-28 (Python Senior Architect — rule-delegated mandate; this rule is the canonical specification CM-28 delegates to). ● the rules registry row "Code Craft — Python".
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M13). ● CM-28. ● `rules/cognitive-identity.md` (Python is the primary language declared at §2). ● PEP 8, PEP 484, PEP 604, PEP 612, PEP 695 (the upstream Python language standards this rule projects).
+- **Gated by ←** ● The path-filter (17 glob patterns covering `*.py`, `pyproject.toml`, `setup.cfg`, `requirements*.txt`, `Pipfile`, `tox.ini`, `pytest.ini`, `conftest.py`, lint configs) — this rule activates only on Python-language artifact touches. ● `rules/cognitive-identity.md` Senior Software Architect role declaration. ● the trivial-vs-non-trivial threshold (trivial-scope Python edits run an abbreviated check covering M13.7 lint / format only).
+- **Cross-bound with ↔** ↔ `rules/code-craft-conventions.md` (universal-delegation stub yields to this rule when the artifact's path matches; the universal floor M13.1–M13.11 is materialized here in Python idioms). ↔ `rules/code-craft-shell.md` + `rules/code-craft-markdown.md` (sibling per-language code-craft rules; consistent body shape across the trio). ↔ `rules/clean-architecture-layers.md` (Python materializes the layer discipline through `Protocol` / `ABC` choice + composition-root patterns; §1 DIP cross-references that rule's §2.3). ↔ `rules/cognitive-identity.md` (the Senior Software Architect role's Python-language manifestation). ↔ `rules/clean-room-generation.md` (Python code emission passes the Writing Protocol §2 + Code Generation §4 before this rule's path-filtered guardrails apply). ↔ `rules/operational-mandates.md` §CM-28 (the inline registry entry that delegates here). ↔ `rules/performance-discipline.md` §1.1 (the per-class performance budgets apply to Python artifacts under this rule's path-filter). ↔ `rules/refactoring-discipline.md` (the per-language quality bar a refactor's deficiency-elevation targets).

package/src/apothem/rules/code-craft-shell.md

@@ -0,0 +1,192 @@
+---
+name: "code-craft-shell"
+description: "Per-language code-craft for shell artifacts — POSIX bash idioms (set -euo pipefail; quoted variables; no eval on untrusted input; trap-based cleanup) and PowerShell idioms (Set-StrictMode -Version Latest; verb-noun cmdlet naming; no Invoke-Expression on untrusted input; structured error records). Honor shellcheck for bash and Invoke-ScriptAnalyzer for PowerShell; pass the host's ratified shell linter clean."
+pathFilter: "**/*.sh, **/*.bash, **/*.ps1, **/*.psm1, **/*.psd1"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Code Craft — Shell
+
+## What this rule enforces
+
+This rule binds **M13 — Code Craft Conventions** at the **shell per-language tier**, covering POSIX bash and PowerShell. Every shell artifact the agent produces — script, hook stub, build helper, runner, deployment driver, environment activator, CI-pipeline glue, one-shot administrative command — MUST meet the M13.1–M13.11 floor with shell-specific materialization: strict mode by default, every variable quoted, no shell injection on untrusted input, deterministic error handling with explicit exit codes, named constants over magic numbers, and behavior-shaped tests where the host has a shell-test framework. The artifact MUST pass `shellcheck` (bash / sh) and `Invoke-ScriptAnalyzer` (PowerShell) clean against the host's ratified configuration.
+
+## Pre-conditions
+
+Applies whenever a shell artifact matching the `pathFilter` glob list — `*.sh`, `*.bash`, `*.ps1`, `*.psm1`, `*.psd1` — is authored, modified, or reviewed. Ecosystem-internal shell stubs under `hooks/lib/bootstrap.sh` and `hooks/lib/bootstrap.ps1` (and siblings) honor this rule alongside host-project shell. The shell-execution sub-budgets at `rules/performance-discipline.md` §1.1 govern the runtime ceiling for hook bootstrap stubs and shell linters; this rule governs their static-form quality.
+
+## Required behavior
+
+### 1. Strict-Mode Defaults
+
+#### 1.1 POSIX bash / sh
+
+Every bash script opens with strict-mode declarations as the first non-shebang, non-comment lines:
+
+```bash
+#!/usr/bin/env bash
+# Optional: header comment naming purpose / why-not-what / cross-references
+set -euo pipefail
+IFS=$'\n\t'
+```
+
+- **`set -e`** — exit immediately on any command failure (no silent error swallowing).
+- **`set -u`** — unset variable reference is an error (catches typos at runtime).
+- **`set -o pipefail`** — a pipeline's exit status is the last non-zero in the chain (no silent failure of `cmd1 | cmd2` when `cmd1` fails).
+- **`IFS=$'\n\t'`** — restrict word-splitting to newline + tab; eliminates a class of space-bearing-filename bugs.
+
+When the host's existing shell scripts use a different strict-mode discipline (e.g., `set -eEuo pipefail` adding the `-E` ERR-trap inheritance), honor the host's discovery per `rules/host-discovery.md`.
+
+#### 1.2 PowerShell
+
+Every PowerShell script opens with strict-mode declaration:
+
+```powershell
+#Requires -Version 7.0
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+```
+
+- **`Set-StrictMode -Version Latest`** — uninitialized variable reference, missing object property access, function call with too-many positional args all become errors.
+- **`$ErrorActionPreference = 'Stop'`** — non-terminating errors become terminating, eliminating the silent-error class.
+- **`#Requires -Version 7.0`** — declare the minimum PowerShell version (or `5.1` when targeting Windows PowerShell). Match the host's discovered minimum.
+
+### 2. Variable Quoting & Word-Splitting
+
+#### 2.1 Bash
+
+Every variable expansion is double-quoted unless the unquoted form is a deliberate word-splitting use:
+
+- **Right form:** `cp -- "$src" "$dst"` (handles spaces, tabs, glob characters in `$src` and `$dst`).
+- **Wrong form:** `cp $src $dst` (silently breaks on a path containing a space; security risk on adversarial inputs).
+- **Argument terminators.** Use `--` before path arguments to disambiguate against unintended option parsing (`rm -- "$file"`).
+- **Array expansion.** `"${array[@]}"` to expand each element as a separate argument; `"${array[*]}"` only when joining is intended.
+
+#### 2.2 PowerShell
+
+PowerShell handles word-splitting differently — variables are not subject to bash-style word-splitting. The discipline:
+
+- **Stop-parsing token.** When invoking native executables that take arguments PowerShell would parse as operators, use `--%` to prevent re-parsing: `git log --% --format=%H`.
+- **Splatting.** Pass argument arrays via splatting (`@args`) rather than string concatenation to preserve quoting.
+- **Path operations.** Use `Join-Path` and `[System.IO.Path]::Combine()` rather than string concatenation for path construction.
+
+### 3. Injection Prevention (M13.8)
+
+A shell command or PowerShell expression MUST NOT be constructed from untrusted input:
+
+#### 3.1 Bash
+
+- **No `eval` on untrusted input.** `eval "$user_input"` is RCE. Use `case` / function dispatch instead.
+- **No unquoted command substitution containing untrusted input.** `cmd $(echo "$user_input")` re-splits on word-splitting; prefer arrays.
+- **No `bash -c "$untrusted"`.** Same RCE class. Pass arguments through `argv`, not via interpolation.
+- **`xargs` with `-0` and `-r`** when chaining filename lists; otherwise newline-bearing names break the pipeline.
+
+#### 3.2 PowerShell
+
+- **No `Invoke-Expression` on untrusted input.** Same RCE class as bash `eval`. Use script blocks (`& { ... }`) with parameterized arguments instead.
+- **No string-formatted SQL / shell commands.** Parameterized cmdlets honor quoting; string-formatted commands do not.
+- **`-LiteralPath` over `-Path`** when the path is data, not a glob pattern (Path expands wildcards; LiteralPath does not).
+
+### 4. Error Handling & Exit Codes (M13.3)
+
+#### 4.1 Bash
+
+- **Explicit exit codes.** `exit 0` for success; `exit 1`–`125` for documented failure modes (avoid 126 / 127 / 128+, reserved by POSIX for shell-internal errors).
+- **`trap` for cleanup.** Resources allocated in the script (temp files, lock files, mounts, child processes) are released by a `trap '...' EXIT INT TERM` clause, not deferred to GC.
+- **Error context on failure.** When a command fails, the failure message names the command, the input, and the exit code: `printf 'error: <command> failed (exit %d) with input %q\n' "$rc" "$input" >&2; exit "$rc"`.
+- **No silent failure.** Every command whose failure is recoverable is wrapped in an explicit conditional; every command whose failure is fatal is allowed to propagate via `set -e`.
+
+#### 4.2 PowerShell
+
+- **Throw structured errors.** `throw [System.IO.FileNotFoundException]::new("$path")` rather than `throw "file not found"` (typed errors are catchable by type).
+- **Try / catch / finally** over `$LASTEXITCODE` checks for cmdlet errors. Native-exe errors still need `$LASTEXITCODE` inspection.
+- **`exit $exitCode`** at script tail makes the exit code explicit; absence defaults to 0 even after errors in `$ErrorActionPreference = 'Continue'` mode.
+
+### 5. Naming & Documentation (M13.2, M13.11)
+
+#### 5.1 Bash
+
+- **Function names** use snake_case: `cleanup_tempfiles`, `parse_arguments`, `validate_input`.
+- **Variable names** for script-level constants use UPPER_SNAKE_CASE: `readonly LOG_DIR="/var/log/app"`.
+- **Local variables** inside functions use lower_snake_case and the `local` keyword: `local input="$1"; local rc=0`.
+- **Header comment** at the top of the script names: purpose, dependencies (other scripts / binaries the script invokes), invocation example, exit-code catalog.
+
+#### 5.2 PowerShell
+
+- **Verb-noun cmdlet naming.** Functions follow the approved-verb list (`Get-Verb` lists them): `Get-FooConfig`, `Set-FooConfig`, `New-FooSession`, `Remove-FooSession`, `Test-FooReachability`. Non-approved verbs trigger `Invoke-ScriptAnalyzer` warnings.
+- **Comment-based help.** Every public function carries a `<#  .SYNOPSIS / .DESCRIPTION / .PARAMETER / .EXAMPLE / .OUTPUTS  #>` block per the host's ratified discipline.
+
+### 6. Magic Numbers & Constants (M13.10)
+
+Numeric literals in shell logic become named constants:
+
+#### 6.1 Bash
+
+```bash
+readonly TIMEOUT_SECONDS=30
+readonly MAX_RETRIES=3
+readonly EXIT_INVALID_INPUT=2
+
+if (( retries >= MAX_RETRIES )); then
+    exit "$EXIT_INVALID_INPUT"
+fi
+```
+
+Avoid literal `30`, `3`, `2` in the body — the named constants tell the next reader why these values.
+
+#### 6.2 PowerShell
+
+```powershell
+$Script:TimeoutSeconds = 30
+$Script:MaxRetries = 3
+$Script:ExitInvalidInput = 2
+```
+
+### 7. Linting & Static Analysis (M13.7)
+
+The artifact passes the host's ratified shell linter clean:
+
+- **Bash.** `shellcheck script.sh` exits 0. The host's `.shellcheckrc` is honored per M1 host-discovery; sibling scripts' shellcheck-disable directives are followed unless the new script's context warrants different.
+- **PowerShell.** `Invoke-ScriptAnalyzer -Path script.ps1 -Severity Error,Warning` exits 0. The host's `PSScriptAnalyzerSettings.psd1` is honored.
+
+The shell-linter performance budgets at `rules/performance-discipline.md` §1.1 govern the runtime ceiling: 5s for `shellcheck` over `hooks/lib/*.sh`, 10s for `Invoke-ScriptAnalyzer` over `hooks/lib/*.ps1`.
+
+### 8. Testing (M13.6)
+
+Where the host has a ratified shell-test framework:
+
+- **bats-core** for bash. Test files at `tests/bash/<unit>.bats`. AAA shape: `setup() { … }` (Arrange) → `@test 'description' { run cmd; ... }` (Act) → `[ "$status" -eq 0 ]; [ "$output" = '...' ]` (Assert).
+- **Pester** for PowerShell. Test files at `tests/powershell/<unit>.Tests.ps1`. AAA shape: `BeforeAll { … }` (Arrange) → `It 'description' { $result = Invoke-Foo … }` (Act) → `$result | Should -Be 'expected'` (Assert).
+
+When the host has no shell-test framework configured but the script's behavior warrants verification, surface as an inquiry per `rules/authority-inquiry.md` with bats-core / Pester recommended per the language.
+
+### 9. Cross-Platform Convention
+
+When a script must run on multiple platforms (Windows + POSIX), prefer:
+
+- **Pure POSIX sh** when the script's surface is small and dependency-free (no `[[ ]]`, no arrays, no `$(<file)` substitutions).
+- **Bash with explicit `#!/usr/bin/env bash`** when the script needs bash features and the host has bash on every target platform.
+- **Two parallel scripts** (`script.sh` + `script.ps1`) when the host has POSIX-only and Windows-only paths, with the dispatching wrapper choosing per platform. This is the pattern the ecosystem uses at `hooks/lib/bootstrap.{sh,ps1}` per the canonical-pair discipline declared in the hooks pipeline Paired-Template Review Cadence.
+
+## Disclosure surface
+
+Every shell artifact emission, refactor, or anti-pattern interception is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Discovery — source: .shellcheckrc | sibling-shell-scripts; value: <strict-mode-form | linter-config>; honored]` for shellcheck-config and bash-idiom discoveries.
+- `[Discovery — source: PSScriptAnalyzerSettings.psd1 | sibling-ps1-scripts; value: <ruleset>; honored]` for PowerShell linter-config discoveries.
+- `[Refinement — improvement: security; intercepted: <eval | Invoke-Expression | shell-injection-pattern>; replacement: <safe-form>]` for security interceptions.
+- `[Default — applied: <auto-decision>; class: pure-formatting-normalization]` for shellcheck / Invoke-ScriptAnalyzer normalizations on existing files where the host has a ratified style.
+
+## Failure tells
+
+`#!/bin/sh` followed by bash-only constructs (`[[ ]]`, arrays, `$()` instead of backticks in old-shell contexts — bashism creep). A bash script with no `set -euo pipefail` (silent-error class). A bash script using `set -e` but with `||` chains that swallow the `-e` propagation without explicit handling. Variable expansion without quotes (`cp $src $dst` instead of `cp -- "$src" "$dst"`). `eval "$user_input"` (RCE). `bash -c "$untrusted"` (RCE). A PowerShell script with no `Set-StrictMode` (uninitialized-variable class). A PowerShell script using `Invoke-Expression` on untrusted input (RCE). A PowerShell function named with a non-approved verb (`Process-Foo` instead of `Update-Foo` or `Invoke-Foo`). A bash script that fails `shellcheck` with new findings the host's existing scripts do not have. A PowerShell script that fails `Invoke-ScriptAnalyzer -Severity Error,Warning`. Magic numbers in retry / timeout / buffer-size logic without named constants. A trap-less bash script that allocates a tempfile and exits without cleanup. A PowerShell script that throws a string literal (`throw "error"`) instead of a typed exception. A cross-platform-intended script that uses bash-only constructs without a PowerShell parallel.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every shell artifact's quality floor across every host project (strict-mode defaults, variable quoting, injection prevention, deterministic error handling). ● Every `hooks/lib/bootstrap.sh` and `hooks/lib/bootstrap.ps1` touch under the path-filter (the canonical-pair stubs governed by the hooks pipeline). ● Every CI shell stub, deployment driver, and environment activator. ◐ The shell-execution sub-budgets at `rules/performance-discipline.md` §1.1.
+- **Satisfies →** ● the fifteen-mandate registry row **M13 — Code Craft** at the shell per-language tier. ● the rules registry row "Code Craft — Shell".
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M13). ● POSIX shell standards (IEEE Std 1003.1) and PowerShell language specification (Microsoft Learn). ● `shellcheck` rules catalog (the upstream lint rulebook this rule projects). ● `PSScriptAnalyzer` rules catalog (the upstream PowerShell lint rulebook this rule projects).
+- **Gated by ←** ● The path-filter (`*.sh`, `*.bash`, `*.ps1`, `*.psm1`, `*.psd1`) — this rule activates only on shell-language artifact touches. ● the trivial-vs-non-trivial threshold (trivial-scope shell edits run an abbreviated check covering strict-mode and quoting only).
+- **Cross-bound with ↔** ↔ `rules/code-craft-conventions.md` (universal-delegation stub yields to this rule when the artifact's path matches; the universal floor M13.1–M13.11 is materialized here in shell idioms). ↔ `rules/code-craft-python.md` + `rules/code-craft-markdown.md` (sibling per-language code-craft rules; consistent body shape across the trio). ↔ `rules/performance-discipline.md` §1.1 (per-shell budgets — bootstrap.sh ≤ 500ms, bootstrap.ps1 ≤ 1500ms, find-python.{sh,ps1} ≤ 200ms, shellcheck ≤ 5s, Invoke-ScriptAnalyzer ≤ 10s; this rule is the static-form quality discipline whose runtime is governed there). ↔ `rules/host-discovery.md` (M1 — shellcheck and ScriptAnalyzer config discovery walks). ↔ `rules/clean-room-generation.md` (Code Generation §4 governs initial shell emission before this rule's path-filtered guardrails apply).