@ahmed-g-gad/apothem 0.1.1

package/src/apothem/hooks/lib/find-pwsh.ps1

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+
+# Purpose: Locate a real PowerShell >= 7 on PATH for any PowerShell-side
+# surface that needs to spawn a pwsh subprocess, rejecting Microsoft Store
+# launcher shims (zero-byte stubs at AppData\Local\Microsoft\WindowsApps
+# that fail at exec time with "Executable not found").
+# Contract: dot-source then call Find-RealPwsh; returns the absolute
+# path to a working pwsh interpreter, or $null when none found. Does
+# not throw on probe failures — silently skips bad candidates so the
+# caller's diagnostic envelope path runs.
+# Sibling files in hooks/lib/: find-pwsh.sh (POSIX counterpart),
+# find-python.ps1 (PowerShell counterpart for Python — paired-template
+# peer), find-python.sh (POSIX counterpart of the Python locator).
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Find-RealPwsh {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [int]$MinMajor = 7
+    )
+
+    $candidates = @('pwsh', 'pwsh-preview')
+    $fallbackPaths = @(
+        (Join-Path $env:ProgramFiles 'PowerShell\7\pwsh.exe'),
+        (Join-Path $env:ProgramFiles 'PowerShell\7-preview\pwsh.exe'),
+        (Join-Path ${env:ProgramFiles(x86)} 'PowerShell\7\pwsh.exe')
+    )
+    $probe = '$PSVersionTable.PSVersion.Major'
+
+    # Phase 1 — PATH probe via Get-Command, rejecting WindowsApps stubs.
+    foreach ($name in $candidates) {
+        $cmds = @(Get-Command $name -All -ErrorAction SilentlyContinue)
+        foreach ($cmd in $cmds) {
+            $src = $cmd.Source
+            if (-not $src) { continue }
+            if ($src -match 'WindowsApps') { continue }
+            $info = Get-Item -LiteralPath $src -ErrorAction SilentlyContinue
+            if (-not $info) { continue }
+            if ($info.Length -lt 1024) { continue }
+
+            $output = $null
+            try { $output = & $src -NoProfile -Command $probe 2>$null } catch { continue }
+            if ($LASTEXITCODE -ne 0) { continue }
+            if (-not $output) { continue }
+            $trimmed = ($output -join '').Trim()
+            $maj = 0
+            if (-not [int]::TryParse($trimmed, [ref]$maj)) { continue }
+            if ($maj -ge $MinMajor) {
+                return $src
+            }
+        }
+    }
+
+    # Phase 2 — canonical Windows install paths.
+    foreach ($candidate in $fallbackPaths) {
+        if (-not $candidate) { continue }
+        if (-not (Test-Path -LiteralPath $candidate)) { continue }
+        $info = Get-Item -LiteralPath $candidate -ErrorAction SilentlyContinue
+        if (-not $info) { continue }
+        if ($info.Length -lt 1024) { continue }
+
+        $output = $null
+        try { $output = & $candidate -NoProfile -Command $probe 2>$null } catch { continue }
+        if ($LASTEXITCODE -ne 0) { continue }
+        if (-not $output) { continue }
+        $trimmed = ($output -join '').Trim()
+        $maj = 0
+        if (-not [int]::TryParse($trimmed, [ref]$maj)) { continue }
+        if ($maj -ge $MinMajor) {
+            return $candidate
+        }
+    }
+
+    return $null
+}

