Adopt the four markdown namespaces and gate them

Renames this repo's markdown onto README.md / CLAUDE*.md / DOCS*.md /
TODO*.md so a future session can tell a live task from a finished
record without reading the file to find out.

TODO files carry the literal "REMOVE ME AFTER FINISH" and are deleted
when the work lands. Enforced by the md-naming pre-commit hook and CI
workflow, both delegating to the shared gate in kuhyx/utils so this
repo's idea of a valid name cannot drift from every other repo's.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A47aX5DJwmA3QFn3pkEWi7

.github/workflows/md-naming.yml

@@ -0,0 +1,38 @@
+name: md-naming
+
+# The four markdown namespaces, enforced on push as well as at commit time.
+# The local pre-commit hook can be skipped (a fresh clone that never ran
+# `pre-commit install` has no hooks at all), so the convention needs a second
+# gate that no one can forget to install.
+#
+# Deliberately a SEPARATE workflow from any release job: a badly named doc
+# should fail lint, not block publishing an artifact.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  md-naming:
+    name: markdown naming convention
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The gate and its exemption list live in the shared utils repo so every
+      # repo enforces the same namespaces. Checking it out beats vendoring a
+      # copy here, which is exactly how a gate and a survey start disagreeing.
+      - name: Check out the shared gate
+        uses: actions/checkout@v4
+        with:
+          repository: kuhyx/utils
+          path: .utils
+
+      - name: Enforce the naming convention
+        run: bash .utils/scripts/check_md_naming.sh --all
+
+      # Warns only: no machine can prove a task is finished, so an old TODO
+      # gets a nudge, never a failure.
+      - name: Warn about stale TODOs
+        run: PYTHONPATH=.utils python3 .utils/md_naming/stale.py

.pre-commit-config.yaml

@@ -235,3 +235,13 @@ repos:
         pass_filenames: false
         require_serial: true
         stages: [pre-push]
+
+      # Four markdown namespaces (README / CLAUDE* / DOCS* / TODO*), plus the
+      # rule that a TODO carries "REMOVE ME AFTER FINISH" and nothing else may.
+      # Shared gate in ~/utils owns the namespaces and the exemption list, so
+      # one repo's idea of a valid name cannot drift from every other repo's.
+      - id: md-naming
+        name: markdown naming convention
+        entry: scripts/check_md_naming.sh
+        language: system
+        files: \.(md|markdown)$

DESIGN_AUDIT_TODO.md

@@ -1,19 +0,0 @@
-# Design audit — screen-locker
-
-Generated against safe-design-rules (anthonyhobday.com/sideprojects/saferules).
-Report only — nothing in this repo was changed by the audit itself.
-
-This repo has two UI surfaces, audited separately below. `~/utils/gatelock`
-was checked with `git -C ~/utils/gatelock rev-parse --show-toplevel` → prints
-`/home/kuhy/utils`, i.e. gatelock is a subdirectory of the `~/utils` monorepo,
-**not its own git repo**. Per audit scope, no separate gatelock report was
-written; see the "Shared gatelock library" section at the end instead.
-
-Split into one file per audited surface to stay under the repo's 250-line
-cap; the findings themselves are unchanged.
-
-## Sections
-
-- [Python/Tkinter lock UI](docs/design-audit/python-tkinter-lock-ui.md) — `screen_locker/`
-- [Flutter workout app](docs/design-audit/flutter-workout-app.md) — `stronglift_replacement/workout_app/`
-- [Shared gatelock library](docs/design-audit/shared-gatelock-library.md) — `~/utils/gatelock`

scripts/check_md_naming.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# ============================================================================
+# Fail if any markdown file breaks the shared naming convention.
+#
+# Thin delegate to the shared gate in ~/utils, which owns the four namespaces
+# (README / CLAUDE* / DOCS* / TODO*), the "REMOVE ME AFTER FINISH" marker rule
+# and the exemption list. Copying that logic here is what lets one repo's idea
+# of a valid name drift from every other repo's -- so this script only locates
+# the shared checker and forwards its arguments.
+#
+# Usage:
+#   scripts/check_md_naming.sh <file> [<file> ...]   # pre-commit passes these
+#   scripts/check_md_naming.sh --all                 # whole tree, from cwd
+# ============================================================================
+
+set -euo pipefail
+
+readonly SHARED_GATE="${UTILS_ROOT:-$HOME/utils}/scripts/check_md_naming.sh"
+
+main() {
+    if [[ ! -x "$SHARED_GATE" ]]; then
+        echo "Error: shared markdown-naming gate not found at $SHARED_GATE" >&2
+        echo "       Clone github.com/kuhyx/utils to ~/utils, or set" >&2
+        echo "       UTILS_ROOT to where it lives." >&2
+        exit 1
+    fi
+
+    exec bash "$SHARED_GATE" "$@"
+}
+
+main "$@"