Skip to content

fix: align flat command diagnostics#606

Merged
djm81 merged 491 commits into
mainfrom
bugfix/cli-removed-flat-alias-diagnostics
Jun 12, 2026
Merged

fix: align flat command diagnostics#606
djm81 merged 491 commits into
mainfrom
bugfix/cli-removed-flat-alias-diagnostics

Conversation

@djm81

@djm81 djm81 commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • remove stale flat alias diagnostics from the core CLI command suggestion path
  • preserve grouped command diagnostics for missing module bundles
  • quote Hatch pythonpath scripts so env manager paths with spaces work on macOS
  • bump specfact-cli to 0.47.5 and add the changelog entry
  • update validation docs away from removed flat command examples

Fixes #605.

Follow-up

The former plan backlog-edit verbs and project migrate rehome are tracked separately in nold-ai/specfact-cli-modules#317. The local OpenSpec draft for that follow-up is intentionally not included in this PR.

Validation

  • hatch run openspec validate cli-removed-flat-alias-diagnostics --strict
  • hatch run openspec validate tooling-spaced-env-pythonpath --strict
  • targeted tests: 28 passed, 2 skipped
  • hatch run type-check
  • hatch run lint
  • hatch run yaml-lint
  • hatch run check-version-sources
  • hatch run check-pypi-ahead

djm81 and others added 30 commits March 6, 2026 02:26
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* refactor: remove backlog ownership from core cli

* fix: align CI marketplace validation paths

* test: stabilize command audit validation and add command-surface change

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
# Conflicts:
#	openspec/CHANGE_ORDER.md
#	openspec/changes/module-migration-10-bundle-command-surface-alignment/proposal.md
* fix: finalize cli runtime validation regressions

* test: align satisfied dependency logging assertions

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat: add OpenSpec change for backlog-core commands migration

Change: backlog-02-migrate-core-commands
- Add proposal, design, tasks, specs
- Add TDD_EVIDENCE.md with implementation progress
- GitHub Issue: #389

Rules applied: AGENTS.md Git Worktree Policy, TDD Hard Gate

Made-with: Cursor

* docs: update TDD_EVIDENCE and tasks for quality gate results

Made-with: Cursor

* docs: update TDD_EVIDENCE with test fix results

Made-with: Cursor

* docs: update TDD_EVIDENCE with all test fixes complete

Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* fix: use POST instead of PATCH for ADO work item creation

Azure DevOps API requires POST (not PATCH) for creating work items.

Also fixed category grouping to always register group commands.

Made-with: Cursor

* docs: add changelog entry for ADO POST fix

Made-with: Cursor

* chore: bump version to 0.40.4

Made-with: Cursor

* fix: update test mocks from PATCH to POST for ADO create

- Reverted incorrect unconditional _mount_installed_category_groups call

- Updated test_create_issue mocks to use requests.post instead of requests.patch

Made-with: Cursor

* test: skip category group test when bundles not installed

The test_bootstrap_with_category_grouping_disabled_registers_flat_commands test

expects bundles like specfact-codebase to be installed, but in CI they may not be.

Added pytest.skip() when 'code' command is not available.

Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
- Archived backlog-02-migrate-core-commands change

- Updated CHANGE_ORDER.md with implementation status

- Updated main specs with backlog-add, backlog-analyze-deps, backlog-delta, backlog-sync, backlog-verify-readiness

Made-with: Cursor
* feat: document code-review module scaffold

* chore: sync 0.41.0 release version artifacts

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
* Realign code import ownership surface

* Harden temp registry command audit test

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Link the existing change issue, record TDD evidence, and align the OpenSpec artifacts with the bundle-owned DDL and paired worktree implementation flow.

Made-with: Cursor

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Made-with: Cursor

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* Track house-rules skill OpenSpec changes

Made-with: Cursor

* Cursor: Apply local changes for cloud agent

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
djm81 and others added 12 commits June 2, 2026 01:54
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Dom <39115308+djm81@users.noreply.github.com>
* Add clean code cleanup docs change

* docs: position SpecFact as AI-bloat defense CLI

* docs: address PR review wording

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
@strix-security

strix-security Bot commented Jun 9, 2026

Copy link
Copy Markdown

Strix is installed on this repository, but we could not run this PR security review because this workspace does not have an active plan. If you'd like to continue receiving code reviews, you can add a payment method or manage billing here.

@coderabbitai

coderabbitai Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

CLI Surface & User-Visible Behavior

  • Removed flat root aliases (validate, plan, analyze, drift, repro, sync, migrate) from root command diagnostic paths so invoking them (e.g., specfact validate --help) no longer emits module install/disabled/skipped/shadowed diagnostics; the CLI reports the command as removed/unknown and points to canonical grouped replacements when available.
  • Canonical grouped commands (e.g., specfact code validate, specfact project plan) remain module-aware and continue to show actionable missing-module diagnostics when appropriate.
  • Hatch gate scripts for type-check and lint now quote the --pythonpath interpreter substitution so environment-manager paths containing spaces (notably on macOS) are preserved.

Contract / API Impact

  • Internal refactor in src/specfact_cli/cli.py:
    • Removed deprecated flat-token → marketplace mappings for the deprecated aliases while preserving canonical group tokens (e.g., project, code family).
    • Introduced helpers and a patch function (_patch_missing_bundle_resolution, _resolve_root_command_with_guidance, _print_removed_flat_alias_help, _print_unresolved_root_token_help) to centralize root resolution/diagnostic guidance and ensure removed aliases do not participate in marketplace/module diagnostics.
    • Applied Click/Typer integration patches so root-group resolution emits the new guidance across Typer materialization surfaces.
  • No public function signatures, Pydantic models, or package-exported APIs were changed.

