Skip to content

Expose plan command in specfact-project manifest; update docs and add regression test#256

Closed
djm81 wants to merge 2 commits into
devfrom
codex/fix-specfact-project-module-bug
Closed

Expose plan command in specfact-project manifest; update docs and add regression test#256
djm81 wants to merge 2 commits into
devfrom
codex/fix-specfact-project-module-bug

Conversation

@djm81
Copy link
Copy Markdown
Contributor

@djm81 djm81 commented Apr 29, 2026

Motivation

Description

  • Added plan to packages/specfact-project/module-package.yaml commands list and bumped the package version and integrity checksum/signature.
  • Updated documentation entries to list plan as part of the project bundle in docs/guides/marketplace.md and docs/reference/module-categories.md.
  • Added an OpenSpec change folder openspec/changes/project-02-plan-root-command-fix/ with proposal, design, spec, tasks, and TDD evidence, and updated openspec/CHANGE_ORDER.md.
  • Added regression test tests/unit/test_specfact_project_manifest_commands.py that asserts the manifest contains both project and plan.

Testing

  • Ran pytest -q tests/unit/test_specfact_project_manifest_commands.py and the test passed.
  • Ran ./scripts/pre-commit-quality-checks.sh and the pre-commit quality checks passed.

Codex Task

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 29, 2026

📝 Walkthrough

PR #256: Expose plan command in specfact-project manifest; update docs and add regression test

Bundle and Module Surface

  • Issue: specfact plan was inaccessible despite nold-ai/specfact-project installation because the bundle manifest failed to declare the plan command group.
  • Root cause: CLI command registry loads bundle command groups from module-package.yaml commands list; the plan implementation existed in codebase (packages/specfact-project/src/specfact_project/plan/) but was never registered for runtime routing.
  • Fix: Added plan to commands list in packages/specfact-project/module-package.yaml alongside existing project command.
  • Module imports: Module extensively uses specfact_cli.registry.registry.CommandRegistry, specfact_cli.models.plan, specfact_cli.models.project, and specfact_cli.adapters.registry for command and adapter delegation; no breaking API changes to these contracts.

Manifest and Integrity

  • Version bump: 0.41.70.41.9 (patch semver increment aligned with manifest-only fix).
  • Command surface updated: commands: [project]commands: [project, plan].
  • Integrity block: Both SHA256 checksum and signature regenerated for new manifest state.
  • Core compatibility: Unchanged (>=0.40.0,<1.0.0); no specfact-cli version requirement modifications.
  • Bundle dependencies: No new bundle-level or pip dependencies introduced.

Cross-Repo and specfact_cli Contract Alignment

  • No changes to Python import paths, adapter interfaces, or runtime bridge contracts.
  • Module continues to depend on specfact_cli models and utilities for plan/project bundle handling, validation, progress tracking, and telemetry (no new transitive dependencies).
  • CommandRegistry API usage verified; no evidence of deprecated APIs or breaking changes in this PR.

Documentation

  • docs/guides/marketplace.md: Updated bundle overview to list plan alongside project and sync for the nold-ai/specfact-project bundle.
  • docs/reference/module-categories.md: Updated "Bundle Contents by Category" table to include plan in specfact-project contents (project, plan, sync).
  • Effect: Public documentation now accurately reflects exposed command surface; no discrepancy between marketplace description and implementation.

OpenSpec Change Tracking

  • Change ID: project-02-plan-root-command-fix (order 02 under Project bundle runtime changes).
  • Design: Manifest-first correction with regression test; design doc clarifies command registry delegation mechanism.
  • Spec: ADDED requirement for bundle to declare both project and plan in manifest commands list; scenario asserts manifest includes plan and related docs mention it.
  • Tasks: Checklist covers spec delta, failing test/evidence, manifest/docs updates, quality gate validation.
  • TDD evidence:
    • Failing case: specfact plan --help fails without module installation.
    • Passing case: Pytest for new test passes; pre-commit quality checks pass; runtime validation with locally linked module confirms specfact plan --help renders root command usage and subcommands.

Testing and Validation

  • New regression test: tests/unit/test_specfact_project_manifest_commands.py validates that packages/specfact-project/module-package.yaml commands array includes both "project" and "plan" (manifest-level contract assertion).
  • Test execution: Pytest passed; pre-commit checks (./scripts/pre-commit-quality-checks.sh) passed.
  • Runtime validation: Verified with local module shadow-linking; confirmed specfact plan --help renders correctly when module is enabled (nold-ai/specfact-project 0.41.9).

