Skip to content

Reframe SpecFact around validation evidence and AI-bloat defense#604

Merged
djm81 merged 492 commits into
mainfrom
codex/reposition-validation-roadmap
Jun 6, 2026
Merged

Reframe SpecFact around validation evidence and AI-bloat defense#604
djm81 merged 492 commits into
mainfrom
codex/reposition-validation-roadmap

Conversation

@djm81
Copy link
Copy Markdown
Collaborator

@djm81 djm81 commented Jun 6, 2026

Summary

  • Repositioned the core and modules OpenSpec roadmaps around validation evidence, drift detection, and AI-bloat defense.
  • Archived completed OpenSpec changes and parked upstream planning expansions that no longer fit the product thesis.
  • Added a living integration contract, refreshed the internal wiki mirrors, and renamed the key GitHub epics to match the new framing.

Testing

  • hatch run openspec validate --all --strict passed in the core repo.
  • hatch run openspec validate --all --strict passed in the modules worktree.
  • Clean-code review wrappers skipped for this change because no Python files were touched.

djm81 and others added 30 commits March 6, 2026 02:41
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 9 commits June 2, 2026 08:53
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
Copy link
Copy Markdown

strix-security Bot commented Jun 6, 2026

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
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Jun 6, 2026

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5e7ea65b-3608-40e3-9c25-ecf659773ff1

📥 Commits

Reviewing files that changed from the base of the PR and between 4081b54 and 4023d7d.

📒 Files selected for processing (15)
  • .agents/skills/openspec-workflows/references/create-change-from-plan.md
  • .agents/skills/openspec-workflows/references/validate-change.md
  • openspec/changes/ai-integration-02-mcp-server/design.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/changes/validation-02-full-chain-engine/proposal.md
  • openspec/specs/call-graph-analysis/spec.md
  • openspec/specs/command-package-runtime-validation/spec.md
  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/specs/dep-license-gate/spec.md
  • openspec/specs/installed-runtime-module-discovery/spec.md
  • openspec/specs/module-scope-diagnostics/spec.md
  • openspec/specs/project-artifact-write-safety/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
  • openspec/specs/upgrade-command/spec.md
  • openspec/specs/user-module-root/spec.md
✅ Files skipped from review due to trivial changes (6)
  • openspec/specs/module-scope-diagnostics/spec.md
  • openspec/specs/installed-runtime-module-discovery/spec.md
  • openspec/changes/ai-integration-02-mcp-server/design.md
  • openspec/specs/project-artifact-write-safety/spec.md
  • .agents/skills/openspec-workflows/references/validate-change.md
  • .agents/skills/openspec-workflows/references/create-change-from-plan.md
🚧 Files skipped from review as they are similar to previous changes (6)
  • openspec/specs/call-graph-analysis/spec.md
  • openspec/specs/command-package-runtime-validation/spec.md
  • openspec/specs/upgrade-command/spec.md
  • openspec/specs/user-module-root/spec.md
  • openspec/specs/dep-license-gate/spec.md
  • openspec/changes/validation-02-full-chain-engine/proposal.md