Testing & Quality Gates

  • Regression and unit testing:
    • tests/integration/test_category_group_routing.py: added parametrized test test_removed_flat_commands_do_not_report_shadowed_modules plus helper _install_shadowed_module_fixture to simulate dual-scope (project + user) module copies and assert removed aliases do not report shadowed/module diagnostics.
    • tests/integration/test_core_slimming.py: updated stale-flat-shim test to assert removed-alias guidance (contains “removed” and canonical group reference) and absence of install/shadow diagnostics.
    • tests/unit/packaging/test_core_package_includes.py: added test_hatch_gate_scripts_quote_pythonpath_interpreter_substitution to assert Hatch scripts quote --pythonpath substitutions.
    • tests/unit/registry/test_category_groups.py: relaxed conditional assertions around project/spec registration to avoid brittle coupling while still asserting absence of flat shims.
  • Quality gates performed: targeted tests (28 passed, 2 skipped), OpenSpec strict validation for the change passed; hatch runs for type-check, lint, yaml-lint, check-version-sources, and check-pypi-ahead completed for relevant changes.

Versioning, Changelog & Release Hygiene

  • Package version bumped to 0.47.6 across pyproject.toml, setup.py, src/init.py, and src/specfact_cli/init.py.
  • CHANGELOG.md updated with a 0.47.6 entry documenting removal of misleading flat-alias diagnostics, quoted Hatch pythonpath substitutions, and preserved canonical bundle diagnostics.

OpenSpec & Documentation

  • OpenSpec change ID: cli-removed-flat-alias-diagnostics
    • Includes proposal, spec, tasks, CHANGE_VALIDATION.md, and TDD_EVIDENCE.md; validation recorded as passing with no breaking changes detected.
    • OpenSpec scope documents the requirement that removed flat aliases not trigger marketplace/module-availability diagnostics and that canonical grouped command families remain module-aware.
  • Documentation updates:
    • docs/validation-integration.md: examples updated to reference canonical grouped validation paths (e.g., specfact code validate sidecar run) instead of removed flat commands.
    • docs/_config.yml: non-functional YAML formatting tweak.

Notes & Follow-ups

Walkthrough

Adds CLI root-token guidance to treat removed flat aliases as removed (not module diagnostics), quotes Hatch --pythonpath substitutions in gate scripts, updates tests and OpenSpec artifacts, and bumps package/version and changelog to 0.47.6.

Changes

CLI diagnostics & tooling fixes (0.47.6)

