docs: align flat command references#318
Conversation
|
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. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (9)
🔗 Linked repositories identifiedCodeRabbit considers these linked repositories for cross-repo context during reviews:
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (5)
📜 Recent review details🧰 Additional context used📓 Path-based instructions (1)packages/**/module-package.yaml⚙️ CodeRabbit configuration file
Files:
🔀 Multi-repo context nold-ai/specfact-cliLinked repositories findingsnold-ai/specfact-cli
Conclusion: I found cross-repo context that is directly relevant — widespread 🔇 Additional comments (3)
📝 WalkthroughPR Summary: Align Flat Command ReferencesBundle & Module Surface ChangesModule Manifests & Semver Bumps
All bumps are patch-level. Integrity checksums and signatures have been regenerated in CI to match updated artifact content. Command Surface Realignment
Module docstrings now explicitly state that Commands & Adapters Impactedspecfact-spec (
specfact-project (
specfact-codebase (
specfact-govern (
Documentation & Cross-Repo AlignmentContract Alignment: All help text and prompt examples now conform to the current namespaced CLI structure. No functional logic changes; this is purely help/example text realignment. Registry Impact: 6 module versions are incremented and signature-verified. These changes should propagate to the registry without functional consequences (help text only). No breaking API changes to exported function signatures or command wiring. CLI Relationship: The PR assumes specfact-cli has already removed the flat command shims (per specfact-cli#605). Embedded examples now consistently direct users to the new command namespaces. No new CLI dependencies introduced; only documented guidance changes. Testing & Validation
Dep & Fixture ChangesRemoved SummaryThis PR completes the documentation alignment for the flat command shim removal. All embedded command examples and user-facing error/guidance messages now reference the correct namespaced forms ( WalkthroughSix module manifests are patch-bumped and integrity metadata refreshed; CLI help text, examples, and user-facing guidance are normalized to bundle-oriented namespaces and authoritative ChangesRelease messaging and module version updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
djm81
added
bug
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 16b817c96c
ℹ️ 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".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@packages/specfact-spec/src/specfact_spec/generate/commands.py`:
- Around line 526-542: Update all remaining legacy flat command references in
user-facing help/flow text to the namespaced forms; specifically replace
occurrences like "specfact generate contracts-prompt" and "specfact sdd ..."
with "specfact spec generate contracts-prompt" and "specfact spec sdd ..." in
the prompt/help templates and remediation strings (the Complete Workflow block
and any example command lines shown). Locate the strings used to render
interactive/help text in this module (e.g., the Complete Workflow text and
individual example command lines such as the ones showing "specfact generate
contracts-prompt --bundle legacy-api --apply beartype") and standardize them to
the current namespaced CLI (and update any accompanying comments or inline hints
such as "--no-interactive" examples) so all user-facing command samples are
consistent with the new "specfact spec ..." namespace.
🪄 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: 44e5ba64-3478-4fe8-91b0-cd144ee4228a
📒 Files selected for processing (19)
packages/specfact-backlog/module-package.yamlpackages/specfact-code-review/module-package.yamlpackages/specfact-codebase/module-package.yamlpackages/specfact-codebase/src/specfact_codebase/analyze/commands.pypackages/specfact-codebase/src/specfact_codebase/drift/commands.pypackages/specfact-codebase/src/specfact_codebase/import_cmd/commands.pypackages/specfact-codebase/src/specfact_codebase/repro/commands.pypackages/specfact-govern/module-package.yamlpackages/specfact-govern/src/specfact_govern/enforce/commands.pypackages/specfact-project/module-package.yamlpackages/specfact-project/src/specfact_project/import_cmd/commands.pypackages/specfact-project/src/specfact_project/sync/commands.pypackages/specfact-project/src/specfact_project/sync_runtime/sync_perform_operation_impl.pypackages/specfact-spec/module-package.yamlpackages/specfact-spec/src/specfact_spec/generate/commands.pypackages/specfact-spec/src/specfact_spec/sdd/commands.pypackages/specfact-spec/src/specfact_spec/spec/commands.pytests/unit/sync_runtime/test_bridge_sync.pytests/unit/sync_runtime/test_drift_detector.py
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
nold-ai/specfact-cli(manual)
💤 Files with no reviewable changes (2)
- tests/unit/sync_runtime/test_bridge_sync.py
- tests/unit/sync_runtime/test_drift_detector.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
packages/**/module-package.yaml
⚙️ CodeRabbit configuration file
packages/**/module-package.yaml: Validate metadata: name, version, commands, dependencies, and parity with packaged src.
Call out semver and signing implications when manifests or payloads change.
Files:
packages/specfact-code-review/module-package.yamlpackages/specfact-backlog/module-package.yamlpackages/specfact-codebase/module-package.yamlpackages/specfact-govern/module-package.yamlpackages/specfact-spec/module-package.yamlpackages/specfact-project/module-package.yaml
**/*.{js,ts,tsx,jsx,py,java,cs,go,rb,php,cpp,c,h}
📄 CodeRabbit inference engine (CLAUDE.md)
Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Files:
packages/specfact-codebase/src/specfact_codebase/import_cmd/commands.pypackages/specfact-project/src/specfact_project/sync_runtime/sync_perform_operation_impl.pypackages/specfact-codebase/src/specfact_codebase/drift/commands.pypackages/specfact-spec/src/specfact_spec/spec/commands.pypackages/specfact-codebase/src/specfact_codebase/analyze/commands.pypackages/specfact-codebase/src/specfact_codebase/repro/commands.pypackages/specfact-project/src/specfact_project/sync/commands.pypackages/specfact-spec/src/specfact_spec/sdd/commands.pypackages/specfact-govern/src/specfact_govern/enforce/commands.pypackages/specfact-project/src/specfact_project/import_cmd/commands.pypackages/specfact-spec/src/specfact_spec/generate/commands.py
packages/**/src/**/*.py
⚙️ CodeRabbit configuration file
packages/**/src/**/*.py: Focus on adapter and bridge patterns: imports from specfact_cli (models, runtime, validators),
Typer/Rich command surfaces, and clear boundaries so core upgrades do not silently break bundles.
Flag breaking assumptions about registry loading, lazy imports, and environment/mode behavior.
Files:
packages/specfact-codebase/src/specfact_codebase/import_cmd/commands.pypackages/specfact-project/src/specfact_project/sync_runtime/sync_perform_operation_impl.pypackages/specfact-codebase/src/specfact_codebase/drift/commands.pypackages/specfact-spec/src/specfact_spec/spec/commands.pypackages/specfact-codebase/src/specfact_codebase/analyze/commands.pypackages/specfact-codebase/src/specfact_codebase/repro/commands.pypackages/specfact-project/src/specfact_project/sync/commands.pypackages/specfact-spec/src/specfact_spec/sdd/commands.pypackages/specfact-govern/src/specfact_govern/enforce/commands.pypackages/specfact-project/src/specfact_project/import_cmd/commands.pypackages/specfact-spec/src/specfact_spec/generate/commands.py
🔀 Multi-repo context nold-ai/specfact-cli
nold-ai/specfact-cli
-
Legacy flat command references found:
- docs/reference/commands.md: table shows "
specfact sdd ...| Removed — usespecfact govern enforce sdd [BUNDLE]" and "specfact repro ...|specfact code repro ..." entries. [::nold-ai/specfact-cli::docs/reference/commands.md:152,154] - docs/migration/migration-cli-reorganization.md: multiple examples still referencing
specfact sdd ...(constitution examples). [::nold-ai/specfact-cli::docs/migration/migration-cli-reorganization.md:166-218,231,239,256] - CHANGELOG.md: many historical entries documenting moves from flat commands to namespaced forms (multiple lines). [::nold-ai/specfact-cli::CHANGELOG.md:2574,2632,2634-2636,2698,2746,2751,4031,4048,4076,4048]
- openspec archive and tasks files reference
specfact sddmigration and tests. [::nold-ai/specfact-cli::openspec/changes/archive/2026-01-02-refactor-speckit-to-bridge-adapter/*]
- docs/reference/commands.md: table shows "
-
Remaining direct code/script reference to deprecated guidance:
- scripts/cleanup_acceptance_criteria.py: error message contains "Please specify bundle name or run 'specfact plan select'". (PR updated many help strings to reference active project bundle instead of
specfact plan select.) [::nold-ai/specfact-cli::scripts/cleanup_acceptance_criteria.py:124]
- scripts/cleanup_acceptance_criteria.py: error message contains "Please specify bundle name or run 'specfact plan select'". (PR updated many help strings to reference active project bundle instead of
-
"specfact repro" usages (flat repro command still present in docs, tests, tooling):
- docs/reference/commands.md and docs/migration/migration-guide.md include mapping/mentions of
specfact repro→specfact code repro. [::nold-ai/specfact-cli::docs/reference/commands.md:152; ::docs/migration/migration-guide.md:90] - tests and tools reference
specfact reproin integration/unit tests and tooling (e.g., tests/integration/commands/test_repro_command.py, tools/validate_prompts.py, tests/unit/workflows/test_trustworthy_green_checks.py). [::nold-ai/specfact-cli::tests/integration/commands/test_repro_command.py:320; ::tests/unit/workflows/test_trustworthy_green_checks.py:213; ::tools/validate_prompts.py:53] - openspec specs and proposals refer to running
specfact reproin CI and design documents. [::nold-ai/specfact-cli::openspec/specs/ci-log-artifacts/spec.md:46,52,70]
- docs/reference/commands.md and docs/migration/migration-guide.md include mapping/mentions of
-
beartype usage surface (widespread; PR removed some decorators in tests to fix pytest on Python 3.14):
- tools/validate_prompts.py contains many
@beartypeusages (imports and multiple decorated functions). [::nold-ai/specfact-cli::tools/validate_prompts.py:15,87,109,150,203,264,323,353,413,439] - Numerous test modules import and use
@beartype(many files under tests/...), including the specific unit tests noted in the PR (sync_runtime, drift_detector). [::nold-ai/specfact-cli::tests/unit/sync_runtime/test_bridge_sync.py; ::tests/unit/sync_runtime/test_drift_detector.py — see multiple@beartypeoccurrences across tests/* (truncated output).]
- tools/validate_prompts.py contains many
Assessment:
- The repo contains many docs, tests, and scripts that reference flat commands (specfact repro, specfact sdd, specfact plan select). The PR’s doc/help-string updates and beartype removals are relevant and likely necessary to keep examples and tests consistent with the new namespacing and to avoid test failures on Python 3.14.
- Tools and many tests still include
@beartypeusage; verify whether the PR removed all problematic decorators (PR removed a subset in sync_runtime tests).
🔇 Additional comments (15)
packages/specfact-backlog/module-package.yaml (1)
2-2: LGTM!Also applies to: 30-31
packages/specfact-code-review/module-package.yaml (1)
2-2: LGTM!Also applies to: 26-27
packages/specfact-govern/src/specfact_govern/enforce/commands.py (1)
7-9: LGTM!Also applies to: 220-220, 285-285, 316-316, 335-335, 385-385, 566-566, 581-581, 585-585
packages/specfact-project/src/specfact_project/import_cmd/commands.py (1)
8-10: LGTM!Also applies to: 1669-1669, 1673-1673, 1681-1681, 1685-1685, 1730-1730, 1965-1967, 2410-2410, 2535-2535
packages/specfact-project/src/specfact_project/sync/commands.py (1)
8-10: LGTM!Also applies to: 715-715, 796-796, 815-815, 860-862, 882-882
packages/specfact-codebase/module-package.yaml (1)
2-2: LGTM!Also applies to: 27-28
packages/specfact-govern/module-package.yaml (1)
2-2: LGTM!Also applies to: 22-23
packages/specfact-project/src/specfact_project/sync_runtime/sync_perform_operation_impl.py (1)
105-105: LGTM!packages/specfact-spec/src/specfact_spec/spec/commands.py (1)
65-66: LGTM!Also applies to: 96-97, 221-222, 722-723, 858-859
packages/specfact-project/module-package.yaml (1)
2-2: LGTM!Also applies to: 30-31
packages/specfact-spec/module-package.yaml (1)
2-2: LGTM!Also applies to: 24-25
packages/specfact-codebase/src/specfact_codebase/analyze/commands.py (1)
6-9: LGTM!Also applies to: 62-62, 75-75, 95-95
packages/specfact-codebase/src/specfact_codebase/drift/commands.py (1)
6-9: LGTM!Also applies to: 48-48, 86-87, 108-108
packages/specfact-codebase/src/specfact_codebase/import_cmd/commands.py (1)
1-6: LGTM!Also applies to: 86-86
packages/specfact-codebase/src/specfact_codebase/repro/commands.py (1)
6-9: LGTM!Also applies to: 217-220, 474-476, 566-566
- Replace leftover 'specfact generate ...' runtime examples and remediation hints with 'specfact spec generate ...' in the apply-help block, prompt next-steps, fix-prompt, and test-prompt listings. - Replace remaining flat 'specfact sdd constitution ...' hints with 'specfact spec constitution ...' in constitution validation next-steps and the sync bootstrap guidance, matching the prompt-command validator mounts. Addresses the PR #318 review annotations from chatgpt-codex-connector and coderabbitai about incomplete namespace migration in user-facing help/error paths. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
Summary
Related to nold-ai/specfact-cli#605.
Validation