Skip to content

Commit 729a53b

Browse files
authored
docs: verify bounded workflow adoption planning (#743)
# Description Module #481 remains In Progress, while paired #483 remains Todo as checked on 12 October 2026. Preserve the newer proposal already on dev and defer core runtime adoption until its signed module contract is implemented. **Refs** #742 **Contract References**: Planning-only contract research and dependency reconciliation. No future runtime execution or delivery completion is claimed. ## Type of Change - [x] 📚 Documentation update ## Contract-First Testing Evidence Strict OpenSpec and local planned Requirements validate the proposal. Existing completed evidence is preserved with its original scope. Runtime adoption requires its own spec, actual failing-first tests, implementation and passing exact-head evidence. ## How Has This Been Tested? Validate source proposals, current repository contents and paired implementation readiness. Prerequisites [#761](#761) and [#767](#767) are merged at protected dev `c6af68a0`. Signed #743 head `4d1e7429` follows signed security parent `57f51829`, whose [native Requirements](https://github.com/nold-ai/specfact-cli/actions/runs/38306990823) is verified with no findings and whose exact-head authority passes. Strict selected OpenSpec, documentation validation and unchanged-provider planned Requirements pass locally: one source, planned maturity, no findings. Hosted producer/execution/final verdict must independently authenticate inherited root proof with scoped tokens; those current-head checks remain pending. ## Checklist - [x] Verify planning scope and preserve completed work - [x] Keep deferred runtime tasks unchecked - [x] Signed branch history and owner-authorized exact-head grants - [x] Protected prerequisite integration and signed restacking onto the validated root - [ ] Final exact-head Requirements, required CI and review closure ## Quality Gates Status Current signed head: `4d1e7429c2dfb69e9d33a93bf554aed8aae6affd`. Normal applicable hooks passed and GitHub signature verification precedes the authorized new djm81 grant. No required execution, signature, authority, review or security gate is bypassed. Final current-head checks and review remain required. ## Stack Native [stack #759](https://github.com/nold-ai/specfact-cli/pull/759): `dev ← #719 security implementation ← #743 workflow planning ← #751 roadmap planning`. Leave all three stack PRs unmerged for owner review. The earlier planning consumer ancestry failure is corrected by protected #767. Current hosted consumers must independently validate that correction with the fresh root proof; no gate or trust boundary is weakened. Independent Code Review correctly rejected the planned receipt as non-final execution proof (run 38303860784). The reviewed local protective follow-up preserves full protected-dev review and authentic finalized root proof; exact acceptance, native proof and protected integration remain pending. Current inherited review gates stay enforced; this PR is not yet ready to merge.
2 parents daefe0c + 859643f commit 729a53b

38 files changed

Lines changed: 5994 additions & 148 deletions

‎CHANGELOG.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,35 @@ All notable changes to this project will be documented in this file.
1010

1111
---
1212

13+
## [0.55.10] - 2026-10-13
14+
15+
### Security
16+
17+
- Reject malformed alternate project manifests during authenticated admission without aborting CLI startup.
18+
19+
- Require authenticated project authority for indirect category mounts and shared member loaders, including bundle aliases and cross-category claims.
20+
21+
- Bind privileged project registration metadata and executable inventory to authenticated artifact bytes; reproduce source caches before the final file check and recheck authority before registration effects.
22+
23+
- Reject category-less grouped workspace root commands, external claims to permanent core commands and
24+
unauthenticated workspace claims to official category roots before registry, bridge or import-source activation.
25+
- Preserve resolved built-in authority, reject forged source labels and escaping symlinks, and prevent
26+
rejected workspace sources from shadowing eligible package dependencies.
27+
- Reject unsigned executable caches and omitted Python/native artifacts; authenticate captured signed source
28+
bytes before reproducing compatible interpreter caches without executing candidate code.
29+
30+
### Fixed
31+
32+
- Select the first fully eligible copy of each module, reconsider dependency fallbacks against selected versions
33+
and each candidate's own version, and refuse contradictory priority cycles before registration effects.
34+
- Preserve categorized routing and supported unreserved legacy registration, including operator-configured
35+
built-in discovery, while retaining the completed removal of flat bundle shims.
36+
- Preserve all six official project-scoped bundle roots only after full artifact checksum and signature
37+
verification against the core-bundled key; reject unsigned, tampered and workspace-key replacements.
38+
- Preserve genuine installed bundles when a rejected project copy claims the same name, retain authenticated
39+
project priority, and skip artifact payload verification for disabled module names.
40+
- Synchronize bugfix version declarations, frozen project metadata and the promotion fixture.
41+
1342
## [0.55.9] - 2026-10-13
1443

1544
### Security

‎docs/reference/module-categories.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ nav_order: 35
55
permalink: /reference/module-categories/
66
doc_owner: specfact-cli
77
tracks: [src/specfact_cli/registry/**, ../specfact-cli-modules/packages/**]
8-
last_reviewed: 2026-07-10
8+
last_reviewed: 2026-10-11
99
exempt: false
1010
exempt_reason: ""
1111
---
@@ -91,6 +91,15 @@ Namespace mapping:
9191
Compatibility note:
9292

9393
- Flat top-level command shims were removed. Use category groups (`project`, `backlog`, `code`, `spec`, `govern`, `requirements`).
94+
- Category-less workspace modules are skipped in default grouped mode. Add category/bundle metadata to
95+
use the supported grouped surface. Explicitly disabling grouping preserves unreserved legacy workspace
96+
commands; category-less user, marketplace and custom sources retain their compatibility path.
97+
- Permanent core commands (`init`, `module`, `upgrade`) are reserved for resolved built-in package paths.
98+
Operator-selected built-in discovery remains supported. External packages cannot extend these roots
99+
by declaring a core category, name or source label. Workspace packages also cannot supply official
100+
category root command apps in either mode. Rejected packages contribute no active import roots,
101+
schema extensions, service bridges or category mounts. Eligible categorized execution remains
102+
intentional extension behavior; this guard is not a sandbox.
94103
- `specfact backlog auth ...` is provided by the backlog bundle, not by the permanent core command surface.
95104
- Prerelease `specfact-requirements` manifests that still declare category
96105
`project` with `bundle_group_command: requirements` are normalized to the

‎docs/reference/module-security.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,34 @@ Module packages carry **publisher** and **integrity** metadata so installation,
1919
- **Publisher trust gate**: Non-official publishers require one-time explicit trust (interactive confirmation or `--trust-non-official` / `SPECFACT_TRUST_NON_OFFICIAL`).
2020
- **Denylist gate**: Modules listed in denylist are blocked before install/bootstrap regardless of source.
2121

22+
## Workspace command authority
23+
24+
Default grouped registration rejects category-less project modules before registration or import effects.
25+
Permanent `init`, `module` and `upgrade` commands require resolved built-in package paths in both modes.
26+
Unverified workspace packages cannot supply the official `project`, `backlog`, `code`, `spec`, `govern` or
27+
`requirements` roots. Supported official bundles installed with `--scope project` retain their canonical roots
28+
only after complete filesystem checksum and signature verification, including untracked module source files,
29+
against the public key bundled with the CLI and matching
30+
signed official bundle metadata. Payload symlink members, standalone bytecode, uncovered executable source and missing keys fail closed.
31+
Current-interpreter source caches remain compatible only when their compiled bytes match the signed source.
32+
Verification compares those bytes without executing or deserializing candidate caches. Unsigned/test flags, installation receipts and
33+
`SPECFACT_MODULE_PUBLIC_KEY_PEM` overrides cannot grant these project root commands.
34+
35+
Categorized project packages can populate shared category-member loaders even when their commands do not name a
36+
root. They therefore require authenticated official bundle authority before candidate selection and registration.
37+
The same gate covers category mounts induced by explicit bundle metadata or namespaced bundle aliases.
38+
Explicit legacy registration retains unreserved category-less project commands without an official mount claim;
39+
non-project categorized routing retains its existing policy. These controls protect command admission and import activation, and do not sandbox intentionally
40+
invoked module code.
41+
42+
## Preparing project-scoped release artifacts
43+
44+
Publish regular payload files rather than symlinks. Replace links with their intended files before signing;
45+
remove standalone bytecode and executable files under directories excluded from signing. Regenerate ordinary
46+
source caches with the target interpreter, or remove stale or transformed caches before project installation.
47+
The strict project-root admission check independently verifies these conditions. Passing a companion repository
48+
signing or release-verification command alone does not establish eligibility for privileged project roots.
49+
2250
## Integrity flow
2351

2452
1. Discovery reads `module-package.yaml` and parses `integrity.checksum`.
@@ -104,3 +132,9 @@ Module packages carry **publisher** and **integrity** metadata so installation,
104132
## Versioned dependencies
105133

106134
Manifest may declare versioned module and pip dependencies via `module_dependencies_versioned` and `pip_dependencies_versioned` (each entry: `name`, `version_specifier`). These are parsed and stored for installation-time resolution while keeping legacy `module_dependencies` / `pip_dependencies` lists backward compatible.
135+
136+
Privileged project-root admission binds discovery fields to the same normalized manifest captured in the signed
137+
payload. It also completes reproduction of any permitted source caches before checking a fresh executable inventory.
138+
The final check compares membership, source/native digests and raw cache bodies without executing candidate code or
139+
invoking compilation. Admission and its recheck precede schema, bridge, protocol and import-root registration effects.
140+
These checks authenticate the admission snapshot; they do not make a mutable workspace immutable after admission.

‎openspec/INTEGRATION.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@ This document is the living ownership contract for active SpecFact OpenSpec
44
changes. It exists to keep parallel roadmap work aligned without creating a
55
separate product feature for integration governance.
66

7+
## Ordinary workflow ownership
8+
9+
- Paired `workflow-01-turn-orchestration` assigns reusable `specfact workflow` execution, bundled workflow skills, producer adapters and disposable local receipts to modules #483; core #742 owns repository settings, check-only gate adapters, thin wrapper projection and signed adoption/pilot.
10+
- This unsealed ordinary path does not replace optional preflight/checkpoint/conformance. Seal-bound behavior stays with its existing owners and applies only on explicit assurance selection.
11+
- R09 owns current-run Requirements claims; its module reconciler remains free of Git/test/network execution. Governance owns durable evidence envelopes, traceability owns artifact semantics, and C15 owns calibrated review policy. A workflow findings projection preserves original producer identities/outcomes and cannot fuse verdicts or silently extend ReviewReport.
12+
- Standalone verify and ordinary CI require no prior local receipts. Local progress cannot authenticate itself for protected CI. Generic #251/#253 still owns customer installation/export and general generated references; repository wrapper projection is a separate development convenience.
13+
- Release direction is modules #481 -> workflow modules #483 -> core #742 runtime adoption. Independent projection has no signed-runtime prerequisite. Related optional assurance/graph/findings work is not a blanket blocker.
14+
- Runtime integration/adoption validates exact signed #481 schema-v3 current_execution and actual core/#483 compatibility before selecting the workflow combination; a signed workflow alone is insufficient. Projection remains independent.
15+
716
## Positioning
817

918
SpecFact is the local validation and AI-bloat defense CLI. Active changes SHALL

0 commit comments

Comments
 (0)