diff --git a/.agents/skills/openspec-workflows/SKILL.md b/.agents/skills/openspec-workflows/SKILL.md new file mode 100644 index 00000000..c3f973ff --- /dev/null +++ b/.agents/skills/openspec-workflows/SKILL.md @@ -0,0 +1,66 @@ +--- +name: openspec-workflows +description: Create OpenSpec changes from implementation plans, and validate existing changes before implementation. Use when the user wants to turn a plan document into an OpenSpec change proposal, or validate that a change is safe to implement (breaking changes, dependency analysis). +license: MIT +metadata: + author: openspec + version: "1.0" +--- + +Two workflows for managing OpenSpec changes at the proposal stage. + +**Input**: Optionally specify a workflow name (`create` or `validate`) and a target (plan path or change ID). If omitted, ask the user which workflow they need. + +## Workflow Selection + +Determine which workflow to run: + +| User Intent | Workflow | Reference | +|---|---|---| +| Turn a plan into an OpenSpec change | **Create Change from Plan** | `references/create-change-from-plan.md` | +| Validate a change before implementation | **Validate Change** | `references/validate-change.md` | + +If the user's intent is unclear, use **AskUserQuestion** to ask which workflow they need. + +## Create Change from Plan + +Turns an implementation plan document into a fully formed OpenSpec change with proposal, specs, design, and tasks — including GitHub issue creation for public repos. + +**When to use**: The user has a plan document (typically in `specfact-cli-internal/docs/internal/implementation/`) and wants to create an OpenSpec change from it. + +**Load** `references/create-change-from-plan.md` and follow the full workflow. + +**Key steps**: +1. Select and parse the plan document +2. Cross-reference against existing plans and validate targets +3. Resolve any issues interactively +4. Create the OpenSpec change via `opsx:ff` skill +5. Review and improve: enforce TDD-first, add git worktree tasks (worktree creation first, PR last, cleanup after merge), validate against `openspec/config.yaml` +6. Create GitHub issue (public repos only) + +## Validate Change + +Performs dry-run simulation to detect breaking changes, analyze dependencies, and verify format compliance before implementation begins. + +**When to use**: The user wants to validate that an existing change is safe to implement — check for breaking interface changes, missing dependency updates, and format compliance. + +**Load** `references/validate-change.md` and follow the full workflow. + +**Key steps**: +1. Select the change (by ID or interactive list) +2. Parse all change artifacts (proposal, tasks, design, spec deltas) +3. Simulate interface changes in a temporary workspace +4. Analyze dependencies and detect breaking changes +5. Present findings and get user decision if breaking changes found +6. Run `openspec validate --strict` +7. Create `CHANGE_VALIDATION.md` report + +## Guardrails + +- Read `openspec/config.yaml` for project context and rules +- Read `AGENTS.md` for project conventions +- Never modify production code during validation — use temp workspaces +- Never proceed with ambiguities — ask for clarification +- Enforce TDD-first ordering in tasks (per config.yaml) +- Enforce git worktree workflow: worktree creation first task, PR creation last task, worktree cleanup after merge — never switch the primary checkout away from `dev` +- Only create GitHub issues in the target repository specified by the plan diff --git a/.agents/skills/openspec-workflows/references/create-change-from-plan.md b/.agents/skills/openspec-workflows/references/create-change-from-plan.md new file mode 100644 index 00000000..4efa594d --- /dev/null +++ b/.agents/skills/openspec-workflows/references/create-change-from-plan.md @@ -0,0 +1,314 @@ +# Workflow: Create OpenSpec Change from Plan + +## Table of Contents + +- [Guardrails](#guardrails) +- [Step 1: Plan Selection](#step-1-plan-selection) +- [Step 2: Plan Review and Alignment](#step-2-plan-review-and-alignment) +- [Step 3: Integrity Re-Check](#step-3-integrity-re-check) +- [Step 4: OpenSpec Change Creation](#step-4-openspec-change-creation) +- [Step 5: Proposal Review and Improvement](#step-5-proposal-review-and-improvement) +- [Step 6: GitHub Issue Creation](#step-6-github-issue-creation) +- [Step 7: Create GitHub Issue via gh CLI](#step-7-create-github-issue-via-gh-cli) +- [Step 8: Completion](#step-8-completion) + +## Guardrails + +- Read `openspec/config.yaml` during the workflow (before or at Step 5) for project context and TDD/SDD rules. +- Favor straightforward, minimal implementations. Keep changes tightly scoped. +- Never proceed with ambiguities or conflicts — ask for clarification interactively. +- Do not write code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, spec deltas). +- Always validate alignment against existing plans and implementation reality before proceeding. +- **CRITICAL**: Only create GitHub issues in the target repository specified by the plan. +- **CRITICAL Git Workflow (Worktree Policy)**: Use git worktrees for parallel development — never switch the primary checkout away from `dev`. Add a worktree creation task as the FIRST task, and PR creation as the LAST task. Never work on protected branches (`main`/`dev`) directly. Branch naming: `/`. Worktree path: `../specfact-cli-worktrees//`. All subsequent tasks execute inside the worktree directory. +- **CRITICAL TDD**: Per config.yaml, test tasks MUST come before implementation tasks. + +## Step 1: Plan Selection + +**If plan path provided**: Resolve to absolute path, verify file exists. + +**If no plan path provided**: +1. Search for plans in: + - `specfact-cli-internal/docs/internal/brownfield-strategy/` (`*.md`) + - `specfact-cli-internal/docs/internal/implementation/` (`*.md`) + - `specfact-cli/docs/` (if accessible) +2. Display numbered list with file path, title (first heading), last modified date. +3. Prompt user to select. + +## Step 2: Plan Review and Alignment + +### 2.1: Read and Parse Plan + +1. Read plan file completely. +2. Extract: + - Title and purpose (first H1) + - **Target repository** (look for `**Repository**:` in header metadata, e.g. `` `nold-ai/specfact-cli` ``) + - Phases/tasks with descriptions + - Files to create/modify (note repository prefixes) + - Dependencies, success metrics, estimated effort +3. Identify referenced targets (files, directories, repositories). + +### 2.2: Cross-Reference Check + +1. Search `specfact-cli-internal/docs/internal/brownfield-strategy/` for overlapping plans. +2. Search `specfact-cli-internal/docs/internal/implementation/` for conflicting implementation plans. +3. Extract conflicting info, overlapping scope, dependency relationships, timeline conflicts. + +### 2.3: Target Validation + +For each target in the plan: +- **Files**: Check existence, readability, location, structure matches assumptions. +- **Directories**: Check existence, structure. +- **Repositories**: Verify in workspace, structure matches, access ok. +- **Code refs**: Verify functions/classes exist, structure matches. + +### 2.4: Alignment Analysis + +Check: +1. **Accuracy**: File paths correct? Repos referenced accurately? Commands valid? +2. **Correctness**: Technical details accurate? Implementation approaches align with codebase? +3. **Ambiguities**: Unclear requirements, vague acceptance criteria, missing context. +4. **Conflicts**: With other plans, overlapping scope, timeline/resource conflicts. +5. **Consistency**: With CLAUDE.md conventions, OpenSpec conventions, existing patterns. + +### 2.5: Issue Detection and Interactive Resolution + +**If issues found**: +1. Categorize: Critical (must resolve), Warning (should resolve), Info (non-blocking). +2. Present: `[CRITICAL/WARNING/INFO] : ` with context and suggested resolutions. +3. Resolve interactively: For critical issues, prompt for clarification. For warnings, ask resolve or skip. +4. Re-validate after resolution. Loop until all critical issues resolved. + +## Step 3: Integrity Re-Check + +1. Re-run all checks from Step 2 with updated understanding. +2. Verify user clarifications are consistent. +3. Check for new issues introduced by clarifications. +4. If misalignments remain, go back to Step 2.5. + +## Step 4: OpenSpec Change Creation + +### 4.1: Determine Change Name + +1. Extract from plan title, convert to kebab-case. +2. Ensure unique (check existing changes in `openspec/changes/`). + +### 4.2: Execute OPSX Fast-Forward + +Invoke the `opsx:ff` skill with the change name: +- Use the plan as source of requirements. +- Map plan phases/tasks to OpenSpec capabilities. +- The opsx:ff workflow creates: change directory, proposal.md, specs/, design.md, tasks.md. +- It reads `openspec/config.yaml` for project context and per-artifact rules. + +### 4.3: Extract Change ID + +1. Identify created change ID. +2. Verify change directory: `openspec/changes//`. +3. Verify artifacts created: proposal.md, tasks.md, specs/. + +## Step 5: Proposal Review and Improvement + +### 5.1: Review Against Config and Project Rules + +1. **Read `openspec/config.yaml`**: + - Project context: Tech stack, constraints, architecture patterns. + - Development discipline (SDD + TDD): (1) Specs first, (2) Tests second (expect failure), (3) Code last. + - Per-artifact rules: `rules.tasks` — TDD order, test-before-code. + +2. **Read and apply project rules** from CLAUDE.md: + - Contract-first development, testing requirements, code conventions. + +3. **Verify config.yaml rules applied**: + - Source Tracking section (if public-facing). + - GitHub issue creation task (if public repo). + - 2-hour maximum chunks. + - TDD: test tasks before implementation. + +### 5.2: Update Tasks with Quality Standards and Git Workflow + +#### 5.2.1: Determine Branch Type + +- `add-*`, `create-*`, `implement-*`, `enhance-*` -> `feature/` +- `fix-*`, `correct-*`, `repair-*` -> `bugfix/` +- `update-*`, `modify-*`, `refactor-*` -> `feature/` +- `hotfix-*`, `urgent-*` -> `hotfix/` +- Default: `feature/` + +Branch name: `/`. Target: `dev`. + +#### 5.2.2: Add Git Worktree Creation Task (FIRST TASK) + +Add as first task in tasks.md: + +```markdown +## 1. Create git worktree for this change + +- [ ] 1.1 Fetch latest and create a worktree with a new branch from `origin/dev`. + - [ ] 1.1.1 `git fetch origin` + - [ ] 1.1.2 `git worktree add ../specfact-cli-worktrees// -b / origin/dev` + - [ ] 1.1.3 Change into the worktree: `cd ../specfact-cli-worktrees//` + - [ ] 1.1.4 Bootstrap Hatch environment: `hatch env create` + - [ ] 1.1.5 Run pre-flight checks: `hatch run smart-test-status` + - [ ] 1.1.6 Run pre-flight checks: `hatch run contract-test-status` + - [ ] 1.1.7 `git branch --show-current` (verify correct branch) +``` + +**If a GitHub issue exists**, use `gh issue develop` to link the branch before creating the worktree: + +```markdown + - [ ] 1.1.2a `gh issue develop --repo --base dev --name /` (creates remote branch from `dev` linked to issue) + - [ ] 1.1.2b `git fetch origin && git worktree add ../specfact-cli-worktrees// /` +``` + +All remaining tasks in tasks.md MUST run inside the worktree directory, not the primary checkout. + +#### 5.2.3: Update Tasks with Quality Standards + +For each task, ensure: +- Testing requirements (unit, contract, integration, E2E). +- Code quality checks: `hatch run format`, `hatch run type-check`, `hatch run contract-test`. +- Validation: `openspec validate --strict`. + +#### 5.2.4: Enforce TDD-first in tasks.md + +1. **Add "TDD / SDD order (enforced)" section** at top of tasks.md (after title, before first numbered task): + - State: per config.yaml, tests before code for any behavior-changing task. + - Order: (1) Spec deltas, (2) Tests from scenarios (expect failure), (3) Code last. + - "Do not implement production code until tests exist and have been run (expecting failure)." + - Separate with `---`. + +2. **Reorder each behavior-changing section**: Test tasks before implementation tasks. + +3. **Verify**: Scan tasks.md — any section with both test and implementation tasks must have tests first. + +#### 5.2.5: Add PR Creation Task (LAST TASK) + +Add as last task in tasks.md. Only create PR if target repo is public (specfact-cli, platform-frontend). + +Key steps (run from inside the worktree directory): +1. Prepare commit: `git add .`, commit with conventional message, push with `-u`: `git push -u origin /`. +2. Create PR body from `.github/pull_request_template.md`: + - Use full repo path format for issue refs: `Fixes nold-ai/specfact-cli#` + - Include OpenSpec change ID in description. +3. Create PR: `gh pr create --repo --base dev --head --title ": " --body-file ` +4. Link to project (specfact-cli only): `gh project item-add 1 --owner nold-ai --url ` +5. Verify Development link on issue, project board. +6. Update project status to "In Progress" (if applicable). + +PR title format: `feat:` for feature/, `fix:` for bugfix/, etc. + +#### 5.2.6: Add Worktree Cleanup Task (AFTER MERGE) + +Add a note after the PR task for post-merge cleanup: + +```markdown +## Post-merge cleanup (after PR is merged) + +- [ ] Return to primary checkout: `cd .../specfact-cli` +- [ ] `git fetch origin` +- [ ] `git worktree remove ../specfact-cli-worktrees//` +- [ ] `git branch -d /` +- [ ] `git worktree prune` +- [ ] (Optional) `git push origin --delete /` +``` + +### 5.3: Update Proposal with Quality Gates + +Update proposal.md with: quality standards section, git workflow requirements, acceptance criteria (branch created, tests pass, contracts validated, docs updated, PR created). + +### 5.4: Validate with OpenSpec + +1. Verify format: proposal.md has `# Change:` title, `## Why`, `## What Changes`, `## Impact`. Tasks.md uses `## 1.` numbered format. +2. Check status: `openspec status --change "" --json`. +3. Run: `openspec validate --strict`. Fix and re-run until passing. + +### 5.5: Markdown Linting + +Run `markdownlint --config .markdownlint.json --fix` on all `.md` files in the change directory. Fix remaining issues manually. + +## Step 6: GitHub Issue Creation + +### 6.1: Determine Target Repository + +1. Extract target repo from plan header (`**Repository**:` field). +2. Decision: + - `specfact-cli` or `platform-frontend` (public) -> create issue, proceed to 6.2. + - `specfact-cli-internal` (internal) -> skip issue creation, go to Step 8. + - Not specified -> ask user. + +### 6.2: Sanitize Proposal Content + +For public issues: +- **Remove**: Competitive analysis, market positioning, internal strategy, effort estimates. +- **Preserve**: User-facing value, feature descriptions, acceptance criteria, API changes. + +Format per config.yaml: +- Title: `[Change] ` +- Labels: `enhancement`, `change-proposal` +- Body: `## Why`, `## What Changes`, `## Acceptance Criteria` +- Footer: `*OpenSpec Change Proposal: *` + +Show sanitized content to user for approval before creating. + +## Step 7: Create GitHub Issue via gh CLI + +1. Write sanitized content to temp file. +2. Create issue: + +```bash +gh issue create \ + --repo \ + --title "[Change] " \ + --body-file /tmp/github-issue-<change-id>.md \ + --label "enhancement" \ + --label "change-proposal" +``` + +3. For specfact-cli: link to project `gh project item-add 1 --owner nold-ai --url <ISSUE_URL>`. +4. Update `proposal.md` Source Tracking section: + +```markdown +## Source Tracking + +<!-- source_repo: <target-repo> --> +- **GitHub Issue**: #<number> +- **Issue URL**: <url> +- **Last Synced Status**: proposed +``` + +5. Cleanup temp file. + +## Step 8: Completion + +Display summary: + +```text +Change ID: <change-id> +Location: openspec/changes/<change-id>/ + +Validation: + - OpenSpec validation passed + - Markdown linting passed + - Config.yaml rules applied (TDD-first enforced) + - Git workflow tasks added (branch + PR) + +GitHub Issue (if public): + - Issue #<number> created: <url> + - Source tracking updated + +Next Steps: + 1. Review: openspec/changes/<change-id>/proposal.md + 2. Review: openspec/changes/<change-id>/tasks.md + 3. Verify TDD order and git workflow in tasks + 4. Apply when ready: invoke opsx:apply skill +``` + +## Error Handling + +- **Plan not found**: Search and suggest alternatives. +- **Validation failures**: Present clearly, allow interactive resolution. +- **OpenSpec validation fails**: Fix and re-validate, don't proceed until passing. +- **gh CLI unavailable**: Inform user, provide manual creation instructions. +- **Issue creation fails**: Log error, allow retry, don't fail entire workflow. +- **Project linking fails**: Log warning, continue (non-critical). diff --git a/.agents/skills/openspec-workflows/references/validate-change.md b/.agents/skills/openspec-workflows/references/validate-change.md new file mode 100644 index 00000000..8a6cbe0c --- /dev/null +++ b/.agents/skills/openspec-workflows/references/validate-change.md @@ -0,0 +1,268 @@ +# Workflow: Validate OpenSpec Change + +## Table of Contents + +- [Guardrails](#guardrails) +- [Step 1: Change Selection](#step-1-change-selection) +- [Step 2: Read and Parse Change](#step-2-read-and-parse-change) +- [Step 3: Simulate Change Application](#step-3-simulate-change-application) +- [Step 4: Dependency Analysis](#step-4-dependency-analysis) +- [Step 5: Validation Report and Decision](#step-5-validation-report-and-decision) +- [Step 6: Create Validation Report](#step-6-create-validation-report) +- [Step 7: Completion](#step-7-completion) + +## Guardrails + +- Never modify the actual codebase during validation — only work in temp directories. +- Focus on interface/contract/parameter analysis, not implementation details. +- Identify breaking changes, not style or formatting issues. +- Always create CHANGE_VALIDATION.md for audit trail. +- Ask for user confirmation before extending change scope or rejecting proposals. + +## Step 1: Change Selection + +**If change ID provided**: Resolve to `openspec/changes/<change-id>/`, verify directory and proposal.md exist. + +**If no change ID provided**: +1. List active changes: `openspec list --json`. +2. Display numbered list with change ID, schema, status, brief description. +3. Prompt user to select. + +## Step 2: Read and Parse Change + +### 2.1: Check Status and Read Artifacts + +1. **Read `openspec/config.yaml`** for project context, constraints, and per-artifact rules. + +2. **Check change status**: `openspec status --change "<change-id>" --json` + - Verify required artifacts exist and are parseable for proposal-stage validation + (do not require status `"done"`). + - Accept proposal-stage statuses such as `"proposed"`, `"in-review"`, or + `"in-progress"`; fail only when the change is missing, parse errors are + present, or status is explicitly rejected/deferred. + +3. **Get artifact context**: `openspec instructions apply --change "<change-id>" --json` + +4. **Verify proposal.md format** (per config.yaml): + - Title: `# Change: [Brief description]` + - Required sections: `## Why`, `## What Changes`, `## Capabilities`, `## Impact` + - "What Changes": bullet list with NEW/EXTEND/MODIFY markers + - "Capabilities": each capability needs a spec file + - "Impact": Affected specs, Affected code, Integration points + +5. **Read proposal.md**: Extract summary, rationale, scope, capabilities, affected files. + +6. **Verify tasks.md format** (per config.yaml): + - Hierarchical numbered sections: `## 1.`, `## 2.` + - Tasks: `- [ ] 1.1 [Description]` + - Sub-tasks: `- [ ] 1.1.1 [Description]` + - Rules: 2-hour max chunks, contract tasks, test tasks, quality gates, git worktree workflow (worktree creation first, PR last, cleanup after merge) + +7. **Read tasks.md**: Extract tasks, files to create/modify/delete, task dependencies. Verify worktree creation first, PR creation last, worktree cleanup after merge. + +8. **Read design.md** (if exists): Architectural decisions, interface changes, contracts, migration plans. Verify bridge adapter docs, sequence diagrams for multi-repo. + +9. **Read spec deltas** (`specs/<capability>/spec.md`): ADDED/MODIFIED/REMOVED requirements, interface/parameter/contract changes, cross-refs. Verify Given/When/Then format. + +### 2.2: Identify Change Scope + +1. **Files to modify**: Extract from tasks.md and proposal.md. Categorize: code, tests, docs, config. +2. **Modules/Components**: Python modules, classes, functions, interfaces, contracts, APIs. Note public vs private. +3. **Dependencies**: From proposal "Dependencies" section and task dependencies. + +## Step 3: Simulate Change Application + +### 3.1: Create Temporary Workspace + +```bash +TEMP_WORKSPACE="/tmp/specfact-validation-<change-id>-$(date +%s)" +mkdir -p "$TEMP_WORKSPACE" +``` + +Copy relevant repository structure to temp workspace. + +### 3.2: Analyze Spec Deltas for Interface Changes + +For each spec delta: +1. Parse ADDED/MODIFIED/REMOVED requirements. +2. Extract interface changes: function signatures, class interfaces, `@icontract`/`@beartype` decorators, type hints, API endpoints. +3. Create interface scaffolds in temp workspace (stubs only, no implementation): + +```python +# OLD INTERFACE (from existing codebase) +def process_data(data: str, options: dict) -> dict: ... + +# NEW INTERFACE (from change proposal) +def process_data(data: str, options: dict, validate: bool = True) -> dict: ... +``` + +### 3.3: Map Tasks to File Modifications + +For each task, categorize modification type: +- **Interface change**: Function/class signature modification +- **Contract change**: `@icontract` decorator modification +- **Type change**: Type hint modification +- **New/Delete file**: Module/class/function added or removed +- **Documentation**: Non-breaking doc changes + +Create modification map: File path -> Modification type -> Interface changes. + +## Step 4: Dependency Analysis + +### 4.1: Find Dependent Code + +For each modified file/interface, search codebase: +- `from...import...<module>` — find imports +- `<function_name>(` or `<class_name>(` — find usages +- `@<decorator>` — find contract decorators + +Build dependency graph: Modified interface -> dependent files (direct, indirect, test). + +### 4.2: Analyze Breaking Changes + +Compare old vs new interface. Detect: +- **Parameter removal**: Required param removed +- **Parameter addition**: Required param added (no default) +- **Parameter type change**: Incompatible type +- **Return type change**: Incompatible return +- **Contract strengthening**: `@require` stricter, `@ensure` weaker +- **Method/class/module removal**: Public API removed + +For each dependent file, check if it would break: +- **Would break**: Incompatible usage detected +- **Would need update**: Compatible but may need adjustment +- **No impact**: Usage compatible + +### 4.3: Identify Required Updates + +Categorize: +- **Critical**: Must update or code breaks +- **Recommended**: Should update for consistency +- **Optional**: No update needed + +## Step 5: Validation Report and Decision + +### 5.1: Summary + +Count breaking changes, affected interfaces, dependent files. Assess impact: High/Medium/Low. + +### 5.2: Present Findings + +```text +Change Validation Report: <change-id> + +Breaking Changes Detected: <count> + - <interface 1>: <description> + +Dependent Files Affected: <count> + Critical (must update): <count> + Recommended: <count> + Optional: <count> + +Impact Assessment: <High/Medium/Low> +``` + +### 5.3: User Decision (if breaking changes) + +**Option A: Extend Scope** — Add tasks to update dependent files. May require major version. + +**Option B: Adjust Change** — Add default params, keep old interface (deprecation), use optional params. + +**Option C: Reject and Defer** — Update status to "deferred", document in CHANGE_VALIDATION.md. + +**No breaking changes**: Proceed to 5.4. + +### 5.4: OpenSpec Validation + +1. Check status: `openspec status --change "<change-id>" --json` +2. Run: `openspec validate <change-id> --strict` +3. Fix issues and re-run until passing. +4. If proposal was updated (scope extended/adjusted), re-validate. + +## Step 6: Create Validation Report + +Create `openspec/changes/<change-id>/CHANGE_VALIDATION.md`: + +```markdown +# Change Validation Report: <change-id> + +**Validation Date**: <timestamp> +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation in temporary workspace + +## Executive Summary + +- Breaking Changes: <count> detected / <count> resolved +- Dependent Files: <count> affected +- Impact Level: <High/Medium/Low> +- Validation Result: <Pass/Fail/Deferred> +- User Decision: <Extend Scope/Adjust Change/Reject/N/A> + +## Breaking Changes Detected + +### Interface: <name> +- **Type**: Parameter addition/removal/type change +- **Old Signature**: `<old>` +- **New Signature**: `<new>` +- **Dependent Files**: <file>: <impact> + +## Dependencies Affected + +### Critical Updates Required +- <file>: <reason> + +### Recommended Updates +- <file>: <reason> + +## Impact Assessment + +- **Code Impact**: <description> +- **Test Impact**: <description> +- **Documentation Impact**: <description> +- **Release Impact**: <Minor/Major/Patch> + +## Format Validation + +- **proposal.md Format**: <Pass/Fail> + - Title, sections, capabilities, impact per config.yaml +- **tasks.md Format**: <Pass/Fail> + - Headers, task format, config.yaml compliance (TDD, git workflow, quality gates) +- **specs Format**: <Pass/Fail> + - Given/When/Then format, references existing patterns +- **Config.yaml Compliance**: <Pass/Fail> + +## OpenSpec Validation + +- **Status**: <Pass/Fail> +- **Command**: `openspec validate <change-id> --strict` +- **Issues Found/Fixed**: <count> + +## Validation Artifacts + +- Temporary workspace: <path> +``` + +Update proposal status if deferred, scope extended, or adjusted. + +## Step 7: Completion + +```text +Change ID: <change-id> +Validation Report: openspec/changes/<change-id>/CHANGE_VALIDATION.md + +Findings: + - Breaking Changes: <count> + - Dependent Files: <count> + - Impact Level: <level> + - Validation Result: <result> + +Next Steps: + <based on decision — implement, re-validate, or defer> +``` + +## Error Handling + +- **Change not found**: Search and suggest alternatives. +- **Repo not accessible**: Inform user, provide manual validation instructions. +- **Breaking changes**: Present options clearly, don't proceed without user decision. +- **Dependency analysis fails**: Continue with partial analysis, note limitations. diff --git a/README.md b/README.md index e00ca0de..c5a985a7 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ These findings are bloat-shape detection and cleanup guidance, not AI-authorship - **Reviews AI-assisted changes against evidence** — compare code against contracts, clean-code rules, and policy gates - **Extracts structure from existing code** — reverse-engineer brownfield repos before you change them - **Blocks drift before merge** — use the same checks locally, in pre-commit, and in CI -- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation +- **Consumes upstream planning inputs** — treat Spec Kit, OpenSpec, backlog, specs, tests, and contracts as validation evidence - **Stays local-first** — no cloud account, no vendor lock-in, no built-in model dependency ## What is SpecFact? @@ -136,17 +136,18 @@ SpecFact uses the same discipline it asks you to trust: ## For teams and organizations -SpecFact still scales beyond the solo-developer entry path: +SpecFact still scales beyond the solo-developer entry path, but validation stays +the center: -- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear +- **Upstream context adapters** for GitHub, Azure DevOps, Jira, Linear, OpenSpec, and Spec Kit inputs - **DoR/DoD and policy enforcement** for teams that need repeatable gates - **Evidence-backed PR review** with the same checks used locally - **CI/CD adoption path** that keeps validation deterministic instead of model-driven -Start with: +Optional module-deep paths include: -- `specfact backlog ceremony standup ...` -- `specfact backlog ceremony refinement ...` +- `specfact project import ...` +- `specfact spec validate ...` - `specfact backlog verify-readiness --bundle <bundle-name>` - `specfact govern ...` diff --git a/docs/index.md b/docs/index.md index 433ca3e9..0ac818f1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,7 +43,7 @@ SpecFact does **not** include built-in AI. It pairs deterministic CLI commands w ## What is SpecFact? -SpecFact helps you keep backlog intent, specifications, implementation, and validation from drifting apart. It supports spec-first handoffs with **OpenSpec** and spec-kit-style workflows so brownfield and AI-assisted teams can keep backlog language, specs, and code aligned. +SpecFact helps you keep upstream intent, specifications, implementation, and validation from drifting apart. It consumes **OpenSpec**, Spec Kit-style workflows, backlog items, contracts, tests, and code as upstream inputs so brownfield and AI-assisted teams can validate what actually landed. It is especially useful when: @@ -68,7 +68,7 @@ With SpecFact, you get: - AI-bloat defense with cleanup forecasts and remediation packet handoff - a validation layer around AI-assisted delivery - codebase analysis and sidecar validation for brownfield work -- stronger backlog/spec/code alignment +- stronger upstream-input/spec/code alignment without replacing your planning stack - a clean handoff from this site into module-deep workflows on [modules.specfact.io](https://modules.specfact.io/) ## How to get started diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 29c17502..b9226d1d 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -1,217 +1,220 @@ # OpenSpec Change Order -This document is the **single source of truth for active work** in this repository. -It lists what is in flight, what is paused, and the order in which active changes -should be implemented. +This document is the **single source of truth for active work** in this +repository. It lists what is in flight, what is paused, and the order in which +active changes should be implemented. ## Status snapshot | Bucket | Count | Location | -|---|---|---| -| **Active** | 28 | [`openspec/changes/`](changes/) | -| **Parked** | 20 | [`openspec/parking-lot/`](parking-lot/) | -| **Archived** | 106 | [`openspec/changes/archive/`](changes/archive/) | +|---|---:|---| +| **Active** | 18 | [`openspec/changes/`](changes/) | +| **Parked** | 21 | [`openspec/parking-lot/`](parking-lot/) | +| **Archived** | 115 | [`openspec/changes/archive/`](changes/archive/) | `openspec list` reflects the active set only. Parking-lot proposals are paused -pending external signal (paying enterprise customer, third-party publisher, -evidence corpus, etc.) — see [`parking-lot/README.md`](parking-lot/README.md) -for the un-park trigger of each parked change. +pending external signal, such as paying customer pull, third-party publisher +adoption, or a real evidence corpus. See +[`parking-lot/README.md`](parking-lot/README.md) for un-park triggers. -## Naming convention - -- **Folder**: `<module>-<NN>-<suffix>` (e.g. `requirements-01-data-model`). -- **Order**: lower numbers within a module are implemented first. Cross-module - dependencies are listed in the **Blocked by** column of each track table. +## Product thesis -## Active tracks +SpecFact is the local validation and AI-bloat defense CLI for AI-assisted and +brownfield delivery. The active roadmap should make that thesis stronger: -The 28 active changes group into five independent tracks. Tracks can run in -parallel; within a track, follow the order column. +- produce deterministic evidence before merge; +- detect AI-bloat, drift, weak contracts, and orphaned artifacts; +- hand remediation packets to AI IDEs without becoming the IDE; +- consume Spec Kit, OpenSpec, backlog, ADR, contract, code, and test artifacts + as upstream inputs; +- avoid competing with upstream planning stacks that already own spec-driven or + intent-driven authoring. -### Track A — Full-chain traceability (core thesis) +## Naming convention -The end-to-end "Req → Arch → Spec → Code → Tests" chain. This is the headline -SpecFact value proposition; all other tracks support or extend it. +- **Folder**: `<module>-<NN>-<suffix>` such as `requirements-01-data-model`. +- **Order**: lower numbers within a module come first. Cross-module dependencies + are listed in the **Blocked by** column. -| Order | Change | Issue | Blocked by | -|---|---|---|---| -| 1 | `requirements-01-data-model` | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | arch-07 ✅ | -| 2 | `requirements-02-module-commands` | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | requirements-01 | -| 3 | `architecture-01-solution-layer` | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | requirements-01, requirements-02 | -| 4 | `requirements-03-backlog-sync` | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | requirements-02; modules `sync-01` | -| 5 | `traceability-01-index-and-orphans` | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | requirements-02, architecture-01 | -| 6 | `validation-02-full-chain-engine` | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | requirements-02, architecture-01, policy-engine-01 ✅ | -| 7 | `governance-01-evidence-output` | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | validation-02; modules `policy-02` | -| 8 | `dogfooding-01-full-chain-e2e-proof` | [#255](https://github.com/nold-ai/specfact-cli/issues/255) | requirements-02, architecture-01, validation-02, traceability-01, governance-01 | +## Active tracks -**Critical path**: requirements-01 → requirements-02 → architecture-01 → -traceability-01 + validation-02 → governance-01. +The 18 active changes group into three product tracks plus one reliability lane. +Tracks can run in parallel; within a track, follow the order column. -### Track B — AI IDE distribution +### Track A - Validation Evidence Spine -Skills-first integration so AI IDEs invoke SpecFact validation in-loop. +This is the core product path. It turns existing repo and planning artifacts +into auditable validation evidence and cleanup feedback. -| Order | Change | Issue | Blocked by | -|---|---|---|---| -| 1 | `ai-integration-01-agent-skill` | [#251](https://github.com/nold-ai/specfact-cli/issues/251) | validation-02 | -| 2 | `ai-integration-03-instruction-files` | [#253](https://github.com/nold-ai/specfact-cli/issues/253) | ai-integration-01 | -| 3 | `ai-integration-02-mcp-server` *(scope: trim to 2-3 tools before implementation — see Modify queue)* | [#252](https://github.com/nold-ai/specfact-cli/issues/252) | ai-integration-01 | -| 4 | `ai-integration-04-intent-skills` *(scope: collapse to single intent-capture skill — see Modify queue)* | [#349](https://github.com/nold-ai/specfact-cli/issues/349) | ai-integration-01, requirements-02 | -| — | `openspec-01-intent-trace` *(scope: convert to optional adapter convention — see Modify queue)* | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | requirements-01, requirements-02 | +| Order | Change | Issue | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `profile-01-config-layering` | [#237](https://github.com/nold-ai/specfact-cli/issues/237) | Rollout modes for validation severity and evidence strictness | - | +| 2 | `governance-01-evidence-output` | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | Evidence JSON, CI verdicts, remediation packet attachment points | modules `policy-02` | +| 3 | `governance-02-exception-management` | [#248](https://github.com/nold-ai/specfact-cli/issues/248) | Time-bound validation exceptions and waiver evidence | governance-01; modules `policy-02` | +| 4 | `traceability-01-index-and-orphans` | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | Artifact drift and orphan detection across inputs | requirements/architecture adapter contracts where present | +| 5 | `validation-02-full-chain-engine` | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | Validation evidence graph over existing inputs, not a product lifecycle engine | governance-01, traceability-01 | +| 6 | `dogfooding-01-full-chain-e2e-proof` | [#255](https://github.com/nold-ai/specfact-cli/issues/255) | AI-bloat defense and validation proof on real PRs | governance-01, validation-02, traceability-01 | -### Track C — Profile and configuration +**Critical path**: profile-01 plus governance-01 -> traceability-01 -> +validation-02 -> dogfooding proof. -Adoption gradient from solo developer to enterprise. +### Track B - AI IDE Validation Distribution -| Order | Change | Issue | Blocked by | -|---|---|---|---| -| 1 | `profile-01-config-layering` | [#237](https://github.com/nold-ai/specfact-cli/issues/237) | — | -| — | `profile-04-safe-project-artifact-writes` *(in flight: 16/22 done)* | [#490](https://github.com/nold-ai/specfact-cli/issues/490) | — | +AI integrations should teach agents how to run SpecFact validation, interpret +evidence, apply remediation packets, and rerun proof. They should not become an +upstream intent-engineering product. -`profile-02` and `profile-03` are parked pending profile-01 shipping with -demonstrated drift complaints — see parking-lot README. +| Order | Change | Issue | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `ai-integration-01-agent-skill` | [#251](https://github.com/nold-ai/specfact-cli/issues/251) | Agent skill for running validation and reading evidence | governance-01, validation-02 | +| 2 | `ai-integration-03-instruction-files` | [#253](https://github.com/nold-ai/specfact-cli/issues/253) | Lightweight IDE aliases for validation and remediation loops | ai-integration-01 | +| 3 | `ai-integration-02-mcp-server` | [#252](https://github.com/nold-ai/specfact-cli/issues/252) | Later thin adapter with 2-3 validation tools only | CLI pull from ai-integration-01 | -### Track D — CLI reliability +### Track C - Upstream Context Adapters -User-facing CLI behavior assertions and acceptance-test surface. +These changes are useful only when they improve validation evidence. They import +and normalize upstream context from Spec Kit, OpenSpec, backlog systems, ADRs, +and architecture docs. They do not own authoring, ceremonies, or bidirectional +planning workflows. -| Order | Change | Issue | Blocked by | -|---|---|---|---| -| 0 | `runtime-01-discovery-reliability` | [#552](https://github.com/nold-ai/specfact-cli/issues/552), [#553](https://github.com/nold-ai/specfact-cli/issues/553), [#554](https://github.com/nold-ai/specfact-cli/issues/554) | — | -| 0.5 | `tester-cli-reliability` | [#594](https://github.com/nold-ai/specfact-cli/issues/594); source bugs [#585](https://github.com/nold-ai/specfact-cli/issues/585), [#587](https://github.com/nold-ai/specfact-cli/issues/587), [#588](https://github.com/nold-ai/specfact-cli/issues/588), [#589](https://github.com/nold-ai/specfact-cli/issues/589), [#590](https://github.com/nold-ai/specfact-cli/issues/590), [#593](https://github.com/nold-ai/specfact-cli/issues/593) | paired modules `tester-module-cli-reliability` | -| 1 | `cli-val-03-misuse-safety-proof` | [#281](https://github.com/nold-ai/specfact-cli/issues/281) | — | -| 2 | `cli-val-04-acceptance-test-runner` | [#282](https://github.com/nold-ai/specfact-cli/issues/282) | cli-val-03 | +| Order | Change | Issue | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `requirements-01-data-model` | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | Normalized requirements-input records for evidence | arch-07 | +| 2 | `requirements-02-module-commands` | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | Import and normalize existing requirement context | requirements-01 | +| 3 | `requirements-03-backlog-sync` | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | Read-first drift evidence; no write-back critical path | requirements-02; modules `sync-01` | +| 4 | `architecture-01-solution-layer` | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | Architecture-boundary records and drift validation | requirements input contracts | +| 5 | `openspec-01-intent-trace` | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | Optional OpenSpec and Spec Kit evidence adapter | requirements-01/02 | +| Gated | `architecture-02-well-architected-review` | [#524](https://github.com/nold-ai/specfact-cli/issues/524) | Architecture-boundary review findings | architecture-01 shipped plus one usage cycle | +| Gated | `telemetry-01-opentelemetry-default-on` | [#518](https://github.com/nold-ai/specfact-cli/issues/518) | Opt-in validation outcome telemetry only | governance-01 evidence fields | -The remaining cli-val items (01, 02, 05, 06) are parked — see parking-lot -README. Snapshot/CI work folds into 03 and 04 if and when needed. +### Track D - CLI Validation Trust -### Track E — Other active work +These changes make the CLI itself trustworthy enough to be the validation tool. -| Change | Status | Notes | -|---|---|---| -| `dep-security-cleanup` | 62/69 done | Apache-2.0 license-cleanliness pass | -| `marketplace-07-module-install-state-consistency` | ✓ archive pending | Resolves install-state disagreement across scopes | -| `module-scope-version-diagnostics` | active | Resolves project/user module version mismatch diagnostics and enforcement under #565 / #353 | -| `upgrade-01-install-method-aware` | ✓ archive pending | Bug-fix for uvx/uv users | -| `governance-02-exception-management` | active | Time-bound policy exceptions | -| `architecture-02-well-architected-review` | **gated on architecture-01 shipping + 1 cycle of usage** | Boundary/ADR review pillar | -| `telemetry-01-opentelemetry-default-on` | **modify queue** | Flip to opt-in; revisit default-on later | -| `integration-01-cross-change-contracts` | **convert to living `INTEGRATION.md`** | Stops being a tasked change | +| Order | Change | Issue | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `cli-val-03-misuse-safety-proof` | [#281](https://github.com/nold-ai/specfact-cli/issues/281) | Misuse safety proof for user-facing commands | - | +| 2 | `cli-val-04-acceptance-test-runner` | [#282](https://github.com/nold-ai/specfact-cli/issues/282) | Acceptance-test runner for CLI behavior proof | cli-val-03 | -## Modify queue (do this before implementing) +## Modify queue before implementation -Six active changes need scope adjustments before any implementation work -begins. One PR per change, focused. +No behavior implementation should start from stale upstream-planning language. +Update each proposal first, then run strict OpenSpec validation. | Change | Required adjustment | |---|---| -| `openspec-01-intent-trace` | Rewrite proposal to describe an *optional adapter convention* SpecFact reads if present, not a mandatory upstream OpenSpec schema change. | -| `ai-integration-04-intent-skills` | Collapse to a single intent-capture skill; drop "SQUER" branding and the 7-question interview machinery. | -| `ai-integration-02-mcp-server` | Trim to 2–3 tools; explicitly gate on ai-integration-01 shipping and showing user pull. | -| `telemetry-01-opentelemetry-default-on` | Default to opt-in, not opt-out. Document criteria under which it would flip to default-on later. | -| `integration-01-cross-change-contracts` | Replace tasked change with a living `INTEGRATION.md` that other changes reference; archive the change once doc exists. | -| `architecture-02-well-architected-review` | Add explicit "BLOCKED ON: architecture-01 shipped + 1 usage cycle" at top of proposal. | +| `validation-02-full-chain-engine` | Rewrite as a validation evidence graph engine over existing inputs. Do not own requirements-to-code lifecycle authoring. | +| `traceability-01-index-and-orphans` | Keep artifact drift, orphan, and linkage evidence. Remove ceremony/dashboard positioning. | +| `requirements-01-data-model` | Reduce to optional normalized requirements-input records for validation evidence. | +| `requirements-02-module-commands` | Drop requirement authoring as a flagship path. Keep import, normalization, validation, and coverage inspection. | +| `requirements-03-backlog-sync` | Make drift detection/read-first import the product value. Keep write-back preview out of the critical path. | +| `architecture-01-solution-layer` | Reduce to architecture-boundary validation and drift evidence. Do not generate architecture. | +| `openspec-01-intent-trace` | Rewrite as an optional adapter that consumes OpenSpec and Spec Kit artifacts. | +| `dogfooding-01-full-chain-e2e-proof` | Rewrite proof around real PR review, JSON evidence, AI-bloat findings, remediation packets, rerun proof. | +| `ai-integration-01-agent-skill` | Teach agents to run SpecFact validation and interpret evidence. | +| `ai-integration-03-instruction-files` | Generate lightweight validation aliases only. | +| `ai-integration-02-mcp-server` | Gate later, after CLI validation has pull; expose only 2-3 validation tools. | +| `telemetry-01-opentelemetry-default-on` | Keep opt-in only and measure validation outcomes, not product-management workflow analytics. | +| `architecture-02-well-architected-review` | Add explicit blocked status until architecture-01 ships and completes one usage cycle. | ## Implementation waves -Waves are dependency-ordered. A wave can start once all its hard blockers are -green; tracks within a wave can run in parallel. +### Wave 1 - Scope cleanup and archives -### Wave 1 — Adjust active scope (immediate) +- Archive completed active OpenSpec folders whose GitHub issues are closed. +- Move `ai-integration-04-intent-skills` to the parking lot because upstream + intent engineering is no longer active scope. +- Convert `integration-01-cross-change-contracts` into + [`INTEGRATION.md`](INTEGRATION.md) and archive the change. +- Apply the modify queue above to active proposals and internal wiki mirrors. +- Recheck GitHub Project fields with a token that has `read:project` before + implementation work begins. -Run the **Modify queue** above. No implementation, just proposal rewrites and -the integration-01 → INTEGRATION.md conversion. +### Wave 2 - Validation foundations -### Wave 2 — Foundations (parallel) +- `profile-01-config-layering` +- `governance-01-evidence-output` +- `governance-02-exception-management` +- `cli-val-03-misuse-safety-proof` -- Track A items 1–3: `requirements-01` → `requirements-02` → `architecture-01` -- Track C item 1: `profile-01-config-layering` -- Track D item 1: `cli-val-03-misuse-safety-proof` -- Track E in-flight items: finish `dep-security-cleanup`, `profile-04`, - archive `marketplace-07` and `upgrade-01` +### Wave 3 - Evidence graph and drift detection -### Wave 3 — Chain assembly +- `validation-02-full-chain-engine` +- `traceability-01-index-and-orphans` +- `cli-val-04-acceptance-test-runner` -- Track A items 4–6: `requirements-03`, `traceability-01`, `validation-02` -- Track D item 2: `cli-val-04-acceptance-test-runner` +### Wave 4 - AI IDE validation loop -### Wave 4 — Evidence and AI surface +- `ai-integration-01-agent-skill` +- `ai-integration-03-instruction-files` +- Dogfooding slice: run review on a real repo, emit JSON evidence, identify + AI-bloat findings, hand remediation packets to an AI IDE, rerun review, and + show improved evidence. -- Track A item 7: `governance-01-evidence-output` -- Track B items 1–2: `ai-integration-01-agent-skill`, `ai-integration-03-instruction-files` +### Wave 5 - Optional adapters and later extensions -### Wave 5 — Proof, intent, extensions - -- Track A item 8: `dogfooding-01-full-chain-e2e-proof` -- Track B items 3–4: `ai-integration-02-mcp-server` (trimmed), `ai-integration-04-intent-skills` (trimmed) -- `openspec-01-intent-trace` (trimmed) -- `governance-02-exception-management` -- `architecture-02-well-architected-review` (only after architecture-01 has been used for one full development cycle) +- `requirements-01/02/03` only as validation input adapters. +- `architecture-01` only as architecture-boundary validation input. +- `openspec-01` as optional OpenSpec and Spec Kit evidence adapter. +- `architecture-02`, `telemetry-01`, and `ai-integration-02` only after pull + from the validation loop exists. ## Wave exit gates A wave is complete only when all listed criteria are auditable: -- **Wave 1**: Each item in the Modify queue has either (a) a rewritten proposal - validated by `openspec validate`, or (b) for integration-01, an - `INTEGRATION.md` doc replacing the tasked change. -- **Wave 2**: Three foundations (`requirements-01/02`, `architecture-01`) pass - contract tests + strict OpenSpec validation. `profile-01` and `cli-val-03` - archived. -- **Wave 3**: One chain run proves `requirements → architecture → - validation/traceability` flows end-to-end with no ownership conflicts. -- **Wave 4**: `governance-01` evidence JSON consumed by at least one CI run. - `ai-integration-01` skill installed in one IDE end-to-end. -- **Wave 5**: `dogfooding-01` artifacts demonstrate the full chain on real - SpecFact backlog data. `openspec-01` and `ai-integration-04` adopted by at - least one upstream OpenSpec project / IDE. - -## Ownership authority (cross-change) - -These ownership boundaries are mandatory before implementation when changes -overlap on shared files or interfaces. **No dependent change may redefine an -owned surface** — propose a delta to the authoritative change first. - -| Owned surface | Authoritative change | Dependent changes | -|---|---|---| -| Requirements schema (`src/specfact_cli/models/requirements.py`) | `requirements-01-data-model` | `requirements-02`, `requirements-03`, `architecture-01` | -| `ProjectBundle` requirements namespace | `requirements-01-data-model` | `requirements-02`, `requirements-03`, `architecture-01` | -| `ProjectBundle` architecture namespace | `architecture-01-solution-layer` | `validation-02`, `traceability-01` | -| Backlog requirements extraction adapter contract | `requirements-02-module-commands` | `requirements-03-backlog-sync` | -| Evidence JSON envelope and CI verdict schema | `governance-01-evidence-output` | `validation-02`, `governance-02`, `dogfooding-01` | -| Exception scope suppression and expiry | `governance-02-exception-management` | `governance-01`; modules `policy-02` | - -## Parent issues (Epics) - -| Module group | Epic | +- **Wave 1**: Active changes match the validation positioning and completed + work is archived. +- **Wave 2**: Evidence envelope, exception model, profile severity, and CLI + misuse proof validate strictly. +- **Wave 3**: One evidence graph run proves drift/orphan detection over existing + artifacts without ownership conflicts. +- **Wave 4**: One AI-bloat defense loop produces JSON evidence, remediation + packets, rerun proof, and improved evidence on a real repository slice. +- **Wave 5**: External planning artifacts are consumed as inputs. They are not + positioned as workflows SpecFact replaces. + +## Ownership authority + +The cross-change ownership contract lives in +[`INTEGRATION.md`](INTEGRATION.md). No dependent change may redefine an owned +surface. Propose a delta to the authoritative change first. + +## Parent issues and epic framing + +Rename or reframe parent issues where possible: + +| Current issue | Desired framing | |---|---| -| Architecture Layer Integration (Requirements → AI) | [#256](https://github.com/nold-ai/specfact-cli/issues/256) | -| AI IDE Integration | [#257](https://github.com/nold-ai/specfact-cli/issues/257) | -| Integration Governance and Dogfooding | [#258](https://github.com/nold-ai/specfact-cli/issues/258) | -| CLI End-User Validation | [#285](https://github.com/nold-ai/specfact-cli/issues/285) | +| [#256](https://github.com/nold-ai/specfact-cli/issues/256) | Validation evidence and context adapters | +| [#257](https://github.com/nold-ai/specfact-cli/issues/257) | AI IDE validation integration | +| [#258](https://github.com/nold-ai/specfact-cli/issues/258) | Evidence dogfooding and governance | +| [#285](https://github.com/nold-ai/specfact-cli/issues/285) | CLI validation trust | -Set the GitHub **Type** to Epic on the project board and link child issues -via **Relationships → tracks** or by setting the project **Parent** field. +Set GitHub **Type** to Epic on the project board and link child issues via +**Relationships -> tracks** or by setting the project **Parent** field. Project +board metadata was not available with the current token, so final issue +governance must recheck those fields before implementation. ## Cross-repo coordination Module-side companions live in [`nold-ai/specfact-cli-modules`](https://github.com/nold-ai/specfact-cli-modules). -The runtime pairs for `requirements-02`, `requirements-03`, `architecture-01`, -`validation-02`, `traceability-01`, `governance-01`, `governance-02`, and -`openspec-01` are in that repo's `CHANGE_ORDER.md`. Treat both files as a -single cross-repo plan. +The modules roadmap should now treat `specfact code` and AI-bloat defense as +the flagship product path, while backlog, ceremony, enterprise, FinOps, and +knowledge extensions remain parked unless validation evidence requires them. ## Archive All implemented changes are under -[`openspec/changes/archive/`](changes/archive/) with date-prefixed folder -names. Run `git log openspec/changes/archive/` for chronological history. +[`openspec/changes/archive/`](changes/archive/) with date-prefixed folder names. After a change merges to `dev`, run `openspec archive <change-id>` from the -repo root — do not move folders manually. +repo root. Do not move folders manually. ## See also -- [`parking-lot/README.md`](parking-lot/README.md) — paused proposals + un-park triggers -- [`config.yaml`](config.yaml) — repo-wide OpenSpec rules and context -- [`specfact-cli-modules/openspec/CHANGE_ORDER.md`](https://github.com/nold-ai/specfact-cli-modules/blob/main/openspec/CHANGE_ORDER.md) — module-side companion plan +- [`parking-lot/README.md`](parking-lot/README.md) - paused proposals and + un-park triggers +- [`INTEGRATION.md`](INTEGRATION.md) - cross-change ownership contract +- [`config.yaml`](config.yaml) - repo-wide OpenSpec rules and context +- [`specfact-cli-modules/openspec/CHANGE_ORDER.md`](https://github.com/nold-ai/specfact-cli-modules/blob/main/openspec/CHANGE_ORDER.md) - module-side companion plan diff --git a/openspec/INTEGRATION.md b/openspec/INTEGRATION.md new file mode 100644 index 00000000..3850f1bb --- /dev/null +++ b/openspec/INTEGRATION.md @@ -0,0 +1,68 @@ +# OpenSpec Integration Contract + +This document is the living ownership contract for active SpecFact OpenSpec +changes. It exists to keep parallel roadmap work aligned without creating a +separate product feature for integration governance. + +## Positioning + +SpecFact is the local validation and AI-bloat defense CLI. Active changes SHALL +strengthen deterministic evidence, code-review remediation, artifact drift +detection, and trusted CLI behavior. + +Spec Kit, OpenSpec, backlog systems, ADRs, and architecture documents are +upstream inputs. SpecFact consumes those artifacts to validate implementation +reality; it does not try to replace the upstream planning stack. + +## Ownership Rules + +- `governance-01-evidence-output` owns the evidence envelope, CI verdict schema, + severity taxonomy, and remediation packet attachment points. +- `governance-02-exception-management` owns exception scope, expiry, + suppression behavior, and waiver evidence. +- `validation-02-full-chain-engine` owns the validation evidence graph contract + and graph-level aggregation rules. +- `traceability-01-index-and-orphans` owns artifact identity, linkage, and + orphan/drift classification. +- `requirements-01-data-model` owns normalized requirements-input records only. + It does not own requirement authoring or backlog source-of-truth behavior. +- `requirements-02-module-commands` owns import and normalization contracts for + upstream planning inputs. +- `requirements-03-backlog-sync` owns read-first drift evidence between backlog + systems and normalized inputs. Write-back remains outside the critical path. +- `architecture-01-solution-layer` owns architecture-boundary input records and + validation hooks, not architecture generation. +- `architecture-02-well-architected-review` owns architecture-review finding + contracts after `architecture-01` has shipped and completed one usage cycle. +- `profile-01-config-layering` owns rollout mode defaults that tune validation + severity without changing evidence semantics. + +## Compatibility Rules + +Shared payloads MUST be additive by default. A change that needs to remove or +rename evidence fields, graph node kinds, severity values, policy modes, or +artifact IDs MUST first update the owning change and document migration impact. + +Dependent changes MAY consume owner-defined payloads, but MUST NOT redefine +their semantics in local proposal text, spec deltas, tests, or implementation +notes. + +## Wave Gates + +A roadmap wave closes only when its evidence is auditable: + +- Active OpenSpec changes validate with `openspec validate --strict`. +- Closed GitHub issues are archived instead of left as planned work. +- Validation evidence is available as JSON, not only prose. +- AI-bloat findings and remediation packets can be produced, applied, and + rechecked on a real repository slice. +- Spec Kit and OpenSpec artifacts are documented as upstream inputs whenever + they appear in examples or adapters. + +## Issue Governance + +Before implementation, linked GitHub issues still need the repository governance +checks in `docs/agent-rules/60-github-change-governance.md`: parent, labels, +project assignment, blockers, and blocked-by relationships. The current token +does not expose GitHub Project fields, so board metadata must be rechecked by a +token with `read:project` before a scoped implementation begins. diff --git a/openspec/changes/ai-integration-01-agent-skill/design.md b/openspec/changes/ai-integration-01-agent-skill/design.md index 4830ddec..75e8fea4 100644 --- a/openspec/changes/ai-integration-01-agent-skill/design.md +++ b/openspec/changes/ai-integration-01-agent-skill/design.md @@ -1,6 +1,8 @@ ## Context -This change implements proposal scope for `ai-integration-01-agent-skill` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. +This change implements the narrowed validation-skill scope for +`ai-integration-01-agent-skill`. It is proposal-stage only and defines +implementation strategy without changing runtime code. ## Goals / Non-Goals @@ -14,7 +16,8 @@ This change implements proposal scope for `ai-integration-01-agent-skill` from t - No production code implementation in this stage. - No schema-breaking changes outside declared capabilities. -- No dependency expansion beyond the proposal and plan. +- No upstream intent interviews, requirement authoring, or architecture + generation. ## Decisions @@ -38,5 +41,6 @@ This change implements proposal scope for `ai-integration-01-agent-skill` from t ## Open Questions -- Dependency summary: Depends on validation-02-full-chain-engine. +- Dependency summary: Depends on governance-01-evidence-output and + validation-02-full-chain-engine. - Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/ai-integration-01-agent-skill/proposal.md b/openspec/changes/ai-integration-01-agent-skill/proposal.md index 5fb6b1d2..b4766f71 100644 --- a/openspec/changes/ai-integration-01-agent-skill/proposal.md +++ b/openspec/changes/ai-integration-01-agent-skill/proposal.md @@ -1,31 +1,32 @@ -# Change: Agent Skill for Spec Intelligence (Skills-First Interface) +# Change: Agent Skill for SpecFact Validation ## Why -AI IDEs generate 41% of all code with zero specification validation. No spec-driven tool offers a Skills-first integration that keeps context usage near-zero until activated. Agent Skills — adopted by 26+ platforms (Claude Code, Copilot, Cursor, Windsurf, Gemini CLI, Codex) in under two months — provide the most context-efficient integration path: ~80 tokens at rest vs 13,647+ tokens for MCP servers. A SpecFact Agent Skill teaches AI agents when and how to invoke SpecFact validation, making specification intelligence available across the entire AI IDE ecosystem with a single implementation. +AI IDEs need a low-context way to invoke SpecFact after they change code, read +the evidence, apply remediation packets, and rerun proof. A skills-first +integration is a good distribution path because it keeps the CLI authoritative +and avoids a large always-loaded MCP context. ## What Changes -- **NEW**: Agent Skill at `skills/specfact/SKILL.md` following the open standard: - - YAML frontmatter: name, description, allowed-tools (bash/terminal) - - Markdown instructions: when to invoke SpecFact, what validation modes exist, how to interpret results - - Progressive disclosure: agents see ~80 tokens of metadata at session start, load full instructions (~2,000-3,000 tokens) only when spec-related work is detected -- **NEW**: Per-workflow composable sub-skills: - - `skills/specfact-assess-pr/SKILL.md` — validate a PR against impacted business requirements - - `skills/specfact-check-architecture/SKILL.md` — verify code changes align with architectural decisions - - `skills/specfact-coverage/SKILL.md` — show which requirements have full traceability -- **NEW**: Skill-triggered CLI invocation patterns: - - On API file edit → `specfact validate --full-chain --output json` - - On PR review → `specfact trace show REQ-{id}` for impacted requirements - - On new endpoint → `specfact requirements list --show-coverage` to check for orphans -- **NEW**: `specfact ide skill install` — copy skill files to the appropriate location for the current project -- **NEW**: Skill bundled resources: common spec patterns, validation result interpretation guide, example workflows +- **NEW**: Agent Skill at `skills/specfact/SKILL.md` that teaches agents when + and how to run SpecFact validation and code review. +- **NEW**: Skill instructions for interpreting JSON evidence, severity, policy + exceptions, `ai_bloat` advisories, cleanup forecasts, and remediation packets. +- **NEW**: Small workflow sub-skills focused on validation use cases: + PR evidence review, code-bloat cleanup loop, contract/spec validation, and + rerun comparison. +- **NEW**: `specfact ide skill install` copies skill files to the appropriate + project or IDE location. +- **REMOVED FROM SCOPE**: Upstream intent interviews, requirement authoring, and + architecture generation. ## Capabilities ### New Capabilities -- `agent-skill-spec-intelligence`: Agent Skill (open standard, 26+ platform support) for specification validation, traceability queries, and requirements coverage — ~80 tokens at rest, ~2,000-3,000 tokens on activation. Includes composable sub-skills for PR assessment, architecture checking, and coverage reporting. +- `agent-skill-validation`: Agent Skill for running SpecFact validation, + interpreting evidence, applying remediation packets, and rerunning proof. ### Modified Capabilities @@ -40,4 +41,4 @@ AI IDEs generate 41% of all code with zero specification validation. No spec-dri - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/251> - **Last Synced Status**: proposed - **Sanitized**: false -<!-- content_hash: 2b715dada0ffb0b0 --> \ No newline at end of file +<!-- content_hash: 2b715dada0ffb0b0 --> diff --git a/openspec/changes/ai-integration-02-mcp-server/design.md b/openspec/changes/ai-integration-02-mcp-server/design.md index 02b58c07..bf1582ae 100644 --- a/openspec/changes/ai-integration-02-mcp-server/design.md +++ b/openspec/changes/ai-integration-02-mcp-server/design.md @@ -1,6 +1,8 @@ ## Context -This change implements proposal scope for `ai-integration-02-mcp-server` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. +This change implements the gated thin-MCP-adapter scope for +`ai-integration-02-mcp-server`. It is proposal-stage only and defines +implementation strategy without changing runtime code. ## Goals / Non-Goals @@ -14,7 +16,7 @@ This change implements proposal scope for `ai-integration-02-mcp-server` from th - No production code implementation in this stage. - No schema-breaking changes outside declared capabilities. -- No dependency expansion beyond the proposal and plan. +- No broad MCP surface before the CLI validation loop shows pull. ## Decisions @@ -38,5 +40,6 @@ This change implements proposal scope for `ai-integration-02-mcp-server` from th ## Open Questions -- Dependency summary: Depends on validation-02-full-chain-engine. +- Dependency summary: Depends on ai-integration-01-agent-skill, + governance-01-evidence-output, and validation-02-full-chain-engine. - Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/ai-integration-02-mcp-server/proposal.md b/openspec/changes/ai-integration-02-mcp-server/proposal.md index 33b17274..930b5e75 100644 --- a/openspec/changes/ai-integration-02-mcp-server/proposal.md +++ b/openspec/changes/ai-integration-02-mcp-server/proposal.md @@ -1,28 +1,35 @@ -# Change: MCP Server — Programmatic Tool Interface for Agentic Workflows +# Change: MCP Adapter for Validation Tools ## Why -While the Agent Skill handles 90% of developer interactions via CLI invocation, agentic workflows (CI/CD pipelines, autonomous coding agents, multi-step validation loops) need programmatic tool access with structured inputs and outputs. MCP (Model Context Protocol) — adopted by every major AI platform with 97M+ monthly SDK downloads — provides the standard interface. An MCP server exposing 3-5 high-level tools with compressed, summarized results gives SpecFact programmatic accessibility without the context bloat of naive MCP implementations. +An MCP server may be useful after the CLI validation loop has real pull, but it +should remain a thin adapter over trusted CLI behavior. Shipping a broad MCP +surface early would distract from the flagship validation and AI-bloat defense +path. + +## Gate + +This change is gated until `ai-integration-01-agent-skill` has shipped and at +least one real user or dogfooding workflow shows pull for programmatic +validation access. ## What Changes -- **NEW**: MCP server in `src/specfact_cli/mcp/` exposing high-level tools: - - `validate_spec(spec_path, options)` — run validation (spec-only or full-chain), return compressed summary - - `check_compatibility(base_spec, revision_spec)` — breaking change detection between spec versions - - `get_requirement_coverage(requirement_id)` — traceability status for a specific requirement - - `suggest_fixes(validation_report_path)` — actionable fix recommendations for validation failures -- **NEW**: Server-side summarization — tools never return raw specs or full diffs; only compressed, actionable summaries suitable for LLM context windows -- **NEW**: Dual-response pattern: concise text summary for LLM reasoning + ResourceLink URI for full reports that agents can fetch on demand -- **NEW**: `specfact mcp serve` — start the MCP server (stdio transport for IDE integration, HTTP/SSE for CI/CD) -- **NEW**: `specfact mcp install` — generate MCP server configuration for Claude Desktop, Cursor, VS Code, etc. -- **NEW**: Tool count disciplined to 3-5 tools per MCP best practices (Phil Schmid: 5-15 maximum) -- **DESIGN DECISION**: MCP server wraps CLI commands internally — the CLI remains the source of truth, MCP is a thin adapter layer +- **NEW**: MCP server exposing only 2-3 high-value validation tools: + `run_validation`, `read_evidence`, and optionally `prepare_remediation`. +- **NEW**: Server-side summarization that returns bounded evidence summaries and + resource links instead of raw specs, raw diffs, or full reports. +- **NEW**: `specfact mcp serve` starts stdio transport for IDE integration. +- **NEW**: `specfact mcp install` generates minimal IDE configuration. +- **DESIGN DECISION**: MCP wraps CLI commands internally. The CLI remains the + source of truth. ## Capabilities ### New Capabilities -- `mcp-server`: MCP server exposing 3-5 high-level specification intelligence tools with server-side summarization, dual-response pattern, stdio and HTTP/SSE transports. Wraps CLI commands as thin adapter layer. +- `mcp-validation-adapter`: Thin MCP adapter exposing a minimal validation and + evidence-reading surface after CLI demand is proven. ### Modified Capabilities @@ -37,4 +44,4 @@ While the Agent Skill handles 90% of developer interactions via CLI invocation, - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/252> - **Last Synced Status**: proposed - **Sanitized**: false -<!-- content_hash: 83b763280fc0b831 --> \ No newline at end of file +<!-- content_hash: 83b763280fc0b831 --> diff --git a/openspec/changes/ai-integration-03-instruction-files/proposal.md b/openspec/changes/ai-integration-03-instruction-files/proposal.md index 1e05fe88..d73d42da 100644 --- a/openspec/changes/ai-integration-03-instruction-files/proposal.md +++ b/openspec/changes/ai-integration-03-instruction-files/proposal.md @@ -1,34 +1,36 @@ -# Change: Cross-Platform AI IDE Instruction Files +# Change: Cross-Platform AI IDE Validation Instructions ## Why -Each AI IDE has its own instruction file format (`.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, `CLAUDE.md`, `.windsurf/rules/`). Teams using multiple IDEs need SpecFact guidance in each format. Auto-generated lightweight instruction files that point to the core Agent Skill — with glob-based auto-attachment on spec files — ensure consistent spec validation guidance across all IDEs without manual per-platform maintenance. +Teams use several AI IDEs, each with a different instruction-file format. Those +files should point agents to SpecFact validation and remediation loops without +embedding long planning workflows or clean-code charters inline. ## What Changes -- **NEW**: `specfact ide setup --platforms cursor,copilot,claude,windsurf` — auto-generate instruction files for selected platforms: - - `.cursor/rules/specfact.mdc` — Cursor rule with glob: `**/*.yaml, **/*.json, **/openapi*` - - `.github/instructions/specfact.instructions.md` — Copilot instructions with `applyTo` glob - - `CLAUDE.md` additions — Claude Code project instructions - - `.windsurf/rules/specfact.md` — Windsurf rule file -- **NEW**: Each instruction file is a lightweight alias (~200-500 tokens) pointing to the core Agent Skill: - - When to invoke SpecFact (on API file edits, PR reviews, new endpoints) - - How to invoke (`specfact validate`, `specfact trace`, `specfact requirements`) - - How to interpret results (pass/fail/advisory meanings) -- **NEW**: `specfact ide setup --update` — regenerate instruction files to match latest skill content -- **NEW**: Glob-based auto-attachment: instruction files activate automatically when developer works on spec-related files (`*.yaml`, `*.json`, `**/openapi*`, `**/asyncapi*`) -- **NEW**: Instruction file template system: instruction content is generated from a single source template, ensuring consistency across all platform formats -- **MODIFY**: Generated instruction files stay lightweight and MUST reference clean-code enforcement through a one-line alias to the canonical `specfact-code-review` skill instead of embedding the full 7-principle charter inline +- **NEW**: `specfact ide setup --platforms cursor,copilot,claude,windsurf` + generates lightweight instruction files for selected platforms. +- **NEW**: Generated files tell agents when to run SpecFact validation, how to + find JSON evidence, how to handle `ai_bloat` remediation packets, and when to + rerun proof. +- **NEW**: `specfact ide setup --update` regenerates instruction files from the + canonical validation skill template. +- **NEW**: Glob-based attachment focuses on code, spec, contract, and test files + where validation evidence is relevant. +- **MODIFY**: Clean-code enforcement is referenced by alias to the canonical + code-review skill, not copied inline. ## Capabilities ### New Capabilities -- `cross-platform-instructions`: Auto-generated AI IDE instruction files for Cursor, Copilot, Claude Code, and Windsurf. Lightweight aliases pointing to the core Agent Skill, with glob-based auto-attachment on spec files. +- `cross-platform-validation-instructions`: Auto-generated AI IDE instruction + files that point to SpecFact validation, evidence interpretation, remediation, + and rerun proof. ### Modified Capabilities -- `cross-platform-instructions`: Extended so generated aliases can reference clean-code enforcement without breaking the lightweight token budget for IDE instruction surfaces +(none) --- diff --git a/openspec/changes/ai-integration-04-intent-skills/proposal.md b/openspec/changes/ai-integration-04-intent-skills/proposal.md deleted file mode 100644 index e1099523..00000000 --- a/openspec/changes/ai-integration-04-intent-skills/proposal.md +++ /dev/null @@ -1,47 +0,0 @@ -# Change: Intent Engineering Skills — SQUER Workflow for AI IDEs - -## Why - -AI IDEs generate requirements, architecture, and code but have no structured intent-capture workflow. The result is "green specs, wrong product" — every contract passes but the shipped feature misses the business outcome because no tool validated the upstream intent. `ai-integration-01-agent-skill` ships general spec-validation skills; it does not provide the upstream intent-engineering workflow (7-question business interview, requirements decomposition, architecture derivation, trace validation). A dedicated intent skills set — following the SQUER intent interview model and the open Agent Skills standard — closes this gap by making persona-outcome capture and traceability validation available as first-class IDE slash commands across all 26+ AI IDE platforms. - -## What Changes - -- **NEW**: Intent-engineering Agent Skills at `skills/specfact-intent/`: - - `skills/specfact-intent/SKILL.md` — umbrella intent skills entrypoint; ~80 tokens at rest, full instructions on activation - - `skills/specfact-intent-capture/SKILL.md` — SQUER 7-question intent interview: What problem? Who has it? What happens today? What should change? How will we know? What must not break? What's the priority? Captures to `.specfact/requirements/{id}.req.yaml` - - `skills/specfact-intent-decompose/SKILL.md` — Takes captured BusinessOutcome, decomposes into BusinessRules (Given/When/Then) and ArchitecturalConstraints - - `skills/specfact-intent-architecture/SKILL.md` — Generates Architecture Decision Records from requirements context using `specfact architecture derive` - - `skills/specfact-intent-trace-validate/SKILL.md` — Validates full traceability chain (outcome → code), reports gaps with fix prompts - - `skills/specfact-intent-evidence-check/SKILL.md` — Checks evidence completeness for all artifacts in the chain -- **NEW**: `specfact ide skill install --type intent` — copies intent skills to the correct location for the active AI IDE -- **NEW**: Prompt-validate-feedback loop documentation: pattern for using intent skills with `specfact validate --full-chain` in a 3-phase cycle (prompt → validate → feedback) -- **EXTEND**: `specfact ide skill install` — adds `--type intent` option alongside existing `--type spec` (ai-integration-01) -- **EXTEND**: Skills discovery: intent skills listed by `specfact ide skill list` - -## Capabilities - -### New Capabilities - -- `agent-skill-intent-workflow`: SQUER 7-question intent capture skill (~80 tokens at rest), BusinessRule G/W/T decomposition skill, architecture derivation skill, traceability validation skill, and evidence-check skill — all following the open Agent Skills standard for 26+ AI IDE platforms. Installed via `specfact ide skill install --type intent`. - -### Modified Capabilities - -- `agent-skill-spec-intelligence`: Extended skill discovery and install CLI to support `--type` selector (spec vs intent); `specfact ide skill list` enumerates both skill types. - -## Impact - -- New directory: `skills/specfact-intent*/` (6 skill files, ~2,000-3,000 tokens each) -- CLI change: `specfact ide skill install --type {spec,intent}` (new `--type` option, backwards-compatible default `spec`) -- Depends on: `ai-integration-01-agent-skill` (#251) — must land first; `requirements-01-data-model` (#238) — intent skills invoke `specfact requirements capture`; `requirements-02-module-commands` (#239) — skills call `specfact requirements validate` and `specfact requirements trace` -- Wave 8 — blocked by ai-integration-01 (#251) and requirements-02 (#239) -- Docs: new guide `docs/guides/intent-capture-workflow.md`; update `docs/guides/ai-ide-workflow.md` to include intent skills - ---- - -## Source Tracking - -<!-- source_repo: nold-ai/specfact-cli --> -- **GitHub Issue**: #349 -- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/349> -- **Repository**: nold-ai/specfact-cli -- **Last Synced Status**: proposed diff --git a/openspec/changes/architecture-01-solution-layer/proposal.md b/openspec/changes/architecture-01-solution-layer/proposal.md index c263a126..26884c9d 100644 --- a/openspec/changes/architecture-01-solution-layer/proposal.md +++ b/openspec/changes/architecture-01-solution-layer/proposal.md @@ -1,110 +1,49 @@ -# Change: Solution Architecture Layer — Derive, Store, Validate +# Change: Architecture Boundary Validation Inputs ## Why -Architectural decisions live in separate ADRs or Confluence pages with zero programmatic links to requirements or code. This is the layer where the costliest misalignments occur — a wrong architectural choice invalidates entire implementation efforts regardless of code quality. No tool today systematically connects business requirements → architectural decisions → implementation. A solution architecture module that derives, stores, and validates architecture with explicit traceability to requirements closes the biggest blind spot in the end-to-end chain. +Architecture context is valuable to SpecFact when it helps validate code reality: +boundary violations, missing ADR evidence, stale component ownership, and +contracts that no longer match the intended design. SpecFact should not compete +with planning or architecture-generation tools. -## Ownership Alignment (2026-04-08) +This change narrows the old solution-layer proposal to architecture-boundary +records and drift evidence used by validation. -- Repository assignment: `split/rescope` -- Core-owned scope retained here: shared architecture schema, namespace extension ownership, and cross-change contracts. -- Bundle-owned follow-up required: the flat `specfact architecture ...` command family and `modules/architecture/...` package structure below are not canonical in the grouped command model. -- Target modules-repo follow-up issue: [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) in `nold-ai/specfact-cli-modules` -- Implementation MUST NOT proceed from the legacy package layout below until a bundle-owned follow-up defines the correct command surface. - -## Module Package Structure - -``` -modules/architecture/ - module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace - src/architecture/ - __init__.py - main.py # typer.Typer app — architecture command group - engine/ - deriver.py # Derive architecture from requirements (template + AI-assisted) - coverage_validator.py # Validate architecture covers all requirements - trace_builder.py # Build architecture ↔ requirements traceability links - models/ - solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models - templates/ - microservice.yaml # Microservice architecture template - monolith.yaml # Modular monolith template - event_driven.yaml # Event-driven architecture template - commands/ - derive.py # specfact architecture derive - validate_coverage.py # specfact architecture validate-coverage - trace.py # specfact architecture trace - storage/ - architecture_store.py # Read/write .specfact/architecture/*.arch.yaml -``` - -**`module-package.yaml` declares:** - -- `name: architecture` -- `version: 0.1.0` -- `commands: [architecture derive, architecture validate-coverage, architecture trace]` -- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness +## Ownership Alignment (2026-06-06) -## Module Package Structure - -``` -modules/architecture/ - module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace - src/architecture/ - __init__.py - main.py # typer.Typer app — architecture command group - engine/ - deriver.py # Derive architecture from requirements (template + AI-assisted) - coverage_validator.py # Validate architecture covers all requirements - trace_builder.py # Build architecture ↔ requirements traceability links - models/ - solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models - templates/ - microservice.yaml # Microservice architecture template - monolith.yaml # Modular monolith template - event_driven.yaml # Event-driven architecture template - commands/ - derive.py # specfact architecture derive - validate_coverage.py # specfact architecture validate-coverage - trace.py # specfact architecture trace - storage/ - architecture_store.py # Read/write .specfact/architecture/*.arch.yaml -``` - -**`module-package.yaml` declares:** - -- `name: architecture` -- `version: 0.1.0` -- `commands: [architecture derive, architecture validate-coverage, architecture trace]` -- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Repository assignment: `split/rescope` +- Core-owned scope retained here: architecture input schema, namespace extension + ownership, and validation hooks. +- Bundle-owned follow-up required: runtime delivery belongs to the canonical + grouped module command model. +- Target modules-repo follow-up issue: [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) +- Implementation MUST NOT ship architecture generation as the product path. ## What Changes -- **NEW**: Pydantic domain models in `modules/architecture/src/architecture/models/`: - - `SolutionArchitecture` — architecture ID, requirement IDs (traceability links), components, data flows, ADRs - - `ComponentSpec` — name, responsibility, business rule IDs (from requirements), integrations - - `DataFlow` — source, target, data type, protocol - - `ADR` — ADR ID, decision, rationale (links to architectural constraints from requirements), alternatives considered, tradeoff -- **NEW**: `specfact architecture derive --requirements .specfact/requirements/ --suggest-components --interactive` — derive architecture from requirements using templates and optional AI assistance -- **NEW**: `specfact architecture validate-coverage` — verify every business rule maps to a component, every architectural constraint has an ADR, every component has spec coverage -- **NEW**: `specfact architecture trace --format table|json|markdown` — show traceability matrix: requirements ↔ components ↔ ADRs ↔ specs -- **NEW**: Storage convention: `.specfact/architecture/{architecture_id}.arch.yaml` -- **NEW**: Architecture templates for common patterns (microservice, monolith, event-driven) — profile-aware complexity -- **EXTEND**: `ProjectBundle` extended with optional `architecture` field via arch-07 schema extensions (namespace: `architecture.solution_architecture`) +- **NEW**: Architecture-boundary input models for components, ownership, + interfaces, data-flow hints, ADR references, and validation constraints. +- **NEW**: Storage/import convention for architecture records that originate from + existing ADRs, diagrams, docs, Spec Kit plans, or OpenSpec design notes. +- **NEW**: Coverage checks that classify missing ADR links, interface leaks, + component ownership gaps, and mismatched contract boundaries. +- **EXTEND**: `ProjectBundle` receives an optional architecture-boundary + namespace through the schema extension system. +- **REMOVED FROM CRITICAL PATH**: AI-assisted architecture derivation and + template-based architecture authoring. ## Capabilities ### New Capabilities -- `solution-architecture`: Derive, store, and validate solution architecture with explicit traceability to business requirements. Includes component specs, data flows, ADRs, and coverage validation. +- `architecture-boundary-validation-inputs`: Architecture records and validation + hooks for boundary, ADR, interface, and component drift evidence. ### Modified Capabilities -- `data-models`: ProjectBundle extended with architecture field via arch-07 schema extensions +- `data-models`: ProjectBundle extended with an optional architecture-boundary + namespace. --- diff --git a/openspec/changes/architecture-02-well-architected-review/proposal.md b/openspec/changes/architecture-02-well-architected-review/proposal.md index 7826280b..274f7a68 100644 --- a/openspec/changes/architecture-02-well-architected-review/proposal.md +++ b/openspec/changes/architecture-02-well-architected-review/proposal.md @@ -1,33 +1,55 @@ -# Change: Well-Architected and Clean-Architecture Review Layer +# Change: Architecture Boundary Review Layer + +## Blocked Status + +BLOCKED ON: `architecture-01-solution-layer` shipped plus one complete usage +cycle with real validation evidence. ## Why -`architecture-01-solution-layer` establishes solution architecture as a modeled layer, but it does not yet score designs against boundary, interface, and well-architected review rules. This change turns architecture from passive documentation into an active review pillar that catches layer violations and missing ADR traceability before implementation drifts. +Architecture review is useful when it strengthens validation evidence: boundary +violations, interface leaks, layer inversions, missing ADR links, and coupling +hotspots that explain why a code change is risky. This change stays downstream +of the architecture-boundary input model and does not generate or prescribe +architecture. ## What Changes -- **NEW**: `architecture-review` capability covering architecture findings, review contracts, and `specfact architecture diff`. -- **NEW**: Finding categories for boundary violations, interface leaks, layer inversion, coupling hotspots, missing ADR links, and Well-Architected review dimensions. -- **NEW**: CLI surface to diff interface changes and classify them as breaking, non-breaking, or additive. -- **EXTEND**: ADR-to-code traceability rules so the architecture layer can emit review findings, not just references. -- **EXTEND**: Shared review-report integration so architecture findings can live beside code quality, security, and resiliency pillars. +- **NEW**: `architecture-review` capability covering boundary findings, review + contracts, and interface-diff evidence. +- **NEW**: Finding categories for boundary violations, interface leaks, layer + inversion, coupling hotspots, missing ADR links, and selected Well-Architected + review dimensions. +- **NEW**: CLI/report surface to classify interface changes as breaking, + non-breaking, additive, or evidence-missing. +- **EXTEND**: ADR-to-code traceability rules so architecture context can emit + review findings. +- **EXTEND**: Shared review-report integration so architecture findings can live + beside code quality, security, resiliency, and validation graph evidence. -**Backward-compatible envelope:** The existing `ReviewReport` envelope stays stable for legacy parsers: required sections and field names used today remain unchanged. Implementations add an optional top-level `architecture` object (or, if we standardize a single extension map first, an optional `extensions.architecture` object) so older consumers ignore unknown keys while new consumers read the pillar. Serialized contract for review runs: **review runs MUST include an `architecture` section in the shared envelope while preserving other review sections unchanged** (e.g., `code_quality`, `security`, `resiliency` keys and their payloads stay as today). Example shape: `ReviewReport { ..., "architecture"?: { "findings": [...], "summary": {...} } }` — exact inner fields follow `specs/architecture-review/spec.md`; parsers MUST treat missing `architecture` as “no architecture findings” until emitters roll out. +**Backward-compatible envelope:** The existing `ReviewReport` envelope stays +stable for legacy parsers. Implementations add an optional top-level +`architecture` object, or an optional `extensions.architecture` object if a +single extension map lands first. ## Capabilities ### New Capabilities -- `architecture-review`: Architecture review findings, interface-diff contract, and ADR traceability enforcement. +- `architecture-review`: Architecture-boundary review findings, interface-diff + contract, and ADR traceability enforcement. ### Modified Capabilities -- `solution-architecture`: Extend the solution layer so ADR and interface metadata can feed the architecture review surface. +- `architecture-boundary-validation-inputs`: Extended so ADR and interface + metadata can feed the architecture review surface. ## Impact -- Depends on `architecture-01-solution-layer`, `review-finding-model`, and `review-report-model`. -- Supplies the contract consumed by the modules-side `architecture-02-module-well-architected` bundle. +- Depends on `architecture-01-solution-layer`, `review-finding-model`, and + `review-report-model`. +- Supplies the contract consumed by the modules-side + `architecture-02-module-well-architected` bundle. - Affects docs and future governance evidence flows; no existing API is removed. --- diff --git a/openspec/changes/upgrade-01-install-method-aware/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/upgrade-01-install-method-aware/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/TDD_EVIDENCE.md diff --git a/openspec/changes/upgrade-01-install-method-aware/proposal.md b/openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/proposal.md similarity index 100% rename from openspec/changes/upgrade-01-install-method-aware/proposal.md rename to openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/proposal.md diff --git a/openspec/changes/upgrade-01-install-method-aware/specs/upgrade-command/spec.md b/openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/specs/upgrade-command/spec.md similarity index 100% rename from openspec/changes/upgrade-01-install-method-aware/specs/upgrade-command/spec.md rename to openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/specs/upgrade-command/spec.md diff --git a/openspec/changes/upgrade-01-install-method-aware/tasks.md b/openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/tasks.md similarity index 100% rename from openspec/changes/upgrade-01-install-method-aware/tasks.md rename to openspec/changes/archive/2026-06-02-upgrade-01-install-method-aware/tasks.md diff --git a/openspec/changes/dep-security-cleanup/.openspec.yaml b/openspec/changes/archive/2026-06-06-dep-security-cleanup/.openspec.yaml similarity index 100% rename from openspec/changes/dep-security-cleanup/.openspec.yaml rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/.openspec.yaml diff --git a/openspec/changes/dep-security-cleanup/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/dep-security-cleanup/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/TDD_EVIDENCE.md diff --git a/openspec/changes/dep-security-cleanup/design.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/design.md similarity index 100% rename from openspec/changes/dep-security-cleanup/design.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/design.md diff --git a/openspec/changes/dep-security-cleanup/proposal.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/proposal.md similarity index 100% rename from openspec/changes/dep-security-cleanup/proposal.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/proposal.md diff --git a/openspec/changes/dep-security-cleanup/specs/call-graph-analysis/spec.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/call-graph-analysis/spec.md similarity index 100% rename from openspec/changes/dep-security-cleanup/specs/call-graph-analysis/spec.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/call-graph-analysis/spec.md diff --git a/openspec/changes/dep-security-cleanup/specs/dep-license-gate/spec.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dep-license-gate/spec.md similarity index 100% rename from openspec/changes/dep-security-cleanup/specs/dep-license-gate/spec.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dep-license-gate/spec.md diff --git a/openspec/changes/dep-security-cleanup/specs/dependency-resolution/spec.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dependency-resolution/spec.md similarity index 100% rename from openspec/changes/dep-security-cleanup/specs/dependency-resolution/spec.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/specs/dependency-resolution/spec.md diff --git a/openspec/changes/dep-security-cleanup/tasks.md b/openspec/changes/archive/2026-06-06-dep-security-cleanup/tasks.md similarity index 100% rename from openspec/changes/dep-security-cleanup/tasks.md rename to openspec/changes/archive/2026-06-06-dep-security-cleanup/tasks.md diff --git a/openspec/changes/integration-01-cross-change-contracts/.openspec.yaml b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/.openspec.yaml similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/.openspec.yaml rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/.openspec.yaml diff --git a/openspec/changes/integration-01-cross-change-contracts/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/CHANGE_VALIDATION.md diff --git a/openspec/changes/integration-01-cross-change-contracts/design.md b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/design.md similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/design.md rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/design.md diff --git a/openspec/changes/integration-01-cross-change-contracts/proposal.md b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/proposal.md similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/proposal.md rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/proposal.md diff --git a/openspec/changes/integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md diff --git a/openspec/changes/integration-01-cross-change-contracts/tasks.md b/openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/tasks.md similarity index 100% rename from openspec/changes/integration-01-cross-change-contracts/tasks.md rename to openspec/changes/archive/2026-06-06-integration-01-cross-change-contracts/tasks.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/.openspec.yaml b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/.openspec.yaml similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/.openspec.yaml rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/.openspec.yaml diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/TDD_EVIDENCE.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/design.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/design.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/design.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/design.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/proposal.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/proposal.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/proposal.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/proposal.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/specs/init-module-state/spec.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/init-module-state/spec.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/specs/init-module-state/spec.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/init-module-state/spec.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/specs/module-installation/spec.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md similarity index 98% rename from openspec/changes/marketplace-07-module-install-state-consistency/specs/module-installation/spec.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md index 12a5bb8f..56a94746 100644 --- a/openspec/changes/marketplace-07-module-install-state-consistency/specs/module-installation/spec.md +++ b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/module-installation/spec.md @@ -28,6 +28,8 @@ When a user installs a module whose artifact already exists in the selected scop - **THEN** the command MAY skip reinstalling the artifact - **AND** the command SHALL report that the module is already installed and available from the selected scope +## MODIFIED Requirements + ### Requirement: Missing Command Diagnostics Explain Installed-Unavailable Causes When a known module-provided command group is not registered, the system SHALL distinguish an absent module from an installed module that is unavailable for another local reason. @@ -55,6 +57,8 @@ When a known module-provided command group is not registered, the system SHALL d - **THEN** the CLI SHALL keep reporting that the module is not installed - **AND** the CLI SHALL include install or init profile guidance +## ADDED Requirements: Canonical Module Identity + ### Requirement: Module Install Uses Canonical Module Identity The system SHALL resolve install requests, discovered manifest IDs, and lifecycle state rows to a canonical module identity before deciding whether an install is already satisfied. diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/specs/user-module-root/spec.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/user-module-root/spec.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/specs/user-module-root/spec.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/specs/user-module-root/spec.md diff --git a/openspec/changes/marketplace-07-module-install-state-consistency/tasks.md b/openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/tasks.md similarity index 100% rename from openspec/changes/marketplace-07-module-install-state-consistency/tasks.md rename to openspec/changes/archive/2026-06-06-marketplace-07-module-install-state-consistency/tasks.md diff --git a/openspec/changes/module-scope-version-diagnostics/.openspec.yaml b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/.openspec.yaml similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/.openspec.yaml rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/.openspec.yaml diff --git a/openspec/changes/module-scope-version-diagnostics/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/TDD_EVIDENCE.md diff --git a/openspec/changes/module-scope-version-diagnostics/design.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/design.md similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/design.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/design.md diff --git a/openspec/changes/module-scope-version-diagnostics/proposal.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/proposal.md similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/proposal.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/proposal.md diff --git a/openspec/changes/module-scope-version-diagnostics/specs/module-installation/spec.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-installation/spec.md similarity index 97% rename from openspec/changes/module-scope-version-diagnostics/specs/module-installation/spec.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-installation/spec.md index 06930ed5..60a166d2 100644 --- a/openspec/changes/module-scope-version-diagnostics/specs/module-installation/spec.md +++ b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-installation/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Module install enforces versioned bundle dependencies diff --git a/openspec/changes/module-scope-version-diagnostics/specs/module-packages/spec.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-packages/spec.md similarity index 97% rename from openspec/changes/module-scope-version-diagnostics/specs/module-packages/spec.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-packages/spec.md index 0d27d767..e53d21a0 100644 --- a/openspec/changes/module-scope-version-diagnostics/specs/module-packages/spec.md +++ b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-packages/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Module registration enforces versioned module dependencies diff --git a/openspec/changes/module-scope-version-diagnostics/specs/module-scope-diagnostics/spec.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-scope-diagnostics/spec.md similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/specs/module-scope-diagnostics/spec.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/specs/module-scope-diagnostics/spec.md diff --git a/openspec/changes/module-scope-version-diagnostics/tasks.md b/openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/tasks.md similarity index 100% rename from openspec/changes/module-scope-version-diagnostics/tasks.md rename to openspec/changes/archive/2026-06-06-module-scope-version-diagnostics/tasks.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/.openspec.yaml b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/.openspec.yaml similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/.openspec.yaml rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/.openspec.yaml diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/TDD_EVIDENCE.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/design.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/design.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/design.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/design.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/proposal.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/proposal.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/proposal.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/proposal.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md diff --git a/openspec/changes/profile-04-safe-project-artifact-writes/tasks.md b/openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/tasks.md similarity index 100% rename from openspec/changes/profile-04-safe-project-artifact-writes/tasks.md rename to openspec/changes/archive/2026-06-06-profile-04-safe-project-artifact-writes/tasks.md diff --git a/openspec/changes/runtime-01-discovery-reliability/.openspec.yaml b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/.openspec.yaml similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/.openspec.yaml rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/.openspec.yaml diff --git a/openspec/changes/runtime-01-discovery-reliability/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/TDD_EVIDENCE.md diff --git a/openspec/changes/runtime-01-discovery-reliability/proposal.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/proposal.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/proposal.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/proposal.md diff --git a/openspec/changes/runtime-01-discovery-reliability/specs/environment-manager-detection/spec.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/environment-manager-detection/spec.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/specs/environment-manager-detection/spec.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/environment-manager-detection/spec.md diff --git a/openspec/changes/runtime-01-discovery-reliability/specs/installed-runtime-module-discovery/spec.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/installed-runtime-module-discovery/spec.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/specs/installed-runtime-module-discovery/spec.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/installed-runtime-module-discovery/spec.md diff --git a/openspec/changes/runtime-01-discovery-reliability/specs/module-installation/spec.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-installation/spec.md similarity index 97% rename from openspec/changes/runtime-01-discovery-reliability/specs/module-installation/spec.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-installation/spec.md index 3306b979..3d155231 100644 --- a/openspec/changes/runtime-01-discovery-reliability/specs/module-installation/spec.md +++ b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-installation/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Missing Command Diagnostics Explain Installed-Unavailable Causes diff --git a/openspec/changes/runtime-01-discovery-reliability/specs/module-owned-ide-prompts/spec.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-owned-ide-prompts/spec.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/specs/module-owned-ide-prompts/spec.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/specs/module-owned-ide-prompts/spec.md diff --git a/openspec/changes/runtime-01-discovery-reliability/tasks.md b/openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/tasks.md similarity index 100% rename from openspec/changes/runtime-01-discovery-reliability/tasks.md rename to openspec/changes/archive/2026-06-06-runtime-01-discovery-reliability/tasks.md diff --git a/openspec/changes/tester-cli-reliability/.openspec.yaml b/openspec/changes/archive/2026-06-06-tester-cli-reliability/.openspec.yaml similarity index 100% rename from openspec/changes/tester-cli-reliability/.openspec.yaml rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/.openspec.yaml diff --git a/openspec/changes/tester-cli-reliability/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/tester-cli-reliability/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/TDD_EVIDENCE.md diff --git a/openspec/changes/tester-cli-reliability/proposal.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/proposal.md similarity index 100% rename from openspec/changes/tester-cli-reliability/proposal.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/proposal.md diff --git a/openspec/changes/tester-cli-reliability/specs/ci-integration/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/ci-integration/spec.md similarity index 97% rename from openspec/changes/tester-cli-reliability/specs/ci-integration/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/ci-integration/spec.md index b143f507..97749d02 100644 --- a/openspec/changes/tester-cli-reliability/specs/ci-integration/spec.md +++ b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/ci-integration/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Package Manager Runtime Checks Block Pull Requests diff --git a/openspec/changes/tester-cli-reliability/specs/cli-error-guidance/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/cli-error-guidance/spec.md similarity index 100% rename from openspec/changes/tester-cli-reliability/specs/cli-error-guidance/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/cli-error-guidance/spec.md diff --git a/openspec/changes/tester-cli-reliability/specs/command-package-runtime-validation/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/command-package-runtime-validation/spec.md similarity index 99% rename from openspec/changes/tester-cli-reliability/specs/command-package-runtime-validation/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/command-package-runtime-validation/spec.md index 951306a9..b75ae409 100644 --- a/openspec/changes/tester-cli-reliability/specs/command-package-runtime-validation/spec.md +++ b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/command-package-runtime-validation/spec.md @@ -48,6 +48,8 @@ The system SHALL execute the command inventory in a deterministic order that mat - **AND** nested command families are executed under their owning root in a stable order - **AND** the audit report shows which phase each command belonged to. +## ADDED Requirements + ### Requirement: Package Manager Runtime Matrix Blocks Command Mismatches The command validation surface SHALL run through representative hatch, pip, pipx, and uv launchers before PRs can merge. diff --git a/openspec/changes/tester-cli-reliability/specs/core-cli-reference/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/core-cli-reference/spec.md similarity index 100% rename from openspec/changes/tester-cli-reliability/specs/core-cli-reference/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/core-cli-reference/spec.md diff --git a/openspec/changes/tester-cli-reliability/specs/generated-command-overview/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/generated-command-overview/spec.md similarity index 100% rename from openspec/changes/tester-cli-reliability/specs/generated-command-overview/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/generated-command-overview/spec.md diff --git a/openspec/changes/tester-cli-reliability/specs/runtime-tool-probing/spec.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/runtime-tool-probing/spec.md similarity index 100% rename from openspec/changes/tester-cli-reliability/specs/runtime-tool-probing/spec.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/specs/runtime-tool-probing/spec.md diff --git a/openspec/changes/tester-cli-reliability/tasks.md b/openspec/changes/archive/2026-06-06-tester-cli-reliability/tasks.md similarity index 100% rename from openspec/changes/tester-cli-reliability/tasks.md rename to openspec/changes/archive/2026-06-06-tester-cli-reliability/tasks.md diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/.openspec.yaml b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/.openspec.yaml similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/.openspec.yaml rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/.openspec.yaml diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/TDD_EVIDENCE.md diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/design.md b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/design.md similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/design.md rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/design.md diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/proposal.md b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/proposal.md similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/proposal.md rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/proposal.md diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/specs/upgrade-command/spec.md b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/specs/upgrade-command/spec.md similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/specs/upgrade-command/spec.md rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/specs/upgrade-command/spec.md diff --git a/openspec/changes/upgrade-02-pipx-spaced-home-output/tasks.md b/openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/tasks.md similarity index 100% rename from openspec/changes/upgrade-02-pipx-spaced-home-output/tasks.md rename to openspec/changes/archive/2026-06-06-upgrade-02-pipx-spaced-home-output/tasks.md diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md index 1554fafb..811cb70d 100644 --- a/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md @@ -1,12 +1,14 @@ ## Context -This change defines an auditable dogfooding path proving the complete business-to-code traceability chain for SpecFact CLI itself. +This change defines an auditable dogfooding path proving SpecFact's validation +and AI-bloat defense loop on real project artifacts. ## Goals / Non-Goals **Goals:** -- Produce objective E2E proof artifacts for the full-chain claim. +- Produce objective proof artifacts for JSON evidence, AI-bloat findings, + remediation packets, rerun comparison, and improved validation evidence. - Ensure proof is reproducible in CI and local workflows. - Tie proof to release readiness and product positioning. @@ -14,24 +16,27 @@ This change defines an auditable dogfooding path proving the complete business-t - No unrelated feature expansion. - No synthetic-only demo path; evidence must use real project artifacts. +- No requirement that SpecFact own the upstream planning lifecycle. ## Decisions -- Use a bounded backlog slice (5-10 items) to keep proof practical and repeatable. -- Require machine-readable evidence output and traceability matrix exports. -- Couple proof completion to wave exit criteria. +- Use a bounded PR or demo repository slice to keep proof practical and repeatable. +- Require machine-readable evidence output and rerun comparison artifacts. +- Couple proof completion to the validation-positioning wave exit criteria. ## Risks / Trade-offs -- [Proof too narrow] -> Mitigation: include multiple item types and at least one exception/governance case. -- [Proof too expensive] -> Mitigation: optimize for deterministic CI runs and reusable fixtures. +- [Proof too narrow] -> Mitigation: include at least one AI-bloat finding, one + remediation packet, and one evidence improvement. +- [Proof too expensive] -> Mitigation: optimize for deterministic CI runs and + reusable fixtures. ## Migration Plan -1. Select dogfooding slice and map initial requirements. +1. Select dogfooding slice and capture baseline evidence. 2. Implement tests and fail-first evidence. -3. Produce end-to-end evidence artifacts and docs updates. +3. Produce validation-loop artifacts and docs updates. ## Open Questions -- Which backlog slice should be canonical for long-term regression proof. +- Which repository slice should be canonical for long-term regression proof. diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md index 0a8a013c..54b42e1d 100644 --- a/openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md @@ -1,24 +1,34 @@ -# Change: Dogfooding E2E Proof for Full-Chain Traceability +# Change: Dogfooding Proof for AI-Bloat Defense and Validation ## Why -To claim SpecFact CLI as the end-to-end "swiss knife" for agile DevOps teams, the tool must prove its own flow with real artifacts. This change establishes a dedicated dogfooding implementation and evidence path from requirements through architecture, specs, code, tests, and CI evidence output. +SpecFact's flagship claim is no longer that it owns the full planning chain. The +claim to prove is sharper: run deterministic validation on a real repo, emit +JSON evidence, identify AI-bloat and drift findings, hand remediation packets to +an AI IDE, rerun, and show improved evidence. ## What Changes -- **NEW**: Define a dogfooding scenario set using real SpecFact backlog items and requirements -- **NEW**: Require one complete end-to-end traceability run: - - backlog item -> requirement -> architecture artifact -> spec -> code/test references -> full-chain evidence JSON -- **EXTEND**: The dogfooding proof also runs clean-code review as a side-channel so the final evidence bundle demonstrates both traceability and clean-code compliance -- **NEW**: Define release-readiness proof criteria for end-to-end positioning claims -- **NEW**: Add CI/report outputs proving wave gate completion for E2E chain +- **NEW**: Define a dogfooding scenario set using real SpecFact PRs or a pinned + demo repository slice. +- **NEW**: Require one end-to-end validation loop: + - run `specfact code review` or equivalent validation command; + - persist JSON evidence; + - identify `ai_bloat`, drift, contract, or weak-test findings; + - hand remediation packets to an AI IDE or headless agent; + - rerun validation and compare evidence. +- **NEW**: Define release-readiness proof criteria for AI-bloat defense and + validation positioning claims. +- **NEW**: Add CI/report outputs proving the evidence loop rather than a + requirements-to-code lifecycle. ## Capabilities ### New Capabilities -- `dogfooding-full-chain-e2e`: End-to-end self-validation flow for SpecFact CLI that proves requirements-to-evidence traceability in a real project slice. -- `dogfooding-full-chain-e2e`: Extended to include clean-code review evidence in the final proof bundle +- `dogfooding-validation-ai-bloat-proof`: Self-validation flow that proves + evidence generation, AI-bloat remediation, rerun comparison, and improved + validation evidence on a real project slice. ### Modified Capabilities diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md index b5f83a44..a3f0c947 100644 --- a/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md @@ -1,22 +1,21 @@ # Tasks: dogfooding-01-full-chain-e2e-proof -## 1. Branch and dataset setup +## 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.2 Select and document the canonical backlog slice for proof. -- [ ] 1.3 Map slice items to requirements and traceability IDs. +- [ ] 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. ## 2. Test-first and failing evidence -- [ ] 2.1 Add integration tests covering backlog->requirements->architecture->validation flow. +- [ ] 2.1 Add integration tests covering review -> evidence -> remediation packet -> rerun comparison. - [ ] 2.2 Run tests expecting initial failure and capture in `TDD_EVIDENCE.md`. -- [ ] 2.3 Add validation checks for evidence schema and traceability completeness. +- [ ] 2.3 Add validation checks for evidence schema, AI-bloat findings, remediation packet references, and rerun deltas. ## 3. Implementation and verification -- [ ] 3.1 Implement minimal changes required for full-chain proof generation. -- [ ] 3.2 Generate evidence outputs and traceability matrix artifacts. -- [ ] 3.2.1 Extend the proof run to collect clean-code review output alongside the full-chain evidence bundle. +- [ ] 3.1 Implement the minimal proof harness required to run the AI-bloat defense loop. +- [ ] 3.2 Generate JSON evidence, cleanup forecasts, remediation packets, and rerun comparison artifacts. - [ ] 3.3 Re-run tests and quality gates until all proof scenarios pass. ## 4. Delivery diff --git a/openspec/changes/governance-01-evidence-output/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md index 89c2dd87..9880cc0b 100644 --- a/openspec/changes/governance-01-evidence-output/proposal.md +++ b/openspec/changes/governance-01-evidence-output/proposal.md @@ -2,7 +2,12 @@ ## Why -Enterprise environments require machine-readable evidence that policies were enforced, traceability exists, and exceptions are tracked. Current validation output is human-readable (Markdown/terminal) but not suitable for CI gates, audit systems, or compliance dashboards. A standardized evidence JSON output format — covering policy results, traceability coverage, exception status, and timestamps — makes SpecFact validation results consumable by any CI/CD pipeline, audit tool, or governance platform. +Teams need machine-readable evidence that validation ran, policies were +enforced, AI-bloat and drift findings were classified, and exceptions were +tracked. Current validation output is human-readable (Markdown/terminal) but not +suitable for CI gates, AI IDE remediation loops, audit systems, or compliance +dashboards. A standardized evidence JSON output format makes SpecFact +validation results consumable by any deterministic gate or agent handoff. ## Ownership Alignment (2026-04-08) @@ -24,9 +29,9 @@ Enterprise environments require machine-readable evidence that policies were enf "profile": "enterprise", "policy_mode": "hard", "validation_results": { - "full_chain": { "pass": 67, "fail": 2, "advisory": 5 }, - "layers": { ... }, - "orphans": { ... } + "evidence_graph": { "pass": 67, "fail": 2, "advisory": 5 }, + "orphans": { ... }, + "drift": { ... } }, "code_quality": { "clean_code_score": 95, @@ -34,10 +39,9 @@ Enterprise environments require machine-readable evidence that policies were enf "verdict": "PASS_WITH_ADVISORY" }, "coverage": { - "req_to_arch": "92%", - "arch_to_spec": "100%", - "spec_to_code": "100%", - "code_to_test": "87%" + "contracts": "100%", + "tests": "87%", + "review_findings_resolved": "64%" }, "exceptions": [ { "id": "EXC-001", "policy": "...", "expires": "2026-12-31", "status": "active" } @@ -47,12 +51,12 @@ Enterprise environments require machine-readable evidence that policies were enf } ``` -- **NEW**: `--evidence-dir .specfact/evidence/` flag on `specfact validate --full-chain` to persist evidence artifacts per run +- **NEW**: `--evidence-dir .specfact/evidence/` flag on validation and code-review runs to persist evidence artifacts per run - **NEW**: `--ci-mode` flag that sets exit codes based on profile enforcement mode: advisory=always 0, mixed=1 for hard-fail rules only, hard=1 for any failure - **NEW**: Evidence artifact naming: `{timestamp}_{run_id}_evidence.json` for audit trail - **NEW**: Evidence summary on terminal: human-readable table alongside JSON output -- **EXTEND**: Full-chain validation (validation-02) extended to produce evidence artifacts -- **EXTEND**: Full-chain validation can append `code_quality` as a parallel section when the run includes review-based clean-code checks +- **EXTEND**: Validation evidence graph (validation-02) extended to produce evidence artifacts +- **EXTEND**: Validation evidence can append `code_quality` as a parallel section when the run includes review-based clean-code checks - **EXTEND**: Policy engine results formatted as evidence-compatible structures - **NEW**: Ownership authority — this change is authoritative for evidence JSON envelope/schema; sibling governance changes may add fields only through this envelope contract. @@ -64,7 +68,7 @@ Enterprise environments require machine-readable evidence that policies were enf ### Modified Capabilities -- `full-chain-validation`: Extended with evidence artifact generation via `--evidence-dir` and `--ci-mode` flags +- `validation-evidence-graph`: Extended with evidence artifact generation via `--evidence-dir` and `--ci-mode` flags - `policy-engine`: Results formatted as evidence-compatible structures with run_id and timestamps - `governance-evidence-output`: Extended with a `code_quality` section that remains parallel to `validation_results` rather than introducing a new traceability layer diff --git a/openspec/changes/openspec-01-intent-trace/proposal.md b/openspec/changes/openspec-01-intent-trace/proposal.md index 790d7c3e..05f5190e 100644 --- a/openspec/changes/openspec-01-intent-trace/proposal.md +++ b/openspec/changes/openspec-01-intent-trace/proposal.md @@ -1,48 +1,59 @@ -# Change: OpenSpec Intent Trace — Bridge Adapter Integration +# Change: OpenSpec and Spec Kit Evidence Adapter ## Why -OpenSpec proposals are plain Markdown with no structured business-intent metadata. When SpecFact imports a proposal via `specfact sync bridge --adapter openspec`, it has no machine-readable context about the business outcomes, business rules, or architectural constraints the change is supposed to satisfy — it only sees tasks and specs. This means the traceability chain starts at the spec level, missing the upstream intent layer entirely. Adding a structured `## Intent Trace` section to OpenSpec proposals (with JSON Schema validation) gives SpecFact the data it needs to construct the full outcome → rule → constraint → spec → code chain automatically on import. +OpenSpec and Spec Kit already own large parts of upstream specification and +planning. SpecFact should consume their artifacts as validation inputs rather +than define a mandatory upstream intent schema that those projects must adopt. -## Ownership Alignment (2026-04-08) +This change reframes intent trace as an optional adapter convention: when +structured context exists, SpecFact imports it; when it does not, SpecFact still +validates code, contracts, tests, and artifact drift with source-attributed +evidence. + +## Ownership Alignment (2026-06-06) - Repository assignment: `split/rescope` -- Core-owned scope retained here: the OpenSpec proposal schema, `tasks.md` metadata fields, and validation behavior for `## Intent Trace`. -- Bundle-owned follow-up required: the runtime import behavior referenced below (`sync bridge --import-intent`) belongs with the canonical project-bundle sync/import owner rather than `specfact-cli` core. -- Target modules-repo follow-up issue: [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) in `nold-ai/specfact-cli-modules` -- Implementation MUST separate schema/validation work from bundle runtime import work before coding resumes. +- Core-owned scope retained here: optional adapter schema, source attribution, + task/reference parsing, and validation behavior when context is present. +- Bundle-owned follow-up required: runtime import behavior belongs to the + canonical project-bundle sync/import owner. +- Target modules-repo follow-up issue: [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) +- Implementation MUST NOT require OpenSpec or Spec Kit to change their native + authoring model. ## What Changes -- **NEW**: `## Intent Trace` section schema for OpenSpec `proposal.md` files: - - YAML-fenced block under `## Intent Trace` with `intent_trace` root key - - Fields: `business_outcomes` (id, description, persona), `business_rules` (id, outcome_ref, given, when, then), `architectural_constraints` (id, outcome_ref, constraint), `requirement_refs` (list of REQ-NNN strings) - - JSON Schema at `openspec/schemas/intent-trace.schema.json` for validation -- **NEW**: `requirement_refs` optional field on individual tasks in `tasks.md` — links a task to specific `BusinessRule` IDs or `ArchitecturalConstraint` IDs -- **NEW**: `evidence` optional field on archived changes — points to evidence JSON envelope file(s) generated during implementation; creates immutable proposal → intent trace → implementation → evidence → archive chain -- **NEW**: `specfact sync bridge --adapter openspec --import-intent` — reads `## Intent Trace` section from imported proposals and populates `.specfact/requirements/` with `BusinessOutcome` and `BusinessRule` artifacts automatically -- **EXTEND**: `specfact sync bridge --adapter openspec` — when `## Intent Trace` section is present, include intent context in the imported project bundle; backwards-compatible (section is optional) -- **EXTEND**: `openspec validate <change-id> --strict` — validates `## Intent Trace` section against `intent-trace.schema.json` when present +- **NEW**: Optional adapter metadata convention for OpenSpec proposals and Spec + Kit feature folders. +- **NEW**: Source-attributed import of outcomes, requirement references, tasks, + spec deltas, acceptance checks, and evidence links when present. +- **NEW**: Strict validation of adapter metadata only when the optional metadata + is present. +- **NEW**: Evidence pointers on archived changes MAY reference validation JSON + produced during implementation. +- **EXTEND**: Bridge/import flows can map upstream artifacts into the + requirements input model and evidence graph without creating duplicate + planning artifacts. ## Capabilities ### New Capabilities -- `openspec-intent-trace-schema`: JSON Schema definition and validation for the `## Intent Trace` section in OpenSpec proposals — enabling machine-readable business-outcome traceability in change proposals. -- `openspec-bridge-intent-import`: Extended SpecFact OpenSpec bridge adapter that reads, validates, and imports `## Intent Trace` sections from proposals into `.specfact/requirements/` artifacts automatically. +- `openspec-speckit-evidence-adapter`: Optional source-attributed adapter for + OpenSpec and Spec Kit artifacts consumed by SpecFact validation. ### Modified Capabilities -- `openspec-bridge-adapter`: Extended to parse optional `## Intent Trace` section on proposal import; backwards-compatible when section is absent. +- `openspec-bridge-adapter`: Extended to parse optional metadata and evidence + links without requiring them. ## Impact -- New file: `openspec/schemas/intent-trace.schema.json` -- Existing bridge adapter: `src/specfact_cli/adapters/` OpenSpec adapter extended with intent-trace parsing -- CLI change: `specfact sync bridge --adapter openspec` — new optional `--import-intent` flag; no breaking change to existing workflows -- Depends on: `requirements-01-data-model` (#238) — `BusinessOutcome` and `BusinessRule` schemas must exist to populate; `requirements-02-module-commands` (#239) — `specfact requirements capture` used for artifact creation -- Wave: aligns with Wave 5/6 (after requirements-01/02 land) -- Docs: new `docs/guides/openspec-journey.md` section on Intent Trace; update `docs/adapters/` for OpenSpec adapter +- OpenSpec and Spec Kit are documented as upstream inputs. +- Existing OpenSpec proposals remain valid when no adapter metadata exists. +- Depends on `requirements-01-data-model` and `requirements-02-module-commands` + only for normalized evidence import. --- @@ -52,6 +63,6 @@ OpenSpec proposals are plain Markdown with no structured business-intent metadat - **GitHub Issue**: #350 - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/350> - **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#168 -- **Paired Modules Scope**: OpenSpec intent import runtime +- **Paired Modules Scope**: OpenSpec and Spec Kit evidence import runtime - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/profile-01-config-layering/proposal.md b/openspec/changes/profile-01-config-layering/proposal.md index 435acd41..03d17ac7 100644 --- a/openspec/changes/profile-01-config-layering/proposal.md +++ b/openspec/changes/profile-01-config-layering/proposal.md @@ -1,111 +1,48 @@ -# Change: Profile & Config Layering System +# Change: Profile and Validation Config Layering ## Why -SpecFact treats every user the same — a solo developer and an enterprise architecture board get identical defaults, enforcement levels, and module activation. This blocks adoption at both ends: solos drown in ceremony they don't need, enterprises can't enforce baselines across hundreds of repos. A profile-driven initialization that deterministically selects modules, templates, policies, and enforcement modes makes SpecFact scale from single-developer projects to regulated enterprise environments without configuration sprawl. +SpecFact needs adoption modes that tune validation strictness without changing +the evidence contract. A solo developer should get fast local feedback, while a +regulated team can hard-fail CI and require exception evidence. Profiles should +therefore configure severity, policy mode, module activation, and local/org +layering around validation. -## Ownership Alignment (2026-04-08) +## Ownership Alignment (2026-06-06) - Repository assignment: stays in `specfact-cli` core. -- Canonical owner: core `init` and core config resolution, not a standalone extracted `profile` module. -- The `modules/profile/...` package structure below is stale relative to the lean-core architecture and MUST NOT be used as an implementation target. -- Required rescope: express this change through `specfact init --profile`, shared profile/config models, and core-owned config layering behavior. - -## Module Package Structure - -``` -modules/profile/ - module-package.yaml # name: profile; commands: profile init, profile show, profile diff - src/profile/ - __init__.py - main.py # typer.Typer app — profile command group - engine/ - resolver.py # Config layering: profile defaults → org baseline → repo overlay → dev local - divergence.py # Detect and warn when local deviates from org baseline - models/ - profile_config.py # ProfileConfig Pydantic model (tier, modules, policy_mode, fields) - profiles/ - solo.yaml # Minimal modules, advisory mode, 3 required fields - startup.yaml # Team modules (+ sync, ceremonies), advisory → mixed - mid_size.yaml # Org modules (+ policy, architecture), mixed mode - enterprise.yaml # Full modules (+ marketplace, audit), hard mode - commands/ - init_profile.py # specfact init --profile solo|startup|mid-size|enterprise - show_profile.py # specfact profile show (resolved config with source annotations) - diff_profile.py # specfact profile diff (local vs org baseline divergence) -``` - -**`module-package.yaml` declares:** - -- `name: profile` -- `version: 0.1.0` -- `commands: [profile init, profile show, profile diff]` -- `dependencies: []` (no module deps; foundational) -- `publisher:` + `integrity:` — arch-06 marketplace readiness - -## Module Package Structure - -``` -modules/profile/ - module-package.yaml # name: profile; commands: profile init, profile show, profile diff - src/profile/ - __init__.py - main.py # typer.Typer app — profile command group - engine/ - resolver.py # Config layering: profile defaults → org baseline → repo overlay → dev local - divergence.py # Detect and warn when local deviates from org baseline - models/ - profile_config.py # ProfileConfig Pydantic model (tier, modules, policy_mode, fields) - profiles/ - solo.yaml # Minimal modules, advisory mode, 3 required fields - startup.yaml # Team modules (+ sync, ceremonies), advisory → mixed - mid_size.yaml # Org modules (+ policy, architecture), mixed mode - enterprise.yaml # Full modules (+ marketplace, audit), hard mode - commands/ - init_profile.py # specfact init --profile solo|startup|mid-size|enterprise - show_profile.py # specfact profile show (resolved config with source annotations) - diff_profile.py # specfact profile diff (local vs org baseline divergence) -``` - -**`module-package.yaml` declares:** - -- `name: profile` -- `version: 0.1.0` -- `commands: [profile init, profile show, profile diff]` -- `dependencies: []` (no module deps; foundational) -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Canonical owner: core `init`, core config resolution, and validation severity + defaults. +- The legacy `modules/profile/...` package structure is stale and MUST NOT be + used as an implementation target. +- Implementation MUST keep profiles focused on validation rollout and evidence + strictness, not broad ceremony enablement. ## What Changes -- **NEW**: Profile module in `modules/profile/` with config layering engine: profile defaults → org baseline (read-only) → repo overlay → developer local. Highest priority last. -- **NEW**: Four built-in profiles shipped as YAML (`solo.yaml`, `startup.yaml`, `mid_size.yaml`, `enterprise.yaml`) defining: enabled modules, policy enforcement mode, required requirements fields, config sources, and enforcement location. -- **EXTEND**: Tier profiles also define the default clean-code pack mode inherited by `specfact/clean-code-principles`: `solo -> advisory`, `startup -> advisory then mixed`, `mid_size -> mixed`, `enterprise -> hard`. -- **NEW**: Config file `.specfact/profile.yaml` (or extend existing `.specfact/config.yaml`) storing selected profile, config source URIs, and local overlays. -- **NEW**: `specfact init --profile <tier>` generates profile-appropriate config and activates tier-relevant modules. -- **NEW**: `specfact profile show` displays the fully resolved config with annotations showing which layer each value came from. -- **NEW**: `specfact profile diff` detects and warns when local config deviates from the org baseline. -- **EXTEND**: `specfact init` extended with `--profile` flag; existing init behavior preserved as implicit `solo` profile when no flag is passed. - -### Profile Behavior Matrix - -| Capability | Solo | Startup | Mid-size | Enterprise | -|---|---|---|---|---| -| Modules enabled | minimal (backlog, validate, requirements-light) | team (+ sync, ceremonies) | org (+ policy, architecture) | full (+ marketplace, audit) | -| Policy mode | advisory | advisory → mixed | mixed | hard (with exceptions) | -| Requirements fields | As_a/I_want/So_that only | + Business_outcome, Business_rules | Org-defined schema | Regulated + domain overlays | -| Config sources | local only | local + optional org | org baseline + local overlay | org baseline (read-only) + BU overlays | -| Enforcement location | local warnings only | local + CI advisory | CI mixed (some hard) | CI hard-fail + evidence | +- **NEW**: Deterministic config layering: profile defaults -> org baseline -> repo + overlay -> developer local. +- **NEW**: Built-in profile defaults for validation severity, policy mode, + evidence persistence, clean-code enforcement mode, and module activation. +- **NEW**: `specfact init --profile <tier>` configures the validation posture for + the project. +- **NEW**: Resolved-config display with source annotations. +- **NEW**: Divergence warnings when local overrides weaken org validation policy. +- **EXTEND**: Existing init behavior remains the implicit solo profile when no + profile is specified. ## Capabilities ### New Capabilities -- `profile-config-layering`: Profile-driven config resolution with deterministic layering (profile defaults → org baseline → repo overlay → dev local), divergence detection, and tier-aware module/policy activation. -- `profile-config-layering`: Extended so clean-code enforcement defaults are derived from the selected tier instead of a parallel clean-code profile concept. +- `profile-validation-config-layering`: Profile-driven config resolution for + validation severity, evidence behavior, policy mode, clean-code defaults, and + module activation. ### Modified Capabilities -- `init-module-state`: Extended with `--profile` flag for tier-aware initialization; default behavior preserved as implicit `solo` profile. +- `init-module-state`: Extended with profile-aware initialization while + preserving the existing default. --- diff --git a/openspec/changes/requirements-01-data-model/proposal.md b/openspec/changes/requirements-01-data-model/proposal.md index c2c66ac9..2fe5ac4a 100644 --- a/openspec/changes/requirements-01-data-model/proposal.md +++ b/openspec/changes/requirements-01-data-model/proposal.md @@ -1,31 +1,44 @@ -# Change: Requirements Data Model & Storage +# Change: Requirements Evidence Input Model ## Why -Business requirements have no formal representation in SpecFact. They exist only as unstructured text in backlog items (acceptance criteria, descriptions). This means the most impactful validation gap — "are we building the right thing?" — cannot be programmatically checked. A Pydantic domain model for business requirements with versioned YAML storage under `.specfact/requirements/` gives requirements first-class status in the traceability chain, enabling all downstream validation (Req → Arch → Spec → Code → Tests). +SpecFact needs a normalized way to reference upstream requirement context during +validation. It does not need to become the primary requirement-authoring tool. +Spec Kit, OpenSpec, backlog systems, docs, and issue trackers remain the source +of planning intent; SpecFact stores the minimum local records needed to explain +validation evidence and drift. ## What Changes -- **NEW**: Pydantic domain models in `src/specfact_cli/models/requirements.py`: - - `BusinessOutcome` — success metrics and quantified business value - - `BusinessRule` — rule ID, name, Given/When/Then scenario, MoSCoW priority - - `ArchitecturalConstraint` — constraint type (performance/security/integration/compliance/ux), requirement, validation criteria - - `BusinessRequirement` — the top-level model: requirement ID, schema version, user story link, business outcome, business rules, architectural constraints, UX requirements - - `RequirementTrace` — traceability links: requirement ID → architecture refs, spec refs, code refs, test refs -- **NEW**: Storage convention: `.specfact/requirements/{requirement_id}.req.yaml` with human-readable YAML serialization -- **NEW**: Schema versioning: all requirement models carry `schema_version` field for forward-compatible migration -- **NEW**: Profile-aware field validation: required fields determined by active profile tier (solo = minimal 3 fields, enterprise = all fields + regulatory references) -- **EXTEND**: `ProjectBundle` extended with optional `requirements` field via arch-07 schema extension system (namespace: `requirements.business_requirements`) +- **NEW**: Pydantic models in `src/specfact_cli/models/requirements.py` for + normalized requirement inputs, business rules, constraints, source references, + and validation evidence links. +- **NEW**: Optional storage convention under `.specfact/requirements/` for + imported or normalized records used by validation runs. +- **NEW**: Schema versioning for forward-compatible adapters. +- **NEW**: Profile-aware completeness checks that affect validation severity, not + planning workflow ownership. +- **EXTEND**: `ProjectBundle` receives an optional requirements-input namespace + through the existing schema extension system. + +## Out of Scope + +- Interactive requirement authoring as a flagship workflow. +- Treating `.specfact/requirements/` as the system of record for product + management. +- Bidirectional backlog sync or ceremony automation. ## Capabilities ### New Capabilities -- `requirements-data-model`: Pydantic domain models for business requirements (BusinessOutcome, BusinessRule, ArchitecturalConstraint, BusinessRequirement, RequirementTrace) with versioned YAML storage and profile-aware field validation. +- `requirements-evidence-input-model`: Normalized requirement input records and + source references used by validation evidence and drift detection. ### Modified Capabilities -- `data-models`: ProjectBundle extended with requirements field via arch-07 schema extensions +- `data-models`: ProjectBundle extended with an optional requirements-input + namespace. --- @@ -36,4 +49,4 @@ Business requirements have no formal representation in SpecFact. They exist only - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/238> - **Last Synced Status**: proposed - **Sanitized**: false -<!-- content_hash: 1dad52a86e44c9f9 --> \ No newline at end of file +<!-- content_hash: 1dad52a86e44c9f9 --> diff --git a/openspec/changes/requirements-02-module-commands/proposal.md b/openspec/changes/requirements-02-module-commands/proposal.md index 4f84942a..7708079e 100644 --- a/openspec/changes/requirements-02-module-commands/proposal.md +++ b/openspec/changes/requirements-02-module-commands/proposal.md @@ -1,106 +1,50 @@ -# Change: Requirements Module — Extract, Author, Validate Commands +# Change: Requirements Import and Validation Commands ## Why -Even with a formal data model (requirements-01), there are no CLI commands for working with business requirements. Teams need to extract structured requirements from existing backlog items (reverse-engineer from AC text), author new requirements with profile-aware templates, and validate requirements completeness — all from the terminal. This module is the primary user-facing entry point for the upstream traceability chain. +SpecFact needs user-facing commands that can import, normalize, validate, and +inspect upstream requirement context for evidence. It should not position itself +as the authoring stack for requirements, since teams may already use Spec Kit, +OpenSpec, Jira, GitHub Issues, Azure DevOps, Linear, documents, or another +planning source. -## Ownership Alignment (2026-04-08) +## Ownership Alignment (2026-06-06) - Repository assignment: `split/rescope` -- Core-owned scope retained here: shared requirements contracts, schemas, and adapter/interface deltas needed by downstream owners. -- Bundle-owned follow-up required: the user-facing command surface proposed below cannot remain a flat `specfact requirements ...` family and cannot be implemented in `specfact-cli` core as described. -- Target modules-repo follow-up issue: [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) in `nold-ai/specfact-cli-modules` -- Implementation MUST NOT proceed from the legacy `modules/requirements/...` package structure below until a paired bundle-owned follow-up change defines the canonical grouped command home. - -## Module Package Structure - -``` -modules/requirements/ - module-package.yaml # name: requirements; commands: requirements extract, author, validate, list - src/requirements/ - __init__.py - main.py # typer.Typer app — requirements command group - engine/ - extractor.py # Parse AC text from backlog items → structured BusinessRequirement - author.py # Interactive + template-based requirement authoring - validator.py # Validate requirements completeness per profile schema - coverage.py # Compute requirement coverage (arch/spec/code/test links) - templates/ - story.yaml # User story template (As_a, I_want, So_that + business rules) - feature.yaml # Feature template (outcome, rules, constraints, UX) - spike.yaml # Spike template (hypothesis, success criteria) - commands/ - extract.py # specfact requirements extract --from-backlog <adapter> - author.py # specfact requirements author --template <type> - validate.py # specfact requirements validate - list.py # specfact requirements list --show-coverage -``` - -**`module-package.yaml` declares:** - -- `name: requirements` -- `version: 0.1.0` -- `commands: [requirements extract, requirements author, requirements validate, requirements list]` -- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness - -## Module Package Structure - -``` -modules/requirements/ - module-package.yaml # name: requirements; commands: requirements extract, author, validate, list - src/requirements/ - __init__.py - main.py # typer.Typer app — requirements command group - engine/ - extractor.py # Parse AC text from backlog items → structured BusinessRequirement - author.py # Interactive + template-based requirement authoring - validator.py # Validate requirements completeness per profile schema - coverage.py # Compute requirement coverage (arch/spec/code/test links) - templates/ - story.yaml # User story template (As_a, I_want, So_that + business rules) - feature.yaml # Feature template (outcome, rules, constraints, UX) - spike.yaml # Spike template (hypothesis, success criteria) - commands/ - extract.py # specfact requirements extract --from-backlog <adapter> - author.py # specfact requirements author --template <type> - validate.py # specfact requirements validate - list.py # specfact requirements list --show-coverage -``` - -**`module-package.yaml` declares:** - -- `name: requirements` -- `version: 0.1.0` -- `commands: [requirements extract, requirements author, requirements validate, requirements list]` -- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Core-owned scope retained here: shared requirements input contracts, schemas, + adapter semantics, and validation result boundaries. +- Bundle-owned follow-up required: runtime commands belong to the canonical + grouped module command model. +- Target modules-repo follow-up issue: [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) +- Implementation MUST NOT ship requirement authoring as the critical path. ## What Changes -- **NEW**: Requirements module in `modules/requirements/` implementing `ModuleIOContract`: - - `import_to_bundle`: Extract requirements from backlog items into ProjectBundle - - `export_from_bundle`: Generate requirements documents (YAML, Markdown) from bundle - - `sync_with_bundle`: Bidirectional sync between requirements and backlog (read-only in v1) - - `validate_bundle`: Check requirements completeness per profile schema -- **NEW**: `specfact requirements extract --from-backlog <adapter> --project <org/repo>` — parse acceptance criteria from existing backlog items, infer business rules, generate `.specfact/requirements/*.req.yaml` files -- **NEW**: `specfact requirements author --template story|feature|spike --story STORY-123` — interactive requirement authoring with profile-aware templates (solo gets 3 fields, enterprise gets full schema) -- **NEW**: `specfact requirements validate --requirements-dir .specfact/requirements/` — validate completeness against active profile's required fields -- **NEW**: `specfact requirements list --show-coverage` — list requirements with traceability coverage status (architecture %, spec %, code %, test %) -- **NEW**: Profile-aware templates: solo requires only As_a/I_want/So_that; startup adds Business_outcome + Business_rules; mid-size uses org-defined schema; enterprise adds Regulatory_reference + Risk_owner +- **NEW**: Import and normalization contract for upstream requirement-like + sources, including backlog items, OpenSpec proposals, Spec Kit feature + folders, and local markdown/YAML records. +- **NEW**: Validation command behavior that checks completeness, source + freshness, and evidence usefulness by profile. +- **NEW**: Coverage inspection over normalized inputs, architecture boundaries, + contracts, code, tests, and review findings. +- **NEW**: Adapter hooks that return bounded, source-attributed records rather + than free-form planning prose. +- **REMOVED FROM CRITICAL PATH**: Interactive authoring templates and broad + requirement lifecycle management. ## Capabilities ### New Capabilities -- `requirements-module`: CLI commands for extracting requirements from backlog items, authoring with profile-aware templates, validating completeness per profile schema, and listing with traceability coverage status. Implements ModuleIOContract for requirements lifecycle. +- `requirements-validation-commands`: Commands for importing, normalizing, + validating, and inspecting upstream requirement context as validation evidence. ### Modified Capabilities -- `module-io-contract`: New implementation of ModuleIOContract for the requirements domain (import from backlog, export to YAML/Markdown, sync, validate) -- `backlog-adapter`: Extended with requirement extraction hooks — adapters provide raw AC text, extractor parses into structured BusinessRequirement models +- `module-io-contract`: Requirements implementations expose import, + normalization, and validation hooks for evidence, not full lifecycle sync. +- `backlog-adapter`: Backlog adapters can provide source-attributed requirement + snippets for validation. --- diff --git a/openspec/changes/requirements-03-backlog-sync/proposal.md b/openspec/changes/requirements-03-backlog-sync/proposal.md index 59062bf8..d506faf6 100644 --- a/openspec/changes/requirements-03-backlog-sync/proposal.md +++ b/openspec/changes/requirements-03-backlog-sync/proposal.md @@ -1,38 +1,46 @@ -# Change: Requirements ↔ Backlog Bidirectional Sync +# Change: Backlog Requirement Drift Evidence ## Why -When backlog items change, requirements aren't updated. When requirements change, backlog items aren't updated. The two drift apart silently, creating a traceability gap that grows with every sprint. Teams discover the drift only during audits or after building the wrong thing. A bidirectional sync between backlog items and `.specfact/requirements/` using the sync kernel makes requirements and backlog items a single source of truth — with drift detection as the safety net. +Backlog items and local validation inputs often drift apart. The useful product +value for SpecFact is to detect and explain that drift before code merges, not +to become the bidirectional source-of-truth sync layer for product management. -## Ownership Alignment (2026-04-08) +## Ownership Alignment (2026-06-06) - Repository assignment: `split/rescope` -- Core-owned scope retained here: shared sync contracts, adapter semantics, and spec-kit duplicate-creation safeguards. -- Bundle-owned follow-up required: the user-facing requirements/backlog sync workflow below spans project and backlog bundle behavior and cannot remain a flat `specfact requirements ...` command family in core. -- Target modules-repo follow-up issue: [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) in `nold-ai/specfact-cli-modules` -- Implementation MUST NOT proceed from this proposal as a single-repo change until the bundle-owned follow-up changes are split out explicitly. +- Core-owned scope retained here: drift evidence contracts, adapter semantics, + conflict classification, and duplicate-creation safeguards. +- Bundle-owned follow-up required: runtime import/drift commands belong to the + canonical project/backlog module surfaces. +- Target modules-repo follow-up issue: [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) +- Implementation MUST NOT depend on backlog write-back for validation value. ## What Changes -- **NEW**: `specfact requirements sync --from-backlog <adapter> --project <org/repo> --preview` — pull structured requirements from backlog AC text, update `.specfact/requirements/` -- **NEW**: `specfact requirements sync --to-backlog <adapter> --project <org/repo> --preview` — push requirement-derived fields back to backlog items (missing AC, business value gaps, architectural constraints) -- **NEW**: `specfact requirements drift --from-backlog <adapter> --project <org/repo>` — detect divergence between local requirements and backlog items without making changes -- **NEW**: Sync operations use the sync kernel (sync-01) for session management, conflict detection, and patch preview -- **NEW**: Backlog adapter extension: adapters provide `extract_requirements_fields()` and `update_requirements_fields()` methods for bidirectional sync -- **EXTEND**: Requirements module (requirements-02) extended with sync commands -- **DESIGN DECISION**: v1 starts with pull-first (backlog → requirements) as primary direction; push (requirements → backlog) is preview-only and requires explicit `--write` confirmation via patch-mode -- **EXTEND**: Spec-Kit backlog extension awareness — before creating issues during push (requirements → backlog), the sync SHALL query `ToolCapabilities.extension_commands` (from speckit-02) to detect active spec-kit backlog extensions (Jira, ADO, Linear, GitHub Projects, Trello). When a spec-kit backlog extension is active, the sync SHALL scan spec-kit feature `tasks.md` files for existing issue references (e.g., `PROJ-123`, `AB#456`) and import them as pre-existing mappings. Issue creation is skipped for tasks that already have spec-kit extension mappings, preventing duplicate issues. This detection is implemented in `speckit-03-change-proposal-bridge` (specfact-cli-modules) and consumed here via the adapter interface. +- **NEW**: Read-first backlog import and drift detection contract. +- **NEW**: Evidence categories for missing acceptance criteria, stale local + records, changed issue status, missing source links, and ambiguous mappings. +- **NEW**: Preview-only write-back MAY exist as a later adapter feature, but it + remains outside the validation critical path and requires explicit write + confirmation. +- **EXTEND**: Backlog adapters provide source-attributed requirement fields for + validation. +- **EXTEND**: Spec Kit backlog extension awareness prevents duplicate issue + creation when imported upstream artifacts already contain tracker mappings. ## Capabilities ### New Capabilities -- `requirements-backlog-sync`: Bidirectional sync between `.specfact/requirements/` and backlog items (GitHub, ADO, Jira, Linear) via sync kernel. Includes pull (extract from backlog), push (update backlog), and drift detection. +- `backlog-requirement-drift-evidence`: Read-first detection of drift between + backlog items and normalized validation inputs. ### Modified Capabilities -- `backlog-adapter`: Extended with requirements field extraction and update methods for bidirectional sync; extended with spec-kit backlog extension issue mapping import -- `requirements-module`: Extended with sync and drift commands; extended with spec-kit duplicate issue prevention +- `backlog-adapter`: Extended with source-attributed requirement field import and + drift classification hooks. +- `requirements-validation-commands`: Extended with backlog drift evidence. --- @@ -42,6 +50,6 @@ When backlog items change, requirements aren't updated. When requirements change - **GitHub Issue**: #244 - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/244> - **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#166 -- **Paired Modules Scope**: requirements-backlog sync runtime +- **Paired Modules Scope**: requirements-backlog drift runtime - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/telemetry-01-opentelemetry-default-on/design.md b/openspec/changes/telemetry-01-opentelemetry-default-on/design.md index b0eba4a3..c80c2048 100644 --- a/openspec/changes/telemetry-01-opentelemetry-default-on/design.md +++ b/openspec/changes/telemetry-01-opentelemetry-default-on/design.md @@ -1,5 +1,8 @@ # Design: telemetry-01-opentelemetry-default-on +This folder name is historical. The retained scope is opt-in validation outcome +telemetry only. + ## Architecture ```text @@ -54,8 +57,9 @@ If the user accepts, the current command MAY emit exactly one summary event afte validation passes. If the user declines, the current command remains silent. The prompt SHALL be short, neutral, and explicit: -- What is tracked: five required semantic fields (`command`, `modules_composed`, `duration_ms`, `exit_code`, `outcome`), - optional bounded `subcommand`, `schema_version`, `run_id`, `timestamp`, major/minor Python version, and coarse platform. +- What is tracked: bounded validation outcome fields (`command_family`, `validation_surface`, `modules_composed`, + `duration_ms`, `exit_code`, `outcome`, `failure_class`), `schema_version`, `run_id`, `timestamp`, major/minor Python + version, and coarse platform. - What is not tracked: file paths, repository names, branch names, remotes, prompts, chat transcripts, OpenSpec/spec content, usernames, emails, hostnames, free-form logs, and raw error messages. - How to change it: `specfact telemetry enable`, `specfact telemetry disable`, `specfact telemetry status`, and @@ -69,7 +73,8 @@ source. Permitted fields only. Required semantic fields: -- `command` (enum: validated against registered command names) +- `command_family` (enum: validated against registered command families) +- `validation_surface` (enum: code_review, spec_validation, contract_validation, governance, other) - `modules_composed` (list[str], bundle names) - `duration_ms` (int) - `exit_code` (int) @@ -77,7 +82,7 @@ Permitted fields only. Required semantic fields: Optional bounded semantic field: -- `subcommand` (enum, optional) +- `failure_class` (enum, optional) Required bounded metadata: diff --git a/openspec/changes/telemetry-01-opentelemetry-default-on/proposal.md b/openspec/changes/telemetry-01-opentelemetry-default-on/proposal.md index 95ab8f3b..14bafd49 100644 --- a/openspec/changes/telemetry-01-opentelemetry-default-on/proposal.md +++ b/openspec/changes/telemetry-01-opentelemetry-default-on/proposal.md @@ -1,51 +1,54 @@ -# Change: OpenTelemetry Active Opt-In with PII-Safe Payload +# Change: Opt-In Validation Outcome Telemetry ## Why -SpecFact needs honest usage signal to improve the platform, but the first public telemetry release must earn developer trust before collecting anything. Default-on telemetry would create avoidable community backlash even with a PII-safe payload because developers reasonably expect explicit consent for CLI usage reporting. This change therefore reverts the default-on posture and ships an active opt-in flow during `specfact init` or the first interactive run, with a concise disclosure of what is tracked, what is never tracked, and how to change the setting later. +SpecFact needs honest usage signal only if it earns trust first. Telemetry must +remain opt-in and should measure validation outcomes, not product-management +workflow analytics. The useful questions are whether validation ran, which +bounded module categories participated, how long it took, and what verdict was +returned. ## What Changes -- **NEW**: OpenTelemetry emitter available for CLI invocations only after explicit user consent, emitting a PII-safe payload with five required semantic fields (`command`, `modules_composed`, `duration_ms`, `exit_code`, `outcome`) plus optional bounded `subcommand`. -- **NEW**: Active opt-in consent prompt during `specfact init` or the first interactive `specfact` run. Non-interactive, CI, and unattended first runs default to disabled until `specfact telemetry enable` or `SPECFACT_TELEMETRY=true` is provided. -- **NEW**: Telemetry disclosure copy shown before consent and available from `specfact telemetry status`, clearly stating the tracked fields and rejected categories. -- **NEW**: Allowlisted payload contract — the five required **semantic** telemetry fields are **`command`**, **`modules_composed`** (bundle/module names), **`duration_ms`**, **`exit_code`**, and **`outcome`** (enum), plus optional bounded **`subcommand`**, mapped onto the versioned schema in `specs/telemetry-otel/spec.md` (additional bounded metadata such as `schema_version`, `run_id`, and coarse platform facts remain allowlisted there). Rejections are **per disallowed category** at the emitter boundary: - - **File paths** — any filesystem path or repo-relative path is rejected. - - **Repo names / branches** — repository identifiers, default-branch names, or remote URLs are rejected. - - **Prompt content** — user prompts, system prompts, or chat transcripts are rejected. - - **Spec content** — OpenSpec bodies, markdown specs, or large free-text blobs are rejected. - - **Free-form strings** — unconstrained error text, log lines, or narrative strings are rejected (bounded error **class** only). -- **NEW**: `specfact telemetry [enable|disable|status]` command surface plus `SPECFACT_TELEMETRY=true|false` environment variable for CI-friendly per-process overrides. -- **NEW**: Enterprise-mode default: when `.specfact/enterprise.yaml` (or equivalent marker) is detected, telemetry defaults to `off` unless a signed `org-admin` policy opts in. -- **NEW**: Local audit log at `.specfact/telemetry/sent.log` (append-only) recording the exact redacted payload transmitted for each invocation, so users can verify contents. -- **EXTEND**: `specfact --version` surface prints current telemetry status. -- **DOCUMENT**: Criteria for revisiting default-on later: published telemetry transparency docs, stable allowlist tests, local audit log adoption, explicit enterprise policy controls, and evidence that the community accepts the opt-in payload contract without privacy complaints. +- **NEW**: OpenTelemetry emitter available for CLI invocations only after + explicit user consent. +- **NEW**: PII-safe payload focused on validation outcomes: + `command_family`, `validation_surface`, `modules_composed`, `duration_ms`, + `exit_code`, `outcome`, and bounded `failure_class`. +- **NEW**: Active opt-in consent prompt during `specfact init` or first + interactive run. Non-interactive, CI, and unattended first runs default to + disabled until `specfact telemetry enable` or `SPECFACT_TELEMETRY=true`. +- **NEW**: Telemetry disclosure copy available from `specfact telemetry status`. +- **NEW**: Allowlist enforcement rejects file paths, repo names, branch names, + prompts, spec contents, free-form error text, and planning artifact bodies. +- **NEW**: Enterprise-mode default remains off unless a signed org-admin policy + opts in. +- **NEW**: Local audit log at `.specfact/telemetry/sent.log` records the exact + redacted payload transmitted for each invocation. +- **DOCUMENT**: Criteria for ever revisiting default-on: published transparency + docs, stable allowlist tests, local audit adoption, explicit enterprise + policy controls, and no unresolved privacy complaints. ## Capabilities -### New Capability: `telemetry-otel` +### New Capability -Emitter, payload contract, active opt-in commands, enterprise default, local audit log. +- `validation-outcome-telemetry`: Opt-in OpenTelemetry emitter for bounded + validation outcome metrics with local auditability and strict PII rejection. ## Migration Notes -- **Path change:** the canonical append-only audit log for transmitted telemetry moves to **`.specfact/telemetry/sent.log`** - (per-project). Operators and automation should update tail/grep/ship scripts to the new location. -- **Legacy file:** if `~/.specfact/telemetry.log` exists after upgrade, the CLI **detects** it on first run, emits a - **deprecation warning**, and (per `design.md`) follows the **dual-write** window so historical consumers keep working - while new consumers prefer the project-local path. Optional one-time **copy/merge** tooling MAY ship as a follow-up - command, but the contract only requires dual-append plus warning until the legacy file is removed. -- **Legacy overrides:** existing `SPECFACT_TELEMETRY_OPT_IN` and `.specfact/config.yaml` `telemetry.opt-in` settings are - honored during one deprecation series when `SPECFACT_TELEMETRY` and `telemetry.enabled` are unset. The CLI emits a - runtime deprecation warning when a legacy key is used, and emits a conflict warning when legacy and new keys disagree. - New keys take precedence over legacy keys. Release notes SHALL publish the cutoff before legacy override support is - removed. +- The canonical append-only audit log is `.specfact/telemetry/sent.log`. +- Legacy `~/.specfact/telemetry.log` consumers receive a deprecation warning + during any dual-write window. +- Existing legacy opt-in settings are honored for one deprecation series when + new keys are unset. ## Impact -- Downstream (finops-01, knowledge-01, distillation) can rely on a single telemetry surface when users opt in. -- Enterprise tier (enterprise-02 audit) reuses the same emitter path but routes to its own exporter. -- No runtime cost impact for air-gapped users: emitter is a no-op when no exporter is configured. +- Downstream analytics may consume validation outcome metrics only after opt-in. +- Enterprise environments remain off by default unless explicitly enabled. +- Air-gapped users pay no runtime cost when no exporter is configured. --- diff --git a/openspec/changes/traceability-01-index-and-orphans/proposal.md b/openspec/changes/traceability-01-index-and-orphans/proposal.md index a3dc8e32..a10b0efb 100644 --- a/openspec/changes/traceability-01-index-and-orphans/proposal.md +++ b/openspec/changes/traceability-01-index-and-orphans/proposal.md @@ -1,96 +1,45 @@ -# Change: Traceability Index & Orphan Detection +# Change: Artifact Evidence Index and Orphan Detection ## Why -As the number of requirements, specs, and code modules grows, manually tracking traceability becomes impossible. Teams need a fast, queryable index that maps every artifact to its upstream/downstream counterparts — and actively detects orphans (artifacts with broken or missing links). This index is the backbone for the full-chain validation, coverage dashboards, and ceremony enrichment. Without it, traceability is a write-once artifact that decays the moment someone adds a new endpoint without linking it. +Validation evidence decays when artifacts are added, renamed, or deleted without +their upstream and downstream references changing with them. Teams need a fast +index that can answer whether a code path, test, contract, backlog item, +OpenSpec change, Spec Kit feature, or ADR still has useful evidence around it. -## Ownership Alignment (2026-04-08) +This change keeps traceability as a validation capability. It is not a ceremony, +dashboard, or planning-authoring feature. -- Repository assignment: `split/rescope` -- Core-owned scope retained here: shared traceability index contracts and artifact linkage semantics. -- Bundle-owned follow-up required: the flat `specfact trace ...` command family and `modules/trace/...` package structure below are not canonical in the grouped command model. -- Target modules-repo follow-up issue: [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) in `nold-ai/specfact-cli-modules` -- Implementation MUST NOT proceed from the legacy package layout below until the bundle-owned query/reporting surface is defined separately. - -## Module Package Structure - -``` -modules/trace/ - module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix - src/trace/ - __init__.py - main.py # typer.Typer app — trace command group - engine/ - indexer.py # Build/rebuild traceability index from all layers - query.py # Query index by requirement, spec, code, or test ID - orphan_detector.py # Find artifacts with broken or missing upstream/downstream links - matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) - models/ - trace_index.py # TraceIndex, TraceEntry, OrphanReport models - storage/ - index_store.py # Read/write .specfact/trace/index.json (generated, not authored) - commands/ - index.py # specfact trace index --rebuild - show.py # specfact trace show <id> - orphans.py # specfact trace orphans - matrix.py # specfact trace matrix --format markdown|csv|json -``` - -**`module-package.yaml` declares:** - -- `name: trace` -- `version: 0.1.0` -- `commands: [trace index, trace show, trace orphans, trace matrix]` -- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` -- `publisher:` + `integrity:` — arch-06 marketplace readiness +## Ownership Alignment (2026-06-06) -## Module Package Structure - -``` -modules/trace/ - module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix - src/trace/ - __init__.py - main.py # typer.Typer app — trace command group - engine/ - indexer.py # Build/rebuild traceability index from all layers - query.py # Query index by requirement, spec, code, or test ID - orphan_detector.py # Find artifacts with broken or missing upstream/downstream links - matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) - models/ - trace_index.py # TraceIndex, TraceEntry, OrphanReport models - storage/ - index_store.py # Read/write .specfact/trace/index.json (generated, not authored) - commands/ - index.py # specfact trace index --rebuild - show.py # specfact trace show <id> - orphans.py # specfact trace orphans - matrix.py # specfact trace matrix --format markdown|csv|json -``` - -**`module-package.yaml` declares:** - -- `name: trace` -- `version: 0.1.0` -- `commands: [trace index, trace show, trace orphans, trace matrix]` -- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Repository assignment: `split/rescope` +- Core-owned scope retained here: artifact identity, linkage semantics, orphan + classifications, and graph index contracts. +- Bundle-owned follow-up required: the runtime query and reporting surface belongs + to the canonical module command model. +- Target modules-repo follow-up issue: [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) +- Implementation MUST NOT revive the legacy flat `specfact trace ...` package + layout without the paired module change. ## What Changes -- **NEW**: Trace module in `modules/trace/` with auto-maintained traceability index -- **NEW**: `specfact trace index --rebuild` — scan all requirements, architecture, specs, code, and test artifacts to build a comprehensive traceability index stored at `.specfact/trace/index.json` -- **NEW**: `specfact trace show REQ-123` — query upstream/downstream links for any artifact (requirement, component, spec operation, code module, test) -- **NEW**: `specfact trace orphans` — detect orphaned artifacts: specs with no requirement, code with no spec, requirements with no architecture coverage, tests with no code reference -- **NEW**: `specfact trace matrix --format markdown|csv|json` — export traceability matrix showing the full chain for each requirement -- **NEW**: Incremental index updates — when a single file changes, update only affected trace entries (not full rebuild) -- **NEW**: TraceIndex model with bidirectional links: each entry stores both `upstream_refs` and `downstream_refs` +- **NEW**: Artifact evidence index stored as generated state under `.specfact/`. +- **NEW**: Link model for upstream inputs and downstream implementation evidence: + Spec Kit, OpenSpec, backlog, ADRs, contracts, specs, code, tests, policy + results, and code-review findings. +- **NEW**: Orphan and drift categories for artifacts with missing, stale, + ambiguous, or contradicted evidence. +- **NEW**: Incremental rebuild contract so validation runs can update affected + entries without reindexing an entire repository when possible. +- **NEW**: JSON export shape consumed by `validation-02-full-chain-engine` and + `governance-01-evidence-output`. ## Capabilities ### New Capabilities -- `traceability-index`: Auto-maintained bidirectional traceability index mapping requirements → architecture → specs → code → tests, with orphan detection, incremental updates, and matrix export in markdown/CSV/JSON. +- `artifact-evidence-index`: Generated index for artifact identity, evidence + links, orphan detection, and drift classification across existing inputs. ### Modified Capabilities diff --git a/openspec/changes/validation-02-full-chain-engine/design.md b/openspec/changes/validation-02-full-chain-engine/design.md index 43089e44..c69c5e4d 100644 --- a/openspec/changes/validation-02-full-chain-engine/design.md +++ b/openspec/changes/validation-02-full-chain-engine/design.md @@ -1,12 +1,15 @@ ## Context -This change implements proposal scope for `validation-02-full-chain-engine` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. +This change implements the narrowed validation evidence graph scope for +`validation-02-full-chain-engine`. It is proposal-stage only and defines +implementation strategy without changing runtime code. ## Goals / Non-Goals **Goals:** -- Define an implementation approach that stays within the proposal scope. +- Define an implementation approach that stays within the validation evidence + graph proposal scope. - Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. - Preserve offline-first behavior and deterministic CLI execution. @@ -14,7 +17,8 @@ This change implements proposal scope for `validation-02-full-chain-engine` from - No production code implementation in this stage. - No schema-breaking changes outside declared capabilities. -- No dependency expansion beyond the proposal and plan. +- No ownership of upstream planning, requirements authoring, or architecture + generation. ## Decisions @@ -22,6 +26,8 @@ This change implements proposal scope for `validation-02-full-chain-engine` from - Keep all public APIs contract-first with `@icontract` and `@beartype`. - Make all behavior extensions opt-in or backward-compatible by default. - Add/modify OpenSpec deltas first so tests can be derived before implementation. +- Treat Spec Kit, OpenSpec, backlog, ADR, contract, code, test, and review + artifacts as inputs to validation evidence. ## Risks / Trade-offs @@ -38,5 +44,7 @@ This change implements proposal scope for `validation-02-full-chain-engine` from ## Open Questions -- Dependency summary: Depends on requirements-02-module-commands, architecture-01-solution-layer, and policy-engine-01-unified-framework. +- Dependency summary: Depends on traceability-01-index-and-orphans, + governance-01-evidence-output, requirements input adapters where present, + architecture-boundary input adapters where present, and policy-engine-01. - Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/validation-02-full-chain-engine/proposal.md b/openspec/changes/validation-02-full-chain-engine/proposal.md index 14335d51..7c7beb9f 100644 --- a/openspec/changes/validation-02-full-chain-engine/proposal.md +++ b/openspec/changes/validation-02-full-chain-engine/proposal.md @@ -1,89 +1,59 @@ -# Change: Full-Chain Validation Engine +# Change: Validation Evidence Graph Engine ## Why -Validation today operates only at the spec-code level (`specfact validate` checks spec deltas and contract enforcement). There is no way to validate the entire chain from business requirements through architecture to code and tests. This means a project can pass all technical validations while building entirely the wrong thing. A `--full-chain` validation mode that checks every layer transition — Req → Arch → Spec → Code → Tests — and reports gaps, orphans, and coverage metrics, unlocks the core value proposition: end-to-end traceability with actionable evidence. +SpecFact should not own the full upstream planning lifecycle. Spec Kit, +OpenSpec, backlog tools, ADRs, contracts, tests, and source code already produce +the artifacts teams plan and build from. The sharper product gap is that those +artifacts drift, AI-assisted code accumulates bloat, and CI evidence is often too +weak to prove what changed. -## Ownership Alignment (2026-04-08) +This change turns the old full-chain idea into a validation evidence graph: a +local, deterministic engine that consumes existing artifacts, detects missing or +weak links, classifies severity, and writes evidence that humans, CI, and AI IDEs +can trust. -- Repository assignment: `split/rescope` -- Core-owned scope retained here: shared full-chain report contracts and governance/evidence integration boundaries. -- Bundle-owned follow-up required: the runtime validation engine described below belongs to the canonical `code` / `specfact-codebase` bundle surface, not to `specfact-cli` core. -- Target modules-repo follow-up issue: [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) in `nold-ai/specfact-cli-modules` -- Implementation MUST NOT proceed from the legacy `modules/validate/...` package structure below as a core-owned change. - -## Module Package Structure - -``` -modules/validate/ - # Extends existing validate module — no new module directory - src/validate/ - engine/ - full_chain.py # Full-chain validation orchestrator - layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) - coverage_calculator.py # Compute coverage percentages per layer - evidence_writer.py # Write machine-readable evidence JSON - models/ - chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics -``` - -## Module Package Structure +## Ownership Alignment (2026-06-06) -``` -modules/validate/ - # Extends existing validate module — no new module directory - src/validate/ - engine/ - full_chain.py # Full-chain validation orchestrator - layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) - coverage_calculator.py # Compute coverage percentages per layer - evidence_writer.py # Write machine-readable evidence JSON - models/ - chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics -``` +- Repository assignment: `split/rescope` +- Core-owned scope retained here: evidence graph contracts, node/link semantics, + severity aggregation, and governance/evidence integration boundaries. +- Bundle-owned runtime scope remains in `nold-ai/specfact-cli-modules` and MUST + implement the engine through the canonical grouped command model. +- Target modules-repo follow-up issue: [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) +- Implementation MUST NOT proceed as a requirements-to-architecture-to-code + lifecycle engine. ## What Changes -- **EXTEND**: `specfact validate` extended with `--full-chain` flag that runs validation across all layer transitions: - - Req → Arch: Every business rule mapped to component; every architectural constraint has ADR - - Arch → Spec: Every component has OpenAPI/AsyncAPI spec - - Spec → Code: Existing spec-delta validation (unchanged) - - Code → Tests: Contract coverage, test existence checks - - Orphan detection: Specs with no requirement, code with no spec -- **EXTEND**: Optional `--with-code-quality` side-channel runs `specfact review` during full-chain validation and passes its clean-code summary into the governance evidence envelope without redefining the chain layers. -- **NEW**: Full-chain validation orchestrator in `modules/validate/src/validate/engine/full_chain.py` — runs all layer transition checks, aggregates results, computes coverage metrics -- **NEW**: Layer transition rules with profile-dependent severity: solo gets advisory-only, enterprise gets hard-fail with evidence -- **NEW**: Machine-readable evidence output (JSON) for CI gates: - - ```json - { - "schema_version": "1.0", - "timestamp": "...", - "profile": "enterprise", - "layers": { - "req_to_arch": { "pass": 12, "fail": 2, "advisory": 1 }, - "arch_to_spec": { "pass": 8, "fail": 0, "advisory": 3 }, - "spec_to_code": { "pass": 47, "fail": 0 }, - "orphans": { "specs_without_req": ["GET /legacy/endpoint"] } - }, - "policy_mode": "hard", - "overall": "PASS_WITH_ADVISORY" - } - ``` - -- **NEW**: `--evidence-dir .specfact/evidence/` flag for persisting validation evidence artifacts -- **EXTEND**: Policy engine integration — layer transition severities configurable via policy-engine-01 policy rules +- **NEW**: Validation evidence graph model that normalizes upstream artifacts + into nodes such as requirements input, architecture boundary, OpenSpec/Spec Kit + change, contract, code unit, test, policy result, and code-review finding. +- **NEW**: Link and gap classification for missing evidence, stale references, + orphaned implementation artifacts, uncovered contracts, weak tests, and + AI-bloat remediation status. +- **NEW**: Severity aggregation tuned by profiles and policy modes without + changing the evidence schema. +- **NEW**: Machine-readable evidence output that can be consumed by + `governance-01-evidence-output`, CI gates, and AI IDE remediation loops. +- **EXTEND**: Existing validation flows SHALL expose a compatibility alias such as + `--full-chain`, but the implementation language and evidence schema SHALL use + validation graph terminology. +- **EXTEND**: Optional code-review side channel attaches clean-code and + `ai_bloat` summaries to the graph without redefining upstream planning layers. ## Capabilities ### New Capabilities -- `full-chain-validation`: End-to-end validation across all traceability layers (Req → Arch → Spec → Code → Tests) with profile-dependent severity, orphan detection, coverage metrics, and machine-readable evidence output for CI gates. +- `validation-evidence-graph`: Deterministic validation graph over existing + planning, spec, contract, code, test, policy, and review artifacts with + severity aggregation and JSON evidence output. ### Modified Capabilities -- `sidecar-validation`: Extended with `--full-chain` flag; existing spec-delta validation preserved as-is when flag is omitted -- `full-chain-validation`: Extended with optional code-quality side-channel reporting that remains parallel to the Req → Arch → Spec → Code → Tests transitions +- `sidecar-validation`: Extended to publish graph-compatible evidence for + downstream governance and AI IDE remediation. --- @@ -93,6 +63,6 @@ modules/validate/ - **GitHub Issue**: #241 - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/241> - **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#171 -- **Paired Modules Scope**: full-chain validation runtime engine +- **Paired Modules Scope**: validation evidence graph runtime engine - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/validation-02-full-chain-engine/tasks.md b/openspec/changes/validation-02-full-chain-engine/tasks.md index 3d6549b5..a35b21f6 100644 --- a/openspec/changes/validation-02-full-chain-engine/tasks.md +++ b/openspec/changes/validation-02-full-chain-engine/tasks.md @@ -4,7 +4,7 @@ - [ ] 1.1 Create dedicated worktree branch `feature/validation-02-full-chain-engine` from `dev` before implementation work: `scripts/worktree.sh create feature/validation-02-full-chain-engine`. - [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. -- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. +- [ ] 1.3 Reconfirm scope against the validation evidence graph positioning and this proposal. ## 2. Spec-first and test-first preparation @@ -17,7 +17,7 @@ - [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. - [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. - [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. -- [ ] 3.4 Add `--with-code-quality` as an optional side-channel and keep clean-code reporting out of the core chain-layer state machine. +- [ ] 3.4 Add code-review evidence as an optional side channel and keep clean-code reporting out of any upstream planning state machine. ## 4. Validation and documentation diff --git a/openspec/parking-lot/README.md b/openspec/parking-lot/README.md index a69b9f78..9411b1fc 100644 --- a/openspec/parking-lot/README.md +++ b/openspec/parking-lot/README.md @@ -10,8 +10,9 @@ building infrastructure for customers, publishers, or evidence corpora that do n exist. Carrying them as live changes: - Made the project look unfocused to anyone reading the repo. -- Scattered effort across speculative platforms while the core thesis (full-chain - traceability for agile DevOps + AI IDEs) was still incomplete. +- Scattered effort across speculative platforms while the core thesis + (validation evidence and AI-bloat defense for AI-assisted delivery) was still + incomplete. - Inflated coordination cost (cross-change contracts, integration umbrellas) for work that may never ship as proposed. @@ -53,16 +54,18 @@ Any proposal here can be returned to `openspec/changes/` by: | `cli-val-02-output-snapshot-stability` | A user reports a silent output regression that snapshots would have caught | | `cli-val-05-ci-integration` | cli-val-03 + cli-val-04 shipped and need CI gates | | `cli-val-06-copilot-test-generation` | Manual scenario authoring becomes the bottleneck | +| `ai-integration-04-intent-skills` | Real user pull for a tiny validation-intent helper, not upstream intent engineering | ## Not parked (active roadmap) The following remain in `openspec/changes/` because they directly serve the core thesis: -- `requirements-01..03` (data model, commands, backlog sync) -- `architecture-01-solution-layer` +- `requirements-01..03` as upstream context adapters for validation evidence +- `architecture-01-solution-layer` as architecture-boundary validation input - `traceability-01-index-and-orphans` - `validation-02-full-chain-engine` - `governance-01-evidence-output` +- `governance-02-exception-management` - `profile-01-config-layering` - `ai-integration-01-agent-skill`, `ai-integration-03-instruction-files` - `cli-val-03-misuse-safety-proof`, `cli-val-04-acceptance-test-runner` @@ -72,7 +75,5 @@ implementation (Step 2 of the triage): - `openspec-01-intent-trace` - `ai-integration-02-mcp-server` -- `ai-integration-04-intent-skills` - `telemetry-01-opentelemetry-default-on` - `architecture-02-well-architected-review` (gated on architecture-01 shipping) -- `integration-01-cross-change-contracts` (will be converted to a living doc) diff --git a/openspec/changes/ai-integration-04-intent-skills/.openspec.yaml b/openspec/parking-lot/ai-integration-04-intent-skills/.openspec.yaml similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/.openspec.yaml rename to openspec/parking-lot/ai-integration-04-intent-skills/.openspec.yaml diff --git a/openspec/changes/ai-integration-04-intent-skills/CHANGE_VALIDATION.md b/openspec/parking-lot/ai-integration-04-intent-skills/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/CHANGE_VALIDATION.md rename to openspec/parking-lot/ai-integration-04-intent-skills/CHANGE_VALIDATION.md diff --git a/openspec/changes/ai-integration-04-intent-skills/design.md b/openspec/parking-lot/ai-integration-04-intent-skills/design.md similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/design.md rename to openspec/parking-lot/ai-integration-04-intent-skills/design.md diff --git a/openspec/parking-lot/ai-integration-04-intent-skills/proposal.md b/openspec/parking-lot/ai-integration-04-intent-skills/proposal.md new file mode 100644 index 00000000..850d3b28 --- /dev/null +++ b/openspec/parking-lot/ai-integration-04-intent-skills/proposal.md @@ -0,0 +1,50 @@ +# Change: Parked Validation Intent Helper + +## Status + +PARKED. The old upstream intent-engineering and SQUER workflow is no longer part +of the active product path. + +## Why + +SpecFact should not compete with Spec Kit, OpenSpec, or AI IDE planning +workflows for requirements interviews, decomposition, or architecture derivation. +If a helper exists later, it should only capture the narrow validation question: +what evidence must be checked before this AI-assisted change is trusted? + +## What Changes + +- **PARK**: Multi-skill intent interview, requirement decomposition, architecture + generation, and evidence-check workflow. +- **KEEP AS OPTIONAL FUTURE SCOPE**: One tiny validation-intent helper that can + record expected evidence, risk, and rerun criteria for a validation loop. +- **REMOVE FROM CRITICAL PATH**: SQUER branding, seven-question interviews, + requirement authoring, and architecture derivation. + +## Capabilities + +### New Capabilities + +- `validation-intent-helper`: Optional future helper for capturing expected + validation evidence before an AI-assisted change. Not active until real user + pull exists. + +### Modified Capabilities + +- `agent-skill-validation`: MAY reference the helper if it is later un-parked. + +## Impact + +- No implementation should begin while this change remains parked. +- If un-parked, the proposal must be rewritten as a small validation helper and + moved out of the upstream-planning category. + +--- + +## Source Tracking + +<!-- source_repo: nold-ai/specfact-cli --> +- **GitHub Issue**: #349 +- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/349> +- **Repository**: nold-ai/specfact-cli +- **Last Synced Status**: proposed diff --git a/openspec/changes/ai-integration-04-intent-skills/specs/agent-skill-intent-workflow/spec.md b/openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-intent-workflow/spec.md similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/specs/agent-skill-intent-workflow/spec.md rename to openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-intent-workflow/spec.md diff --git a/openspec/changes/ai-integration-04-intent-skills/specs/agent-skill-spec-intelligence/spec.md b/openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-spec-intelligence/spec.md similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/specs/agent-skill-spec-intelligence/spec.md rename to openspec/parking-lot/ai-integration-04-intent-skills/specs/agent-skill-spec-intelligence/spec.md diff --git a/openspec/changes/ai-integration-04-intent-skills/tasks.md b/openspec/parking-lot/ai-integration-04-intent-skills/tasks.md similarity index 100% rename from openspec/changes/ai-integration-04-intent-skills/tasks.md rename to openspec/parking-lot/ai-integration-04-intent-skills/tasks.md diff --git a/openspec/specs/call-graph-analysis/spec.md b/openspec/specs/call-graph-analysis/spec.md new file mode 100644 index 00000000..06dea034 --- /dev/null +++ b/openspec/specs/call-graph-analysis/spec.md @@ -0,0 +1,59 @@ +# call-graph-analysis Specification + +## Purpose +TBD - created by archiving change dep-security-cleanup. Update Purpose after archive. +## Requirements +### Requirement: Call-graph extraction via pycg CLI + +The system SHALL provide optional call-graph analysis using the `pycg` CLI tool (Apache-2.0-licensed). When `pycg` is not installed, the system SHALL degrade gracefully by returning an empty call graph without raising an exception. All code paths involving `pycg` MUST be decorated with `@beartype` and `@icontract` on public-facing methods. + +#### Scenario: pycg available — call graph extracted successfully + +- **WHEN** `pycg` is available on `$PATH` +- **AND** `graph_analyzer.extract_call_graph(file_path)` is called with a valid Python file +- **THEN** the system SHALL invoke `subprocess.run` with argv equivalent to + `["pycg", "--package", <repo_root>, str(file_path), "--output", <temp_json_path>]` + (repository root is the analyzer's `repo_path`) +- **AND** SHALL parse the resulting JSON file using `_parse_pycg_json` +- **AND** SHALL return a `dict[str, list[str]]` mapping **caller** names to lists of **callee** names (PyCG simple JSON adjacency list) +- **AND** SHALL store the result in `self.call_graphs` keyed by relative file path + +#### Scenario: pycg not available — graceful degradation + +- **WHEN** `pycg` is NOT available on `$PATH` +- **AND** `graph_analyzer.extract_call_graph(file_path)` is called +- **THEN** the system SHALL return an empty dict `{}` +- **AND** SHALL NOT raise any exception + +#### Scenario: pycg invocation fails (non-zero exit) + +- **WHEN** `pycg` is available but returns a non-zero exit code for a given file +- **THEN** the system SHALL return an empty dict `{}` +- **AND** SHALL NOT propagate the subprocess error to the caller + +#### Scenario: JSON output parsed into call graph structure + +- **WHEN** `pycg` produces a JSON file with content `{"foo": ["bar", "baz"]}` +- **THEN** `_parse_pycg_json` SHALL return `{"foo": ["bar", "baz"]}` (caller `foo` calls `bar` and `baz`) +- **AND** the result SHALL be a `dict[str, list[str]]` + +### Requirement: Optional dep availability check for pycg + +The system SHALL expose enhanced-analysis availability via `check_enhanced_analysis_dependencies()` in `optional_deps.py`. That routine SHALL include `pycg` using `check_cli_tool_available("pycg")` and document that **`pycg` is the active call-graph tool**. + +#### Scenario: pycg listed in optional deps report + +- **WHEN** `check_enhanced_analysis_dependencies()` is called +- **THEN** the returned dict SHALL contain a `"pycg"` key +- **AND** the value SHALL be `(True, None)` when `pycg` is available and the probe succeeds +- **AND** the value SHALL be `(False, <error_message>)` when `pycg` is not available (non-empty installation hint string) + +### Requirement: License-clean optional analysis stack + +All packages in the `enhanced-analysis` extra SHALL use MIT, Apache-2.0, BSD, or PSF licenses. No GPL or AGPL packages SHALL appear in any distributed extra. + +#### Scenario: enhanced-analysis extra contains no GPL packages + +- **WHEN** `pip install specfact-cli[enhanced-analysis]` is run +- **THEN** no installed package SHALL carry a GPL-2.0, GPL-3.0, AGPL-3.0, or GPL-2.0-or-later license +- **AND** the call-graph capability SHALL be provided by `pycg` (Apache-2.0) diff --git a/openspec/specs/ci-integration/spec.md b/openspec/specs/ci-integration/spec.md index ee3f517c..e96a5041 100644 --- a/openspec/specs/ci-integration/spec.md +++ b/openspec/specs/ci-integration/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change ci-docs-sync-check. Update Purpose after archive. - ## Requirements - ### Requirement: Branch Protection Configuration The system SHALL configure branch protection to require docs sync check. @@ -146,3 +144,22 @@ The `sign-modules.yml` **`verify`** job SHALL source **`scripts/module-verify-po - **WHEN** the job runs for `pull_request` or `workflow_dispatch` - **THEN** it SHALL invoke `verify-modules-signature.py` with **`VERIFY_MODULES_PR`** and `--version-check-base origin/<base_branch>` + +### Requirement: Package Manager Runtime Checks Block Pull Requests + +CI SHALL execute command contract smoke tests through the supported package-manager launch paths before pull requests can merge. + +#### Scenario: Pull request package-manager matrix + +- **GIVEN** a pull request changes CLI runtime, command docs, command validators, packaging, module discovery, or CI smoke scripts +- **WHEN** PR validation runs +- **THEN** CI executes a runtime matrix that covers hatch, pip wheel install, pipx install, uv run, and uv tool or uvx execution +- **AND** each matrix leg validates root help, unknown command guidance, module command discovery, generated command overview checks, and representative official module help paths. + +#### Scenario: Matrix failures identify package-manager context + +- **GIVEN** one matrix leg fails +- **WHEN** CI reports the failure +- **THEN** the failure output identifies the package-manager launcher, command path, exit code, and relevant stdout/stderr excerpt +- **AND** the PR is blocked until the mismatch is fixed or an explicit documented exception is accepted. + diff --git a/openspec/specs/cli-error-guidance/spec.md b/openspec/specs/cli-error-guidance/spec.md new file mode 100644 index 00000000..cbcc54c8 --- /dev/null +++ b/openspec/specs/cli-error-guidance/spec.md @@ -0,0 +1,43 @@ +# cli-error-guidance Specification + +## Purpose +TBD - created by archiving change tester-cli-reliability. Update Purpose after archive. +## Requirements +### Requirement: CLI Errors Show Relevant Help And Missing Information + +The CLI SHALL render actionable help for unknown commands, missing subcommands, and missing required parameters across core and loaded module command groups. + +#### Scenario: Unknown root command suggests recovery + +- **GIVEN** a user invokes an unknown root command such as `specfact hello` +- **WHEN** command resolution fails +- **THEN** the output includes the root help context +- **AND** it states that `hello` is not a valid command +- **AND** it suggests nearby valid command groups or the command used to list commands +- **AND** the command exits with a usage-error status. + +#### Scenario: Missing subcommand on command group + +- **GIVEN** a command group has no default action +- **WHEN** the user invokes the group without a subcommand +- **THEN** the output includes that group's help +- **AND** it states that a subcommand is required +- **AND** it lists or points to the available subcommands +- **AND** the command exits with a usage-error status. + +#### Scenario: Missing required parameter on leaf command + +- **GIVEN** a leaf command requires one or more arguments or options +- **WHEN** the user invokes the command without those required parameters +- **THEN** the output includes that command's help +- **AND** it names each missing required parameter using its CLI spelling +- **AND** it shows the canonical invocation shape +- **AND** the command exits with a usage-error status. + +#### Scenario: Explicit help remains successful + +- **GIVEN** a user invokes any command or command group with `--help` +- **WHEN** help rendering succeeds +- **THEN** the command exits successfully +- **AND** no missing-parameter or missing-subcommand error is emitted. + diff --git a/openspec/specs/command-package-runtime-validation/spec.md b/openspec/specs/command-package-runtime-validation/spec.md index ff082599..75a5c94f 100644 --- a/openspec/specs/command-package-runtime-validation/spec.md +++ b/openspec/specs/command-package-runtime-validation/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change cli-val-07-command-package-runtime-validation. Update Purpose after archive. - ## Requirements - ### Requirement: Command Inventory Covers Core And Official Bundles The system SHALL derive a validation inventory that covers the released core commands and every official command package shipped from `specfact-cli-modules`. @@ -27,6 +25,13 @@ The system SHALL derive a validation inventory that covers the released core com - **AND** the inventory includes grouped paths such as `backlog ceremony standup`, `project sync bridge`, `spec contract validate`, `code validate sidecar run`, and `govern patch apply` - **AND** a missing nested command path fails validation instead of being silently skipped. +#### Scenario: Inventory feeds AI-agent command overview artifacts + +- **GIVEN** the runtime validation inventory is generated +- **WHEN** command overview artifacts are written +- **THEN** the same inventory data is used for `llms.txt`, Markdown, JSON, docs validation, and runtime smoke selection +- **AND** validators do not use a separate manually maintained command allowlist for canonical commands. + ### Requirement: Validation Matrix Executes Commands In Logical Runtime Order The system SHALL execute the command inventory in a deterministic order that matches normal user setup and runtime dependencies. @@ -103,3 +108,23 @@ The system SHALL emit a report that maps findings to the responsible package, co - **WHEN** the command reports success - **THEN** it prints one line per upgraded module rather than a single comma-joined list - **AND** each line includes the module id plus the previous and resulting version in `old -> new` form. + +### Requirement: Package Manager Runtime Matrix Blocks Command Mismatches + +The command validation surface SHALL run through representative hatch, pip, pipx, and uv launchers before PRs can merge. + +#### Scenario: Runtime matrix exercises installed CLI paths + +- **GIVEN** a pull request changes CLI runtime, module discovery, command docs, or packaging behavior +- **WHEN** CI runs the package-manager runtime matrix +- **THEN** it builds and executes the CLI through hatch source execution, pip wheel install, pipx install, uv run, and uv tool or uvx execution paths +- **AND** it validates representative core and official module command groups in each path +- **AND** any command path, module discovery, or install-method mismatch blocks the PR. + +#### Scenario: Runtime matrix covers pipx stale-launcher repair + +- **GIVEN** `specfact upgrade` is running from a pipx-managed installation +- **WHEN** the upgrade-command stale-launcher recovery scenario is exercised +- **THEN** the package-manager runtime matrix SHALL validate the authoritative + `upgrade-command` contract for `pipx reinstall specfact-cli` fallback and + post-reinstall launcher validation. diff --git a/openspec/specs/core-cli-reference/spec.md b/openspec/specs/core-cli-reference/spec.md index c1d234ab..3beff7b7 100644 --- a/openspec/specs/core-cli-reference/spec.md +++ b/openspec/specs/core-cli-reference/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change docs-05-core-site-ia-restructure. Update Purpose after archive. - ## Requirements - ### Requirement: Core CLI reference pages exist The system SHALL provide dedicated reference pages for core CLI commands. @@ -15,17 +13,35 @@ The system SHALL provide dedicated reference pages for core CLI commands. - **GIVEN** the docs/core-cli/init.md page exists - **WHEN** a user reads the page - **THEN** it documents: specfact init, init --profile, init --install, init ide, init --install-deps -- **AND** all documented commands match the actual --help output +- **AND** all documented commands match the actual --help output. + +#### Scenario: Init ide exports match target integration model + +- **GIVEN** prompt sources are available from core or installed modules +- **WHEN** `specfact init ide` exports to a slash-command target such as Cursor, VS Code, or Claude commands +- **THEN** it writes one prompt file per workflow into the target command/prompt directory. +- **WHEN** `specfact init ide` exports to a skill-based target such as Codex CLI, Claude Code Skills, or Mistral Vibe +- **THEN** it writes grouped capability-oriented `<skill>/SKILL.md` files per selected source/module +- **AND** it does not create one `SKILL.md` folder per slash-command prompt. #### Scenario: Module reference page documents all subcommands - **GIVEN** the docs/core-cli/module.md page exists - **WHEN** a user reads the page - **THEN** it documents: module install, module uninstall, module list, module show, module search, module upgrade, module alias, module add-registry, module list-registries, module remove-registry, module enable, module disable -- **AND** all documented commands match the actual --help output +- **AND** all documented commands match the actual --help output. #### Scenario: Upgrade reference page documents the command - **GIVEN** the docs/core-cli/upgrade.md page exists - **WHEN** a user reads the page -- **THEN** it documents the specfact upgrade command and its options +- **THEN** it documents the specfact upgrade command and its options. + +#### Scenario: Reference docs are checked against generated command overview + +- **GIVEN** a core CLI reference page, prompt, template, or guidance string contains a `specfact` command example +- **WHEN** docs command validation runs +- **THEN** the example is checked against the generated command overview +- **AND** stale flat shims and invalid option ordering fail validation +- **AND** no reference page is excluded from command validation unless it is explicitly marked as historical migration material. + diff --git a/openspec/specs/cross-change-integration-contract/spec.md b/openspec/specs/cross-change-integration-contract/spec.md new file mode 100644 index 00000000..d7456272 --- /dev/null +++ b/openspec/specs/cross-change-integration-contract/spec.md @@ -0,0 +1,39 @@ +# cross-change-integration-contract Specification + +## Purpose + +This spec defines deterministic ownership, compatibility, and wave-gate +contracts for active OpenSpec changes that touch shared interfaces or payloads. +It gives repo maintainers, tooling modules, and implementation agents a stable +source of truth for resolving overlap without weakening backward compatibility. + +## Requirements +### Requirement: Cross-Change Ownership Contract + +The system SHALL define authoritative ownership boundaries for shared interfaces and overlapping implementation files across active architecture integration changes. + +#### Scenario: Shared interface has one owner + +- **WHEN** multiple changes modify the same interface family +- **THEN** exactly one change is designated owner for canonical interface semantics +- **AND** dependent changes align to that canonical contract + +### Requirement: Cross-Change Compatibility Contract + +The system SHALL define compatibility constraints for shared payloads and extension namespaces used across architecture integration changes. + +#### Scenario: Shared payload compatibility is validated + +- **WHEN** a dependent change introduces payload extensions +- **THEN** the extension preserves compatibility with the owner-defined envelope +- **AND** migration guidance is required for any non-additive change + +### Requirement: Integration Gate for Wave Progression + +The system SHALL require objective integration gate criteria to close each architecture integration wave. + +#### Scenario: Wave cannot close without gate evidence + +- **WHEN** a wave completion is proposed +- **THEN** required gate evidence is present and traceable +- **AND** unresolved cross-change conflicts block wave closure diff --git a/openspec/specs/dep-license-gate/spec.md b/openspec/specs/dep-license-gate/spec.md new file mode 100644 index 00000000..1b013402 --- /dev/null +++ b/openspec/specs/dep-license-gate/spec.md @@ -0,0 +1,140 @@ +# dep-license-gate Specification + +## Purpose +TBD - created by archiving change dep-security-cleanup. Update Purpose after archive. +## Requirements +### Requirement: Automated license compliance gate + +The system SHALL provide a `hatch run license-check` script that scans all installed packages in the active environment and fails if any package carries a GPL-2.0, GPL-3.0, AGPL-3.0, GPL-2.0-or-later, GPL-3.0-or-later, or AGPL-3.0-or-later license that is not present in the project's documented exception allowlist. This gate SHALL be executable in CI and locally. + +The gate SHALL be implemented as `scripts/check_license_compliance.py` using `pip-licenses` to enumerate installed packages and their SPDX expressions. + +#### Scenario: All packages are license-compliant + +- **WHEN** `hatch run license-check` is executed +- **AND** no installed package has a GPL or AGPL license outside the allowlist +- **THEN** the script SHALL exit with code 0 +- **AND** SHALL print a summary of all packages and their licenses + +#### Scenario: GPL package detected outside allowlist + +- **WHEN** `hatch run license-check` is executed +- **AND** an installed package carries a GPL or AGPL license not in the exception allowlist +- **THEN** the script SHALL exit with code 1 +- **AND** SHALL print the offending package name, version, and license +- **AND** SHALL print the message: `LICENSE VIOLATION: <package>==<version> uses <license> which is incompatible with Apache-2.0` + +#### Scenario: Package in exception allowlist is accepted + +- **WHEN** `hatch run license-check` is executed +- **AND** an installed package is in the allowlist (e.g., `pygments`, `pylint`, `semgrep`) +- **THEN** the script SHALL accept the package without failing +- **AND** SHALL print: `EXCEPTION: <package>==<version> (<license>) — <reason>` + +#### Scenario: Unknown license triggers warning, not failure + +- **WHEN** `hatch run license-check` is executed +- **AND** a package has no SPDX expression or `UNKNOWN` license +- **THEN** the script SHALL print a WARNING for each such package +- **AND** SHALL NOT fail the gate (these are investigated separately) +- **AND** SHALL include the warning in the summary output + +### Requirement: License exception allowlist file + +The project SHALL maintain a `scripts/license_allowlist.yaml` file that documents all accepted GPL/LGPL exception packages. Each entry SHALL include the package name, accepted license, and a human-readable reason. + +#### Scenario: Allowlist file exists and is parseable + +- **WHEN** `scripts/check_license_compliance.py` runs +- **THEN** it SHALL load `scripts/license_allowlist.yaml` +- **AND** each entry SHALL have `package`, `license`, and `reason` fields +- **AND** the script SHALL fail with a clear error if the allowlist file is missing or malformed + +#### Scenario: Manifest dependency missing from static license map + +- **WHEN** `hatch run license-check` evaluates `pip_dependencies` in a `module-package.yaml` +- **AND** the dependency name is not listed under `licenses` in `scripts/module_pip_dependencies_licenses.yaml` +- **THEN** the gate SHALL exit with code 1 +- **AND** SHALL print a `MODULE MANIFEST VIOLATION` message that names the dependency and the mapping file + +#### Scenario: New (A)GPL package added to pyproject.toml without allowlist entry + +- **WHEN** a developer adds a new GPL or AGPL package to any extra in `pyproject.toml` +- **AND** runs `hatch run license-check` +- **THEN** the gate SHALL fail +- **AND** SHALL instruct the developer to either remove the package or add an allowlist entry with a documented reason + +### Requirement: Automated CVE and security audit gate + +The system SHALL provide a `hatch run security-audit` script that runs `pip-audit` against the active environment to detect known CVEs in installed packages. The gate SHALL fail if any vulnerability with CVSS score >= 7.0 (high severity) is found. + +`pip-audit` (MIT, by Python Packaging Authority) is the standard CVE scanning tool for Python packages, backed by the OSV and PyPI vulnerability databases. + +#### Scenario: No CVEs found + +- **WHEN** `hatch run security-audit` is executed +- **AND** no installed package has a known CVE at high severity +- **THEN** the script SHALL exit with code 0 +- **AND** SHALL print: `Security audit passed. No high-severity vulnerabilities found.` + +#### Scenario: High-severity CVE found + +- **WHEN** `hatch run security-audit` is executed +- **AND** an installed package has a CVE with CVSS >= 7.0 +- **THEN** the script SHALL exit with code 1 +- **AND** SHALL print the package name, version, CVE ID, CVSS score, and description +- **AND** SHALL print: `ACTION REQUIRED: Update or replace <package>==<version>` + +#### Scenario: Low/medium CVE found — warning only + +- **WHEN** `hatch run security-audit` is executed +- **AND** an installed package has a CVE with CVSS < 7.0 +- **THEN** the script SHALL print a WARNING with the details +- **AND** SHALL NOT fail the gate (engineer reviews and decides) + +#### Scenario: pip-audit not available + +- **WHEN** `hatch run security-audit` is executed +- **AND** `pip-audit` is not installed +- **THEN** the script SHALL print an error: `pip-audit not installed. Run: pip install pip-audit` +- **AND** SHALL exit with code 1 + +### Requirement: CI integration for license and security gates + +The license compliance gate SHALL be integrated into the project's CI workflow +as a separate step that runs on pull requests modifying dependency manifests +such as `pyproject.toml`. The security audit gate SHALL run on every PR. The +agent-rules documentation SHALL reference these gates as mandatory checks before +merging any dependency change. + +#### Scenario: License gate runs in CI on dependency changes + +- **WHEN** a pull request modifies `pyproject.toml` **and** matches the PR orchestrator's non-documentation code-change filter +- **THEN** the CI workflow SHALL run the license compliance gate (`hatch run license-check` / `scripts/check_license_compliance.py`) +- **AND** SHALL block merge if the gate fails + +#### Scenario: Security audit runs in CI on all PRs + +- **WHEN** any pull request is opened or updated +- **THEN** the CI workflow SHALL run `hatch run security-audit` +- **AND** SHALL block merge if any high-severity CVE is found + +### Requirement: Agent-rules documentation for dependency hygiene + +The project's `docs/agent-rules/` framework SHALL include a dedicated section on dependency hygiene that specifies: + +- No packages without a known SPDX license expression (treat as unknown risk) +- All new runtime dependencies must have MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, or PSF licenses +- `hatch run license-check` and `hatch run security-audit` are required before any dependency change is merged + +#### Scenario: Agent reads dependency hygiene rules + +- **WHEN** an AI agent or developer reviews the agent-rules framework +- **THEN** `docs/agent-rules/` SHALL contain explicit rules about (A)GPL prohibition, allowlist process, and required gate scripts +- **AND** these rules SHALL be discoverable via the INDEX.md + +#### Scenario: Developer adds dependency without license check + +- **WHEN** a PR adds a new package to pyproject.toml +- **AND** the license-check gate is not run +- **THEN** CI SHALL catch the omission and require the gate to pass before merge diff --git a/openspec/specs/dependency-resolution/spec.md b/openspec/specs/dependency-resolution/spec.md index da037959..710392eb 100644 --- a/openspec/specs/dependency-resolution/spec.md +++ b/openspec/specs/dependency-resolution/spec.md @@ -3,12 +3,10 @@ ## Purpose TBD - created by archiving change marketplace-02-advanced-marketplace-features. Update Purpose after archive. - ## Requirements - ### Requirement: Resolve pip dependencies across all modules -The system SHALL aggregate pip_dependencies from all installed modules and resolve constraints using pip-compile or fallback resolver. +The system SHALL aggregate pip_dependencies from all installed modules and resolve constraints using pip-compile or fallback resolver. The resolved package set SHALL NOT include packages with GPL-2.0, GPL-3.0, or AGPL-3.0 licenses unless they are documented in the project's license-exception allowlist. #### Scenario: Dependencies resolved without conflicts @@ -230,3 +228,57 @@ resolution plan without performing any installs or upgrades. ``` - **AND** SHALL exit 0 without modifying any installed modules + +### Requirement: Wrong-package removal from enhanced-analysis and dev extras + +The system SHALL NOT include `syft` (OpenMined ML framework) or `bearer` (SaaS HTTP auth client) in any distributed extra. These packages provide no functional benefit and were included in error. + +#### Scenario: enhanced-analysis extra does not install syft or bearer + +- **WHEN** `pip install specfact-cli[enhanced-analysis]` is run +- **THEN** the `syft` PyPI package SHALL NOT be installed +- **AND** the `bearer` PyPI package SHALL NOT be installed + +#### Scenario: dev extra does not install bearer + +- **WHEN** `pip install specfact-cli[dev]` is run +- **THEN** the `bearer` PyPI package SHALL NOT be installed + +### Requirement: JSONC read/write via commentjson and stdlib json + +The system SHALL read VS Code `settings.json` (JSONC format with `//` comments and trailing commas) using `commentjson.loads()` and SHALL write JSON output using stdlib `json.dumps(indent=4)`. The `json5` package SHALL NOT be used. + +#### Scenario: JSONC file with comments is read correctly + +- **WHEN** `project_artifact_write` reads a VS Code `settings.json` that contains `//` comments +- **THEN** `commentjson.loads(raw_text)` SHALL strip the comments and parse the JSON successfully +- **AND** the resulting Python dict SHALL match the data in the file (excluding comments) + +#### Scenario: JSONC file with trailing commas is read correctly + +- **WHEN** `project_artifact_write` reads a `settings.json` containing trailing commas in arrays or objects +- **THEN** `commentjson.loads(raw_text)` SHALL parse it without raising a `JSONDecodeError` + +#### Scenario: JSON output is written without trailing commas or unquoted keys + +- **WHEN** `project_artifact_write` writes a payload to a JSON file +- **THEN** `json.dumps(payload, indent=4)` SHALL produce valid standard JSON +- **AND** all keys SHALL be quoted +- **AND** there SHALL be no trailing commas +- **AND** the output SHALL be byte-for-byte equivalent to the previous `json5.dumps(..., quote_keys=True, trailing_commas=False)` output for well-formed inputs + +### Requirement: bandit available for Python-native security analysis + +The system SHALL include `bandit` in the `dev` extra as the Python-native static security analysis tool. A `bandit-scan` hatch script SHALL allow developers to run bandit against `src/`. + +#### Scenario: bandit installed in dev environment + +- **WHEN** `pip install specfact-cli[dev]` is run +- **THEN** `bandit` SHALL be available on `$PATH` + +#### Scenario: bandit scan runs against src/ + +- **WHEN** `hatch run bandit-scan` is executed +- **THEN** `bandit -r src/ -ll` SHALL run and report findings at medium severity or above +- **AND** the command SHALL exit non-zero if high-severity issues are found + diff --git a/openspec/specs/doc-frontmatter-schema/spec.md b/openspec/specs/doc-frontmatter-schema/spec.md index 510d79b0..7d69280d 100644 --- a/openspec/specs/doc-frontmatter-schema/spec.md +++ b/openspec/specs/doc-frontmatter-schema/spec.md @@ -115,7 +115,7 @@ The system SHALL provide a function to extract frontmatter from Markdown files. - **THEN** the function SHALL return an empty dictionary - **AND** no error SHALL be raised -## Contract Requirements +**Contract requirements:** ### Requirement: Input Validation Contracts diff --git a/openspec/specs/doc-frontmatter-validation/spec.md b/openspec/specs/doc-frontmatter-validation/spec.md index f431ba37..25eb81a9 100644 --- a/openspec/specs/doc-frontmatter-validation/spec.md +++ b/openspec/specs/doc-frontmatter-validation/spec.md @@ -116,7 +116,7 @@ The system SHALL properly handle files marked as exempt. - **WHEN** a file has `exempt: false` or no exemption - **THEN** the file SHALL undergo full validation -## Contract Requirements +**Contract requirements:** ### Requirement: Validation Contracts @@ -139,7 +139,7 @@ The script SHALL handle file and YAML errors gracefully while preserving validat - **THEN** the error SHALL be surfaced in validation output - **AND** validation SHALL continue for the remaining files -## Performance Requirements +**Performance requirements:** ### Requirement: Efficient File Processing diff --git a/openspec/specs/docs-contributing-updates/spec.md b/openspec/specs/docs-contributing-updates/spec.md index 1298a56a..255889b8 100644 --- a/openspec/specs/docs-contributing-updates/spec.md +++ b/openspec/specs/docs-contributing-updates/spec.md @@ -89,7 +89,7 @@ The system SHALL provide practical examples and templates. - **THEN** they SHALL find real-world examples - **AND** explanations of design decisions -## Contract Requirements +**Contract requirements:** ### Requirement: Documentation Completeness @@ -111,7 +111,7 @@ Documentation SHALL accurately reflect the current implementation. - **THEN** it SHALL work as described - **AND** produce the expected results -## Quality Requirements +**Quality requirements:** ### Requirement: Readability diff --git a/openspec/specs/environment-manager-detection/spec.md b/openspec/specs/environment-manager-detection/spec.md new file mode 100644 index 00000000..67058ca2 --- /dev/null +++ b/openspec/specs/environment-manager-detection/spec.md @@ -0,0 +1,47 @@ +# environment-manager-detection Specification + +## Purpose +TBD - created by archiving change runtime-01-discovery-reliability. Update Purpose after archive. +## Requirements +### Requirement: Environment Manager Detection Supports Rootless Monorepos + +The system SHALL detect supported Python environment managers in repositories that do not have a root-level Python project file but do contain package-level project files. + +#### Scenario: Rootless monorepo with uv package files + +- **GIVEN** a repository root has no `pyproject.toml` +- **AND** a first-level package directory contains `pyproject.toml` +- **AND** `uv` is available on `PATH` +- **WHEN** environment manager detection runs for the repository root +- **THEN** the detected manager is `uv` +- **AND** the command prefix is `uv run` +- **AND** `specfact init ide` does not report "No Compatible Environment Manager Detected" + +#### Scenario: Rootless monorepo with nested uv lock + +- **GIVEN** a repository root has no `pyproject.toml` +- **AND** a first-level or second-level package directory contains `uv.lock` or `uv.toml` +- **AND** `uv` is available on `PATH` +- **WHEN** environment manager detection runs for the repository root +- **THEN** the detected manager is `uv` + +### Requirement: Environment Manager Detection Falls Back To PATH Tools + +When no project marker identifies an environment manager, the system SHALL detect supported tools available on `PATH` before returning `unknown`. + +#### Scenario: PATH-only uv detection + +- **GIVEN** a repository has no supported root or package-level Python project marker +- **AND** `uv` is available on `PATH` +- **WHEN** environment manager detection runs +- **THEN** the detected manager is `uv` +- **AND** the command prefix is `uv run` + +#### Scenario: No markers or tools remain unknown + +- **GIVEN** a repository has no supported Python project marker +- **AND** no supported environment manager executable is available on `PATH` +- **WHEN** environment manager detection runs +- **THEN** the detected manager remains `unknown` +- **AND** existing direct-invocation fallback behavior is preserved + diff --git a/openspec/specs/generated-command-overview/spec.md b/openspec/specs/generated-command-overview/spec.md new file mode 100644 index 00000000..200eee18 --- /dev/null +++ b/openspec/specs/generated-command-overview/spec.md @@ -0,0 +1,42 @@ +# generated-command-overview Specification + +## Purpose +TBD - created by archiving change tester-cli-reliability. Update Purpose after archive. +## Requirements +### Requirement: Generated Command Overview Is The Authoritative Command Contract + +The repository SHALL generate deterministic command overview artifacts from the actual core and official module command tree. + +#### Scenario: Core command overview artifacts are generated + +- **GIVEN** the command overview generator runs in the core repository +- **WHEN** it writes artifacts +- **THEN** it produces `llms.txt`, `docs/reference/commands.generated.md`, and `docs/reference/commands.generated.json` +- **AND** every command record includes command path, owning repo, owning package or module, install prerequisite, short help, arguments/options, subcommands, source import path when known, and hidden/deprecated status +- **AND** generated output is stable for the same source tree. + +#### Scenario: Generated artifacts are freshness-checked + +- **GIVEN** CLI source, module manifests, docs, prompts, or command validation scripts change +- **WHEN** the command overview check runs in pre-commit or CI +- **THEN** it fails if generated artifacts are stale +- **AND** it tells the developer which generator command refreshes the artifacts. + +### Requirement: Docs And Guidance Validate Against Generated Command Contract + +Docs, prompt, template, and code guidance validation SHALL use the generated command contract instead of prefix-only help checks. + +#### Scenario: Legacy command references fail validation + +- **GIVEN** a Markdown file, prompt, Jinja2 template, YAML/JSON/text resource, or Python guidance string contains an obsolete command such as `specfact sync bridge` +- **WHEN** command guidance validation runs +- **THEN** the validator fails unless the reference is inside an explicitly marked migration/deprecation context +- **AND** the finding includes file path, line number, observed command, and canonical replacement when known. + +#### Scenario: Invalid option placement fails validation + +- **GIVEN** documentation contains `specfact code import <bundle> --repo .` +- **WHEN** command guidance validation runs +- **THEN** the validator rejects the example because the generated command contract does not support that option placement +- **AND** it reports the canonical supported invocation. + diff --git a/openspec/specs/init-ide-prompt-source-selection/spec.md b/openspec/specs/init-ide-prompt-source-selection/spec.md index 28077d7e..4f4b709b 100644 --- a/openspec/specs/init-ide-prompt-source-selection/spec.md +++ b/openspec/specs/init-ide-prompt-source-selection/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change init-ide-prompt-source-selection. Update Purpose after archive. - ## Requirements - ### Requirement: Init IDE Must Export All Prompt Sources By Default `specfact init ide` SHALL export all available prompt sources by default. @@ -79,3 +77,31 @@ Exported prompts for VS Code / Copilot (under ``.github/prompts/``) and other mu - **WHEN** two installed modules expose the same template basename - **THEN** the merged export uses a deterministic last-wins rule by sorted source id (later id overwrites earlier) - **AND** the flat export contains exactly one file per output basename. + +### Requirement: Init IDE SHALL preserve unrelated VS Code settings + +`specfact init ide` SHALL reconcile prompt recommendations into `.vscode/settings.json` without deleting unrelated user-managed settings. + +#### Scenario: Existing non-SpecFact settings survive prompt export + +- **WHEN** a repository already contains `.vscode/settings.json` with Python, test, or formatter settings +- **AND** the user runs `specfact init ide` +- **THEN** the command SHALL preserve those unrelated settings +- **AND** SHALL update only SpecFact-managed prompt recommendation entries + +#### Scenario: Selective prompt export removes only prior SpecFact-managed recommendations + +- **WHEN** the user runs `specfact init ide --prompts <subset>` +- **THEN** prior SpecFact-managed prompt recommendations outside the selected subset MAY be removed +- **AND** unrelated `.github/prompts/` recommendations and non-SpecFact settings SHALL remain unchanged + +### Requirement: Init IDE SHALL fail safe on malformed settings documents + +`specfact init ide` SHALL not replace malformed or unparsable VS Code settings with an empty or generated document by default. + +#### Scenario: Malformed settings file blocks destructive rewrite + +- **WHEN** `.vscode/settings.json` exists but cannot be parsed as JSON +- **THEN** `specfact init ide` SHALL stop with an actionable error +- **AND** SHALL leave the existing file unchanged unless explicit replacement is requested through the safe-write policy + diff --git a/openspec/specs/init-module-state/spec.md b/openspec/specs/init-module-state/spec.md index 9907a0bc..b8813008 100644 --- a/openspec/specs/init-module-state/spec.md +++ b/openspec/specs/init-module-state/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change arch-01-cli-modular-command-registry. Update Purpose after archive. - ## Requirements - ### Requirement: Init Discovers Modules and Stores State with Version and Enabled Flag When the user runs **specfact init**, the CLI SHALL discover all available module packages, SHALL treat each as **enabled by default**, and SHALL write a **state file** under `~/.specfact/registry/` (e.g. `modules.json`) that records for each module: identifier, version, and **enabled** (boolean). Subsequent runs of specfact init SHALL read this state file and SHALL respect previously set enabled/disabled values (user overrides). @@ -53,3 +51,38 @@ When the user runs **specfact init**, the CLI SHALL discover all available modul - --enable-module <id> and --disable-module <id> are supported (multiple allowed) - State file is updated after init so overrides persist - After init, if any module is disabled and that is due to user override (saved in state), print a message: e.g. "The following modules are disabled by your configuration: <list>. Re-enable with specfact init --enable-module <id>." + +### Requirement: Init Profile State Refresh Is Repo-Aware and Merge-Based + +When `specfact init` installs or refreshes modules, the system SHALL discover project-scope modules relative to the selected repository path and SHALL merge discovered module rows with existing lifecycle state instead of replacing unrelated state blindly. + +#### Scenario: Init profile uses repo option for project discovery + +- **GIVEN** the current working directory is outside `<repo>` +- **AND** `<repo>/.specfact/modules/<module-name>` exists +- **WHEN** the user runs `specfact init --repo <repo> --profile <profile>` +- **THEN** init SHALL use `<repo>` when discovering project-scope modules for state refresh and prompt audits +- **AND** init SHALL NOT use an unrelated current working directory as the project module root + +#### Scenario: Init preserves disabled state for rediscovered modules + +- **GIVEN** `modules.json` marks a discovered module as disabled +- **WHEN** the user runs `specfact init --profile <profile>` +- **THEN** init SHALL preserve that module's disabled state unless the user explicitly enables it +- **AND** init SHALL report actionable re-enable guidance when the disabled module belongs to the selected profile + +#### Scenario: Init does not drop unrelated module state from another context + +- **GIVEN** `modules.json` contains a module row that is not visible from the current repository discovery context +- **WHEN** the user runs `specfact init --repo <repo> --profile <profile>` +- **THEN** init SHALL NOT delete or reset that unrelated row solely because it is absent from the current discovery view +- **AND** discovered rows for the selected repository SHALL still have current version and enabled metadata + +#### Scenario: Init profile install repairs installed-but-disabled profile module + +- **GIVEN** a profile-selected module artifact already exists +- **AND** lifecycle state marks that module as disabled +- **WHEN** the user runs `specfact init --profile <profile>` +- **THEN** init SHALL not leave the profile command group in a contradictory not-installed/already-installed state +- **AND** init SHALL either enable the profile-selected module or report the exact disabled-state recovery command + diff --git a/openspec/specs/installed-runtime-module-discovery/spec.md b/openspec/specs/installed-runtime-module-discovery/spec.md index bcddd642..8b0a273b 100644 --- a/openspec/specs/installed-runtime-module-discovery/spec.md +++ b/openspec/specs/installed-runtime-module-discovery/spec.md @@ -2,25 +2,29 @@ ## Purpose -TBD - created by archiving change backlog-core-04-installed-runtime-discovery-and-add-prompt. Update Purpose after archive. +This spec defines how installed SpecFact module packages are discovered and +loaded when no development checkout is available. It ensures runtime command +validation uses installed artifacts, reports missing dependencies honestly, and +keeps tests traceable to installed-runtime behavior. ## Requirements - ### Requirement: Module Discovery Roots -The system SHALL discover module packages consistently between development and installed runtime contexts when invoked from a repository checkout. +The system SHALL discover and load module packages consistently between development and installed runtime contexts. -#### Scenario: Installed runtime discovers workspace modules from repo root +#### Scenario: Installed runtime loads dependent module packages -- **GIVEN** `specfact` is installed from PyPI/site-packages -- **AND** the current working directory contains `modules/` with valid module packages -- **WHEN** module discovery runs -- **THEN** discovery includes the current working directory `modules/` root -- **AND** commands contributed by those modules are available without requiring `SPECFACT_MODULES_ROOTS`. +- **GIVEN** user-scope modules `nold-ai/specfact-project` and `nold-ai/specfact-codebase` are installed and enabled +- **AND** no sibling `specfact-cli-modules` source checkout contributes bundle paths to `sys.path` +- **WHEN** the user invokes `specfact code --help` +- **THEN** the codebase module command app loads from the installed module artifact +- **AND** imports of installed dependency packages such as `specfact_project` resolve without manual `PYTHONPATH` +- **AND** the command help includes codebase subcommands such as `import`, `analyze`, `drift`, `validate`, and `repro` -#### Scenario: No cwd modules directory keeps existing behavior +#### Scenario: Development source paths do not mask installed-runtime validation -- **GIVEN** the current working directory does not contain a `modules/` directory -- **WHEN** module discovery runs -- **THEN** discovery roots remain limited to packaged modules and explicitly configured roots -- **AND** no extra discovery errors are introduced. +- **GIVEN** tests configure explicit installed module roots +- **AND** development-only sibling module source paths are disabled for that runtime +- **WHEN** module command loading is validated +- **THEN** success depends on the installed module artifacts under the configured roots +- **AND** missing installed dependencies fail the validation instead of being satisfied by a sibling checkout diff --git a/openspec/specs/module-installation/spec.md b/openspec/specs/module-installation/spec.md index 9e647f46..76e88f8d 100644 --- a/openspec/specs/module-installation/spec.md +++ b/openspec/specs/module-installation/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change marketplace-01-central-module-registry. Update Purpose after archive. - ## Requirements - ### Requirement: Install command downloads and installs modules The system SHALL provide `specfact module install <module-id>` command that downloads, verifies, and installs modules from the registry. @@ -252,3 +250,95 @@ behaviour and the UX of standard package managers. - **THEN** the system SHALL report that A is not found - **AND** SHALL still attempt to uninstall B - **AND** SHALL exit non-zero if any module failed or was not found + +### Requirement: Install Reconciles Existing Module Availability + +When a user installs a module whose artifact already exists in the selected scope, the system SHALL reconcile the artifact with lifecycle state and runtime availability before reporting success. + +#### Scenario: Existing installed module is disabled + +- **GIVEN** a module artifact exists under the selected install scope +- **AND** the module state file marks the manifest module id as disabled +- **WHEN** the user runs `specfact module install <module-id>` +- **THEN** the command SHALL NOT report only that the module is already installed +- **AND** the command SHALL either enable that module for the user-requested install or print an explicit installed-but-disabled diagnostic with `specfact module enable <manifest-module-id>` + +#### Scenario: Existing installed module is skipped by runtime eligibility checks + +- **GIVEN** a module artifact exists under the selected install scope +- **AND** runtime registration would skip that module because of compatibility, dependency, schema, or integrity validation +- **WHEN** the user runs `specfact module install <module-id>` +- **THEN** the command SHALL report the specific local reason that the module is installed but unavailable +- **AND** the command SHALL include a recovery action such as reinstall, enable dependency modules, update SpecFact CLI, or inspect origins + +#### Scenario: Existing installed module is available + +- **GIVEN** a module artifact exists under the selected install scope +- **AND** lifecycle state and runtime eligibility allow its command group to register +- **WHEN** the user runs `specfact module install <module-id>` +- **THEN** the command MAY skip reinstalling the artifact +- **AND** the command SHALL report that the module is already installed and available from the selected scope + +### Requirement: Missing Command Diagnostics Explain Installed-Unavailable Causes + +When a known module-provided command group is not registered, the system SHALL distinguish an absent module from an installed module that is unavailable for another local reason. + +#### Scenario: Missing command is provided by disabled module + +- **GIVEN** a known command group is provided by a discovered module +- **AND** that module is disabled in lifecycle state +- **WHEN** the user invokes the command group +- **THEN** the CLI SHALL report that the module is installed but disabled +- **AND** the CLI SHALL include `specfact module enable <manifest-module-id>` guidance + +#### Scenario: Missing command is provided by skipped module + +- **GIVEN** a known command group is provided by a discovered module +- **AND** command registration skipped the module for compatibility, dependency, schema, or integrity reasons +- **WHEN** the user invokes the command group +- **THEN** the CLI SHALL report that the module is installed but unavailable +- **AND** the CLI SHALL include the specific skipped reason when it can be derived without importing the module command app + +#### Scenario: Missing command has no discovered provider + +- **GIVEN** no discovered module provider exists for a known command group +- **WHEN** the user invokes the command group +- **THEN** the CLI SHALL keep reporting that the module is not installed +- **AND** the CLI SHALL include install or init profile guidance + +### Requirement: Module install enforces versioned bundle dependencies + +The system SHALL validate versioned bundle dependency declarations during module installation. + +#### Scenario: Existing dependency version is too old + +- **GIVEN** a module being installed declares a bundle dependency with a version range +- **AND** that dependency already exists in the target install root with a version outside the range +- **WHEN** the user installs the dependent module +- **THEN** install fails before accepting the dependency set +- **AND** the error identifies the dependency id, required version range, and installed version + +#### Scenario: Newly installed dependency version is validated + +- **GIVEN** a module being installed declares a missing bundle dependency with a version range +- **WHEN** dependency installation completes +- **THEN** the installed dependency version is validated against the declared range +- **AND** install fails if the installed dependency still does not satisfy the range + +### Requirement: Module Install Uses Canonical Module Identity + +The system SHALL resolve install requests, discovered manifest IDs, and lifecycle state rows to a canonical module identity before deciding whether an install is already satisfied. + +#### Scenario: Bare name resolves to installed marketplace manifest id + +- **GIVEN** `~/.specfact/modules/specfact-codebase/module-package.yaml` declares `name: nold-ai/specfact-codebase` +- **WHEN** the user runs `specfact module install specfact-codebase` +- **THEN** the command SHALL treat `specfact-codebase` and `nold-ai/specfact-codebase` as the same installed module for lifecycle-state checks +- **AND** any state update or enable guidance SHALL use `nold-ai/specfact-codebase` + +#### Scenario: Legacy namespace request resolves to installed marketplace manifest id + +- **GIVEN** an installed module manifest declares `name: nold-ai/specfact-codebase` +- **WHEN** the user runs `specfact module install specfact/specfact-codebase` +- **THEN** the command SHALL NOT create or require a duplicate lifecycle state entry for `specfact/specfact-codebase` +- **AND** the command SHALL explain the canonical installed module identity if it skips installation diff --git a/openspec/specs/module-owned-ide-prompts/spec.md b/openspec/specs/module-owned-ide-prompts/spec.md index 7a33e6b5..709abf99 100644 --- a/openspec/specs/module-owned-ide-prompts/spec.md +++ b/openspec/specs/module-owned-ide-prompts/spec.md @@ -3,24 +3,17 @@ ## Purpose TBD - created by archiving change packaging-02-cross-platform-runtime-and-module-resources. Update Purpose after archive. - ## Requirements - ### Requirement: IDE prompt export SHALL use installed module resources `specfact init ide` SHALL discover prompt templates from installed module packages and their packaged resource directories. The export flow SHALL not depend on workflow prompt files stored under the core CLI package for bundle-owned commands. -#### Scenario: Installed bundle contributes prompt resources - -- **WHEN** an installed module exposes packaged prompt resources for IDE export -- **THEN** `specfact init ide` discovers that module's prompt directory from the installed module location -- **AND** copies the prompt files from that module-owned resource path into the selected IDE folder +#### Scenario: IDE setup accepts explicit environment manager -#### Scenario: Core package does not masquerade as owner of bundle prompts - -- **WHEN** workflow prompts exist only for bundle/module-owned commands -- **THEN** the export catalog excludes equivalent core-owned fallback prompt files -- **AND** prompt provenance remains attributable to the owning module +- **GIVEN** prompt templates are available for export +- **WHEN** the user runs `specfact init ide --env-manager uv` +- **THEN** IDE prompt export uses the selected `uv` environment manager metadata for dependency setup decisions +- **AND** the command does not emit the "No Compatible Environment Manager Detected" warning for that explicit manager ### Requirement: Missing prompt assets SHALL fail clearly @@ -53,3 +46,20 @@ When a setup or install flow needs a non-prompt resource that is owned by an ext - **WHEN** a required installed bundle resource path for a module-owned template is absent - **THEN** the CLI reports which bundle-owned asset is missing - **AND** the message directs the user toward installing or updating the owning bundle + +### Requirement: Core materialization of module-owned IDE assets SHALL use safe project writes + +When core setup flows materialize module-owned IDE assets into a user repository, they SHALL route all local file mutations through the core safe-write policy. + +#### Scenario: Module-owned prompt export uses safe-write helper for settings mutation + +- **WHEN** `specfact init ide` exports bundle-owned prompt files and updates a related IDE config artifact +- **THEN** the config mutation SHALL use the safe-write helper with declared ownership metadata +- **AND** the command SHALL preserve unrelated user-managed content in the target artifact + +#### Scenario: Module-owned template copy does not silently replace existing user customization + +- **WHEN** a core setup flow copies a module-owned template asset into a target path that already exists in the user repository +- **THEN** the flow SHALL skip, merge, or require explicit replacement according to the declared safe-write mode +- **AND** SHALL NOT silently overwrite the existing file + diff --git a/openspec/specs/module-packages/spec.md b/openspec/specs/module-packages/spec.md index 47e140b7..93d57f6d 100644 --- a/openspec/specs/module-packages/spec.md +++ b/openspec/specs/module-packages/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change arch-01-cli-modular-command-registry. Update Purpose after archive. - ## Requirements - ### Requirement: Logical Packages by Feature with Dedicated Folder Structure The CLI SHALL group functionality into **logical module packages** by feature (e.g. "backlog refine", "backlog daily", "validate sidecar"). Each package SHALL live in a dedicated folder under a modules root and SHALL include its own **metadata**, **src**, **resources** (prompts, templates), and **tests**. Resources that are used only by one feature SHALL belong to that package; shared resources remain in core or a shared package. @@ -244,3 +242,23 @@ The system SHALL extend module discovery to scan built-in, marketplace, and cust - **WHEN** module is registered - **THEN** registry SHALL persist source information - **AND** SHALL be queryable via module list command + +### Requirement: Module registration enforces versioned module dependencies + +The system SHALL skip registering an enabled module when its declared versioned module dependency is absent, disabled, or present at a version that does not satisfy the declared specifier. + +#### Scenario: Enabled dependency version is too old + +- **GIVEN** an enabled module declares a dependency on another module with a minimum version +- **AND** the dependency is enabled but its manifest version is below that minimum +- **WHEN** module package commands are registered +- **THEN** the dependent module is skipped +- **AND** diagnostics report the required version and the discovered version + +#### Scenario: Dependency version satisfies the declared range + +- **GIVEN** an enabled module declares a versioned module dependency +- **AND** the dependency is enabled and its version satisfies the declared range +- **WHEN** module package commands are registered +- **THEN** the dependent module remains eligible for registration + diff --git a/openspec/specs/module-scope-diagnostics/spec.md b/openspec/specs/module-scope-diagnostics/spec.md new file mode 100644 index 00000000..1a64af32 --- /dev/null +++ b/openspec/specs/module-scope-diagnostics/spec.md @@ -0,0 +1,28 @@ +# module-scope-diagnostics Specification + +## Purpose + +This spec defines diagnostics for effective, shadowed, and development-source +module copies across project and user scopes. It makes module precedence, +version ownership, and recovery guidance auditable without importing module +command code. + +## Requirements +### Requirement: Module doctor reports effective and shadowed module copies + +The system SHALL provide a `specfact module doctor` diagnostic that reports module origin, version, path, and shadowing state without importing module command code. + +#### Scenario: Duplicate project and user module copies are visible + +- **GIVEN** a module id exists in project scope and user scope with different versions +- **WHEN** the user runs `specfact module doctor <module-id>` +- **THEN** the output identifies the project copy as effective +- **AND** the output identifies the user copy as shadowed +- **AND** the output shows both versions and paths +- **AND** the output includes a recovery command for removing the stale user-scope copy + +#### Scenario: Development source roots are disclosed + +- **GIVEN** development source root environment variables are configured +- **WHEN** the user runs `specfact module doctor` +- **THEN** the output lists the configured development source roots that may influence import resolution diff --git a/openspec/specs/project-artifact-write-safety/spec.md b/openspec/specs/project-artifact-write-safety/spec.md new file mode 100644 index 00000000..3a4b40df --- /dev/null +++ b/openspec/specs/project-artifact-write-safety/spec.md @@ -0,0 +1,57 @@ +# project-artifact-write-safety Specification + +## Purpose + +This spec prevents data loss when SpecFact writes project artifacts in user +repositories. It defines ownership-aware write modes, validation, recovery +material, and failure behavior so requirements, tests, CI gates, and audits can +trace every artifact mutation back to an explicit safety contract. + +## Requirements +### Requirement: Core commands SHALL classify project artifact writes by ownership and mutation mode + +The system SHALL require core init/setup flows to declare whether a target artifact is create-only, mergeable, append-managed, or explicit-replace before writing into a user repository. + +#### Scenario: Partial-ownership artifact cannot use implicit full replacement + +- **WHEN** a core command targets a user-project artifact that SpecFact owns only partially +- **THEN** the command SHALL use a partial-ownership write mode such as structured merge or managed-block append +- **AND** SHALL NOT replace the full file implicitly + +#### Scenario: Unowned existing artifact fails safe + +- **WHEN** a core command would modify an existing artifact with no declared SpecFact-owned section or full-file ownership +- **THEN** the command SHALL stop with an actionable conflict message +- **AND** SHALL NOT mutate the artifact unless an explicit replacement mode is requested + +### Requirement: Lossy project artifact mutations SHALL create recovery material + +The system SHALL create backup and recovery metadata for any lossy local artifact mutation initiated by a core command. + +#### Scenario: Explicit replacement emits backup path + +- **WHEN** a core command performs an explicit replace of an existing project artifact +- **THEN** a backup copy SHALL be created in a SpecFact-managed recovery location before replacement +- **AND** the command output SHALL identify the backup path and original target + +#### Scenario: Failed structured merge leaves original file untouched + +- **WHEN** structured reconciliation cannot be completed safely +- **THEN** the original project artifact SHALL remain unchanged +- **AND** the command SHALL report why reconciliation failed and how to proceed safely + +### Requirement: CI SHALL detect unsafe core writes to user-project artifacts + +The repository SHALL enforce a CI or quality gate that flags unsafe write paths for user-project artifacts touched by core init/setup flows. + +#### Scenario: Raw overwrite path is rejected in CI + +- **WHEN** a core init/setup code path writes a protected user-project artifact without using the sanctioned safe-write helper +- **THEN** the quality gate SHALL fail +- **AND** the failure output SHALL identify the offending path or call site + +#### Scenario: Regression fixture preserves unrelated user configuration + +- **WHEN** CI runs regression fixtures for existing user-owned project configs +- **THEN** init/setup commands SHALL preserve unrelated user-managed content +- **AND** only declared SpecFact-managed sections or keys may change diff --git a/openspec/specs/runtime-tool-probing/spec.md b/openspec/specs/runtime-tool-probing/spec.md new file mode 100644 index 00000000..777bad7d --- /dev/null +++ b/openspec/specs/runtime-tool-probing/spec.md @@ -0,0 +1,31 @@ +# runtime-tool-probing Specification + +## Purpose +TBD - created by archiving change tester-cli-reliability. Update Purpose after archive. +## Requirements +### Requirement: Runtime Tool Probing Uses The Active Execution Context + +Tool and install-method diagnostics SHALL prefer the active execution context over stale package-manager inventories. + +#### Scenario: Upgrade launched through uv run is not classified as pipx + +- **GIVEN** a machine has a pipx-installed SpecFact CLI entry in global inventory +- **AND** the current invocation is launched through `uv run specfact upgrade` +- **WHEN** install-method detection runs +- **THEN** the effective method is reported as uv-run or uv project execution +- **AND** pipx-specific spaced-home warnings are not emitted for that invocation. + +#### Scenario: Semgrep available through uv is detected + +- **GIVEN** a project where `uv run semgrep --version` succeeds +- **WHEN** code analysis diagnostics check semgrep availability +- **THEN** semgrep is reported as available +- **AND** the diagnostic does not tell the user to install semgrep with a pip-only command. + +#### Scenario: Env-manager tool probe failures name the active manager + +- **GIVEN** a required external tool is not available in the active hatch or uv + environment-manager context +- **WHEN** a diagnostic is emitted +- **THEN** the message names the active manager context +- **AND** the installation hint matches that manager when a manager-specific hint is known. diff --git a/openspec/specs/upgrade-command/spec.md b/openspec/specs/upgrade-command/spec.md new file mode 100644 index 00000000..5430c70c --- /dev/null +++ b/openspec/specs/upgrade-command/spec.md @@ -0,0 +1,56 @@ +# upgrade-command Specification + +## Purpose + +This spec defines the `specfact upgrade` contract for detecting the active +installation method, running the appropriate package-manager upgrade, preserving +diagnostics, and repairing stale launchers so users can trust upgrade outcomes +across pip, pipx, uv, and uvx installs. + +## Requirements + +### Requirement: Upgrade command must respect installation method + +`specfact upgrade` SHALL detect whether SpecFact is installed via pip, pipx, uv, or uvx and present/execute an installation-method-appropriate upgrade command. When a pipx upgrade succeeds, the command SHALL suppress the known benign pipx warning block about spaces in `PIPX_HOME`. When a pipx upgrade fails, the command SHALL preserve child-process stdout and stderr diagnostics. When an upgrade times out after producing partial child-process output, the command SHALL replay the partial diagnostics before reporting the timeout. + +#### Scenario: Successful pipx upgrade suppresses spaced-home warning + +- **GIVEN** SpecFact detects a pipx installation +- **AND** `pipx upgrade specfact-cli` exits successfully +- **AND** pipx emits its warning block about a space in the pipx home path +- **WHEN** `specfact upgrade` runs the update +- **THEN** the user-visible output does not include the spaced-home warning block +- **AND** the upgrade still reports success. + +#### Scenario: Failed pipx upgrade preserves diagnostics + +- **GIVEN** SpecFact detects a pipx installation +- **AND** `pipx upgrade specfact-cli` exits with a non-zero status +- **AND** pipx emits stdout or stderr diagnostics +- **WHEN** `specfact upgrade` handles the failed update +- **THEN** the user-visible output includes the child-process diagnostics +- **AND** the upgrade reports failure. + +#### Scenario: Timed-out upgrade preserves partial diagnostics + +- **GIVEN** an installation-method-appropriate upgrade command starts +- **AND** the child process emits stdout or stderr diagnostics before exceeding the timeout +- **WHEN** `specfact upgrade` handles the timed-out update +- **THEN** the user-visible output includes the partial child-process diagnostics +- **AND** the upgrade reports the timeout. + +#### Scenario: Pipx upgrade validates and repairs stale launcher + +- **GIVEN** `specfact upgrade` is running from a pipx-managed installation +- **AND** `pipx upgrade specfact-cli` exits successfully +- **WHEN** the installed `specfact --version` launcher fails because it still + points at a stale or missing pipx venv path +- **THEN** the upgrader runs `pipx reinstall specfact-cli` +- **AND** it validates `specfact --version` again after the reinstall +- **AND** it suppresses the stale-launcher warning and reports success when the + reinstall repairs the launcher +- **AND** it preserves and surfaces child-process stdout and stderr diagnostics + from `pipx reinstall specfact-cli` when reinstall fails +- **AND** it replays any partial reinstall output produced before a timeout +- **AND** it reports failure if reinstall fails, times out, or the launcher still + cannot execute after reinstall. diff --git a/openspec/specs/user-module-root/spec.md b/openspec/specs/user-module-root/spec.md index cd548ca9..93b4fd6b 100644 --- a/openspec/specs/user-module-root/spec.md +++ b/openspec/specs/user-module-root/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change backlog-core-05-user-modules-bootstrap. Update Purpose after archive. - ## Requirements - ### Requirement: Canonical User Module Root The system SHALL use a canonical per-user module root at `<user-home>/.specfact/modules` for installed module artifacts and discovery. @@ -284,3 +282,31 @@ Bundled module release tooling SHALL support module-level versioning independent - **WHEN** module signing/version checks run - **THEN** bundled module version does not need to change - **AND** module versioning is enforced only by module payload change semantics. + +### Requirement: Scope Diagnostics Preserve Deterministic Precedence + +The system SHALL preserve project-before-user module precedence while making scope-related availability decisions explicit when they affect install or command availability. + +#### Scenario: Project module shadows user module during install check + +- **GIVEN** `<repo>/.specfact/modules/<module-id>` exists +- **AND** `<user-home>/.specfact/modules/<module-id>` exists +- **WHEN** the user runs `specfact module install <module-id> --scope user` from within `<repo>` +- **THEN** the command SHALL decide whether user-scope installation is satisfied using the user-scope target root +- **AND** the command SHALL warn if runtime command behavior in the current repository is still governed by the project-scope copy + +#### Scenario: Project module shadows user module during missing command diagnostic + +- **GIVEN** a project-scope module copy shadows a user-scope module copy with the same manifest id +- **AND** the active project-scope copy is disabled or skipped +- **WHEN** the user invokes a command group provided by that module +- **THEN** the CLI SHALL identify the active project-scope origin as the source that controls command availability +- **AND** the CLI SHALL mention that a user-scope copy exists but is shadowed in the current repository + +#### Scenario: User module remains available outside project scope + +- **GIVEN** a user-scope module is installed and enabled +- **AND** no project-scope copy exists in the current repository root +- **WHEN** module discovery runs from that repository +- **THEN** command availability SHALL be based on the user-scope module +- **AND** install diagnostics SHALL NOT imply that a project-scope module is required