@ahmed-g-gad/apothem 0.1.1

package/src/apothem/hooks/messages/posttooluse-proactive-compaction.md

@@ -0,0 +1,46 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Proactive-compaction tracker for PostToolUse tool calls.
+
+> Advisory: this hook reports; it never blocks. A PostToolUse hook cannot block the tool call that already ran.
+
+This handler mechanically operationalizes the CM-19 proactive-compaction
+triggers (`rules/context-management-protocol.md` §2): the ~18-tool-call window
+and the large-cumulative-emission band. The dispatcher routes this message
+basename to the per-session activity tracker (`hooks/proactive_compaction_tracker.py`)
+rather than emitting this static context — the tracker maintains lightweight
+per-session counters keyed off the `session_id` field of the hook stdin payload
+and surfaces a concise proactive-compaction advisory once a threshold crosses,
+then resets the counters (anti-spam back-off) so it does not fire on every
+subsequent tool call.
+
+**Scope.** Fires on every PostToolUse tool call (empty matcher — all tools).
+Per session, it tracks the tool-call count and a cumulative tool-output-size
+estimate since the last advisory.
+
+**Thresholds (configurable).**
+
+- `APOTHEM_PROACTIVE_COMPACTION_TOOL_THRESHOLD` (default `18`) — tool calls
+  since the last advisory; mirrors the §2 "~18 tool calls" trigger.
+- `APOTHEM_PROACTIVE_COMPACTION_OUTPUT_THRESHOLD` (default `20000`) — cumulative
+  tool-output bytes since the last advisory; a mechanical proxy for the §2
+  "500-line emission" / heavy-read band (~20 KB). A non-positive or
+  unparseable override falls back to the default, so a typo can never silently
+  disable the tracker.
+
+**Advisory shape.** When a threshold crosses, the tracker emits a `systemMessage`
+plus `additionalContext` recommending the operator externalize in-conversation
+state (PROGRESS.md Resumption Contract + PLAN-NOTES.md, or a scratch file under
+the active harness's config root when no suite is active) and then compact, so
+context stays lean per the blind-execution invariant.
+
+**State.** Per-session counters live under the OS temp dir
+(`<tempdir>/apothem-proactive-compaction/<session>.json`) — never inside the
+repository's tracked tree. A missing, empty, or corrupt counter file degrades to
+"start counting again", never a crash.
+
+**Fail-disposition.** Fail-open at every layer. The Python dispatcher at
+`hooks/dispatch.py` converts any handler error to a structured failure envelope
+on stdout; the tracker's own `main` swallows every exception and emits an empty
+envelope. A tracker fault therefore costs nothing — never a blocked or stalled
+tool call.

package/src/apothem/hooks/messages/precompact.md

@@ -0,0 +1,14 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Pre-compaction protocol (CM-24 §2.3). Externalize all in-conversation state BEFORE the harness compresses context.
+
+With an active plan suite — execute IN ORDER (all mandatory):
+
+1. Verify PROGRESS.md Resumption Contract reflects current state — phase, task, next action, convention anchors, critical-files manifest. Update any stale fields.
+2. Verify every decision made this session is recorded in PLAN-NOTES.md § Resolved Decisions.
+3. Verify Phase Output Registry reflects every artifact produced this phase with verified status (and actual path).
+4. Identify any state that exists ONLY in conversation (not in any durable file). Externalize now — task state → PROGRESS.md, decisions → PLAN-NOTES.md, working notes → scratch file under the active suite's `_inputs/` directory (or the active harness's config root when no suite is active).
+
+No active suite: externalize accumulated session decisions and working notes to a scratch file under the active harness's config root.
+
+Gate. If externalization is incomplete, complete it BEFORE compaction proceeds — compaction with state still in conversation loses that state.

package/src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md

@@ -0,0 +1,65 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Call-time `(Recommended)`-marker guard for `AskUserQuestion` tool calls.
+
+> Advisory: this guard reports; it does not block by default. The strict
+> opt-in (`APOTHEM_CONFORMITY_STRICT=1` or `--strict`) escalates
+> well-formedness violations to a block.
+
+This guard closes the previously documented-but-unenforced call-time gap in the
+`(Recommended)` interactive-question guarantee. The option-annotation matchers
+(`conformity/option_annotation_grep.py`) scan committed `*.md` artifacts only;
+nothing inspected the LIVE `AskUserQuestion` tool payload at the moment the
+agent asks the operator. This dispatch-routed `PreToolUse` handler
+(`hooks/askuserquestion_validator.py`) inspects the live payload — the
+`questions` array, each question's `options[].label` and `multiSelect` — and
+validates marker well-formedness against the canonical rule at
+`rules/interactive-questions-canonical-shapes.md` §2.1.
+
+**Scope.** Fires on `AskUserQuestion` tool calls. The dispatcher routes this
+message basename to the validator rather than emitting a static context, so the
+check runs on the live payload at call time.
+
+**Well-formedness findings (block-eligible under the strict opt-in).** Each is
+objectively decidable from the payload alone:
+
+- **non-canonical-postfix-case** — a label ends with the banned lowercase
+  `(recommended)`; the canonical form is the capital `(Recommended)`.
+- **non-canonical-postfix-form** — a label names a recommended token in a
+  non-canonical bracket / spacing form (`[Recommended]`, `(Rec)`,
+  `(Recommended )`, `( Recommended )`); the canonical form is the exact
+  ` (Recommended)` postfix with one leading space at the end of the label.
+- **recommended-on-destructive** — the marker rides a clearly-destructive
+  option label (delete / remove / discard / overwrite / revert / …); an
+  irreversible action must not be the recommended (and easy) path, per the
+  destructive-op no-default floor at
+  `rules/interactive-questions-canonical-shapes.md` §5.8.
+- **single-select-multi-recommended** — a `multiSelect: false` question carries
+  the marker on more than one option; at most one is permitted (set
+  `multiSelect: true` to recommend several).
+
+**Nudge (advisory only — never blocks).** A `multiSelect: false` question with
+two or more substantive options and zero `(Recommended)` markers is *advised*
+to mark its recommended option. The native `AskUserQuestion` payload carries no
+separate "recommended" field — the marker IS the only signal of which option is
+recommended — so a missing marker cannot be proven a defect. This is a
+heuristic nudge, not a hard rule.
+
+**What the runtime check CAN and CANNOT guarantee.** It CAN guarantee marker
+well-formedness (a present marker is in the canonical form, placed correctly,
+not on a destructive option, at most one per single-select question). It CANNOT
+force a recommendation to exist — that is a behavioral-convention obligation the
+rules carry, surfaced here only as the advisory nudge.
+
+**Advisory vs. strict.** By default the guard emits a `systemMessage` surfacing
+the findings and nudges; the question proceeds. Under the strict opt-in
+(`APOTHEM_CONFORMITY_STRICT=1` or `--strict`, mirroring `conformity/gate.py`),
+well-formedness findings (never the nudge) escalate to a
+`{"decision":"block","reason":"…"}` envelope.
+
+**Fail-disposition.** Fail-open. Any exception inside the validator — a
+malformed payload, a shapeless `questions` array, an unexpected option type —
+yields an empty (allow) envelope, so a validator error never crashes the
+operator's question. The dispatcher's outer boundary is fail-open too: a
+dispatch error converts to a structured failure envelope on stdout and the
+question proceeds.

