Upstream latest change proposals to main branch

.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"

openspec/CHANGE_ORDER.md

@@ -29,6 +29,15 @@ Changes are grouped by **module** and prefixed with **`<module>-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.

openspec/changes/ai-integration-01-agent-skill/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-15

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.

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`.

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
+
+<!-- source_repo: nold-ai/specfact-cli -->
+- **GitHub Issue**: #251
+- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/251>
+- **Last Synced Status**: proposed
+- **Sanitized**: false
+<!-- content_hash: 2b715dada0ffb0b0 -->