[codex] tighten data rotation, cleanup, and service lifecycle defaults

README.md

@@ -280,6 +280,7 @@ Use the dedicated CI helpers when you need to spin up the published stack inside
 | `provision-qa` | Differential backup + targeted restore for QA databases. |
 | `config-render` | Re-render `postgresql.conf` / `pg_hba.conf` from the templates and restart PostgreSQL (terminates active connections; required for some settings like `shared_buffers` and `max_connections`). |
 | `config-check` | Compare live `postgresql.conf` / `pg_hba.conf` against rendered templates to catch drift. |
+| `data-cleanup` | Report or remove stale `data/.pytest_backups` entries left by interrupted local pytest runs; dry-run by default, deletes entries older than 7 days only with `--execute`. |
 | `audit-roles` / `audit-security` | Generate CSV/text reports covering role hygiene, passwords, and HBA/RLS posture. |
 | `audit-extensions` | Confirm bundled extensions are present and on expected versions. |
 | `audit-autovacuum` | Flag tables with high dead tuple counts or ratios. |
@@ -311,6 +312,8 @@ Use the dedicated CI helpers when you need to spin up the published stack inside
 
 The CLI sources modular helpers from `scripts/lib/` so each function can be imported by tests or future automation.
 
+Interrupted local test runs can leave full service-directory snapshots under `data/.pytest_backups/`. These are disposable pytest stashes, not live cluster state. Inspect them with `./scripts/manage.sh data-cleanup`; remove stale entries with `./scripts/manage.sh data-cleanup --execute`. The command only targets `.pytest_backups`, defaults to entries older than 7 days, and refuses to delete while Compose containers are running unless `--force` is supplied.
+
 `daily-maintenance` now emits a richer bundle under `backups/daily/<YYYYMMDD>/`, including `pg_stat_statements` snapshots, `pg_buffercache` heatmaps, role/extension/autovacuum/replication CSVs, pg_cron schedules, pg_squeeze activity, and a security checklist alongside logs, dumps, pgBadger HTML, and pgaudit summaries. The workflow also records per-step results in `maintenance_status.json`, records the most recent sidecar dump run in `logical_backup_status.txt`, runs `partman.run_maintenance_proc()` across each database so freshly created partitions land even if the background worker interval has not elapsed, and captures version drift in `version_status.csv` (focusing on out-of-date components). Pair those reports with `config-check` to keep the rendered configs aligned with the templates. Tune the thresholds via `DAILY_PG_STAT_LIMIT`, `DAILY_BUFFERCACHE_LIMIT`, `DAILY_DEAD_TUPLE_THRESHOLD`, `DAILY_DEAD_TUPLE_RATIO`, and `DAILY_REPLICATION_LAG_THRESHOLD` as needed.
 
 Nightly cron jobs also refresh pg_squeeze targets, reset `pg_stat_statements`, and run a safe `VACUUM (ANALYZE, SKIP_LOCKED, PARALLEL 4)` so statistics stay current without blocking hot tables.

docs/SOURCE_DOCS.md

@@ -0,0 +1,7 @@
+# Source Documentation Index
+
+This index links repository source documentation that is required by the local
+module documentation policy.
+
+- [../tests/MODULE.md](../tests/MODULE.md) - test-suite contracts and cleanup
+  safety expectations.

repo_config.yaml

@@ -1,3 +1,14 @@
+hooks:
+  enabled_groups:
+    - format
+    - syntax
+    - workflow
+    - go
+    - ai
+    - commit-msg
+
 python:
+  docstring_coverage:
+    enabled: false
   pytest_gate:
     enabled: false

