diff --git a/.github/workflows/md-naming.yml b/.github/workflows/md-naming.yml new file mode 100644 index 0000000..1bb197c --- /dev/null +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 4885257..c5f81a9 100644 --- a/.pre-commit-config.yaml +++ b/.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)$ diff --git a/DESIGN_AUDIT_TODO.md b/DESIGN_AUDIT_TODO.md deleted file mode 100644 index 294df55..0000000 --- a/DESIGN_AUDIT_TODO.md +++ /dev/null @@ -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` diff --git a/refactor_claude_todo.md b/TODO-file-length-250.md similarity index 100% rename from refactor_claude_todo.md rename to TODO-file-length-250.md diff --git a/todo_finish_dart_250_prompt.md b/TODO-finish-dart-250.md similarity index 100% rename from todo_finish_dart_250_prompt.md rename to TODO-finish-dart-250.md diff --git a/todo_fix_pylint_10_prompt.md b/TODO-pylint-to-ten.md similarity index 100% rename from todo_fix_pylint_10_prompt.md rename to TODO-pylint-to-ten.md diff --git a/docs/android-ui-automation-task.md b/docs/TODO-android-ui-mcp-wrapper.md similarity index 100% rename from docs/android-ui-automation-task.md rename to docs/TODO-android-ui-mcp-wrapper.md diff --git a/docs/design-audit/flutter-workout-app.md b/docs/design-audit/DOCS-audit-flutter-workout.md similarity index 100% rename from docs/design-audit/flutter-workout-app.md rename to docs/design-audit/DOCS-audit-flutter-workout.md diff --git a/docs/design-audit/shared-gatelock-library.md b/docs/design-audit/DOCS-audit-gatelock-tokens.md similarity index 100% rename from docs/design-audit/shared-gatelock-library.md rename to docs/design-audit/DOCS-audit-gatelock-tokens.md diff --git a/docs/design-audit/python-tkinter-lock-ui.md b/docs/design-audit/DOCS-audit-tkinter-lock-ui.md similarity index 100% rename from docs/design-audit/python-tkinter-lock-ui.md rename to docs/design-audit/DOCS-audit-tkinter-lock-ui.md diff --git a/docs/todo/workstream-c-github-sync-workout-data.md b/docs/todo/DOCS-workstream-c-github-sync.md similarity index 100% rename from docs/todo/workstream-c-github-sync-workout-data.md rename to docs/todo/DOCS-workstream-c-github-sync.md diff --git a/docs/todo/workstream-d-scoping-findings.md b/docs/todo/DOCS-workstream-d-scoping-findings.md similarity index 100% rename from docs/todo/workstream-d-scoping-findings.md rename to docs/todo/DOCS-workstream-d-scoping-findings.md diff --git a/docs/todo/workstream-d-shared-crdt-transport.md b/docs/todo/DOCS-workstream-d-shared-crdt-transport.md similarity index 100% rename from docs/todo/workstream-d-shared-crdt-transport.md rename to docs/todo/DOCS-workstream-d-shared-crdt-transport.md diff --git a/prompts/dopamine-ux-04-screen-locker.md b/prompts/TODO-dopamine-ux-04-screen-locker.md similarity index 100% rename from prompts/dopamine-ux-04-screen-locker.md rename to prompts/TODO-dopamine-ux-04-screen-locker.md diff --git a/prompts/dopamine-ux-05-workout-app.md b/prompts/TODO-dopamine-ux-05-workout-app.md similarity index 100% rename from prompts/dopamine-ux-05-workout-app.md rename to prompts/TODO-dopamine-ux-05-workout-app.md diff --git a/scripts/check_md_naming.sh b/scripts/check_md_naming.sh new file mode 100755 index 0000000..50deaa0 --- /dev/null +++ b/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 [ ...] # 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 "$@" diff --git a/stronglift_replacement/design.md b/stronglift_replacement/DOCS-workout-app-requirements.md similarity index 100% rename from stronglift_replacement/design.md rename to stronglift_replacement/DOCS-workout-app-requirements.md diff --git a/stronglift_replacement/dfesign_v2.md b/stronglift_replacement/TODO-workout-app-v2.md similarity index 100% rename from stronglift_replacement/dfesign_v2.md rename to stronglift_replacement/TODO-workout-app-v2.md diff --git a/stronglift_replacement/workout_app/CONTEXT.md b/stronglift_replacement/workout_app/TODO-workout-app-context.md similarity index 100% rename from stronglift_replacement/workout_app/CONTEXT.md rename to stronglift_replacement/workout_app/TODO-workout-app-context.md