Layer / File(s) Summary
CLI root resolution & guidance patch
src/specfact_cli/cli.py, tests/integration/test_category_group_routing.py, tests/integration/test_core_slimming.py, tests/unit/registry/test_category_groups.py
Removes deprecated flat-alias mappings from known-bundle/module lookups, adds _REMOVED_FLAT_ALIAS_TO_CANONICAL and unified guidance helpers, centralizes resolution in _resolve_root_command_with_guidance, patches Typer/Click root Group get_command/resolve_command, and updates integration/unit tests to assert removed aliases produce removed/unknown guidance (no module shadow/install diagnostics).
Hatch interpreter-path quoting & packaging tests
pyproject.toml, tests/unit/packaging/test_core_package_includes.py, openspec/changes/tooling-spaced-env-pythonpath/*
Quotes --pythonpath "$(python -c '...')" in Hatch type-check/lint scripts, adds unit test verifying the quoted pattern and absence of unquoted variant, and records OpenSpec proposal/TDD evidence for the tooling fix.
OpenSpec artifacts and TDD/validation records
openspec/changes/cli-removed-flat-alias-diagnostics/*, openspec/changes/tooling-spaced-env-pythonpath/*
Adds proposal, spec, tasks, CHANGE_VALIDATION, and TDD evidence documenting validation, failing-before/passing-after artifacts, and regression/verification steps for both CLI diagnostic and tooling changes.
Release/version/docs updates
CHANGELOG.md, setup.py, pyproject.toml, src/__init__.py, src/specfact_cli/__init__.py, docs/validation-integration.md, docs/_config.yml
Bumps package/project version constants to 0.47.6, prepends a 0.47.6 changelog entry covering the three fixes, updates validation docs to reference the canonical grouped validation command, and reformats Jekyll description block.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant TyperRootGroup
  participant PatchResolver as _patch_missing_bundle_resolution
  participant Guidance as _resolve_root_command_with_guidance

  User->>TyperRootGroup: run root-token (e.g., `specfact validate --help`)
  TyperRootGroup->>PatchResolver: get_command / resolve_command (patched)
  PatchResolver->>Guidance: classify token (removed vs canonical)
  alt removed alias
    Guidance->>User: emit removed-alias guidance (mention canonical grouped command)
  else canonical bundle unresolved
    Guidance->>User: emit actionable missing-bundle/module guidance
  end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

Possibly related PRs

Suggested labels

QA

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed Title clearly summarizes main change: removing misleading flat alias diagnostics from CLI error paths while preserving grouped command diagnostics.
Description check ✅ Passed Description covers summary, fixes linked issue, validation gates run, and follow-up tracking; mostly complete though contract-first testing checklist sections remain unchecked.
Linked Issues check ✅ Passed Changes fully implement #605 objectives: removed flat aliases (validate, plan, analyze, drift, repro, sync, migrate) no longer produce module diagnostics [src/specfact_cli/cli.py, tests/integration/test_category_group_routing.py]; canonical commands preserve diagnostics [specs]; regression test includes shadowed-module fixture [test_category_group_routing.py]; OpenSpec validation documented [CHANGE_VALIDATION.md].
Out of Scope Changes check ✅ Passed All changes are scope-aligned: flat alias removal (cli.py, tests), pythonpath quoting (pyproject.toml, setup.py), version bumps (version artifacts), CHANGELOG/docs updates, and OpenSpec evidence—no unrelated code changes detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch bugfix/cli-removed-flat-alias-diagnostics

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

SpecFact CLI Validation Report

All validations passed!
Duration: 20.38s
Checks: 4 total (1 passed) (3 skipped)

@djm81 djm81 self-assigned this Jun 9, 2026
@djm81 djm81 added bug Something isn't working documentation Improvements or additions to documentation module-system Module system and registry marketplace Module marketplace features labels Jun 9, 2026
@djm81
djm81 marked this pull request as ready for review June 9, 2026 23:06

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 253e14c501

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/specfact_cli/cli.py Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md`:
- Line 52: In CHANGE_VALIDATION.md remove or redact the host-specific absolute
artifact path
`/Users/dom/.lean-ctx/tee/2026-06-09_232654_hatch_run_python_-m_pytest_tests_integra.log`
and replace it with a portable placeholder (e.g. `<ARTIFACT_LOG_PATH>`), a
relative path, or a sanitized example path to avoid leaking local
user/workstation identifiers; ensure the replacement preserves meaning for
validation evidence and update any nearby text that references the original
path.

In `@tests/integration/test_category_group_routing.py`:
- Around line 134-138: The test currently asserts a single exact phrase ("no
such command") in the variable output which is brittle; update the final
assertion to accept common wording variants by asserting that output matches any
of a small set of expected phrases (e.g., "no such command", "not a valid
command", "no such cmd", etc.) using a regex search (re.search) or an any(...)
over substrings and make it case-insensitive; keep the other assertions
unchanged and operate on the same variable name output.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d86e2ae3-f23b-4480-b7bd-1965613de87e

📥 Commits

Reviewing files that changed from the base of the PR and between b28ab20 and 253e14c.

📒 Files selected for processing (20)
  • CHANGELOG.md
  • docs/_config.yml
  • docs/validation-integration.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md
  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • pyproject.toml
  • setup.py
  • src/__init__.py
  • src/specfact_cli/__init__.py
  • src/specfact_cli/cli.py
  • tests/integration/test_category_group_routing.py
  • tests/unit/packaging/test_core_package_includes.py
  • tests/unit/registry/test_category_groups.py
🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

  • nold-ai/specfact-cli-modules (manual)
💤 Files with no reviewable changes (1)
  • tests/unit/registry/test_category_groups.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Tests (Python 3.12)
  • GitHub Check: Socket Security: Pull Request Alerts
🧰 Additional context used
📓 Path-based instructions (19)
**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/*.py: Maintain minimum 80% test coverage, with 100% coverage for critical paths in Python code
Use clear naming and self-documenting code, preferring clear names over comments
Ensure each function/class has a single clear purpose (Single Responsibility Principle)
Extract common patterns to avoid code duplication (DRY principle)
Apply SOLID object-oriented design principles in Python code
Use type hints everywhere in Python code and enable basedpyright strict mode
Use Pydantic models for data validation and serialization in Python
Use async/await for I/O operations in Python code
Use context managers for resource management in Python
Use dataclasses for simple data containers in Python
Enforce maximum line length of 120 characters in Python code
Use 4 spaces for indentation in Python code (no tabs)
Use 2 blank lines between classes and 1 blank line between methods in Python
Organize imports in order: Standard library → Third party → Local in Python files
Use snake_case for variables and functions in Python
Use PascalCase for class names in Python
Use UPPER_SNAKE_CASE for constants in Python
Use leading underscore (_) for private methods in Python classes
Use snake_case for Python file names
Enable basedpyright strict mode with strict type checking configuration in Python
Use Google-style docstrings for functions and classes in Python
Include comprehensive exception handling with specific exception types in Python code
Use logging with structured context (extra parameters) instead of print statements
Use retry logic with tenacity decorators (@retry) for operations that might fail
Use Pydantic BaseSettings for environment-based configuration in Python
Validate user input using Pydantic validators in Python models
Use @lru_cache and Redis-based caching for expensive calculations in Python
Run code formatting with Black (120 character line length) and isort in Python
Run type checking with basedpyright on all Python files
Run linting with ruff and pylint on all Pyth...

Files:

  • setup.py
  • src/__init__.py
  • src/specfact_cli/__init__.py
  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py
  • src/specfact_cli/cli.py
{src/__init__.py,pyproject.toml,setup.py}

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

{src/__init__.py,pyproject.toml,setup.py}: Update src/init.py first as primary source of truth for package version, then pyproject.toml and setup.py
Maintain version synchronization across src/init.py, pyproject.toml, and setup.py

Files:

  • setup.py
  • src/__init__.py
  • pyproject.toml
{pyproject.toml,setup.py,src/__init__.py}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Manually update version numbers in pyproject.toml, setup.py, and src/init.py when making a formal version change

Files:

  • setup.py
  • src/__init__.py
  • pyproject.toml
**/*.{py,pyi}

📄 CodeRabbit inference engine (.cursorrules)

**/*.{py,pyi}: After any code changes, follow these steps in order: (1) Apply linting and formatting to ensure code quality: hatch run format, (2) Type checking: hatch run type-check (basedpyright), (3) Contract-first approach: Run hatch run contract-test for contract validation, (4) Run full test suite: hatch test --cover -v, (5) Verify all tests pass and contracts are satisfied, (6) Fix any issues and repeat steps until all tests pass
All public APIs must have @icontract decorators and @beartype type checking
Use Pydantic models for all data structures with data validation
Only write high-value comments if at all. Avoid talking to the user through comments

Files:

  • setup.py
  • src/__init__.py
  • src/specfact_cli/__init__.py
  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py
  • src/specfact_cli/cli.py
src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

src/**/*.py: All code changes must be followed by running the full test suite using the smart test system.
All Python files in src/ and tools/ directories must have corresponding test files in tests/ directory. If you modify src/common/logger_setup.py, you MUST have tests/unit/common/test_logger_setup.py. NO EXCEPTIONS - even small changes require tests.
All new Python runtime code files must have corresponding test files created BEFORE committing the code. NO EXCEPTIONS - no code without tests.
Test Coverage Validation: Run hatch run smart-test-unit for modified files, hatch run smart-test-folder for modified directories, and hatch run smart-test-full before committing. ALL TESTS MUST PASS.
All components must support TEST_MODE=true environment variable with test-specific behavior defined as: if os.environ.get('TEST_MODE') == 'true': # test-specific behavior
Use src/common/logger_setup.py for all logging via: from common.logger_setup import get_logger; logger = get_logger(name)
Use src/common/redis_client.py with fallback for Redis operations via: from common.redis_client import get_redis_client; redis_client = get_redis_client()
Type checking must pass with no errors using: mypy .
Test coverage must meet or exceed 80% total coverage. New code must have corresponding tests. Modified code must maintain or improve coverage. Critical paths must have 100% coverage.
Use Pydantic v2 validation for all context and data schemas.