scripts/lib/apparmor.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc.
+# SPDX-License-Identifier: MIT
+
+# shellcheck shell=bash
+set -euo pipefail
+
+APPARMOR_LIB_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=common.sh
+# shellcheck disable=SC1091
+source "${APPARMOR_LIB_DIR}/common.sh"
+
+cmd_apparmor_load() {
+  local parser=${APPARMOR_PARSER:-apparmor_parser}
+  if ! command -v "${parser}" >/dev/null 2>&1; then
+    echo "[apparmor] ${parser} not found. Install apparmor-utils (Debian/Ubuntu) or ensure apparmor_parser is on PATH." >&2
+    exit 1
+  fi
+  if [[ $EUID -ne 0 ]] && ! command -v sudo >/dev/null 2>&1; then
+    echo "[apparmor] sudo required to load profiles or rerun as root." >&2
+    exit 1
+  fi
+  local loaded=false
+  for profile in "${ROOT_DIR}/apparmor"/*.profile; do
+    [[ -e "${profile}" ]] || continue
+    if [[ $EUID -ne 0 ]]; then
+      sudo "${parser}" -r -W "${profile}" || exit 1
+    else
+      "${parser}" -r -W "${profile}" || exit 1
+    fi
+    loaded=true
+    echo "[apparmor] loaded ${profile##*/}" >&2
+  done
+  if [[ ${loaded} == false ]]; then
+    echo "[apparmor] no profiles found under ${ROOT_DIR}/apparmor" >&2
+    exit 1
+  fi
+  echo "[apparmor] profiles loaded. Set CORE_DATA_APPARMOR_<SERVICE>=apparmor:core_data_minimal (or your custom profile) before composing." >&2
+}