package/src/apothem/hooks/messages/pretooluse-bash-plan-guard.md

@@ -0,0 +1,97 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Plans-Discipline write guard for Bash tool calls (companion to
+`pretooluse-write-plan-guard.md`).
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+This guard surfaces the Plans-Locality discipline at the shell-redirection
+surface so a shell-redirected write does not bypass the Write-route guard. It
+reports a redirection that would land a plan outside the sole canonical
+project-local plans tree `<project-root>/.apothem/plans/` and recommends a
+redirection; the operator decides. A legacy `<project-root>/.plans/` tree is no
+longer canonical and is redirect-recommended to `.apothem/plans/` (operators
+upgrade it via `apothem migrate-workspace`). Mechanical enforcement of
+Plans-Locality runs in CI and pre-commit via the strict conformity corpus gate
+(`no_global_plans_grep`), not at this tool call.
+
+**Scope.** Fires on every PreToolUse Bash event. Scans the Bash command
+string for **output-redirection patterns** that would write a file
+under a global plans directory (a `.plans/` or `.apothem/plans/` directory
+under a non-project root — such as `~/.claude/.plans/` or `~/.apothem/plans/`
+for users on the Claude Code harness) or any other global-ecosystem path with
+plan-shaped content. Applies the same redirect-required / soft-flag / allow verdict matrix
+that the Write / Edit / NotebookEdit guard applies, projected onto the
+shell-redirection surface. Surfaces the foundational Plans-Locality
+mandate (`CLAUDE.md` Plans Discipline; spec `_spec/spec.md` §3 +
+§5.5.1) at the Bash tool-call surface so shell-redirected writes do not
+bypass the Write-route guard.
+
+**Output-redirection patterns inspected.**
+
+| Pattern class | Examples |
+|---------------|----------|
+| **POSIX redirect** | `cmd > path` · `cmd >> path` · `cmd 2> path` · `cmd 2>> path` · `cmd &> path` · `cmd >| path` |
+| **Heredoc emission** | `cat > path <<EOF` · `cat >> path <<'EOF'` · `tee path <<EOF` (with or without `-a`) |
+| **`tee` invocations** | `cmd \| tee path` · `cmd \| tee -a path` · `cmd \| tee path1 path2` |
+| **File-creation utilities** | `touch path` · `cp src path` · `mv src path` · `install -m … src path` |
+| **Editor-pipe** | `printf '...' > path` · `echo '...' > path` · `python -c '...' > path` |
+| **PowerShell analogs** | `Out-File -FilePath path` · `Set-Content -Path path` · `Add-Content -Path path` · `... > path` (PowerShell pipeline redirect) |
+
+The scanner extracts every `path` argument from these patterns and
+applies the same path-classification predicate as
+`pretooluse-write-plan-guard.md`:
+
+1. Resolve every extracted path to its absolute form (relative paths are
+   resolved against the Bash command's working directory, falling back to
+   the tool-call's `cwd` field when present).
+2. Resolve the **current project root** by walking from the working
+   directory to the nearest enclosing `.git/` directory; when no
+   enclosing repo exists, the working directory is the project root.
+3. Apply the verdict matrix (recursion-self allow / redirect-required /
+   soft-flag / allow-otherwise) per the table in
+   `pretooluse-write-plan-guard.md`.
+
+**Action — redirect-required path.**
+
+Invoke the structured-inquiry channel using the canonical Plans-Locality option-set at `rules/interactive-questions-canonical-shapes.md` §5.9.1 (the 2-option redirect-required variant; Bash-tool label form: `rewrite-redirect-to-project-plans` / `cancel`). Substitute the actual rejected path and resolved project root at invocation time. The recommended option redirects the shell-redirected write to the canonical project-local plans tree `<project-root>/.apothem/plans/`; the operator decides.
+
+Recursion-self case: when the resolved project root IS the Apothem source repo itself (for Claude Code users this is `~/.claude/`), the redirection IS canonical. Pass through silently. The recursion case is the ONLY allowed shell-redirect path under the apothem-source-repo plans tree `.apothem/plans/`.
+
+**Action — soft-flag path.**
+
+Invoke the structured-inquiry channel using the canonical Plans-Locality option-set at `rules/interactive-questions-canonical-shapes.md` §5.9.2 (soft-flag 3-option variant; Bash-tool label form: `rewrite-redirect-to-project-plans` / `run-as-proposed` / `cancel`). Substitute the actual flagged path at invocation time.
+
+**Action — allow path.**
+
+When every extracted path is allow-class (the canonical project-local plans
+tree `<project-root>/.apothem/plans/`, or any non-plan-shaped path outside the
+protected classes, or no redirection at all), pass through silently. The vast
+majority of Bash commands fall into this class.
+
+**Heuristic robustness.**
+
+- Quoted paths are unwrapped (`> "path with spaces.md"` → `path with spaces.md`).
+- Variable expansions are best-effort (`> $HOME/.plans/x.md` resolves
+  `$HOME` against the tool-call's environment block when present;
+  otherwise treated as a soft-flag candidate pending operator review).
+- Glob patterns are inspected as literal paths (a redirect target is a
+  single file, not a glob expansion site).
+- Subshell-piped commands (`(cmd1; cmd2) > path`) are inspected at the
+  outer redirect.
+- Multi-statement commands separated by `;` / `&&` / `||` are inspected
+  per-statement.
+
+**Fail-disposition.** Two layers govern failure. (a) The Python dispatcher at
+`hooks/dispatch.py` is fail-open: a hook error (parse failure on the Bash
+command, path normalization exception, project-root resolution failure, Python
+exception inside the predicate) converts to a structured failure envelope on
+stdout and the Bash call proceeds, so a harness error never silently blocks the
+tool call. (b) The assistant's interpretation of this context is fail-closed on
+a detected verdict: when the scan returns redirect-required or soft-flag, the
+directive is to surface the redirection via the structured-inquiry channel and
+let the operator decide before re-issuing the command. The two layers are
+non-redundant: the dispatcher protects the runtime, this context protects the
+Plans-Locality discipline. The Plans-Locality invariant itself is enforced
+mechanically in CI and pre-commit via the strict conformity corpus gate
+(`no_global_plans_grep`).

package/src/apothem/hooks/messages/pretooluse-bash.md

@@ -0,0 +1,39 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+CM-7 git-artifact isolation + M12 numeric-prefix discipline + M15 human-only authorship.
+
+Trigger. Bash command contains any of `git commit`, `git checkout -b`, `git branch`, `git tag`, `git merge -m`, `git rebase --exec`, `git stash push -m`, `git notes add`, `git mv`, `git rm`.
+
+The hook scans the message / name / path argument for three independent classes of finding. Any one finding is a STOP — fix the cause, do not silently strip, and re-issue the Bash call.
+
+## Scan 1 — CM-7 plan-internal isolation
+
+Scan the message / name argument for any term in the canonical forbidden-terms block at CM-7 (TM-N, CM-N, CP-N, "Resumption Contract", "Phase Output Registry", "convention anchors", phase-folder names, plan-suite file names, seriousness-level names).
+
+On hit: STOP. Rewrite the message in natural domain language describing the WHAT and WHY of the change, not the plan structure that produced it. Re-issue.
+
+## Scan 2 — M12 numeric-prefix discipline (suite-root and root-level singletons)
+
+Scan the path argument of `git mv`, `git rm`, and any path appearing in the commit message body (referenced files, renames). Detect candidate violations:
+
+- A target path matching `<plans-root>/{suite}/00-<NAME>.md` (or any `0[0-9]-<NAME>.md` at the suite root, not inside `phases/`), where `<plans-root>` is the active plan-suite root — `<project-root>/.apothem/plans/` in host projects, and the apothem-source-repo plan-suite tree during ecosystem authoring (the legacy `.plans/` tree resolves to `~/.claude/.plans/` for Claude Code users) — the `NN-` numeric prefix is forbidden on suite-root infrastructure files per `rules/canonical-layout.md` §2.1. Numeric prefixes apply only where ordering is intrinsic (phase folders, sub-phase folders, host-discovered ordinal naming schemes).
+- A new file class introduced at any root level whose first instance carries a numeric prefix without sibling-set evidence that ordering is intrinsic — the prefix mis-signals an ordering relationship that does not exist.
+
+On hit: STOP. Re-issue the operation against an unprefixed target path. Existing prefixed instances at suite roots that pre-date this discipline are migrated through a normal rename change-set, not silently overwritten.
+
+## Scan 3 — M15 human-only authorship discipline
+
+Scan the message / name / annotation argument of every git-write command (commit, tag annotation, stash name, notes body, branch name, PR-relevant text in `gh pr create` invocations) for **agent-attribution patterns**:
+
+- Trailer patterns: any line matching `^\s*Co-Authored-By:.*` whose value contains a non-human-author signal — `claude` / `gpt` / `chatgpt` / `copilot` / `cursor` / `gemini` / `llama` / `bard` / `anthropic` / `openai` / `microsoft` / `noreply@.*ai` / `noreply@.*-bot` / `bot@` / any other LLM / AI assistant / automated agent name.
+- Body-narrative patterns: phrases like "🤖 Generated with", "Generated with [Claude Code]", "Generated by an AI", "Co-authored by an AI", "with assistance from `<agent>`", "written by `<model>`", "`<agent>` implemented this", "`<agent>` drafted", "based on `<model>`'s suggestion".
+- Subject-line patterns: any subject containing an agent-authorship marker (`[claude]`, `[gpt]`, `[ai]`, `🤖`, `Generated by:`, `From: <agent>`).
+- Author / committer field manipulation: detect `git -c user.email=…` overrides where the override targets a non-human address (`noreply@anthropic.com`, `noreply@openai.com`, `<bot>@…`).
+
+On hit: STOP. Strip the agent-attribution and re-issue without it. The sole authorship surface git resolves at commit time is the operator's own identity, per `rules/production-ready-prs.md` §6 Human-only authorship. The agent acts as an instrument the operator wields; never as a co-author of record.
+
+**Carve-out — legitimate product / runtime references.** Subject lines and body text that reference a product or runtime by name (e.g., "Claude Code never stalls", "harness honors Claude Code's hook contract", `CLAUDE_PROJECT_DIR`) are descriptions of the product, not authorship signals; they pass the scan. The discriminator: authorship signals attach the named entity to the **act of authoring** ("co-authored by Claude", "generated by Claude"); product references attach the named entity to the **subject under discussion** ("Claude Code's hook contract", "the CLAUDE.md file"). When in doubt, rephrase to refer to the product as a noun rather than to the agent as a verb-doer.
+
+## Non-matching commands
+
+No action. The hook is scoped to the ten git-write triggers above; other Bash commands pass unaffected.

package/src/apothem/hooks/messages/pretooluse-conformity.md

@@ -0,0 +1,70 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Conformity-gate orchestrator (PreToolUse Write/Edit)
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+The conformity-gate orchestrator at `<harness-root>/apothem/conformity/gate.py`
+runs the registered per-Write greps against the Write/Edit tool input before the
+tool fires. The orchestrator reads the harness's tool-input JSON from stdin,
+extracts the content (Write `content` field, Edit `new_string` field) and the
+target path, and dispatches every registered per-Write matcher via `importlib`.
+Each grep returns a structured result; the orchestrator aggregates them into a
+single JSON report. The findings are surfaced as an advisory nudge plus a
+definitive next step — the per-Write surface does not block the tool call (the
+EN-1 advisory-by-default posture). Strict enforcement runs separately in CI and
+pre-commit via the corpus gate (`gate --all-perwrite --strict`).
+
+## Per-Write grep coverage
+
+The authoritative full set is `conformity/gate.py` `GREP_MODULES`; the per-Write
+dispatch runs **every** registered matcher in that tuple (count derived from the
+registry, never hardcoded here). The matchers partition into a small blocking set
+(`_BLOCKING_PER_WRITE_GREPS` — deterministic, low-false-positive, green over the
+tracked corpus, so a finding fails the strict corpus run) and the remaining
+advisory set (`_ADVISORY_PER_WRITE_GREPS` — reported with a named remediation
+owner per `_ADVISORY_RATIONALE`, never gating). Representative matchers and their
+cited rules:
+
+| Grep | Rule cited | Partition |
+|------|------------|-----------|
+| user-confirm-grep | M5 authority-inquiry §10 | advisory |
+| option-annotation-grep | M7 option-annotation | blocking |
+| binding-reciprocity-grep | M10 bidirectional-binding §Notation | blocking |
+| completion-claim-grep | M12 / M15 completion claims | blocking |
+| unpinned-action-grep | M15 production-ready §Supply-chain | blocking |
+| hedging-grep | M8 definitiveness §Hedging | advisory |
+| secret-leak-grep | M13.8 + M15 production-ready | advisory |
+| file-header-grep | SPDX authorship-header policy | advisory |
+| always-on-budget-grep | token-budget-discipline §Always-on body budget | advisory |
+
+The blocking-vs-advisory classification is asserted at import time
+(`_assert_perwrite_partition`) so every registered matcher is classified.
+
+## Performance budget
+
+Per-grep wall-clock is bounded by `PER_GREP_BUDGET_SECONDS` (0.520 s) in
+`gate.py`; `over_budget: true` in the JSON output flags a matcher that exceeded
+it. The budget surfaces as a watch item in the report — it does not block the
+write (the hook's own ceiling and the fail-open dispatcher govern hard limits).
+
+## Exit / disposition contract
+
+- **Advisory finding (per-Write hook):** the orchestrator surfaces the JSON
+  report (one entry per matcher, with findings) and a recommended next step; the
+  Write/Edit proceeds. The operator decides whether to address a finding before
+  re-issuing.
+- **Strict enforcement (CI / pre-commit corpus):** `gate --all-perwrite . --strict`
+  exits non-zero when a **blocking** matcher reports a finding over the tracked
+  corpus; that is where the conformity floor is enforced, not at the tool call.
+- **Fail-disposition:** the dispatcher at `hooks/dispatch.py` is fail-open — any
+  exception inside a matcher or the orchestrator converts to a structured failure
+  envelope on stdout and the tool call proceeds, so a harness error never
+  silently blocks a write.
+
+## Action on a finding
+
+The operator inspects the JSON report (one entry per matcher, with findings for
+the matchers that flagged), addresses the reported violations in the candidate
+content where warranted, and re-issues the Write/Edit. Each finding carries its
+rule anchor for routing.

package/src/apothem/hooks/messages/pretooluse-dependency-guard.md

@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Dependency-manifest supply-chain guard (advisory).
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+Scope. Fires on Write/Edit to dependency manifests and their lockfiles: `pyproject.toml`, `requirements*.txt`, `package.json`, `Cargo.toml`, `go.mod`, `Gemfile`, and the matching lockfiles (`uv.lock`, `poetry.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `go.sum`, `Gemfile.lock`). Non-matching paths pass unaffected.
+
+This guard protects the operator's supply-chain posture per `rules/production-ready-prs.md` §3. It is advisory — it never blocks a correct manifest; it surfaces a dependency the operator should ratify before it lands.
+
+Trigger / inspected patterns. The guard diffs the new content against the prior manifest and flags a newly-introduced or changed dependency line that matches any of three classes:
+
+- **Unpinned where the host pins exact.** A version range, caret, tilde, or wildcard (`^1.2.0`, `~=2.3`, `>=4`, `*`, `latest`, an unbounded constraint) on a dependency in a manifest whose sibling dependencies are pinned to exact versions (`==1.2.3`, `=1.2.3`, an exact lockfile hash). The discriminator is the host's own ratified pinning policy discovered from the surrounding lines, not an absolute rule — library manifests legitimately carry ranges; production manifests pin.
+- **Untrusted or unknown source.** A dependency pointing at a registry, index URL, or scope the manifest's siblings do not already use (`--index-url`, `--extra-index-url`, a private registry host, an unrecognized npm scope, a non-default crates source).
+- **Git or URL dependency.** A dependency resolved from a git ref or a direct URL (`git+https://…`, a `git = …` table, a `path`/`url` source, a tarball link) rather than a published registry release.
+
+Action — advisory flag. On any flagged line: surface the dependency through the structured-inquiry channel per `rules/interactive-questions.md` with a three-option set — **pin-to-exact (Recommended)** / **accept-as-proposed** / **cancel** — annotated per the canonical option-set discipline at `rules/interactive-questions-canonical-shapes.md` §2 (three-segment body, concrete-driver rationale, named default). The recommended option pins the flagged dependency to the exact resolvable version, citing the supply-chain posture as the driver. The operator's pick is the gate; the guard does not pin silently.
+
+Fail-disposition. Two layers govern failure. (a) The Python dispatcher at `hooks/dispatch.py` is fail-open: a hook error — the diff cannot be parsed, the manifest cannot be read, or any Python exception inside the predicate — converts to a structured failure envelope on stdout and the Write proceeds, so a harness error never silently blocks the tool call. (b) The assistant's interpretation of this context is fail-closed on a detected finding: when a flagged dependency line is found, the directive is to surface it through the structured-inquiry channel and let the operator decide before the line lands. The two layers are non-redundant: the dispatcher protects the runtime, this context protects the supply-chain discipline, which is enforced mechanically in CI and pre-commit.
+
+Non-matching paths. No action. The guard is scoped to the dependency-manifest and lockfile patterns above; every other path class passes unaffected.

package/src/apothem/hooks/messages/pretooluse-edit-header-guard.md

@@ -0,0 +1,61 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+SPDX-header inject guard for Edit tool calls.
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+This guard surfaces the SPDX / authorship-header discipline: every applicable
+file MUST carry the canonical `SPDX-License-Identifier: MIT` header, and an
+edit MUST NOT strip it. It reports a create-via-edit missing the header or an
+edit that would remove the header, and recommends the corrected content; the
+operator decides. Mechanical enforcement of the header invariant runs in CI
+and pre-commit via the strict conformity corpus gate, not at this tool call.
+
+**Scope.** Fires on two corner cases; is a pass-through on all others.
+
+**Corner case A — create-via-edit (new file).** An Edit tool call where the
+target path does not yet exist on disk (the Edit will create the file) and
+the proposed `new_string` constitutes the entire file content. Applies only
+when the target path is an applicable file — not matching any glob in
+`src/apothem/schemas/header-exceptions.txt` and whose suffix or basename maps to a known
+variant family in `src/apothem/conformity/file_header_grep.py` SUFFIX_VARIANT /
+BASENAME_VARIANT — and `file_header_grep.check()` returns HEADER_ABSENT or
+HEADER_MALFORMED for `new_string`.
+
+**Corner case B — header removal (existing file).** An Edit tool call where
+the target path already exists on disk and currently carries the canonical
+`SPDX-License-Identifier: MIT` header line, but the proposed edit would
+remove or overwrite that line (i.e., the `old_string` matches all or part of
+the SPDX header and the `new_string` does not reinstate it). Applies when the
+file is applicable per the same criteria as corner case A.
+
+**Pass-through.** Any Edit that modifies an existing file without touching
+the canonical SPDX header region is a pass-through — no action is taken and
+the edit proceeds uninterrupted.
+
+**Action (both corner cases).**
+
+1. Determine the corrected content. Read `src/apothem/schemas/authorship-header.txt` to
+   obtain the single `SPDX-License-Identifier: MIT` line. Call
+   `_render_canonical_block` (from `src/apothem/conformity/file_header_grep.py`) for the
+   file's variant family to produce the canonical block (the one SPDX line
+   rendered in the family's comment syntax, followed by one trailing blank
+   line). Set the insertion index to 1 when the proposed content opens
+   with a shebang `#!`, otherwise 0. Insert the canonical block at that index
+   into the proposed content to produce the corrected content.
+
+2. Invoke the structured-inquiry channel using the canonical Authorship-Header option-set at `rules/interactive-questions-canonical-shapes.md` §5.10 (3-option set + override-record schema specified there). Substitute the actual path, corner-case label (`create-via-edit` | `header-removal`), and variant at invocation time. The override-record schema's `rule` column carries the Edit-route corner-case label for this hook.
+
+**Fail-disposition.** Two layers govern failure. (a) The Python dispatcher at
+`hooks/dispatch.py` is fail-open: a hook-emission error — `src/apothem/schemas/authorship-header.txt`
+unreadable, `_render_canonical_block` raising, the variant lookup failing, or
+any Python exception inside the predicate — converts to a structured failure
+envelope on stdout and the Edit proceeds, so a harness error never silently
+blocks the tool call. (b) The assistant's interpretation of this context is
+fail-closed on a detected gap: when the validator reports HEADER_ABSENT or
+HEADER_MALFORMED on a create-via-edit, or a header-removing edit, the directive
+is to surface the corrected content via the structured-inquiry channel and let
+the operator decide before re-issuing the Edit. The two layers are
+non-redundant: the dispatcher protects the runtime, this context protects the
+header discipline. The header invariant itself is enforced mechanically in CI
+and pre-commit via the strict conformity corpus gate.

package/src/apothem/hooks/messages/pretooluse-edit.md

@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+CM-7 codebase isolation (Edit scope).
+
+Scope. Triggered on every Edit. Skip when target is inside the Apothem source repo or the active harness's config root (for the Claude Code harness, `~/.claude/`). Apply otherwise.
+
+Action. Scan ONLY the `new_string` (Edit is partial; pre-existing violations elsewhere in the file are out of scope unless this Edit touches them) for any term in the canonical forbidden-terms block at `CLAUDE.md` §CM-7.
+
+On hit: STOP. Rewrite `new_string` in natural domain language. Re-issue the Edit.
+
+Always-on rule body budget. When the Edit target matches `rules/*.md` and the file's frontmatter declares `alwaysApply: true` AND `pathFilter:` empty, the post-Edit body's substantive-token count must satisfy the 500-token ceiling per `rules/token-budget-discipline.md`. The conformity-gate orchestrator runs `conformity/always_on_budget_grep.py` and reports `over_budget` when the ceiling is exceeded. On `over_budget: true`: STOP, decompose along a path-filtered seam into a companion sub-rule, trim the parent body, re-issue.
+
+Scratch-convention path check.
+
+Trigger. Every Edit.
+
+Action. Examine the target `file_path` against the scratch-convention discipline at `rules/context-management-scratch.md` §1 (scratch-file naming + closed-purpose vocabulary) and §2 (Plan-Workflow Directories + suite-locality invariant). REJECT an Edit whose target violates the closed-purpose vocabulary, the disjoint-vocabulary rule, or the suite-locality invariant; ACCEPT otherwise. On a REJECT: STOP and re-issue the Edit at the corrected target per the rule's recovery clause.
+
+Non-matching paths: no action. The scratch-convention check is scoped to the `_inputs/` and `_spec/` directory patterns defined at `rules/context-management-scratch.md` §1–§2 and does not interact with other path classes.
+
+**Fail-disposition.** Two layers govern failure. (a) The Python dispatcher at `hooks/dispatch.py` is fail-open: a hook-emission error converts to a structured failure envelope on stdout and the Edit proceeds, so a harness error never silently blocks the tool call. (b) The assistant's interpretation of this context is fail-closed on a detected violation: when the CM-7 scan, an over-budget body, or a scratch-path REJECT class is hit, the directive is to STOP and re-issue the Edit corrected. The two layers are non-redundant: the dispatcher protects the runtime, this context protects the rule. Mechanical enforcement runs in CI and pre-commit via the strict conformity corpus gate.

package/src/apothem/hooks/messages/pretooluse-eval-guard.md

@@ -0,0 +1,39 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Dynamic-eval / unsafe-deserialization guard — advisory prompt-injection defense.
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+This guard is ADVISORY, not a correctness gate. It surfaces a flagged construct for the operator's decision; it never rewrites code on its own and never blocks on a false positive without a confirmation step. Its purpose is to intercept the prompt-injection and unsafe-eval attack surface before a construct that evaluates untrusted or model-derived input lands in the codebase, per the security-conscious-code discipline (no `eval` / `exec` on untrusted input).
+
+## Scope
+
+Fires on every Write, Edit, and Bash command that introduces dynamic evaluation or unsafe deserialization of a value flowing from an untrusted or model-derived source — a language-model prompt, a language-model response, a tool-call result, network input, or any other input the program does not control. The guard is language- and runtime-agnostic: it inspects the construct's shape, not any specific vendor or framework. Skip the scan when the target is inside the Apothem source repo's own fixture trees that document these patterns as test material.
+
+## Trigger / inspected patterns
+
+The hook flags a construct when a dynamic-evaluation or unsafe-deserialization primitive receives an argument that originates from an untrusted source:
+
+- Dynamic code evaluation — `eval(`, `exec(`, `Function(` / `new Function(`, `compile(` followed by `exec`, or an equivalent eval primitive in the target language — applied to interpolated prompt or response text.
+- Shell-out on interpolated text — `subprocess` / `child_process` / `os.system` / backtick or `Popen` invocations with `shell=True` (or the runtime's shell-on equivalent) where the command string interpolates model-derived or untrusted input.
+- Unsafe deserialization — `pickle.loads`, `yaml.load` without a safe loader, `marshal.loads`, or an equivalent native-object deserializer applied to model output or network input.
+
+The discriminator is the data-flow: the primitive is benign on a trusted literal and a finding on a value that traces back to a prompt, a response, a tool result, or external input.
+
+## Action — advisory flag
+
+On a flagged construct: surface it through the structured-inquiry channel per `rules/interactive-questions.md` with a single-select three-option set, annotated per the canonical option-set discipline at `rules/interactive-questions-canonical-shapes.md` (three-segment body; concrete-driver rationale on every non-neutral recommendation). Do not author the full YAML here.
+
+- **refactor-to-safe (Recommended)** — replace the construct with a non-evaluating equivalent (dispatch table over `eval`, argument-vector subprocess over shell interpolation, safe loader over native deserialization). Recommended because it removes the attack surface rather than documenting it.
+- **accept-with-justification** — proceed with the construct, recording a justification that names why the input is trusted or already sanitized.
+- **cancel** — block the edit; no file is modified.
+
+Every option carries `default-pointer: no-default: user decision required` — the guard proposes no silent default on a security-relevant construct.
+
+## Fail-disposition
+
+Two layers govern failure. (a) The Python dispatcher at `hooks/dispatch.py` is fail-open: a hook error — the inspection itself fails to complete, or any Python exception inside the predicate — converts to a structured failure envelope on stdout and the tool call proceeds, so a harness error never silently blocks it. (b) The assistant's interpretation of this context is fail-closed on a detected construct: when the scan flags a dynamic-evaluation or unsafe-deserialization primitive on untrusted input, the directive is to surface it through the structured-inquiry channel and let the operator decide before the construct lands. The two layers are non-redundant: the dispatcher protects the runtime, this context protects the security discipline, which is enforced mechanically in CI and pre-commit (`bare_except_grep` and the security matchers).
+
+## Non-matching writes
+
+No action. The guard is scoped to the dynamic-evaluation and unsafe-deserialization primitives above applied to untrusted input; every other construct passes unaffected.

package/src/apothem/hooks/messages/pretooluse-notebookedit.md

@@ -0,0 +1,11 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+CM-7 codebase isolation (notebook scope).
+
+Scope. Triggered on every NotebookEdit. Skip when target is inside the Apothem source repo or the active harness's config root (for the Claude Code harness, `~/.claude/`). Apply otherwise.
+
+Action. Apply the CM-7 scan to the new cell content regardless of cell type — code cells, markdown cells, and existing execution-output cells are all artifacts visible outside the Apothem meta-config locations. Reject any term in the canonical forbidden-terms block at `CLAUDE.md` §CM-7.
+
+On hit: STOP. Rewrite the cell in natural domain language. Re-issue the NotebookEdit. Output cells produced by subsequent execution are not scanned at write time but must be cleared before commit if they contain plan-term leaks.
+
+**Fail-disposition.** Two layers govern failure: (a) the Python dispatcher at `hooks/dispatch.py` is fail-open — a hook-emission error converts to a structured failure envelope on stdout and the NotebookEdit proceeds, so harness errors never silently block tool calls; (b) the assistant's interpretation of this context is fail-closed on rule-violation detection — when the CM-7 scan hits, the directive is to STOP and re-issue with the cell rewritten in natural domain language. The two layers are non-redundant: the dispatcher protects the runtime; this context protects the rule.

package/src/apothem/hooks/messages/pretooluse-write-header-guard.md

@@ -0,0 +1,45 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+SPDX-header inject guard for Write tool calls.
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+This guard surfaces the SPDX / authorship-header discipline: every applicable
+new file MUST begin with the canonical `SPDX-License-Identifier: MIT` header.
+It reports a missing or malformed header and recommends the corrected content;
+the operator decides. Mechanical enforcement of the header invariant runs in CI
+and pre-commit via the strict conformity corpus gate, not at this tool call.
+
+**Scope.** Fires when a Write tool call targets an applicable file — any file
+whose path does not match a glob in `src/apothem/schemas/header-exceptions.txt` and whose
+suffix or basename maps to a known variant family in
+`src/apothem/conformity/file_header_grep.py` SUFFIX_VARIANT / BASENAME_VARIANT — and
+`file_header_grep.check()` returns HEADER_ABSENT or HEADER_MALFORMED for the
+proposed content.
+
+**Action.**
+
+1. Determine the corrected content. Read `src/apothem/schemas/authorship-header.txt` to
+   obtain the single `SPDX-License-Identifier: MIT` line. Call
+   `_render_canonical_block` (from `src/apothem/conformity/file_header_grep.py`) for the
+   file's variant family to produce the canonical block (the one SPDX line
+   rendered in the family's comment syntax, followed by one trailing blank
+   line). Set the insertion index to 1 when the proposed content opens
+   with a shebang `#!`, otherwise 0. Insert the canonical block at that index
+   to produce the corrected content.
+
+2. Invoke the structured-inquiry channel using the canonical Authorship-Header option-set at `rules/interactive-questions-canonical-shapes.md` §5.10 (3-option set + override-record schema specified there). Substitute the actual path, rule, and variant at invocation time. The override-record schema's `rule` column carries the Write-route rule label for this hook.
+
+**Fail-disposition.** Two layers govern failure. (a) The Python dispatcher at
+`hooks/dispatch.py` is fail-open: a hook-emission error — `src/apothem/schemas/authorship-header.txt`
+unreadable, `_render_canonical_block` raising, the variant lookup failing, or
+any Python exception inside the predicate — converts to a structured failure
+envelope on stdout and the Write proceeds, so a harness error never silently
+blocks the tool call. (b) The assistant's interpretation of this context is
+fail-closed on a detected gap: when the validator reports HEADER_ABSENT or
+HEADER_MALFORMED, the directive is to surface the corrected content via the
+structured-inquiry channel and let the operator decide before re-issuing the
+Write. The two layers are non-redundant: the dispatcher protects the runtime,
+this context protects the header discipline. The header invariant itself is
+enforced mechanically in CI and pre-commit via the strict conformity corpus
+gate.

package/src/apothem/hooks/messages/pretooluse-write-plan-guard.md

@@ -0,0 +1,72 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Plans-Discipline write guard for Write / Edit / NotebookEdit tool calls.
+
+> Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI.
+
+This guard surfaces the Plans-Locality discipline: planning artifacts live at
+the sole canonical project-local plans tree `<project-root>/.apothem/plans/` —
+never at the active harness's config root and never at any other global
+location. A legacy `<project-root>/.plans/` tree is no longer canonical;
+operators upgrade it via `apothem migrate-workspace`. It reports a write that
+would land a plan outside the canonical tree and recommends a redirection; the
+operator decides. Mechanical enforcement of Plans-Locality runs in CI and
+pre-commit via the strict conformity corpus gate (`no_global_plans_grep`), not
+at this tool call.
+
+**Scope.** Fires when a write-capable tool call (Write, Edit, NotebookEdit)
+targets a path under one of the protected plans-discipline regions, OR targets
+a non-canonical plans path with plan-shaped content. Enforces the
+foundational Plans-Locality mandate: planning artifacts live at the sole
+canonical project-local plans tree `<project-root>/.apothem/plans/`, never at
+the active harness's config root and never at any other global location (per
+`CLAUDE.md` Plans Discipline and the suite-locality and operator-authorship
+contract).
+
+**Decision predicate.**
+
+1. Resolve the **target path** to its absolute form.
+2. Resolve the **current project root** by walking from the working directory
+   to the nearest enclosing `.git/` directory; when no enclosing repo exists,
+   the current working directory is the project root.
+3. Apply the verdict matrix below.
+
+In the conditions below, the **canonical project-local plans tree** is the sole
+location `<project-root>/.apothem/plans/` (the shared Apothem working
+directory's plans child). A legacy `<project-root>/.plans/` tree is no longer
+canonical and is redirect-recommended to `.apothem/plans/`. A **global plans
+location** is a `.plans/` OR `.apothem/plans/` directory under a root that is
+NOT the resolved project root (a harness-config root such as `~/.claude/`, the
+user home such as `~/.apothem/plans/`, or any other non-project location).
+
+| Case | Condition | Verdict |
+|------|-----------|---------|
+| **Project-local (allow)** | Target path is under the resolved project's canonical plans tree `<project-root>/.apothem/plans/` | **Allow** — the canonical project-local plans location |
+| **Legacy-local (redirect-recommended)** | Target path is under the resolved project's legacy `<project-root>/.plans/` tree | **Redirect-recommended** — surface a structured inquiry recommending redirection to `<project-root>/.apothem/plans/` (run `apothem migrate-workspace` to upgrade the legacy tree) |
+| **Recursion-self (allow)** | Resolved project root IS the Apothem source repo itself (case-insensitive on Windows; for Claude Code users that working tree is `~/.claude/`) AND target path is under the apothem-source-repo canonical plans tree `.apothem/plans/` | **Allow** — the working tree IS the Apothem source repo; its own plans tree is the canonical destination for this project |
+| **Redirect-required** | Target path is under a global plans location (a harness-config-root `.plans/` or `.apothem/plans/` directory — e.g., `~/.claude/.plans/`, `~/.claude/<anything>/.plans/`, `~/.apothem/plans/` — for the Claude Code harness) AND project root is NOT the Apothem source repo | **Redirect-required** — surface a structured inquiry recommending redirection to the project-local plans tree |
+| **Soft-flag** | Target path is in another global-ecosystem location (`~/Desktop`, `~/Downloads`, `~/Documents`, `~/`, OR any path outside the resolved project root) AND filename matches `*plan*.md`, `*notes*.md`, `*draft*.md` (case-insensitive) OR proposed content carries plan-shaped frontmatter (`name:`, `phases:`, `master-plan:`, `phase-id:`) | **Soft-flag** — surface a structured inquiry proposing redirection |
+| **Allow** | Any other write | **Allow** unchanged |
+
+**Action — redirect-required path.**
+
+Invoke the structured-inquiry channel using the canonical Plans-Locality option-set at `rules/interactive-questions-canonical-shapes.md` §5.9.1 (the 2-option redirect-required variant). Substitute the actual rejected path and resolved project root at invocation time. The recommended option redirects the write to the canonical project-local plans tree `<project-root>/.apothem/plans/`; the operator decides.
+
+Recursion-self case: when the resolved project root IS the Apothem source repo itself (for Claude Code users that working tree is `~/.claude/`), the write IS canonical. Pass through silently with no structured inquiry. The recursion case is the ONLY allowed write path under the apothem-source-repo plans tree `.apothem/plans/`.
+
+**Action — soft-flag path.**
+
+Invoke the structured-inquiry channel using the canonical Plans-Locality option-set at `rules/interactive-questions-canonical-shapes.md` §5.9.2 (soft-flag 3-option variant). Substitute the actual flagged path at invocation time.
+
+**Fail-disposition.** Two layers govern failure. (a) The Python dispatcher at
+`hooks/dispatch.py` is fail-open: a hook error (project-root resolution failure,
+path normalization exception, Python exception inside the predicate) converts to
+a structured failure envelope on stdout and the write proceeds, so a harness
+error never silently blocks the tool call. (b) The assistant's interpretation of
+this context is fail-closed on a detected verdict: when the predicate returns
+redirect-required or soft-flag, the directive is to surface the redirection via
+the structured-inquiry channel and let the operator decide before re-issuing the
+write. The two layers are non-redundant: the dispatcher protects the runtime,
+this context protects the Plans-Locality discipline. The Plans-Locality
+invariant itself is enforced mechanically in CI and pre-commit via the strict
+conformity corpus gate (`no_global_plans_grep`).