@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/zed/templates/apothem-rules.md

@@ -0,0 +1,32 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Zed Bootstrap
+
+This file is materialised by `apothem install --harness zed --project <path>` and lands at `<project>/.rules`, the current Zed project agent-instruction surface per https://zed.dev/docs/ai/instructions. Zed auto-includes this flat project-root file (alongside the `AGENTS.md` / `CLAUDE.md` family) as agent instructions; there is no per-tool rules directory, so the whole apothem surface lands in this single file. Any pre-existing `.rules` is backed up before this file replaces it.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside Zed, the surface manifests as this `.rules` instruction file:
+
+- **Rules** — engineering rules applied on every interaction. The full rule cohort lives at the apothem source repository under `src/apothem/rules/`; this Zed-facing anchor names the disciplines the operator may consult in detail.
+- **Skills, commands, agents** — reusable techniques, slash-style workflows, and persistent sub-agent definitions. Apothem's canonical-master cohort at the apothem source repository defines them; Zed does not auto-discover them as separate surfaces, so they manifest here as referenced discipline.
+- **Context servers (MCP)** — Zed's MCP surface (`.zed/settings.json` `context_servers`) is operator-owned, not apothem-managed.
+- **Global instructions** — Zed's global instruction surface (`~/.config/zed/AGENTS.md`) is operator-owned, not apothem-managed.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including Zed:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity through a question instead of inventing a plausible-looking value.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Human-only authorship.** Git commit messages, PR descriptions, branch names, and tag annotations carry human contributors only — never the underlying language model, runtime, IDE extension, or any automated tool as a co-author.
+- **Lean-context delegation.** Where the host provides delegated-worker dispatch, broad reads and heavy workloads route to a spawned worker by default so the main working context stays lean. The heavy parallel apparatus stays opt-in; routing delegable work away from the main thread is the standing posture once dispatch is available.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+- **Source accessibility.** When the authoritative source for a claim, convention, or version pin is closed, paywalled, login-gated, or otherwise unreachable, ask the operator for it in full rather than substituting a lower-trust open page. Trust outranks reachability.
+
+## Refreshing the file
+
+Re-run `apothem install --harness zed --project <this-project-root>` to overwrite this file with the latest apothem template. The operation is idempotent. `apothem uninstall --harness zed --project <this-project-root>` renames the file to a timestamped backup; `apothem verify --harness zed --project <this-project-root>` checks the file is present and non-empty.