scripts/lib/data_cleanup.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc.
+# SPDX-License-Identifier: MIT
+
+# shellcheck shell=bash
+set -euo pipefail
+
+DATA_CLEANUP_LIB_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=common.sh
+# shellcheck disable=SC1091
+source "${DATA_CLEANUP_LIB_DIR}/common.sh"
+
+DATA_CLEANUP_DEFAULT_RETENTION=${DATA_CLEANUP_DEFAULT_RETENTION:-7d}
+CORE_DATA_DATA_ROOT=${CORE_DATA_DATA_ROOT:-${ROOT_DIR}/data}
+
+data_cleanup_usage() {
+  cat <<'USAGE'
+Usage: manage.sh data-cleanup [options]
+
+Remove stale pytest data stashes left under data/.pytest_backups.
+
+Options:
+  --older-than AGE       Retain entries newer than AGE (default: 7d).
+                         AGE accepts s, m, h, or d suffixes.
+  --execute             Delete matching entries. Without this, only report.
+  --force               Allow execution even when compose containers are running.
+  --json                Emit a JSON summary.
+  -h, --help            Show this help.
+USAGE
+}
+
+data_cleanup_parse_age() {
+  local age=$1
+  local number
+  local suffix
+
+  if [[ "${age}" =~ ^([0-9]+)([smhd])$ ]]; then
+    number=${BASH_REMATCH[1]}
+    suffix=${BASH_REMATCH[2]}
+  elif [[ "${age}" =~ ^([0-9]+)$ ]]; then
+    number=${BASH_REMATCH[1]}
+    suffix=d
+  else
+    echo "[data-cleanup] invalid age '${age}'; expected values like 24h or 7d." >&2
+    return 1
+  fi
+
+  case "${suffix}" in
+    s) echo "${number}" ;;
+    m) echo $((number * 60)) ;;
+    h) echo $((number * 60 * 60)) ;;
+    d) echo $((number * 24 * 60 * 60)) ;;
+  esac
+}
+
+data_cleanup_compose_running() {
+  local output
+  if ! output=$(compose ps -q 2>/dev/null); then
+    return 2
+  fi
+  [[ -n "${output}" ]]
+}
+
+data_cleanup_json_escape() {
+  local value=$1
+  value=${value//\\/\\\\}
+  value=${value//\"/\\\"}
+  value=${value//$'\n'/\\n}
+  printf '%s' "${value}"
+}
+
+cmd_data_cleanup() {
+  local older_than=${DATA_CLEANUP_DEFAULT_RETENTION}
+  local execute=false
+  local force=false
+  local json=false
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --older-than)
+        if [[ $# -lt 2 ]]; then
+          echo "[data-cleanup] --older-than requires an age value." >&2
+          return 1
+        fi
+        older_than=$2
+        shift 2
+        ;;
+      --older-than=*)
+        older_than=${1#*=}
+        shift
+        ;;
+      --execute)
+        execute=true
+        shift
+        ;;
+      --force)
+        force=true
+        shift
+        ;;
+      --json)
+        json=true
+        shift
+        ;;
+      -h | --help)
+        data_cleanup_usage
+        return 0
+        ;;
+      *)
+        echo "[data-cleanup] unknown option: $1" >&2
+        data_cleanup_usage >&2
+        return 1
+        ;;
+    esac
+  done
+
+  local retention_seconds
+  retention_seconds=$(data_cleanup_parse_age "${older_than}")
+  local now
+  now=$(date +%s)
+  local cutoff=$((now - retention_seconds))
+  local backup_root="${CORE_DATA_DATA_ROOT%/}/.pytest_backups"
+  local candidates=()
+  local candidate_count=0
+  local total_bytes=0
+
+  if [[ -d "${backup_root}" ]]; then
+    local path
+    while IFS= read -r -d '' path; do
+      local modified
+      modified=$(stat -c '%Y' "${path}")
+      if ((modified <= cutoff)); then
+        local bytes
+        bytes=$(du -s -B1 "${path}" | awk '{print $1}')
+        candidates+=("${path}")
+        candidate_count=$((candidate_count + 1))
+        total_bytes=$((total_bytes + bytes))
+      fi
+    done < <(find "${backup_root}" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z)
+  fi
+
+  if [[ "${execute}" == "true" && "${force}" != "true" ]]; then
+    local compose_state=0
+    data_cleanup_compose_running || compose_state=$?
+    case "${compose_state}" in
+      0)
+        echo "[data-cleanup] refusing to delete while compose containers are running; rerun after shutdown or pass --force." >&2
+        return 1
+        ;;
+      2)
+        echo "[data-cleanup] unable to determine compose state; pass --force to execute anyway." >&2
+        return 1
+        ;;
+    esac
+  fi
+
+  if [[ "${json}" == "true" ]]; then
+    printf '{"mode":"%s","backup_root":"%s","older_than":"%s","candidates":%d,"bytes":%d,"paths":[' \
+      "$([[ "${execute}" == "true" ]] && echo execute || echo dry-run)" \
+      "$(data_cleanup_json_escape "${backup_root}")" \
+      "$(data_cleanup_json_escape "${older_than}")" \
+      "${candidate_count}" \
+      "${total_bytes}"
+    local first=true
+    local candidate
+    for candidate in "${candidates[@]}"; do
+      if [[ "${first}" == "true" ]]; then
+        first=false
+      else
+        printf ','
+      fi
+      printf '"%s"' "$(data_cleanup_json_escape "${candidate}")"
+    done
+    printf ']}\n'
+  else
+    printf '[data-cleanup] mode: %s\n' "$([[ "${execute}" == "true" ]] && echo execute || echo dry-run)"
+    printf '[data-cleanup] backup root: %s\n' "${backup_root}"
+    printf '[data-cleanup] retention: older than %s\n' "${older_than}"
+    printf '[data-cleanup] candidates: %d\n' "${candidate_count}"
+    printf '[data-cleanup] reclaimable bytes: %d\n' "${total_bytes}"
+    local candidate
+    for candidate in "${candidates[@]}"; do
+      printf '%s\n' "${candidate}"
+    done
+    if [[ "${execute}" != "true" ]]; then
+      printf '[data-cleanup] dry run only; pass --execute to delete matching entries.\n'
+    fi
+  fi
+
+  if [[ "${execute}" == "true" ]]; then
+    local candidate
+    for candidate in "${candidates[@]}"; do
+      rm -rf -- "${candidate}"
+    done
+  fi
+}

scripts/manage.sh

@@ -43,12 +43,16 @@ source "${SCRIPT_DIR}/lib/memcached.sh"
 source "${SCRIPT_DIR}/lib/rabbitmq.sh"
 # shellcheck source=scripts/lib/seccomp.sh
 source "${SCRIPT_DIR}/lib/seccomp.sh"
