diff --git a/.claude/skills/openspec-workflows/SKILL.md b/.claude/skills/openspec-workflows/SKILL.md index 08937fbc..172ac79a 100644 --- a/.claude/skills/openspec-workflows/SKILL.md +++ b/.claude/skills/openspec-workflows/SKILL.md @@ -2,7 +2,6 @@ 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 -compatibility: Requires openspec CLI and gh CLI. metadata: author: openspec version: "1.0" diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 511aaf31..ee036f49 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -29,6 +29,15 @@ Changes are grouped by **module** and prefixed with **`-NN-`** so implem All entries in the table below are pending implementation. +## Plan-derived addendum (2026-02-15 architecture integration plan) + +The source plan inventory listed 17 new changes. Two additional cross-cutting changes were intentionally added during proposal creation to close integration governance and proof gaps discovered in dependency review: + +- `integration-01-cross-change-contracts`: owns cross-change interface ownership, compatibility constraints, and wave gate criteria. +- `dogfooding-01-full-chain-e2e-proof`: defines reproducible end-to-end evidence for running the full chain on real SpecFact backlog slices. + +These are derived extensions of the same 2026-02-15 plan and are required to operationalize the plan's end-to-end positioning rather than optional scope expansion. + --- ## Module groups and change folders @@ -90,6 +99,60 @@ All entries in the table below are pending implementation. |--------|-------|---------------|----------|------------| | ceremony-cockpit | 01 | ceremony-cockpit-01-ceremony-aliases | [#185](https://github.com/nold-ai/specfact-cli/issues/185) | — (optional: #220, #170, #171, #169, #183, #184) | +### Profile and configuration layering (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| profile | 01 | profile-01-config-layering | [#237](https://github.com/nold-ai/specfact-cli/issues/237) | #193 (existing init/module-state baseline) | +| profile | 02 | profile-02-central-config-sources | [#249](https://github.com/nold-ai/specfact-cli/issues/249) | profile-01 | +| profile | 03 | profile-03-domain-overlays | [#250](https://github.com/nold-ai/specfact-cli/issues/250) | profile-01, profile-02, #213 | + +### Requirements layer (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| requirements | 01 | requirements-01-data-model | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | #213 | +| requirements | 02 | requirements-02-module-commands | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | requirements-01, #213 | +| requirements | 03 | requirements-03-backlog-sync | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | requirements-02, sync-01 | + +### Architecture and traceability chain (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| architecture | 01 | architecture-01-solution-layer | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | requirements-01, requirements-02 | +| validation | 02 | validation-02-full-chain-engine | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | requirements-02, architecture-01, #176 | +| traceability | 01 | traceability-01-index-and-orphans | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | requirements-02, architecture-01 | + +### Sync and ceremony integration (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| sync | 01 | sync-01-unified-kernel | [#243](https://github.com/nold-ai/specfact-cli/issues/243) | #177 | +| ceremony | 02 | ceremony-02-requirements-aware-output | [#245](https://github.com/nold-ai/specfact-cli/issues/245) | requirements-02, #185 | + +### Governance extensions (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| policy | 02 | policy-02-packs-and-modes | [#246](https://github.com/nold-ai/specfact-cli/issues/246) | profile-01, #176 | +| governance | 01 | governance-01-evidence-output | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | validation-02, policy-02 | +| governance | 02 | governance-02-exception-management | [#248](https://github.com/nold-ai/specfact-cli/issues/248) | policy-02 | + +### AI integration (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| ai-integration | 01 | ai-integration-01-agent-skill | [#251](https://github.com/nold-ai/specfact-cli/issues/251) | validation-02 | +| ai-integration | 02 | ai-integration-02-mcp-server | [#252](https://github.com/nold-ai/specfact-cli/issues/252) | validation-02 | +| ai-integration | 03 | ai-integration-03-instruction-files | [#253](https://github.com/nold-ai/specfact-cli/issues/253) | ai-integration-01 | + +### Integration governance and proof (architecture integration plan, 2026-02-15) + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| integration | 01 | integration-01-cross-change-contracts | [#254](https://github.com/nold-ai/specfact-cli/issues/254) | profile-01, requirements-02, architecture-01, validation-02, policy-02 | +| dogfooding | 01 | 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 | + --- ## GitHub "Blocked by" relationships @@ -109,11 +172,49 @@ Set these in GitHub so issue dependencies are explicit. Optional dependencies ar | [#183](https://github.com/nold-ai/specfact-cli/issues/183) | backlog-kanban-01 flow metrics | #116 | | [#184](https://github.com/nold-ai/specfact-cli/issues/184) | backlog-safe-01 PI planning | #116 | | [#182](https://github.com/nold-ai/specfact-cli/issues/182) | backlog-safe-02 risk rollups | #184 | +| [#237](https://github.com/nold-ai/specfact-cli/issues/237) | profile-01 config layering | #193 | +| [#249](https://github.com/nold-ai/specfact-cli/issues/249) | profile-02 central config sources | #237 | +| [#250](https://github.com/nold-ai/specfact-cli/issues/250) | profile-03 domain overlays | #237, #249, #213 | +| [#238](https://github.com/nold-ai/specfact-cli/issues/238) | requirements-01 data model | #213 | +| [#239](https://github.com/nold-ai/specfact-cli/issues/239) | requirements-02 module commands | #238, #213 | +| [#244](https://github.com/nold-ai/specfact-cli/issues/244) | requirements-03 backlog sync | #239, #243 | +| [#240](https://github.com/nold-ai/specfact-cli/issues/240) | architecture-01 solution layer | #238, #239 | +| [#241](https://github.com/nold-ai/specfact-cli/issues/241) | validation-02 full-chain engine | #239, #240, #176 | +| [#242](https://github.com/nold-ai/specfact-cli/issues/242) | traceability-01 index and orphans | #239, #240 | +| [#243](https://github.com/nold-ai/specfact-cli/issues/243) | sync-01 unified kernel | #177 | +| [#245](https://github.com/nold-ai/specfact-cli/issues/245) | ceremony-02 requirements-aware output | #239, #185 | +| [#246](https://github.com/nold-ai/specfact-cli/issues/246) | policy-02 packs and modes | #237, #176 | +| [#247](https://github.com/nold-ai/specfact-cli/issues/247) | governance-01 evidence output | #241, #246 | +| [#248](https://github.com/nold-ai/specfact-cli/issues/248) | governance-02 exception management | #246 | +| [#251](https://github.com/nold-ai/specfact-cli/issues/251) | ai-integration-01 agent skill | #241 | +| [#252](https://github.com/nold-ai/specfact-cli/issues/252) | ai-integration-02 mcp server | #241 | +| [#253](https://github.com/nold-ai/specfact-cli/issues/253) | ai-integration-03 instruction files | #251 | +| [#254](https://github.com/nold-ai/specfact-cli/issues/254) | integration-01 cross-change contracts | #237, #239, #240, #241, #246 | +| [#255](https://github.com/nold-ai/specfact-cli/issues/255) | dogfooding-01 full-chain e2e proof | #239, #240, #241, #242, #247 | **How to set in GitHub**: Open the issue → right sidebar **Relationships** → **Mark as blocked by** → search and select the blocking issue(s). --- +## Ownership Authority (Cross-Change) + +The following ownership boundaries are mandatory before implementation for overlapping files/interfaces. + +| Owned surface | Authoritative change | Dependent changes | +|---|---|---| +| Policy mode execution semantics and per-rule mode handling | `policy-02-packs-and-modes` | `governance-01-evidence-output`, `governance-02-exception-management` | +| Evidence JSON envelope and CI verdict schema | `governance-01-evidence-output` | `validation-02-full-chain-engine`, `governance-02-exception-management`, `dogfooding-01-full-chain-e2e-proof` | +| Exception scope suppression logic and expiry behavior | `governance-02-exception-management` | `policy-02-packs-and-modes`, `governance-01-evidence-output` | +| Base requirements schema model (`src/specfact_cli/models/requirements.py`) | `requirements-01-data-model` | `profile-03-domain-overlays`, `requirements-02-module-commands` | +| Architecture namespace extension on `ProjectBundle` (`src/specfact_cli/models/project.py`) | `architecture-01-solution-layer` | `validation-02-full-chain-engine`, `traceability-01-index-and-orphans` | +| Requirements namespace extension on `ProjectBundle` (`src/specfact_cli/models/project.py`) | `requirements-01-data-model` | `requirements-02-module-commands`, `requirements-03-backlog-sync`, `architecture-01-solution-layer` | +| Backlog requirements extraction/update adapter contract (`modules/backlog/src/adapters/`) | `requirements-02-module-commands` | `requirements-03-backlog-sync` | + +Pre-implementation rule: +- No dependent change may redefine an owned surface. Any required semantic change must be proposed as a delta to the authoritative change first. + +--- + ## Parent issues (Epics) per module group One parent issue per module group for grouping. Set **Type** to Epic on the project board. Link child/change issues via **Relationships** (sub-issues or "tracks") or by setting the project **Parent** field to the epic. @@ -157,3 +258,49 @@ Dependencies flow left-to-right; a wave may start once all its hard blockers are - **Wave 4 — Ceremony layer** (needs Wave 3): - ceremony-cockpit-01 (probes installed backlog-* modules at runtime; no hard deps but best after Wave 3) + +- **Wave 5 — Foundations for business-first chain** (architecture integration): + - profile-01 + - requirements-01 + - requirements-02 (after requirements-01 + arch-07) + +- **Wave 6 — End-to-end chain and sync kernel**: + - architecture-01 (after requirements-01 + requirements-02) + - validation-02 (after architecture-01 + requirements-02 + policy-engine-01) + - traceability-01 (after architecture-01 + requirements-02) + - sync-01 (after patch-mode-01) + - requirements-03 (after requirements-02 + sync-01) + +- **Wave 7 — Governance and ceremony business context**: + - policy-02 (after profile-01 + policy-engine-01) + - governance-01 (after validation-02 + policy-02) + - governance-02 (after policy-02) + - ceremony-02 (after requirements-02 + ceremony-cockpit-01) + +- **Wave 8 — Enterprise profile maturity and AI interfaces**: + - profile-02 (after profile-01) + - profile-03 (after profile-01 + profile-02 + arch-07) + - ai-integration-01 (after validation-02) + - ai-integration-02 (after validation-02) + - ai-integration-03 (after ai-integration-01) + +- **Wave 9 — Integration contract and product proof**: + - integration-01 (after profile-01 + requirements-02 + architecture-01 + validation-02 + policy-02) + - dogfooding-01 (after requirements-02 + architecture-01 + validation-02 + traceability-01 + governance-01) + +--- + +## Mandatory Wave Exit Gates + +A wave cannot be considered complete until all gate criteria listed for that wave are met and auditable. + +- Wave 0 gate: Core modular CLI and bridge registry flows remain stable and archived changes are validated. +- Wave 1 gate: arch-06/07, policy-engine-01, patch-mode-01, backlog-core-01, validation-01 produce passing contract and strict OpenSpec validation. +- Wave 2 gate: At least one backlog planning workflow completes with no blocking dependency regressions across backlog-core + marketplace-01. +- Wave 3 gate: Higher-order backlog workflows and marketplace-02 interoperate without command-group regressions. +- Wave 4 gate: `ceremony-cockpit-01` aliases resolve and execute against installed modules without fallback failures. +- Wave 5 gate: `profile-01`, `requirements-01`, `requirements-02` demonstrate profile-aware requirement lifecycle with strict validation and TDD evidence. +- Wave 6 gate: One chain run proves requirements -> architecture -> validation/traceability/sync compatibility with no unresolved ownership conflicts. +- Wave 7 gate: policy/governance/ceremony integration emits consistent evidence and exception semantics aligned to ownership authority. +- Wave 8 gate: profile maturity + AI interfaces (`ai-integration-01/02/03`) operate on top of validation-02 outputs with no schema divergence. +- Wave 9 gate: integration umbrella contract is adopted by all dependent changes and dogfooding E2E proof artifacts confirm end-to-end positioning claims. diff --git a/openspec/changes/ai-integration-01-agent-skill/.openspec.yaml b/openspec/changes/ai-integration-01-agent-skill/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/ai-integration-01-agent-skill/CHANGE_VALIDATION.md b/openspec/changes/ai-integration-01-agent-skill/CHANGE_VALIDATION.md new file mode 100644 index 00000000..3af291b1 --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: ai-integration-01-agent-skill + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate ai-integration-01-agent-skill --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** agent-skill-spec-intelligence +- **Modified capabilities:** (none) +- **Declared dependencies:** validation-02 (full-chain validation as the engine behind skill invocations) +- **Proposed affected code paths:** - `skills/specfact/` (new skill directory);- `skills/specfact-assess-pr/` (new sub-skill) - `skills/specfact-check-architecture/` (new sub-skill);- `skills/specfact-coverage/` (new sub-skill) - `modules/ide/` (new module for `specfact ide skill install`) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/ai-integration-01-agent-skill/design.md b/openspec/changes/ai-integration-01-agent-skill/design.md new file mode 100644 index 00000000..a24a132e --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/design.md @@ -0,0 +1,40 @@ +## 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. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on 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 new file mode 100644 index 00000000..d8928d0d --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/proposal.md @@ -0,0 +1,49 @@ +# Change: Agent Skill for Spec Intelligence (Skills-First Interface) + +## 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. + +## 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 + +## 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. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #251 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/ai-integration-01-agent-skill/specs/agent-skill-spec-intelligence/spec.md b/openspec/changes/ai-integration-01-agent-skill/specs/agent-skill-spec-intelligence/spec.md new file mode 100644 index 00000000..e6982830 --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/specs/agent-skill-spec-intelligence/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Agent Skill Spec Intelligence +The system SHALL provide a skill-first integration that directs AI agents to SpecFact workflows with low context overhead. + +#### Scenario: Skill instructs agent to run deterministic CLI checks +- **GIVEN** skill is activated for PR or change analysis +- **WHEN** agent follows skill guidance +- **THEN** agent invokes commands such as `specfact validate`, `specfact trace show`, and `specfact requirements list` +- **AND** output references evidence paths instead of embedding large raw artifacts. + +#### Scenario: Skill content remains lightweight at rest +- **GIVEN** skill metadata is loaded by an IDE agent +- **WHEN** idle context is measured +- **THEN** base skill content remains compact +- **AND** detailed guidance is loaded only on activation. diff --git a/openspec/changes/ai-integration-01-agent-skill/tasks.md b/openspec/changes/ai-integration-01-agent-skill/tasks.md new file mode 100644 index 00000000..362fcd43 --- /dev/null +++ b/openspec/changes/ai-integration-01-agent-skill/tasks.md @@ -0,0 +1,30 @@ +# Tasks: ai-integration-01-agent-skill + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/ai-integration-01-agent-skill` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate ai-integration-01-agent-skill --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/ai-integration-01-agent-skill` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/ai-integration-02-mcp-server/.openspec.yaml b/openspec/changes/ai-integration-02-mcp-server/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/ai-integration-02-mcp-server/CHANGE_VALIDATION.md b/openspec/changes/ai-integration-02-mcp-server/CHANGE_VALIDATION.md new file mode 100644 index 00000000..19582129 --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: ai-integration-02-mcp-server + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate ai-integration-02-mcp-server --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** mcp-server +- **Modified capabilities:** (none) +- **Declared dependencies:** validation-02 (full-chain validation engine) +- **Proposed affected code paths:** - `src/specfact_cli/mcp/` (new — MCP server implementation);- `src/specfact_cli/mcp/tools/` (new — tool handlers) - `src/specfact_cli/mcp/transport/` (new — stdio + HTTP/SSE transport) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/ai-integration-02-mcp-server/design.md b/openspec/changes/ai-integration-02-mcp-server/design.md new file mode 100644 index 00000000..bbc17068 --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/design.md @@ -0,0 +1,40 @@ +## 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. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on 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 new file mode 100644 index 00000000..4ec70f7a --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/proposal.md @@ -0,0 +1,46 @@ +# Change: MCP Server — Programmatic Tool Interface for Agentic Workflows + +## 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. + +## 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 + +## 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. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #252 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/ai-integration-02-mcp-server/specs/mcp-server/spec.md b/openspec/changes/ai-integration-02-mcp-server/specs/mcp-server/spec.md new file mode 100644 index 00000000..4161b6a2 --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/specs/mcp-server/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Mcp Server +The system SHALL expose a bounded set of high-value MCP tools for validation, compatibility, coverage, and fix guidance. + +#### Scenario: MCP tool returns summarized result with reference +- **GIVEN** a validation MCP tool invocation +- **WHEN** execution completes +- **THEN** response returns concise summary metrics +- **AND** includes a link or path to the full report artifact. + +#### Scenario: Tool surface remains intentionally small +- **GIVEN** MCP server configuration +- **WHEN** server starts +- **THEN** only approved core tools are exposed +- **AND** raw bulk document dumping is not the default response behavior. diff --git a/openspec/changes/ai-integration-02-mcp-server/tasks.md b/openspec/changes/ai-integration-02-mcp-server/tasks.md new file mode 100644 index 00000000..bfd68d73 --- /dev/null +++ b/openspec/changes/ai-integration-02-mcp-server/tasks.md @@ -0,0 +1,30 @@ +# Tasks: ai-integration-02-mcp-server + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/ai-integration-02-mcp-server` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate ai-integration-02-mcp-server --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/ai-integration-02-mcp-server` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/ai-integration-03-instruction-files/.openspec.yaml b/openspec/changes/ai-integration-03-instruction-files/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/ai-integration-03-instruction-files/CHANGE_VALIDATION.md b/openspec/changes/ai-integration-03-instruction-files/CHANGE_VALIDATION.md new file mode 100644 index 00000000..42102ccd --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: ai-integration-03-instruction-files + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate ai-integration-03-instruction-files --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** cross-platform-instructions +- **Modified capabilities:** (none) +- **Declared dependencies:** ai-integration-01 (Agent Skill — instruction files reference skill content) +- **Proposed affected code paths:** - `modules/ide/src/` (extend with instruction file generation);- Instruction template files + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/ai-integration-03-instruction-files/design.md b/openspec/changes/ai-integration-03-instruction-files/design.md new file mode 100644 index 00000000..db5065f6 --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `ai-integration-03-instruction-files` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on ai-integration-01-agent-skill. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/ai-integration-03-instruction-files/proposal.md b/openspec/changes/ai-integration-03-instruction-files/proposal.md new file mode 100644 index 00000000..8a63b7a1 --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/proposal.md @@ -0,0 +1,47 @@ +# Change: Cross-Platform AI IDE Instruction Files + +## 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. + +## 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 + +## 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. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #253 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/ai-integration-03-instruction-files/specs/cross-platform-instructions/spec.md b/openspec/changes/ai-integration-03-instruction-files/specs/cross-platform-instructions/spec.md new file mode 100644 index 00000000..5ce56063 --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/specs/cross-platform-instructions/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Cross Platform Instructions +The system SHALL generate platform-specific instruction files that reference the canonical SpecFact skill behavior. + +#### Scenario: Multi-platform setup command writes instruction files +- **GIVEN** `specfact ide setup --platforms cursor,copilot,claude,windsurf` +- **WHEN** setup runs +- **THEN** platform instruction files are generated in expected locations +- **AND** each file references the same canonical SpecFact workflow entry points. + +#### Scenario: Regeneration is idempotent +- **GIVEN** instruction files already exist +- **WHEN** setup is re-run without behavior changes +- **THEN** files are updated deterministically +- **AND** no duplicate instruction blocks are introduced. diff --git a/openspec/changes/ai-integration-03-instruction-files/tasks.md b/openspec/changes/ai-integration-03-instruction-files/tasks.md new file mode 100644 index 00000000..2469793a --- /dev/null +++ b/openspec/changes/ai-integration-03-instruction-files/tasks.md @@ -0,0 +1,30 @@ +# Tasks: ai-integration-03-instruction-files + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/ai-integration-03-instruction-files` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate ai-integration-03-instruction-files --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/ai-integration-03-instruction-files` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/architecture-01-solution-layer/.openspec.yaml b/openspec/changes/architecture-01-solution-layer/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md b/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md new file mode 100644 index 00000000..5da24ace --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: architecture-01-solution-layer + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate architecture-01-solution-layer --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** solution-architecture +- **Modified capabilities:** data-models +- **Declared dependencies:** requirements-01 (data model), requirements-02 (module commands), arch-07 (#213) +- **Proposed affected code paths:** - `modules/architecture/` (new module);- `src/specfact_cli/models/project.py` (extend via arch-07 schema extensions) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/architecture-01-solution-layer/design.md b/openspec/changes/architecture-01-solution-layer/design.md new file mode 100644 index 00000000..8ed9ce20 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `architecture-01-solution-layer` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-01-data-model and requirements-02-module-commands. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/architecture-01-solution-layer/proposal.md b/openspec/changes/architecture-01-solution-layer/proposal.md new file mode 100644 index 00000000..9ff6dc13 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/proposal.md @@ -0,0 +1,114 @@ +# Change: Solution Architecture Layer — Derive, Store, Validate + +## 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. + +## 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 + +## 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 + +## 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`) + +## 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. + +### Modified Capabilities + +- `data-models`: ProjectBundle extended with architecture field via arch-07 schema extensions + + +--- + +## Source Tracking + + +- **GitHub Issue**: #240 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md b/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md new file mode 100644 index 00000000..e874f6ce --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Data Models +The system SHALL extend project-level models with an architecture namespace linked to requirements. + +#### Scenario: Architecture model references requirement IDs +- **GIVEN** a solution architecture artifact +- **WHEN** model validation runs +- **THEN** each architecture document includes requirement identifiers +- **AND** referenced IDs preserve stable cross-layer linkage. + +#### Scenario: Architecture namespace remains optional for backward compatibility +- **GIVEN** older bundles without architecture data +- **WHEN** bundle parsing runs +- **THEN** parsing succeeds +- **AND** architecture validators only run when architecture data is present. diff --git a/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md b/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md new file mode 100644 index 00000000..c8bd9252 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Solution Architecture +The system SHALL provide architecture derive, coverage validation, and trace outputs linked to requirements. + +#### Scenario: Derive architecture from requirements +- **GIVEN** `specfact architecture derive --requirements .specfact/requirements/ --interactive` +- **WHEN** derive completes +- **THEN** an `.arch.yaml` artifact is created +- **AND** components and ADR entries reference requirement rules. + +#### Scenario: Validate architecture coverage +- **GIVEN** requirements and architecture artifacts exist +- **WHEN** `specfact architecture validate-coverage` runs +- **THEN** unmapped business rules are reported +- **AND** missing ADRs for architectural constraints are reported. + +#### Scenario: Trace command exports architecture linkage +- **GIVEN** architecture and requirements data +- **WHEN** `specfact architecture trace --format json` runs +- **THEN** output includes requirement-to-component-to-ADR mappings +- **AND** output is consumable by full-chain validation. diff --git a/openspec/changes/architecture-01-solution-layer/tasks.md b/openspec/changes/architecture-01-solution-layer/tasks.md new file mode 100644 index 00000000..35b082a1 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/tasks.md @@ -0,0 +1,30 @@ +# Tasks: architecture-01-solution-layer + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/architecture-01-solution-layer` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate architecture-01-solution-layer --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/architecture-01-solution-layer` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml b/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md b/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md new file mode 100644 index 00000000..d5dac549 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: ceremony-02-requirements-aware-output + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate ceremony-02-requirements-aware-output --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** ceremony-requirements-awareness +- **Modified capabilities:** backlog-refinement,daily-standup +- **Declared dependencies:** requirements-02 (requirements module), ceremony-cockpit-01 (#185, ceremony aliases) +- **Proposed affected code paths:** - `modules/ceremony-cockpit/src/` (extend ceremony commands with requirements flag);- Requirements module integration hooks - Ceremony cockpit command handlers + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/design.md b/openspec/changes/ceremony-02-requirements-aware-output/design.md new file mode 100644 index 00000000..199658da --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `ceremony-02-requirements-aware-output` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and ceremony-cockpit-01-ceremony-aliases. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/proposal.md b/openspec/changes/ceremony-02-requirements-aware-output/proposal.md new file mode 100644 index 00000000..d9da0450 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/proposal.md @@ -0,0 +1,51 @@ +# Change: Ceremony Integration — Requirements-Aware Ceremony Output + +## Why + + + + +Current backlog ceremony commands (`backlog ceremony refinement`, `backlog ceremony standup`, `backlog ceremony planning`) operate purely on technical signals — story points, acceptance criteria quality, spec coverage. They don't surface business requirement coverage, value gaps, or architectural readiness. This means ceremonies miss the most impactful signals: "Is the business case defined?" and "Does the architecture support this?" Extending ceremony output with a `--with-requirements` flag enriches refinement and planning with business context, catching value gaps before they become code. + +## What Changes + + + + +- **EXTEND**: `specfact backlog ceremony refinement` extended with `--with-requirements` flag: + - Show per-story business requirement status (defined/missing/incomplete) + - Flag stories missing business value quantification + - Flag stories with requirements but no solution architecture + - Detect orphaned specs (spec exists but no business requirement) + - Recommendation engine: "Defer until business case clarified" for value-undefined stories +- **EXTEND**: `specfact backlog ceremony planning` extended with `--with-requirements` flag: + - Sprint readiness assessment: business value coverage percentage + - Risk items: stories entering sprint without full traceability chain + - Capacity allocation by business outcome (not just story points) +- **EXTEND**: `specfact backlog ceremony standup` extended with `--with-requirements` flag: + - Yesterday/today items annotated with business requirement they serve + - Blockers annotated with impacted business outcomes +- **NEW**: Ceremony output sections: "Business Value Coverage", "Business Risk Items", "Ready for Sprint" with profile-aware detail level (solo gets summary only, enterprise gets full breakdown) +- **EXTEND**: Ceremony cockpit (ceremony-cockpit-01) integration — requirements-aware output available through all ceremony aliases + +## Capabilities +### New Capabilities + +- `ceremony-requirements-awareness`: Requirements-aware enrichment for backlog ceremony commands (`backlog ceremony refinement`, `backlog ceremony planning`, `backlog ceremony standup`) showing business value coverage, risk items, orphaned specs, and sprint readiness with profile-aware detail levels. + +### Modified Capabilities + +- `backlog-refinement`: Extended with `--with-requirements` flag for business context enrichment +- `daily-standup`: Extended with `--with-requirements` flag for business outcome annotations + + +--- + +## Source Tracking + + +- **GitHub Issue**: #245 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md new file mode 100644 index 00000000..16145c9e --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Backlog Refinement +Backlog refinement output SHALL support requirements-aware enrichment. + +#### Scenario: Requirements-aware refinement highlights business value gaps +- **GIVEN** refinement is run with requirements-aware mode enabled +- **WHEN** stories missing quantified business value are present +- **THEN** output lists those stories as business-value gaps +- **AND** recommendations prioritize requirement completion before implementation. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md new file mode 100644 index 00000000..75eb41d4 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Ceremony Requirements Awareness +The system SHALL enrich ceremony outputs with requirement, architecture, and traceability readiness signals. + +#### Scenario: Refinement output includes chain-readiness summary +- **GIVEN** `specfact backlog ceremony refinement --with-requirements` +- **WHEN** command runs +- **THEN** output includes counts for stories with requirements, missing business value, missing architecture, and orphan specs +- **AND** each count links to affected backlog item IDs. + +#### Scenario: Ready-for-sprint signal requires chain prerequisites +- **GIVEN** a story has requirement and architecture artifacts but no code +- **WHEN** ceremony readiness is computed +- **THEN** story can be marked ready-for-implementation +- **AND** missing requirement or architecture links prevent ready status. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md new file mode 100644 index 00000000..bc8c566f --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Daily Standup +Daily standup output SHALL include requirement and architecture blockers when present. + +#### Scenario: Standup reports upstream blockers before technical tasks +- **GIVEN** tasks are blocked by missing requirement or architecture decisions +- **WHEN** standup summary is generated +- **THEN** blockers are listed under a business/architecture blocker section +- **AND** unresolved upstream blockers are prioritized above downstream code tasks. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/tasks.md b/openspec/changes/ceremony-02-requirements-aware-output/tasks.md new file mode 100644 index 00000000..807fc824 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/tasks.md @@ -0,0 +1,30 @@ +# Tasks: ceremony-02-requirements-aware-output + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/ceremony-02-requirements-aware-output` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate ceremony-02-requirements-aware-output --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/ceremony-02-requirements-aware-output` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/.openspec.yaml b/openspec/changes/dogfooding-01-full-chain-e2e-proof/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/CHANGE_VALIDATION.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/CHANGE_VALIDATION.md new file mode 100644 index 00000000..964c79b6 --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/CHANGE_VALIDATION.md @@ -0,0 +1,16 @@ +# Change Validation: dogfooding-01-full-chain-e2e-proof + +- **Validated on (UTC):** 2026-02-15T00:00:00Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate dogfooding-01-full-chain-e2e-proof --strict` +- **Result:** PASS + +## Scope Summary + +- New capability: `dogfooding-full-chain-e2e` +- Focus: reproducible E2E evidence for product-positioning claims + +## Validation Outcome + +- Required artifacts are present. +- Proposal is implementation-ready after dependency confirmation. diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md new file mode 100644 index 00000000..4520a12c --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/design.md @@ -0,0 +1,35 @@ +## Context + +This change defines an auditable dogfooding path proving the complete business-to-code traceability chain for SpecFact CLI itself. + +## Goals / Non-Goals + +**Goals:** +- Produce objective E2E proof artifacts for the full-chain claim. +- Ensure proof is reproducible in CI and local workflows. +- Tie proof to release readiness and product positioning. + +**Non-Goals:** +- No unrelated feature expansion. +- No synthetic-only demo path; evidence must use real project artifacts. + +## 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. + +## 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. + +## Migration Plan + +1. Select dogfooding slice and map initial requirements. +2. Implement tests and fail-first evidence. +3. Produce end-to-end evidence artifacts and docs updates. + +## Open Questions + +- Which backlog 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 new file mode 100644 index 00000000..0a838316 --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/proposal.md @@ -0,0 +1,40 @@ +# Change: Dogfooding E2E Proof for Full-Chain Traceability + +## 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. + +## 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 +- **NEW**: Define release-readiness proof criteria for end-to-end positioning claims +- **NEW**: Add CI/report outputs proving wave gate completion for E2E chain + +## 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. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #255 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/specs/dogfooding-full-chain-e2e/spec.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/specs/dogfooding-full-chain-e2e/spec.md new file mode 100644 index 00000000..cee2e33f --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/specs/dogfooding-full-chain-e2e/spec.md @@ -0,0 +1,17 @@ +## ADDED Requirements + +### Requirement: End-to-End Dogfooding Proof +The system SHALL provide a reproducible dogfooding workflow that proves full-chain traceability from backlog to CI evidence. + +#### Scenario: Full chain proof is generated for a real backlog slice +- **WHEN** dogfooding workflow runs for selected SpecFact backlog items +- **THEN** each item is traceable through requirement, architecture, spec, code/test, and evidence outputs +- **AND** missing links are reported as gate failures + +### Requirement: Dogfooding Evidence Is CI-Consumable +The system SHALL produce machine-readable evidence artifacts for the dogfooding run. + +#### Scenario: CI validates dogfooding proof +- **WHEN** CI executes the dogfooding full-chain run +- **THEN** evidence artifacts are emitted in a stable schema +- **AND** wave gate status is derivable from those artifacts diff --git a/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md b/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md new file mode 100644 index 00000000..6d4f4910 --- /dev/null +++ b/openspec/changes/dogfooding-01-full-chain-e2e-proof/tasks.md @@ -0,0 +1,25 @@ +# Tasks: dogfooding-01-full-chain-e2e-proof + +## 1. Branch and dataset setup + +- [ ] 1.1 Create branch `feature/dogfooding-01-full-chain-e2e-proof` from `dev`. +- [ ] 1.2 Select and document the canonical backlog slice for proof. +- [ ] 1.3 Map slice items to requirements and traceability IDs. + +## 2. Test-first and failing evidence + +- [ ] 2.1 Add integration tests covering backlog->requirements->architecture->validation flow. +- [ ] 2.2 Run tests expecting initial failure and capture in `TDD_EVIDENCE.md`. +- [ ] 2.3 Add validation checks for evidence schema and traceability completeness. + +## 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.3 Re-run tests and quality gates until all proof scenarios pass. + +## 4. Delivery + +- [ ] 4.1 Update docs (`README.md`, `docs/index.md`, validation guide) with proof references. +- [ ] 4.2 Run `openspec validate dogfooding-01-full-chain-e2e-proof --strict`. +- [ ] 4.3 Open PR to `dev` with dogfooding evidence package. diff --git a/openspec/changes/governance-01-evidence-output/.openspec.yaml b/openspec/changes/governance-01-evidence-output/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md b/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md new file mode 100644 index 00000000..81b9d6a2 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: governance-01-evidence-output + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate governance-01-evidence-output --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** governance-evidence-output +- **Modified capabilities:** full-chain-validation,policy-engine +- **Declared dependencies:** validation-02 (full-chain engine), policy-02 (enforcement modes) +- **Proposed affected code paths:** - `modules/validate/src/validate/engine/` (extend with evidence writer);- `modules/policy-engine/src/policy_engine/` (evidence-compatible result formatting) - `.specfact/evidence/` (new evidence artifact directory) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/governance-01-evidence-output/design.md b/openspec/changes/governance-01-evidence-output/design.md new file mode 100644 index 00000000..75561c7e --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `governance-01-evidence-output` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on validation-02-full-chain-engine and policy-02-packs-and-modes. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/governance-01-evidence-output/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md new file mode 100644 index 00000000..cc1cec99 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/proposal.md @@ -0,0 +1,69 @@ +# Change: Evidence & Audit Output for CI/CD Pipelines + +## 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. + +## What Changes + + + + +- **NEW**: Evidence writer producing standardized JSON artifacts: + ```json + { + "schema_version": "1.0", + "run_id": "uuid", + "timestamp": "ISO-8601", + "profile": "enterprise", + "policy_mode": "hard", + "validation_results": { + "full_chain": { "pass": 67, "fail": 2, "advisory": 5 }, + "layers": { ... }, + "orphans": { ... } + }, + "coverage": { + "req_to_arch": "92%", + "arch_to_spec": "100%", + "spec_to_code": "100%", + "code_to_test": "87%" + }, + "exceptions": [ + { "id": "EXC-001", "policy": "...", "expires": "2026-12-31", "status": "active" } + ], + "overall_verdict": "PASS_WITH_ADVISORY", + "ci_exit_code": 0 + } + ``` +- **NEW**: `--evidence-dir .specfact/evidence/` flag on `specfact validate --full-chain` 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**: 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. + +## Capabilities +### New Capabilities + +- `governance-evidence-output`: Machine-readable JSON evidence artifacts for CI/CD gates and audit systems, with per-run persistence, CI exit code modes, coverage percentages, exception status, and profile-aware verdicts. + +### Modified Capabilities + +- `full-chain-validation`: 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 + + +--- + +## Source Tracking + + +- **GitHub Issue**: #247 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md b/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md new file mode 100644 index 00000000..ab936839 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Full Chain Validation +Full-chain validation SHALL emit governance-ready evidence artifacts. + +#### Scenario: Evidence artifact is written with stable schema envelope +- **GIVEN** full-chain validation executes with evidence output enabled +- **WHEN** command completes +- **THEN** evidence includes schema version, timestamp, profile, policy mode, layer summaries, and overall status +- **AND** artifact path is printed for CI ingestion. diff --git a/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md new file mode 100644 index 00000000..7bf7039b --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Governance Evidence Output +The system SHALL produce machine-readable governance evidence suitable for CI and audit ingestion. + +#### Scenario: CI-consumable evidence includes policy and exception context +- **GIVEN** validation runs in CI mode +- **WHEN** evidence is generated +- **THEN** policy results and active exception references are included +- **AND** each exception includes identifier and expiration metadata. + +#### Scenario: Evidence contains layer-level coverage metrics +- **GIVEN** full-chain validation has transition results +- **WHEN** governance evidence is emitted +- **THEN** each layer contains pass/fail/advisory counts and coverage percentages +- **AND** overall verdict is derivable from the evidence alone. diff --git a/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md b/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md new file mode 100644 index 00000000..492c42bd --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +Policy evaluation outputs SHALL be serializable into governance evidence records. + +#### Scenario: Policy rule results include evidence-ready fields +- **GIVEN** policy validation completes +- **WHEN** evidence serialization runs +- **THEN** each rule result includes rule ID, severity, mode, and outcome +- **AND** output can be consumed by CI gates without additional transformation. diff --git a/openspec/changes/governance-01-evidence-output/tasks.md b/openspec/changes/governance-01-evidence-output/tasks.md new file mode 100644 index 00000000..1cc7c7a9 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/tasks.md @@ -0,0 +1,31 @@ +# Tasks: governance-01-evidence-output + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/governance-01-evidence-output` from `dev` before implementation work. +- [ ] 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.4 Confirm governance-01 ownership of evidence envelope/schema per `openspec/CHANGE_ORDER.md` before modifying shared outputs. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate governance-01-evidence-output --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/governance-01-evidence-output` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/governance-02-exception-management/.openspec.yaml b/openspec/changes/governance-02-exception-management/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md b/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md new file mode 100644 index 00000000..46dff12b --- /dev/null +++ b/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: governance-02-exception-management + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate governance-02-exception-management --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** exception-management +- **Modified capabilities:** policy-engine,governance-evidence-output +- **Declared dependencies:** policy-02 (enforcement modes — exceptions modify enforcement behavior) +- **Proposed affected code paths:** - `modules/policy-engine/src/policy_engine/` (extend with exception checking);- `.specfact/exceptions.yaml` (new config file) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/governance-02-exception-management/design.md b/openspec/changes/governance-02-exception-management/design.md new file mode 100644 index 00000000..833849de --- /dev/null +++ b/openspec/changes/governance-02-exception-management/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `governance-02-exception-management` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on policy-02-packs-and-modes. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/governance-02-exception-management/proposal.md b/openspec/changes/governance-02-exception-management/proposal.md new file mode 100644 index 00000000..be29b476 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/proposal.md @@ -0,0 +1,58 @@ +# Change: Exception Management — Time-Bound, Tracked Policy Exceptions + +## Why + + + + +Enterprises always need exceptions — a legacy service can't comply with the new API versioning policy until migration completes, a regulatory deadline grants a 6-month grace period. But untracked exceptions defeat governance: they become permanent workarounds. Explicit, tracked, time-bound exceptions in config — with automatic expiry, monthly digests, and audit trail — make governance flexible without losing accountability. + +## What Changes + + + + +- **NEW**: Exception declaration in `.specfact/exceptions.yaml`: + ```yaml + exceptions: + - id: EXC-1234 + policy: data-residency-eu-only + scope: service:legacy-reporting + reason: "Migration in progress, target Q4 2026" + expires_at: 2026-12-31 + approved_by: "CIO" + created_at: 2026-02-15 + ``` +- **NEW**: `specfact exceptions list` — show all active, approaching expiry, and expired exceptions +- **NEW**: `specfact exceptions add --policy --scope --reason --expires --approved-by ` — add a tracked exception +- **NEW**: `specfact exceptions check` — verify all exceptions are still valid (not expired); flag expired exceptions as hard failures +- **NEW**: Behavior during validation: + - Active exception: treated as warning locally, non-blocking in CI + - Approaching expiry (configurable threshold, default 30 days): elevated warning with reminder + - Expired exception: hard failure — same as if exception never existed +- **NEW**: Monthly digest generation: `specfact exceptions digest` — summary of approaching expirations for governance review +- **EXTEND**: Evidence output (governance-01) includes exception status in evidence artifacts +- **EXTEND**: Policy engine respects exception scope during validation — matching exceptions suppress the specific policy violation for the specific scope only +- **NEW**: Ownership authority — this change is authoritative for exception-scope suppression and expiry semantics; evidence schema remains owned by governance-01. + +## Capabilities +### New Capabilities + +- `exception-management`: Time-bound, tracked policy exceptions with automatic expiry, scope-limited suppression, approaching-expiry warnings, monthly digest generation, and audit trail in evidence artifacts. + +### Modified Capabilities + +- `policy-engine`: Extended to respect exception scope during validation (suppress specific policy for specific scope) +- `governance-evidence-output`: Extended to include exception status in evidence artifacts + + +--- + +## Source Tracking + + +- **GitHub Issue**: #248 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md b/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md new file mode 100644 index 00000000..e2608dd3 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Exception Management +The system SHALL support explicit, tracked, and time-bound governance exceptions. + +#### Scenario: Active exception suppresses blocking until expiry +- **GIVEN** `.specfact/exceptions.yaml` contains an active exception for a policy and scope +- **WHEN** policy validation runs before expiration +- **THEN** matching violation is downgraded from blocking to non-blocking +- **AND** evidence records the applied exception ID. + +#### Scenario: Expired exception restores blocking behavior +- **GIVEN** exception expiry date is in the past +- **WHEN** matching policy violation occurs +- **THEN** violation is treated per normal mode semantics +- **AND** output identifies the exception as expired. diff --git a/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md b/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md new file mode 100644 index 00000000..d94d3713 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Governance Evidence Output +Governance evidence SHALL include exception lifecycle status for active and expired exceptions. + +#### Scenario: Exception lifecycle is visible in evidence +- **GIVEN** evidence generation runs with configured exceptions +- **WHEN** artifact is emitted +- **THEN** evidence lists applied, pending-expiry, and expired exception states +- **AND** each entry includes policy, scope, and expiry date. diff --git a/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md b/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md new file mode 100644 index 00000000..481da689 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +Policy evaluation SHALL apply scoped exceptions before computing final blocking outcome. + +#### Scenario: Scope mismatch does not suppress violation +- **GIVEN** exception exists for a different scope than the evaluated artifact +- **WHEN** policy rule fails +- **THEN** violation is not suppressed +- **AND** engine reports scope mismatch diagnostics. diff --git a/openspec/changes/governance-02-exception-management/tasks.md b/openspec/changes/governance-02-exception-management/tasks.md new file mode 100644 index 00000000..2ae64934 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/tasks.md @@ -0,0 +1,31 @@ +# Tasks: governance-02-exception-management + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/governance-02-exception-management` from `dev` before implementation work. +- [ ] 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.4 Confirm exception-scope ownership boundaries per `openspec/CHANGE_ORDER.md` and avoid schema-envelope changes owned by governance-01. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate governance-02-exception-management --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/governance-02-exception-management` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/integration-01-cross-change-contracts/.openspec.yaml b/openspec/changes/integration-01-cross-change-contracts/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/integration-01-cross-change-contracts/CHANGE_VALIDATION.md b/openspec/changes/integration-01-cross-change-contracts/CHANGE_VALIDATION.md new file mode 100644 index 00000000..ef545f7b --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/CHANGE_VALIDATION.md @@ -0,0 +1,16 @@ +# Change Validation: integration-01-cross-change-contracts + +- **Validated on (UTC):** 2026-02-15T00:00:00Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate integration-01-cross-change-contracts --strict` +- **Result:** PASS + +## Scope Summary + +- New capability: `cross-change-integration-contract` +- Focus: ownership authority, compatibility contract, wave integration gates + +## Validation Outcome + +- Required artifacts are present. +- Proposal is implementation-ready after dependency confirmation. diff --git a/openspec/changes/integration-01-cross-change-contracts/design.md b/openspec/changes/integration-01-cross-change-contracts/design.md new file mode 100644 index 00000000..a6e841a9 --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/design.md @@ -0,0 +1,35 @@ +## Context + +This change is the integration umbrella for the 2026-02-15 architecture-layer wave. It formalizes cross-change contracts and ownership authority before implementation to avoid semantic conflicts. + +## Goals / Non-Goals + +**Goals:** +- Define authoritative ownership for shared interfaces and files. +- Define compatibility contracts across profile/requirements/architecture/validation/sync/governance/AI layers. +- Add explicit integration gates for multi-wave rollout. + +**Non-Goals:** +- No production code implementation. +- No replacement of existing feature proposals. + +## Decisions + +- Store ownership and wave gates in OpenSpec artifacts to keep implementation auditable. +- Require dependency and owner check before implementation branch work. +- Keep interface contracts additive where possible; breaking changes require explicit migration notes. + +## Risks / Trade-offs + +- [Overhead from governance] -> Mitigation: keep ownership matrix concise and limited to overlapping files/interfaces. +- [Late-discovered dependency conflicts] -> Mitigation: add mandatory wave exit gates with objective criteria. + +## Migration Plan + +1. Add umbrella contract artifacts and validate strictly. +2. Reference ownership/gate requirements in dependent changes. +3. Enforce owner checks at apply stage for dependent changes. + +## Open Questions + +- Whether to enforce automated owner checks in CI as a separate governance change. diff --git a/openspec/changes/integration-01-cross-change-contracts/proposal.md b/openspec/changes/integration-01-cross-change-contracts/proposal.md new file mode 100644 index 00000000..956cc94d --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/proposal.md @@ -0,0 +1,47 @@ +# Change: Integration Umbrella for Cross-Change Contracts and Ownership + +## Why + + + + +The architecture integration wave introduces many parallel changes that touch shared files and interfaces (`ProjectBundle` extensions, backlog adapters, policy engine outputs). Without one umbrella integration contract, implementation drift and merge collisions are likely. This change creates a single authoritative contract and ownership model so all dependent changes can compose into one end-to-end system. + +## What Changes + + + + +- **NEW**: Define a cross-change integration contract for shared interfaces: + - ProjectBundle extension namespaces and merge order + - Backlog adapter extension protocol boundaries + - Policy engine result envelope consumed by governance/evidence layers +- **NEW**: Define ownership boundaries and change authority rules for overlapping files: + - `policy-02-packs-and-modes` owns policy mode execution core + - `governance-01-evidence-output` owns evidence schema and CI envelope + - `governance-02-exception-management` owns exception-scope suppression behavior + - `requirements-01-data-model` owns base requirements schema + - `architecture-01-solution-layer` owns architecture-specific bundle extension namespace +- **NEW**: Add compatibility rules for all architecture-plan changes before implementation starts (required pre-implementation checklist) +- **NEW**: Add integration acceptance gate definition for Wave 6+ and Wave 8 closure + +## Capabilities +### New Capabilities + +- `cross-change-integration-contract`: A single integration contract that defines interface boundaries, ownership authority, and compatibility rules across all architecture integration changes. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #254 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md b/openspec/changes/integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md new file mode 100644 index 00000000..cc83cc61 --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/specs/cross-change-integration-contract/spec.md @@ -0,0 +1,25 @@ +## ADDED 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/changes/integration-01-cross-change-contracts/tasks.md b/openspec/changes/integration-01-cross-change-contracts/tasks.md new file mode 100644 index 00000000..c33626c5 --- /dev/null +++ b/openspec/changes/integration-01-cross-change-contracts/tasks.md @@ -0,0 +1,24 @@ +# Tasks: integration-01-cross-change-contracts + +## 1. Branch and authority setup + +- [ ] 1.1 Create branch `feature/integration-01-cross-change-contracts` from `dev`. +- [ ] 1.2 Confirm all architecture-plan changes reference this umbrella contract. +- [ ] 1.3 Establish owner matrix for shared interfaces/files. + +## 2. Spec and validation-first + +- [ ] 2.1 Finalize integration contract spec scenarios. +- [ ] 2.2 Add/align validation checks for ownership and compatibility evidence. +- [ ] 2.3 Run failing-first checks for contract enforcement and record in `TDD_EVIDENCE.md`. + +## 3. Integration controls + +- [ ] 3.1 Add wave gate criteria and apply-phase guidance across dependent changes. +- [ ] 3.2 Add docs references for integration contract usage. +- [ ] 3.3 Re-run `openspec validate integration-01-cross-change-contracts --strict`. + +## 4. Delivery + +- [ ] 4.1 Update `openspec/CHANGE_ORDER.md` with final issue links and blockers. +- [ ] 4.2 Open PR to `dev` with cross-change contract evidence. diff --git a/openspec/changes/policy-02-packs-and-modes/.openspec.yaml b/openspec/changes/policy-02-packs-and-modes/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md b/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md new file mode 100644 index 00000000..da303e3a --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: policy-02-packs-and-modes + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate policy-02-packs-and-modes --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** policy-packs-and-modes +- **Modified capabilities:** policy-engine +- **Declared dependencies:** profile-01 (config layering for default modes), policy-engine-01 (#176, unified framework) +- **Proposed affected code paths:** - `modules/policy-engine/src/policy_engine/engine/` (extend with mode-aware validation);- `modules/policy-engine/src/policy_engine/packs/` (new — pack install/list/manage) - `.specfact/policy.yaml` (extend with mode and pack configuration) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/policy-02-packs-and-modes/design.md b/openspec/changes/policy-02-packs-and-modes/design.md new file mode 100644 index 00000000..bbce1bc4 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `policy-02-packs-and-modes` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on profile-01-config-layering and policy-engine-01-unified-framework. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/policy-02-packs-and-modes/proposal.md b/openspec/changes/policy-02-packs-and-modes/proposal.md new file mode 100644 index 00000000..08214e0f --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/proposal.md @@ -0,0 +1,57 @@ +# Change: Policy Packs & Enforcement Modes (Advisory/Mixed/Hard) + +## Why + + + + +Policy enforcement today is binary — pass or fail. Different team sizes need different enforcement levels: a solo developer needs advisory warnings, a startup needs some hard gates, an enterprise needs full enforcement with tracked exceptions. Additionally, policies should be distributable as reusable packs (DoR/DoD basics, compliance packs, domain-specific rules) so teams don't reinvent quality gates. Three enforcement modes (advisory/mixed/hard) with installable policy packs make governance progressive and composable. + +## What Changes + + + + +- **NEW**: Three enforcement modes with distinct local and CI behavior: + - **Advisory (shadow)**: Warnings only locally, annotations + exit 0 in CI + - **Mixed**: Configurable per rule (some warn, some block); partial blocking in CI + - **Hard**: All violations block locally and in CI; evidence emission required +- **NEW**: Gradual escalation path: new policies start in shadow mode for a configurable period (default 2 weeks), then auto-promote to the profile's default mode. Manual override available. +- **NEW**: Policy packs — installable bundles of related policy rules: + - `specfact policy install specfact/dor-dod-basics` — install built-in DoR/DoD policy pack + - `specfact policy install org/payments-compliance` — install org-specific policy pack + - Pack format: YAML manifest + rule definitions, versioned, signable (arch-06) +- **NEW**: `specfact policy list --show-mode` — list active policies with their current enforcement mode (shadow/advisory/mixed/hard) and escalation schedule +- **NEW**: Per-rule mode override in `.specfact/policy.yaml`: + ```yaml + policies: + dor-dod-basics: + mode: mixed + rules: + require-acceptance-criteria: hard + require-business-value: advisory + ``` +- **EXTEND**: Policy engine (policy-engine-01) extended with mode-aware execution — `policy.validate` respects the configured mode per rule and per pack +- **EXTEND**: Profile integration — each profile tier has a default enforcement mode (solo=advisory, startup=advisory→mixed, mid-size=mixed, enterprise=hard) +- **NEW**: Ownership authority — this change is authoritative for policy mode execution semantics; dependent governance changes must consume this contract without redefining mode behavior. + +## Capabilities +### New Capabilities + +- `policy-packs-and-modes`: Distributable policy packs with three enforcement modes (advisory/mixed/hard), gradual escalation, per-rule mode overrides, and profile-driven defaults. Packs are installable, versioned, and signable. + +### Modified Capabilities + +- `policy-engine`: Extended with mode-aware execution (advisory/mixed/hard per rule), shadow-start for new policies, and gradual escalation scheduling + + +--- + +## Source Tracking + + +- **GitHub Issue**: #246 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md b/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md new file mode 100644 index 00000000..965c870e --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +The policy engine SHALL support advisory, mixed, and hard enforcement modes with per-rule overrides. + +#### Scenario: Advisory mode never blocks +- **GIVEN** policy mode is advisory +- **WHEN** violations are found +- **THEN** command exits successfully +- **AND** violations are emitted as warnings/annotations. + +#### Scenario: Mixed mode applies per-rule blocking semantics +- **GIVEN** mode is mixed and rule severity map marks one rule as blocking +- **WHEN** that rule fails +- **THEN** command exits non-zero +- **AND** non-blocking rule failures remain advisory. diff --git a/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md b/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md new file mode 100644 index 00000000..206e5ee7 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Policy Packs And Modes +The system SHALL install policy packs and evaluate them under active enforcement mode. + +#### Scenario: Policy pack install and listing +- **GIVEN** `specfact policy install ` +- **WHEN** installation succeeds +- **THEN** pack metadata is persisted in active configuration +- **AND** `specfact policy list --show-mode` displays pack and mode. + +#### Scenario: New policy starts in shadow/advisory period +- **GIVEN** newly installed pack with gradual rollout enabled +- **WHEN** validation is run during rollout window +- **THEN** failures are advisory +- **AND** mode promotion behavior is traceable in config/evidence. diff --git a/openspec/changes/policy-02-packs-and-modes/tasks.md b/openspec/changes/policy-02-packs-and-modes/tasks.md new file mode 100644 index 00000000..752bbc53 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/tasks.md @@ -0,0 +1,31 @@ +# Tasks: policy-02-packs-and-modes + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/policy-02-packs-and-modes` from `dev` before implementation work. +- [ ] 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.4 Confirm ownership authority for policy mode semantics per `openspec/CHANGE_ORDER.md` before editing shared policy-engine surfaces. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate policy-02-packs-and-modes --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/policy-02-packs-and-modes` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/profile-01-config-layering/.openspec.yaml b/openspec/changes/profile-01-config-layering/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/profile-01-config-layering/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/profile-01-config-layering/CHANGE_VALIDATION.md b/openspec/changes/profile-01-config-layering/CHANGE_VALIDATION.md new file mode 100644 index 00000000..4d92d53b --- /dev/null +++ b/openspec/changes/profile-01-config-layering/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: profile-01-config-layering + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate profile-01-config-layering --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** profile-config-layering +- **Modified capabilities:** init-module-state +- **Declared dependencies:** None (foundational); extends #193 (command registry + tier gating) +- **Proposed affected code paths:** - `modules/profile/` (new module);- `modules/init/src/` (extend with `--profile` flag) - `.specfact/profile.yaml` or `.specfact/config.yaml` (new/extended config file) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/profile-01-config-layering/design.md b/openspec/changes/profile-01-config-layering/design.md new file mode 100644 index 00000000..915179fc --- /dev/null +++ b/openspec/changes/profile-01-config-layering/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `profile-01-config-layering` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: None (foundation change in Wave A). +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/profile-01-config-layering/proposal.md b/openspec/changes/profile-01-config-layering/proposal.md new file mode 100644 index 00000000..c0625d0f --- /dev/null +++ b/openspec/changes/profile-01-config-layering/proposal.md @@ -0,0 +1,114 @@ +# Change: Profile & Config Layering System + +## 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. + +## 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 + +## 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. +- **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 ` 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 | + +## 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. + +### Modified Capabilities + +- `init-module-state`: Extended with `--profile` flag for tier-aware initialization; default behavior preserved as implicit `solo` profile. + + +--- + +## Source Tracking + + +- **GitHub Issue**: #237 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/profile-01-config-layering/specs/init-module-state/spec.md b/openspec/changes/profile-01-config-layering/specs/init-module-state/spec.md new file mode 100644 index 00000000..4fc5cb39 --- /dev/null +++ b/openspec/changes/profile-01-config-layering/specs/init-module-state/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Init Module State +The system SHALL initialize module state according to the active profile selected during `specfact init`. + +#### Scenario: Profile activates expected module set +- **GIVEN** `specfact init --profile startup` +- **WHEN** init writes module state +- **THEN** enabled modules include sync and ceremony capabilities for startup +- **AND** modules outside the startup profile default set remain disabled unless explicitly enabled. + +#### Scenario: Backward compatible default behavior +- **GIVEN** `specfact init` is executed without `--profile` +- **WHEN** module state is generated +- **THEN** behavior matches current default compatibility profile +- **AND** no hard-fail governance mode is enabled implicitly. diff --git a/openspec/changes/profile-01-config-layering/specs/profile-config-layering/spec.md b/openspec/changes/profile-01-config-layering/specs/profile-config-layering/spec.md new file mode 100644 index 00000000..583d8a3c --- /dev/null +++ b/openspec/changes/profile-01-config-layering/specs/profile-config-layering/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Profile Config Layering +The system SHALL resolve configuration using deterministic layer precedence. + +#### Scenario: Layer precedence is deterministic +- **GIVEN** values are present in profile defaults, org baseline, repo overlay, and developer-local override +- **WHEN** configuration is resolved +- **THEN** precedence is `profile defaults < org baseline < repo overlay < developer local` +- **AND** the resolved output records the winning source for each key. + +#### Scenario: Profile-specific defaults are applied +- **GIVEN** `specfact init --profile enterprise` +- **WHEN** profile config is generated +- **THEN** policy mode defaults to enterprise-grade enforcement +- **AND** requirements schema includes enterprise-required fields. + +#### Scenario: Invalid profile is rejected +- **GIVEN** `specfact init --profile unknown` +- **WHEN** command validation runs +- **THEN** the command exits with a validation error +- **AND** output lists supported profile values. diff --git a/openspec/changes/profile-01-config-layering/tasks.md b/openspec/changes/profile-01-config-layering/tasks.md new file mode 100644 index 00000000..81c4e2d0 --- /dev/null +++ b/openspec/changes/profile-01-config-layering/tasks.md @@ -0,0 +1,30 @@ +# Tasks: profile-01-config-layering + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/profile-01-config-layering` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate profile-01-config-layering --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/profile-01-config-layering` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/profile-02-central-config-sources/.openspec.yaml b/openspec/changes/profile-02-central-config-sources/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/profile-02-central-config-sources/CHANGE_VALIDATION.md b/openspec/changes/profile-02-central-config-sources/CHANGE_VALIDATION.md new file mode 100644 index 00000000..57e9e38e --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: profile-02-central-config-sources + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate profile-02-central-config-sources --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** central-config-sources +- **Modified capabilities:** profile-config-layering +- **Declared dependencies:** profile-01 (config layering foundation) +- **Proposed affected code paths:** - `modules/profile/src/profile/engine/` (extend with central source resolution);- `modules/profile/src/profile/commands/` (new pull command, extended diff) - `.specfact/cache/config-sources/` (new cached baseline directory) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/profile-02-central-config-sources/design.md b/openspec/changes/profile-02-central-config-sources/design.md new file mode 100644 index 00000000..a712fb84 --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `profile-02-central-config-sources` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on profile-01-config-layering. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/profile-02-central-config-sources/proposal.md b/openspec/changes/profile-02-central-config-sources/proposal.md new file mode 100644 index 00000000..120c0205 --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/proposal.md @@ -0,0 +1,50 @@ +# Change: Central Config Sources — Org Baselines with Local Overlays + +## Why + + + + +Mid-size and enterprise teams need centralized configuration baselines that individual repos inherit without copy-pasting. Today every repo has its own `.specfact/config.yaml`, leading to configuration drift across hundreds of repos. A read-only central config source that repos pull from — with local overlays and divergence warnings — gives organizations consistent governance while letting individual teams adapt to their specific needs. + +## What Changes + + + + +- **NEW**: Config source declaration in `.specfact/profile.yaml`: + ```yaml + config_sources: + - git+ssh://github.com/myorg/engineering-standards/.specfact # Read-only baseline + - git+https://github.com/myorg/payments-team/.specfact # BU overlay + overlay: + policy_mode: mixed # Local override (highest priority) + ``` +- **NEW**: `specfact profile pull` — fetch and cache central config sources locally (`.specfact/cache/config-sources/`) +- **NEW**: `specfact profile diff` (extended) — compare local resolved config against central baseline, showing divergence with source annotations +- **NEW**: Config resolution order: profile defaults → central baselines (in order) → local overlay. Central baselines are **read-only** — local changes cannot modify them, only override via overlay. +- **NEW**: Divergence detection and warnings: when local config deviates from central baseline, warn on every `specfact validate` and `specfact init` run +- **NEW**: Staleness detection: warn when cached central config is older than configurable threshold (default 7 days) +- **NEW**: Git-based config sources: support `git+ssh://` and `git+https://` URIs pointing to a repo path containing `.specfact/` config files +- **EXTEND**: Profile module (profile-01) extended with central config resolution and pull commands + +## Capabilities +### New Capabilities + +- `central-config-sources`: Read-only central configuration baselines with git-based source URIs, local overlay support, divergence detection, staleness warnings, and cached resolution. Organizations define baselines once, repos inherit and optionally override. + +### Modified Capabilities + +- `profile-config-layering`: Extended with central config source resolution in the layering order (profile defaults → central baselines → local overlay) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #249 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/profile-02-central-config-sources/specs/central-config-sources/spec.md b/openspec/changes/profile-02-central-config-sources/specs/central-config-sources/spec.md new file mode 100644 index 00000000..cabcafc7 --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/specs/central-config-sources/spec.md @@ -0,0 +1,23 @@ +## ADDED Requirements + +### Requirement: Central Config Sources +The system SHALL support read-only central configuration sources with local overlays. + +#### Scenario: Pull read-only baseline from central source +- **GIVEN** `.specfact/profile.yaml` defines a central git config source +- **WHEN** profile resolution runs +- **THEN** baseline values are loaded from that source +- **AND** baseline files are treated as read-only inputs. + +#### Scenario: Local overlay overrides baseline +- **GIVEN** baseline sets `policy_mode: advisory` +- **AND** repo overlay sets `policy_mode: mixed` +- **WHEN** configuration is resolved +- **THEN** the resolved mode is `mixed` +- **AND** output includes baseline-versus-overlay provenance. + +#### Scenario: Divergence warning is emitted +- **GIVEN** local values diverge from central baseline policy keys +- **WHEN** config check runs +- **THEN** the system emits a divergence warning +- **AND** the warning includes source key paths that differ. diff --git a/openspec/changes/profile-02-central-config-sources/specs/profile-config-layering/spec.md b/openspec/changes/profile-02-central-config-sources/specs/profile-config-layering/spec.md new file mode 100644 index 00000000..16f16bce --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/specs/profile-config-layering/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Profile Config Layering +The system SHALL incorporate central config sources into profile layering without breaking existing local-only workflows. + +#### Scenario: Local-only repositories remain valid +- **GIVEN** no central source is configured +- **WHEN** profile layering resolves config +- **THEN** resolution still works with profile, repo, and local layers +- **AND** no network dependency is required. + +#### Scenario: Source attribution includes central baseline +- **GIVEN** central baseline is configured +- **WHEN** resolved config is inspected +- **THEN** keys sourced from baseline are marked as central +- **AND** overridden keys show both baseline and overriding source. diff --git a/openspec/changes/profile-02-central-config-sources/tasks.md b/openspec/changes/profile-02-central-config-sources/tasks.md new file mode 100644 index 00000000..aecf3ed5 --- /dev/null +++ b/openspec/changes/profile-02-central-config-sources/tasks.md @@ -0,0 +1,30 @@ +# Tasks: profile-02-central-config-sources + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/profile-02-central-config-sources` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate profile-02-central-config-sources --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/profile-02-central-config-sources` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/profile-03-domain-overlays/.openspec.yaml b/openspec/changes/profile-03-domain-overlays/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/profile-03-domain-overlays/CHANGE_VALIDATION.md b/openspec/changes/profile-03-domain-overlays/CHANGE_VALIDATION.md new file mode 100644 index 00000000..9f4fe01b --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: profile-03-domain-overlays + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate profile-03-domain-overlays --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** domain-overlays +- **Modified capabilities:** profile-config-layering,requirements-data-model +- **Declared dependencies:** profile-01 (config layering), profile-02 (central config sources), arch-07 (#213, schema extensions for dynamic field requirements) +- **Proposed affected code paths:** - `modules/profile/src/profile/` (extend with overlay resolution);- `.specfact/profiles/` (new domain overlay directory) - `src/specfact_cli/models/requirements.py` (dynamic field validation via arch-07) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/profile-03-domain-overlays/design.md b/openspec/changes/profile-03-domain-overlays/design.md new file mode 100644 index 00000000..488e01f1 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `profile-03-domain-overlays` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on profile-01-config-layering, profile-02-central-config-sources, and arch-07-schema-extension-system. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/profile-03-domain-overlays/proposal.md b/openspec/changes/profile-03-domain-overlays/proposal.md new file mode 100644 index 00000000..2e964839 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/proposal.md @@ -0,0 +1,57 @@ +# Change: Domain Overlays & Org-Level Requirements Schema + +## Why + + + + +Different business units within an enterprise have different requirements — the payments team needs regulatory references and risk owners on every requirement, the platform team doesn't. A single enterprise profile can't cover this variance without becoming unwieldy. Domain-specific overlays that extend the base profile with additional required fields, constraints, and policies let organizations enforce domain-specific governance without forking the entire profile system. + +## What Changes + + + + +- **NEW**: Domain overlay definitions at `.specfact/profiles/{domain}.yaml`: + ```yaml + inherit: enterprise # Base profile to extend + requirements_schema: + additional_required_fields: + - regulatory_reference + - risk_owner + - data_classification + architectural_constraints: + - "All services must use org-shared payment-gateway adapter" + - "PII fields must be encrypted at rest" + policy_overrides: + require-data-classification: hard # Override from mixed to hard for this domain + ``` +- **NEW**: `specfact profile overlays list` — show available domain overlays +- **NEW**: `specfact profile overlays apply ` — apply a domain overlay to the current repo +- **NEW**: Profile-aware requirements validation — when a domain overlay defines additional required fields, `specfact requirements validate` checks those fields +- **NEW**: Overlay inheritance: domain overlay inherits all settings from the base profile, only overriding specified fields +- **NEW**: Central distribution: domain overlays can be distributed via central config sources (profile-02) or marketplace (marketplace-01) +- **EXTEND**: Requirements data model (requirements-01) supports dynamic field requirements based on active domain overlay via arch-07 schema extensions +- **EXTEND**: Profile resolution order becomes: profile defaults → central baselines → domain overlay → local overlay + +## Capabilities +### New Capabilities + +- `domain-overlays`: Domain-specific profile overlays that extend base profiles with additional required fields, architectural constraints, and policy overrides. Distributed via central config sources or marketplace. + +### Modified Capabilities + +- `profile-config-layering`: Extended with domain overlay in resolution order +- `requirements-data-model`: Requirements validation respects domain-specific required fields + + +--- + +## Source Tracking + + +- **GitHub Issue**: #250 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/profile-03-domain-overlays/specs/domain-overlays/spec.md b/openspec/changes/profile-03-domain-overlays/specs/domain-overlays/spec.md new file mode 100644 index 00000000..e884a681 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/specs/domain-overlays/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Domain Overlays +The system SHALL allow domain-specific overlays to extend profile requirements and policy constraints. + +#### Scenario: Domain overlay adds required requirement fields +- **GIVEN** an enterprise profile with `payments` overlay +- **WHEN** requirements schema is resolved +- **THEN** overlay-required fields include `regulatory_reference` and `risk_owner` +- **AND** requirement validation fails when those fields are missing. + +#### Scenario: Domain overlay adds architectural constraints +- **GIVEN** overlay defines mandatory shared payment gateway usage +- **WHEN** architecture validation runs +- **THEN** solutions missing that integration are flagged +- **AND** severity follows active policy mode. diff --git a/openspec/changes/profile-03-domain-overlays/specs/profile-config-layering/spec.md b/openspec/changes/profile-03-domain-overlays/specs/profile-config-layering/spec.md new file mode 100644 index 00000000..18e9616c --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/specs/profile-config-layering/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Profile Config Layering +The system SHALL merge domain overlays after central profile resolution and before developer-local overrides. + +#### Scenario: Overlay precedence is enforced +- **GIVEN** base enterprise profile and domain overlay define conflicting requirement schema rules +- **WHEN** profile resolution executes +- **THEN** overlay rules win over base profile rules +- **AND** developer-local overrides can still adjust non-locked keys. + +#### Scenario: Unknown overlay is rejected +- **GIVEN** requested overlay name is not available +- **WHEN** initialization runs +- **THEN** command fails with clear overlay-not-found diagnostics +- **AND** available overlays are listed. diff --git a/openspec/changes/profile-03-domain-overlays/specs/requirements-data-model/spec.md b/openspec/changes/profile-03-domain-overlays/specs/requirements-data-model/spec.md new file mode 100644 index 00000000..af690086 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/specs/requirements-data-model/spec.md @@ -0,0 +1,15 @@ +## MODIFIED Requirements + +### Requirement: Requirements Data Model +The system SHALL support schema-driven required fields introduced by domain overlays. + +#### Scenario: Overlay-required fields enforced at model validation +- **GIVEN** overlay declares additional required fields +- **WHEN** a requirement document is parsed +- **THEN** missing overlay-required fields cause validation errors +- **AND** error output identifies the overlay and missing fields. + +#### Scenario: Base schema compatibility preserved +- **GIVEN** no domain overlay is active +- **WHEN** requirement documents are validated +- **THEN** base requirements schema behavior remains unchanged. diff --git a/openspec/changes/profile-03-domain-overlays/tasks.md b/openspec/changes/profile-03-domain-overlays/tasks.md new file mode 100644 index 00000000..a8b348d4 --- /dev/null +++ b/openspec/changes/profile-03-domain-overlays/tasks.md @@ -0,0 +1,30 @@ +# Tasks: profile-03-domain-overlays + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/profile-03-domain-overlays` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate profile-03-domain-overlays --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/profile-03-domain-overlays` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/requirements-01-data-model/.openspec.yaml b/openspec/changes/requirements-01-data-model/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/requirements-01-data-model/CHANGE_VALIDATION.md b/openspec/changes/requirements-01-data-model/CHANGE_VALIDATION.md new file mode 100644 index 00000000..35a41b50 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: requirements-01-data-model + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate requirements-01-data-model --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** requirements-data-model +- **Modified capabilities:** data-models +- **Declared dependencies:** arch-07 (schema extension system, #213) for ProjectBundle extension +- **Proposed affected code paths:** - `src/specfact_cli/models/requirements.py` (new);- `src/specfact_cli/models/project.py` (extend via arch-07 schema extensions) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/requirements-01-data-model/design.md b/openspec/changes/requirements-01-data-model/design.md new file mode 100644 index 00000000..497373d5 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `requirements-01-data-model` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on arch-07-schema-extension-system. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/requirements-01-data-model/proposal.md b/openspec/changes/requirements-01-data-model/proposal.md new file mode 100644 index 00000000..f3caa0db --- /dev/null +++ b/openspec/changes/requirements-01-data-model/proposal.md @@ -0,0 +1,45 @@ +# Change: Requirements Data Model & Storage + +## 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). + +## 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`) + +## 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. + +### Modified Capabilities + +- `data-models`: ProjectBundle extended with requirements field via arch-07 schema extensions + + +--- + +## Source Tracking + + +- **GitHub Issue**: #238 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/requirements-01-data-model/specs/data-models/spec.md b/openspec/changes/requirements-01-data-model/specs/data-models/spec.md new file mode 100644 index 00000000..450e5da4 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/specs/data-models/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Data Models +The system SHALL extend project models to include requirements payloads with schema versioning. + +#### Scenario: Project bundle accepts requirements namespace +- **GIVEN** a project bundle with requirements entries +- **WHEN** model validation runs +- **THEN** the requirements namespace is accepted +- **AND** existing non-requirements fields remain backward compatible. + +#### Scenario: Schema version is required for requirements artifacts +- **GIVEN** a requirement document without `schema_version` +- **WHEN** it is loaded +- **THEN** validation fails +- **AND** output indicates the missing version field. diff --git a/openspec/changes/requirements-01-data-model/specs/requirements-data-model/spec.md b/openspec/changes/requirements-01-data-model/specs/requirements-data-model/spec.md new file mode 100644 index 00000000..4ea4c664 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/specs/requirements-data-model/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Requirements Data Model +The system SHALL define structured business requirement artifacts stored under `.specfact/requirements/`. + +#### Scenario: Requirement artifact captures business intent and constraints +- **GIVEN** a requirement file `.specfact/requirements/REQ-123.req.yaml` +- **WHEN** it is validated +- **THEN** it includes business outcome, business rules, and architectural constraints +- **AND** each business rule has a stable rule identifier. + +#### Scenario: Trace references are represented explicitly +- **GIVEN** requirement trace metadata +- **WHEN** artifacts are parsed +- **THEN** architecture, spec, code, and test references are stored as explicit lists +- **AND** trace references are serializable to JSON evidence output. diff --git a/openspec/changes/requirements-01-data-model/tasks.md b/openspec/changes/requirements-01-data-model/tasks.md new file mode 100644 index 00000000..aabb1978 --- /dev/null +++ b/openspec/changes/requirements-01-data-model/tasks.md @@ -0,0 +1,30 @@ +# Tasks: requirements-01-data-model + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/requirements-01-data-model` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate requirements-01-data-model --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/requirements-01-data-model` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/requirements-02-module-commands/.openspec.yaml b/openspec/changes/requirements-02-module-commands/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md b/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md new file mode 100644 index 00000000..4fb21c6d --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: requirements-02-module-commands + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate requirements-02-module-commands --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** requirements-module +- **Modified capabilities:** module-io-contract,backlog-adapter +- **Declared dependencies:** requirements-01 (data model), arch-07 (#213, schema extensions for ProjectBundle) +- **Proposed affected code paths:** - `modules/requirements/` (new module);- `modules/backlog/src/adapters/` (extend adapters with AC text extraction interface) - `src/specfact_cli/contracts/module_interface.py` (no change — new implementation) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/requirements-02-module-commands/design.md b/openspec/changes/requirements-02-module-commands/design.md new file mode 100644 index 00000000..f70d8055 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `requirements-02-module-commands` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-01-data-model and arch-07-schema-extension-system. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/requirements-02-module-commands/proposal.md b/openspec/changes/requirements-02-module-commands/proposal.md new file mode 100644 index 00000000..84d939a2 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/proposal.md @@ -0,0 +1,110 @@ +# Change: Requirements Module — Extract, Author, Validate 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. + +## 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 + author.py # specfact requirements author --template + 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 + author.py # specfact requirements author --template + 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 + +## 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 --project ` — 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 + +## 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. + +### 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 + + +--- + +## Source Tracking + + +- **GitHub Issue**: #239 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md b/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md new file mode 100644 index 00000000..9a401ffa --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Backlog Adapter +The system SHALL expose backlog acceptance-criteria content to requirements extraction workflows. + +#### Scenario: Adapter returns acceptance criteria payload for extraction +- **GIVEN** a backlog item selected for extraction +- **WHEN** requirements extraction requests source fields +- **THEN** adapter returns title, description, acceptance-criteria text, and item identity +- **AND** extraction proceeds without provider-specific parsing in command handlers. + +#### Scenario: Missing acceptance criteria is surfaced explicitly +- **GIVEN** a backlog item with no acceptance criteria +- **WHEN** extraction runs +- **THEN** item is reported as incomplete input +- **AND** command output includes the backlog item identifier. diff --git a/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md b/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md new file mode 100644 index 00000000..3a4e15ee --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Module Io Contract +The requirements module SHALL implement all `ModuleIOContract` operations. + +#### Scenario: Import operation maps backlog items to requirements +- **GIVEN** backlog input for import +- **WHEN** `import_to_bundle` runs +- **THEN** requirements are added to the bundle with stable IDs +- **AND** parse diagnostics are included for partial failures. + +#### Scenario: Validate operation enforces profile schema +- **GIVEN** requirements bundle and active profile schema +- **WHEN** `validate_bundle` runs +- **THEN** missing required fields are reported +- **AND** validation severity respects active policy mode. diff --git a/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md b/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md new file mode 100644 index 00000000..769f2813 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Requirements Module +The system SHALL provide requirements CLI commands for extract, author, validate, and list. + +#### Scenario: Extract command creates requirement artifacts +- **GIVEN** `specfact requirements extract --from-backlog --output .specfact/requirements/` +- **WHEN** extraction succeeds +- **THEN** one or more `*.req.yaml` files are produced +- **AND** each file includes schema version and source backlog reference. + +#### Scenario: Author command applies profile-aware template fields +- **GIVEN** `specfact requirements author --template story` +- **WHEN** active profile is `solo` +- **THEN** authoring prompts require only solo-required fields +- **AND** optional advanced fields remain non-blocking. + +#### Scenario: Validate and list expose completeness and trace coverage +- **GIVEN** requirement artifacts with trace references +- **WHEN** `specfact requirements validate` and `specfact requirements list --show-coverage` run +- **THEN** completeness and coverage are reported per requirement +- **AND** output is machine-readable when requested. diff --git a/openspec/changes/requirements-02-module-commands/tasks.md b/openspec/changes/requirements-02-module-commands/tasks.md new file mode 100644 index 00000000..f6ea5eca --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/tasks.md @@ -0,0 +1,30 @@ +# Tasks: requirements-02-module-commands + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/requirements-02-module-commands` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate requirements-02-module-commands --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/requirements-02-module-commands` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/requirements-03-backlog-sync/.openspec.yaml b/openspec/changes/requirements-03-backlog-sync/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md b/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md new file mode 100644 index 00000000..cedecec3 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: requirements-03-backlog-sync + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate requirements-03-backlog-sync --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** requirements-backlog-sync +- **Modified capabilities:** backlog-adapter,requirements-module +- **Declared dependencies:** requirements-02 (requirements module), sync-01 (sync kernel) +- **Proposed affected code paths:** - `modules/requirements/src/requirements/commands/` (new sync, drift commands);- `modules/backlog/src/adapters/` (extend with requirements field methods) - Sync kernel integration hooks + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/requirements-03-backlog-sync/design.md b/openspec/changes/requirements-03-backlog-sync/design.md new file mode 100644 index 00000000..4409f9ce --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `requirements-03-backlog-sync` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and sync-01-unified-kernel. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/requirements-03-backlog-sync/proposal.md b/openspec/changes/requirements-03-backlog-sync/proposal.md new file mode 100644 index 00000000..c3768699 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/proposal.md @@ -0,0 +1,43 @@ +# Change: Requirements ↔ Backlog Bidirectional Sync + +## 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. + +## What Changes + + + + +- **NEW**: `specfact requirements sync --from-backlog --project --preview` — pull structured requirements from backlog AC text, update `.specfact/requirements/` +- **NEW**: `specfact requirements sync --to-backlog --project --preview` — push requirement-derived fields back to backlog items (missing AC, business value gaps, architectural constraints) +- **NEW**: `specfact requirements drift --from-backlog --project ` — 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 + +## 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. + +### Modified Capabilities + +- `backlog-adapter`: Extended with requirements field extraction and update methods for bidirectional sync +- `requirements-module`: Extended with sync and drift commands + + +--- + +## Source Tracking + + +- **GitHub Issue**: #244 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md new file mode 100644 index 00000000..78c0ef01 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Backlog Adapter +The backlog adapter SHALL support requirement-aware pull and push sync operations. + +#### Scenario: Pull sync maps backlog changes to requirements updates +- **GIVEN** backlog item acceptance criteria changed since last sync +- **WHEN** requirements sync pull runs +- **THEN** corresponding requirement artifact is updated in preview patch +- **AND** changed fields are listed in sync output. + +#### Scenario: Push sync updates backlog fields from requirements +- **GIVEN** requirement has updated business value fields +- **WHEN** push sync apply runs +- **THEN** mapped backlog fields are updated through adapter write APIs +- **AND** optimistic concurrency checks prevent stale overwrites. diff --git a/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md new file mode 100644 index 00000000..f7d893d9 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Requirements Backlog Sync +The system SHALL support bidirectional backlog and requirements synchronization using sync-kernel session semantics. + +#### Scenario: Preview-first sync does not write upstream +- **GIVEN** `specfact requirements sync --from-backlog github --preview` +- **WHEN** sync executes +- **THEN** a patch preview is generated +- **AND** no upstream write is performed. + +#### Scenario: Drift is detected and reported +- **GIVEN** backlog and requirement artifacts diverged for the same story +- **WHEN** sync analysis runs +- **THEN** drift is flagged with field-level differences +- **AND** required conflict resolution path is provided. diff --git a/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md new file mode 100644 index 00000000..c6a01596 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Requirements Module +The requirements module SHALL include sync workflows backed by the sync kernel. + +#### Scenario: Sync command uses shared session model +- **GIVEN** requirements sync starts +- **WHEN** session is created +- **THEN** sync output includes session ID and status +- **AND** unresolved conflicts can be resumed later. + +#### Scenario: Sync command supports apply mode explicitly +- **GIVEN** preview output is accepted +- **WHEN** apply mode is requested +- **THEN** patch operations are executed with write guards +- **AND** resulting state is persisted for traceability. diff --git a/openspec/changes/requirements-03-backlog-sync/tasks.md b/openspec/changes/requirements-03-backlog-sync/tasks.md new file mode 100644 index 00000000..4470794b --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/tasks.md @@ -0,0 +1,30 @@ +# Tasks: requirements-03-backlog-sync + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/requirements-03-backlog-sync` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate requirements-03-backlog-sync --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/requirements-03-backlog-sync` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/sync-01-unified-kernel/.openspec.yaml b/openspec/changes/sync-01-unified-kernel/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md b/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md new file mode 100644 index 00000000..d4c2c4c4 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: sync-01-unified-kernel + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate sync-01-unified-kernel --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** sync-kernel +- **Modified capabilities:** devops-sync +- **Declared dependencies:** patch-mode-01 (#177, preview/apply gating pattern) +- **Proposed affected code paths:** - `modules/sync-kernel/` (new module);- `modules/sync/src/` (integrate with kernel session management) - `.specfact/sync/journal/` (new offline journal directory) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/sync-01-unified-kernel/design.md b/openspec/changes/sync-01-unified-kernel/design.md new file mode 100644 index 00000000..7008d186 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `sync-01-unified-kernel` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on patch-mode-01-preview-apply. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/sync-01-unified-kernel/proposal.md b/openspec/changes/sync-01-unified-kernel/proposal.md new file mode 100644 index 00000000..2c9e95f3 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/proposal.md @@ -0,0 +1,116 @@ +# Change: Sync Kernel — Unified Session-Based Sync Engine + +## Why + + + + +Sync between backlog, requirements, specs, and code is currently adapter-specific with no unified session management, conflict resolution, or offline support. Each adapter implements its own sync logic, leading to inconsistent behavior: some silently overwrite, some fail on conflict, none provides session resumability. A central, deterministic sync kernel that orchestrates sessions, computes patches, handles conflicts, and queues offline writes gives every sync operation the same safety guarantees — never silent overwrites, always preview first, always resumable. + +## Module Package Structure + +``` +modules/sync-kernel/ + module-package.yaml # name: sync-kernel; commands: sync, sync resolve, sync status + src/sync_kernel/ + __init__.py + main.py # typer.Typer app — sync command group + engine/ + session.py # Session management (session_id, cursor, resume) + patch_computer.py # 3-way merge, JSON Patch (RFC 6902) generation + conflict_detector.py # Field-level conflict detection + conflict_resolver.py # Interactive + auto resolution strategies + offline_queue.py # Offline journal: .specfact/sync/journal/ + models/ + sync_session.py # SyncSession, SyncPatch, ConflictRecord models + sync_event.py # CloudEvents-compatible envelope for interop + providers/ + provider_protocol.py # SyncProviderProtocol — adapters implement this + concurrency/ + etag_manager.py # Optimistic concurrency via ETags / If-Match + commands/ + preview.py # specfact sync --preview + apply.py # specfact sync --apply + resolve.py # specfact sync resolve --session + status.py # specfact sync status (show active sessions) +``` + +**`module-package.yaml` declares:** +- `name: sync-kernel` +- `version: 0.1.0` +- `commands: [sync, sync resolve, sync status]` (`--preview` and `--apply` are flags on `sync`) +- `dependencies: [patch-mode-01-preview-apply]` (uses preview/apply write-safety semantics) +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## Module Package Structure + +``` +modules/sync-kernel/ + module-package.yaml # name: sync-kernel; commands: sync, sync resolve, sync status + src/sync_kernel/ + __init__.py + main.py # typer.Typer app — sync command group + engine/ + session.py # Session management (session_id, cursor, resume) + patch_computer.py # 3-way merge, JSON Patch (RFC 6902) generation + conflict_detector.py # Field-level conflict detection + conflict_resolver.py # Interactive + auto resolution strategies + offline_queue.py # Offline journal: .specfact/sync/journal/ + models/ + sync_session.py # SyncSession, SyncPatch, ConflictRecord models + sync_event.py # CloudEvents-compatible envelope for interop + providers/ + provider_protocol.py # SyncProviderProtocol — adapters implement this + concurrency/ + etag_manager.py # Optimistic concurrency via ETags / If-Match + commands/ + preview.py # specfact sync --preview + apply.py # specfact sync --apply + resolve.py # specfact sync resolve --session + status.py # specfact sync status (show active sessions) +``` + +**`module-package.yaml` declares:** +- `name: sync-kernel` +- `version: 0.1.0` +- `commands: [sync, sync resolve, sync status]` (`--preview` and `--apply` are flags on `sync`) +- `dependencies: [patch-mode-01-preview-apply]` (uses preview/apply write-safety semantics) +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## What Changes + + + + +- **NEW**: Sync kernel in `modules/sync-kernel/` — central orchestrator for all sync operations +- **NEW**: Session management — each sync has `session_id`, cursor, and can be resumed after interruption or conflict +- **NEW**: 3-way merge with JSON Patch (RFC 6902) computation for structured data +- **NEW**: Field-level conflict detection: when both local and remote changed the same field, flag as conflict (never silent overwrite) +- **NEW**: Conflict resolution strategies: auto-resolve for non-overlapping fields, interactive for text conflicts, explicit resolve command for deferred conflicts +- **NEW**: Optimistic concurrency via ETags / If-Match for all upstream writes — fail-fast on stale data +- **NEW**: Offline journal at `.specfact/sync/journal/` — queue writes when upstream is unavailable, apply on next `sync --apply` +- **NEW**: CloudEvents-compatible event envelope for interoperability with external systems +- **NEW**: `SyncProviderProtocol` — adapters (backlog, requirements, architecture) implement this protocol to participate in sync sessions +- **NEW**: CLI commands: `specfact sync --preview` (dry-run patch), `specfact sync --apply` (execute patches), `specfact sync resolve --session ` (resolve pending conflicts), `specfact sync status` (show active sessions) +- **EXTEND**: Existing sync module behavior preserved — the kernel wraps existing adapter-specific sync calls with session management and conflict detection + +## Capabilities +### New Capabilities + +- `sync-kernel`: Unified session-based sync engine with 3-way merge, JSON Patch (RFC 6902), optimistic concurrency (ETags), field-level conflict detection, offline journal, and CloudEvents-compatible event model. Provides SyncProviderProtocol for adapter integration. + +### Modified Capabilities + +- `devops-sync`: Existing sync behavior wrapped with kernel session management; no breaking changes to current sync commands + + +--- + +## Source Tracking + + +- **GitHub Issue**: #243 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md b/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md new file mode 100644 index 00000000..cb9730e9 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Devops Sync +The existing sync behavior SHALL be mediated by unified sync-kernel sessions. + +#### Scenario: Existing sync entry uses session orchestration +- **GIVEN** sync operation starts from supported sync command path +- **WHEN** operation executes +- **THEN** a sync session is created with session ID +- **AND** status can be queried until completion. + +#### Scenario: Sync writes require explicit apply mode +- **GIVEN** sync preview is generated +- **WHEN** apply mode is not requested +- **THEN** no upstream writes are performed +- **AND** output clearly indicates preview-only execution. diff --git a/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md b/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md new file mode 100644 index 00000000..d8a30254 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Sync Kernel +The system SHALL provide a session-based sync kernel with preview/apply safety gates, conflict handling, and offline journaling. + +#### Scenario: Preview mode computes patch set without writing +- **GIVEN** `specfact sync --preview` +- **WHEN** sync analysis runs +- **THEN** JSON patch operations are produced for candidate writes +- **AND** no provider write call is executed. + +#### Scenario: Apply mode enforces optimistic concurrency +- **GIVEN** `specfact sync --apply` and remote data changed after preview +- **WHEN** kernel attempts write +- **THEN** stale writes are rejected using ETag or equivalent concurrency checks +- **AND** conflict records are created for manual resolution. + +#### Scenario: Offline write requests are journaled +- **GIVEN** apply mode is requested while provider is unavailable +- **WHEN** kernel cannot reach upstream +- **THEN** pending writes are stored under `.specfact/sync/journal/` +- **AND** queued writes are eligible for retry in a later session. diff --git a/openspec/changes/sync-01-unified-kernel/tasks.md b/openspec/changes/sync-01-unified-kernel/tasks.md new file mode 100644 index 00000000..ffd6eb7b --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/tasks.md @@ -0,0 +1,30 @@ +# Tasks: sync-01-unified-kernel + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/sync-01-unified-kernel` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate sync-01-unified-kernel --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/sync-01-unified-kernel` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml b/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md b/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md new file mode 100644 index 00000000..578bb2f4 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: traceability-01-index-and-orphans + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate traceability-01-index-and-orphans --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** traceability-index +- **Modified capabilities:** (none) +- **Declared dependencies:** requirements-02 (requirements module), architecture-01 (architecture module) +- **Proposed affected code paths:** - `modules/trace/` (new module);- `.specfact/trace/index.json` (new generated artifact) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/traceability-01-index-and-orphans/design.md b/openspec/changes/traceability-01-index-and-orphans/design.md new file mode 100644 index 00000000..5d5d1444 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `traceability-01-index-and-orphans` from the 2026-02-15 architecture-layer integration plan. 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. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and architecture-01-solution-layer. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/traceability-01-index-and-orphans/proposal.md b/openspec/changes/traceability-01-index-and-orphans/proposal.md new file mode 100644 index 00000000..8881a491 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/proposal.md @@ -0,0 +1,104 @@ +# Change: Traceability Index & 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. + +## 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 + 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 + +## 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 + 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 + +## 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` + +## 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. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **GitHub Issue**: #242 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md b/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md new file mode 100644 index 00000000..82c27e50 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Traceability Index +The system SHALL maintain a queryable index of upstream and downstream links across requirements, architecture, specs, code, and tests. + +#### Scenario: Rebuild index captures all artifact layers +- **GIVEN** `specfact trace index --rebuild` +- **WHEN** index generation completes +- **THEN** `.specfact/trace/index.json` contains entries for requirement, architecture, spec, code, and test artifacts +- **AND** each entry contains both upstream and downstream references. + +#### Scenario: Orphan command reports missing linkage by type +- **GIVEN** at least one artifact has missing required references +- **WHEN** `specfact trace orphans` runs +- **THEN** output groups orphan findings by artifact type +- **AND** each finding includes artifact identifier and missing link category. + +#### Scenario: Matrix export supports machine and human formats +- **GIVEN** a built index +- **WHEN** `specfact trace matrix --format markdown|csv|json` runs +- **THEN** matrix output includes requirement-centered chain rows +- **AND** exported content is deterministic for CI diffs. diff --git a/openspec/changes/traceability-01-index-and-orphans/tasks.md b/openspec/changes/traceability-01-index-and-orphans/tasks.md new file mode 100644 index 00000000..d068008f --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/tasks.md @@ -0,0 +1,30 @@ +# Tasks: traceability-01-index-and-orphans + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/traceability-01-index-and-orphans` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate traceability-01-index-and-orphans --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/traceability-01-index-and-orphans` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/validation-02-full-chain-engine/.openspec.yaml b/openspec/changes/validation-02-full-chain-engine/.openspec.yaml new file mode 100644 index 00000000..2a45c1f4 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md b/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md new file mode 100644 index 00000000..e359d41b --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: validation-02-full-chain-engine + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate validation-02-full-chain-engine --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** full-chain-validation +- **Modified capabilities:** sidecar-validation +- **Declared dependencies:** requirements-02 (module commands), architecture-01 (solution layer), policy-engine-01 (#176, for severity configuration) +- **Proposed affected code paths:** - `modules/validate/src/` (extend with full-chain engine);- Policy engine integration hooks + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/validation-02-full-chain-engine/design.md b/openspec/changes/validation-02-full-chain-engine/design.md new file mode 100644 index 00000000..7cf04d2a --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/design.md @@ -0,0 +1,40 @@ +## 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. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- 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. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands, architecture-01-solution-layer, and policy-engine-01-unified-framework. +- 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 new file mode 100644 index 00000000..a3790256 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/proposal.md @@ -0,0 +1,91 @@ +# Change: Full-Chain Validation 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. + +## 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 + +``` +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 +``` + +## 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 +- **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 + +## 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. + +### Modified Capabilities + +- `sidecar-validation`: Extended with `--full-chain` flag; existing spec-delta validation preserved as-is when flag is omitted + + +--- + +## Source Tracking + + +- **GitHub Issue**: #241 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false + \ No newline at end of file diff --git a/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md b/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md new file mode 100644 index 00000000..a8226e90 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Full Chain Validation +The system SHALL validate Requirement -> Architecture -> Spec -> Code -> Test transitions and emit layered evidence. + +#### Scenario: Full-chain command emits transition-level results +- **GIVEN** `specfact validate --full-chain --output json --evidence-dir .specfact/evidence/` +- **WHEN** validation runs +- **THEN** report includes transition groups `req_to_arch`, `arch_to_spec`, `spec_to_code`, and `code_to_tests` +- **AND** each group reports pass/fail/advisory counts. + +#### Scenario: Severity respects policy mode and profile +- **GIVEN** enterprise profile with hard mode +- **WHEN** a required Req -> Arch mapping is missing +- **THEN** overall validation exits non-zero +- **AND** evidence marks the violation as blocking. + +#### Scenario: Orphan detection is included in evidence +- **GIVEN** specs without requirement links exist +- **WHEN** full-chain validation runs +- **THEN** orphan entries are listed in evidence +- **AND** orphan summary is included in overall status computation. diff --git a/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md b/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md new file mode 100644 index 00000000..2d10b970 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md @@ -0,0 +1,15 @@ +## MODIFIED Requirements + +### Requirement: Sidecar Validation +The sidecar validation capability SHALL support full-chain payload checks in addition to spec-code checks. + +#### Scenario: Sidecar consumes full-chain input set +- **GIVEN** requirement and architecture artifact paths are provided +- **WHEN** sidecar validation runs +- **THEN** sidecar validates layered chain references +- **AND** results are merged into full-chain evidence output. + +#### Scenario: Existing spec-code validation remains supported +- **GIVEN** sidecar is invoked without requirements/architecture inputs +- **WHEN** validation executes +- **THEN** existing spec-code validation behavior continues unchanged. diff --git a/openspec/changes/validation-02-full-chain-engine/tasks.md b/openspec/changes/validation-02-full-chain-engine/tasks.md new file mode 100644 index 00000000..69b551db --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/tasks.md @@ -0,0 +1,30 @@ +# Tasks: validation-02-full-chain-engine + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create branch `feature/validation-02-full-chain-engine` from `dev` before implementation work. +- [ ] 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. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 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. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate validation-02-full-chain-engine --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/validation-02-full-chain-engine` to `dev` with spec/test/code/docs evidence.