Skip to content

Release dev to main: core docs portal overhaul#460

Merged
djm81 merged 337 commits intomainfrom
dev
Mar 28, 2026
Merged

Release dev to main: core docs portal overhaul#460
djm81 merged 337 commits intomainfrom
dev

Conversation

@djm81
Copy link
Copy Markdown
Collaborator

@djm81 djm81 commented Mar 28, 2026

Description

Promote the merged docs-13-core-nav-search-theme-roles work from dev to main.

This release updates the core docs.specfact.io portal so it matches the modules-site UX:
data-driven navigation, client-side search, expertise filtering, persisted theme toggle,
shared top navigation between core and modules docs, refreshed landing/getting-started content,
and docs validation coverage for navigation and command examples.

Fixes #458

New Features #458

Contract References: None. This is a docs shell, validation, and test coverage promotion; no
runtime @icontract behavior changed.

Type of Change

Please check all that apply:

  • 🐛 Bug fix (non-breaking change which fixes an issue)
  • ✨ New feature (non-breaking change which adds functionality)
  • 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • 📚 Documentation update
  • 🔒 Contract enforcement (adding/updating @icontract decorators)
  • 🧪 Test enhancement (scenario tests, property-based tests)
  • 🔧 Refactoring (code improvement without functionality change)

Contract-First Testing Evidence

Required for all changes affecting CLI commands or public APIs:

This release does not change CLI command behavior or public runtime APIs. The relevant validation
for this promotion is docs contract/parity coverage plus docs command validation.

Contract Validation

  • Runtime contracts added/updated (@icontract decorators on public APIs)
  • Type checking enforced (@beartype decorators applied)
  • CrossHair exploration completed: hatch run contract-test-exploration
  • Contract violations reviewed and addressed

Test Execution

  • Contract validation: hatch run contract-test-contracts
  • Contract exploration: hatch run contract-test-exploration
  • Scenario tests: hatch run contract-test-scenarios
  • Full test suite: hatch run contract-test-full

Test Quality

  • CLI commands tested with typer test client
  • Edge cases covered with Hypothesis property tests
  • Error handling tested with invalid inputs
  • Rich console output verified manually or with snapshots

How Has This Been Tested?

Contract-First Approach: The docs shell and cross-site routing are validated through focused
docs parity tests, docs command validation, Jekyll build verification, and strict OpenSpec
validation captured during PR #459.

Manual Testing

  • Tested CLI commands manually
  • Verified rich console output
  • Tested with different input scenarios
  • Checked error messages for clarity

Automated Testing

  • Contract validation passes
  • Property-based tests cover edge cases
  • Scenario tests cover user workflows
  • All existing tests still pass

Test Environment

  • Python version: 3.11
  • OS: Ubuntu Linux

Checklist

  • My code follows the style guidelines (PEP 8, ruff format, isort)
  • I have performed a self-review of my code
  • I have added/updated contracts (@icontract, @beartype)
  • I have added/updated docstrings (Google style)
  • I have made corresponding changes to documentation
  • My changes generate no new warnings (basedpyright, ruff, pylint)
  • All tests pass locally
  • I have added tests that prove my fix/feature works
  • Any dependent changes have been merged

Quality Gates Status

  • Type checking ✅ (hatch run type-check)
  • Linting ✅ (hatch run lint)
  • Contract validation ✅ (hatch run contract-test-contracts)
  • Contract exploration ✅ (hatch run contract-test-exploration)
  • Scenario tests ✅ (hatch run contract-test-scenarios)

Screenshots/Recordings (if applicable)

Not included in this release PR. The promoted work was visually reviewed on the local Jekyll build
during PR #459.

