feat: CORTEX CLI v4.0 — operational layer with enforcement, scoring, and validation#4
Merged
WPHILLIPMACLAYNE merged 1 commit intomainfrom Apr 14, 2026
Conversation
…alidation Transform CORTEX from a documentation framework into a real operational layer with a CLI that verifies, scores, and protects projects. New CLI commands: - cortex init: install .cortex/ (replaces standalone script) - cortex doctor: health check of .cortex/ installation - cortex status: quick project overview with CSEI score - cortex validate: verify package and installation consistency - cortex score: compute CSEI automatically from repo evidence - cortex hooks install/remove/status: git hooks that enforce Law 3 Key changes: - cli/core/: manifest, repo, templates, scoring modules - cli/commands/: init, doctor, status, validate, score, hooks - cli/hooks/: pre-commit (blocks main), pre-push (blocks main), post-checkout (state reminder) - pyproject.toml: installable via pip (cortex-os) - 22 new CLI tests (34 total with installer tests) - Updated CI, docs, README, START.md, MANIFEST v4.0.0 CSEI is now computed by evidence, not opinion: Structure, Clarity, Safety, Verification, Continuity, Recoverability, and Regression Pressure — all measured from actual repo state. Co-Authored-By: Claude Opus 4.6 <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR introduces CORTEX CLI v4.0 as an operational layer around the existing template/manifest system, adding commands for installation, health checks, status reporting, validation, automated CSEI scoring, and git-hook based branch enforcement.
Changes:
- Adds a new Python CLI package (
cli/) with 6 commands (init,doctor,status,validate,score,hooks) plus hook scripts. - Implements automated CSEI scoring based on repository and
.cortex/evidence. - Updates docs/CI/metadata for v4.0.0 and adds a new CLI-focused test suite.
Reviewed changes
Copilot reviewed 24 out of 26 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
pyproject.toml |
Defines packaging and console entrypoint for the new CLI. |
cli/main.py |
CLI entrypoint and argparse command wiring. |
cli/__main__.py |
Enables python -m cli execution. |
cli/__init__.py |
Defines CLI version. |
cli/commands/init.py |
Implements .cortex/ installation logic from manifest/templates. |
cli/commands/doctor.py |
Implements installation + repo health checks with actionable output. |
cli/commands/status.py |
Provides a combined project status + CSEI summary view. |
cli/commands/validate.py |
Validates manifest/templates consistency and target .cortex/ state. |
cli/commands/score.py |
Computes and optionally writes back CSEI into CURRENT_STATUS.md. |
cli/commands/hooks.py |
Installs/removes/reports git hooks for branch enforcement. |
cli/core/manifest.py |
Loads MANIFEST.yaml (PyYAML optional) and exposes file lists/version. |
cli/core/templates.py |
Detects installed/missing/filled template files and reads fields/sections. |
cli/core/repo.py |
Git inspection helpers for branch/clean/remote/commit metadata. |
cli/core/scoring.py |
Implements evidence-based CSEI computation. |
cli/hooks/pre-commit |
Blocks commits on main/master (Law 3 enforcement). |
cli/hooks/pre-push |
Blocks pushes on main/master (Law 3 enforcement). |
cli/hooks/post-checkout |
Prints status reminder on branch switches. |
tests/test_cli.py |
Adds CLI tests covering init/doctor/status/score/hooks/validate and manifest consistency. |
docs/installing.md |
Updates installation docs to focus on the CLI workflow. |
docs/releasing.md |
Updates release checklist to run CLI tests/validation and version checks. |
README.md |
Documents CLI, hooks, and CSEI automation additions. |
START.md |
Updates the recommended first steps to use the CLI + hooks + scoring. |
MANIFEST.yaml |
Bumps manifest version to 4.0.0. |
.github/workflows/ci.yml |
Runs CLI tests and basic python -m cli validations in CI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| [tool.setuptools.package-data] | ||
| "cli.hooks" = ["pre-commit", "pre-push", "post-checkout"] | ||
| "" = ["MANIFEST.yaml", "templates/*.md"] |
Comment on lines
+10
to
+12
| _ROOT = Path(__file__).resolve().parents[2] | ||
| MANIFEST_PATH = _ROOT / "MANIFEST.yaml" | ||
|
|
Comment on lines
+22
to
+23
| # 1 point for .cortex/ existing, up to 4 more based on fill ratio | ||
| score = 1 + round((filled / total) * 4) |
Comment on lines
+11
to
+12
| echo " Push your feature branch instead:" | ||
| echo " git push -u origin $BRANCH" |
| else: | ||
| warnings.append("CURRENT_STATUS.md has no next safe step defined") | ||
|
|
||
| stable_branch = templates.read_field(d / "CURRENT_STATUS.md", "Name") |
Comment on lines
+111
to
+114
| # CURRENT_STATUS has last stable branch | ||
| branch = templates.read_field(d / "CURRENT_STATUS.md", "Name") | ||
| if branch: | ||
| score += 1 |
Comment on lines
+25
to
+32
| subprocess.run(["git", "init", "-b", "main", tmp], capture_output=True) | ||
| subprocess.run( | ||
| ["git", "config", "user.email", "[email protected]"], | ||
| capture_output=True, cwd=tmp, | ||
| ) | ||
| subprocess.run( | ||
| ["git", "config", "user.name", "Test"], | ||
| capture_output=True, cwd=tmp, |
Comment on lines
+22
to
+25
| def make_git_repo(): | ||
| """Create a temporary git repo and return its path.""" | ||
| tmp = tempfile.mkdtemp() | ||
| subprocess.run(["git", "init", "-b", "main", tmp], capture_output=True) |
Comment on lines
+25
to
+32
| subprocess.run(["git", "init", "-b", "main", tmp], capture_output=True) | ||
| subprocess.run( | ||
| ["git", "config", "user.email", "[email protected]"], | ||
| capture_output=True, cwd=tmp, | ||
| ) | ||
| subprocess.run( | ||
| ["git", "config", "user.name", "Test"], | ||
| capture_output=True, cwd=tmp, |
Comment on lines
+25
to
+32
| subprocess.run(["git", "init", "-b", "main", tmp], capture_output=True) | ||
| subprocess.run( | ||
| ["git", "config", "user.email", "[email protected]"], | ||
| capture_output=True, cwd=tmp, | ||
| ) | ||
| subprocess.run( | ||
| ["git", "config", "user.name", "Test"], | ||
| capture_output=True, cwd=tmp, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
init,doctor,status,validate,score,hookspip install -e .) withcortexavailable on PATHWhat this changes about CORTEX
pre-commithook blocks itcortex scorecomputes from evidencecortex statusshows everythingcortex doctorwith actionable reportpip install -e ./pyproject.tomlNew files (26 changed)
cli/— full CLI package (commands, core modules, hooks)pyproject.toml— Python package definitiontests/test_cli.py— 22 CLI testsTest plan
python tests/test_installer.py— 12/12 passingpython tests/test_cli.py— 22/22 passingpython -m cli validate— PASSpython -m cli --version— cortex 4.0.0🤖 Generated with Claude Code