package/src/apothem/harnesses/zed/uninstall.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the zed harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "zed"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Zed targets surgically.
+
+    Zed's flat-file divergence: the target is ``<project>/.rules`` (one
+    level below the project root), so the project root is the file's
+    direct parent — unlike the cohort's nested rules-directory targets. The
+    ``.rules`` ``sentinel_merge`` anchor is cleaned by the shared driver, which
+    strips only Apothem's managed block (operator prose survives), deletes an
+    Apothem-only file, and backs the file up under the Apothem backup root — no
+    whole-file ``.bak`` sibling is left beside the operator's file.
+    """
+    install_driver.run_uninstall(
+        _HARNESS_NAME,
+        project_root=project or output_path.parent,
+    )

package/src/apothem/harnesses/zed/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the zed harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update_project
+from apothem.harnesses.zed.install import install
+
+update = make_update_project(install)

package/src/apothem/harnesses/zed/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the zed harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_project
+
+_HARNESS_NAME: str = "zed"
+
+verify = make_verify_project(_HARNESS_NAME)

package/src/apothem/hooks/README.md

@@ -0,0 +1,81 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# hooks
+
+> **Role.** The hook runtime. A unified Python dispatcher handles every
+> harness hook event, emits per-event Markdown context, and runs the
+> session-start bootstrap.
+
+```mermaid
+%%{ init: { "theme": "neutral" } }%%
+%% verified: 2026-06-23 %%
+%% provenance: hooks/README.md — the hook-dispatch runtime flow %%
+%% cross-reference: src/apothem/hooks/dispatch.py (router); src/apothem/hooks/lib/bootstrap.sh + bootstrap.ps1 (stubs); src/apothem/hooks/messages/ (per-event context) %%
+flowchart TD
+    Event["Harness fires a hook event<br/>PreToolUse · PostToolUse · SessionStart · Stop · PreCompact · …"]
+    Stub["Bootstrap stub — lib/bootstrap.sh / bootstrap.ps1<br/>locates a Python interpreter, then execs the dispatcher<br/>(Claude Code settings.json invokes an install-resolved interpreter on dispatch.py directly)"]
+    Dispatch["dispatch.py — unified router<br/>routes each event to its handler"]
+    Context["Per-event Markdown context<br/>from messages/&lt;event&gt;.md"]
+    Bootstrap["session_start_bootstrap.py<br/>(SessionStart only)"]
+
+    Event --> Stub --> Dispatch
+    Dispatch -->|most events| Context
+    Dispatch -->|SessionStart| Bootstrap
+```
+
+## Entry points
+
+| File | Purpose |
+|------|---------|
+| `dispatch.py` | Unified Python entrypoint for all hook events — routes each event to its handler. |
+| `emit_hook_context.py` | Emit structured JSON context for hook events. |
+| `session_start_bootstrap.py` | Session-start bootstrap hook for the Apothem ecosystem. |
+| `__init__.py` | Package marker. |
+
+## `lib/` — dispatcher support
+
+| File | Purpose |
+|------|---------|
+| `bootstrap.sh` / `bootstrap.ps1` | Shell bootstrap stubs that locate an interpreter (via the locators below) and `exec` the dispatcher. Shipped as the documented shell entry path; the Claude Code `settings.json` entries instead invoke an install-resolved absolute interpreter on `dispatch.py` directly. |
+| `find-python.sh` / `find-python.ps1` | Python interpreter locators. |
+| `find-pwsh.sh` / `find-pwsh.ps1` | PowerShell interpreter locators. |
+| `events.py` | Single source of truth for the supported hook-event vocabulary. |
+| `log.py` | Shared logger factory for the hook scripts. |
+| `resolve_root.py` | Project-root resolution for the Apothem ecosystem. |
+| `__init__.py` | Package marker. |
+
+## `messages/` — per-event context
+
+Markdown context files emitted into the conversation for each hook event:
+
+| File | Event |
+|------|-------|
+| `sessionstart.md` | SessionStart. |
+| `stop.md` | Stop (session-end). |
+| `precompact.md` / `postcompact.md` | PreCompact / PostCompact. |
+| `pretooluse-write.md` / `pretooluse-write-header-guard.md` / `pretooluse-write-plan-guard.md` | PreToolUse Write / apply_patch — base context plus the authorship-header and plans-discipline guards. |
+| `pretooluse-edit.md` / `pretooluse-edit-header-guard.md` | PreToolUse Edit — base context plus the authorship-header guard. |
+| `pretooluse-notebookedit.md` | PreToolUse NotebookEdit. |
+| `pretooluse-bash.md` / `pretooluse-bash-plan-guard.md` | PreToolUse Bash — base context plus the plans-discipline redirection guard. |
+| `pretooluse-conformity.md` | PreToolUse conformity-gate context. |
+| `pretooluse-dependency-guard.md` | PreToolUse Write / Edit — advisory flag on unpinned or untrusted dependency additions to manifests and lockfiles. |
+| `pretooluse-eval-guard.md` | PreToolUse Write / Edit / Bash — advisory flag on dynamic evaluation of untrusted or model-derived input. |
+| `pretooluse-askuserquestion-recommended.md` | PreToolUse AskUserQuestion — advisory `(Recommended)`-marker guard on rendered option sets. |
+| `posttooluse-proactive-compaction.md` | PostToolUse — proactive-compaction tracker context (CM-19). |
+
+## Conventions
+
+- The Claude Code `settings.json` hook entries invoke an install-resolved absolute CPython interpreter on `dispatch.py` directly — the `${PYTHON_BIN}` placeholder is substituted at install time (per `apothem.lib.python_resolver`) so no entry runs a bare `python`. The shell bootstrap stubs (`bootstrap.sh` / `bootstrap.ps1`) are the documented shell entry path that locates an interpreter and hands off to `dispatch.py`; they are not the `settings.json` entry point.
+
+## Operating in this folder
+
+- **Fail-open is the dispatcher contract.** `dispatch.py::main` always exits 0; any uncaught exception is converted to a valid JSON failure envelope on stdout so the host harness never sees a raw traceback and never stalls. A handler that can raise past `main` is a contract breach — preserve the `# noqa: BLE001` intent-marker on the outermost boundary, and never widen the dispatcher's fail-open boundary.
+- **The event vocabulary has one source of truth:** `lib/events.py` (`SUPPORTED_EVENTS`, `HOOK_SPECIFIC_OUTPUT_EVENTS`). Never hard-code an event-name list elsewhere; import from `events`.
+- **Per-event timeout budgets bound runtime** (PreToolUse / PostToolUse / UserPromptSubmit / Notification tighter; SessionStart / PreCompact / PostCompact wider; Stop widest). A handler exceeding its event's budget is silently skipped by the runtime — keep handler work inside the budget; the per-event runtime benchmark is [`../benchmarks/bench_hooks.py`](../benchmarks/bench_hooks.py).
+- **Adding an event:** extend `lib/events.py` first, then the dispatcher routing, then a `messages/<event>.md` context file. A new `messages/<event>.md` carries the markdown SPDX comment line and is registered in the table above in the same change.
+- Validate a change with `python -m ruff check`, `python -m mypy` (cli + harnesses scope), and `python -m pytest`. Surface any unresolved decision as `TODO(clarify): ...` rather than guessing.
+
+## Related
+
+- [`conformity/gate.py`](../conformity/gate.py) — the conformity gate the PreToolUse Write/Edit hooks invoke.
+- [`benchmarks/bench_hooks.py`](../benchmarks/bench_hooks.py) — the per-event hook-handler runtime benchmark.

package/src/apothem/hooks/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+
+"""Hook dispatcher and per-event context emitters.
+
+This package carries the apothem hook-event pipeline. The runtime
+entry-points are:
+
+* ``apothem.hooks.dispatch`` — the harness-side dispatcher. Harness
+  hook entries invoke the materialized copy by absolute script path
+  (``<harness-root>/apothem/hooks/dispatch.py`` or the harness's hook
+  subtree), so no importable ``apothem`` package is required on the
+  host. Receives an event name and an optional message name; emits the
+  per-event Markdown context to stdout for the harness to surface in
+  the operator's chat session.
+* ``apothem.hooks.emit_hook_context`` — the per-event context emitter
+  that materializes a Markdown payload from the bundled message
+  fixtures and the live ecosystem state.
+* ``apothem.hooks.session_start_bootstrap`` — the SessionStart-event
+  bootstrap that surfaces the conformity posture, memory summary, plan
+  summary, and session-source banner at every fresh session.
+
+Shared helpers live under ``apothem.hooks.lib`` (event taxonomy,
+logging, root resolution).
+"""

package/src/apothem/hooks/askuserquestion_validator.py

@@ -0,0 +1,380 @@
+# SPDX-License-Identifier: MIT
+
+"""Call-time validator for the ``AskUserQuestion`` tool's option payload.
+
+Why this validator exists. The option-annotation matchers
+(``conformity/option_annotation_grep.py``) scan committed ``*.md`` artifacts —
+they verify the canonical ``(Recommended)`` marker on rendered option sets that
+already live in the tree. Nothing inspected the LIVE ``AskUserQuestion`` tool
+payload at the moment the agent asks the operator, so a malformed or absent
+marker reached the operator unchecked. This module is the dispatch-routed
+``PreToolUse`` handler that closes that gap: it receives the tool input (a
+``questions`` array, each question carrying ``options[].label`` and
+``multiSelect``), validates marker well-formedness against the canonical rule,
+and emits an advisory ``systemMessage`` (default) or — under the repo's strict
+opt-in — a blocking ``decision`` envelope.
+
+What it CAN guarantee. Well-formedness: a marker present on a label is in the
+canonical form (capital ``(Recommended)``, exact end-of-label placement, one
+leading space, not on a destructive option, at most one per single-select
+question). These are objectively decidable from the payload alone.
+
+What it CANNOT guarantee. The native ``AskUserQuestion`` payload carries no
+separate "recommended" field — the marker IS the only signal of which option is
+recommended. So this validator cannot prove a missing marker is a defect: a
+single-select question with two substantive options and zero markers is merely
+*advised* (a NUDGE) to mark its recommended option, never blocked. Forcing a
+recommendation to exist is a behavioral-convention obligation the rules carry,
+not a fact this runtime check can decide.
+
+Contract. Fast (sub-second; pure-Python regex over a small payload),
+idempotent, and FAIL-OPEN: any exception → allow the call (an empty envelope),
+never crash the operator's question. The strict opt-in mirrors the conformity
+gate's: the ``--strict`` flag or a truthy ``APOTHEM_CONFORMITY_STRICT``
+environment variable escalates WELL-FORMEDNESS findings (never the NUDGE) to a
+``decision: block``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from typing import Final
+
+# Strict opt-in mirrors the conformity gate's (``conformity/gate.py``). Reused
+# verbatim here so the AskUserQuestion validator and the per-Write gate share
+# one strict-mode contract: the operator enables blocking once, for both.
+STRICT_ENV: Final[str] = "APOTHEM_CONFORMITY_STRICT"
+_STRICT_TRUTHY: Final[frozenset[str]] = frozenset({"1", "true", "yes", "on"})
+
+# Canonical recommended-marker forms, kept in lockstep with the static matcher
+# at ``conformity/option_annotation_grep.py``. The canonical postfix is capital
+# ``(Recommended)`` at the exact end of the label with one leading space; the
+# lowercase ``(recommended)`` form is a banned variant. We re-derive the same
+# anchored patterns here because the static matcher operates on Markdown lines
+# (``- `Label`:``) while this validator operates on a structured label string,
+# so the line-shaped label regexes there do not apply — but the postfix rules
+# (case, bracket, end-anchor) are identical and MUST NOT diverge.
+_CANONICAL_POSTFIX_RE: Final[re.Pattern[str]] = re.compile(r" \(Recommended\)$")
+_LOWERCASE_POSTFIX_RE: Final[re.Pattern[str]] = re.compile(r"\(recommended\)\s*$")
+# Any non-canonical bracketing / spacing of the recommended token at the label
+# tail: ``[Recommended]``, ``(Rec)``, ``(Recommended )``, ``( Recommended )`` —
+# anything that names "recommend" near the tail but is not the exact canonical
+# ``" (Recommended)"`` postfix.
+_NONCANONICAL_TAIL_RE: Final[re.Pattern[str]] = re.compile(
+    r"[\[(]\s*rec(?:ommend(?:ed)?)?\s*[\])]\s*$", re.IGNORECASE
+)
+
+# Destructive-intent label tokens. A recommended marker on a clearly-destructive
+# option contradicts the no-default floor for irreversible operations
+# (``rules/interactive-questions-canonical-shapes.md`` §5.8): a recommendation
+# marker on an irreversible action steers the operator toward the dangerous path.
+_DESTRUCTIVE_LABEL_RE: Final[re.Pattern[str]] = re.compile(
+    r"\b("
+    r"delete|remove|retire|discard|destroy|wipe|erase|drop|purge|"
+    r"overwrite|reset|revert|rm|truncate|force[- ]?push"
+    r")\b",
+    re.IGNORECASE,
+)
+
+# A "substantive" option for the NUDGE heuristic: anything that is not the
+# harness-implicit free-text escape hatch (the ``Other`` option the tool adds).
+_IMPLICIT_OTHER_RE: Final[re.Pattern[str]] = re.compile(r"^\s*other\s*$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One validation result against the canonical marker rules.
+
+    ``severity`` is ``"finding"`` for an objectively-decidable well-formedness
+    violation (escalatable to a block under strict mode) or ``"nudge"`` for the
+    heuristic missing-marker advisory (never escalated — it can only advise).
+    """
+
+    severity: str
+    kind: str
+    question_index: int
+    label: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Aggregate outcome of validating one ``AskUserQuestion`` payload."""
+
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def wellformedness_findings(self) -> list[Finding]:
+        """Objectively-decidable violations (block-eligible under strict mode)."""
+        return [f for f in self.findings if f.severity == "finding"]
+
+    @property
+    def nudges(self) -> list[Finding]:
+        """Heuristic missing-marker advisories (never block)."""
+        return [f for f in self.findings if f.severity == "nudge"]
+
+
+def strict_enabled(argv: list[str] | None = None) -> bool:
+    """Return True when the strict opt-in is active.
+
+    Mirrors ``conformity/gate.py``: the ``--strict`` flag or a truthy
+    ``APOTHEM_CONFORMITY_STRICT`` environment variable enables blocking.
+    """
+    args = argv if argv is not None else sys.argv[1:]
+    if "--strict" in args:
+        return True
+    return os.environ.get(STRICT_ENV, "").strip().lower() in _STRICT_TRUTHY
+
+
+def _label_is_canonical_marked(label: str) -> bool:
+    """True iff the label ends with the exact canonical ``" (Recommended)"``."""
+    return _CANONICAL_POSTFIX_RE.search(label) is not None
+
+
+def _label_has_lowercase_marker(label: str) -> bool:
+    """True iff the label ends with the banned lowercase ``(recommended)``."""
+    return _LOWERCASE_POSTFIX_RE.search(label) is not None
+
+
+def _label_has_noncanonical_marker(label: str) -> bool:
+    """True iff the label tail names a recommended token in a non-canonical form.
+
+    Catches ``[Recommended]``, ``(Rec)``, ``(Recommended )``, ``( Recommended )``
+    and similar bracketed tail variants. The canonical ``" (Recommended)"`` form
+    is excluded (it is the legitimate postfix); the lowercase variant is reported
+    separately as ``non-canonical-postfix-case`` so its detail is precise.
+    """
+    if _label_is_canonical_marked(label):
+        return False
+    if _label_has_lowercase_marker(label):
+        return False
+    return _NONCANONICAL_TAIL_RE.search(label) is not None
+
+
+def _is_destructive_label(label: str) -> bool:
+    """True iff the label names a clearly-destructive / irreversible action."""
+    return _DESTRUCTIVE_LABEL_RE.search(label) is not None
+
+
+def _is_substantive_option(label: str) -> bool:
+    """True iff the option is a real choice, not the implicit ``Other`` escape."""
+    return bool(label.strip()) and _IMPLICIT_OTHER_RE.match(label) is None
+
+
+def _option_labels(question: dict[str, object]) -> list[str]:
+    """Extract the option labels from one question, tolerating shape drift."""
+    raw_options = question.get("options")
+    if not isinstance(raw_options, list):
+        return []
+    labels: list[str] = []
+    for option in raw_options:
+        if isinstance(option, str):
+            labels.append(option)
+        elif isinstance(option, dict):
+            label = option.get("label")
+            if isinstance(label, str):
+                labels.append(label)
+    return labels
+
+
+def _validate_question(index: int, question: dict[str, object]) -> list[Finding]:
+    """Validate one question's option labels against the canonical marker rules."""
+    findings: list[Finding] = []
+    labels = _option_labels(question)
+    if not labels:
+        return findings
+    multi_select = bool(question.get("multiSelect", False))
+
+    canonical_marked = 0
+    for label in labels:
+        if _label_has_lowercase_marker(label):
+            findings.append(
+                Finding(
+                    severity="finding",
+                    kind="non-canonical-postfix-case",
+                    question_index=index,
+                    label=label,
+                    detail=(
+                        "label uses lowercase (recommended); the canonical form "
+                        "is the capital (Recommended) postfix"
+                    ),
+                )
+            )
+        elif _label_has_noncanonical_marker(label):
+            findings.append(
+                Finding(
+                    severity="finding",
+                    kind="non-canonical-postfix-form",
+                    question_index=index,
+                    label=label,
+                    detail=(
+                        "label names a recommended token in a non-canonical "
+                        "bracket/spacing form; the canonical form is the exact "
+                        '" (Recommended)" postfix with one leading space at the '
+                        "end of the label"
+                    ),
+                )
+            )
+        elif _label_is_canonical_marked(label):
+            canonical_marked += 1
+            if _is_destructive_label(label):
+                findings.append(
+                    Finding(
+                        severity="finding",
+                        kind="recommended-on-destructive",
+                        question_index=index,
+                        label=label,
+                        detail=(
+                            "the (Recommended) marker rides a clearly-destructive "
+                            "option; an irreversible action must not be the "
+                            "recommended (and easy) path"
+                        ),
+                    )
+                )
+
+    if not multi_select and canonical_marked > 1:
+        findings.append(
+            Finding(
+                severity="finding",
+                kind="single-select-multi-recommended",
+                question_index=index,
+                label="",
+                detail=(
+                    f"single-select question carries {canonical_marked} "
+                    "(Recommended) markers; at most one is permitted "
+                    "(set multiSelect: true to recommend several)"
+                ),
+            )
+        )
+
+    # NUDGE: a single-select question with two or more substantive options and
+    # zero markers. Heuristic only — the native payload carries no separate
+    # "recommended" field, so a missing marker cannot be proven a defect.
+    substantive = [lab for lab in labels if _is_substantive_option(lab)]
+    if not multi_select and len(substantive) >= 2 and canonical_marked == 0:
+        findings.append(
+            Finding(
+                severity="nudge",
+                kind="no-recommended-marker",
+                question_index=index,
+                label="",
+                detail=(
+                    f"single-select question offers {len(substantive)} "
+                    "substantive options but marks none (Recommended); the "
+                    "option-annotation discipline advises marking the "
+                    "recommended option so the operator sees the agent's "
+                    "evaluation"
+                ),
+            )
+        )
+    return findings
+
+
+def validate_payload(payload: dict[str, object] | None) -> ValidationResult:
+    """Validate an ``AskUserQuestion`` tool payload's option markers.
+
+    Pre-condition: *payload* is the harness ``PreToolUse`` stdin object (or
+    ``None`` when stdin carried no parseable object). Post-condition: every
+    well-formedness violation and missing-marker nudge across every question is
+    enumerated; an unparseable or shapeless payload yields an empty result
+    (fail-open — nothing to validate).
+    """
+    if not payload:
+        return ValidationResult()
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return ValidationResult()
+    questions = tool_input.get("questions")
+    if not isinstance(questions, list):
+        return ValidationResult()
+    findings: list[Finding] = []
+    for index, question in enumerate(questions):
+        if isinstance(question, dict):
+            findings.extend(_validate_question(index, question))
+    return ValidationResult(findings=findings)
+
+
+def _read_payload() -> dict[str, object] | None:
+    """Read and parse the hook's stdin JSON payload, fail-open on any error."""
+    try:
+        if sys.stdin.isatty():
+            return None
+        raw = sys.stdin.read()
+    except OSError:
+        return None
+    if not raw or not raw.strip():
+        return None
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _format_findings(findings: list[Finding]) -> str:
+    """Render findings as one human-readable line each."""
+    lines: list[str] = []
+    for finding in findings:
+        label = f" label={finding.label!r}" if finding.label else ""
+        lines.append(
+            f"  - [Q{finding.question_index}] {finding.kind}{label}: {finding.detail}"
+        )
+    return "\n".join(lines)
+
+
+def build_envelope(result: ValidationResult, *, strict: bool) -> dict[str, object]:
+    """Map a validation result to a hook-output envelope.
+
+    Default (advisory): a ``systemMessage`` surfacing well-formedness findings
+    and nudges; the question proceeds. Strict: a ``decision: block`` envelope
+    when well-formedness findings exist (nudges never block). A clean result
+    yields an empty envelope (the question proceeds silently).
+    """
+    wellformedness = result.wellformedness_findings
+    nudges = result.nudges
+    if strict and wellformedness:
+        reason_lines = [
+            "Apothem AskUserQuestion guard (strict): the option set carries "
+            "(Recommended)-marker well-formedness violation(s). Fix the "
+            "label(s) and re-ask:",
+            _format_findings(wellformedness),
+        ]
+        if nudges:
+            reason_lines.append("Advisory (not blocking):\n" + _format_findings(nudges))
+        return {"decision": "block", "reason": "\n".join(reason_lines)}
+
+    advisory: list[Finding] = [*wellformedness, *nudges]
+    if not advisory:
+        return {}
+    header = (
+        "Apothem AskUserQuestion guard (advisory): review the "
+        "(Recommended)-marker finding(s) below; the question proceeds. "
+        "Set APOTHEM_CONFORMITY_STRICT=1 (or pass --strict) to block on "
+        "well-formedness violations."
+    )
+    return {"systemMessage": header + "\n" + _format_findings(advisory)}
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point. Validates the payload and emits one envelope; never raises.
+
+    FAIL-OPEN: any unexpected exception is swallowed and an empty (allow)
+    envelope is written, so a validator bug never crashes the operator's
+    question.
+    """
+    try:
+        strict = strict_enabled(argv)
+        payload = _read_payload()
+        result = validate_payload(payload)
+        envelope = build_envelope(result, strict=strict)
+        sys.stdout.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+    except Exception:  # noqa: BLE001, RUF100 - fail-open boundary: a validator error must never block the operator's question; emit an allow envelope and proceed (BLE001 is the intent marker; RUF100 self-suppresses because ruff's BLE family is not active)
+        sys.stdout.write("{}\n")
+
+
+if __name__ == "__main__":
+    main()