djm81 and others added 30 commits February 10, 2026 15:10
Corrects three broken spec-delta references flagged in PR #221 review:
- backlog-core-02: add-backlog-add-interactive-issue-creation → backlog-core-02-interactive-issue-creation
- backlog-scrum-02: sprint-planning-capacity-commitment-support → backlog-scrum-02-sprint-planning
- backlog-scrum-03: story-complexity-splitting-hints-support → backlog-scrum-03-story-complexity

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…ndency graph

- Replace old flat backlog-01..09 naming with module-scoped groups:
  backlog-core, backlog-scrum, backlog-kanban, backlog-safe,
  policy-engine, patch-mode, bundle-mapper, ceremony-cockpit
- Add arch-06/07 and marketplace-01/02 as pending changes
- Mark arch-01 through arch-05 as implemented (archived 2026-02-04..10)
- Update all GitHub issue numbers to current (incl. new #208, #213, #214,
  #215, #220 from recent changes)
- Clarify hard vs optional dependencies; optional deps are graceful no-ops
  and not set as GitHub blockers
- Update implementation waves to reflect current unblocked state (Wave 0 done)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…ing, and filter parity (#222)

* feat(backlog): finalize daily/refine comment context, interactive posting, and docs parity

* docs(openspec): mark backlog-scrum-01 standup change checklist complete

* fix(openspec): mark backlog-refinement delta as ADDED for archive apply

* Archived completed change backlog-scrum-01

* fix(backlog): make map-fields exit cleanly under CliRunner

* Fix format

* fix(backlog): stabilize map-fields tests in non-interactive env

* docs(agents): enforce signed-commit handoff flow

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
#224)

* fix: parse backlog refine writeback fields and refactor refine command

* fix: preserve heading-style narrative sections in refine parser

* chore: sync OpenSpec change to GitHub issue tracking

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
…228)

* fix: harden backlog refine prompt scaffold and parsing

* fix: normalize mixed notes parsing and boundary flushing

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
GitHub's licensee gem only recognizes standard filenames (LICENSE,
LICENSE.txt) — LICENSE.md caused the repo to show "Other" instead
of "Apache License 2.0". Updated all references across pyproject.toml,
README, docs, workflows, and FAQ.

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
)

The LICENSE body had two non-standard edits that pushed it below
GitHub licensee's ~95% similarity threshold, causing "Other" instead
of "Apache License 2.0". Restored the canonical text; only the
copyright line in the appendix is customized (as intended by the
Apache template).

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
djm81 and others added 16 commits March 26, 2026 00:41
* docs: add core vs modules URL contract and OpenSpec alignment

Document cross-site permalink rules in docs/reference, extend documentation-alignment
and module-docs-ownership specs, update docs-07 and openspec config, and note the
dependency on modules URL policy in CHANGE_ORDER.

Made-with: Cursor

* docs: convert core handoff pages to modules canonical links (docs-07)

- Replace 20 duplicate guides/tutorials with thin summaries, prerequisites,
  and links to modules.specfact.io per URL contract
- Add docs/reference/core-to-modules-handoff-urls.md mapping table
- Align OpenSpec documentation-alignment spec delta with ADDED Requirements
- Complete docs-07-core-handoff-conversion tasks checklist

Refs: #439
Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat(docs-12): docs command validation and cross-site link checks

- Add check-docs-commands (Typer CliRunner prefix + --help) and exclusions for migration/illustrative pages
- Add check-cross-site-links with robust URL extraction; warn-only in docs-validate and CI while live site may lag
- Extend docs-review: Hatch env, validation steps, pytest tests/unit/docs/
- Opt-in handoff map HTTP test (SPECFACT_RUN_HANDOFF_URL_CHECK=1)
- OpenSpec deltas, TDD_EVIDENCE, tasks complete; CHANGELOG [Unreleased]

Made-with: Cursor

* fix(docs-validate): strip leading global flags before command path

- Parse --mode/--input-format/--output-format + value, then other root flags
- Add test for specfact --mode copilot import from-code …
- Fix showcase docs: hatch run contract-test-exploration (not specfact)

Made-with: Cursor

