Conversation
…pages-closeout docs(openspec): close out docs-08 verification
…docs docs: add missing command reference pages
…dation docs: consolidate workflow guides
…tier docs: add team and enterprise guides
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
docs: add docs validation ci checks
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (11)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds extensive documentation (new pages, link fixes, redirects), a docs-command validator plus CI wiring and tests, implements a Spec‑Kit ↔ OpenSpec change‑proposal bridge with backlog‑mapping detection, extends Changes
Sequence Diagram(s)sequenceDiagram
participant User as User/CLI
participant CLI as specfact CLI
participant Bridge as BridgeSync / sync_runtime
participant Repo as OpenSpec repo (openspec/changes)
participant Adapter as External Adapter (GitHub/ADO/Speckit)
User->>CLI: run `specfact sync bridge --adapter speckit --mode change-proposal [--feature|--all]`
CLI->>Bridge: run_sync_bridge_command(mode=change-proposal, feature/all)
Bridge->>Repo: scan `specs/` for Spec-Kit features (detect tracked/untracked)
alt untracked feature found
Bridge->>Bridge: SpecKitConverter.convert_to_change_proposal(feature_path)
Bridge->>Repo: write `openspec/changes/{change}/proposal.md`, `design.md`, `specs/`, `tasks.md`
end
opt export to adapter
Bridge->>Adapter: adapter.export_artifact(proposal)
Adapter-->>Bridge: export result (id/url)
Bridge->>Repo: update proposal `source_tracking` with adapter id/url
end
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Possibly related issues
Possibly related PRs
Suggested labels
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 21
♻️ Duplicate comments (1)
docs/guides/cross-module-chains.md (1)
45-45:⚠️ Potential issue | 🟡 MinorVerify
--previousflag usage (duplicate of earlier finding).Line 45 shows
specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml, which uses--previousas a flag forbackward-compat. However, the command signature documented indocs/bundles/spec/validate.mdline 18 showsspecfact spec backward-compat OLD_SPEC NEW_SPECwith two positional arguments, not a--previousflag. This discrepancy appears in multiple files.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/cross-module-chains.md` at line 45, The command usage in the docs is inconsistent: replace the flagged form "specfact spec backward-compat api/openapi.yaml --previous api/openapi.v1.yaml" with the positional OLD_SPEC NEW_SPEC form used by the tool; specifically change the invocation of "specfact spec backward-compat" so the older spec (api/openapi.v1.yaml) is the first argument and the newer spec (api/openapi.yaml) is the second (i.e., "specfact spec backward-compat api/openapi.v1.yaml api/openapi.yaml") to match the signature shown in docs/bundles/spec/validate.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/docs-review.yml:
- Around line 60-65: Remove the redundant directory creation by deleting the
`mkdir -p logs/docs-review` line in the job step that runs `python
scripts/check-docs-commands.py`; keep the
`DOCS_COMMAND_LOG="logs/docs-review/docs-command-validation_$(date -u
+%Y%m%d_%H%M%S).log"`, `python scripts/check-docs-commands.py 2>&1 | tee
"$DOCS_COMMAND_LOG"`, and `exit "${PIPESTATUS[0]:-$?}"` lines intact so the log
file is still created and the step exit status is preserved.
In `@docs/adapters/github.md`:
- Line 357: The broken anchor /reference/commands/#project-sync-bridge should be
fixed by either adding a corresponding heading titled "Project Sync Bridge" (or
"specfact project sync bridge") into docs/reference/commands.md so the
`#project-sync-bridge` anchor is generated, or by removing the fragment from the
link in docs/adapters/github.md so it points to /reference/commands/ without an
anchor; update the text in docs/adapters/github.md (the sentence mentioning
--sanitize and the sync bridge command) to match whichever option you choose and
ensure the anchor string "#project-sync-bridge" matches the exact heading slug
if you add the heading.
In `@docs/bundles/backlog/policy-engine.md`:
- Around line 17-19: The three bullets for the policy CLI commands are
repetitive in their openings; rephrase them to vary sentence starts and improve
readability while keeping the same meaning and references to the commands
`specfact backlog policy init`, `specfact backlog policy validate`, and
`specfact backlog policy suggest` and the artifact `.specfact/policy.yaml`. For
example, make the first bullet an imperative that mentions scaffolding
`.specfact/policy.yaml`, the second describe evaluation of configured rules
deterministically, and the third describe generation of confidence-scored,
patch-ready recommendations (explicitly noting no automatic writes); keep each
bullet short and parallel in structure but avoid repeating the same leading
phrase.
In `@docs/bundles/codebase/repro.md`:
- Line 63: Replace the awkward link label "Code analyze contracts" with the
concise exact phrasing "Code analyze" in the markup line that currently reads
"[Code analyze contracts](analyze/)"; update only the visible link text (left of
the parentheses) to read "Code analyze" so the link becomes "[Code
analyze](analyze/)".
In `@docs/bundles/govern/enforce.md`:
- Around line 23-25: Remove the unnecessary backslash escapes in the Markdown
table cells for the `--preset` option: replace the literal `--preset
<minimal\|balanced\|strict>` occurrences with `--preset
<minimal|balanced|strict>` (do the same for the identical occurrence later in
the file referenced in the comment), ensuring the table cells no longer include
`\|` so the pipes render correctly as content rather than literal backslashes.
In `@docs/bundles/govern/patch.md`:
- Around line 39-42: The Related links in the "Related" section currently use
relative paths ("enforce/" and "overview/") which are inconsistent with other
docs; update the two link targets for "Govern enforce" and "Govern bundle
overview" to use absolute site-root URLs (/bundles/govern/enforce/ and
/bundles/govern/overview/) so navigation behaves consistently across the site.
In `@docs/bundles/spec/validate.md`:
- Line 45: Add the missing --previous option to the "Key options" table and the
"What it does" section: document the flag name `--previous`, indicate it accepts
a filepath (e.g., previous spec) and describe that it runs inline
backward-compatibility checks against a prior OpenAPI spec (as used in the
example `specfact spec validate api/openapi.yaml --previous
api/openapi.v1.yaml`), so readers see the flag listed and explained alongside
the other key options.
In `@docs/guides/brownfield-examples.md`:
- Line 16: The example call for the CLI command specfact code import has the
positional bundle argument placed before options; update the example so options
come first per the documented policy by reordering the arguments in the specfact
code import invocation (i.e., move --repo . before the bundle name legacy-api)
so the command reads with options preceding the positional bundle.
In `@docs/guides/README.md`:
- Around line 9-68: The README mixes relative links (e.g., "Brownfield
modernization" -> brownfield-modernization.md) with site-root absolute links
(e.g., "DevOps Adapter Integration" -> /integrations/devops-adapter-overview/);
standardize all links to use consistent absolute paths under the guides
namespace (for example, change brownfield-modernization.md to
/guides/brownfield-modernization/ and similarly normalize other entries like
brownfield-examples.md, workflows.md, ide-integration.md, and
/integrations/devops-adapter-overview/ to their canonical absolute guide URLs)
so future restructuring and link resolution remain predictable.
In
`@openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md`:
- Around line 3-7: Update the markdown heading levels so they increment
correctly: change the "Requirement: Workflow documentation SHALL provide a
complete day-level routine..." heading from "###" to "##" and change the
"Scenario: Daily routine covers a full work day" heading from "####" to "###" so
the document uses top-level "#" then "##" then "###" increments (refer to the
headings text "Requirement: Workflow documentation SHALL provide a complete
day-level routine" and "Scenario: Daily routine covers a full work day" to
locate the lines to edit).
In
`@openspec/changes/docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md`:
- Around line 3-13: The document's heading levels are inconsistent: change the
"Requirement: Enterprise configuration docs SHALL cover profiles, overlays, and
multi-repo policy" heading from H1 to H2 (i.e., prefix with "##") and change
both "Scenario: Enterprise config guide covers customization" and "Scenario:
Multi-repo guide covers cross-repo workflows" from H3/H4 to H3 (i.e., prefix
with "###") so the hierarchy flows H1 → H2 → H3; update the three heading lines
in the file to use the new markdown prefixes while leaving the content
unchanged.
In `@openspec/changes/speckit-03-change-proposal-bridge/design.md`:
- Line 1: Change the first-line heading "## Context" to a top-level heading by
replacing it with "# Context" so the document begins with a level-1 heading
(fixes markdownlint MD041); ensure no other content precedes this first-line
heading in design.md.
In `@openspec/changes/speckit-03-change-proposal-bridge/proposal.md`:
- Line 1: Change the document title from a level-2 to level-1 by replacing "##
Why" with "# Why", and add a blank line immediately after the other headings
that currently lack spacing (notably the headings referenced in the review
around lines 15 and 19) so every heading is followed by a single empty line to
satisfy MD041/MD022.
In
`@openspec/changes/speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md`:
- Line 1: The document header currently begins with a level-2 heading ("##
MODIFIED Requirements") which triggers MD041; change the top-level heading to an
H1 by replacing the leading "##" with "#" so the file starts with "# MODIFIED
Requirements" to satisfy markdown linting and ensure the spec begins with an H1.
In
`@openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.md`:
- Line 1: The document starts with a level-2 heading "## ADDED Requirements";
change that top heading to a level-1 heading by replacing "## ADDED
Requirements" with "# ADDED Requirements" so the file begins with a proper
top-level Markdown heading and improves document structure and navigation.
In
`@openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.md`:
- Line 1: The file's first heading is H2 ("## ADDED Requirements") which
triggers markdownlint MD041; change the first heading to an H1 by replacing "##
ADDED Requirements" with "# ADDED Requirements" (or by adding a top-level H1
above it) so the document begins with an H1; locate the heading text "ADDED
Requirements" in the spec.md to make this edit.
In `@openspec/changes/speckit-03-change-proposal-bridge/tasks.md`:
- Line 1: Add a top-level H1 heading above the existing H2 to satisfy MD041
linting: insert a single-line title above the line starting with "## 1. Spec-Kit
to OpenSpec change proposal conversion" (for example, "# Spec-Kit to OpenSpec
change proposal conversion") so the file begins with an H1 before the current
H2.
In `@openspec/specs/team-setup-docs/spec.md`:
- Line 7: The markdown heading "#### Scenario: Team setup guide covers
onboarding" should be demoted one level to "###" to maintain proper heading
hierarchy after the existing "##" header; update the same change for the other
occurrence noted (the heading at line 13) so all h4 headings that directly
follow an h2 become h3, preserving incremental Markdown levels.
In `@scripts/check-docs-commands.py`:
- Around line 99-101: The current detection for bash fences uses
stripped.startswith("```bash"), which also matches variants like "```bashrc";
update the conditional that sets in_bash_block (the variable used to track
entering a bash code block) to only treat exact "```bash" or "```bash " (with a
following space) as the start of a bash block by replacing the startswith check
on the stripped string with a stricter condition (e.g., check stripped ==
"```bash" or stripped.startswith("```bash ")) so only intended fences trigger
in_bash_block.
In `@tests/unit/docs/test_missing_command_docs.py`:
- Line 8: Add a brief inline comment above the _REPO_ROOT assignment explaining
why Path(__file__).resolve().parents[3] is used (it points from this test file
in tests/unit/docs/ up three levels to the repository root), so future
maintainers understand the expected file layout and why the index 3 is chosen
for _REPO_ROOT.
In `@tests/unit/test_check_docs_commands_script.py`:
- Around line 121-124: The test is brittle because it asserts the entire pip
install command string; update the assertions in
tests/unit/test_check_docs_commands_script.py (where the variable workflow is
asserted) to instead verify the install step more flexibly — e.g., assert that
"python -m pip install" (or "pip install") is in workflow and then assert that
each required package name (pytest, click, typer, PyYAML, beartype, icontract,
rich, pydantic, specfact-cli) appears in the workflow string (or use a regex
that checks presence of those tokens) rather than matching the exact full
command line.
---
Duplicate comments:
In `@docs/guides/cross-module-chains.md`:
- Line 45: The command usage in the docs is inconsistent: replace the flagged
form "specfact spec backward-compat api/openapi.yaml --previous
api/openapi.v1.yaml" with the positional OLD_SPEC NEW_SPEC form used by the
tool; specifically change the invocation of "specfact spec backward-compat" so
the older spec (api/openapi.v1.yaml) is the first argument and the newer spec
(api/openapi.yaml) is the second (i.e., "specfact spec backward-compat
api/openapi.v1.yaml api/openapi.yaml") to match the signature shown in
docs/bundles/spec/validate.md.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: ba3a574a-5f01-47a5-ac2b-e7f9595ee1c2
📒 Files selected for processing (109)
.github/workflows/docs-review.ymldocs/adapters/azuredevops.mddocs/adapters/backlog-adapter-patterns.mddocs/adapters/github.mddocs/bundles/backlog/policy-engine.mddocs/bundles/backlog/refinement.mddocs/bundles/code-review/ledger.mddocs/bundles/code-review/overview.mddocs/bundles/code-review/rules.mddocs/bundles/code-review/run.mddocs/bundles/codebase/analyze.mddocs/bundles/codebase/drift.mddocs/bundles/codebase/overview.mddocs/bundles/codebase/repro.mddocs/bundles/govern/enforce.mddocs/bundles/govern/overview.mddocs/bundles/govern/patch.mddocs/bundles/spec/generate-tests.mddocs/bundles/spec/mock.mddocs/bundles/spec/overview.mddocs/bundles/spec/validate.mddocs/getting-started/README.mddocs/getting-started/first-steps.mddocs/getting-started/installation.mddocs/getting-started/tutorial-backlog-refine-ai-ide.mddocs/getting-started/tutorial-daily-standup-sprint-review.mddocs/getting-started/tutorial-openspec-speckit.mddocs/guides/README.mddocs/guides/agile-scrum-workflows.mddocs/guides/ai-ide-workflow.mddocs/guides/brownfield-engineer.mddocs/guides/brownfield-examples.mddocs/guides/brownfield-faq-and-roi.mddocs/guides/brownfield-faq.mddocs/guides/brownfield-journey.mddocs/guides/brownfield-modernization.mddocs/guides/brownfield-roi.mddocs/guides/ci-cd-pipeline.mddocs/guides/command-chains.mddocs/guides/common-tasks.mddocs/guides/contract-testing-workflow.mddocs/guides/cross-module-chains.mddocs/guides/custom-field-mapping.mddocs/guides/daily-devops-routine.mddocs/guides/dual-stack-enrichment.mddocs/guides/ide-integration.mddocs/guides/integrations-overview.mddocs/guides/migration-cli-reorganization.mddocs/guides/migration-guide.mddocs/guides/module-marketplace.mddocs/guides/openspec-journey.mddocs/guides/speckit-comparison.mddocs/guides/template-customization.mddocs/guides/troubleshooting.mddocs/guides/use-cases.mddocs/guides/workflows.mddocs/index.mddocs/integrations/devops-adapter-overview.mddocs/module-publishing-guide.mddocs/reference/architecture.mddocs/reference/command-syntax-policy.mddocs/reference/directory-structure.mddocs/reference/feature-keys.mddocs/reference/parameter-standard.mddocs/reference/specmatic.mddocs/reference/telemetry.mddocs/reference/thorough-codebase-validation.mddocs/team-and-enterprise/agile-scrum-setup.mddocs/team-and-enterprise/enterprise-config.mddocs/team-and-enterprise/multi-repo.mddocs/team-and-enterprise/team-collaboration.mdopenspec/CHANGE_ORDER.mdopenspec/changes/docs-08-bundle-overview-pages/TDD_EVIDENCE.mdopenspec/changes/docs-08-bundle-overview-pages/tasks.mdopenspec/changes/docs-09-missing-command-docs/TDD_EVIDENCE.mdopenspec/changes/docs-09-missing-command-docs/tasks.mdopenspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.mdopenspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.mdopenspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.mdopenspec/changes/docs-10-workflow-consolidation/tasks.mdopenspec/changes/docs-11-team-enterprise-tier/TDD_EVIDENCE.mdopenspec/changes/docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.mdopenspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.mdopenspec/changes/docs-11-team-enterprise-tier/specs/team-setup-docs/spec.mdopenspec/changes/docs-11-team-enterprise-tier/tasks.mdopenspec/changes/docs-12-docs-validation-ci/TDD_EVIDENCE.mdopenspec/changes/docs-12-docs-validation-ci/proposal.mdopenspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.mdopenspec/changes/docs-12-docs-validation-ci/tasks.mdopenspec/changes/speckit-03-change-proposal-bridge/.openspec.yamlopenspec/changes/speckit-03-change-proposal-bridge/CHANGE_VALIDATION.mdopenspec/changes/speckit-03-change-proposal-bridge/design.mdopenspec/changes/speckit-03-change-proposal-bridge/proposal.mdopenspec/changes/speckit-03-change-proposal-bridge/specs/backlog-sync/spec.mdopenspec/changes/speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.mdopenspec/changes/speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.mdopenspec/changes/speckit-03-change-proposal-bridge/tasks.mdopenspec/specs/cross-module-workflow-docs/spec.mdopenspec/specs/daily-devops-routine-docs/spec.mdopenspec/specs/enterprise-config-docs/spec.mdopenspec/specs/missing-command-docs/spec.mdopenspec/specs/modules-docs-command-validation/spec.mdopenspec/specs/team-setup-docs/spec.mdpyproject.tomlscripts/check-docs-commands.pytests/unit/docs/test_bundle_overview_cli_examples.pytests/unit/docs/test_docs_review.pytests/unit/docs/test_missing_command_docs.pytests/unit/test_check_docs_commands_script.py
💤 Files with no reviewable changes (2)
- docs/bundles/backlog/refinement.md
- openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md
…al-bridge Add Speckit change proposal bridge
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
...s/specfact-project/src/specfact_project/sync_runtime/bridge_sync_extract_requirement_impl.py
Fixed
Show fixed
Hide fixed
...s/specfact-project/src/specfact_project/sync_runtime/bridge_sync_extract_requirement_impl.py
Fixed
Show fixed
Hide fixed
packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_issue_subhelpers.py
Fixed
Show fixed
Hide fixed
...es/specfact-project/src/specfact_project/sync_runtime/bridge_sync_read_openspec_proposals.py
Fixed
Show fixed
Hide fixed
...ct-project/src/specfact_project/sync_runtime/bridge_sync_parse_source_tracking_entry_impl.py
Fixed
Show fixed
Hide fixed
…nge-proposal-bridge
chore(registry): publish changed modules
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Promote the current
devbranch state tomain.Refs:
Scope
packages/registry/index.json,packages/*/module-package.yaml).github/workflows/*)docs/*,README.md,AGENTS.md)scripts/sign-modules.py,scripts/verify-modules-signature.py)Bundle Impact
List impacted bundles and version updates:
nold-ai/specfact-project:as merged on devnold-ai/specfact-backlog:as merged on devnold-ai/specfact-codebase:as merged on devnold-ai/specfact-spec:as merged on devnold-ai/specfact-govern:as merged on devother official bundles:as merged on devValidation Evidence
Paste command output snippets or link workflow runs.
Required local gates
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run contract-testhatch run smart-test(orhatch run test)Validation for this promotion PR should rely on the already-passing checks on the merged
devbranch state and the PR orchestrator runs for this branch sync.Signature + version integrity (required)
hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bumpdevdevbranch changes where requiredCI and Branch Protection
verify-module-signaturesquality (3.11)quality (3.12)quality (3.13)Docs / Pages
docs/) where included indevdocs-pages.yml, if changed)specfact-clidocs updated (if applicable)Checklist