@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+CM-7 codebase isolation + frontmatter compliance.
+
+Scope. Triggered on every Write. Skip the CM-7 scan when `target` is inside the Apothem source repo or the active harness's config root (for the Claude Code harness, `~/.claude/`) — those locations are the ecosystem meta-config and are allowed to reference plan terms. Apply the scan otherwise.
+
+CM-7 scan. Reject content containing any term in the canonical forbidden-terms block at `CLAUDE.md` §CM-7. On hit: STOP. Rewrite the offending passage in natural domain language and re-issue the Write — do not silently strip the term, since the surrounding sentence binds to the term and breaks when the term is excised without restructuring.
+
+Frontmatter compliance. `rules/*.md` requires a `description` field. `skills/*/SKILL.md`, `agents/*.md`, and `commands/*.md` require both `name` and `description` fields. Each field must be a non-empty string. On missing or empty fields: STOP, add them, re-issue.
+
+Always-on rule body budget. When the Write target matches `rules/*.md` and the file's frontmatter declares `alwaysApply: true` AND `pathFilter:` empty, the substantive-token count of the body 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 the per-file count plus an `over_budget` flag. On `over_budget: true`: STOP, decompose along a path-filtered seam (companion sub-rule pattern; precedents at `rules/context-management.md` ↔ `rules/context-management-scratch.md`), trim the parent body, re-issue.
+
+Scratch-convention path check.
+
+Trigger. Every Write.
+
+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 a Write 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 Write at the corrected target per the rule's recovery clause.
+
+Non-matching paths (anything that is not a scratch or prose path): 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 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 violation: when the CM-7 scan, a frontmatter gap, an over-budget body, or a scratch-path REJECT class is hit, the directive is to STOP and re-issue the Write 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/sessionstart.md

