fix: module signing automation, startup integrity UX, and v0.37.3 release prep

.github/workflows/pr-orchestrator.yml

@@ -635,12 +635,20 @@ jobs:
           fi
           python -m pip install --upgrade pip
           python -m pip install pyyaml cryptography cffi
-          mapfile -t MANIFESTS < <(find src/specfact_cli/modules -name 'module-package.yaml' -type f)
-          if [ "${#MANIFESTS[@]}" -eq 0 ]; then
-            echo "No bundled module manifests found to sign."
-            exit 0
+          python - <<'PY'
+          import cffi
+          import cryptography
+          import yaml
+
+          print("✅ signing dependencies available:", yaml.__version__, cryptography.__version__, cffi.__version__)
+          PY
+          BASE_REF="${{ github.event.before }}"
+          if [ -z "$BASE_REF" ] || [ "$BASE_REF" = "0000000000000000000000000000000000000000" ]; then
+            BASE_REF="HEAD~1"
           fi
-          python scripts/sign-modules.py "${MANIFESTS[@]}"
+          git rev-parse --verify "$BASE_REF" >/dev/null 2>&1 || BASE_REF="HEAD~1"
+          echo "Using module-signing base ref: $BASE_REF"
+          python scripts/sign-modules.py --changed-only --base-ref "$BASE_REF" --bump-version patch
 
       - name: Get version from PyPI publish step
         id: get_version

CHANGELOG.md

@@ -8,6 +8,22 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 
+---
+
+## [0.37.3] - 2026-02-24
+
+### Changed
+
+- Improved bundled module release workflow by adding changed-module-only signing automation (`--changed-only`, `--base-ref`, `--bump-version`) so module versions remain decoupled from CLI version and only changed modules are bumped/signed.
+- Updated CI release signing flow in PR orchestrator to use changed-module signing with resilient base-ref resolution and explicit signing dependency checks on GitHub runners.
+- Updated developer documentation for module signing to use portable key-file configuration patterns instead of absolute key paths.
+
+### Fixed
+
+- Suppressed startup checksum fallback noise in normal CLI operation; fallback diagnostics are now debug-only.
+- Improved startup integrity failure UX with user-friendly risk warning and mitigation guidance while preserving raw checksum diagnostics in `--debug` mode.
+- Fixed `specfact backlog map-fields` GitHub setup behavior to fail fast when repository issue type IDs are unavailable instead of persisting incomplete type mapping state.
+
 ---
 
 ## [0.37.2] - 2026-02-24

docs/guides/module-marketplace.md

@@ -60,8 +60,11 @@ Additional local hardening:
 Release signing automation:
 
 - `scripts/sign-modules.py` updates manifest integrity metadata (checksum and optional signature)
-- Use `python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem <manifest...>` for local/manual signing
-- Wrapper alternative: `bash scripts/sign-module.sh --key-file /secure/path/module-signing-private.pem <manifest>`
+- Use `KEY_FILE="${SPECFACT_MODULE_PRIVATE_SIGN_KEY_FILE:-.specfact/sign-keys/module-signing-private.pem}"` and run `python scripts/sign-modules.py --key-file "$KEY_FILE" <manifest...>` for local/manual signing
+- Use changed-only automation to avoid re-signing all modules:
+  - `hatch run python scripts/sign-modules.py --key-file "$KEY_FILE" --changed-only --base-ref origin/dev --bump-version patch`
+  - this bumps/signs only changed modules and keeps module versioning decoupled from CLI package version
+- Wrapper alternative: `bash scripts/sign-module.sh --key-file "$KEY_FILE" <manifest>`
 - Without key material, the script fails by default and recommends `--key-file`; checksum-only mode is explicit via `--allow-unsigned` (local testing only)
 - Encrypted keys are supported with passphrase via `--passphrase`, `--passphrase-stdin`, or `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`
 - CI workflows inject private key material via `SPECFACT_MODULE_PRIVATE_SIGN_KEY` and passphrase via `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`

docs/guides/module-signing-and-key-rotation.md