package/src/apothem/hooks/lib/find-pwsh.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+
+# Purpose: Locate a real PowerShell >= 7 on PATH for any bash-side surface
+# that needs to spawn a pwsh subprocess, rejecting Microsoft Store launcher
+# shims (zero-byte stubs at AppData/Local/Microsoft/WindowsApps under
+# WSL/Git-Bash mounts that fail at exec time with "Executable not found").
+# Contract: dot-source then call find_real_pwsh; prints the absolute path
+# on success and returns 0; returns 1 when no candidate satisfies the
+# version floor. Does not throw on probe failures — silently skips bad
+# candidates so the caller's diagnostic envelope path runs.
+# Sibling files in hooks/lib/: find-pwsh.ps1 (PowerShell counterpart),
+# find-python.sh (POSIX counterpart for Python — paired-template peer),
+# find-python.ps1 (PowerShell counterpart of the Python locator).
+#
+# Usage (sourced):  . lib/find-pwsh.sh && p="$(find_real_pwsh)" || exit 1
+# Exit codes: prints absolute path on success; exits 1 if none found.
+
+find_real_pwsh() {
+    local min_major="${1:-7}"
+    local candidates=(pwsh pwsh-preview)
+    local fallback_paths=(
+        /usr/local/bin/pwsh
+        /usr/bin/pwsh
+        /opt/microsoft/powershell/7/pwsh
+        /opt/microsoft/powershell/7-preview/pwsh
+    )
+    local name path size major
+
+    # Phase 1 — PATH probe via type -ap, rejecting WindowsApps stubs.
+    for name in "${candidates[@]}"; do
+        while IFS= read -r path; do
+            [[ -z "$path" ]] && continue
+            case "$path" in *WindowsApps*) continue ;; esac
+            if [[ ! -x "$path" ]]; then continue; fi
+            size=$(wc -c < "$path" 2>/dev/null || echo 0)
+            [[ "$size" -lt 1024 ]] && continue
+            local probe_output
+            # SC2016: the single-quoted expression is intentionally NOT
+            # bash-expanded — it's a PowerShell expression evaluated by pwsh.
+            # shellcheck disable=SC2016
+            probe_output=$("$path" -NoProfile -Command '$PSVersionTable.PSVersion.Major' 2>/dev/null) || continue
+            probe_output="${probe_output//$'\r'/}"
+            probe_output="${probe_output//[[:space:]]/}"
+            major="$probe_output"
+            [[ -z "$major" ]] && continue
+            [[ ! "$major" =~ ^[0-9]+$ ]] && continue
+            if (( major >= min_major )); then
+                printf '%s\n' "$path"
+                return 0
+            fi
+        done < <(type -ap "$name" 2>/dev/null)
+    done
+
+    # Phase 2 — canonical install paths (Linux / macOS).
+    for path in "${fallback_paths[@]}"; do
+        [[ -x "$path" ]] || continue
+        size=$(wc -c < "$path" 2>/dev/null || echo 0)
+        [[ "$size" -lt 1024 ]] && continue
+        local probe_output
+        # SC2016: same intentional PowerShell expression as Phase 1.
+        # shellcheck disable=SC2016
+        probe_output=$("$path" -NoProfile -Command '$PSVersionTable.PSVersion.Major' 2>/dev/null) || continue
+        probe_output="${probe_output//$'\r'/}"
+        probe_output="${probe_output//[[:space:]]/}"
+        major="$probe_output"
+        [[ -z "$major" ]] && continue
+        [[ ! "$major" =~ ^[0-9]+$ ]] && continue
+        if (( major >= min_major )); then
+            printf '%s\n' "$path"
+            return 0
+        fi
+    done
+
+    return 1
+}

