From f6ef201e83b68a7d6a5ea15ff6f94554a713d243 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Mon, 9 Feb 2026 00:03:56 +0100 Subject: [PATCH] docs: align arch-05 scope with protocol migration cleanup --- .../arch-05-bridge-registry/proposal.md | 8 +- .../specs/module-lifecycle-management/spec.md | 16 ++++ .../specs/module-packages/spec.md | 10 +++ .../changes/arch-05-bridge-registry/tasks.md | 89 +++++++++++-------- .../proposal.md | 3 + .../tasks.md | 1 + 6 files changed, 90 insertions(+), 37 deletions(-) diff --git a/openspec/changes/arch-05-bridge-registry/proposal.md b/openspec/changes/arch-05-bridge-registry/proposal.md index ae9b2b54..b15d9cbd 100644 --- a/openspec/changes/arch-05-bridge-registry/proposal.md +++ b/openspec/changes/arch-05-bridge-registry/proposal.md @@ -11,7 +11,10 @@ - **NEW**: Add `src/specfact_cli/registry/bridge_registry.py` with `SchemaConverter` protocol and `BridgeRegistry` for converter registration/discovery. - **MODIFY**: Extend module package metadata to declare `service_bridges` in `module-package.yaml`. - **MODIFY**: Extend module lifecycle registration to validate and register declared service bridges without direct core-to-module imports. +- **MODIFY**: Fix module protocol compliance detection so lifecycle reporting reflects real ModuleIOContract support (no false legacy results for compliant modules). +- **MODIFY**: Reduce lifecycle protocol logging noise (no duplicate warning lines; clear summary-first reporting). - **MODIFY**: Add backlog bridge converter implementations (ADO, Jira, Linear, GitHub) under module-local adapters and register them via manifest metadata. +- **MODIFY**: Complete ModuleIOContract migration coverage for remaining modules and verify registry reporting against upgraded modules. - **NEW**: Add user and developer documentation for bridge registry usage and custom bridge mappings. - **NEW**: Add tests for bridge registry behavior, manifest parsing, registration-time validation, and module integration. @@ -23,7 +26,7 @@ ### Modified Capabilities - `module-packages`: Extend module package manifest schema with declarative bridge metadata. -- `module-lifecycle-management`: Extend discovery/registration flow to validate and register bridge converters safely. +- `module-lifecycle-management`: Extend discovery/registration flow to validate/register bridge converters safely and report protocol compliance accurately without duplicate warnings. - `backlog-adapter`: Add bridge converter implementations and mapping behaviors for backlog service integrations. ## Impact @@ -32,10 +35,13 @@ - **Affected code**: - `src/specfact_cli/registry/bridge_registry.py` (new) - `src/specfact_cli/registry/module_packages.py` (bridge metadata loading and registration) + - `src/specfact_cli/common/logger_setup.py` (logging deduplication path if required by lifecycle reporting changes) - `src/specfact_cli/models/module_package.py` (service bridge metadata) + - `src/specfact_cli/modules/*/src/commands.py` (remaining ModuleIOContract migration where missing) - `src/specfact_cli/modules/backlog/src/adapters/*.py` (new converter modules) - `tests/unit/registry/test_bridge_registry.py` (new) - `tests/unit/registry/test_module_bridge_registration.py` (new) + - `tests/unit/specfact_cli/registry/test_module_packages.py` (protocol detection and reporting assertions) - **Affected documentation**: - `docs/reference/bridge-registry.md` (new) - `docs/guides/creating-custom-bridges.md` (new) diff --git a/openspec/changes/arch-05-bridge-registry/specs/module-lifecycle-management/spec.md b/openspec/changes/arch-05-bridge-registry/specs/module-lifecycle-management/spec.md index 12d8824b..9b56b723 100644 --- a/openspec/changes/arch-05-bridge-registry/specs/module-lifecycle-management/spec.md +++ b/openspec/changes/arch-05-bridge-registry/specs/module-lifecycle-management/spec.md @@ -36,3 +36,19 @@ The system SHALL degrade gracefully when individual bridge declarations fail. - **WHEN** a module declares a converter class that cannot be imported - **THEN** lifecycle registration SHALL skip that bridge declaration - **AND** continue registering other valid modules and bridges. + +### Requirement: Lifecycle protocol reporting is accurate and non-duplicative + +The system SHALL report ModuleIOContract compliance based on actual module capabilities and avoid duplicate warning emission. + +#### Scenario: Compliant module is not misreported as legacy + +- **WHEN** lifecycle registration inspects an enabled module that exposes required ModuleIOContract operations +- **THEN** compliance reporting SHALL classify it as full or partial support +- **AND** SHALL NOT classify it as legacy due to inspection-path mismatch. + +#### Scenario: Warning output is emitted once per condition + +- **WHEN** lifecycle registration logs protocol warnings during startup +- **THEN** each warning condition SHALL be emitted once per module/event +- **AND** a single summary line SHALL report aggregate full/partial/legacy counts. diff --git a/openspec/changes/arch-05-bridge-registry/specs/module-packages/spec.md b/openspec/changes/arch-05-bridge-registry/specs/module-packages/spec.md index b61a0765..a4995ef2 100644 --- a/openspec/changes/arch-05-bridge-registry/specs/module-packages/spec.md +++ b/openspec/changes/arch-05-bridge-registry/specs/module-packages/spec.md @@ -32,3 +32,13 @@ The system SHALL validate service bridge metadata structure before module regist - **WHEN** a manifest contains valid bridge declarations - **THEN** the parsed `ModulePackageMetadata` SHALL expose those declarations for lifecycle registration. + +### Requirement: Protocol metadata reflects real module operations + +The system SHALL derive protocol operation metadata from the effective module interface used at runtime. + +#### Scenario: Protocol operations are populated from runtime-accessible module interface + +- **WHEN** module metadata is loaded for an enabled module +- **THEN** protocol operation detection SHALL inspect the runtime-accessible interface used by lifecycle registration +- **AND** detected operations SHALL be persisted in `ModulePackageMetadata.protocol_operations`. diff --git a/openspec/changes/arch-05-bridge-registry/tasks.md b/openspec/changes/arch-05-bridge-registry/tasks.md index c2263d79..e5618fe0 100644 --- a/openspec/changes/arch-05-bridge-registry/tasks.md +++ b/openspec/changes/arch-05-bridge-registry/tasks.md @@ -60,52 +60,69 @@ Do not implement production code for new behavior until corresponding tests exis - [ ] 7.4 Ensure no direct core imports from module command internals - [ ] 7.5 Run `pytest tests/unit/registry/test_module_bridge_registration.py -v` and expect pass -## 8. Tests: backlog bridge converters (TDD) +## 8. Tests: protocol reporting accuracy and warning deduplication (TDD) -- [ ] 8.1 Add tests under `tests/unit/modules/backlog/` for converter contract compliance -- [ ] 8.2 Add tests for ADO, Jira, Linear, GitHub converter mapping behavior -- [ ] 8.3 Add tests for custom mapping override loading behavior -- [ ] 8.4 Run `pytest tests/unit/modules/backlog -k converter -v` and expect failure +- [ ] 8.1 Extend `tests/unit/specfact_cli/registry/test_module_packages.py` with protocol compliance detection assertions for full/partial/legacy modules +- [ ] 8.2 Add test coverage ensuring lifecycle warnings are not emitted twice for the same module condition +- [ ] 8.3 Add CLI smoke assertion (`specfact -v`) for single summary emission pattern +- [ ] 8.4 Run targeted registry tests and expect failure -## 9. Implementation: backlog bridge converters +## 9. Implementation: protocol reporting and logging cleanup -- [ ] 9.1 Add converter modules under `src/specfact_cli/modules/backlog/src/adapters/` -- [ ] 9.2 Update backlog module manifest to declare `service_bridges` -- [ ] 9.3 Ensure converters satisfy `SchemaConverter` protocol and contract decorators -- [ ] 9.4 Run `pytest tests/unit/modules/backlog -k converter -v` and expect pass +- [ ] 9.1 Update protocol inspection path in `src/specfact_cli/registry/module_packages.py` to classify compliant modules correctly +- [ ] 9.2 Ensure protocol operations are persisted on `ModulePackageMetadata.protocol_operations` from effective runtime interface +- [ ] 9.3 Eliminate duplicate warning emission in lifecycle startup logs (registry/logger integration) +- [ ] 9.4 Run targeted registry tests and expect pass -## 10. Quality gates and validation +## 10. Tests: backlog bridge converters (TDD) -- [ ] 10.1 Run `hatch run format` -- [ ] 10.2 Run `hatch run lint` -- [ ] 10.3 Run `hatch run type-check` -- [ ] 10.4 Run `hatch run contract-test` -- [ ] 10.5 Run `hatch run smart-test` -- [ ] 10.6 Run `openspec validate arch-05-bridge-registry --strict` +- [ ] 10.1 Add tests under `tests/unit/modules/backlog/` for converter contract compliance +- [ ] 10.2 Add tests for ADO, Jira, Linear, GitHub converter mapping behavior +- [ ] 10.3 Add tests for custom mapping override loading behavior +- [ ] 10.4 Run `pytest tests/unit/modules/backlog -k converter -v` and expect failure -## 11. Documentation research and review +## 11. Implementation: backlog bridge converters and module protocol migration completion -- [ ] 11.1 Identify affected docs: `docs/reference/`, `docs/guides/`, `README.md`, `docs/index.md` -- [ ] 11.2 Add `docs/reference/bridge-registry.md` with contract and usage examples -- [ ] 11.3 Add `docs/guides/creating-custom-bridges.md` with manifest and converter examples -- [ ] 11.4 Update `docs/reference/architecture.md` with bridge registry integration notes -- [ ] 11.5 Update `docs/_layouts/default.html` sidebar links for new docs +- [ ] 11.1 Add converter modules under `src/specfact_cli/modules/backlog/src/adapters/` +- [ ] 11.2 Update backlog module manifest to declare `service_bridges` +- [ ] 11.3 Ensure converters satisfy `SchemaConverter` protocol and contract decorators +- [ ] 11.4 Upgrade remaining modules to implement/ expose ModuleIOContract operations required for non-legacy classification +- [ ] 11.5 Run `pytest tests/unit/modules/backlog -k converter -v` and expect pass +- [ ] 11.6 Run module protocol tests and verify improved compliance summary -## 12. Version and changelog +## 12. Quality gates and validation -- [ ] 12.1 Determine semantic version bump for new capability -- [ ] 12.2 Sync version updates in `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` -- [ ] 12.3 Add CHANGELOG entry for bridge registry and manifest bridge metadata support +- [ ] 12.1 Run `hatch run format` +- [ ] 12.2 Run `hatch run lint` +- [ ] 12.3 Run `hatch run type-check` +- [ ] 12.4 Run `hatch run contract-test` +- [ ] 12.5 Run `hatch run smart-test` +- [ ] 12.6 Run `openspec validate arch-05-bridge-registry --strict` -## 13. GitHub issue creation +## 13. Documentation research and review -- [ ] 13.1 Create issue in `nold-ai/specfact-cli` with title `[Change] Bridge Registry for Cross-Module Service Interoperability` -- [ ] 13.2 Use labels `enhancement` and `change-proposal` -- [ ] 13.3 Build issue body from proposal Why/What Changes and append footer `*OpenSpec Change Proposal: arch-05-bridge-registry*` -- [ ] 13.4 Update `proposal.md` Source Tracking with issue number and URL +- [ ] 13.1 Identify affected docs: `docs/reference/`, `docs/guides/`, `README.md`, `docs/index.md` +- [ ] 13.2 Add `docs/reference/bridge-registry.md` with contract and usage examples +- [ ] 13.3 Add `docs/guides/creating-custom-bridges.md` with manifest and converter examples +- [ ] 13.4 Update `docs/reference/architecture.md` with bridge registry integration notes +- [ ] 13.5 Document protocol compliance reporting behavior and migration status in reference docs +- [ ] 13.6 Update `docs/_layouts/default.html` sidebar links for new docs -## 14. Create pull request to dev (LAST) +## 14. Version and changelog -- [ ] 14.1 Commit all completed work with conventional commit message -- [ ] 14.2 Push branch `feature/arch-05-bridge-registry` -- [ ] 14.3 Create PR to `dev` with OpenSpec change reference and quality gate evidence +- [ ] 14.1 Determine semantic version bump for new capability +- [ ] 14.2 Sync version updates in `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` +- [ ] 14.3 Add CHANGELOG entry for bridge registry, protocol-reporting fixes, and manifest bridge metadata support + +## 15. GitHub issue creation + +- [ ] 15.1 Create issue in `nold-ai/specfact-cli` with title `[Change] Bridge Registry for Cross-Module Service Interoperability` +- [ ] 15.2 Use labels `enhancement` and `change-proposal` +- [ ] 15.3 Build issue body from proposal Why/What Changes and append footer `*OpenSpec Change Proposal: arch-05-bridge-registry*` +- [ ] 15.4 Update `proposal.md` Source Tracking with issue number and URL + +## 16. Create pull request to dev (LAST) + +- [ ] 16.1 Commit all completed work with conventional commit message +- [ ] 16.2 Push branch `feature/arch-05-bridge-registry` +- [ ] 16.3 Create PR to `dev` with OpenSpec change reference and quality gate evidence diff --git a/openspec/changes/arch-06-enhanced-manifest-security/proposal.md b/openspec/changes/arch-06-enhanced-manifest-security/proposal.md index bf5ffc7e..2fa1c49b 100644 --- a/openspec/changes/arch-06-enhanced-manifest-security/proposal.md +++ b/openspec/changes/arch-06-enhanced-manifest-security/proposal.md @@ -4,6 +4,8 @@ `arch-05-bridge-registry` enables modular interoperability, but marketplace readiness still lacks trust guarantees for published modules. To prevent tampering and unsafe dependency drift, module manifests must carry integrity metadata and installation must verify checksums/signatures before enabling modules. +This change depends on `arch-05-bridge-registry` for stable lifecycle/protocol reporting behavior. Protocol false-legacy classification and duplicate lifecycle warning cleanup are owned by `arch-05`, not this change. + ## What Changes - **MODIFY**: Extend module manifest metadata (`ModulePackageMetadata`) with publisher identity, integrity fields, and versioned dependency entries. @@ -41,6 +43,7 @@ - **Integration points**: module manifest parsing, module install/registration paths, CI packaging/signing pipeline. - **Backward compatibility**: Backward compatible by default; unsigned modules remain possible only with explicit opt-in policy. - **Rollback plan**: Disable signature enforcement and fallback to checksum-only or legacy manifest fields while preserving compatibility parsing. +- **Out of scope**: ModuleIOContract migration completion and protocol warning deduplication (addressed in `arch-05-bridge-registry`). --- diff --git a/openspec/changes/arch-06-enhanced-manifest-security/tasks.md b/openspec/changes/arch-06-enhanced-manifest-security/tasks.md index 804a31d6..6d795f64 100644 --- a/openspec/changes/arch-06-enhanced-manifest-security/tasks.md +++ b/openspec/changes/arch-06-enhanced-manifest-security/tasks.md @@ -16,6 +16,7 @@ Do not implement production code for changed behavior until corresponding tests - [ ] 1.1 Ensure `dev` is current and create `feature/arch-06-enhanced-manifest-security` - [ ] 1.2 Verify current branch is `feature/arch-06-enhanced-manifest-security` +- [ ] 1.3 Confirm `arch-05-bridge-registry` protocol-reporting fixes are merged or explicitly cherry-picked prerequisite for this change ## 2. Tests: manifest security metadata models (TDD)