@@ -44,37 +44,53 @@ openssl pkey -in module-signing-private.pem -pubout -out module-signing-public.p
 Preferred (strict, with private key):
 
 ```bash
-python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem src/specfact_cli/modules/*/module-package.yaml
-python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem modules/*/module-package.yaml
+KEY_FILE="${SPECFACT_MODULE_PRIVATE_SIGN_KEY_FILE:-.specfact/sign-keys/module-signing-private.pem}"
+python scripts/sign-modules.py --key-file "$KEY_FILE" src/specfact_cli/modules/*/module-package.yaml
+python scripts/sign-modules.py --key-file "$KEY_FILE" modules/*/module-package.yaml
 ```
 
 Encrypted private key options:
 
 ```bash
 # Prompt interactively for passphrase (TTY)
-python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem modules/backlog-core/module-package.yaml
+python scripts/sign-modules.py --key-file "$KEY_FILE" modules/backlog-core/module-package.yaml
 
 # Explicit passphrase flag (avoid shell history when possible)
-python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem --passphrase '***' modules/backlog-core/module-package.yaml
+python scripts/sign-modules.py --key-file "$KEY_FILE" --passphrase '***' modules/backlog-core/module-package.yaml
 
 # Passphrase over stdin (CI-safe pattern)
 printf '%s' "$SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE" | \
-  python scripts/sign-modules.py --key-file /secure/path/module-signing-private.pem --passphrase-stdin modules/backlog-core/module-package.yaml
+  python scripts/sign-modules.py --key-file "$KEY_FILE" --passphrase-stdin modules/backlog-core/module-package.yaml
 ```
 
 Versioning guard:
 
 - The signer enforces module version increments for changed module contents.
 - If module files changed and version is unchanged, signing fails until version is bumped.
 - Override exists for exceptional local workflows: `--allow-same-version` (not recommended).
+- Module versions are independent from CLI package version; bump only modules whose payload changed.
+
+Changed-modules automation (recommended for release prep):
+
+```bash
+# Bump changed modules by patch and sign only those modules
+hatch run python scripts/sign-modules.py \
+  --key-file "$KEY_FILE" \
+  --changed-only \
+  --base-ref origin/dev \
+  --bump-version patch
+
+# Verify after signing
+hatch run python scripts/verify-modules-signature.py --require-signature --enforce-version-bump --version-check-base origin/dev
+```
 
 Wrapper for single manifest:
 
 ```bash
-bash scripts/sign-module.sh --key-file /secure/path/module-signing-private.pem modules/backlog-core/module-package.yaml
+bash scripts/sign-module.sh --key-file "$KEY_FILE" modules/backlog-core/module-package.yaml
 # stdin passphrase:
 printf '%s' "$SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE" | \
-  bash scripts/sign-module.sh --key-file /secure/path/module-signing-private.pem --passphrase-stdin modules/backlog-core/module-package.yaml
+  bash scripts/sign-module.sh --key-file "$KEY_FILE" --passphrase-stdin modules/backlog-core/module-package.yaml
 ```
 
 Local test-only unsigned mode:

docs/reference/module-security.md

@@ -37,6 +37,8 @@ Module packages carry **publisher** and **integrity** metadata so installation,
   - `SPECFACT_MODULE_PRIVATE_SIGN_KEY` (PEM content)
   - `SPECFACT_MODULE_PRIVATE_SIGN_KEY_FILE`
 - **Version guard**: Changed module contents must have a bumped module version before signing. Override exists only for controlled local cases via `--allow-same-version`.
+- **Changed-only release mode**: `scripts/sign-modules.py --changed-only --base-ref <git-ref> --bump-version <patch|minor|major>` auto-selects modules with payload changes, bumps versions when unchanged, and signs only those modules.
+- **Version decoupling**: module versions are semver-managed per module payload and do not need to track CLI package version.
 - **CI secrets**:
   - `SPECFACT_MODULE_PRIVATE_SIGN_KEY`
   - `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`

openspec/changes/backlog-core-05-user-modules-bootstrap/CHANGE_VALIDATION.md

@@ -1,6 +1,12 @@
 # Change Validation Report: backlog-core-05-user-modules-bootstrap
 
 - Status: valid
-- Validation command: `openspec validate backlog-core-05-user-modules-bootstrap --strict`
+- Workflow: `wf-validate-change` (executed via OpenSpec CLI equivalents)
+- Validation command(s):
+  - `openspec status --change "backlog-core-05-user-modules-bootstrap" --json`
+  - `openspec instructions apply --change "backlog-core-05-user-modules-bootstrap" --json`
+  - `openspec validate backlog-core-05-user-modules-bootstrap --strict`
 - Validation result: `Change 'backlog-core-05-user-modules-bootstrap' is valid`
-- Notes: CLI validation passed; local environment emitted non-blocking telemetry network flush warnings.
+- Notes:
+  - Status/instructions confirmed spec-driven schema and artifact completeness.
+  - Validation emitted non-blocking schema warnings from `openspec/config.yaml` rule format, but strict change validation succeeded.

openspec/changes/backlog-core-05-user-modules-bootstrap/TDD_EVIDENCE.md

@@ -123,3 +123,84 @@
 - Result summary:
   - `63 passed` across signing-artifacts, module-security, installer, and module command suites.
   - Formatting checks passed after implementation.
