Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions docs/development/GOVERNED_PROGRESSION_V1_ROADMAP.md
Original file line number Diff line number Diff line change
@@ -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).
11 changes: 11 additions & 0 deletions docs/development/POLICY_GOVERNANCE_V1_ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
134 changes: 134 additions & 0 deletions docs/engineering/GOVERNED_PROGRESSION_AND_DELIVERY_AUTHORITY.md
Original file line number Diff line number Diff line change
@@ -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.
Loading