Add/update contracts on new or modified public APIs, stateful classes and adapters using icontract decorators and beartype runtime type checks

src/**/*.py: Meaningful Naming — identifiers reveal intent; avoid abbreviations. Identifiers in src/ must use snake_case (modules/functions), PascalCase (classes), UPPER_SNAKE_CASE (constants). Avoid single-letter names outside short loop variables.
KISS — keep functions and modules small and single-purpose. Maximum function length: 120 lines (Phase A error threshold). Maximum cyclomati...

Files:

  • src/__init__.py
  • src/specfact_cli/__init__.py
  • src/specfact_cli/cli.py
@(src|tests)/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Linting must pass with no errors using: pylint src tests

Files:

  • src/__init__.py
  • src/specfact_cli/__init__.py
  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py
  • src/specfact_cli/cli.py
src/specfact_cli/**/*.py

⚙️ CodeRabbit configuration file

src/specfact_cli/**/*.py: Focus on modular CLI architecture: lazy module loading, registry/bootstrap patterns, and
dependency direction. Flag breaking changes to public APIs, Pydantic models, and resource
bundling. Verify @icontract + @beartype on public surfaces; prefer centralized logging
(get_bridge_logger) over print().

Files:

  • src/specfact_cli/__init__.py
  • src/specfact_cli/cli.py
**/*.{md,mdc}

📄 CodeRabbit inference engine (.cursor/rules/markdown-rules.mdc)

**/*.{md,mdc}: Do not use more than one consecutive blank line anywhere in the document (MD012: No Multiple Consecutive Blank Lines)
Fenced code blocks should be surrounded by blank lines (MD031: Fenced Code Blocks)
Lists should be surrounded by blank lines (MD032: Lists)
Files must end with a single empty line (MD047: Files Must End With Single Newline)
Lines should not have trailing spaces (MD009: No Trailing Spaces)
Use asterisks (**) for strong emphasis, not underscores (__) (MD050: Strong Style)
Fenced code blocks must have a language specified (MD040: Fenced Code Language)
Headers should increment by one level at a time (MD001: Header Increment)
Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines)
Only one top-level header (H1) is allowed per document (MD025: Single H1 Header)
Use consistent list markers, preferring dashes (-) for unordered lists (MD004: List Style)
Nested unordered list items should be indented consistently, typically by 2 spaces (MD007: Unordered List Indentation)
Use exactly one space after the list marker (e.g., -, *, +, 1.) (MD030: Spaces After List Markers)
Use incrementing numbers for ordered lists (MD029: Ordered List Item Prefix)
Enclose bare URLs in angle brackets or format them as links (MD034: Bare URLs)
Don't use spaces immediately inside code spans (MD038: Spaces Inside Code Spans)
Use consistent indentation (usually 2 or 4 spaces) throughout markdown files
Keep line length under 120 characters in markdown files
Use reference-style links for better readability in markdown files
Use a trailing slash for directory paths in markdown files
Ensure proper escaping of special characters in markdown files

Files:

  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • docs/validation-integration.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
  • CHANGELOG.md
**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • docs/validation-integration.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
  • CHANGELOG.md
openspec/changes/**/*.md

📄 CodeRabbit inference engine (.cursorrules)

For /opsx:archive (Archive change): Include module signing and cleanup in final tasks. Agents MUST run openspec archive <change-id> from repo root (no manual mv under openspec/changes/archive/)

Files:

  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
openspec/**/{proposal.md,tasks.md,design.md,spec.md}

📄 CodeRabbit inference engine (.cursor/rules/automatic-openspec-workflow.mdc)

openspec/**/{proposal.md,tasks.md,design.md,spec.md}: Apply openspec/config.yaml project context and per-artifact rules (for proposal, specs, design, tasks) when creating or updating any OpenSpec change artifact in the specfact-cli codebase
After implementation, validate the change with openspec validate <change-id> --strict; fix validation errors in proposal, specs, design, or tasks and re-validate until passing before considering the change complete

Files:

  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
openspec/**/*.md

⚙️ CodeRabbit configuration file

openspec/**/*.md: Treat as specification source of truth: proposal/tasks/spec deltas vs. code behavior,
CHANGE_ORDER consistency, and scenario coverage. Surface drift between OpenSpec and
implementation.

Files:

  • openspec/changes/tooling-spaced-env-pythonpath/proposal.md
  • openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/tasks.md
  • openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md
**/*.{yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Validate YAML configuration files locally using hatch run yaml-lint before committing

**/*.{yml,yaml}: Format all YAML and workflow files using hatch run yaml-fix-all before committing
Use Prettier to fix whitespace, indentation, and final newline across YAML files
Use yamllint with the repo .yamllint configuration (line-length 140, trailing spaces and final newline enforced) to lint non-workflow YAML files

Files:

  • docs/_config.yml
docs/**/*.md

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Update architecture documentation in docs/ for architecture changes, state machine documentation for FSM modifications, interface documentation for API changes, and configuration guides for configuration changes. DO NOT create internal docs in specfact-cli repo folder that should not be visible to end users; use the respective internal repository instead.

Files:

  • docs/validation-integration.md

⚙️ CodeRabbit configuration file

docs/**/*.md: User-facing accuracy: CLI examples match current behavior; preserve Jekyll front matter;
call out when README/docs index need sync.

Files:

  • docs/validation-integration.md
**/test_*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/test_*.py: Write tests first in test-driven development (TDD) using the Red-Green-Refactor cycle
Ensure each test is independent and repeatable with no shared state between tests
Organize Python imports in tests using unittest.mock for Mock and patch
Use setup_method() for test initialization and Arrange-Act-Assert pattern in test files
Use @pytest.mark.asyncio decorator for async test functions in Python
Organize test files in structure: tests/unit/, tests/integration/, tests/e2e/ by module

Files:

  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py
tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Tests must be meaningful and test actual functionality, cover both success and failure cases, be independent and repeatable, and have clear, descriptive names. NO EXCEPTIONS - no placeholder or empty tests.

