diff --git a/docs/architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md b/docs/architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md new file mode 100644 index 0000000..c9f435d --- /dev/null +++ b/docs/architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md @@ -0,0 +1,258 @@ +# Governed progression and delivery authority + +## Decision and status + +Increment: `GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1`. +Capability target: `FORGE::GOVERNED_PROGRESSION_V1`. +This is a coordinated architecture/roadmap increment, canonical on each owning +main after merge and otherwise PENDING_PR. It implements no resolver, API, +workflow, external integration or deployment and activates no policy or grant. + +This elaborates [policy governance](POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md), +[the product lifecycle](product-model.md), [Governance Profiles](governance-model.md) +and [Mission architecture](engineering-mission.md). It groups the previously +proposed gate-resolution/execution-governance ideas under one capability; those +names do not denote extra parallel engines. Reuse existing ExecutionPolicy, +profile resolution, governance persistence, Action/evidence and decision seams. +See [the scoped roadmap/DAG](../roadmap/GOVERNED_PROGRESSION_V1.md). + +## Three gate families, separate authority + +| Family | Meaning | Owner of decision/enforcement | +| --- | --- | --- | +| Lifecycle governance | Business approval of Candidate, Architecture approval for Engineering | Forge governance contract and assigned human authorities | +| Engineering progression | Review after Action/Intent/Capability, at Mission end, or supported custom boundaries | Forge resolves effective progression policy and blocks successor release | +| Delivery/promotion | Permission before publish, store submission, install, deploy or irreversible migration to an exact target | The declared project/organization delivery or approval authority; never assumed by Forge | + +Mission Intake validates an already approved Mission; Candidate intake/refinement +precedes Business and Architecture approval. Those approvals remain separate and +explicit, including under Solo. Governance Profiles supply defaults/assignments, +not permission to remove lifecycle stages or infer approval from maturity. +Human review, automated quality/security review, technical qualification, merge +approval and production approval are distinct obligations. One does not +implicitly replace another. + +## Ownership invariant + +Forge plans what/why/next, resolves its governance requirements and reconciles +authoritative evidence. EP admits and executes bounded engineering Actions, +qualifies candidates and produces execution evidence. Workspace presents/routs +permitted decisions, records the human interaction and submits it to the owning +service; it is not the final authority for Forge state or external deployments. +Forge Platform owns qualified product distribution/installation composition, +not every project's CD system. Existing external CD owns its own approvals, +execution, production credentials, publication and rollback unless the project +explicitly delegates a bounded operation through its approved control contract. + +```text +HUMAN_GATE_REQUIREMENT != HUMAN_GATE_AUTHORITY +TRIGGER_PERMISSION != APPROVAL_PERMISSION != DEPLOYMENT_PERMISSION +WORKSPACE_PRESENTATION_DOES_NOT_TRANSFER_AUTHORITY = TRUE +EXTERNAL_DELIVERY_AUTHORITY_PRESERVED = TRUE +``` + +## Project defaults and Mission assignments + +A progression profile declares cadence, review scope, required role/decision, +applicable evidence, supported boundaries and permitted overrides. Supported +cadences include continuous, after Action, after Intent, Capability boundary, +Mission-end review and explicit custom boundaries. These are not a universal +ordered scale: allowed combinations and override bounds are defined by policy. +Mission-end acceptance and continuous intermediate progression are independent +fields/obligations, not contradictory enum shortcuts. + +Resolve product invariants + applicable organization/project requirements + +project default + approved Mission assignment + mandatory context/risk rules + +current grants/capability. Distinguish a default from a non-overridable obligation. +A Mission may select a less frequent review only where the higher-scope policy +permits that override and the actor is authorized. Free-form Mission/prompt text +cannot turn off required gates. Selecting Solo does not mean every project must +run continuously; selecting Enterprise does not fix every prototype to per-Action +review. Missing or conflicting assignments are not an autonomous default. + +Examples are target profiles, not active configuration: + +| Project/Mission | Intermediate cadence | Final review | Exceptional/target gates | +| --- | --- | --- | --- | +| Disposable prototype | Continuous | Mission acceptance required | Still enforce scope, security and delivery restrictions | +| Production-critical engineering | After every Action | Applicable Mission acceptance | Still enforce separate before-PROD gates | +| Prototype Mission in stricter project | Mission-specific override if permitted | As explicitly assigned | Cannot waive project mandatory controls | + +No cadence setting weakens EP assurance, increases repair allowance, authorizes +merge/publish or changes the Mission boundary. Policy/grant/runtime consumption +remain distinct. Risk assessment may inform classification; a model cannot +approve its own exceptions or reinterpret PROD as TST. + +## Boundary resolution and successor fence + +Before the applicable lifecycle/progression transition, Forge derives an +Effective Governance Requirement set from pinned policy and current evidence. +Persist each requirement identity, type, boundary, blocking scope, required +roles/authority, policy/evaluator references, subject revision/digest, evidence +requirements, rationale codes and invalidation rules. Materialize requirements +before work is released, not after discovering an unauthorized side effect. + +For after-Action review: + +```text +EP Action A terminal evidence -> Forge verifies/reconciles A + -> evaluate the Mission's progression boundary + -> CONTINUE, or persist a blocking DecisionRequirement + -> Workspace shows the owner-authorized decision + -> owning service validates decision/authority and exact subject + -> Forge may derive/release the next bounded Action +``` + +Forge may collect evidence and prepare non-executable forecasts while waiting; +it may not materialize an approval bypass by dispatching B early. Continuation +approval binds the reviewed Action/evidence and a defined continuation scope, +not an unbounded wildcard for future work. A material change invalidating that +scope requires reevaluation; dynamic in-scope planning remains possible without +an owner-supplied A/B script. Materialized/dispatched Action identity is immutable. + +The default review fence is Mission-scoped: no new execution in that Mission +until satisfied. A narrower graph/subscope fence needs an explicit supported +policy and qualification; unrelated Missions/projects need not stop. Already +in-flight Actions are governed by their owning pause/cancellation contract, +not retrospectively undone. Avoid holding an EP repository mutation lease +solely while waiting for Forge human review after completed delivery. + +A Decision has approve/reject/amend/defer outcomes, authenticated actor/role, +exact requirement/subject/policy references, timestamp, scope and decision +provenance. Pending, rejected, deferred, expired, superseded and satisfied are +not interchangeable. A newer revision or a stale browser click cannot silently +satisfy a different requirement. Replays reconcile one decision/continuation; +restart never loses a fence or dispatches twice. + +Evidence-proven engineering completion and required human acceptance are +separate facts. Do not report unconditional Mission completion while its +required end-acceptance is unresolved, and do not erase proven delivery because +acceptance is deferred. Normal review cadence is not a reapproval of every +Mission's Business/Architecture boundary. + +## Project-owned Delivery Control Contract + +Environment is a first-class classification bound to a stable target, not just +a free-text label. Each target contract declares: + +- project/product/component and target identity; +- environment class TST/ACC/PROD/custom, account/resource/audience and approved + endpoint/registry/store scope; +- supported operations: build, publish artifact, install, deploy, store upload, + submit for review, public release, migration or rollback as applicable; +- trigger/request, approval and execution/deployment authorities separately; +- pipeline/entrypoint identity and relevant configuration revision; +- artifact/source/version input contract, compatibility and qualification; +- gate mapping, decision evidence, receipt/readback, freshness and cancellation. + +The project authority repository owns the declaration. The declared external +system remains authoritative for actual gates/configuration; observed drift +must be reconciled, not overwritten by Forge's cached declaration. A Mission +can request delivery to an allowed target but cannot replace that target's CD. + +TST/ACC can be automatic while PROD requires human approval under the chosen +profile. TST and ACC may also be stricter when project policy requires it. +A production endpoint cannot be relabeled ACC to obtain a weaker policy. +App upload, submission to review, reviewer approval and public availability +are separate outcomes; a store submission does not prove public release. + +## Resolve requirements to existing authorities; do not duplicate gates + +One logical requirement has one authoritative satisfaction binding. Resolve it +to the existing external gate where that gate demonstrably covers the required +semantics, artifact, target and operation. Gate equivalence is not determined +by matching names or by one pipeline having a green status. A configured binding +is NOT a satisfied approval: WAITING_EXTERNAL_DECISION remains pending until +validated matching decision evidence exists. + +Workspace shows an external gate's owner, state, reason, freshness and approved +deep-link. It must not show a local Approve control for that same external gate. +An unavailable external service does not authorize a replacement Workspace gate. +Two distinct approvals are valid only when policy explicitly requires different +obligations, such as business release approval and SRE production approval. +Track their identities independently; no duplicate click for one requirement +and no accidental collapse of genuine separation-of-duties obligations. + +If required authority or evidence cannot be mapped, block the dependent operation +and request a real contract/authority decision. Do not silently take ownership, +weaken requirements, or claim a generic CI success proves human approval. + +## Integration modes and the request-before-approval distinction + +`OBSERVE_ONLY` is the default for an existing delivery system: read verified +state/evidence and never trigger or approve. `REQUEST_AND_WAIT` additionally +allows a bounded authorized request to an existing entrypoint. An authorized +direct trigger is a separately scoped permission within this mode, not a third +mode conferring deployment or approval rights. + +The request/trigger actor must itself be authorized. It can be the existing EP +execution adapter or another explicitly declared delivery integration actor; +Forge never becomes an arbitrary shell/CD executor. Pipeline credentials remain +at the owning service. No ambient production/cloud/store credentials in Forge +or Workspace merely to request or observe a pipeline. + +An external pipeline may need to start before its human gate can be presented. +An authorized request may therefore precede the external decision IF the owning +pipeline demonstrably prevents the protected deployment/publication until its +gate is satisfied. Verify that enforcement binding before the request. Do not +create a circular dependency requiring external approval before the pipeline +that materializes that approval can be requested. Conversely, if the trigger +itself performs the protected side effect, the gate must precede the trigger. + +## Exact authorization and evidence binding + +Bind approval to requirement/operation, applicable policy and contract revision, +project/component, exact artifact digest, qualified source/candidate provenance, +target/environment, pipeline identity/configuration and validity conditions. +A decision for ACC, artifact A or pipeline run R is not permission for PROD, +artifact B or a new unrelated attempt. Source SHA and artifact digest are distinct; +squash/merge relationships need actual provenance, not assumed equality. + +At each protected side-effect boundary its owning executor rechecks current +scope, expiry/revocation, policy compatibility and decision validity. Pinned +snapshots preserve history but cannot override an emergency stop. A cadence +change affects new work by default; in-flight activation requires an explicit +controlled transition preserving grants, history, consumption and fences. + +Persist outgoing operation identity before request. Reconcile ambiguous responses +against that same operation/authority, not by blindly triggering again. Observe +callbacks/readback through authenticated, scoped interfaces; verify run, target, +artifact and decision identity, handle duplicates/out-of-order events, and retain +append-only observations with clear current/freshness status. External systems +need not implement EP's receipt schema; qualified adapters map authentic evidence +without synthesizing facts. An insufficient producer is explicitly unsupported +or unverified, never silently successful. + +Requested, accepted, awaiting approval, approved, executing, deployed, verified, +store-submitted and publicly released are separate facts. A green trigger job +is not deployment success. Forge releases successors only when their declared +requirements have authoritative evidence. Reject/defer/timeout/outage never +causes a direct deployment fallback or automatic bypass resubmission. Keep +already proven delivery separate from later cancellation, rollback or cleanup. + +## Relationship to version/release management and current work + +Native version/release planning (`FORGE::VERSION_RELEASE_MANAGEMENT_V1`) consumes +these authority/target requirements; this increment does not implement it or +claim repository SemVer helpers supply it. Version allocation, build, publication +and installer composition retain their existing owning boundaries. Final +component pins still require real qualified published artifacts. + +The open Living Mission Graph proposal and EP dependency/assurance/queue/SemVer +lanes remain separate. This document does not merge them, close their findings, +change their implementation or make external deployment necessary for a canary +whose Mission does not request it. No live programme DAG/grant is changed. + +## Acceptance for subsequent implementation + +Require source, cross-product and installed proof as applicable: +prototype continuous-to-end versus production after-Action fence; permitted and +forbidden Mission override; distinct mandatory risk gate; restart without losing +pending review; stale/wrong-role decision rejected; no successor dispatch before +review; Mission acceptance separate from delivered evidence; automatic TST/ACC +versus external PROD approval; one external gate with no Workspace duplicate; +separate business/SRE gates; request-before-external-gate without bypass; target +relabeling denied; changed artifact/config invalidates approval; revoked grants; +lost trigger acknowledgment without duplicate deployment; authenticated wrong-run +or out-of-order evidence rejected; external outage; store submission not public +release; no production credential/SQL bypass. All remain PLANNED qualification. diff --git a/docs/roadmap/GOVERNED_PROGRESSION_V1.md b/docs/roadmap/GOVERNED_PROGRESSION_V1.md new file mode 100644 index 0000000..818ec12 --- /dev/null +++ b/docs/roadmap/GOVERNED_PROGRESSION_V1.md @@ -0,0 +1,51 @@ +# Governed progression V1 roadmap and documentary DAG + +Increment: `GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1`. +Owning semantics: [governed progression and delivery authority](../architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md). +Parent: [policy governance roadmap](POLICY_GOVERNANCE_V1.md), itself routed by +the canonical [Forge roadmap](../../knowledge/bootstrap/10_ROADMAP.md). +Machine-readable index: [governed-progression-v1.json](governed-progression-v1.json). +This is not the executable bootstrap DAG, a Mission or runtime configuration. + +| ID | Owning delivery | Depends on | Acceptance / status | +| --- | --- | --- | --- | +| GP-0 | Four product owners | none | This coordinated design; authoritative only on owning main | +| GP-F | Forge | GP-0 | PLANNED: scoped review cadence/overrides, requirement resolution, decision reconciliation, durable successor fence | +| GP-DC | Forge/EP/Platform contract consumers; project owns each declaration | GP-0 | PLANNED: versioned delivery target/environment/authority and evidence contract | +| GP-E | EP | GP-0 | PLANNED: bounded operation/decision enforcement and evidence adapter; no Mission planner or CD takeover | +| GP-Q | Forge + EP | GP-F, GP-E | PLANNED: cross-product progression/gate/identity/restart proof with isolated qualification targets | +| GP-WC | Workspace | GP-0 | PLANNED: review settings and local/external decision projection/command contract | +| GP-W | Workspace | GP-WC, GP-Q | PLANNED: real policy/decision UI; external live claims additionally consume GP-X evidence | +| GP-X | Forge + EP integration, existing target owner retains authority | GP-Q, GP-DC | PLANNED: one approved real external pipeline, no duplicate gate/side effect, exact promotion/receipt evidence | +| GP-P | Forge Platform | GP-X | PLANNED: delivery-authority-aware composition for deployments using an external owner; existing artifact/install qualification also required | + +```text +GP-0 -> GP-F --+ +GP-0 -> GP-E --+-> GP-Q --+-> GP-X -> GP-P +GP-0 -> GP-DC -----------+ +GP-0 -> GP-WC --+ | +GP-Q ----------+-> GP-W | (external live view consumes GP-X) +``` + +The table/JSON define AND-dependencies. They do not allocate another repository's +work or imply an external organization's approval. GP-DC ownership refers to +consumer contract implementation, not ownership of project delivery policy. +GP-E/GP-F reuse the necessary POL-E/POL-F semantics; requiring all future policy +administration is not a hidden dependency. GP-P supplements applicable POL-P, +VR-Q and qualified artifacts where those capabilities are used; it does not +make every local installation depend on an external CD pipeline. + +The first serial dynamic Mission canary requires the actual selected Mission's +progression/authorization seams only. Rich Workspace UI, external CD, App Store, +PROD deployment, generalized parallelism and universal installer completion are +not newly inserted first-canary gates. Proof of one continuous profile is not +proof of all future configurable human-review profiles. + +No existing F/L/POL/VR nodes are renumbered or marked complete. Adoption into a +live programme uses its separate authority/staleness reconciliation without +resetting budgets or extending grants. All implementation nodes remain PLANNED. + +Documentation acceptance: four owning boundaries agree; canonical entrypoints +route to this scoped design; graph IDs/dependencies are valid and acyclic; only +Markdown and documentary DAG JSON change. No implementation, runtime, package +version, workflow, external CD configuration or credential change is implied. diff --git a/docs/roadmap/POLICY_GOVERNANCE_V1.md b/docs/roadmap/POLICY_GOVERNANCE_V1.md index 76fa030..8c661ef 100644 --- a/docs/roadmap/POLICY_GOVERNANCE_V1.md +++ b/docs/roadmap/POLICY_GOVERNANCE_V1.md @@ -73,3 +73,17 @@ Four linked PRs; owner/source matrix agrees; catalogue entries are source-pinned all new graph edges reference known nodes and the graph is acyclic; roadmaps link to owning designs; only Markdown and documentary DAG JSON changed. Existing runtime, workflows, package versions, tests and deployment are untouched. + +## Governed progression and external delivery authority + +The follow-on [GOVERNED_PROGRESSION_V1 roadmap](GOVERNED_PROGRESSION_V1.md) +elaborates scoped review cadence, Mission overrides, effective decision/fence +resolution and environment-aware delivery through existing project/CD authorities. +Its [design](../architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md) is the +owning detailed contract for `FORGE::GOVERNED_PROGRESSION_V1`. It preserves the +fixed pre-Mission approvals and does not duplicate external approval controls. +GP-0/GP-F/GP-DC/GP-E/GP-Q/GP-WC/GP-W/GP-X/GP-P are documentary decomposition, +not replacements for POL/VR nodes or new executable bootstrap authority. +Native release planning consumes the declared delivery authority rather than +assuming publication/deployment ownership. All new implementation remains +PLANNED; full external CD and Workspace UI do not gate a no-deployment canary. diff --git a/docs/roadmap/governed-progression-v1.json b/docs/roadmap/governed-progression-v1.json new file mode 100644 index 0000000..ff157fc --- /dev/null +++ b/docs/roadmap/governed-progression-v1.json @@ -0,0 +1,21 @@ +{ + "document_kind": "ARCHITECTURE_ROADMAP_DAG", + "schema_version": "1.0", + "increment_id": "GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1", + "execution_authority": false, + "runtime_configuration": false, + "implementation_status": "PLANNED", + "semantic_contract": "docs/architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md", + "parent_roadmap": "docs/roadmap/POLICY_GOVERNANCE_V1.md", + "nodes": [ + {"id": "GP-0", "owners": ["forge", "engineering-platform", "workspace", "forge-platform"], "kind": "documentation", "depends_on": [], "status": "DOCUMENTATION_ONLY"}, + {"id": "GP-F", "owners": ["forge"], "kind": "implementation", "depends_on": ["GP-0"], "status": "PLANNED"}, + {"id": "GP-DC", "owners": ["forge", "engineering-platform", "forge-platform"], "kind": "consumer_contract", "depends_on": ["GP-0"], "status": "PLANNED"}, + {"id": "GP-E", "owners": ["engineering-platform"], "kind": "implementation", "depends_on": ["GP-0"], "status": "PLANNED"}, + {"id": "GP-Q", "owners": ["forge", "engineering-platform"], "kind": "qualification", "depends_on": ["GP-F", "GP-E"], "status": "PLANNED"}, + {"id": "GP-WC", "owners": ["workspace"], "kind": "consumer_contract", "depends_on": ["GP-0"], "status": "PLANNED"}, + {"id": "GP-W", "owners": ["workspace"], "kind": "ui", "depends_on": ["GP-WC", "GP-Q"], "status": "PLANNED", "first_canary_blocker": false}, + {"id": "GP-X", "owners": ["forge", "engineering-platform"], "kind": "external_integration_qualification", "depends_on": ["GP-Q", "GP-DC"], "status": "PLANNED", "first_canary_blocker": false}, + {"id": "GP-P", "owners": ["forge-platform"], "kind": "composition_qualification", "depends_on": ["GP-X"], "status": "PLANNED", "first_canary_blocker": false} + ] +}