📜 Recent 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: Compatibility (Python 3.11)
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{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/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/specs/runtime-tool-probing/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/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/specs/runtime-tool-probing/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/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/specs/runtime-tool-probing/spec.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/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
🧠 Learnings (17)
📓 Common learnings
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Applies to openspec/**/{proposal.md,tasks.md,design.md,spec.md} : 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
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/session_startup_instructions.mdc:0-0
Timestamp: 2026-04-10T22:42:04.372Z
Learning: For OpenSpec changes when a sibling `specfact-cli-internal/` checkout exists, read internal wiki guidance in `docs/agent-rules/40-openspec-and-tdd.md` and consult `wiki/hot.md`, `wiki/graph.md`, and relevant `wiki/concepts/*.md` files
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-10T22:41:26.528Z
Learning: Enforce the clean-code review gate through `hatch run specfact code review run --json --out .specfact/code-review.json`
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T22:42:21.860Z
Learning: Perform `spec -> tests -> failing evidence -> code -> passing evidence` in that order for behavior changes
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-10T22:42:21.860Z
Learning: Fix SpecFact code review findings, including warnings, unless a rare explicit exception is documented
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: For changes created from plan documents, use `/specfact-cli/wf-create-change-from-plan <plan-path>` workflow to create OpenSpec proposals; the workflow includes plan selection, alignment review, integrity re-check, proposal creation, improvement, optional GitHub issue creation, and completion steps
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: For `/opsx:ff` (Fast-Forward Change Creation): OPSX provides change scaffolding and artifact templates. AGENTS.md requires explicitly adding: Worktree creation task as Step 1 in tasks.md (not just 'create branch'), TDD_EVIDENCE.md tracking task in section 2 (Tests), Documentation research task per `openspec/config.yaml`, Module signing quality gate if applicable, Worktree cleanup steps in final section
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Use `/opsx-explore` to research the codebase for conflicts and dependencies, then use `/opsx-new` or `/opsx:ff` to create the change proposal with unique verb-led change-id, scaffolded proposal.md, tasks.md, optional design.md, and spec deltas in changes/<id>/specs/<capability>/spec.md; validate with `openspec validate <id> --strict`
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Before implementing code changes, run `openspec validate <change-id> --strict` to validate the OpenSpec change and optionally run `/wf-validate-change <change-id>` for breaking-change and dependency analysis; do not proceed to implementation until validation passes or user explicitly overrides
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Applies to 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
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: When implementation is complete and merged, run `openspec archive <change-id>` from the repository root to merge delta specs into openspec/specs/ and move the change under openspec/changes/archive/; do not manually move folders or use --skip-specs or --no-validate without explicit user confirmation
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: For `/opsx:apply` (Implementation): OPSX provides task iteration and progress tracking. AGENTS.md requires verification before each task: Confirm you are IN a worktree (not primary checkout) before modifying code, Record failing test evidence in `TDD_EVIDENCE.md` BEFORE implementing, Record passing test evidence AFTER implementation, Run quality gates from worktree (format, type-check, contract-test), GPG-signed commits (`git commit -S`), PR to `dev` branch (never direct push)
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: Applies to openspec/changes/**/*.md : 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/`)
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: When implementation is complete and merged, run `openspec archive <change-id>` from the repository root to merge delta specs into openspec/specs/ and move the change under openspec/changes/archive/; do not manually move folders or use --skip-specs or --no-validate without explicit user confirmation

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
📚 Learning: 2026-04-10T22:42:04.372Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/session_startup_instructions.mdc:0-0
Timestamp: 2026-04-10T22:42:04.372Z
Learning: For OpenSpec changes when a sibling `specfact-cli-internal/` checkout exists, read internal wiki guidance in `docs/agent-rules/40-openspec-and-tdd.md` and consult `wiki/hot.md`, `wiki/graph.md`, and relevant `wiki/concepts/*.md` files

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
📚 Learning: 2026-04-10T22:41:19.090Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: Applies to openspec/changes/**/*.md : 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/`)

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Before implementing code changes, run `openspec validate <change-id> --strict` to validate the OpenSpec change and optionally run `/wf-validate-change <change-id>` for breaking-change and dependency analysis; do not proceed to implementation until validation passes or user explicitly overrides

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-04-10T22:41:19.090Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: For `/opsx:ff` (Fast-Forward Change Creation): OPSX provides change scaffolding and artifact templates. AGENTS.md requires explicitly adding: Worktree creation task as Step 1 in tasks.md (not just 'create branch'), TDD_EVIDENCE.md tracking task in section 2 (Tests), Documentation research task per `openspec/config.yaml`, Module signing quality gate if applicable, Worktree cleanup steps in final section

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-03-25T21:32:57.944Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/spec-fact-cli-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:57.944Z
Learning: Applies to docs/**/*.md : 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.

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: For changes created from plan documents, use `/specfact-cli/wf-create-change-from-plan <plan-path>` workflow to create OpenSpec proposals; the workflow includes plan selection, alignment review, integrity re-check, proposal creation, improvement, optional GitHub issue creation, and completion steps

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-03-25T21:33:15.296Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/testing-and-build-guide.mdc:0-0
Timestamp: 2026-03-25T21:33:15.296Z
Learning: Record the contract or property that supersedes a removed test in the PR description

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Applies to openspec/**/{proposal.md,tasks.md,design.md,spec.md} : 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

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: If the request is vague (contains 'intuitive', 'fast', 'better', 'improved') or if architecture patterns are unclear, ask for specific metrics, concrete behaviors, or clarification on scope and approach before creating the OpenSpec change

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-04-10T22:41:19.090Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-04-10T22:41:19.090Z
Learning: When creating implementation plans, task lists, or OpenSpec tasks.md, ALWAYS explicitly verify and include: (1) Worktree creation from `origin/dev` (not `git checkout -b`), (2) `hatch env create` in the worktree, (3) Pre-flight checks (`hatch run smart-test-status`, `hatch run contract-test-status`), (4) Worktree cleanup steps post-merge, (5) Self-check: 'Have I followed AGENTS.md Git Worktree Policy section?'

Applied to files:

  • openspec/specs/cross-change-integration-contract/spec.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Only one top-level header (H1) is allowed per document (MD025: Single H1 Header)

Applied to files:

  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines)

Applied to files:

  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Headers should increment by one level at a time (MD001: Header Increment)

Applied to files:

  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Lines should not have trailing spaces (MD009: No Trailing Spaces)

Applied to files:

  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
📚 Learning: 2026-04-10T22:41:54.436Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-04-10T22:41:54.436Z
Learning: Applies to 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

Applied to files:

  • openspec/specs/runtime-tool-probing/spec.md
🔀 Multi-repo context nold-ai/specfact-cli-modules

Linked repositories findings

nold-ai/specfact-cli-modules

  • Bridge sync reads OpenSpec proposals from openspec/changes/ and exposes include_archived behavior:
    • BridgeSync._read_openspec_change_proposals (definition, include_archived default = True) — [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync.py:488,502,504]
    • read_openspec_change_proposals implementation — [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_read_openspec_proposals.py:159]
  • Export/writeback and Source Tracking / issue-update paths that will be affected by changes to Source Tracking content or sanitization:
    • bridge sync export / issue update helpers and source-tracking updater — [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_export_one_proposal.py] [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_issue_update_impl.py] [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_issue_subhelpers.py]
    • docs instructing GitHub issue creation and writing Source Tracking into proposal.md — [::nold-ai/specfact-cli-modules::docs/adapters/github.md] [::nold-ai/specfact-cli-modules::docs/integrations/devops-adapter-overview.md]
  • Pre-commit / code-review gating and tests that treat openspec/changes files specially (TDD_EVIDENCE.md excluded):
    • Pre-commit check logic and paths (skips TDD_EVIDENCE.md; gates on openspec/changes/*) — [::nold-ai/specfact-cli-modules::scripts/pre_commit_code_review.py] [::nold-ai/specfact-cli-modules::scripts/pre-commit-quality-checks.sh]
    • Tests referencing openspec/changes paths and that mock/patch _read_openspec_change_proposals — many unit tests under tests/unit/sync_runtime/test_bridge_sync.py and tests/unit/scripts/test_pre_commit_code_review.py — [::nold-ai/specfact-cli-modules::tests/unit/sync_runtime/test_bridge_sync.py] [::nold-ai/specfact-cli-modules::tests/unit/scripts/test_pre_commit_code_review.py]
  • Docs, configs, and agent rules that encode filenames/guardrails and TDD/evidence workflows (worktree/TDD-first expectations, TDD_EVIDENCE.md locations):
    • agent/worktree and TDD docs and openspec/config.yaml references to TDD_EVIDENCE.md and archive semantics — [::nold-ai/specfact-cli-modules::docs/agent-rules/30-worktrees-and-branching.md] [::nold-ai/specfact-cli-modules::docs/agent-rules/40-openspec-and-tdd.md] [::nold-ai/specfact-cli-modules::openspec/config.yaml]
  • Consumers of evidence JSON shape: I did not find occurrences of the new "evidence_graph" field in this repo (no matches for evidence_graph), so callers that parse evidence artifacts here may not yet be updated — search returned no hits for evidence_graph in this repo. [::nold-ai/specfact-cli-modules::]

Direct impact summary / risks to verify

  • Archive/include semantics: bridge_sync and related flows assume archived proposals are excluded by default; PR archives many changes and may adjust include/archive semantics — confirm read_openspec_change_proposals include_archived default and any rename/move of archived paths. [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync.py]
  • Source Tracking / issue creation format: docs and bridge export/update code write/parse Source Tracking in proposal.md — confirm sanitization and format changes in PR match parsing and update logic in bridge_sync_issue_update_impl and related helpers. [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_issue_update_impl.py] [::nold-ai/specfact-cli-modules::docs/adapters/github.md]
  • Filenames / guardrails (proposal.md, tasks.md, TDD_EVIDENCE.md): pre-commit gates and tests rely on these names and skipping behavior; PR changes that rename or move these artifacts or change which files are considered "evidence" will require updating pre-commit logic and unit tests. [::nold-ai/specfact-cli-modules::scripts/pre_commit_code_review.py] [::nold-ai/specfact-cli-modules::tests/unit/sync_runtime/test_bridge_sync.py]
  • Evidence JSON schema (validation/evidence output): PR renames/reframes the evidence schema (evidence_graph). No evidence_graph consumers found in this repo — ensure any downstream parsing of prior full-chain evidence schema is updated or compatibility-layered. [::nold-ai/specfact-cli-modules::]
  • Tests: many unit tests patch _read_openspec_change_proposals; if the proposal layout, default include_archived, or proposal file structure changes, update tests accordingly. [::nold-ai/specfact-cli-modules::tests/unit/sync_runtime/test_bridge_sync.py]

If you want, I can:

  • Open specific files to show exact parsing logic for Source Tracking and archival filtering (e.g., bridge_sync_read_openspec_proposals.read_openspec_change_proposals) to pinpoint required updates.
  • List all unit tests that will break if proposal filenames or include_archived behavior change.
🔇 Additional comments (3)
openspec/specs/runtime-tool-probing/spec.md (1)

25-31: LGTM!

openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md (1)

60-60: LGTM!

openspec/specs/cross-change-integration-contract/spec.md (1)

4-9: LGTM!


📝 Walkthrough

Walkthrough

This PR adds OpenSpec workflow playbooks (create/validate), rewrites roadmap and integration contracts, narrows multiple proposals toward validation-evidence/adapter semantics, parks intent-skill work, and adds many specification documents for CLI behavior, module lifecycle, dependency/security gates, telemetry, and write-safety.

Changes

OpenSpec Workflow & Governance

Layer / File(s) Summary
OpenSpec workflow skill and references
.agents/skills/openspec-workflows/SKILL.md, .agents/skills/openspec-workflows/references/create-change-from-plan.md, .agents/skills/openspec-workflows/references/validate-change.md
Adds SKILL.md and two procedural references describing create-from-plan and validate-change workflows with guarded dry-run simulation, structured validation (openspec validate --strict), templated CHANGE_VALIDATION.md output, and GitHub issue creation for public targets.
Roadmap and integration contract
openspec/CHANGE_ORDER.md, openspec/INTEGRATION.md
Rewrites CHANGE_ORDER (tracks, waves, exit gates) and introduces INTEGRATION.md with ownership, compatibility rules, wave gates, and pre-implementation governance checks.
Product messaging & parking
README.md, docs/index.md, openspec/parking-lot/*
Updates messaging to emphasize consuming upstream planning inputs for validation; moves ai-integration-04 to parked status and updates parking-lot triggers and lists.

Validation Evidence Spine

Layer / File(s) Summary
Validation evidence graph & governance output
openspec/changes/validation-02-full-chain-engine/*, openspec/changes/governance-01-evidence-output/proposal.md
Reframes full-chain engine into a Validation Evidence Graph, updates evidence output to an evidence_graph shape, and adjusts CLI flags/ownership mapping for evidence artifact generation.
Artifact Evidence Index / adapters
openspec/changes/traceability-01-index-and-orphans/proposal.md, openspec/changes/openspec-01-intent-trace/proposal.md
Replaces intent-trace import with an optional OpenSpec/Spec Kit evidence adapter and specifies an artifact evidence index with orphan/drift classifications and JSON export for downstream engines.
Opt-in validation telemetry
openspec/changes/telemetry-01-opentelemetry-default-on/*
Converts telemetry to opt-in validation-outcome reporting with bounded fields (command_family, validation_surface, modules_composed, optional failure_class), local audit log, and explicit disallowed data categories.

Feature Scope Reframes

Layer / File(s) Summary
AI integrations narrowed
openspec/changes/ai-integration-0*-*
Narrows agent-skill, MCP server, and instruction-file proposals to validation-focused behaviors, minimal MCP tool surface, and updated capability names/dependencies.
Architecture boundary review
openspec/changes/architecture-0*-*
Shifts architecture proposals to boundary-validation inputs and architecture-review findings; makes architecture optional in review envelopes.
Requirements & profiles
openspec/changes/requirements-0*-*, openspec/changes/profile-01-config-layering/proposal.md
Reframes requirements model into evidence-input models, converts backlog sync to read-first drift evidence, and narrows profile layering to validation-config semantics.
Dogfooding: AI-bloat defense proof
openspec/changes/dogfooding-01-full-chain-e2e-proof/*
Retargets dogfooding proof to an auditable validation + AI-bloat remediation loop producing JSON evidence, remediation packets, and rerun comparison artifacts.

Specification additions and edits

Layer / File(s) Summary
CLI and command artifacts
openspec/specs/cli-error-guidance/spec.md, openspec/specs/generated-command-overview/spec.md, openspec/specs/core-cli-reference/spec.md, openspec/specs/command-package-runtime-validation/spec.md, openspec/specs/upgrade-command/spec.md
Adds CLI error-guidance scenarios, deterministic generated command-overview artifacts with freshness checks, expanded init/IDE export requirements, runtime launcher matrix validation and pipx recovery/upgrade behavior.
Module lifecycle, discovery, and safety
openspec/specs/module-installation/spec.md, openspec/specs/module-packages/spec.md, openspec/specs/module-scope-diagnostics/spec.md, openspec/specs/installed-runtime-module-discovery/spec.md, openspec/specs/init-module-state/spec.md
Adds reconciled install semantics, versioned dependency registration rules, module-scope diagnostics (specfact module doctor), installed-runtime discovery expectations, and profile-aware init-module refresh behavior.
IDE prompts & write-safety
openspec/specs/init-ide-prompt-source-selection/spec.md, openspec/specs/module-owned-ide-prompts/spec.md, openspec/specs/project-artifact-write-safety/spec.md
Specifies VS Code settings reconciliation rules, safe-write semantics for module-owned IDE assets, and project artifact write-safety modes with CI gate guidance.
CI, deps, license/security gates, runtime probing
openspec/specs/ci-integration/spec.md, openspec/specs/dep-license-gate/spec.md, openspec/specs/dependency-resolution/spec.md, openspec/specs/runtime-tool-probing/spec.md
Adds CI package-manager smoke-test matrix gating PR merges, license-compliance and security-audit gates, license filtering for resolved pip packages and dev-extras rules, and runtime tool probing prioritizing active execution context.
Docs schema & call graph
openspec/specs/doc-frontmatter-*.md, openspec/specs/call-graph-analysis/spec.md
Normalizes frontmatter headings and adds optional pycg-based call-graph analysis spec with graceful fallback behavior.
Archived requirement headers
openspec/changes/archive/*/specs/*/spec.md
Standardizes archived spec headings to ADDED/MODIFIED markers where applicable.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

Possibly related PRs

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/reposition-validation-roadmap

@djm81 djm81 marked this pull request as ready for review June 6, 2026 21:41
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 6, 2026

SpecFact CLI Validation Report

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

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

ℹ️ 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 .agents/skills/openspec-workflows/references/create-change-from-plan.md Outdated
Comment thread openspec/CHANGE_ORDER.md Outdated
@djm81 djm81 self-assigned this Jun 6, 2026
@djm81 djm81 added documentation Improvements or additions to documentation change-proposal Proposal for a new change architecture Architecture and design changes labels Jun 6, 2026
@djm81 djm81 moved this from Todo to In Progress in SpecFact CLI Jun 6, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 6, 2026

SpecFact CLI Validation Report

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

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

Caution

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

⚠️ Outside diff range comments (2)
openspec/changes/validation-02-full-chain-engine/tasks.md (1)

3-32: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Task checklist is missing required workflow guardrails.

This tasks file omits required implementation-plan items that your OpenSpec workflow expects (explicit hatch env create, pre-flight status checks, and final worktree cleanup/module-signing closure tasks). Without them, execution can drift from the enforced delivery contract.

Based on learnings: “When creating implementation plans, task lists, or OpenSpec tasks.md, ALWAYS explicitly verify and include: (1) Worktree creation from origin/dev, (2) hatch env create, (3) pre-flight checks, (4) worktree cleanup steps post-merge.”

🤖 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 `@openspec/changes/validation-02-full-chain-engine/tasks.md` around lines 3 -
32, Update the tasks checklist in
openspec/changes/validation-02-full-chain-engine/tasks.md to add the missing
workflow guardrails: under "1. Branch and dependency guardrails" add an explicit
item to create the worktree from origin/dev (e.g., `scripts/worktree.sh create
...` referencing the existing 1.1), add a top-level pre-implementation step for
`hatch env create` (can be placed in section 2 or as a new 0.x pre-flight
block), insert pre-flight status checks (validate branch, CI, and dependency
prerequisites) before implementation (referencing the 2.x test-prep area), and
add post-delivery cleanup and module-signing/closure tasks (worktree cleanup,
branch deletion, and module-signing confirmation) in section 5 so the plan
enforces creation, environment setup, pre-flight checks, and final
cleanup/signing.

Source: Learnings

openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md (1)

3-26: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the required worktree pre-flight and cleanup gates to the task plan.

This checklist omits required execution gates (env bootstrap, pre-flight status checks, and cleanup/self-check), so implementers can run the flow in an inconsistent state and miss required quality evidence.

Proposed task patch
 ## 1. Branch and proof setup

 - [ ] 1.1 Create dedicated worktree branch `feature/dogfooding-01-full-chain-e2e-proof` from `dev`: `scripts/worktree.sh create feature/dogfooding-01-full-chain-e2e-proof`.
+- [ ] 1.1.1 Run `hatch env create` inside the worktree.
+- [ ] 1.1.2 Run pre-flight checks: `hatch run smart-test-status` and `hatch run contract-test-status`.
 - [ ] 1.2 Select and document the canonical PR or demo repository slice for proof.
 - [ ] 1.3 Capture the baseline command sequence, JSON output path, and evidence comparison criteria.
@@
 ## 4. Delivery
@@
 - [ ] 4.3 Open PR to `dev` with dogfooding evidence package.
+- [ ] 4.4 Run worktree cleanup after merge and record completion.
+- [ ] 4.5 Add explicit self-check note: AGENTS.md Git Worktree Policy complied.

Based on learnings: task plans must explicitly include worktree creation/usage gates, hatch env create, smart-test-status, contract-test-status, and cleanup/self-check steps.

🤖 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 `@openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md` around lines 3
- 26, The checklist is missing pre-flight/bootstrap and cleanup gates; update
the tasks in sections 1–4 (e.g., around items 1.1, 2.1, 3.1, 4.2) to explicitly
run and validate: worktree pre-flight (create/select/verify branch/worktree),
env bootstrap via hatch env create, pre-run status checks smart-test-status and
contract-test-status before tests/evidence generation, and a post-run
cleanup/self-check step that validates artifacts and tears down environments;
add these steps as required gates in the relevant numbered tasks so the flow
cannot proceed without passing each gate.

Sources: Coding guidelines, Learnings

🤖 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 @.agents/skills/openspec-workflows/references/create-change-from-plan.md:
- Around line 284-303: The unlabeled fenced code block containing the change
metadata (the block beginning with "Change ID: <change-id>" and the subsequent
YAML-like fields) must include a language identifier to satisfy MD040; update
that block to use an appropriate language tag (e.g., add "yaml" after the
opening backticks so it reads as a YAML fenced block) so the markdown linter
recognizes the language for the example.
- Around line 151-153: Replace the existing venv bootstrap step ("1.1.4 Create a
virtual environment: `python -m venv .venv && source .venv/bin/activate && pip
install -e \"[dev]\"`") with the AGENTS-compliant Hatch bootstrap and pre-flight
checks: run `hatch env create` followed by `hatch run smart-test-status` and
`hatch run contract-test-status`, and update any generated task output (e.g.,
the tasks.md sequence produced by this workflow) to reflect those Hatch commands
instead of the python venv commands so the workflow and worktree flow (hatch env
create → hatch run smart-test-status → hatch run contract-test-status) are
enforced.