+
+## Follow-up failing run (integrity fallback log-level noise)
+
+- Timestamp: 2026-02-24T21:26:13Z
+- Command(s): `python -m pytest tests/unit/registry/test_module_installer.py -k "fallback_does_not_emit_info_in_normal_mode or fallback_emits_debug_in_debug_mode" -q`
+- Failure summary:
+  - `test_verify_module_artifact_fallback_does_not_emit_info_in_normal_mode` failed because `verify_module_artifact` emitted fallback details via `logger.info(...)` in non-debug mode.
+  - `test_verify_module_artifact_fallback_emits_debug_in_debug_mode` failed because fallback diagnostics were not emitted through debug-level logging.
+
+## Follow-up passing run (integrity fallback log-level noise)
+
+- Timestamp: 2026-02-24T21:26:13Z
+- Command(s):
+  - `python -m pytest tests/unit/registry/test_module_installer.py -k "fallback_does_not_emit_info_in_normal_mode or fallback_emits_debug_in_debug_mode" -q`
+  - `python -m pytest tests/unit/registry/test_module_installer.py -q`
+- Result summary:
+  - Targeted fallback-log tests: `2 passed`.
+  - Full installer test file: `20 passed`.
+
+## Follow-up failing run (GitHub map-fields missing issue-type IDs)
+
+- Timestamp: 2026-02-24T21:42:09Z
+- Command(s): `python -m pytest tests/unit/commands/test_backlog_commands.py -k "map_fields_github_provider_persists_backlog_config or map_fields_github_provider_fails_when_issue_types_unavailable" -q`
+- Failure summary:
+  - `test_map_fields_github_provider_fails_when_issue_types_unavailable` failed because `backlog map-fields` returned success even when repository issue types were empty/unavailable.
+  - This left `github_issue_types.type_ids` unconfigured and allowed `backlog add` to keep warning despite setup attempts.
+
+## Follow-up passing run (GitHub map-fields missing issue-type IDs)
+
+- Timestamp: 2026-02-24T21:42:09Z
+- Command(s):
+  - `python -m pytest tests/unit/commands/test_backlog_commands.py -k "map_fields_github_provider_persists_backlog_config or map_fields_github_provider_fails_when_issue_types_unavailable" -q`
+  - `python -m pytest modules/backlog-core/tests/unit/test_add_command.py -k "warns_when_github_issue_type_mapping_missing" -q`
+- Result summary:
+  - GitHub map-fields targeted tests: `2 passed`.
+  - Backlog add warning path regression check: `1 passed`.
+
+## Follow-up failing run (startup integrity warning noise)
+
+- Timestamp: 2026-02-24T22:54:14+01:00
+- Command(s): `hatch run specfact module list`
+- Failure summary:
+  - Startup emitted raw logger warning with checksum internals:
+    - `Module backlog: Integrity check failed: Checksum mismatch: ...`
+  - Warning was noisy and not user-guided, and exposed technical checksum detail in normal mode.
+
+## Follow-up passing run (startup integrity warning UX + debug separation)
+
+- Timestamp: 2026-02-24T22:57:56+01:00
+- Command(s):
+  - `python -m pytest tests/unit/registry/test_module_installer.py -k "checksum_mismatch_hides_raw_details_without_debug or checksum_mismatch_logs_raw_details_in_debug" -q`
+  - `python -m pytest tests/unit/specfact_cli/registry/test_module_packages.py -k "integrity_failure_shows_user_friendly_risk_warning" -q`
+  - `PYTHONPATH=src python -m specfact_cli.cli module list`
+  - `PYTHONPATH=src python -m specfact_cli.cli --debug module list`
+- Result summary:
+  - New debug-gating tests: `3 passed`.
+  - User-warning UX test: `1 passed`.
+  - CLI startup now shows a concise risk warning with mitigation guidance (`specfact module init`) instead of raw checksum mismatch internals in normal mode.
+  - With `--debug`, raw checksum mismatch diagnostics are shown for troubleshooting.
+
+## Follow-up failing run (changed-module release automation)
+
+- Timestamp: 2026-02-24T23:05:56+01:00
+- Command(s): `python -m pytest tests/unit/specfact_cli/registry/test_signing_artifacts.py -k "changed_module_automation or changed_only_auto_bump" -q`
+- Failure summary:
+  - `test_sign_modules_py_help_mentions_changed_module_automation` failed because signer help did not expose changed-module automation flags.
+  - `test_sign_modules_py_changed_only_auto_bump_and_sign` failed because `sign-modules.py` did not accept `--changed-only`, `--base-ref`, or `--bump-version`.
+
+## Follow-up passing run (changed-module release automation)
+
+- Timestamp: 2026-02-24T23:08:05+01:00
+- Command(s):
+  - `python -m pytest tests/unit/specfact_cli/registry/test_signing_artifacts.py -k "changed_module_automation or changed_only_auto_bump" -q`
+  - `python -m pytest tests/unit/specfact_cli/registry/test_signing_artifacts.py -q`
+  - `python scripts/sign-modules.py --allow-unsigned --changed-only --base-ref HEAD --bump-version patch`
+  - `python -m pytest tests/unit/registry/test_module_installer.py tests/unit/specfact_cli/registry/test_module_packages.py tests/unit/commands/test_backlog_commands.py -q`
+- Result summary:
+  - New changed-module automation tests: `2 passed`.
+  - Full signing-artifacts suite: `15 passed`.
+  - Changed-only automation bumped and re-signed changed bundled manifest (`backlog`), restoring runtime integrity sync.
+  - Regression safety suites after module re-sign: `95 passed, 1 skipped`.