@@ -0,0 +1,15 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Session-start conformity posture.
+
+**Working-trace surface.** The most-recent plan suite's PROGRESS.md Resumption Contract is the authoritative pickup point. Read its Watch Items and Blockers sections before any substantive action. The Critical Files Manifest is the deterministic next-session bootstrap order — read those files first, in that order.
+
+**Unresolved-inquiry enumeration.** Before emitting any artifact of meaningful scope, walk the active suite for unresolved `<USER-CONFIRM:…>` placeholders and any `unresolved-inquiries:` arrays in prior phase reports' fifteen-bar gate attestation blocks. Surface every one — do not silently re-invent the answer. Required-category placeholders (identity / scope / security / public-surface naming) block emission until resolved through the canonical inquiry channel; optional-category placeholders fall back to the recommended option per the option-annotation discipline and record the fallback as a finding.
+
+**Host-discovery freshness.** Convention discovery (formatter, linter, test framework, CI provider, branch strategy, commit-message convention) runs on-demand per the host-discovery rule, not at session start. The session-start posture only declares that discovery is the path; the actual walk fires when the first artifact-emission decision needs it.
+
+**Pre-emission gate awareness.** Every host-project artifact emission of meaningful scope passes through the fifteen-bar pre-emission gate before it leaves the agent's hands. The gate's mechanical bars (M2, M5, M7, M8, M10, M13, M15) are operationalized as PreToolUse hooks at `apothem/conformity/*_grep.py` orchestrated by `apothem/conformity/gate.py`; the reasoned bars (M1, M3, M6, M9, M11, M12, M14) are evaluated by the operating agent and recorded in the attestation block.
+
+**Trivial-vs-non-trivial threshold.** The threshold separating trivial from non-trivial work — non-trivial work triggers the agile sprint apparatus, the per-sub-phase reporting, and the full pre-emission gate — is the line-count + scope hybrid: a change is trivial when it is a single-file edit of ≤ 5 lines AND introduces no public-API surface change AND no behavioral shift. Anything else is non-trivial. Project-scope CLAUDE.md may override per host discipline.
+
+**Fail-disposition.** Fail-open at every layer. The Python dispatcher at `hooks/dispatch.py` converts any exception in `session_start_bootstrap.main()` to a structured failure envelope on stdout (per the dispatcher's `_emit_failure` contract); the session itself proceeds. A bootstrap-script error degrades the operator's session-start summary but never blocks the session — there is no recovery path that would benefit from blocking. If the operator notices a missing posture block, the recovery is to re-invoke the bootstrap manually or inspect `hooks/session_start_bootstrap.py` for the diagnostic stack trace.

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

@@ -0,0 +1,27 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+Session-end protocol (CM-14 + CM-24 §2.5 + CM-26 + CM-22 §2/§4).
+
+**Phase A — Mandatory externalization** (CM-14, CM-24 §2.5)
+
+1. With an active plan suite, mid-phase: write current task state to PROGRESS.md Resumption Contract — phase id, task id, status (in_progress|partial), next action as a precise imperative.
+2. Move every session decision to PLAN-NOTES.md § Resolved Decisions; remove from in-conversation working memory.
+3. Update Phase Output Registry — every declared output that landed on disk gets verified status with its actual path; missing outputs get blocked status with the reason.
+4. Update convention anchors in the Resumption Contract if any evolved this session.
+5. Write the critical-files manifest — ordered list of files the next session must read first to resume.
+
+**Phase B — Evaluation** (skip only on immediate-exit signal)
+
+1. Memory evaluation per CM-26 (auto-memory rule §5): scan session for stable patterns / preferences / architectural decisions / debugging insights; write or update memory entries; prune any entry this session contradicted.
+2. Artifact evolution per CM-22 §2 + §4: detect patterns that recurred 2+ times this session and need a new or updated rule, skill, command, hook, or agent.
+3. Convention sweep per CM-22 §3: verify cross-references still resolve, no orphan artifacts were created, naming remains consistent.
+
+No active suite: skip Phase A entirely; execute Phase B against working notes accumulated this session.
+
+**No re-narration (no repeated messages).** Phases A–C externalize state to durable files; they are file-side, not conversational output. The session's single conversational close is the three-element close per `rules/session-closure.md` §3 — do not re-narrate these phases as additional end-of-session messages, and do not re-emit a close already emitted this session. On a Stop-condition / goal / loop re-engagement, advance the work and report only the delta; never re-print the prior close.
+
+**Phase C — Conformity trace flush** (run alongside Phase A; non-negotiable when an active suite carries unresolved inquiries)
+
+1. Working-trace emission. Verify the active suite's PROGRESS.md Resumption Contract was updated this session — if any session decision, blocker, or watch item is still in conversation memory only, write it to durable file before the session ends.
+2. Unresolved-inquiry flush. Walk the active suite for concrete-id `<USER-CONFIRM:…>` placeholders and any `unresolved-inquiries:` arrays in this session's emitted phase reports' fifteen-bar gate attestation blocks. Surface every unresolved inquiry in the Resumption Contract Watch Items section so the next session inherits the inventory and does not silently re-invent.
+3. Mandate-axis findings. If this session emitted any findings against the M-N mandate axs (host-discovery gaps, code-craft drift, supply-chain regressions, production-readiness gaps), summarize them in the Resumption Contract so the next session inherits the audit signal alongside its task pointer.

package/src/apothem/hooks/proactive_compaction_tracker.py

@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: MIT
+
+"""PostToolUse handler that mechanically operationalizes the CM-19 proactive-
+compaction triggers.
+
+Why this handler exists. The compaction-trigger catalog
+(``rules/context-management-protocol.md`` §2 — ~18 tool calls since the last
+externalization, a large cumulative emission, a heavy-read run) was
+agent-discipline only: nothing *measured* per-session activity, so the
+"compact before context fills" advisory fired solely on the agent's own
+vigilance. The harness ``PreCompact`` event fires only once compaction has
+already been initiated — too late to be proactive. This module is the
+dispatch-routed ``PostToolUse`` handler that closes that gap: it keys off the
+``session_id`` in the hook stdin payload, maintains a tiny per-session counter
+file, and once a threshold from the §2 catalog is crossed it surfaces a concise
+proactive-compaction advisory (externalize state + compact now) and then resets
+the counter so the advisory does not fire on every subsequent tool call.
+
+What it guarantees.
+
+* **Advisory-only.** It NEVER blocks. A PostToolUse hook cannot block the tool
+  call that already ran; the envelope only ever carries a ``systemMessage`` plus
+  ``additionalContext`` nudge, or is empty.
+* **Fast.** A single small-file read + write (a JSON counter object keyed by
+  session id). No project scan, no engine import on the hot path.
+* **Fail-open.** Any exception -> emit nothing (an empty envelope), never
+  disrupt the session. A tracker bug must never cost the operator a tool call.
+* **Low-noise / anti-spam.** It emits at most once per threshold window: when a
+  threshold crosses, the per-session counters reset (back-off), so the next
+  advisory is at least another full window away.
+
+Configuration. Two thresholds, each overridable by an environment variable
+(falling back to a default grounded in the §2 catalog):
+
+* ``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 "large cumulative emission" / heavy-read triggers (~20 KB ≈ the
+  500-line emission band the catalog names).
+
+A non-positive or unparseable override falls back to the default, so a typo in
+the environment can never disable or zero-out the tracker silently.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+#: Environment overrides for the two thresholds. Each falls back to its default
+#: when unset, non-numeric, or non-positive.
+TOOL_THRESHOLD_ENV: Final[str] = "APOTHEM_PROACTIVE_COMPACTION_TOOL_THRESHOLD"
+OUTPUT_THRESHOLD_ENV: Final[str] = "APOTHEM_PROACTIVE_COMPACTION_OUTPUT_THRESHOLD"
+
+#: Default thresholds, grounded in the §2 compaction-trigger catalog.
+#: ``18`` mirrors the "~18 tool calls" trigger; ``20000`` bytes is a mechanical
+#: proxy for the "500-line emission" / heavy-read band (~20 KB).
+DEFAULT_TOOL_THRESHOLD: Final[int] = 18
+DEFAULT_OUTPUT_THRESHOLD: Final[int] = 20_000
+
+#: Per-session state lives under a dedicated subdirectory of the OS temp dir —
+#: never inside the repository's tracked tree (the hook runs in the operator's
+#: harness, not the checkout). The subdirectory keeps the counter files grouped
+#: and easy to purge.
+_STATE_DIRNAME: Final[str] = "apothem-proactive-compaction"
+
+#: Sanitized fallback when a session id is absent or unusable. A shared key is
+#: acceptable here: the tracker is advisory, and a missing id only means the
+#: counters are not partitioned per session for that (rare) case.
+_DEFAULT_SESSION_KEY: Final[str] = "_default"
+
+
+@dataclass(frozen=True)
+class Thresholds:
+    """Resolved tool-call and output-byte thresholds for one invocation."""
+
+    tool_calls: int
+    output_bytes: int
+
+
+@dataclass
+class SessionState:
+    """Mutable per-session counters since the last advisory.
+
+    ``tool_calls`` counts PostToolUse firings; ``output_bytes`` accumulates the
+    estimated size of each tool's output. Both reset to zero when an advisory
+    fires (the anti-spam back-off).
+    """
+
+    tool_calls: int = 0
+    output_bytes: int = 0
+
+    def to_dict(self) -> dict[str, int]:
+        """Serialize to the on-disk JSON shape."""
+        return {"tool_calls": self.tool_calls, "output_bytes": self.output_bytes}
+
+    @classmethod
+    def from_obj(cls, obj: object) -> SessionState:
+        """Reconstruct from a parsed JSON object, tolerating shape drift.
+
+        A garbage or partial object yields zeroed counters (fail-open): a
+        corrupt state file degrades to "start counting again", never a crash.
+        """
+        if not isinstance(obj, dict):
+            return cls()
+        tool_calls = obj.get("tool_calls")
+        output_bytes = obj.get("output_bytes")
+        return cls(
+            tool_calls=tool_calls
+            if isinstance(tool_calls, int) and tool_calls >= 0
+            else 0,
+            output_bytes=(
+                output_bytes
+                if isinstance(output_bytes, int) and output_bytes >= 0
+                else 0
+            ),
+        )
+
+
+def _positive_int_env(name: str, default: int) -> int:
+    """Return a positive integer from environment variable *name*, else *default*.
+
+    A non-positive or unparseable value falls back to *default* so a typo can
+    never silently disable or zero-out the threshold.
+    """
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+def resolve_thresholds() -> Thresholds:
+    """Resolve both thresholds from the environment with grounded defaults."""
+    return Thresholds(
+        tool_calls=_positive_int_env(TOOL_THRESHOLD_ENV, DEFAULT_TOOL_THRESHOLD),
+        output_bytes=_positive_int_env(OUTPUT_THRESHOLD_ENV, DEFAULT_OUTPUT_THRESHOLD),
+    )
+
+
+def _sanitize_session_key(session_id: object) -> str:
+    """Map an arbitrary session id to a safe, bounded filename stem.
+
+    Keeps only ``[A-Za-z0-9._-]`` (path-traversal-safe), bounds the length, and
+    falls back to a shared default key when the id is absent, non-string, or
+    sanitizes to empty. This guarantees the state path stays inside the state
+    directory regardless of payload contents.
+    """
+    if not isinstance(session_id, str) or not session_id.strip():
+        return _DEFAULT_SESSION_KEY
+    allowed = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-"
+    cleaned = "".join(ch for ch in session_id if ch in allowed)
+    cleaned = cleaned.strip("._-")
+    if not cleaned:
+        return _DEFAULT_SESSION_KEY
+    return cleaned[:120]
+
+
+def _state_dir() -> Path:
+    """Return the per-session state directory under the OS temp dir."""
+    return Path(tempfile.gettempdir()) / _STATE_DIRNAME
+
+
+def state_path_for(session_id: object) -> Path:
+    """Return the counter-file path for *session_id* (never inside the repo)."""
+    return _state_dir() / f"{_sanitize_session_key(session_id)}.json"
+
+
+def _read_state(path: Path) -> SessionState:
+    """Load per-session counters from *path*, fail-open to zero on any error."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return SessionState()
+    try:
+        return SessionState.from_obj(json.loads(raw))
+    except (json.JSONDecodeError, ValueError):
+        return SessionState()
+
+
+def _write_state(path: Path, state: SessionState) -> None:
+    """Persist per-session counters to *path*, creating the dir as needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(state.to_dict(), separators=(",", ":")) + "\n",
+        encoding="utf-8",
+    )
+
+
+def estimate_output_bytes(payload: dict[str, object] | None) -> int:
+    """Estimate the byte size of a PostToolUse tool result from the payload.
+
+    The harness PostToolUse stdin carries ``tool_response`` (the tool's output).
+    Its shape varies by tool, so the estimate serializes whatever is present to
+    a JSON string and measures its UTF-8 length — a stable, tool-agnostic proxy
+    for "how much did this tool emit". An absent or unserializable response
+    contributes zero (fail-open).
+    """
+    if not payload:
+        return 0
+    response = payload.get("tool_response")
+    if response is None:
+        return 0
+    try:
+        if isinstance(response, str):
+            text = response
+        else:
+            text = json.dumps(response, separators=(",", ":"), default=str)
+    except (TypeError, ValueError):
+        return 0
+    return len(text.encode("utf-8"))
+
+
+def _advisory_text() -> str:
+    """Return the proactive-compaction advisory body."""
+    return (
+        "Apothem proactive-compaction advisory (CM-19): activity since the last "
+        "checkpoint has crossed a context-rot threshold. Externalize in-conversation "
+        "state to durable files now, then compact:\n"
+        "  1. Update the PROGRESS.md Resumption Contract (phase, task, next action, "
+        "convention anchors, critical-files manifest); record session decisions in "
+        "PLAN-NOTES.md. With no active suite, externalize to a scratch file under the "
+        "active harness's config root.\n"
+        "  2. Compact (or start a fresh session) so context stays lean per the "
+        "blind-execution invariant — every turn must remain executable from durable "
+        "files alone.\n"
+        "This is advisory; it does not block. The counter has reset, so the next "
+        "advisory is at least another full window away."
+    )
+
+
+def build_envelope(state: SessionState, thresholds: Thresholds) -> dict[str, object]:
+    """Map current counters to a hook-output envelope.
+
+    Returns the advisory envelope when either threshold is crossed (the caller
+    has already reset the counters on the crossing path), or an empty envelope
+    when below both thresholds (the silent, low-noise default).
+    """
+    crossed = (
+        state.tool_calls >= thresholds.tool_calls
+        or state.output_bytes >= thresholds.output_bytes
+    )
+    if not crossed:
+        return {}
+    text = _advisory_text()
+    return {
+        "systemMessage": text,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": text,
+        },
+    }
+
+
+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 evaluate(payload: dict[str, object] | None) -> dict[str, object]:
+    """Increment the per-session counters and return the advisory envelope.
+
+    Pre-condition: *payload* is the harness PostToolUse stdin object (or
+    ``None``). Post-condition: the per-session counter file reflects this tool
+    call; when a threshold crosses, the counters are reset to zero and the
+    advisory envelope is returned; otherwise an empty envelope is returned and
+    the counters carry forward.
+    """
+    session_id = payload.get("session_id") if isinstance(payload, dict) else None
+    path = state_path_for(session_id)
+    thresholds = resolve_thresholds()
+
+    state = _read_state(path)
+    state.tool_calls += 1
+    state.output_bytes += estimate_output_bytes(payload)
+
+    envelope = build_envelope(state, thresholds)
+    if envelope:
+        # Threshold crossed: reset the window so the advisory does not fire on
+        # the next tool call (anti-spam back-off).
+        _write_state(path, SessionState())
+    else:
+        _write_state(path, state)
+    return envelope
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point. Tracks activity and emits one envelope; never raises.
+
+    The ``argv`` parameter is accepted for signature parity with the sibling
+    dispatch handlers (the dispatcher calls ``main([])``); this handler reads no
+    flags, so it is intentionally unused.
+
+    FAIL-OPEN: any unexpected exception is swallowed and an empty (no-op)
+    envelope is written, so a tracker bug never disrupts the session.
+    """
+    try:
+        payload = _read_payload()
+        envelope = evaluate(payload)
+        sys.stdout.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+    except Exception:  # noqa: BLE001, RUF100 - fail-open boundary: a tracker error must never disrupt the session; emit an empty 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()