package/src/apothem/hooks/lib/find-python.ps1

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+
+# Purpose: Locate a real CPython >= 3.10 on PATH for the PowerShell
+# bootstrap stub, rejecting Microsoft Store launcher shims (zero-byte
+# stubs at AppData\Local\Microsoft\WindowsApps).
+# Contract: dot-source then call Find-RealPython; returns the absolute
+# path to a working interpreter, or $null when none found. Does not
+# throw on probe failures — silently skips bad candidates.
+# Sibling files in hooks/lib/: find-python.sh (POSIX counterpart),
+# bootstrap.ps1 (the script that dot-sources this locator),
+# bootstrap.sh (POSIX counterpart of the bootstrap stub).
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Find-RealPython {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [int]$MinMajor = 3,
+        [int]$MinMinor = 10
+    )
+
+    $candidates = @('python', 'python3', 'python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10')
+    $probe = 'import sys; sys.stdout.write(str(sys.version_info.major) + chr(32) + str(sys.version_info.minor))'
+
+    foreach ($name in $candidates) {
+        # PATH resolution: Get-Command searches only the non-empty directories
+        # in $env:PATH and never the current directory implicitly, so an empty
+        # PATH segment (a doubled ';;' or a leading/trailing separator) yields
+        # no candidate here. The cwd-from-empty-segment footgun closed in the
+        # sibling find-python.sh / python_resolver.py PATH walks does not arise
+        # in this stub. Do NOT replace Get-Command with a manual PATH walk that
+        # maps empty segments to cwd: an explicit '.' entry on PATH is honored,
+        # an empty one is not. (Verified against Windows PowerShell.)
+        $cmds = @(Get-Command $name -All -ErrorAction SilentlyContinue)
+        foreach ($cmd in $cmds) {
+            $src = $cmd.Source
+            if (-not $src) { continue }
+            # Literal substring match (parity with the POSIX `${v#*WindowsApps}`
+            # prefix-strip in find-python.sh); -like avoids regex semantics.
+            if ($src -like '*WindowsApps*') { continue }
+            $info = Get-Item -LiteralPath $src -ErrorAction SilentlyContinue
+            if (-not $info) { continue }
+            if ($info.Length -lt 1024) { continue }
+
+            $output = $null
+            try { $output = & $src -c $probe 2>$null } catch { continue }
+            if ($LASTEXITCODE -ne 0) { continue }
+            if (-not $output) { continue }
+            $trimmed = ($output -join '').Trim()
+            $parts = $trimmed.Split(' ')
+            if ($parts.Count -lt 2) { continue }
+            $maj = 0; $min = 0
+            if (-not [int]::TryParse($parts[0], [ref]$maj)) { continue }
+            if (-not [int]::TryParse($parts[1], [ref]$min)) { continue }
+            if ($maj -gt $MinMajor -or ($maj -eq $MinMajor -and $min -ge $MinMinor)) {
+                return $src
+            }
+        }
+    }
+    return $null
+}

package/src/apothem/hooks/lib/find-python.sh