Summary

This PR is a targeted manifest-only fix addressing Issue #255. The plan command implementation was production-ready but not exposed via the module registry due to a missing manifest declaration. The fix aligns manifest, documentation, and change-tracking; adds regression coverage; and prevents future regressions via a manifest-level test. No code logic changes, API breaks, or new dependencies introduced.

Walkthrough

This PR adds the plan command to the nold-ai/specfact-project bundle's module manifest, updates documentation to reflect the command inclusion, adds a regression test to validate the manifest declaration, and documents the change through formal change tracking. The fix addresses the root cause where the command registry failed to load the plan delegate due to missing manifest entry.

Changes

Cohort / File(s) Summary
Documentation Updates
docs/guides/marketplace.md, docs/reference/module-categories.md
Updated bundle documentation to remove deprecated migrate command and add plan command to the project bundle's command list.
Manifest Configuration
packages/specfact-project/module-package.yaml
Added plan to the commands list alongside project, updated version to 0.41.9, removed category and bundle_group_command metadata fields, and updated integrity checksums.
Regression Test
tests/unit/test_specfact_project_manifest_commands.py
New unit test validating that the specfact-project manifest includes both project and plan command entries.
Change Tracking & Specification
openspec/CHANGE_ORDER.md, openspec/changes/project-02-plan-root-command-fix/*
Formal change documentation including proposal, design notes, TDD evidence, specification requirements, and task checklist for the plan command fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

  • Issue #255: Directly addressed by adding plan to the specfact-project manifest's command list, enabling the specfact plan CLI command that was previously unavailable despite module installation.
  • Issue #532: Related change addressing the same root cause through the same manifest fix and supporting regression test coverage.

Suggested labels

module, documentation, change-proposal

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.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 describes the main changes (exposing plan command, updating docs, adding test) and uses a descriptive format aligned with conventional commits guidance.
Description check ✅ Passed Description covers motivation, implementation details, testing evidence, and maps well to the provided template with clear section organization and validation steps.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ 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 codex/fix-specfact-project-module-bug

Review rate limit: 4/5 reviews remaining, refill in 12 minutes.

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

Copy link
Copy Markdown

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

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: d3dadc18e1

ℹ️ 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 on lines 27 to 28
description: Official SpecFact project bundle package.
category: project
bundle_group_command: project
integrity:
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Restore bundle_group_command in project manifest

This change drops bundle_group_command from the specfact-project manifest, but repo validation still treats that field as required (tools/validate_repo_manifests.py defines it in REQUIRED_KEYS). In contexts where YAML validation runs (e.g., hatch run yaml-lint via pre-commit/CI), this manifest now fails with a missing-key error, and any workflow expecting bundle-group metadata cannot rely on this package manifest anymore.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/specfact-project/module-package.yaml (1)

1-30: ⚠️ Potential issue | 🔴 Critical

Restore the required manifest metadata.

This manifest now omits bundle_group_command, but tools/validate_repo_manifests.py still treats that field as required, so validation will fail unless the validator is updated in the same PR. The plan command addition is fine; the missing metadata field needs to stay.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/specfact-project/module-package.yaml` around lines 1 - 30, Restore
the missing required manifest field "bundle_group_command" in the package
manifest (module-package.yaml); add the bundle_group_command entry back
alongside the existing commands (e.g., matching the package's group/category or
the existing "project"/"plan" semantics) so tools/validate_repo_manifests.py
continues to pass validation, ensuring the key name is exactly
"bundle_group_command" and populated with the same kind of value other official
bundles use.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@openspec/changes/project-02-plan-root-command-fix/proposal.md`:
- Around line 1-9: Change the first heading "Why" from H2 to H1 (use a single
leading #) and ensure there is a blank line before and after each top-level
section heading ("Why", "What Changes", and "Impact") to satisfy markdownlint
MD041/MD022; update the proposal headings so they are separated by single empty
lines and the first heading is H1.

In `@openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md`:
- Around line 4-5: Update the TDD_EVIDENCE.md to capture the true regression:
install the nold-ai/specfact-project bundle in the test workspace (instead of
showing "module not installed"), reproduce the failing symptom where the
installed bundle's metadata does not expose or delegate the root "plan" command,
and include a runtime verification step that runs `specfact plan --help`
(showing the missing/delegated output) to confirm the root plan command fails to
render; ensure the failing-before section explicitly states
"nold-ai/specfact-project installed but plan not delegated by registry" and
includes the exact CLI output from the verification run.
- Around line 3-21: The markdown headings in TDD_EVIDENCE.md (specifically the
headings "Failing-before evidence", "Implementation changes", "Passing-after
evidence", "Tooling verification", and "Runtime validation with linked local
module") lack surrounding blank lines and trigger markdownlint MD022; edit that
file to ensure there is a single blank line before and after each of those
headings so each heading is separated from surrounding content (i.e.,
insert/ensure an empty line above and below each of those heading lines).

---

Outside diff comments:
In `@packages/specfact-project/module-package.yaml`:
- Around line 1-30: Restore the missing required manifest field
"bundle_group_command" in the package manifest (module-package.yaml); add the
bundle_group_command entry back alongside the existing commands (e.g., matching
the package's group/category or the existing "project"/"plan" semantics) so
tools/validate_repo_manifests.py continues to pass validation, ensuring the key
name is exactly "bundle_group_command" and populated with the same kind of value
other official bundles use.
🪄 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: ASSERTIVE

Plan: Pro

Run ID: 298453e6-9dc7-4a61-bb97-75849dbb1619

📥 Commits

Reviewing files that changed from the base of the PR and between 0ea9f11 and d3dadc1.

📒 Files selected for processing (10)
  • docs/guides/marketplace.md
  • docs/reference/module-categories.md
  • openspec/CHANGE_ORDER.md
  • openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md
  • openspec/changes/project-02-plan-root-command-fix/design.md
  • openspec/changes/project-02-plan-root-command-fix/proposal.md
  • openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md
  • openspec/changes/project-02-plan-root-command-fix/tasks.md
  • packages/specfact-project/module-package.yaml
  • tests/unit/test_specfact_project_manifest_commands.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (5)
openspec/**/*.md

