test: decide and wire a testing strategy for grimoire's executable code (#34)

.github/workflows/ci.yml

@@ -37,6 +37,25 @@ jobs:
       - name: Verify
         run: make verify
 
+  test:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: "22"
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Test
+        run: make test
+
   lint:
     runs-on: ubuntu-24.04
     timeout-minutes: 10
@@ -70,12 +89,12 @@ jobs:
     if: always()
     # When you add jobs above, add them to BOTH the needs list and the results
     # array below.
-    needs: [verify, lint]
+    needs: [verify, test, lint]
     runs-on: ubuntu-24.04
     timeout-minutes: 2
     steps:
       - run: |
-          results=("${{ needs.verify.result }}" "${{ needs.lint.result }}")
+          results=("${{ needs.verify.result }}" "${{ needs.test.result }}" "${{ needs.lint.result }}")
           for r in "${results[@]}"; do
             if [[ "$r" != "success" && "$r" != "skipped" ]]; then
               echo "Check failed: $r"

CLAUDE.md

@@ -56,12 +56,26 @@ done, confirm:
 
 ```bash
 make verify
+make test
 make lint
 ```
 
 CI runs the same checks. `AGENTS.md` is a symlink to this file, not a second
 source of truth -- edit `CLAUDE.md`.
 
+## Test
+
+`make test` runs `node --test` (Node hook scripts and reviewer tooling) and
+`python3 -m unittest discover` (`scripts/generate-codex.py`). Both runners ship
+with the interpreter already running that code, so neither adds a dependency.
+Write logic that carries real parsing or bookkeeping as a pure, exported
+function -- a thin hook wrapper that only calls the Claude Code hook API back
+is not worth a fixture. Node tests live beside their source as `*.test.js`
+(node:test's own zero-config discovery pattern); Python tests live in
+`scripts/` as `test_*.py` (unittest's discovery pattern) and load
+`generate-codex.py` via `importlib`, since its hyphenated filename cannot be
+`import`ed directly.
+
 Then confirm by inspection: each skill/agent frontmatter `name` matches its directory, and
 any plugin with changed content under `plugins/<name>/` has a bumped `version` in
 `plugin.json`.

CONTRIBUTING.md

@@ -22,6 +22,7 @@ error.
 ```bash
 make lint
 make verify
+make test
 ```
 
 Both must pass -- CI runs the same checks. `make help` lists what each target

Makefile

@@ -1,7 +1,7 @@
 # CI calls these targets directly, so this file is the single definition of the
 # checks. Recipes run under dash both here and on the runners -- no bashisms.
 
-.PHONY: help install lint verify
+.PHONY: help install lint verify test
 
 help:  ## Show available targets
 	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*?## "}{printf "  %-12s %s\n", $$1, $$2}'
@@ -14,6 +14,15 @@ install:  ## Install pre-commit and wire the git hook
 lint:  ## Lint all files via pre-commit (codespell, shellcheck, markdownlint, lychee, actionlint, zizmor, hygiene)
 	pre-commit run --all-files --show-diff-on-failure
 
+# Both runners ship with the interpreter already running every hook and
+# generate-codex.py, so neither line adds a dependency. `node --test` with no
+# path args recursively discovers *.test.js; unittest's discover needs an
+# explicit pattern since its default (test*.py) would also match a stray
+# fixture module.
+test:  ## Run the test suite (node:test, Python unittest)
+	node --test
+	python3 -m unittest discover -s scripts -p 'test_*.py'
+
 # `git grep -l` exits 1 on no match, so `|| true` would turn the ASCII gate into
 # a permanent no-op and any other non-zero means the invocation itself failed.
 # One logical line because Make gives each recipe line its own shell.

README.md

@@ -57,6 +57,7 @@ Local checks, run by CI and by the pre-commit hook:
 ```bash
 make lint
 make verify
+make test
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions.

plugins/praxis/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Development workflow -- issue planning, implementation, PR creation, code review with specialized reviewers, and project conventions",
   "author": {
     "name": "Jartan LLC",

plugins/praxis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Development workflow -- issue planning, implementation, PR creation, code review with specialized reviewers, and project conventions",
   "interface": {
     "displayName": "Praxis",

plugins/praxis/README.md

@@ -52,8 +52,9 @@ codex plugin add gitwise@grimoire
 ### Skills
 
 - **api-error-patterns** -- error response format, status codes
-- **code-hygiene** -- zombie code (dead/reinvented/orphaned), tombstone comments
+- **code-hygiene** -- zombie code (dead/reinvented/orphaned), truthful names, real implementations
 - **code-structure** -- structural craft: decompose on responsibility not size, deep modules, cohesion/coupling/interface/error-contract/data shape
+- **comment-hygiene** -- comment truthfulness: KEEP/DELETE/EXEMPT/CONDITIONAL, tombstone and retold-fact detection, comment density
 - **docs-patterns** -- writing style, structure, brevity
 - **frontend-patterns** -- design tokens, mobile-first, component isolation
 - **logging-patterns** -- log levels, formatting, structured output

plugins/praxis/agents/general-reviewer.md

@@ -8,6 +8,7 @@ permissionMode: plan
 skills:
   - gitwise:github-conventions
   - code-hygiene
+  - comment-hygiene
   - review-severity
 ---
 
@@ -17,8 +18,8 @@ You are a senior code reviewer focusing on general quality and adherence to proj
 
 1. **Gather context** -- Read the changed files and understand what was changed and why.
 2. **Check project conventions** -- Read `CLAUDE.md` for project constraints.
-3. **Index repeated comments** -- run `find-duplicate-comments.js` from the `code-hygiene` skill; a retelling is invisible from the file it sits in.
-4. **Weigh the diff as a body** -- a per-comment pass at every site still misses an over-commented diff; run the density check in `code-hygiene`.
+3. **Index repeated comments** -- run `find-duplicate-comments.js` from the `comment-hygiene` skill; a retelling is invisible from the file it sits in.
+4. **Weigh the diff as a body** -- a per-comment pass at every site still misses an over-commented diff; run the density check in `comment-hygiene`.
 5. **Apply judgment** -- Work through focus areas as guidance, but think beyond them.
 
 ## Confidence Filtering
@@ -40,16 +41,17 @@ Guidance, not an exhaustive checklist -- tier each finding with the `review-seve
 
 ### Important
 
-- Reinvention and orphaned abstractions (speculative generality), and comments that don't earn their place -- see `code-hygiene`
+- Reinvention and orphaned abstractions (speculative generality) -- see `code-hygiene`
+- Comments that don't earn their place -- see `comment-hygiene`
 - Blanket linter/type/test suppressions -- see `code-hygiene`
 - Duplication a maintainer must untangle -- see `code-hygiene`
-- Retold facts -- a keep-category comment told again at another site -- see `code-hygiene`
+- Retold facts -- a keep-category comment told again at another site -- see `comment-hygiene`
 
 ### Minor
 
 - Non-conventional naming (casing, prefixes, project style)
-- Dead / commented-out code, and debug/scaffolding output left behind -- see `code-hygiene`
-- Unanchored TODOs -- see `code-hygiene`
+- Dead code, commented-out code, and debug/scaffolding output left behind -- see `code-hygiene`
+- Unanchored TODOs -- see `comment-hygiene`
 
 ## Deferred
 

plugins/praxis/codex/agents/general-reviewer.toml

@@ -8,8 +8,8 @@ You are a senior code reviewer focusing on general quality and adherence to proj
 
 1. **Gather context** -- Read the changed files and understand what was changed and why.
 2. **Check project conventions** -- Read `CLAUDE.md` for project constraints.
-3. **Index repeated comments** -- run `find-duplicate-comments.js` from the `code-hygiene` skill; a retelling is invisible from the file it sits in.
-4. **Weigh the diff as a body** -- a per-comment pass at every site still misses an over-commented diff; run the density check in `code-hygiene`.
+3. **Index repeated comments** -- run `find-duplicate-comments.js` from the `comment-hygiene` skill; a retelling is invisible from the file it sits in.
+4. **Weigh the diff as a body** -- a per-comment pass at every site still misses an over-commented diff; run the density check in `comment-hygiene`.
 5. **Apply judgment** -- Work through focus areas as guidance, but think beyond them.
 
 ## Confidence Filtering
@@ -31,16 +31,17 @@ Guidance, not an exhaustive checklist -- tier each finding with the `review-seve
 
 ### Important
 
-- Reinvention and orphaned abstractions (speculative generality), and comments that don't earn their place -- see `code-hygiene`
+- Reinvention and orphaned abstractions (speculative generality) -- see `code-hygiene`
+- Comments that don't earn their place -- see `comment-hygiene`
 - Blanket linter/type/test suppressions -- see `code-hygiene`
 - Duplication a maintainer must untangle -- see `code-hygiene`
-- Retold facts -- a keep-category comment told again at another site -- see `code-hygiene`
+- Retold facts -- a keep-category comment told again at another site -- see `comment-hygiene`
 
 ### Minor
 
 - Non-conventional naming (casing, prefixes, project style)
-- Dead / commented-out code, and debug/scaffolding output left behind -- see `code-hygiene`
-- Unanchored TODOs -- see `code-hygiene`
+- Dead code, commented-out code, and debug/scaffolding output left behind -- see `code-hygiene`
+- Unanchored TODOs -- see `comment-hygiene`
 
 ## Deferred
 
@@ -74,5 +75,5 @@ ran must not read as one that found nothing.
 
 ## Skills
 
-Load these skills before starting: `gitwise:github-conventions`, `praxis:code-hygiene`, `praxis:review-severity`.
+Load these skills before starting: `gitwise:github-conventions`, `praxis:code-hygiene`, `praxis:comment-hygiene`, `praxis:review-severity`.
 '''