tests/**/*.py: Trim low-value unit tests when a contract covers the same assertion (type/shape/raises on negative checks)
Delete tests that only assert input validation, datatype/shape enforcement, or raises on negative conditions now guarded by contracts and runtime typing
Convert repeated edge-case permutations into one Hypothesis property with contracts acting as oracles

Secret redaction via LoggerSetup.redact_secrets must be covered by unit tests

Files:

  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py

⚙️ CodeRabbit configuration file

tests/**/*.py: Contract-first testing: meaningful scenarios, not redundant assertions already covered by
contracts. Flag flakiness, environment coupling, and missing coverage for changed behavior.

Files:

  • tests/unit/packaging/test_core_package_includes.py
  • tests/integration/test_category_group_routing.py
CHANGELOG.md

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

Include new version entries at the top of CHANGELOG.md when updating versions

Update CHANGELOG.md with all code changes as part of version control requirements.

Update CHANGELOG.md to document all significant changes under Added, Fixed, Changed, or Removed sections when making a version change

Files:

  • CHANGELOG.md
pyproject.toml

📄 CodeRabbit inference engine (.cursorrules)

When updating the version in pyproject.toml, ensure it's newer than the latest PyPI version. The CI/CD pipeline will automatically publish to PyPI only if the new version is greater than the published version

Files:

  • pyproject.toml
**/*cli*.{py,pyi}

📄 CodeRabbit inference engine (.cursorrules)

Commands should follow typer patterns with rich console output

Files:

  • src/specfact_cli/cli.py
🔀 Multi-repo context nold-ai/specfact-cli-modules

nold-ai/specfact-cli-modules

  • docs bundles reference removed flat verbs (affects user guidance/examples):

    • docs/bundles/spec/validate.md — mentions specfact validate examples. [::nold-ai/specfact-cli-modules::docs/bundles/spec/validate.md]
    • docs/bundles/codebase/plan.md / docs/bundles/codebase/repro.md / docs/bundles/codebase/drift.md / docs/bundles/codebase/analyze.md — bundle docs referencing plan/repro/drift/analyze verbs. [::nold-ai/specfact-cli-modules::docs/bundles/codebase/overview.md] (see related bundle files listed in tree)
    • docs/reference/commands.md and docs/reference/commands.generated.md — command docs present many flat-token mentions (search hits across docs). [::nold-ai/specfact-cli-modules::docs/reference/commands.md]
  • Tests and scripts that reference flat aliases and command-path expectations (potentially need updates or confirm compatibility with PR behavior):

    • tests/unit/test_specfact_project_manifest_commands.py — asserts "plan" in commands. [::nold-ai/specfact-cli-modules::tests/unit/test_specfact_project_manifest_commands.py]
    • tests/unit/test_global_cli_error_contract.py — asserts "analyze" present in CLI error contract output. [::nold-ai/specfact-cli-modules::tests/unit/test_global_cli_error_contract.py]
    • tests/unit/test_check_prompt_commands_script.py — contains multiple assertions ensuring removed flat prefixes (e.g., ("specfact","sync"), ("specfact","plan"), ("specfact","migrate")) are not present and validates prompt examples referencing flat commands. [::nold-ai/specfact-cli-modules::tests/unit/test_check_prompt_commands_script.py]
    • tests/unit/test_bundle_resource_payloads.py — includes resource filenames like specfact.validate.md, specfact.02-plan.md, specfact.06-sync.md. These resource artifacts reference flat command examples. [::nold-ai/specfact-cli-modules::tests/unit/test_bundle_resource_payloads.py]
  • Tools/validation scripts that may surface CLI expectations:

    • tools/validate_cli_contracts.py — used to validate CLI contract scenarios (mentions validate). Changes in CLI diagnostics could affect its outputs. [::nold-ai/specfact-cli-modules::tools/validate_cli_contracts.py]

Summary assessment

  • This repository contains multiple docs, tests, and resource files that reference the flat aliases removed by the PR (validate, plan, analyze, drift, repro, sync, migrate). They are likely consumers of CLI surface/diagnostic behavior and should be audited to ensure examples/tests align with the new behavior (e.g., removed aliases reporting "no such command" rather than module diagnostics) and to update examples that previously used flat aliases.
🔇 Additional comments (16)
openspec/changes/tooling-spaced-env-pythonpath/proposal.md (1)

1-26: LGTM!

openspec/changes/tooling-spaced-env-pythonpath/specs/trustworthy-green-checks/spec.md (1)

1-19: LGTM!

openspec/changes/tooling-spaced-env-pythonpath/tasks.md (1)

1-21: LGTM!

pyproject.toml (3)

7-7: LGTM!


227-227: LGTM!


229-229: LGTM!

tests/unit/packaging/test_core_package_includes.py (1)

125-134: LGTM!

openspec/changes/tooling-spaced-env-pythonpath/TDD_EVIDENCE.md (1)

1-17: LGTM!

openspec/changes/cli-removed-flat-alias-diagnostics/proposal.md (1)

1-40: LGTM!

openspec/changes/cli-removed-flat-alias-diagnostics/specs/cli-error-guidance/spec.md (1)

1-28: LGTM!

openspec/changes/cli-removed-flat-alias-diagnostics/tasks.md (1)

1-28: LGTM!

src/specfact_cli/cli.py (1)

187-230: LGTM!

Also applies to: 901-903, 931-933

setup.py (1)

10-10: Verify 0.47.5 version synchronization and CHANGELOG entry

  • pyproject.toml, setup.py, src/__init__.py, and src/specfact_cli/__init__.py all specify version 0.47.5.
  • CHANGELOG.md contains a ## [0.47.5] - 2026-06-10 entry, with related fixes listed.
CHANGELOG.md (1)

13-30: LGTM!

docs/_config.yml (1)

5-8: LGTM!

docs/validation-integration.md (1)

27-27: Keep specfact code validate sidecar run as the canonical command; align module docs/tests to the new no-flat-alias behavior.

docs/validation-integration.md line 27 now correctly uses the grouped/canonical OpenSpec validation command (specfact code validate sidecar run), avoiding stale flat-alias guidance.

In nold-ai/specfact-cli-modules, earlier findings show still-stale flat-alias references that should be updated/rewired alongside this PR (e.g., docs/bundles/spec/validate.md, docs/bundles/codebase/{plan,repro,drift,analyze}.md, and unit checks like tests/unit/test_check_prompt_commands_script.py / CLI error-contract expectations). Ensure these changes are fully tracked in nold-ai/specfact-cli-modules#317 (or coordinate a separate follow-up if anything is missing).

Comment thread openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md Outdated
Comment thread tests/integration/test_category_group_routing.py Outdated
- Removed flat root aliases (validate, plan, analyze, drift, repro, sync,
  migrate) now report 'No such command' with guidance to their canonical
  grouped replacement on all three root resolution surfaces (_RootCLIGroup,
  patched Typer root group, lazy delegate loader), per the
  cli-error-guidance spec scenario.
- Deduplicate the root resolve/diagnostic logic into
  _resolve_root_command_with_guidance and _print_unresolved_root_token_help.
- Update stale test test_stale_flat_shim_plan_exits_with_install_instructions
  (renamed ..._removed_alias_guidance) that caused the CI failures on
  Python 3.11/3.12; harden the shadowed-module regression assertions against
  unknown-command wording variants and assert canonical guidance.
- Redact host-specific absolute paths from OpenSpec validation evidence.
- Bump version artifacts to 0.47.6 with changelog entry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

SpecFact CLI Validation Report

All validations passed!
Duration: 20.04s
Checks: 4 total (1 passed) (3 skipped)

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
tests/integration/test_core_slimming.py (1)

172-183: 💤 Low value

Test name/docstring may be stale after diagnostic behavior change.

This test will pass because "plan" appears in the output, but the test name "exits_with_not_found_or_install_instructions" no longer accurately describes the new behavior. With _REMOVED_FLAT_ALIAS_TO_CANONICAL, "plan" now shows "removed" guidance pointing to specfact project, not install instructions.

Consider renaming this test in a follow-up to align with test_stale_flat_shim_plan_exits_with_removed_alias_guidance or tightening assertions to explicitly verify "removed" and "project" are present.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/integration/test_core_slimming.py` around lines 172 - 183, The test
test_flat_shim_plan_exits_with_not_found_or_install_instructions no longer
matches behavior after the _REMOVED_FLAT_ALIAS_TO_CANONICAL change; update it by
either renaming it to
test_stale_flat_shim_plan_exits_with_removed_alias_guidance or tightening its
assertions to assert that result.exit_code != 0 and that the output contains the
keywords "removed" and "project" (or explicit guidance text pointing to
`specfact project`) instead of the previous "not installed"/"install" checks so
the test reflects the new removed-alias messaging.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/integration/test_core_slimming.py`:
- Around line 172-183: The test
test_flat_shim_plan_exits_with_not_found_or_install_instructions no longer
matches behavior after the _REMOVED_FLAT_ALIAS_TO_CANONICAL change; update it by
either renaming it to
test_stale_flat_shim_plan_exits_with_removed_alias_guidance or tightening its
assertions to assert that result.exit_code != 0 and that the output contains the
keywords "removed" and "project" (or explicit guidance text pointing to
`specfact project`) instead of the previous "not installed"/"install" checks so
the test reflects the new removed-alias messaging.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cd5aa7b8-80c4-4604-90c5-725912b4b416

📥 Commits

Reviewing files that changed from the base of the PR and between 253e14c and 817d5cd.

📒 Files selected for processing (10)
  • CHANGELOG.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
  • pyproject.toml
  • setup.py
  • src/__init__.py
  • src/specfact_cli/__init__.py
  • src/specfact_cli/cli.py
  • tests/integration/test_category_group_routing.py
  • tests/integration/test_core_slimming.py
🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

  • nold-ai/specfact-cli-modules (manual)
✅ Files skipped from review due to trivial changes (4)
  • openspec/changes/cli-removed-flat-alias-diagnostics/CHANGE_VALIDATION.md
  • src/specfact_cli/init.py
  • src/init.py
  • openspec/changes/cli-removed-flat-alias-diagnostics/TDD_EVIDENCE.md
🚧 Files skipped from review as they are similar to previous changes (2)
  • setup.py
  • tests/integration/test_category_group_routing.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
  • GitHub Check: Linting (ruff, pylint, safe-write guard)
  • GitHub Check: Type Checking (basedpyright)
  • GitHub Check: Tests (Python 3.12)
  • GitHub Check: Compatibility (Python 3.11)
  • GitHub Check: CLI Command Validation
  • GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (14)
**/*.{md,mdc}