⚙️ CodeRabbit configuration file

openspec/**/*.md: Specification truth: proposal/tasks/spec deltas vs. bundle behavior, CHANGE_ORDER, and
drift vs. shipped modules or docs.

Files:

  • openspec/changes/project-02-plan-root-command-fix/tasks.md
  • openspec/CHANGE_ORDER.md
  • openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md
  • openspec/changes/project-02-plan-root-command-fix/design.md
  • openspec/changes/project-02-plan-root-command-fix/proposal.md
  • openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md
docs/**/*.md

⚙️ CodeRabbit configuration file

docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.

Files:

  • docs/reference/module-categories.md
  • docs/guides/marketplace.md
**/*.{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:

  • tests/unit/test_specfact_project_manifest_commands.py
tests/**/*.py

⚙️ CodeRabbit configuration file

tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.

Files:

  • tests/unit/test_specfact_project_manifest_commands.py
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-project/module-package.yaml
🧠 Learnings (6)
📚 Learning: 2026-04-13T10:38:43.535Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-13T10:38:43.535Z
Learning: Perform `spec -> tests -> failing evidence -> code -> passing evidence` in that order for behavior changes

Applied to files:

  • openspec/changes/project-02-plan-root-command-fix/tasks.md
  • openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md
📚 Learning: 2026-04-13T10:38:29.399Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-13T10:38:29.399Z
Learning: When a change is paired with work in specfact-cli, review the paired public change artifacts there before widening scope or redefining shared workflow semantics

Applied to files:

  • openspec/changes/project-02-plan-root-command-fix/tasks.md
  • openspec/CHANGE_ORDER.md
📚 Learning: 2026-04-13T10:38:22.848Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-13T10:38:22.848Z
Learning: This repository enforces the clean-code review gate through hatch run specfact code review run --json --out .specfact/code-review.json

Applied to files:

  • openspec/changes/project-02-plan-root-command-fix/tasks.md
  • docs/reference/module-categories.md