In @.agents/skills/openspec-workflows/references/validate-change.md:
- Around line 147-159: The two unlabeled fenced code blocks showing the "Change
Validation Report: <change-id>" example and the second example (the block
starting with the same "Change Validation Report" content around the later
example) must include a language label to satisfy MD040; update each opening
fence from "```" to a labeled fence such as "```text" (or a more specific
language like "```yaml" if appropriate) so both fenced blocks are annotated and
pass markdown-lint checks.
- Around line 37-39: Update the "Check change status" step so it does not
require status "done" for proposal-stage validation: modify the guidance around
the openspec command (openspec status --change "<change-id>" --json) to verify
that the change and required artifacts exist and are not in an error/rejected
state, but do not insist the status equals "done"; adjust the text under the
"Check change status" heading to accept in-progress statuses (e.g., "proposed",
"in-review") and only fail on missing or explicitly rejected statuses.

In `@openspec/changes/ai-integration-02-mcp-server/design.md`:
- Around line 43-44: The dependency summary line uses shorthand labels; replace
them with the canonical change IDs used elsewhere: use
ai-integration-01-agent-skill, governance-01-evidence-output, and
validation-02-full-chain-engine (instead of governance-01 and validation-02 user
pull) so tooling and ordering consume stable identifiers; update the dependency
summary text in design.md to list those exact canonical IDs.