📄 CodeRabbit inference engine (.cursor/rules/markdown-rules.mdc)

**/*.{md,mdc}: Do not use more than one consecutive blank line anywhere in the document (MD012: No Multiple Consecutive Blank Lines)
Fenced code blocks should be surrounded by blank lines (MD031: Fenced Code Blocks)
Lists should be surrounded by blank lines (MD032: Lists)
Files must end with a single empty line (MD047: Files Must End With Single Newline)
Lines should not have trailing spaces (MD009: No Trailing Spaces)
Use asterisks (**) for strong emphasis, not underscores (__) (MD050: Strong Style)
Fenced code blocks must have a language specified (MD040: Fenced Code Language)
Headers should increment by one level at a time (MD001: Header Increment)
Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines)
Only one top-level header (H1) is allowed per document (MD025: Single H1 Header)
Use consistent list markers, preferring dashes (-) for unordered lists (MD004: List Style)
Nested unordered list items should be indented consistently, typically by 2 spaces (MD007: Unordered List Indentation)
Use exactly one space after the list marker (e.g., -, *, +, 1.) (MD030: Spaces After List Markers)
Use incrementing numbers for ordered lists (MD029: Ordered List Item Prefix)
Enclose bare URLs in angle brackets or format them as links (MD034: Bare URLs)
Don't use spaces immediately inside code spans (MD038: Spaces Inside Code Spans)
Use consistent indentation (usually 2 or 4 spaces) throughout markdown files
Keep line length under 120 characters in markdown files
Use reference-style links for better readability in markdown files
Use a trailing slash for directory paths in markdown files
Ensure proper escaping of special characters in markdown files

Files:

  • CHANGELOG.md
CHANGELOG.md

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

Include new version entries at the top of CHANGELOG.md when updating versions

Update CHANGELOG.md with all code changes as part of version control requirements.

Update CHANGELOG.md to document all significant changes under Added, Fixed, Changed, or Removed sections when making a version change

Files:

  • CHANGELOG.md
**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

  • CHANGELOG.md
{src/__init__.py,pyproject.toml,setup.py}

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

{src/__init__.py,pyproject.toml,setup.py}: Update src/init.py first as primary source of truth for package version, then pyproject.toml and setup.py
Maintain version synchronization across src/init.py, pyproject.toml, and setup.py

Files:

  • pyproject.toml
{pyproject.toml,setup.py,src/__init__.py}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Manually update version numbers in pyproject.toml, setup.py, and src/init.py when making a formal version change

Files:

  • pyproject.toml
pyproject.toml

📄 CodeRabbit inference engine (.cursorrules)

When updating the version in pyproject.toml, ensure it's newer than the latest PyPI version. The CI/CD pipeline will automatically publish to PyPI only if the new version is greater than the published version

Files:

  • pyproject.toml
**/test_*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/test_*.py: Write tests first in test-driven development (TDD) using the Red-Green-Refactor cycle
Ensure each test is independent and repeatable with no shared state between tests
Organize Python imports in tests using unittest.mock for Mock and patch
Use setup_method() for test initialization and Arrange-Act-Assert pattern in test files
Use @pytest.mark.asyncio decorator for async test functions in Python
Organize test files in structure: tests/unit/, tests/integration/, tests/e2e/ by module