* fix(docs-12): harden link/command validators and spec wording

- Capitalize Markdown in cross-site link spec requirement
- Cross-site: redirect-only HTTP success, UTF-8 read failures, URL delimiter/trim fixes
- Docs commands: catch Typer exceptions on --help, UTF-8 read failures
- Tests: shared loader for check-cross-site-links module

Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
…ty (#451)

Default CliRunner() merges stderr into stdout; read stdout only so
accessing result.stderr does not raise when streams are combined.

Made-with: Cursor

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
…pes) (#452)

* fix: satisfy review gates for docs scripts and module_lifecycle typing

- Replace print() with Rich Console in docs validation scripts (semgrep)
- Split HTTP URL checks and doc scans to reduce cyclomatic complexity (radon)
- Add icontract require/ensure on public helpers; use CliRunner() without mix_stderr
- Cast questionary API for basedpyright reportUnknownMemberType

Made-with: Cursor

* fix(scripts): address #452 review (HTTP helpers, icontract, CLI streams)

- _http_success_code: use int directly after None guard
- _response_status: safe getcode via getattr/callable
- check-docs: drop @require preconditions duplicated by beartype
- _cli_invoke_streams_text: merge stdout + stderr for not-installed detection

Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat(adapters): spec-kit v0.4.x adapter alignment — extensions, presets, hooks, version detection, 7-command presets

Update SpecKitAdapter, ToolCapabilities, BridgeConfig presets, and
SpecKitScanner for spec-kit v0.4.3 compatibility:

- ToolCapabilities: 5 new optional fields (extensions, extension_commands,
  presets, hook_events, detected_version_source)
- SpecKitScanner: scan_extensions(), scan_presets(), scan_hook_events()
  with .extensionignore support and defensive JSON parsing
- SpecKitAdapter: 3-tier version detection (CLI → heuristic → None),
  refactored get_capabilities() with reduced cyclomatic complexity
- BridgeConfig: all 3 speckit presets expanded from 2 to 7 command
  mappings (specify, plan, tasks, implement, constitution, clarify, analyze)
- 42 new tests across 4 test files (110 targeted, 2248 full suite pass)
- Docs updated: comparison matrix, journey guide, integrations overview,
  adapter development guide

Closes #453

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address CodeRabbit review findings

- Use get_bridge_logger instead of logging.getLogger in speckit adapter
  and scanner (production command path convention)
- Narrow except Exception to except OSError in _load_extensionignore
- Simplify redundant base_path conditional in get_capabilities
- Use SimpleNamespace instead of dynamic type() in tests
- Add subprocess.TimeoutExpired and OSError exception tests for CLI
  version detection
- Fix duplicate MD heading in bridge-adapter spec
- Add blank lines after markdown headings in proposal (MD022)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* chore: bump version to 0.43.0 and add changelog entry

Minor version bump for spec-kit v0.4.x adapter alignment feature.
Syncs version across pyproject.toml, setup.py, and __init__.py.
Adds changelog entry documenting new capabilities.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Sync deps and fix changelog

* Sync deps and fix changelog

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…441, v0.43.1) (#456)

* fix(packaging): drop duplicate workflow prompts from core wheel (packaging-02 3.5)

Remove resources/prompts from wheel force-include and repo tree; canonical
copies remain in specfact-cli-modules bundles. Align startup IDE drift
checks and init template resolution with discover_prompt_template_files.
Bump to 0.43.1; re-sign init module 0.1.19. Update CHANGELOG, docs, OpenSpec.

Made-with: Cursor

* fix: address PR review (changelog, TDD evidence, startup checks, tests)

- Changelog 0.43.1 header uses Unreleased until release tag
- TDD_EVIDENCE: pre-fail block for Task 3.5 before passing verification
- TemplateCheckResult.sources_available; skip last_checked_version bump when no
  discoverable prompts; drift missing only when source exists
- Integration _fake_discover respects include_package_fallback
- test_validate_all_prompts uses tmp_path; re-enable file in default test run
- test_print_startup_checks_version_update_no_type uses stale version timestamp

Made-with: Cursor

* fix: address follow-up PR review (startup metadata, tests)

- Use ide_dir directly in TemplateCheckResult when IDE folder exists
- Set last_checked_version only after successful template-source checks
- Integration test: assert discover_prompt_template_files fallback + stable startup patches
- validate_all_prompts test: valid vs invalid specfact.*.md outcomes

Made-with: Cursor

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
* docs: unify core docs portal UX

* Fix docs-13 core review findings

* Address docs-13 PR review feedback

* Address follow-up docs review feedback

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Mar 28, 2026

Warning

Rate limit exceeded

@djm81 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 8 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 5 minutes and 8 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9124a8be-dbc7-45d4-87ad-034ec2283dd6

📥 Commits

Reviewing files that changed from the base of the PR and between 366ad4d and ce49cd5.

📒 Files selected for processing (53)
  • CHANGELOG.md
  • README.md
  • docs/_config.yml
  • docs/_data/nav.yml
  • docs/_includes/breadcrumbs.html
  • docs/_includes/expertise-filter.html
  • docs/_includes/search.html
  • docs/_includes/sidebar-nav.html
  • docs/_includes/theme-toggle.html
  • docs/_layouts/default.html
  • docs/architecture/implementation-status.md
  • docs/architecture/overview.md
  • docs/assets/js/filters.js
  • docs/assets/js/search-index.json
  • docs/assets/js/search.js
  • docs/assets/js/theme.js
  • docs/assets/main.scss
  • docs/core-cli/debug-logging.md
  • docs/core-cli/init.md
  • docs/core-cli/modes.md
  • docs/core-cli/module.md
  • docs/core-cli/upgrade.md
  • docs/getting-started/README.md
  • docs/getting-started/installation.md
  • docs/getting-started/quickstart.md
  • docs/getting-started/where-to-start.md
  • docs/guides/ai-ide-workflow.md
  • docs/guides/ide-integration.md
  • docs/index.md
  • docs/migration/migration-guide.md
  • docs/module-system/bootstrap-checklist.md
  • docs/module-system/custom-registries.md
  • docs/module-system/installing-modules.md
  • docs/module-system/marketplace.md
  • docs/module-system/module-marketplace.md
  • docs/reference/authentication.md
  • docs/reference/bridge-registry.md
  • docs/reference/commands.md
  • docs/reference/documentation-url-contract.md
  • openspec/CHANGE_ORDER.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/CHANGE_VALIDATION.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/TDD_EVIDENCE.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/design.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/proposal.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/specs/core-docs-client-search/spec.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/specs/core-docs-data-driven-nav/spec.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/specs/core-docs-expertise-paths/spec.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/specs/core-docs-theme-toggle/spec.md
  • openspec/changes/docs-13-core-nav-search-theme-roles/tasks.md
  • scripts/check-docs-commands.py
  • tests/unit/docs/test_docs_validation_scripts.py
  • tests/unit/docs/test_release_docs_parity.py
  • tests/unit/test_core_docs_site_contract.py
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch dev

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

@djm81 djm81 self-assigned this Mar 28, 2026
@djm81 djm81 added documentation Improvements or additions to documentation enhancement New feature or request labels Mar 28, 2026
@djm81 djm81 moved this from Todo to In Progress in SpecFact CLI Mar 28, 2026
Comment thread tests/unit/test_core_docs_site_contract.py Fixed
@djm81 djm81 merged commit 835ffec into main Mar 28, 2026
24 checks passed
@github-project-automation github-project-automation bot moved this from In Progress to Done in SpecFact CLI Mar 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

[User Story] docs-13: Refine Core Docs UX With Data-Driven Navigation, Search, Theme, And Audience Paths

2 participants