📚 Learning: 2026-04-13T10:38:22.848Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-13T10:38:22.848Z
Learning: Work belongs on feature/*, bugfix/*, hotfix/*, or chore/* branches, normally in a worktree rooted under ../specfact-cli-modules-worktrees/

Applied to files:

  • docs/reference/module-categories.md
  • openspec/CHANGE_ORDER.md
  • docs/guides/marketplace.md
📚 Learning: 2026-04-13T10:38:22.848Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-13T10:38:22.848Z
Learning: Refresh .specfact/backlog/github_hierarchy_cache.md with python scripts/sync_github_hierarchy_cache.py when GitHub hierarchy metadata is missing or stale before parent or blocker work

Applied to files:

  • docs/reference/module-categories.md
📚 Learning: 2026-04-13T10:38:43.535Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-13T10:38:43.535Z
Learning: If GitHub hierarchy metadata is needed and `.specfact/backlog/github_hierarchy_cache.md` is missing or stale, refresh it with `python scripts/sync_github_hierarchy_cache.py`

Applied to files:

  • docs/reference/module-categories.md
🪛 markdownlint-cli2 (0.22.1)
openspec/changes/project-02-plan-root-command-fix/tasks.md

[warning] 1-1: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)

openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md

[warning] 1-1: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 1-1: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)


[warning] 2-2: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above

(MD022, blanks-around-headings)


[warning] 2-2: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 5-5: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

openspec/changes/project-02-plan-root-command-fix/design.md

[warning] 1-1: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 1-1: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)

openspec/changes/project-02-plan-root-command-fix/proposal.md

[warning] 1-1: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 1-1: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)


[warning] 4-4: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md

[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 7-7: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 15-15: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 21-21: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🔇 Additional comments (9)
docs/reference/module-categories.md (1)

61-61: Looks aligned with the new command surface.

The bundle contents list now includes plan, which matches the manifest and spec updates.

docs/guides/marketplace.md (1)

35-35: Bundle overview stays in sync.

Listing plan here keeps the marketplace docs aligned with the bundle manifest and command surface.

openspec/changes/project-02-plan-root-command-fix/tasks.md (1)

1-4: Checklist order is fine.

Spec, regression test, implementation/docs, and validation are sequenced sensibly for this change.

openspec/CHANGE_ORDER.md (1)

58-58: Correct module and order slot.

The project-runtime / 02 entry matches the change scope and dependency context.

tests/unit/test_specfact_project_manifest_commands.py (1)

9-14: Good manifest-level regression coverage.

This pins the bundle contract directly and should catch future command-surface regressions.

openspec/changes/project-02-plan-root-command-fix/design.md (1)

1-4: Design note matches the fix strategy.

The manifest-first delegation explanation is clear and lines up with the regression-test approach.

openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md (1)

1-8: Spec captures the right contract.

This cleanly constrains the bundle manifest to expose project and plan, which is the right observable requirement for the fix.

openspec/changes/project-02-plan-root-command-fix/proposal.md (1)

2-7: Good manifest-first framing for the bundle↔core registry boundary.

The proposal clearly ties the root cause to missing commands metadata and includes the required manifest/docs/regression-test actions.

As per coding guidelines, “When proposing runtime bundle command-surface fixes, tie the root cause to the manifest declaration gap ... then enumerate required actions: update the bundle manifest commands, update the docs ... and add regression coverage...”.

openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md (1)

8-25: Implementation/passing/runtime evidence is well aligned to module manifest delegation behavior.

This captures the manifest change, targeted regression test, quality gates, and linked-module runtime check for specfact plan --help.

As per coding guidelines, “Follow the design rationale that runtime command delegation is driven by packages/*/module-package.yaml commands ... validated by a regression test that inspects bundle metadata.”

Comment on lines +1 to +9
## Why
Issue #255 reports that `specfact plan` is not accessible even when `nold-ai/specfact-project` is installed. The project bundle manifest only declares `project` in `commands`, so runtime command registry never loads the plan delegate.

## What Changes
- Add `plan` to `packages/specfact-project/module-package.yaml` commands list.
- Update docs that describe project bundle exposed command groups to include plan.
- Add regression coverage for manifest command declaration.

## Impact
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.

⚠️ Potential issue | 🟡 Minor

Fix heading structure to satisfy markdownlint (MD041/MD022).

Line 1 should be an H1, and headings at Line 1, Line 4, and Line 9 need surrounding blank lines.

Suggested markdown fix
-## Why
+# Proposal: project-02-plan-root-command-fix
+
+## Why
+
 Issue `#255` reports that `specfact plan` is not accessible even when `nold-ai/specfact-project` is installed. The project bundle manifest only declares `project` in `commands`, so runtime command registry never loads the plan delegate.
 
 ## What Changes
+
 - Add `plan` to `packages/specfact-project/module-package.yaml` commands list.
 - Update docs that describe project bundle exposed command groups to include plan.
 - Add regression coverage for manifest command declaration.
 
 ## Impact
+
 - Affected spec: project-command-surface
 - Affected code: packages/specfact-project/module-package.yaml, docs/guides/marketplace.md, docs/reference/module-categories.md, tests
 - Tracking: https://github.com/nold-ai/specfact-cli-modules/issues/255
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 1-1: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 1-1: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)


