ActiveMemory
diff --git a/‎.claude/skills/_ctx-surface-audit/SKILL.md‎
Lines changed: 21 additions & 8 deletions b/‎.claude/skills/_ctx-surface-audit/SKILL.md‎
Lines changed: 21 additions & 8 deletions
diff --git a/‎.context/CONVENTIONS.md‎
Lines changed: 33 additions & 0 deletions b/‎.context/CONVENTIONS.md‎
Lines changed: 33 additions & 0 deletions
diff --git a/‎.context/DECISIONS.md‎
Lines changed: 45 additions & 0 deletions b/‎.context/DECISIONS.md‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎.context/LEARNINGS.md‎
Lines changed: 33 additions & 0 deletions b/‎.context/LEARNINGS.md‎
Lines changed: 33 additions & 0 deletions
@@ -1,13 +1,26 @@
 ---
-name: ctx-surface-audit
-description: "Out-of-band audit: scan a git ref range for user-facing surfaces that landed without matching SKILL.md, recipe, or docs/cli updates. Run me from a SEPARATE Claude Code session, not the one that wrote the code. Drops a structured report at .context/audit/surface.md for the next interactive session's check-audit hook to relay verbatim."
+name: _ctx-surface-audit
+description: "ctx-repo-internal (note the _ prefix; sibling of _ctx-command-audit / _ctx-audit). Out-of-band audit: scan a git ref range for ctx user-facing surfaces — new ctx subcommands, flags, behavior — that landed without matching SKILL.md, recipe, or docs/cli updates. Run from a SEPARATE Claude Code session, not the one that wrote the code. Drops a report at .context/audit/surface.md for the ctxctl audit-relay hook to relay verbatim."
 allowed-tools: Bash(git:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Read, Glob, Grep, Write
 ---
 
 You are the **surface audit**: an out-of-band reviewer that
 catches user-facing changes landing without matching agent
 SKILL.md, recipe, or `docs/cli` updates.
 
+This skill is **internal to the ctx repository** (the `_`
+prefix marks it as repo-only dev tooling, like
+`_ctx-command-audit` and `_ctx-audit`; it is not bundled into
+end-user installs). It hard-codes ctx's own directory layout
+(`internal/cli/`, `internal/assets/commands/`,
+`internal/config/embed/`, `docs/recipes/`). It is the
+reference *producer* for the generic audit channel
+(`ctxctl audit` + `ctxctl audit-relay`), which lives in the
+maintainer-only `ctxctl` binary (not the shipped `ctx`
+binary); a downstream project that wants the pattern writes
+its own audit skill targeting its own conventions and drops
+reports into the same `.context/audit/` channel.
+
 The whole point of this skill is **fresh-context judgment**.
 The agent that just shipped a feature has tunnel vision; you
 do not. You read the diff cold and ask: "if a user runs `ctx
@@ -165,7 +178,7 @@ Surfaces scanned: <N>
 Coverage checked: SKILL.md, recipes, docs/cli, integrations
 ```
 
-A `clean` report is still useful — `ctx audit list` shows
+A `clean` report is still useful — `ctxctl audit list` shows
 it with a timestamp, so the user knows the audit ran.
 
 ### Digest
@@ -189,7 +202,7 @@ the dismissal.
    frontmatter + body.
 8. Print a one-line summary to the user: report path,
    surface count, finding count, and the next-step hint
-   ("Open a working session — the check-audit hook will
+   ("Open a working session — the audit-relay hook will
    relay the findings on the next prompt.").
 
 ## Important Notes
@@ -213,10 +226,10 @@ the dismissal.
 
 - `specs/audit-channel.md`: design rationale, retention
   policy, naming-collision notes.
-- `internal/cli/audit/`: CLI for `ctx audit list / show /
-  dismiss`.
-- `internal/cli/system/cmd/checkaudit/`: the
-  UserPromptSubmit hook that relays your reports.
+- `internal/ctxctl/cli/audit/`: logic behind `ctxctl audit
+  list / show / dismiss`.
+- `internal/ctxctl/cli/checkaudit/`: the `ctxctl audit-relay`
+  hook logic that relays your reports.
 - `.context/CONVENTIONS.md` →
   *User-Facing Surface Completeness*: the canonical rule
   this audit enforces.
@@ -344,3 +344,36 @@ The Self-check before declaring a feature commit complete is:
 *"If a user runs `ctx help` or asks `/ctx-<area>` to do this
 new thing today, will the help text / skill / recipe match
 what the code does?"* If no, the commit is not complete.
+
+## Maintainer-Only Binaries (Layout and Installation)
+
+Maintainer-only binaries — tooling that must never ship to end
+users — live in `tools/<name>/` as separate Go modules. The
+module path is lexically nested under the main ctx module
+(`github.com/ActiveMemory/ctx/tools/<name>`) so the new module
+CAN import the parent's `internal/` packages (Go's
+internal-import rule is path-lexical, not module-scoped — see
+LEARNINGS.md), reusing `rc`, `desc`, `nudge`, `config`
+primitives without duplication.
+
+Build and install:
+
+- Built to `dist/<name>` via `make <name>` (keeps the repo
+  root clean).
+- PATH-installed to `/usr/local/bin/<name>` via
+  `make install-<name>` / `make reinstall-<name>` —
+  mirroring ctx's `install` / `reinstall` targets so one
+  binary serves every worktree and repo copy.
+- The shipped `ctx` binary's `go.mod` must NOT `require` the
+  maintainer module, giving a **hard module-graph guarantee**
+  that the maintainer code can never leak into `ctx`.
+
+Repo-local hooks calling the maintainer binary live in the
+gitignored `.claude/settings.local.json`, **not** in the
+shipped `internal/assets/claude/hooks/hooks.json`. The hook
+command shape is `cd "$CLAUDE_PROJECT_DIR" && <name>
+<subcommand>` (PATH binary, project-root cwd so `.context/`
+resolves correctly under cwd-anchoring).
+
+`tools/ctxctl/` is the first inhabitant. Future maintainer
+binaries follow the same shape.
@@ -3,6 +3,9 @@
 <!-- INDEX:START -->
 | Date | Decision |
 |----|--------|
+| 2026-05-28 | ctxctl PATH-installed alongside ctx for clean roots and one binary across worktrees |
+| 2026-05-28 | Memory pressure detection uses OS-native signals (macOS pressure level + Linux PSI), not occupancy |
+| 2026-05-27 | ctxctl is a separate Go module at tools/ctxctl (own go.mod), not cmd/ctxctl in the same module |
 | 2026-05-24 | ctxctl lives at cmd/ctxctl in the same Go module, not a separate go.mod |
 | 2026-05-24 | Discipline enforcement belongs on the verbatim-relay channel, run out-of-band |
 | 2026-05-24 | Pad snapshot-on-mutate at the store.WriteEntries choke point |
@@ -154,6 +157,48 @@ For significant decisions:
 
 -->
 
+## [2026-05-28-201000] ctxctl PATH-installed alongside ctx for clean roots and one binary across worktrees
+
+**Status**: Accepted
+
+**Context**: Initial ctxctl design wired the hook to `./ctxctl` at repo root, forcing a per-worktree build, dirtying the root, and contradicting the project's PATH-only convention (`block-non-path-ctx` enforces it for ctx).
+
+**Decision**: ctxctl PATH-installed alongside ctx for clean roots and one binary across worktrees
+
+**Rationale**: Mirror ctx's install pattern: build to `dist/`, install to `/usr/local/bin/ctxctl`. One binary serves all worktrees and repo copies; the local hook calls `ctxctl` from PATH so no repo-root binary is needed. Defensive `/ctxctl` + `tools/ctxctl/ctxctl` gitignores stay so stray binaries can never be committed.
+
+**Consequence**: New Makefile targets `install-ctxctl` and `reinstall-ctxctl` mirror `install`/`reinstall`. Hook in `.claude/settings.local.json`: `cd "$CLAUDE_PROJECT_DIR" && ctxctl audit-relay`. Sets the convention for future maintainer-only binaries (`tools/<name>/` separate module, `dist/` build, PATH install). `specs/ctxctl-bootstrap.md` Interface section updated to match.
+
+---
+
+## [2026-05-28-200500] Memory pressure detection uses OS-native signals (macOS pressure level + Linux PSI), not occupancy
+
+**Status**: Accepted
+
+**Context**: `check-resource` alerted DANGER at swap-used ≥ 75% / memory-used ≥ 90% — pure occupancy. macOS swap is sticky (never recedes); post-hibernation swap stays >75% with idle RAM, producing false "wrap up the session" DANGER at session start. Memory occupancy on macOS includes reclaimable cache — also a poor pressure proxy.
+
+**Decision**: Memory pressure detection uses OS-native signals (macOS pressure level + Linux PSI), not occupancy
+
+**Rationale**: Occupancy is a level; pressure is a derivative. Only the kernel's derivative reflects current struggle. macOS: `sysctl kern.memorystatus_vm_pressure_level` (1/2/4 → OK/Warning/Danger). Linux: `/proc/pressure/memory` (PSI) `some.avg10 ≥ 10.0` → warn, `full.avg10 ≥ 10.0` → danger. Windows: filed as an exploratory task; unsupported for now ("other" platform falls through to `PressureSupported=false`, no alert).
+
+**Consequence**: `MemInfo` gains `Pressure` + `PressureSupported`; `threshold.go` drops both occupancy `byteCheck`s and emits a single pressure alert. Doctor swap row removed (no longer a health signal); occupancy fields retained for `ctx stats` display. PSI 10.0 defaults named in `config/stats` — retunable in one place. `make lint` 0 issues, `make test` ok on the change.
+
+---
+
+## [2026-05-27-161302] ctxctl is a separate Go module at tools/ctxctl (own go.mod), not cmd/ctxctl in the same module
+
+**Status**: Accepted
+
+**Context**: Migrating the maintainer-only audit channel out of the ctx binary (specs/ctxctl-bootstrap.md). The prior decision (handover 2026-05-26) chose same-module cmd/ctxctl, on the belief that a separate go.mod could not import ctx's internal/ packages and would force relocating/duplicating ~25 files.
+
+**Decision**: ctxctl is a separate Go module at tools/ctxctl (own go.mod), not cmd/ctxctl in the same module
+
+**Rationale**: That blocker was empirically disproved this session: a nested module whose path is lexically under github.com/ActiveMemory/ctx CAN import the parent module's internal/ packages (verified by build test; a non-nested 'outsider' module path is rejected). Given that, a hard module boundary beats an in-module import-graph test for the asymmetric requirement that actually matters: ctx must never break because of ctxctl. ctx's go.mod will not require tools/ctxctl, so ctx literally cannot import ctxctl; the one-directional ctxctl->ctx coupling is acceptable because ctxctl is disposable maintainer tooling ('nobody whines if ctxctl breaks; everyone suffers if ctxctl leaks into ctx'). Full self-containment (duplicating the ~20 shared internal foundations: rc, desc, config, nudge, io...) was rejected as a DRY catastrophe and a worse broken window than the one being fixed.
+
+**Consequence**: New module tools/ctxctl (module path github.com/ActiveMemory/ctx/tools/ctxctl) reuses ctx's internal/ foundations in place; audit-channel-specific logic relocates to internal/ctxctl/; ctxctl owns its relay/CLI text as plain English Go constants under tools/ctxctl (no YAML localization, no desc/i18n engine for its own output -- no French ctxctl); a repo-root go.work (committed) wires the workspace; an import-graph guard test asserts cmd/ctx never imports internal/ctxctl. Supersedes the same-module cmd/ctxctl decision. specs/ctxctl-bootstrap.md is rewritten to match.
+
+---
+
 ## [2026-05-24-123908] ctxctl lives at cmd/ctxctl in the same Go module, not a separate go.mod
 
 **Status**: Accepted
 
@@ -17,6 +17,9 @@ DO NOT UPDATE FOR:
 <!-- INDEX:START -->
 | Date | Learning |
 |----|--------|
+| 2026-05-28 | Swap occupancy is not memory pressure — use the kernel's derivative |
+| 2026-05-28 | A non-root Go module nested under the main module's path CAN import its internal/ packages |
+| 2026-05-28 | cobra's legacyArgs lets unknown subcommands silently succeed on non-root groups |
 | 2026-05-25 | Skill shipping location: _ctx- prefix is repo-internal, internal/assets/claude/skills/ctx-* is bundled and shipped |
 | 2026-05-24 | Audit gates that bite when introducing new packages and helpers |
 | 2026-05-23 | Spec-trailer improvisation is heuristic drift — when no spec genuinely fits, the failure mode is reaching for the most-recent one |
@@ -162,6 +165,36 @@ DO NOT UPDATE FOR:
 
 ---
 
+## [2026-05-28-201500] Swap occupancy is not memory pressure — use the kernel's derivative
+
+**Context**: ctx's `check-resource` UserPromptSubmit hook alerted DANGER at swap-used ≥ 75% / memory-used ≥ 90%, generating false "wrap up the session" warnings at session start after hibernation. On macOS, swap doesn't recede when pressure ends — it's a sticky high-water mark, so static occupancy carries zero current information about whether the system is actually struggling.
+
+**Lesson**: macOS and Windows swap proactively, and swap occupancy is STICKY — it doesn't recede when pressure ends. After hibernation, swap can be >75% full with zero current pressure. Any alert keyed on `SwapUsed/SwapTotal ≥ X%` will false-positive at session start. The signal isn't the *level*, it's the *derivative* — pages actively being pushed out, or the kernel's own pressure metric.
+
+**Application**: For host-pressure detection, key on OS-native pressure signals (macOS `kern.memorystatus_vm_pressure_level` 1/2/4 → OK/Warning/Danger; Linux PSI `/proc/pressure/memory` `some.avg10` and `full.avg10`). These are kernel-computed derivatives — no snapshot state needed and they collapse to zero when the pressure ends. If native is unavailable, fall back to swap-out RATE (snapshot delta) gated on low available memory; never to occupancy alone. (Decision recorded same date; Windows exploratory task filed under Phase CLI-FIX.)
+
+---
+
+## [2026-05-28-201400] A non-root Go module nested under the main module's path CAN import its internal/ packages
+
+**Context**: While designing the ctxctl module split, the initial spec (and a lot of online consensus) claimed a separate `go.mod` cannot import the parent module's `internal/` packages, which would have forced relocating or duplicating ~25 foundation packages (`rc`, `desc`, `nudge`, `config/*`, …). The "obvious" reading made same-module the only viable option.
+
+**Lesson**: Go's internal-import rule is **lexical on import paths, not module-scoped**. A separate module whose path is `github.com/<owner>/<main>/tools/<x>` CAN import `github.com/<owner>/<main>/internal/...` — verified by an empirical build experiment this session. An outsider path (`example.com/...`) is rejected with `use of internal package … not allowed`. The rule fires on the import-path prefix relative to the `internal/` directory's parent, not on module boundaries.
+
+**Application**: For monorepo splits (maintainer-only tooling, isolated experiments, ancillary CLIs), choose a module path nested under the main module so the new module reuses the parent's foundations via the lexical-internal allowance. Full self-containment of a maintainer module would be a DRY catastrophe; the lexical allowance is the correct shape. Prove it with a throwaway `go build` against a representative `internal/` import before designing around the *wrong* constraint.
+
+---
+
+## [2026-05-28-201300] cobra's legacyArgs lets unknown subcommands silently succeed on non-root groups
+
+**Context**: Every prompt of this session injected 52 lines of `ctx system` help text into agent context, labeled "hook success." Investigation traced it to the 0.8.1 plugin's `hooks.json` wiring `ctx system check-anchor-drift` as the first UserPromptSubmit hook — a command the 0.8.1 binary no longer has (the command was deleted by the cwd-anchored migration in `fc7db228`, but the plugin's hook config wasn't updated). The harness reported "hook success" because cobra exits 0 on the unknown subcommand.
+
+**Lesson**: cobra's `legacyArgs` only raises "unknown command" for the **root** command (`!cmd.HasParent()`); any non-root group (built with `parent.Cmd`) treats an unknown subcommand as non-error: it falls through to `Help()` and returns nil → exit 0. In a UserPromptSubmit hook this is **invisible** — the harness logs "hook success" and injects the whole help text into agent context every prompt. The 0.8.1 plugin's stale wiring of the retired `check-anchor-drift` caused exactly this for the entire session.
+
+**Application**: Non-root cobra groups must have an explicit unknown-subcommand guard. Two routes: (a) `Args: cobra.NoArgs` so unknown subcommands error loud (non-zero exit + "unknown command" stderr); (b) a `RunE` that emits a **verbatim relay** — which is what actually reaches the user in a UserPromptSubmit hook context where a non-zero exit alone is invisible. Tracked under Phase CLI-FIX as the verbatim-relay guard on `ctx system`.
+
+---
+
 ## [2026-05-25-221357] Skill shipping location: _ctx- prefix is repo-internal, internal/assets/claude/skills/ctx-* is bundled and shipped
 
 **Context**: Created /ctx-surface-audit under internal/assets/claude/skills/ (the shipped path), but it audits ctx's own internal/ source layout — useless in an end-user project that installs ctx. There is an established _ctx-* family (_ctx-command-audit, _ctx-audit, _ctx-release, _ctx-qa, etc.) in .claude/skills/ for repo-only dev skills; the user caught the misplacement.