From 06a7704aee28a7d5ea3446efae856629b57eee73 Mon Sep 17 00:00:00 2001 From: DJConnect Date: Tue, 8 Sep 2026 12:18:37 +0200 Subject: [PATCH] docs: define policy-aware release and installer composition roadmap --- BOOTSTRAP.md | 5 +- docs/architecture/POLICY_AWARE_COMPOSITION.md | 192 ++++++++++++++++++ docs/roadmap/POLICY_GOVERNANCE_V1.md | 46 +++++ docs/roadmap/README.md | 10 +- 4 files changed, 251 insertions(+), 2 deletions(-) create mode 100644 docs/architecture/POLICY_AWARE_COMPOSITION.md create mode 100644 docs/roadmap/POLICY_GOVERNANCE_V1.md diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index 2a06e5e..140a1bc 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -10,7 +10,10 @@ entrypoint. Read, in order: 3. `docs/architecture/FORGE_PLATFORM_ARCHITECTURE.md` and `docs/architecture/OWNERSHIP_MATRIX.md` for product boundaries; 4. `docs/roadmap/README.md` and `docs/development/TDE_INTEGRATION.md` for - local planning and delivery evidence. + local planning and delivery evidence; +5. for policy/version/release work, `docs/architecture/POLICY_AWARE_COMPOSITION.md` + and `docs/roadmap/POLICY_GOVERNANCE_V1.md`. These route the coordinated + documentation target without making this product a peer policy authority. Validate the checkout offline with `sh scripts/validate.sh`. The generated projection is committed evidence, not a live dependency on another checkout or diff --git a/docs/architecture/POLICY_AWARE_COMPOSITION.md b/docs/architecture/POLICY_AWARE_COMPOSITION.md new file mode 100644 index 0000000..10884e2 --- /dev/null +++ b/docs/architecture/POLICY_AWARE_COMPOSITION.md @@ -0,0 +1,192 @@ +# Policy-aware artifact and deployment composition + +## Decision and scope + +Increment: `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`. +This is the Forge Platform-owned architecture in a coordinated documentation and +roadmap increment. It is target authority on owning `main`, `PENDING_PR` otherwise. +It implements no installer, schema, version helper, workflow, policy service, +manifest migration or runtime activation. It grants no merge/publish/install rights. + +Baseline observed 2026-09-08: Forge Platform main +`bbdb299ca06217b69220db02c4cc3e86df67a009`. +The [architecture](FORGE_PLATFORM_ARCHITECTURE.md), +[ownership matrix](OWNERSHIP_MATRIX.md), [compatibility contract](COMPATIBILITY.md) +and [discovery/pairing contract](INSTANCE_DISCOVERY_AND_PAIRING_CONTRACT.md) +retain their product boundaries. The [policy roadmap](../roadmap/POLICY_GOVERNANCE_V1.md) +extends the existing composition horizon. + +Shared semantics: `pcvantol/forge:docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md`, +proposal [Forge #50](https://github.com/pcvantol/forge/pull/50). +EP target: [EP #103](https://github.com/pcvantol/engineering-platform/pull/103). +Workspace consumer target: [Workspace #15](https://github.com/pcvantol/workspace/pull/15). +These are coordinated owner proposals, not installed capability evidence. + +## One administration experience, independent policy owners + +Forge owns native planning/progression/version-release policy and impact reasoning. +EP owns actual execution, admission, validation/assurance, provider constraints, +repair accounting, qualification and execution receipts. Workspace owns role-aware +human policy-management and historical projection. Forge Platform owns composition, +deployment presets, installer compatibility, updates and installation receipts. + +Forge maintaining shared policy vocabulary does not give it a global policy +server. Forge Platform maintaining deployment compatibility does not give it +another product's rule evaluator or canonical version source. The installer must +not write peer SQL/files as a shortcut to policy activation. + +## Existing baseline and migration concerns + +| Concern | Source or proposal | Target disposition | +| --- | --- | --- | +| Product/component ownership | Main architecture and ownership matrix | Preserve independently owned Forge Runtime, EP Server/Agent and Workspace Server/Client artifacts | +| Deployment presets | Main architecture and deployment ADRs | Catalogue as Forge Platform-owned configuration constrained by artifact/host/trust compatibility | +| Policy discovery/management | No implemented generic policy service established by this documentation baseline | Future logical interfaces consumed through owner APIs; no implied availability from a diagram | +| Independent versions | Main compatibility contract | Preserve product/component versions separately from API/schema/policy versions and artifact digests | +| Canonical versioning | Pending #17 at `dee34d2685037ae8621ef878c19626fcc9723625` | Reconcile independent push-bump workflow with native Forge release operations; no approval or code change here | +| Artifact-gated composition | Pending #16 at `17b107b3ace6c5084b9731b9c5d2b6425d20b0aa` | Preserve its owning artifact dependency proposal; policy compatibility supplements, not replaces, release evidence | + +Each owned rule must be classified as invariant, governed policy, operational +configuration, authorization grant, runtime fact or implementation limit. A preset +selection does not grant install/merge rights or turn unavailable runtime policy +features into supported ones. + +## Version and release authority + +`FORGE::VERSION_RELEASE_MANAGEMENT_V1` plans version/release operations for managed +products under their approved policy. Product repositories retain the exact +canonical version source and compatibility promise; EP executes authorized +repository/build/publish Actions. Forge Platform consumes their qualified published +artifacts and independently versions its own distribution product. + +A repository can contain multiple independently releaseable components. The +owning contract decides shared versus independent series; the installer must not +assume repository = package = component = version. Equal initial numbers do not +prove compatibility, and this document selects no baseline or new product version. + +The policy describes one source per product/component, which may be pyproject or +a dedicated version manifest. Different source formats are valid when explicitly +owned; all package/UI/runtime projections must be derived and checked. No second +allocator may run beside an active Forge-managed operation. Standalone EP retains +an explicit local operation policy when it is not Forge-managed. + +Branch-event numbering can be a preference but is not semantic compatibility, +major approval or publication permission. Release decisions bind operation ID, +approved source, version, scope, actor/grant and immutable artifact evidence. +A branch name or matching commit subject alone cannot authorize publication or +establish exactly-once allocation. + +Retain the reviewed acceptance requirements for future implementation: +field-specific projections, strict product/schema/type validation, interruption-safe +complete changes, expected-head/idempotent operations, version preparation before +final qualification, build without source/version mutation, separate source and +installed checks, qualified final bot-created head where one exists, and no +replacement of published identity with different artifact content. These address +the SemVer review findings; they are not claimed fixes to pending implementation. + +## Required composition descriptor semantics + +A future component entry must distinguish at least: + +| Meaning | Required evidence | +| --- | --- | +| Product/component identity | Exact product and releaseable role; no filename-only inference | +| Product release | Explicit product version and publication identity | +| Source identity | Qualified source revision and candidate-to-delivery relationship | +| Installable bytes | Artifact name/URI, digest algorithm and exact digest | +| Artifact qualification | Producer qualification/provenance and supported platform/architecture | +| Runtime/API compatibility | Explicit supported contracts, not equality of product version numbers | +| Policy compatibility | Supported policy schema/evaluator/capability versions and required obligations | +| Activation/deployment | Selected policy references and owner acceptance/activation receipts for the target | + +This table is a documentation contract, not a new implemented manifest schema. +Do not prematurely write invented checksums, active policies or future source SHAs +into a definitive manifest. Policy support advertised by an artifact requires +actual qualification; an unrecognized version or missing required policy blocks +that component combination rather than being silently ignored. + +The composition can distribute verified policy definitions/presets where their +owner contract allows it, but selection and activation use the owner's API and +appropriate authority. No executable policy scripts or hidden rule interpreter +are shipped as a side channel. Secrets remain in their secure product/host stores. + +## Cross-repository release dependency example + +For a Mission to make EP Execution Agents installable: + +```text +EP Agent/protocol implementation -> qualified version/build/publication --+ + | +Forge Platform Agent-role installer support ----------------------------+ + v + final component manifest + policy compatibility + -> installer qualification +``` + +Forge decides the Action graph. Independent producer and installer work may be +eligible in parallel; EP owns actual execution/leases/capacity. The final manifest +waits for actual qualified published Server/Agent artifacts and applicable policy +contracts, not merely a merged source PR or a version string. The same rule later +applies to Forge Server and Workspace Server/Client. Forge Platform does not +invent or enforce a competing execution DAG. + +## One, two or three server roles and partial availability + +EP-only, Forge+EP, Workspace+EP, all-server and remote-peer configurations remain +valid. Optional Workspace UI is not required for policy enforcement. A server can +operate under its approved local policy while an optional peer is absent. + +Installation/update flow: select verified component combination -> verify +artifact/runtime/policy compatibility -> establish authorized pinned identity -> +prepare owner-specific settings/activation -> read owner receipts -> qualify the +actual installation. Discovery produces candidates only; it grants neither policy +activation nor execution authority. Existing trusted identity is not silently +replaced by a newly discovered endpoint. + +Cross-product activation is not an atomic SQL transaction. A changeset records +prepared/accepted/active revisions per owner. Missing/incompatible acceptance +leaves the dependent composition visibly incomplete; it does not silently choose +a weaker profile. Unrelated components need not be stopped. Retry uses the same +operation identity and reconciles existing owner receipts. + +Runtime policy remains product-owned after installation; the installer is not a +required long-running policy service. Workspace may show effective status through +owner APIs but is not required to keep the services functioning. + +## Update, rollback and authority preservation + +Before update, validate policy/schema/runtime compatibility and preserve the +product's grants, run lineage, consumed budgets, historical snapshots and instance +identity according to its migration contract. The installer invokes product-owned +migrations and quiescence, not direct SQL. Do not reset failed or exhausted runs +because a new artifact or default profile is installed. + +A new default does not retroactively rewrite active or historical policy. Explicit +in-flight migration requires owner authority and requalification. Rollback is a +new auditable deployment/activation of compatible known content; it cannot revive +revoked permissions or restore already consumed allowances. Expiry, revocation +and emergency stops are checked at protected side-effect boundaries. + +If a required owner or fresh authorization is unavailable, follow its documented +fail-closed rule. Offline artifact verification does not itself prove current +permission to deploy or activate a policy. Cached read models never become grant +writers. No protection bypass is implied by installation ownership. + +## Roadmap and future acceptance + +POL-P is the local policy-aware composition capability. It requires cross-product +POL-Q (effective-policy qualification) and VR-Q (qualified version/release evidence) +for the production installer flow that consumes these capabilities. Work on static +manifest/API design may proceed earlier; implementation completion cannot be +inferred from the documentary graph. + +Future tests: wrong product/component/policy version; unpublished/changed artifact +under reused version; valid hash but wrong source/operation; absent owner acceptance; +partial activation/retry; stale permissions; downgrade incompatibility; no shared +SQL; no secret disclosure; 1/2/3-role deployments; budget/identity/history preservation; +no competing version allocation; actual installed artifact/receipt binding. + +Existing #16/#17 and peer implementation PRs remain separate. Before their relevant +changes are merged, reconcile target semantics; documentation does not close code +review findings or issue a release approval. Full policy administration UI, full +network discovery and generic workflow editing do not become first-canary gates. diff --git a/docs/roadmap/POLICY_GOVERNANCE_V1.md b/docs/roadmap/POLICY_GOVERNANCE_V1.md new file mode 100644 index 0000000..ea1c7af --- /dev/null +++ b/docs/roadmap/POLICY_GOVERNANCE_V1.md @@ -0,0 +1,46 @@ +# Policy-aware composition roadmap + +Increment: `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`. +Part of the [canonical roadmap index](README.md), governed by +[Policy-aware composition](../architecture/POLICY_AWARE_COMPOSITION.md). +This increment is documentation-only; all runtime capabilities below remain PLANNED. + +| Node | Owner / result | Required inputs | Position | +| --- | --- | --- | --- | +| POL-0 | Four owners document classifications, authority and compatible logical contracts | none | This documentation increment | +| POL-Q | Forge/EP qualify effective request/admission policy binding, history and authority | POL-B, with POL-F/POL-E | External qualification dependency, not Platform status authority | +| VR-Q | Forge/EP qualify native release planning -> bounded execution -> actual published artifact evidence | VR-F, VR-X, POL-Q | External producer proof before final composition | +| POL-P | Forge Platform qualifies component/policy/runtime manifest and controlled owner activation/installation receipts | POL-Q, VR-Q | PLANNED local production-composition capability | +| POL-W | Workspace implements Policy & Automation management UI | POL-WC, POL-Q | Separate peer UI; not an installer or first-canary prerequisite | + +```text +{POL-F, POL-E} -> POL-B -> POL-Q +{VR-F, VR-X, POL-Q} -> VR-Q +{POL-Q, VR-Q} -> POL-P +{POL-WC, POL-Q} -> POL-W (independent UI lane) +``` + +The full documentary node/edge set is +`pcvantol/forge:docs/roadmap/policy-governance-v1.json`, proposal +[Forge #50](https://github.com/pcvantol/forge/pull/50). EP-owned milestones are in +[EP #103](https://github.com/pcvantol/engineering-platform/pull/103); Workspace +consumer/UX milestones in [Workspace #15](https://github.com/pcvantol/workspace/pull/15). +Owning main/evidence decides implementation and readiness; diagram order does not. + +## Scope relative to existing work + +Static composition/policy contract design can run in parallel with producer +implementation. Final manifests require actual published qualified artifacts. +Pending #16 retains the artifact-gated composition proposal; #17's versioning +implementation must reconcile with native Forge release planning and the SemVer +review findings. Neither is rewritten, merged or qualified by this increment. + +Do not make full Workspace UI, every legacy policy migration or general discovery +a new prerequisite for the first Forge -> EP -> Forge canary. Production universal +installer readiness is different: the claimed release/policy/component combination +requires its real producer and installed qualification. + +Preserve the existing executable bootstrap DAG and grants. This document neither +allocates Missions nor resets budgets, authorizes side effects or changes version +baselines. Merge of this documentation makes a design canonical, not a runtime +capability implemented. diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md index 4907351..cdc20b9 100644 --- a/docs/roadmap/README.md +++ b/docs/roadmap/README.md @@ -5,10 +5,18 @@ This directory is the canonical roadmap location for Forge Platform's cross-prod ## Canonical entrypoints - [Forge Platform MVP 1.0](MVP_1_0.md) — product boundary, capability waves, a two-chain DAG that joins only at `MVP_1_0_RELEASE_READY`, the B8 → B8C → B8D → B9 → `STANDALONE_EP_VERIFIED` → `EP_EXTRACTION_CUTOVER_COMPLETE` transition gates, and separate post-verification lanes (CENTRAL relocation, EP self-hosting, and bounded multi-repository parallel execution). +- [Policy-aware composition](POLICY_GOVERNANCE_V1.md) — scoped policy/release DAG for `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`; native Forge release planning, EP enforcement and actual published artifact evidence precede qualified production installer composition. Documentation only; implementation remains PLANNED. - [Historical migration register](MIGRATION_REGISTER.md) — auditable classification of relevant historical DJConnect material and its canonical destination or retained status. The earlier stage view is retained here as orientation only; it is superseded for MVP planning by the dependency-aware capability map in [MVP 1.0](MVP_1_0.md). +The [policy-aware architecture](../architecture/POLICY_AWARE_COMPOSITION.md) keeps +Forge Platform's deployment/composition policy separate from Forge planning and +EP execution/assurance. Workspace is the human management surface, not a global +policy authority. The policy/release sub-DAG changes no executable programme DAG, +version manifest, runtime state, grant or consumed budget. Full policy UI is not +a new first-canary dependency; production compositions require their real proof. + | Earlier stage | Corresponding roadmap concern | | --- | --- | | 0–1 | Foundation, contracts, manifest, compatibility, and governance | @@ -33,4 +41,4 @@ Knowledge integration is additive and remains independently owned by `pcvantol/a | K6 | Governed automated observation extraction, health, and drift signals | | K7 | KB productization and optional Forge Platform distribution when qualified | -KB is currently a Git-backed repository-local CLI capability, not a current installer role. See the [learning-loop architecture](../architecture/KNOWLEDGE_LEARNING_LOOP.md). +KB is currently a Git-backed repository-local CLI capability, not a Workspace/EP server role and not a current Forge Platform installer component. See the [learning-loop architecture](../architecture/KNOWLEDGE_LEARNING_LOOP.md).