+# shellcheck source=scripts/lib/apparmor.sh
+source "${SCRIPT_DIR}/lib/apparmor.sh"
 # shellcheck source=scripts/lib/test_dataset.sh
 source "${SCRIPT_DIR}/lib/test_dataset.sh"
 # shellcheck source=scripts/lib/bootstrap_ci.sh
 source "${SCRIPT_DIR}/lib/bootstrap_ci.sh"
 # shellcheck source=scripts/lib/ci.sh
 source "${SCRIPT_DIR}/lib/ci.sh"
+# shellcheck source=scripts/lib/data_cleanup.sh
+source "${SCRIPT_DIR}/lib/data_cleanup.sh"
 # shellcheck source=scripts/lib/permissions.sh
 source "${SCRIPT_DIR}/lib/permissions.sh"
 
@@ -172,6 +176,7 @@ Lifecycle
   networks-show                       Print the currently rendered allow list.
   config-render                       Re-render postgresql.conf/pg_hba.conf then restart PostgreSQL.
   config-check                        Compare live configs to rendered templates.
+  data-cleanup                        Remove stale pytest data stashes (dry-run by default).
   logs                                Tail postgres logs.
   status                              Show container status and health.
   service-urls                        Print connection URLs for local services using external host IP.
@@ -377,34 +382,6 @@ cmd_service_urls() {
 
 }
 
-cmd_apparmor_load() {
-	local parser=${APPARMOR_PARSER:-apparmor_parser}
-	if ! command -v "${parser}" >/dev/null 2>&1; then
-		echo "[apparmor] ${parser} not found. Install apparmor-utils (Debian/Ubuntu) or ensure apparmor_parser is on PATH." >&2
-		exit 1
-	fi
-	if [[ $EUID -ne 0 ]] && ! command -v sudo >/dev/null 2>&1; then
-		echo "[apparmor] sudo required to load profiles or rerun as root." >&2
-		exit 1
-	fi
-	local loaded=false
-	for profile in "${ROOT_DIR}/apparmor"/*.profile; do
-		[[ -e "${profile}" ]] || continue
-		if [[ $EUID -ne 0 ]]; then
-			sudo "${parser}" -r -W "${profile}" || exit 1
-		else
-			"${parser}" -r -W "${profile}" || exit 1
-		fi
-		loaded=true
-		echo "[apparmor] loaded ${profile##*/}" >&2
-	done
-	if [[ ${loaded} == false ]]; then
-		echo "[apparmor] no profiles found under ${ROOT_DIR}/apparmor" >&2
-		exit 1
-	fi
-	echo "[apparmor] profiles loaded. Set CORE_DATA_APPARMOR_<SERVICE>=apparmor:core_data_minimal (or your custom profile) before composing." >&2
-}
-
 ensure_compose
 
 COMMAND=${CORE_DATA_SELECTED_COMMAND:-help}
@@ -429,6 +406,9 @@ ci-up)
 ci-down)
 	cmd_ci_down "$@"
 	;;
+data-cleanup)
+	cmd_data_cleanup "$@"
+	;;
 build-image)
 	ensure_env
 	build_postgres_image

tests/MODULE.md

@@ -0,0 +1,10 @@
+# Tests Module
+
+The `tests` package verifies Core Data management behavior from the operator
+boundary. Lightweight tests avoid Docker where possible, while integration tests
+exercise Compose-managed services and persistent data workflows.
+
+Tests that create temporary service data must isolate their data roots and must
+not remove live directories outside their fixture-owned paths. Cleanup tests use
+fake Compose binaries to validate command safety gates without depending on a
+running container stack.

tests/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc.
+# SPDX-License-Identifier: MIT
+
+"""Repository test suite contracts.
+
+This package contains lightweight and integration tests for the Core Data
+management tooling. The tests exercise operator-facing shell commands and
+container workflows from outside the production code paths.
+
+See Also:
+    MODULE.md: Test-suite contract and cleanup safety expectations.
+
+"""