@@ -0,0 +1,97 @@
+#!/bin/sh
+# SPDX-License-Identifier: MIT
+
+# Purpose: Locate a real CPython >= 3.10 on PATH for the POSIX bootstrap
+# stub, rejecting Microsoft Store launcher shims (zero-byte stubs at
+# AppData/Local/Microsoft/WindowsApps under WSL/Git-Bash mounts).
+# Contract: dot-source then call find_real_python; prints the absolute
+# path on success and returns 0; returns 1 when no candidate satisfies
+# the version floor. Does not throw on probe failures — silently skips
+# bad candidates so the dispatcher's diagnostic envelope path runs.
+# POSIX sh only (no bashisms): runs under dash/ash as well as bash, so a
+# `curl … | sh` installer that dot-sources this locator stays portable.
+# Sibling files in hooks/lib/: find-python.ps1 (PowerShell counterpart),
+# bootstrap.sh (the script that dot-sources this locator), bootstrap.ps1
+# (PowerShell counterpart of the bootstrap stub).
+#
+# Usage (sourced):  . lib/find-python.sh && py="$(find_real_python)" || exit 1
+# Exit codes: prints absolute path on success; exits 1 if none found.
+
+# Walk every PATH entry and print each executable file matching $1, in PATH
+# order — the POSIX stand-in for bash's `type -ap`, which lists all matches
+# rather than only the first (so a WindowsApps shim earlier on PATH does not
+# mask a real interpreter found later).
+_find_python_path_candidates() {
+    _fpc_name="$1"
+    _fpc_saved_ifs="$IFS"
+    IFS=:
+    for _fpc_dir in $PATH; do
+        IFS="$_fpc_saved_ifs"
+        # Skip an empty PATH segment (a doubled "::" or a leading/trailing
+        # delimiter) rather than resolving it to the current directory. POSIX
+        # maps an empty segment to cwd, but this locator's result is
+        # version-probed (executed) and wired into the hook command that runs
+        # on every tool use; discovering an attacker-planted cwd "python" there
+        # is the footgun this guard closes. A user who genuinely wants cwd
+        # searched adds an explicit "." entry — non-empty, still honored below.
+        if [ -z "$_fpc_dir" ]; then
+            IFS=:
+            continue
+        fi
+        _fpc_full="${_fpc_dir}/${_fpc_name}"
+        if [ -f "$_fpc_full" ] && [ -x "$_fpc_full" ]; then
+            printf '%s\n' "$_fpc_full"
+        fi
+        IFS=:
+    done
+    IFS="$_fpc_saved_ifs"
+}
+
+find_real_python() {
+    _frp_min_major="${1:-3}"
+    _frp_min_minor="${2:-10}"
+    _frp_candidates="python python3 python3.14 python3.13 python3.12 python3.11 python3.10"
+
+    for _frp_name in $_frp_candidates; do
+        # Probe every match for this name once. The inner loop runs in a
+        # command-substitution subshell, so `break` (not `return`) emits the
+        # first qualifying interpreter; the parent reads it back.
+        _frp_winner=$(
+            _find_python_path_candidates "$_frp_name" | while IFS= read -r _frp_path; do
+                [ -z "$_frp_path" ] && continue
+                # Skip Microsoft Store launcher shims. A POSIX prefix-strip
+                # test, NOT `case`: this loop body runs inside `_frp_winner=$( … )`,
+                # and macOS `/bin/sh` (bash 3.2) cannot parse a `case … ;; esac`
+                # inside a command substitution. `dash -n` accepts it, which is
+                # why the POSIX-parse gate missed it; `sh install.sh` on macOS
+                # then fails at parse time. `${v#*WindowsApps}` differs from `$v`
+                # exactly when `$v` contains "WindowsApps".
+                if [ "${_frp_path#*WindowsApps}" != "$_frp_path" ]; then
+                    continue
+                fi
+                [ -x "$_frp_path" ] || continue
+                _frp_size=$(wc -c < "$_frp_path" 2>/dev/null || echo 0)
+                [ "$_frp_size" -lt 1024 ] && continue
+                _frp_probe=$("$_frp_path" -c 'import sys; sys.stdout.write(str(sys.version_info.major) + " " + str(sys.version_info.minor))' 2>/dev/null) || continue
+                _frp_probe=$(printf '%s' "$_frp_probe" | tr -d '\r')
+                _frp_major=$(printf '%s\n' "$_frp_probe" | cut -d' ' -f1)
+                _frp_minor=$(printf '%s\n' "$_frp_probe" | cut -d' ' -f2)
+                { [ -z "$_frp_major" ] || [ -z "$_frp_minor" ]; } && continue
+                # Reject empty or non-numeric version components without `case`
+                # (same bash-3.2 command-substitution limitation as above): strip
+                # every ASCII digit and require a non-empty value with nothing left.
+                { [ -z "$_frp_major" ] || [ -n "$(printf '%s' "$_frp_major" | tr -d '0123456789')" ]; } && continue
+                { [ -z "$_frp_minor" ] || [ -n "$(printf '%s' "$_frp_minor" | tr -d '0123456789')" ]; } && continue
+                if [ "$_frp_major" -gt "$_frp_min_major" ] || { [ "$_frp_major" -eq "$_frp_min_major" ] && [ "$_frp_minor" -ge "$_frp_min_minor" ]; }; then
+                    printf '%s\n' "$_frp_path"
+                    break
+                fi
+            done
+        )
+        if [ -n "$_frp_winner" ]; then
+            printf '%s\n' "$_frp_winner"
+            return 0
+        fi
+    done
+    return 1
+}