Files:

  • tests/integration/test_core_slimming.py
**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/*.py: Maintain minimum 80% test coverage, with 100% coverage for critical paths in Python code
Use clear naming and self-documenting code, preferring clear names over comments
Ensure each function/class has a single clear purpose (Single Responsibility Principle)
Extract common patterns to avoid code duplication (DRY principle)
Apply SOLID object-oriented design principles in Python code
Use type hints everywhere in Python code and enable basedpyright strict mode
Use Pydantic models for data validation and serialization in Python
Use async/await for I/O operations in Python code
Use context managers for resource management in Python
Use dataclasses for simple data containers in Python
Enforce maximum line length of 120 characters in Python code
Use 4 spaces for indentation in Python code (no tabs)
Use 2 blank lines between classes and 1 blank line between methods in Python
Organize imports in order: Standard library → Third party → Local in Python files
Use snake_case for variables and functions in Python
Use PascalCase for class names in Python
Use UPPER_SNAKE_CASE for constants in Python
Use leading underscore (_) for private methods in Python classes
Use snake_case for Python file names
Enable basedpyright strict mode with strict type checking configuration in Python
Use Google-style docstrings for functions and classes in Python
Include comprehensive exception handling with specific exception types in Python code
Use logging with structured context (extra parameters) instead of print statements
Use retry logic with tenacity decorators (@retry) for operations that might fail
Use Pydantic BaseSettings for environment-based configuration in Python
Validate user input using Pydantic validators in Python models
Use @lru_cache and Redis-based caching for expensive calculations in Python
Run code formatting with Black (120 character line length) and isort in Python
Run type checking with basedpyright on all Python files
Run linting with ruff and pylint on all Pyth...

Files:

  • tests/integration/test_core_slimming.py
  • src/specfact_cli/cli.py
tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Tests must be meaningful and test actual functionality, cover both success and failure cases, be independent and repeatable, and have clear, descriptive names. NO EXCEPTIONS - no placeholder or empty tests.

tests/**/*.py: Trim low-value unit tests when a contract covers the same assertion (type/shape/raises on negative checks)
Delete tests that only assert input validation, datatype/shape enforcement, or raises on negative conditions now guarded by contracts and runtime typing
Convert repeated edge-case permutations into one Hypothesis property with contracts acting as oracles

Secret redaction via LoggerSetup.redact_secrets must be covered by unit tests

Files:

  • tests/integration/test_core_slimming.py

⚙️ CodeRabbit configuration file

tests/**/*.py: Contract-first testing: meaningful scenarios, not redundant assertions already covered by
contracts. Flag flakiness, environment coupling, and missing coverage for changed behavior.

Files:

  • tests/integration/test_core_slimming.py
@(src|tests)/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Linting must pass with no errors using: pylint src tests

Files:

  • tests/integration/test_core_slimming.py
  • src/specfact_cli/cli.py
**/*.{py,pyi}

📄 CodeRabbit inference engine (.cursorrules)

**/*.{py,pyi}: After any code changes, follow these steps in order: (1) Apply linting and formatting to ensure code quality: hatch run format, (2) Type checking: hatch run type-check (basedpyright), (3) Contract-first approach: Run hatch run contract-test for contract validation, (4) Run full test suite: hatch test --cover -v, (5) Verify all tests pass and contracts are satisfied, (6) Fix any issues and repeat steps until all tests pass
All public APIs must have @icontract decorators and @beartype type checking
Use Pydantic models for all data structures with data validation
Only write high-value comments if at all. Avoid talking to the user through comments

Files:

  • tests/integration/test_core_slimming.py
  • src/specfact_cli/cli.py
src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

src/**/*.py: All code changes must be followed by running the full test suite using the smart test system.
All Python files in src/ and tools/ directories must have corresponding test files in tests/ directory. If you modify src/common/logger_setup.py, you MUST have tests/unit/common/test_logger_setup.py. NO EXCEPTIONS - even small changes require tests.
All new Python runtime code files must have corresponding test files created BEFORE committing the code. NO EXCEPTIONS - no code without tests.
Test Coverage Validation: Run hatch run smart-test-unit for modified files, hatch run smart-test-folder for modified directories, and hatch run smart-test-full before committing. ALL TESTS MUST PASS.
All components must support TEST_MODE=true environment variable with test-specific behavior defined as: if os.environ.get('TEST_MODE') == 'true': # test-specific behavior
Use src/common/logger_setup.py for all logging via: from common.logger_setup import get_logger; logger = get_logger(name)
Use src/common/redis_client.py with fallback for Redis operations via: from common.redis_client import get_redis_client; redis_client = get_redis_client()
Type checking must pass with no errors using: mypy .
Test coverage must meet or exceed 80% total coverage. New code must have corresponding tests. Modified code must maintain or improve coverage. Critical paths must have 100% coverage.
Use Pydantic v2 validation for all context and data schemas.