[warning] 4-4: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openspec/changes/project-02-plan-root-command-fix/proposal.md` around lines 1
- 9, Change the first heading "Why" from H2 to H1 (use a single leading #) and
ensure there is a blank line before and after each top-level section heading
("Why", "What Changes", and "Impact") to satisfy markdownlint MD041/MD022;
update the proposal headings so they are separated by single empty lines and the
first heading is H1.

Comment on lines +3 to +21
## Failing-before evidence
- `specfact plan --help` in a clean temp workspace without installed project module failed with:
- `Module 'nold-ai/specfact-project' is not installed.`

## Implementation changes
- Added `plan` to `packages/specfact-project/module-package.yaml` `commands` list.
- Added regression test `tests/unit/test_specfact_project_manifest_commands.py`.

## Passing-after evidence
- `pytest -q tests/unit/test_specfact_project_manifest_commands.py` → **passed**.
- `./scripts/pre-commit-quality-checks.sh` → **passed** in this environment.

## Tooling verification
- OpenSpec npm install command verified from openspec.dev:
- `npm install -g @fission-ai/openspec@latest`
- `openspec --version` returned `1.3.1` after install.


## Runtime validation with linked local module
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.

⚠️ Potential issue | 🟡 Minor

Add blank lines around section headings to clear markdownlint MD022.

Headings at Line 3, Line 7, Line 11, Line 15, and Line 21 need surrounding blank lines.

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 7-7: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 15-15: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 21-21: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md` around
lines 3 - 21, The markdown headings in TDD_EVIDENCE.md (specifically the
headings "Failing-before evidence", "Implementation changes", "Passing-after
evidence", "Tooling verification", and "Runtime validation with linked local
module") lack surrounding blank lines and trigger markdownlint MD022; edit that
file to ensure there is a single blank line before and after each of those
headings so each heading is separated from surrounding content (i.e.,
insert/ensure an empty line above and below each of those heading lines).

Comment on lines +4 to +5
- `specfact plan --help` in a clean temp workspace without installed project module failed with:
- `Module 'nold-ai/specfact-project' is not installed.`
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.

⚠️ Potential issue | 🟠 Major

Failing-before evidence does not capture the actual regression contract.

Line 4 and Line 5 show “module not installed,” but Issue #255 is about installed bundle metadata not exposing plan. Please record the failing symptom with nold-ai/specfact-project installed but plan not delegated by registry.

Suggested correction
-## Failing-before evidence
-- `specfact plan --help` in a clean temp workspace without installed project module failed with:
-  - `Module 'nold-ai/specfact-project' is not installed.`
+## Failing-before evidence
+- With `nold-ai/specfact-project` installed (pre-fix manifest declaring only `project`), `specfact plan --help` failed because the root `plan` delegate was not registered from bundle metadata.

As per coding guidelines, “Use this repo’s TDD-evidence pattern: (1) record the failing-before CLI symptom ... and (4) include runtime verification ... running specfact plan --help to confirm the root plan command renders.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- `specfact plan --help` in a clean temp workspace without installed project module failed with:
- `Module 'nold-ai/specfact-project' is not installed.`
- With `nold-ai/specfact-project` installed (pre-fix manifest declaring only `project`), `specfact plan --help` failed because the root `plan` delegate was not registered from bundle metadata.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md` around
lines 4 - 5, Update the TDD_EVIDENCE.md to capture the true regression: install
the nold-ai/specfact-project bundle in the test workspace (instead of showing
"module not installed"), reproduce the failing symptom where the installed
bundle's metadata does not expose or delegate the root "plan" command, and
include a runtime verification step that runs `specfact plan --help` (showing
the missing/delegated output) to confirm the root plan command fails to render;
ensure the failing-before section explicitly states "nold-ai/specfact-project
installed but plan not delegated by registry" and includes the exact CLI output
from the verification run.

@djm81 djm81 self-assigned this Apr 29, 2026
@djm81 djm81 added bug Something isn't working documentation Improvements or additions to documentation labels Apr 29, 2026
@djm81 djm81 moved this from Todo to In Progress in SpecFact CLI Apr 29, 2026
@djm81
Copy link
Copy Markdown
Contributor Author

djm81 commented Apr 29, 2026

Codex requires a new PR due to PR updates.

@djm81 djm81 closed this Apr 29, 2026
@github-project-automation github-project-automation Bot moved this from In Progress to Done in SpecFact CLI Apr 29, 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 codex documentation Improvements or additions to documentation

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

specfact plan command group not accessible despite nold-ai/specfact-project being installed (v0.41.7)

1 participant