package/src/apothem/hooks/lib/log.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared logger factory for the apothem hook scripts.
+
+Purpose: a single source of truth for how hook modules acquire a
+``logging.Logger``. Both ``hooks/emit_hook_context.py`` and
+``hooks/session_start_bootstrap.py`` previously instantiated their
+loggers via ``logging.getLogger(<hard-coded-name>)``, which drifted
+over time and made downstream handler configuration inconsistent.
+
+Contract: ``get_logger(name)`` returns a ``logging.Logger`` whose
+name is the caller's ``__name__``. The hook runtime configures
+handlers itself; this factory does not attach handlers, set levels,
+or alter the root logger — it only provides a uniform acquisition
+point so future structured-logging changes land in one file.
+
+Sibling files in hooks/lib/: events.py (event-name single source of
+truth), resolve_root.py (project-root resolver), bootstrap.sh +
+bootstrap.ps1 (the entry stubs that exec the Python hook scripts
+this logger serves), find-python.sh + find-python.ps1 (interpreter
+locators).
+
+Note on module name: this file is `log.py` rather than `logging.py`
+because ``hooks/lib/`` is inserted at ``sys.path[0]`` by the
+dispatcher; a sibling named ``logging.py`` would shadow the stdlib
+``logging`` module on first ``import logging`` and break every
+caller.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger named ``name``, typically the caller's ``__name__``.
+
+    The factory deliberately does no handler/level/formatter setup —
+    that is the hook runtime's responsibility. Centralizing the
+    acquisition point keeps the call sites uniform and makes future
+    structured-logging migrations a single-file change.
+    """
+    return logging.getLogger(name)

package/src/apothem/hooks/lib/resolve_root.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: MIT
+
+"""Project root resolution for the apothem ecosystem.
+
+Resolves the absolute path of the apothem project root using a
+four-level strategy: explicit environment variable, script-relative
+ascent, current-working-directory walk, and a `$HOME/.claude` fallback
+(the Claude Code harness's config root — one of the supported harnesses).
+
+Two marker strategies are supported:
+
+* ``Mode.HOOKS`` — the root must contain both ``hooks/`` and ``rules/``
+  subdirectories. Used by runtime hook scripts that need a populated
+  ecosystem.
+* ``Mode.MARKER`` — the root must contain a ``CLAUDE.md`` file. Used by
+  scripts that may run before the full layout exists (ecosystem
+  scaffolding, bootstrap utilities).
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Final
+
+#: The Apothem-owned shared working-directory name. The sole canonical
+#: project-local plans home is ``<project-root>/.apothem/plans``. The legacy
+#: ``<project-root>/.plans`` layout is no longer canonical; operators upgrade an
+#: existing ``.plans`` tree via ``apothem migrate-workspace``.
+_APOTHEM_SUBTREE: Final[str] = ".apothem"
+_PLANS_CHILD: Final[str] = "plans"
+
+__all__ = [
+    "Mode",
+    "ResolutionStrategy",
+    "canonical_plans_dir",
+    "default_content_root",
+    "is_canonical_project_plans_dir",
+    "resolve_project_root",
+]
+
+
+class Mode(str, Enum):
+    """Marker-set selector for root detection."""
+
+    HOOKS = "hooks"
+    MARKER = "marker"
+
+
+_HOOKS_MARKERS: Final[tuple[str, ...]] = ("hooks", "rules")
+_FILE_MARKERS: Final[tuple[str, ...]] = ("CLAUDE.md",)
+
+
+@dataclass(frozen=True)
+class ResolutionStrategy:
+    """Concrete resolution configuration derived from a `Mode`.
+
+    Attributes:
+        directory_markers: Subdirectories whose presence identifies a root.
+        file_markers: Files whose presence identifies a root.
+    """
+
+    directory_markers: tuple[str, ...]
+    file_markers: tuple[str, ...]
+
+    @classmethod
+    def for_mode(cls, mode: Mode) -> ResolutionStrategy:
+        """Return the strategy corresponding to `mode`."""
+        if mode is Mode.HOOKS:
+            return cls(directory_markers=_HOOKS_MARKERS, file_markers=())
+        return cls(directory_markers=(), file_markers=_FILE_MARKERS)
+
+    def matches(self, candidate: Path) -> bool:
+        """Return True when `candidate` contains all required markers."""
+        if not candidate.is_dir():
+            return False
+        if not all((candidate / name).is_dir() for name in self.directory_markers):
+            return False
+        return all((candidate / name).is_file() for name in self.file_markers)
+
+
+def _iter_ancestors(start: Path) -> Iterable[Path]:
+    """Yield `start` and each parent up to the filesystem root."""
+    current = start.resolve()
+    yield current
+    yield from current.parents
+
+
+def _from_env(strategy: ResolutionStrategy, env: Mapping[str, str]) -> Path | None:
+    """Resolve via ``$CLAUDE_PROJECT_DIR`` or ``$LLM_PROJECT_DIR``, or ``None``.
+
+    The primary variable ``CLAUDE_PROJECT_DIR`` is consulted first; if it is
+    unset or does not satisfy the strategy, the vendor-neutral alias
+    ``LLM_PROJECT_DIR`` is tried as secondary. A successor harness that only
+    sets ``LLM_PROJECT_DIR`` resolves without falling through to later steps.
+    """
+    for var_name in ("CLAUDE_PROJECT_DIR", "LLM_PROJECT_DIR"):
+        env_dir = env.get(var_name)
+        if not env_dir:
+            continue
+        candidate = Path(env_dir)
+        if strategy.matches(candidate):
+            return candidate.resolve()
+    return None
+
+
+def _from_script(
+    strategy: ResolutionStrategy, script_path: Path | str | None
+) -> Path | None:
+    """Resolve via the parent of a script located in ``hooks/``."""
+    if script_path is None:
+        return None
+    script = Path(script_path).resolve()
+    if script.parent.name != "hooks":
+        return None
+    grand = script.parent.parent
+    return grand if strategy.matches(grand) else None
+
+
+def _from_walk(strategy: ResolutionStrategy, cwd: Path | str | None) -> Path | None:
+    """Resolve by walking ancestors of `cwd`."""
+    start = Path(cwd) if cwd is not None else Path.cwd()
+    for ancestor in _iter_ancestors(start):
+        if strategy.matches(ancestor):
+            return ancestor
+    return None
+
+
+def _from_home(strategy: ResolutionStrategy, home: Path | str | None) -> Path | None:
+    """Resolve via ``$HOME/.claude``."""
+    home_dir = Path(home) if home is not None else Path.home()
+    fallback = home_dir / ".claude"
+    return fallback.resolve() if strategy.matches(fallback) else None
+
+
+def resolve_project_root(
+    mode: Mode = Mode.HOOKS,
+    *,
+    script_path: Path | str | None = None,
+    cwd: Path | str | None = None,
+    environ: Mapping[str, str] | None = None,
+    home: Path | str | None = None,
+) -> Path | None:
+    """Locate the apothem project root.
+
+    The resolution order is:
+
+    1. ``$CLAUDE_PROJECT_DIR`` if it satisfies the strategy.
+    2. ``$LLM_PROJECT_DIR`` (vendor-neutral alias) if it satisfies the
+       strategy.
+    3. ``script_path``'s grandparent, when `script_path`'s immediate
+       parent is named ``hooks``.
+    4. Walk from `cwd` upward; return the first ancestor that
+       satisfies the strategy.
+    5. ``$HOME/.claude`` if it satisfies the strategy.
+
+    Returns ``None`` when no candidate satisfies the chosen strategy.
+
+    Args:
+        mode: Which marker set to require.
+        script_path: Absolute path of the calling script. When provided
+            and located in a ``hooks/`` directory, the parent is tested.
+        cwd: Starting directory for the upward walk. Defaults to
+            ``Path.cwd()``.
+        environ: Environment mapping. Defaults to ``os.environ``.
+        home: Home directory. Defaults to ``Path.home()``.
+
+    Returns:
+        Absolute `Path` of the resolved root, or `None` if unresolved.
+    """
+    strategy = ResolutionStrategy.for_mode(mode)
+    env: Mapping[str, str] = os.environ if environ is None else environ
+    resolvers: tuple[Callable[[], Path | None], ...] = (
+        lambda: _from_env(strategy, env),
+        lambda: _from_script(strategy, script_path),
+        lambda: _from_walk(strategy, cwd),
+        lambda: _from_home(strategy, home),
+    )
+    for resolver in resolvers:
+        result = resolver()
+        if result is not None:
+            return result
+    return None
+
+
+def default_content_root(root: Path) -> Path:
+    """Resolve the harness content root for a apothem project root.
+
+    In the apothem *source* repository the harness convention surface
+    (``hooks/``, ``rules/``, ``commands/``, ...) lives under the
+    ``src/apothem/`` package directory; in an installed harness (for
+    example ``~/.claude/``) it sits flat at the project root. This
+    helper returns ``root / "src" / "apothem"`` when that path carries
+    the package marker (a ``hooks/`` subdirectory), otherwise ``root``
+    unchanged — so dev validators run bare from either layout without an
+    explicit ``--content-root`` flag.
+
+    Args:
+        root: The resolved apothem project root.
+
+    Returns:
+        The directory under which the harness convention surface lives.
+    """
+    src_layout = root / "src" / "apothem"
+    if (src_layout / "hooks").is_dir():
+        return src_layout
+    return root
+
+
+def canonical_plans_dir(project_root: Path) -> Path:
+    """Return the canonical project-local plans directory for a root.
+
+    Apothem keeps its working state in a single shared
+    ``<project-root>/.apothem`` directory; the sole canonical plans tree is
+    ``<project-root>/.apothem/plans``. The legacy ``<project-root>/.plans``
+    layout is no longer canonical — operators upgrade an existing ``.plans``
+    tree via ``apothem migrate-workspace``.
+
+    The project-root resolution itself (git-ascent + CWD walk via
+    :func:`resolve_project_root`) is unchanged; this helper only names the
+    canonical plans location beneath an already-resolved root. The path is
+    computed purely; no filesystem access occurs and no directory is created.
+
+    Args:
+        project_root: The resolved project root.
+
+    Returns:
+        ``<project-root>/.apothem/plans`` — the sole canonical plans location.
+    """
+    return project_root / _APOTHEM_SUBTREE / _PLANS_CHILD
+
+
+def is_canonical_project_plans_dir(candidate: Path, project_root: Path) -> bool:
+    """Return True iff *candidate* is the canonical project-local plans directory.
+
+    The sole canonical project-local plans directory is
+    ``<project-root>/.apothem/plans``. Any other plans-shaped directory — a
+    legacy ``<project-root>/.plans``, a stray ``.plans`` nested elsewhere, or an
+    ``.apothem/plans`` under a different root such as a harness-config root or
+    the user home — is NOT canonical and remains subject to the global-plans
+    deny.
+
+    The comparison is by resolved path so a relative *candidate* and an absolute
+    *project_root* compare correctly.
+
+    Args:
+        candidate: The plans-directory path under test.
+        project_root: The resolved project root the candidate must sit beneath.
+
+    Returns:
+        True when *candidate* resolves to the canonical project-local plans
+        directory, False otherwise.
+    """
+    try:
+        resolved_candidate = candidate.resolve()
+    except (OSError, RuntimeError):
+        return False
+    try:
+        return resolved_candidate == canonical_plans_dir(project_root).resolve()
+    except (OSError, RuntimeError):
+        return False

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

@@ -0,0 +1,14 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Post-compaction Blind Bootstrap (CM-24 §6.2). Restore working state from durable files; conversation context is now compressed.
+
+Read sequence — execute IN ORDER:
+
+1. MEMORY.md (project tier, then global) and every topic file referenced in the project index.
+2. With an active plan suite: PROGRESS.md Resumption Contract — phase/task status, next action, convention anchors, blockers, watch items, critical-files manifest.
+3. Each file in the critical-files manifest, in the listed order. Skip any path already covered by a Resumption Contract snapshot to avoid redundant context spend.
+4. The active phase file (`phases/NN-topic/PHASE.md`) — scope, tasks, inputs, outputs, verification criteria.
+5. Adopt the convention anchors verbatim from the Resumption Contract; do NOT re-derive them from the preamble.
+6. Verify alignment. The user's most recent request must be fully addressable from the loaded state. If it references files, decisions, or context NOT in the loaded set, read those files BEFORE proceeding. If the request contradicts loaded state, surface the contradiction to the user — never silently override durable state.
+
+No active suite: step 1, then re-read any files referenced in the user's most recent request, then step 6.