openspec/changes/backlog-core-05-user-modules-bootstrap/proposal.md

@@ -5,6 +5,7 @@
 
 
 
+
 `specfact backlog add` is still missing in installed-runtime contexts when command discovery depends on repository-local `modules/` folders. This makes behavior vary by working directory and machine.
 
 For production usage, shipped modules and their resources should be managed as user-level artifacts. We need a reliable path where `specfact module init` prepares a per-user module root (not repo-local) so command availability is stable.
@@ -14,6 +15,7 @@ For production usage, shipped modules and their resources should be managed as u
 
 
 
+
 - **MODIFY**: Add a canonical user module root at `<user-home>/.specfact/modules` for installed module artifacts.
 - **MODIFY**: Ensure discovery and installer flows prefer `<user-home>/.specfact/modules` and stop treating workspace `./modules` as an automatic discovery root.
 - **MODIFY**: Add workspace-local module discovery only under `<repo>/.specfact/modules` to avoid claiming ownership of non-SpecFact repository paths.
@@ -31,6 +33,8 @@ For production usage, shipped modules and their resources should be managed as u
 - **NEW**: Require signature/checksum verification for shipped/bundled modules using release-generated signatures (not publisher-name trust alone).
 - **NEW**: Add release signing automation for bundled modules in this repository so module signatures are generated during release orchestration without exposing private keys.
 - **NEW**: Support encrypted signing keys with passphrase input via CLI flag, stdin, or environment variable, and wire CI signing steps to dedicated secrets (`SPECFACT_MODULE_PRIVATE_SIGN_KEY`, `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE`).
+- **NEW**: Add changed-module release automation that selects only modules with payload changes, applies module-level semver bump, and performs bump/sign/verify in one workflow.
+- **MODIFY**: Treat bundled module versions as independent semver from CLI package version; only changed module payloads require module version increments.
 - **MODIFY**: Document and codify boundary with `marketplace-02`: this change hardens local/shipped module trust and install safety; online multi-registry ecosystem remains in `marketplace-02`.
 - **MODIFY**: Add tests for init/module discovery parity that verify `backlog add` availability does not depend on current working directory.
 - **MODIFY**: Strengthen prompt resource detection/copy tests so `specfact init ide` consistently finds bundled prompt resources and installs them to project target locations.
@@ -48,6 +52,6 @@ For production usage, shipped modules and their resources should be managed as u
 <!-- source_repo: nold-ai/specfact-cli -->
 - **GitHub Issue**: #298
 - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/298>
-- **Last Synced Status**: implemented
+- **Last Synced Status**: proposed
 - **Sanitized**: false
 <!-- content_hash: deb60d1fd1a5ed08 -->

openspec/changes/backlog-core-05-user-modules-bootstrap/specs/backlog-map-fields/spec.md

@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Provider auth and field discovery checks
+
+The system SHALL verify auth context and discover provider fields/metadata before accepting mappings.
+
+#### Scenario: GitHub mapping fails when repository issue types are unavailable
+
+- **GIVEN** GitHub provider mapping setup is requested
+- **AND** repository issue types cannot be discovered (API failure, missing scope, or empty response)
+- **WHEN** `specfact backlog map-fields` runs
+- **THEN** the command exits non-zero with actionable guidance
+- **AND** it does not report successful GitHub type mapping persistence.
+
+#### Scenario: GitHub mapping persists repository issue-type IDs for add flow
+
+- **GIVEN** repository issue types are discovered from GitHub metadata
+- **WHEN** `specfact backlog map-fields` persists GitHub settings
+- **THEN** `.specfact/backlog-config.yaml` includes `backlog_config.providers.github.settings.github_issue_types.type_ids`
+- **AND** subsequent `specfact backlog add` can consume those IDs for issue-type updates.