Add/update contracts on new or modified public APIs, stateful classes and adapters using icontract decorators and beartype runtime type checks

src/**/*.py: Meaningful Naming — identifiers reveal intent; avoid abbreviations. Identifiers in src/ must use snake_case (modules/functions), PascalCase (classes), UPPER_SNAKE_CASE (constants). Avoid single-letter names outside short loop variables.
KISS — keep functions and modules small and single-purpose. Maximum function length: 120 lines (Phase A error threshold). Maximum cyclomati...

Files:

  • src/specfact_cli/cli.py
**/*cli*.{py,pyi}

📄 CodeRabbit inference engine (.cursorrules)

Commands should follow typer patterns with rich console output

Files:

  • src/specfact_cli/cli.py
src/specfact_cli/**/*.py

⚙️ CodeRabbit configuration file

src/specfact_cli/**/*.py: Focus on modular CLI architecture: lazy module loading, registry/bootstrap patterns, and
dependency direction. Flag breaking changes to public APIs, Pydantic models, and resource
bundling. Verify @icontract + @beartype on public surfaces; prefer centralized logging
(get_bridge_logger) over print().

Files:

  • src/specfact_cli/cli.py
🔀 Multi-repo context nold-ai/specfact-cli-modules

nold-ai/specfact-cli-modules

  • Documentation references removed flat verbs (examples or command lists):

    • docs/bundles/spec/validate.md — contains examples mentioning specfact validate and flat usage. [::nold-ai/specfact-cli-modules::docs/bundles/spec/validate.md]
    • docs/bundles/codebase/analyze.md, docs/bundles/codebase/drift.md, docs/bundles/codebase/repro.md — bundle docs reference code analyze, code drift, code repro and related flat examples (search hits for flat verbs present). [::nold-ai/specfact-cli-modules::docs/bundles/codebase/analyze.md] [::nold-ai/specfact-cli-modules::docs/bundles/codebase/drift.md] [::nold-ai/specfact-cli-modules::docs/bundles/codebase/repro.md]
    • docs/reference/commands.md and docs/reference/commands.generated.md — command reference and generated command overview include many flat-token mentions and mapping rows (e.g., lists of top-level commands and examples). [::nold-ai/specfact-cli-modules::docs/reference/commands.md] [::nold-ai/specfact-cli-modules::docs/reference/commands.generated.md]
  • Tests and test utilities that reference flat aliases or assert CLI contract details (may need updating to align with new removed-alias guidance):

    • tests/unit/test_specfact_project_manifest_commands.py — asserts plan is present in module manifest commands. [::nold-ai/specfact-cli-modules::tests/unit/test_specfact_project_manifest_commands.py]
    • tests/unit/test_global_cli_error_contract.py — contains assertions expecting analyze in CLI error output. [::nold-ai/specfact-cli-modules::tests/unit/test_global_cli_error_contract.py]
    • tests/unit/test_check_prompt_commands_script.py — validates prompt examples and includes expectations for flat verbs (e.g., specfact.validate, specfact repro, specfact sync). [::nold-ai/specfact-cli-modules::tests/unit/test_check_prompt_commands_script.py]
    • tests/unit/test_bundle_resource_payloads.py — includes resource filenames and prompt artifacts named after flat commands (e.g., specfact.validate.md, specfact.02-plan.md). [::nold-ai/specfact-cli-modules::tests/unit/test_bundle_resource_payloads.py]
    • tests reference package manifests under packages/* (the project manifest test reads packages/specfact-project/module-package.yaml). These manifests may list flat commands. [::nold-ai/specfact-cli-modules::packages/specfact-project/module-package.yaml]
  • Scripts/tools that index or validate CLI contracts and prompt examples (consumers of CLI command surface):

    • scripts/check-prompt-commands.py — extracts prompt command examples and validates them against a command index; will surface differences in removed vs module-diagnostic behavior. [::nold-ai/specfact-cli-modules::scripts/check-prompt-commands.py]
    • tools/validate_cli_contracts.py — used to validate CLI contract scenarios (may need re-run/adjustment after CLI diagnostic behavior changes). [::nold-ai/specfact-cli-modules::tools/validate_cli_contracts.py]

Notes / quick implication:

  • Multiple docs, prompt resources, tests, and validation scripts in this repo reference the flat aliases removed by the PR (validate, plan, analyze, drift, repro, sync, migrate). These are likely to need edits to examples, test expectations, or validation tooling to reflect that flat aliases now produce "removed/unknown" guidance instead of module-install/shadow diagnostics.
  • The prompt-checking and CLI-contract validation tooling are direct consumers of the CLI surface and should be re-run/adjusted to avoid false positives from the new guidance behavior.
🔇 Additional comments (11)
CHANGELOG.md (1)

13-24: LGTM!

pyproject.toml (2)

227-229: LGTM!


7-7: Version synchronization looks correct at 0.47.6

pyproject.toml / setup.py / src/__init__.py / src/specfact_cli/__init__.py all report 0.47.6, so the packaging version sources are aligned and safe.

src/specfact_cli/cli.py (7)

115-125: LGTM!


169-177: LGTM!


180-188: LGTM!


191-212: LGTM!


219-220: LGTM!


231-238: LGTM!


624-632: LGTM!

tests/integration/test_core_slimming.py (1)

186-212: LGTM!

@djm81
djm81 merged commit ed6d23a into main Jun 12, 2026
48 checks passed
@coderabbitai coderabbitai Bot mentioned this pull request Jul 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation marketplace Module marketplace features module-system Module system and registry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Change] Remove flat alias module diagnostics from root CLI errors

1 participant