In
`@openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md`:
- Line 60: The file contains a duplicate second-level heading "## ADDED
Requirements" (the same text appears at Line 1 and Line 60), triggering
markdownlint MD024; to fix it, either remove or merge the duplicate heading into
the existing "## ADDED Requirements" section or rename the second occurrence to
a unique title (e.g., "## Additional Requirements" or "## ADDED - Supplemental
Requirements") so that only one identical H2 remains; update any surrounding
content to reflect the chosen merge/rename so the section flow remains correct.

In `@openspec/changes/validation-02-full-chain-engine/proposal.md`:
- Around line 39-41: The proposal weakens a required compatibility alias by
changing `--full-chain` to "MAY expose", which breaks existing tests/docs that
still use `--full-chain`; update the wording so `--full-chain` remains a
REQUIRED transition contract (e.g., change back to "SHALL expose a compatibility
alias `--full-chain`") and clarify that the internal implementation and evidence
schema still use validation graph terminology, ensuring consumers, tests, and
downstream docs keep supporting the `--full-chain` CLI alias while allowing
internal terminology to be validation graph-based.

In `@openspec/specs/call-graph-analysis/spec.md`:
- Line 8: Update the call-graph spec text to match the actual dependency
license: replace occurrences that state `pycg` is "MIT-licensed" or describe the
call-graph capability as provided by `pycg (MIT)" with "Apache-2.0" so the spec
aligns with `pyproject.toml` which pins `pycg==0.0.7` under Apache-2.0; search
for the literal `pycg` mentions in the spec (including the sentence beginning
with "The system SHALL provide optional call-graph analysis..." and the later
phrase that currently annotates `pycg` as MIT) and change the license token to
`Apache-2.0`.

In `@openspec/specs/command-package-runtime-validation/spec.md`:
- Around line 124-131: The spec for pipx stale-launcher repair is duplicated
under command-package-runtime-validation but missing from the upgrade-command
spec, causing contract drift; consolidate the behavior by moving or copying the
"Pipx upgrade validates and repairs stale launcher" scenario (the steps invoking
`specfact upgrade`, `pipx upgrade specfact-cli`, the fallback `pipx reinstall
specfact-cli`, and revalidation of `specfact --version`) into
openspec/specs/upgrade-command/spec.md (or ensure upgrade-command includes an
equivalent scenario) so the upgrade-command spec owns this recovery path and
both specs reference the same authoritative scenario text.

In `@openspec/specs/cross-change-integration-contract/spec.md`:
- Line 4: Replace the placeholder "TBD - created by archiving change
integration-01-cross-change-contracts. Update Purpose after archive." with a
finalized Purpose paragraph for the cross-change-integration-contract spec:
update the top-level "Purpose" section to clearly state the contract's intent,
scope, expected consumers (e.g., repo/tooling modules), and desired semantic
guarantees (e.g., deterministic interpretation across repos, backward
compatibility expectations), and ensure the new Purpose text is concise,
canonical, and unambiguous so downstream implementers and parsers can rely on
consistent OpenSpec semantics.

In `@openspec/specs/dep-license-gate/spec.md`:
- Around line 104-110: The document currently contradicts itself by saying the
license and security gates "SHALL" run on every PR while the "Scenario: License
gate runs in CI on dependency changes" only triggers on PRs that modify
pyproject.toml and meet the PR orchestrator's non-documentation filter; pick one
model and make the wording consistent: either change the requirement text
referencing "every PR" to scope both gates to dependency changes (e.g., "SHALL
be integrated into the project's CI workflow as separate steps that run on pull
requests that modify dependency manifests such as pyproject.toml") or broaden
the scenario to remove the pyproject.toml + filter condition so the license
compliance gate (license compliance gate / scripts/check_license_compliance.py)
and security audit gate run on every PR. Ensure the phrase "license compliance
gate" and the scenario header "Scenario: License gate runs in CI on dependency
changes" are updated to match the chosen trigger model.

In `@openspec/specs/installed-runtime-module-discovery/spec.md`:
- Line 5: Replace the placeholder "TBD" in the Purpose section of the spec (the
Purpose heading in openspec/specs/installed-runtime-module-discovery/spec.md)
with a concise authoritative purpose statement that describes the goal of the
spec (what installed runtime module discovery must achieve, its scope and
intended consumers), include one sentence of rationale and one-line acceptance
criteria or traceability note; update the Purpose paragraph so it is specific,
actionable, and no longer ambiguous for downstream consumers/tests.

In `@openspec/specs/module-scope-diagnostics/spec.md`:
- Line 4: Replace the placeholder Purpose paragraph that currently reads "TBD -
created by archiving change module-scope-version-diagnostics. Update Purpose
after archive." with a concrete Purpose section that clearly states the intent,
ownership, and scope of the new behavioral contracts; edit the "Purpose" heading
(search for the literal "Purpose" and the "TBD - created by archiving change
module-scope-version-diagnostics" line) to provide an explicit, auditable
description aligned with OpenSpec guidelines before merging.

In `@openspec/specs/project-artifact-write-safety/spec.md`:
- Line 4: Replace the "TBD - created by archiving change
profile-04-safe-project-artifact-writes. Update Purpose after archive."
placeholder in the Purpose section of the spec
(openspec/specs/project-artifact-write-safety/spec.md) with a clear, final
Purpose that states the intent to prevent data loss during project artifact
writes, defines the scope (which artifacts and operations are covered), lists
expected safety behaviors (e.g., atomic writes, validation, retries, rollback on
failure), and notes traceability to CI gates and implementation audits so
requirements, tests, and audits can be mapped back to this Purpose.

In `@openspec/specs/runtime-tool-probing/spec.md`:
- Around line 27-30: The spec mixes pipx with env-managers which is inconsistent
with the env_manager.py probing contract; either tighten the scenario to target
env-manager diagnostics only (e.g., mention only "hatch, uv" and state the
diagnostic must come from env_manager.py's probe implementation), or split into
two concrete scenarios: one that tests env-manager diagnostics emitted by
env_manager.py (for hatch/uv) and a separate scenario that tests
installer-specific hints for installers like pip and pipx; update the wording so
each testable requirement maps to a single diagnostic source (env_manager.py for
env managers or the installer-specific probe for pip/pipx).

In `@openspec/specs/upgrade-command/spec.md`:
- Around line 7-35: Add a new scenario covering the pipx stale-launcher
recovery: when `specfact upgrade` detects a pipx installation and `pipx upgrade
specfact-cli` fails due to a stale launcher, the upgrade SHALL run `pipx
reinstall specfact-cli` and then re-validate the launcher; the spec must state
that on successful reinstall the stale-launcher warning is suppressed and
upgrade reports success, while on reinstall failure the child-process
stdout/stderr diagnostics from `pipx reinstall specfact-cli` are preserved and
surfaced and the upgrade reports failure (and any partial output produced before
a timeout is replayed if the reinstall times out).

In `@openspec/specs/user-module-root/spec.md`:
- Around line 292-295: The scenario mixes two identifiers (<module-name> and
<module-id>) for the same entity; pick one token and use it consistently
throughout the GIVEN/WHEN/THEN steps (e.g., replace all occurrences of
<module-name> with <module-id> or vice versa) so the acceptance criteria and
automation mapping are unambiguous, ensuring the same identifier is used in the
paths (`<repo>/.specfact/modules/...`, `<user-home>/.specfact/modules/...`) and
the command (`specfact module install <module-id> --scope user`) as well as in
the THEN clause that checks the user-scope target root decision.

---

Outside diff comments:
In `@openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md`:
- Around line 3-26: The checklist is missing pre-flight/bootstrap and cleanup
gates; update the tasks in sections 1–4 (e.g., around items 1.1, 2.1, 3.1, 4.2)
to explicitly run and validate: worktree pre-flight (create/select/verify
branch/worktree), env bootstrap via hatch env create, pre-run status checks
smart-test-status and contract-test-status before tests/evidence generation, and
a post-run cleanup/self-check step that validates artifacts and tears down
environments; add these steps as required gates in the relevant numbered tasks
so the flow cannot proceed without passing each gate.

In `@openspec/changes/validation-02-full-chain-engine/tasks.md`:
- Around line 3-32: Update the tasks checklist in
openspec/changes/validation-02-full-chain-engine/tasks.md to add the missing
workflow guardrails: under "1. Branch and dependency guardrails" add an explicit
item to create the worktree from origin/dev (e.g., `scripts/worktree.sh create
...` referencing the existing 1.1), add a top-level pre-implementation step for
`hatch env create` (can be placed in section 2 or as a new 0.x pre-flight
block), insert pre-flight status checks (validate branch, CI, and dependency
prerequisites) before implementation (referencing the 2.x test-prep area), and
add post-delivery cleanup and module-signing/closure tasks (worktree cleanup,
branch deletion, and module-signing confirmation) in section 5 so the plan
enforces creation, environment setup, pre-flight checks, and final
cleanup/signing.
🪄 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: c842bf9a-9bc2-4629-a07f-301591c51e81

📥 Commits

Reviewing files that changed from the base of the PR and between 809ce53 and bd26c1f.

📒 Files selected for processing (129)
  • .agents/skills/openspec-workflows/SKILL.md
  • .agents/skills/openspec-workflows/references/create-change-from-plan.md
  • .agents/skills/openspec-workflows/references/validate-change.md
  • README.md
  • docs/index.md
  • openspec/CHANGE_ORDER.md
  • openspec/INTEGRATION.md
  • openspec/changes/ai-integration-01-agent-skill/design.md
  • openspec/changes/ai-integration-01-agent-skill/proposal.md
  • openspec/changes/ai-integration-02-mcp-server/design.md
  • openspec/changes/ai-integration-02-mcp-server/proposal.md
  • openspec/changes/ai-integration-03-instruction-files/proposal.md
  • openspec/changes/ai-integration-04-intent-skills/proposal.md
  • openspec/changes/architecture-01-solution-layer/proposal.md
  • openspec/changes/architecture-02-well-architected-review/proposal.md
  • openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/proposal.md
  • openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/specs/upgrade-command/spec.md
  • openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/tasks.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/.openspec.yaml
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/design.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/proposal.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/call-graph-analysis/spec.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dep-license-gate/spec.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dependency-resolution/spec.md
  • openspec/changes/archive/2026-06-06-dep-security-cleanup/tasks.md
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/.openspec.yaml
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/CHANGE_VALIDATION.md
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/design.md
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/proposal.md
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md
  • openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/tasks.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/.openspec.yaml
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/design.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/proposal.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/init-module-state/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/user-module-root/spec.md
  • openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/tasks.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/.openspec.yaml
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/design.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/proposal.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-installation/spec.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-packages/spec.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-scope-diagnostics/spec.md
  • openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/tasks.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/.openspec.yaml
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/design.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/proposal.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md
  • openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/tasks.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/.openspec.yaml
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/proposal.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/environment-manager-detection/spec.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/installed-runtime-module-discovery/spec.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-installation/spec.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-owned-ide-prompts/spec.md
  • openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/tasks.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/.openspec.yaml
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/proposal.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/ci-integration/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/cli-error-guidance/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/command-package-runtime-validation/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/core-cli-reference/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/generated-command-overview/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/runtime-tool-probing/spec.md
  • openspec/changes/archive/2026-06-06-tester-cli-reliability/tasks.md
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/.openspec.yaml
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/TDD_EVIDENCE.md
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/design.md
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/proposal.md
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/specs/upgrade-command/spec.md
  • openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/tasks.md
  • openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md
  • openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md
  • openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md
  • openspec/changes/governance-01-evidence-output/proposal.md
  • openspec/changes/openspec-01-intent-trace/proposal.md
  • openspec/changes/profile-01-config-layering/proposal.md
  • openspec/changes/requirements-01-data-model/proposal.md
  • openspec/changes/requirements-02-module-commands/proposal.md
  • openspec/changes/requirements-03-backlog-sync/proposal.md
  • openspec/changes/telemetry-01-opentelemetry-default-on/design.md
  • openspec/changes/telemetry-01-opentelemetry-default-on/proposal.md
  • openspec/changes/traceability-01-index-and-orphans/proposal.md
  • openspec/changes/validation-02-full-chain-engine/design.md
  • openspec/changes/validation-02-full-chain-engine/proposal.md
  • openspec/changes/validation-02-full-chain-engine/tasks.md
  • openspec/parking-lot/README.md
  • openspec/parking-lot/ai-integration-04-intent-skills/.openspec.yaml
  • openspec/parking-lot/ai-integration-04-intent-skills/CHANGE_VALIDATION.md
  • openspec/parking-lot/ai-integration-04-intent-skills/design.md
  • openspec/parking-lot/ai-integration-04-intent-skills/proposal.md
  • openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-intent-workflow/spec.md
  • openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-spec-intelligence/spec.md
  • openspec/parking-lot/ai-integration-04-intent-skills/tasks.md
  • openspec/specs/call-graph-analysis/spec.md
  • openspec/specs/ci-integration/spec.md
  • openspec/specs/cli-error-guidance/spec.md
  • openspec/specs/command-package-runtime-validation/spec.md
  • openspec/specs/core-cli-reference/spec.md
  • openspec/specs/cross-change-integration-contract/spec.md
  • openspec/specs/dep-license-gate/spec.md
  • openspec/specs/dependency-resolution/spec.md
  • openspec/specs/doc-frontmatter-schema/spec.md
  • openspec/specs/doc-frontmatter-validation/spec.md
  • openspec/specs/docs-contributing-updates/spec.md
  • openspec/specs/environment-manager-detection/spec.md
  • openspec/specs/generated-command-overview/spec.md
  • openspec/specs/init-ide-prompt-source-selection/spec.md
  • openspec/specs/init-module-state/spec.md
  • openspec/specs/installed-runtime-module-discovery/spec.md
  • openspec/specs/module-installation/spec.md
  • openspec/specs/module-owned-ide-prompts/spec.md
  • openspec/specs/module-packages/spec.md
  • openspec/specs/module-scope-diagnostics/spec.md
  • openspec/specs/project-artifact-write-safety/spec.md
  • openspec/specs/runtime-tool-probing/spec.md
  • openspec/specs/upgrade-command/spec.md
  • openspec/specs/user-module-root/spec.md
💤 Files with no reviewable changes (1)
  • openspec/changes/ai-integration-04-intent-skills/proposal.md

Comment thread .agents/skills/openspec-workflows/references/create-change-from-plan.md Outdated
Comment thread .agents/skills/openspec-workflows/references/create-change-from-plan.md Outdated
Comment thread .agents/skills/openspec-workflows/references/validate-change.md
Comment thread .agents/skills/openspec-workflows/references/validate-change.md Outdated
Comment thread openspec/changes/ai-integration-02-mcp-server/design.md Outdated
Comment thread openspec/specs/module-scope-diagnostics/spec.md Outdated
Comment thread openspec/specs/project-artifact-write-safety/spec.md Outdated
Comment thread openspec/specs/runtime-tool-probing/spec.md Outdated
Comment thread openspec/specs/upgrade-command/spec.md
Comment thread openspec/specs/user-module-root/spec.md Outdated
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 6, 2026

SpecFact CLI Validation Report

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

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 6, 2026

SpecFact CLI Validation Report

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

@djm81 djm81 merged commit 4d7431a into main Jun 6, 2026
25 checks passed
@github-project-automation github-project-automation Bot moved this from In Progress to Done in SpecFact CLI Jun 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

architecture Architecture and design changes change-proposal Proposal for a new change documentation Improvements or additions to documentation

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant