From f323a2d6379ae24757da07bdbeaecad423b56fae Mon Sep 17 00:00:00 2001 From: DJConnect Date: Tue, 8 Sep 2026 16:38:34 +0200 Subject: [PATCH] docs: preserve CD authority at governed delivery boundaries --- .../GOVERNED_PROGRESSION_V1_ROADMAP.md | 40 ++++++ .../POLICY_GOVERNANCE_V1_ROADMAP.md | 11 ++ ...RNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md | 134 ++++++++++++++++++ 3 files changed, 185 insertions(+) create mode 100644 docs/development/GOVERNED_PROGRESSION_V1_ROADMAP.md create mode 100644 docs/engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md diff --git a/docs/development/GOVERNED_PROGRESSION_V1_ROADMAP.md b/docs/development/GOVERNED_PROGRESSION_V1_ROADMAP.md new file mode 100644 index 0000000..03ada38 --- /dev/null +++ b/docs/development/GOVERNED_PROGRESSION_V1_ROADMAP.md @@ -0,0 +1,40 @@ +# EP governed progression roadmap + +Increment: `GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1`. +Scoped under [EP policy-governance roadmap](POLICY_GOVERNANCE_V1_ROADMAP.md) +and its canonical parent roadmap. This is a documentary capability DAG, not +execution authority or live policy. Implementation remains PLANNED. + +Shared documentary graph: +`pcvantol/forge:docs/roadmap/governed-progression-v1.json`. +EP owns the implementation/qualification of its execution/delivery-adapter boundary. + +| Node | Owner | Depends on | Completion proof | +| --- | --- | --- | --- | +| GP-0 | Four owning repositories | none | Reconciled lifecycle/cadence/delivery/authority documentation | +| GP-E | EP | GP-0 | Explicit target/operation authority checks, external request/readback correlation, no bypass, durable evidence | +| GP-Q | Forge + EP | GP-F, GP-E | Cross-product boundary tests, revision-bound approvals and restart/no-duplicate progression | +| GP-X | Forge + EP integration, target owner retains authority | GP-Q, GP-DC | Real external gate/pipeline qualification under an approved project target contract | + +GP-F is Forge's progression resolver and decision reconciliation. GP-DC is the +project-owned Delivery Control Contract consumed by Forge/EP/Platform. Neither +gives EP Mission planning authority. Workspace GP-WC/GP-W and Forge Platform +GP-P remain consumer productization lanes. Existing POL/VR nodes are retained; +only the effective-policy/release seams used by this profile are prerequisites. + +```text +GP-0 -> GP-E ---------------------+ +GP-0 -> GP-F (Forge) --------------+-> GP-Q --+ +GP-0 -> GP-DC (project contract) ------------+-> GP-X +``` + +The first serial dynamic Mission canary needs only the progression/approval +seams actually used by its approved Mission. It does not require general CD +adapters, production deployment, App Store release, Workspace policy UI or +universal installer implementation. Existing EP assurance, queue and SemVer +findings remain independent work; this document fixes none by declaration. + +Before delivery-aware execution is claimed, prove exact authority, environment, +artifact and operation binding, retained external gates, no duplicate approvals, +current authorization, fail-closed unknown evidence and qualified recovery. +See [the owning design](../engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md). diff --git a/docs/development/POLICY_GOVERNANCE_V1_ROADMAP.md b/docs/development/POLICY_GOVERNANCE_V1_ROADMAP.md index dd5fe88..723a51b 100644 --- a/docs/development/POLICY_GOVERNANCE_V1_ROADMAP.md +++ b/docs/development/POLICY_GOVERNANCE_V1_ROADMAP.md @@ -54,3 +54,14 @@ or implicit peer readiness; source/CI/runtime/package/permission files unchanged Implementation acceptance additionally requires the concrete tests in the owning design and applicable installed evidence. Documentary completion alone cannot unlock a run or close a live assurance gate. + +## Governed progression and existing CD authority + +The [GP roadmap](GOVERNED_PROGRESSION_V1_ROADMAP.md) and +[owning delivery-authority design](../engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md) +refine how EP enforces protected operation requirements without owning Forge's +review cadence or a project's existing CD approval/deployment authority. +GP-E/GP-Q/GP-X are PLANNED; a Workspace decision is not a substitute for the +external target's gate. No duplicate workflow, live policy or executable DAG +is introduced. The current Action assurance and bounded repair requirements +remain intact and distinct from post-Action human review. diff --git a/docs/engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md b/docs/engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md new file mode 100644 index 0000000..4cb1507 --- /dev/null +++ b/docs/engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md @@ -0,0 +1,134 @@ +# EP governed progression and external delivery authority + +Increment: `GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY_V1`. +Documentation and roadmap only. Canonical target on owning main; otherwise +PENDING_PR. No runtime implementation, deployment, policy activation or grant +is created by this document. + +## Authority + +Forge owns Mission progression and review cadence. EP owns Action admission, +execution, validation/assurance, operational repair, finalization and receipts. +A project's existing CD/release system retains its approval, deployment, +publication, credentials and rollback authority. Workspace presents decisions; +presentation does not transfer authority. Forge Platform composes qualified +artifacts and invokes supported product/target interfaces; it does not replace +an organization's delivery control plane. + +Shared semantics: +`pcvantol/forge:docs/architecture/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md`. +This elaborates the existing [EP policy architecture](POLICY_GOVERNANCE_AND_ASSURANCE_PROFILES.md) +and narrows generic release/deployment wording to the actually assigned authority. + +## Three distinct gates + +1. Pre-Mission Business and Architecture approvals remain Forge lifecycle + invariants. They are not EP's post-implementation quality step. +2. An after-Action human review is Forge progression policy. EP can complete + its bounded Action while Forge waits before releasing successor work. +3. A before-publish/install/deploy gate protects a specific side effect and + belongs to the declared target authority. A post-Action review cannot replace + a required pre-production approval. + +EP must not autonomously launch a new Forge Action while Forge progression is +paused. Conversely, a Forge pause does not cancel an already running Action or +external pipeline. In-flight handling uses the owning execution/cancellation +contract and preserves evidence. A completed EP run need not retain its repository +mutation lease merely because Forge's next Action is waiting for human review. + +## Environment and Delivery Control Contract + +Each project-owned target declaration distinguishes stable target identity, +environment class (TST/ACC/PROD/custom), account/resource/audience, product/component, +artifact input, pipeline/entrypoint identity and configuration revision, approval +authority, trigger authority, deployment/publication authority, permitted operations, +evidence/readback and cancellation/rollback boundaries. Labels and prompt text +cannot turn a production endpoint into TST. Actual target identity must agree +with the approved declaration and the authoritative external configuration. + +TST and ACC may allow automatic progression; PROD or App Store submission may +require a human gate under the applicable target policy. These are selectable +profiles, not a universal requirement to add a second human approval to every +production pipeline. A project may impose stricter TST/ACC rules. Upload, +submission for review, approval and public release are distinct operations; +permission for one does not authorize the others. + +## External delivery integration + +Use `OBSERVE_ONLY` by default for existing external delivery. An approved +`REQUEST_AND_WAIT` mode permits a bounded request to an existing entrypoint. +Direct trigger permission is separately scoped within that mode, not another +mode conferring deployment or approval permission. Existing external gates +cannot be bypassed by EP's provider, repository credentials or Workspace approval. + +One logical requirement has one authoritative satisfaction binding. Mapping to +an external gate is not a satisfied decision: pending external approval stays +pending. Verify semantic coverage, not just equal labels. Only validated evidence +for the exact candidate/target can satisfy that requirement. Two gates are +legitimate for explicitly different obligations, such as business release and +SRE deployment approval. Missing mappings fail closed; no local fallback gate. + +EP may execute a release/deployment operation only where the project explicitly +assigns EP that operation and supplies scoped authority. This does not confer +control over a target that remains CD-owned. Never give general cloud, store or +production credentials to Forge/Workspace just to trigger a pipeline. + +An authorized pipeline request may occur while its external approval is still +pending IF that pipeline demonstrably fences the protected side effect until +approval. Verify the authority/enforcement binding before requesting it. This +avoids requiring approval before the request that creates the external gate. +If the trigger itself causes the protected side effect, approval must precede +that trigger. A request acknowledgment never proves approval or deployment. + +## Side-effect boundary and evidence + +At each protected operation the owning executor verifies current actor/grant +scope, expiry/revocation, exact policy/decision references, artifact bytes/digest, +source-to-delivery provenance, target/environment and operation identity. +Candidate, target, pipeline or material policy changes invalidate old evidence +according to declared rules. Pinned policy does not override current revocation. +Avoid network calls inside long database write transactions; persist operation +intent and use idempotent dispatch plus authoritative readback. + +Receipts correlate Mission/Action where supplied, release/operation ID, +product/component, artifact identity/digest, source revision, target/environment, +pipeline/run identity, applied gate/decision references, outcome and the actual +deployed/published identity. Acceptance, approval, execution, verification and +public release are separate facts. External evidence is mapped through qualified +adapters, not fabricated into an EP execution artifact. Redact secrets and +sensitive operator details. + +Duplicate callbacks, lost acknowledgments and restarts reconcile the same +operation. Verify authenticated origin and exact identity and handle out-of-order +events. Successful but wrong-run/wrong-target evidence cannot unlock progression. +If a pipeline cannot supply sufficient verifiable evidence, report unsupported +or unverified integration. An outage is not a license to deploy directly. +Already proven delivery stays true when later cleanup or rollback fails; report +the subsequent event separately. + +## Engineering governance compatibility + +The existing quality/security step, read-only reviewers, actual candidate +qualification and shared maximum of three corrective rounds remain unchanged. +Human review cadence cannot remove those controls or replenish consumed budget. +A project/Mission policy may impose stricter limits but cannot grant execution, +merge or publication rights. Review after each Action is distinct from GitHub +PR review and from an external CD environment approval. EP-only operation stays +supported under its own approved local policy; optional Forge/Workspace downtime +does not require a second authority or bypassing a mandatory gate. + +## Future qualification + +Required scenarios: automatic TST/ACC and externally gated PROD; prototype +Mission-end review versus production after-Action review; no duplicate approval; +explicit independent business/SRE approvals; wrong target/environment/artifact; +stale approval after mutation; revoked trigger grant; untrusted callback; lost +trigger response/restart without duplicate deployment; rejected/deferred external +gate; unavailable authority; request-before-external-approval without protected +side effects; store submission distinct from public release; no direct credential +or SQL bypass; preserved repair consumption and history. + +Implementation is PLANNED. The owning lane is GP-E in the +[governed progression roadmap](../development/GOVERNED_PROGRESSION_V1_ROADMAP.md). +This architecture does not close open #100 findings or insert full CD integration +ahead of the first serial Forge Mission canary.