diff --git a/docs/architecture/FORGE_V1_BOOTSTRAP_GOVERNANCE_DECISION.md b/docs/architecture/FORGE_V1_BOOTSTRAP_GOVERNANCE_DECISION.md index 63e6921..f4caf90 100644 --- a/docs/architecture/FORGE_V1_BOOTSTRAP_GOVERNANCE_DECISION.md +++ b/docs/architecture/FORGE_V1_BOOTSTRAP_GOVERNANCE_DECISION.md @@ -1,8 +1,10 @@ # Forge V1 Bootstrap Governance Decision -**Status: canonical governance decision.** This governs a temporary V1 -bootstrap programme only; it neither implements a runner nor changes EP's -execution or lease authority. +**Status: canonical governance decision when present on owning main.** This +governs a temporary V1 bootstrap programme only; it neither implements a runner +nor changes EP's execution or lease authority. Policy clarifications are part of +[Policy governance and effective profiles](POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md). +They do not activate, renew or modify a live grant. ## Authority @@ -45,7 +47,8 @@ the Forge mapping: `NORMAL_LOW` changes need no separate owner authorization; changes require exact-head Owner Authorization; `HIGH` security/auth, credential, execution/lease, installer/update, remote-access or autonomous mutation changes require exact-head Owner Authorization plus security review. -New commits invalidate it. It is distinct from CI and Human UI Review. +New commits invalidate candidate qualification, not automatically the unchanged +programme grant. Exact-head evidence is distinct from CI and Human UI Review. `FORGE_OWNER_AUTHORIZATION_RISK_MAPPING = DEFINED` `OWNER_AUTHORIZATION_APPLICABILITY = DEFINED` @@ -55,27 +58,51 @@ New commits invalidate it. It is distinct from CI and Human UI Review. ## Merge and operating boundary Within a valid programme authorization, a node may be squash-merged only after -an executable exact-head qualification has passed. A node reaches `MERGE_READY` only after -implementation, local and exact-head hosted qualification, resolved reviews, +executable exact-head qualification has passed. `MERGE_READY` requires +implementation, local and current hosted qualification, resolved reviews, applicable UI/owner/security gates, valid authority, fresh contracts and -mergeability. It then enters `WAITING_HUMAN_MERGE`; human merge is followed by -post-merge qualification before `DONE`. A bounded merge packet includes node, -PR, exact head, risk, DoR/DoD, CI/reviews/gates, scopes, unlocked dependents and -known risks. Parallel PRs re-evaluate after every merge. +mergeability. A bounded merge packet binds node, PR, exact head, risk, DoR/DoD, +checks/reviews/gates, scopes, unlocked dependents and known risks. + +Without a applicable delegation, retain the explicit human merge boundary. +With a valid scoped delegation, the existing authorized merge executor may +consume the exact qualified packet without another owner message. A policy +flag alone does not authorize a merge; branch protection is never bypassed. +Post-merge qualification is still required before `DONE`. Parallel PRs +re-evaluate after every relevant merge. This target does not assert that every +current runtime/CI merge adapter already consumes the grant. `BOOTSTRAP_AUTO_MERGE = QUALIFIED_SQUASH_ONLY` `QUALIFIED_SQUASH_MERGE_REQUIRED = TRUE` `MERGE_DECISION_PACKET = DEFINED` `PARALLEL_PR_MERGE_REEVALUATION = TRUE` -Autonomous repair is permitted only when its programme authorization states a -finite per-PR/per-head budget. The current policy supports at most three -attempts for an exact head; a new head requires a fresh exact-head -qualification and its own budget. The runner must stop at scope expansion, -expired or revoked authorization, failed security/review/CI, or exhausted -budget. +## Repair budget and exact-head proof are separate + +Autonomous repair requires a finite authorized budget. Consumption is bound to +the Action/run continuation lineage and survives new SHA, PR, phase, process +restart and resubmission of the same work. The current bootstrap upper bound is +three total operational repair rounds per run/continuation lineage, subject to +any stricter applicable programme ceiling. EP owns actual operational round +reservation/consumption; Forge correlates it and enforces programme limits, +not an additional independent provider-repair allowance. + +Every changed candidate needs fresh exact-head qualification. It does not +receive a fresh repair budget. This explicitly supersedes the earlier per-PR/ +per-head wording that could imply a budget reset on each commit. Previously +recorded consumption and provenance remain evidence and must be preserved. -`AUTONOMOUS_REPAIR_ENABLED = BOUNDED_PER_EXACT_HEAD` +The runner stops at scope expansion, expired/revoked authorization, unresolved +security/review/CI blockers or exhausted limits. Ordinary bounded corrective +work may continue under the same valid delegation; a failed check is not itself +new authority. A fourth repair cannot be created by a new run ID or a UI edit. + +`AUTONOMOUS_REPAIR_ENABLED = BOUNDED_ACTION_LINEAGE` `UNBOUNDED_AUTONOMOUS_REPAIR = FALSE` `BOOTSTRAP_RUNNER_CAN_SELF_AUTHORIZE = FALSE` `BOOTSTRAP_GOVERNANCE_FORWARD_COMPATIBLE = TRUE` + +Documentation/DAG adoption does not renew expiry, mint capability grants, +retroactively approve candidates, reset counters or migrate runtime state. +Any material change to a live programme's authorized node set or objectives +requires explicit staleness reconciliation through the owning writer. diff --git a/docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md b/docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md new file mode 100644 index 0000000..6a04085 --- /dev/null +++ b/docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md @@ -0,0 +1,258 @@ +# Policy governance and effective profiles + +## Decision, scope and authority + +Decision ID: `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`. +This is one coordinated **documentation and roadmap increment** across Forge, +Engineering Platform (EP), Workspace and Forge Platform. On the owning `main` +branches these documents define the target architecture; on proposal branches +they remain `PENDING_PR`. Documented does not mean implemented, qualified, +installed or active. This increment changes no code, CI workflow, configuration, +version manifest, schema migration, grant, budget or runtime instance. + +Forge maintains the Forge-family policy vocabulary and planning integration +specified here. This does not make Forge a global policy server or replace the +independently owned generic AI-development contracts. Each product owns its +policy definitions, interpretation, activation and enforcement. A coordinated +change is complete only when the affected owning contracts agree. + +| Owner | Policy responsibility | Not acquired through this design | +| --- | --- | --- | +| Forge | Mission progression/pause, governance-profile resolution, planning/model preferences, native version/release planning, policy-change impact and proposals | EP admission, provider execution, repository mutation or a universal installer | +| EP | Execution/assurance/validation/repair/provider policies, actual admission, resource leases, qualification and receipts | Mission planning, self-approval or authority to weaken a producer's requirements | +| Workspace | Role-aware policy UX, proposal/decision presentation, effective-policy and historical explanations; its own session/UX policy | A second Forge/EP policy evaluator or credential-bearing execution authority | +| Forge Platform | Deployment presets, artifact composition and policy/runtime compatibility, controlled installation/update choreography | A cross-product version allocator, direct product SQL writes or another policy engine | +| Project/product authority repository | Repository-owned policy definitions, validation-tool configuration, product/component version source and compatibility promises | Authority from an incidental checkout or branch name | + +See [governance model](governance-model.md), +[server target](FORGE_SERVER_DEPLOYMENT_TARGET.md), the +[policy inventory](POLICY_INVENTORY.md) and the +[scoped roadmap/DAG](../roadmap/POLICY_GOVERNANCE_V1.md). + +## Classify before exposing a setting + +| Kind | Example | Change semantics | +| --- | --- | --- | +| `INVARIANT` | No fabricated evidence; no self-approved repair; no trust from discovery | Not an ordinary UI toggle; changes require a separately governed architecture/security decision | +| `GOVERNED_POLICY` | Required review/validation profile, release decision rule, authorized budget ceiling | Versioned definition, scoped proposal, required authority, controlled activation | +| `OPERATIONAL_CONFIGURATION` | Endpoint, bounded polling interval, timeout within an approved range | Product-owned configuration writer and actor authorization; not an arbitrary workflow script | +| `AUTHORIZATION_GRANT` | Named owner delegation for repositories/scopes/time | Separate auditable grant lifecycle, expiry and revocation; selecting a profile creates no grant | +| `RUNTIME_FACT` | Two repair rounds consumed; current instance/run identity | Immutable/auditable observation or counter; not editable preferences | +| `IMPLEMENTATION_LIMIT` | Only one action can currently be in flight | Capability constraint until separately implemented and qualified; no setting can manufacture support | + +Code constants are not automatically defects. Classify and expose their origin +before migrating them. Preserve safe defaults and unsupported-feature errors. +A policy definition must state whether it is configurable, constrained or fixed. + +## Logical records, not a new runtime schema in this increment + +These are required semantics for future versioned contracts, not implemented +classes, API routes or tables: + +- `PolicyDefinition`: stable identity, owning product/domain, schema version, + immutable revision and content digest, typed parameters, allowed ranges, + applicability, composition rules, required change authority and supported + runtime/evaluator versions. +- `PolicyAssignment`: definition revision bound to an installation, organization, + project, repository, releaseable component, programme, Mission or Action. + Supported scopes are declared per family; not every family supports all scopes. +- `PolicyChangeProposal`: exact before/after references, expected current + revision, rationale, affected scope, required roles, impact evidence and + migration/activation proposal. +- `PolicyDecision`: authenticated actor and role claims, decision, exact proposal + digest, time, scope and authority provenance. Proposal generation is not approval. +- `PolicyActivation`: accepted revision, target instance/scope, effective boundary, + predecessor activation, state and owning-service receipt. +- `EffectivePolicy`: immutable resolved values, contributing definition/assignment + revisions and digests, evaluator version, scope and source references. +- `PolicyEvaluation`: rule identifiers, relevant input/evidence references, + outcome, obligations and bounded explanation. No secrets or private reasoning + transcripts are required to explain a decision. + +Use existing product-owned SQL/storage and application services when implemented. +Do not add a separate policy daemon, shared cross-product database or second queue. + +## Definition source and runtime snapshot are different + +Every policy family declares exactly one definition writer/source mode: + +1. Repository-owned definitions are changed through their approved repository + engineering/review route. An owning service imports and activates the exact + approved revision; it does not silently edit its own competing copy. +2. Installation/operator configuration uses the existing owning service writer, + version checks and audit where this is its declared source mode. + +Runtime assignments, activation receipts and per-execution snapshots do not +replace the definition's source of truth. Workspace caches/projections are never +a definition writer. UI edits to repository-owned policy create proposals and +bounded engineering intent, not direct SQL or unreviewed file writes. + +Policy-changing work is assessed under the previously authorized policy. A +candidate cannot lower its own checks, coverage, required reviewers or authority +requirements to qualify itself. The replacement becomes active only through +its separately validated decision and activation boundary. + +## Resolution and authority algebra + +Do not use unrestricted last-writer-wins or assume that Action scope overrides +all earlier scopes. Each field has an explicit composition rule: + +| Field category | Required resolution | +| --- | --- | +| Budget/time/capacity ceiling | Minimum applicable ceiling, further bounded by remaining authorized allowance and actual qualified capability | +| Required controls/evidence | Union of applicable obligations; a lower scope cannot remove a mandatory requirement | +| Allowed providers/targets/write scopes | Intersection of applicable allowlists and grants; empty intersection denies | +| Cost/latency/style preference | Documented override rule within invariant and permission boundaries | +| Incompatible or unknown policy/schema | Explicit conflict/unavailable result; no silent default or newest-version substitution | + +This is not a universal ordering of every risk rule. Each policy family must +publish and test its own safe composition semantics. For example, a medium +severity defect that violates an explicit acceptance criterion can still block. + +`auto_merge=true` is an execution preference, not merge authorization. +Policy, grant, technical qualification and actual capability must all permit +the operation. Forecast/model advice is not an authoritative release decision. + +## Change lifecycle and cross-product activation + +```text +DRAFT -> VALIDATED -> IMPACT_ASSESSED -> REQUIRED_DECISIONS + -> APPROVED -> PUBLISHED_REVISION -> ACTIVATED +``` + +Reject, amend and defer remain explicit outcomes. Expected-revision checks +reject stale concurrent edits. Risk/role requirements come from the current +owning policy, not the proposed replacement. Routine evaluation and requalification +inside an existing valid delegation do not require repetitive human approval. + +Impact preview shows affected scopes and future work, compatibility conflicts, +current grants, which in-flight executions retain their snapshot, and which +operations would be denied. It is advisory until the owning service decides. + +There is no distributed SQL transaction across products. A coordinated change +references a shared change-set ID and owner-specific revisions/activation +receipts. Each owner validates independently. Partial preparation/activation +is visible; dependent new work waits until its required compatible revision +vector is accepted. Unaffected work is not globally stopped. Compensating +activation is explicit, never a silent claim of cross-product atomicity. + +Rollback is a new audited activation of known content where still compatible, +not deletion of history, grant resurrection or resetting consumption. + +## Action/admission binding and ongoing execution + +Forge materializes its effective planning/release policy and requested +execution constraints before dispatch. EP resolves and pins its own effective +admission/assurance profile, validates the incoming requirements and records the +accepted policy references. Unsupported or conflicting requirements fail closed. +EP returns its applied profile/evaluation evidence; Forge verifies exact request, +run and profile correspondence. An opaque digest alone is not a permission token. + +A run retains its immutable effective snapshot across restart, repair, new SHA +and historical display. A new policy normally applies to newly admitted work. +An explicit controlled migration is required to change policy for in-flight +work; it preserves lineage, consumed budget and prior evidence, and requalifies +any invalidated candidate. + +Pinned snapshots do not defeat current revocation, expiry, emergency stops or +changed credential trust. Recheck applicable dynamic authority at each protected +side-effect boundary, including provider mutation, merge, publication and install. +An unavailable authority source follows the documented fail-closed/lease rule; +never use an indefinitely stale positive cache to grant a write. Preserve +already proven delivery and record a subsequent stop/cleanup issue separately. + +EP owns the operation-level repair counter. Forge can impose stricter Mission/ +programme ceilings and correlate consumption, but never adds another three +provider repairs. The current bootstrap maximum remains **three total repair +rounds per run/continuation lineage**; lower limits are allowed, a higher future +limit requires explicit new policy/authority and cannot reset an exhausted run. +Exact-head requalification is required after mutation; a new SHA is not a new +repair allowance or automatically a new human decision. + +## Native Forge version and release management + +`FORGE::VERSION_RELEASE_MANAGEMENT_V1` is a native planning/application-service +capability for managed products, not merely a script that versions Forge itself. +It consumes product-owned compatibility and version-source contracts, evaluates +impact/policy, reserves an idempotent release operation per releaseable component, +plans bounded Actions and reconciles resulting evidence. EP performs authorized +repository/build/publish operations through the existing execution route; Forge +Platform owns composition and installation of the qualified artifacts. + +Repository, product and releaseable component are not interchangeable. EP Server +and Agent, or Workspace Server and Client, may share or separate a version series +only according to their owning contract. Matching baseline numbers do not imply +lockstep compatibility; this increment changes no baseline or product version. + +A release operation binds product/component, policy revision, operation identity, +baseline version/source, intended version, grant references, qualified candidate, +artifact identities and actual publication receipt. `PROPOSED`, `RESERVED`, +`VERSION_COMMITTED`, `QUALIFIED`, `BUILT` and `PUBLISHED` are distinct facts. +Reconcile ambiguous publication against the same operation and registry evidence; +do not allocate another version merely because an acknowledgement was lost. + +A branch-event numbering preference can be a selectable policy, but does not +prove semantic compatibility or publication authority. Stable release decisions +must address compatible fixes/additions, breaking changes and the explicitly +authorized major boundary. Branch names and commit subjects alone are not grants +or reliable operation identities. Independent candidate branches may not publish +different content under one supposedly immutable product release identity. + +Required engineering acceptance for the future implementation: + +- One named version source per product, with field-aware derived projections; + no whole-file replacement of coincidentally equal dependency/protocol versions. +- Read/validate all intended changes before writing; per-file atomic replacement + plus an explicit complete Git publication/recovery boundary. Do not claim that + several file replacements are a distributed or multi-file transaction. +- Normal build reads the already committed version and does not allocate/bump it. + Repeated build cannot silently change source or release identity. +- Version preparation precedes final candidate qualification. A later version + commit creates a new candidate requiring actual checks/review/authorization; + no assumption that bot events automatically qualify that SHA. +- Expected-head and durable operation/event identity handle retries, parallel + writers, rebase and ambiguous pushes. No subject-only bump marker. +- Validate all declared package/UI/runtime projections, then separately verify + the exact installed artifact without source-path shadowing. +- Publication binds approved source, explicit version, artifact bytes/digest, + compatibility and qualification evidence; a release branch name is insufficient. + +These requirements reconcile the findings on pending Forge #49, Workspace #14, +Forge Platform #17 and the versioning portion of EP #100. Those PRs are not +modified or approved here. Competing autonomous push-bump writers are not the +target under Forge-managed releases. Standalone EP use must remain possible with +its own explicit authorized policy and must not require Forge availability. + +## Workspace interaction boundary + +Workspace's target surface is **Policy & Automation / Beleid & automatisering**. +It provides catalogue, effective-policy explanation, diff/impact, role-routed +proposal/decision and historical views through authenticated owner APIs. +Clients do not receive ambient service-admin or provider credentials. An owner +validates the real actor/scope even when Workspace Server mediates the request. +A policy editor only exposes supported fields/extension points; it is not a +free-form workflow engine, arbitrary command launcher or safety-gate bypass. + +Policy management must explain both "why allowed?" and "why waiting?", distinguishing +policy conflict, grant/expiry, capability absence, EP lease/capacity and budget +consumption. See owning design `pcvantol/workspace:docs/POLICY_AND_AUTOMATION.md`. + +## Compatibility and bounded rollout + +Reuse existing ExecutionPolicy, governance profiles, AgentPolicySelection, +provider configuration, programme grants and EP validation profiles. Publish an +inventory before migration. A data type in code is not proof of a wired management +API; a known legacy alias needs explicit mapping, and unresolved legacy data is +not silently upgraded to a new authority. Test profile coverage and aliases. + +Keep native release integration and effective assurance contracts explicit +before a universal-installer production composition is approved. Full policy UI, +visual workflow editing and migration of every legacy knob are not new prerequisites +for the first Forge -> EP -> Forge Mission canary. Do not reopen completed producer +work or claim the canary from this documentation. + +The [roadmap](../roadmap/POLICY_GOVERNANCE_V1.md) defines the future proof gates. +The existing executable bootstrap DAG, live programme digest and grants are not +changed by this documentary sub-DAG. Any later material programme-DAG adoption +must explicitly reconcile authorization without minting authority or resetting +budget as a documentation side effect. diff --git a/docs/architecture/POLICY_INVENTORY.md b/docs/architecture/POLICY_INVENTORY.md new file mode 100644 index 0000000..ed98a5d --- /dev/null +++ b/docs/architecture/POLICY_INVENTORY.md @@ -0,0 +1,68 @@ +# Policy inventory and migration register + +Increment: `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`. +This is a source-pinned inventory, not a live configuration dump or a claim that +all repository constants have been audited. Target semantics are in +[Policy governance and effective profiles](POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md). +Runtime/effective values require the owning product API when implemented. + +## Evidence baseline + +Observed source on 2026-09-08: +Forge main `a1f2ef65d007f13423bc576a1f5ac026220ca218`; +EP main `51c2def28f23a5b1942ebdcbc5a240fd98fc2f23`; +Workspace main `c8240c39f295f3c976955a7cfd04a08c0147470b`; +Forge Platform main `bbdb299ca06217b69220db02c4cc3e86df67a009`. +These pins are historical observation sources once the repositories advance. +No installed runtime was inspected for this increment. + +## Forge-owned inventory + +| Stable inventory ID | Source at Forge baseline | Classification/current form | Target action and proof | +| --- | --- | --- | --- | +| F-PROGRESSION | `forge/governance/execution_policy.py` | Versioned ExecutionPolicy: continuous, Action/Intent/Capability/Mission pauses, custom boundaries | Retain semantics; expose supported definition/assignment/evaluation contracts and test pause/restart/approval identity | +| F-GOVERNANCE-PROFILE | `forge/governance/profiles.py`, `docs/architecture/governance-model.md` | Code-defined roles/defaults/matrices and legacy mappings, not a full management UI | Reconcile advertised profiles and aliases; explicit role decisions remain distinct, including Solo | +| F-AGENT-PROFILE | `forge/models/agent_policy.py` | Deterministic abstract model/reasoning/cost/latency selection with version/digest | Preserve provider-independent intent; EP retains actual provider/host admission; migrate mappings only through approved revision | +| F-PLANNING-PROVIDER | `forge/provider_security.py` | Runtime-owned configuration writer with expected version, audit, model/time/token parameters and secret references | Register as OPERATIONAL_CONFIGURATION constrained by policy; preserve secure-store boundary and in-flight permit rules | +| F-PROGRAMME-GRANT | `forge/programme_authorization.py`, `forge/governance_authority.py` | Separate concrete authorization/grant, exact-head qualification, Action-lineage repair authorization and squash boundary | Keep grant distinct from policy and consumption; no UI profile selection grants write/merge authority | +| F-SINGLE-FLIGHT | `forge/models/agent_policy.py`, `forge/mission_scheduler.py`, `forge/autonomous_orchestrator.py` | IMPLEMENTATION_LIMIT: single active Mission/Action assumptions | Catalogue visibly; parallel capability must be separately implemented/qualified, not enabled by a new numeric setting | +| F-BACKOFF | `forge/runtime/service.py` | Constructor-level operational bounds, default 0.25 to 5 seconds, wakeable wait | Publish supported range and effective runtime evidence without implying existing admin API | +| F-EVIDENCE-GATES | `forge/scheduler/ep_v11.py`, `forge/runtime/runner.py` | Contract/integrity validation and persisted request recovery | Retain invariants; evidence honesty/correlation is not an optional policy | +| F-VERSION-RELEASE | Pending #49, observed `a0602ba702fcf0ec3807599526257c410084b02f` | PENDING_PR repository-local manifest/helper/push workflow, not native managed-project release planning | Reconcile with FORGE::VERSION_RELEASE_MANAGEMENT_V1 and SemVer findings before adoption; no code changed here | + +## Observed governance drift and disposition + +The baseline bootstrap governance decision contained two conflicting descriptions: +new-SHA/per-head repair budgets versus the implemented Mission/Action-lineage +counter, and mandatory human merge text versus qualified delegated squash merge. +The accompanying edit to +[the owning decision](FORGE_V1_BOOTSTRAP_GOVERNANCE_DECISION.md) removes those +contradictions for the target contract. It does not claim that every runtime/CI +merge adapter already consumes delegation, or modify a live grant. + +Exact-head proof becomes stale when the candidate changes; consumed repair +budget does not reset. EP operational rounds and Forge programme ceilings are +correlated constraints, not additive repair loops. Any unmapped legacy record +requires explicit compatibility treatment, not inferred fresh allowance. + +## Peer observations, not peer authority copies + +| Owner / inventory family | Pinned source or proposal | Observation | Owning migration document | +| --- | --- | --- | --- | +| EP validation | EP baseline `src/engineering_platform/validation_profile.py` | Code registry, diff paths, control launchers and branch-specific exception; producer selects a registry profile but cannot substitute controls | `pcvantol/engineering-platform:docs/engineering/POLICY_GOVERNANCE_AND_ASSURANCE_PROFILES.md` | +| EP timeouts | EP baseline `src/engineering_platform/execution_timeout_policy.py` | Named code-defined bounded provider timeouts | Same EP document | +| EP assurance | #100; detailed earlier observation `1357f21a6895b027d47f3ae8be69b2fe4dd2764b`; refreshed open head `c9cbe95e5205c8d2d4aa27703c7b9b0bb80704aa` | PENDING_PR: review/budget/receipt work, not proof of deployed configurable profiles; do not reuse old defect status without rechecking current head | Same EP document; #100 remains owning implementation lane | +| Workspace governance | Workspace baseline `docs/ARCHITECTURE.md`, `ROADMAP.md` | Role-aware governance is target product direction; application stack and policy administration are not qualified implementation | `pcvantol/workspace:docs/POLICY_AND_AUTOMATION.md` | +| Forge Platform composition | Platform baseline architecture and pending #16/#17 | Installer/composition owns compatibility, not peer runtime policies; pending event-driven versioning must reconcile with native Forge planning | `pcvantol/forge-platform:docs/architecture/POLICY_AWARE_COMPOSITION.md` | + +## Required fields for the maintained catalogue + +Each future entry records owning product/domain, source mode and exact source, +current form (hardcoded baseline, configurable, grant, fact or implementation +limit), supported scopes and data types, effective resolution, who may change, +non-overridable boundaries, snapshot/evaluator identity, explanation evidence, +qualification tests, migration status and legacy disposition. Hidden/hardcoded +must remain visible labels until the real writer/reader/enforcer is integrated. + +Do not put bearer tokens, raw secret values or current consumption copies in this +repository catalogue. Use redacted runtime views with freshness/provenance. diff --git a/docs/roadmap/POLICY_GOVERNANCE_V1.md b/docs/roadmap/POLICY_GOVERNANCE_V1.md new file mode 100644 index 0000000..76fa030 --- /dev/null +++ b/docs/roadmap/POLICY_GOVERNANCE_V1.md @@ -0,0 +1,75 @@ +# Policy governance V1 roadmap and cross-product DAG + +Scoped roadmap under the [Forge roadmap](../../knowledge/bootstrap/10_ROADMAP.md). +Decision: [POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1](../architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md). +Machine-readable companion: [policy-governance-v1.json](policy-governance-v1.json). + +This increment delivers documentation and sequencing only. All implementation +nodes below are PLANNED. POL-0 records the design deliverable, not implemented +policy services. Peer rows describe dependencies; each peer roadmap owns its +local delivery and status. No dates, runtime readiness or grants are inferred +from this graph. It is not the executable bootstrap programme DAG. + +| ID | Owner | Deliverable / acceptance boundary | Depends on | Disposition | +| --- | --- | --- | --- | --- | +| POL-0 | Four owning repositories; Forge coordinates vocabulary | Catalogue, source ownership, change/activation semantics, grant/fact separation and typed resolution documented consistently | none | Documentation increment; canonical only after owning merges | +| POL-F | Forge | Existing policy objects wired to owner services, revisioned assignments, effective snapshots and explanation; migration preserves lineage | POL-0 | PLANNED; independent of rich UI | +| POL-E | EP | Effective admission/validation/assurance profiles, shared repair consumption and applied-policy receipt evidence | POL-0 | PLANNED; owning assurance lane supplies required subset | +| POL-WC | Workspace | Role-aware view/proposal/decision consumer contract, historical/freshness semantics and negative authority cases | POL-0 | PLANNED contract-first; parallel/non-blocking | +| POL-B | Forge + EP, independent owner adapters | Exact materialized-request -> accepted-policy binding; conflicts/unsupported profiles denied; restart/revocation rules proven | POL-F, POL-E | PLANNED bounded integration | +| POL-Q | Forge + EP | Cross-product tests: no weaker override, no fourth repair, no stale grant, historic snapshot fidelity, no policy self-approval or duplicate side effect | POL-B | PLANNED integration qualification | +| POL-W | Workspace | Policy & Automation UI backed by real owner APIs; impact/role decisions, audit, no arbitrary workflow/SQL | POL-WC, POL-Q | PLANNED; POST_AUTONOMY UI | +| VR-F | Forge | Native version/release operations and immutable component/source/artifact lineage; no independent push-bot authority | POL-F | PLANNED release-capability slice | +| VR-X | EP | Authorized field-aware version preparation, clean exact-version build, qualified publication and receipts | POL-E | PLANNED execution slice; no Forge planning inside EP | +| VR-Q | Forge + EP | Idempotent version/dispatch/publish roundtrip and final artifact evidence; candidate qualified after version preparation | VR-F, VR-X, POL-Q | PLANNED production-release prerequisite | +| POL-P | Forge Platform | Policy/runtime compatibility manifest and 1/2/3-role deployment composition; owner acceptance receipts, no direct SQL | POL-Q, VR-Q | PLANNED; installer production qualification | + +```text +POL-0 -> POL-F -> VR-F -----------+ + | | | + +----> POL-E -> VR-X ---------+| + | | || + | +--+ || + | v vv + | POL-F -> POL-B -> POL-Q -> VR-Q -> POL-P + | | + +----> POL-WC ----------+----> POL-W +``` + +The table and JSON are the precise AND-dependencies; the ASCII is an orientation +view. POL-W additionally requires POL-Q. Owner services may start independently; +full UI is never needed to resolve or enforce a run policy. + +## First canary versus installer release + +For the first same-Mission Forge -> EP -> Forge canary, implement and qualify +only the applicable effective-policy/provenance and authorization/assurance +seams. Existing bounded profiles can implement those semantics without a generic +administration UI. Do not add all of POL-F/POL-E/POL-W/VR-F as artificial umbrella +gates before a canary that does not exercise release publication. + +For a production universal-installer composition that does exercise release +management, require VR-Q and POL-P plus its existing artifact/deployment proof. +A documentary promise or a matching version string cannot satisfy those gates. +Workspace UI, full discovery and cross-repo parallel scheduling are independent +capabilities, not hidden prerequisites introduced by policy administration. + +## Integration with existing proposals + +Forge #48 (observed `455b22a5`) owns the pending Living Mission Graph/cross-repo +DAG proposal; this policy sub-DAG does not supersede its F10/F11 or renumber it. +Forge #49, Workspace #14, Platform #17 and EP #100 retain their owning +implementation/review work. Their relevant target design must be reconciled +before merge; this increment does not approve those heads or implement their fixes. +EP #102 and Platform #16 remain separate dependency/artifact contract proposals. + +Adopt executable programme-DAG changes only through explicit authorization +staleness reconciliation. Do not reset historical budgets, extend expiry or +turn these PLANNED documentary nodes into executable Missions. + +## Closure proof for this documentation increment + +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. diff --git a/docs/roadmap/policy-governance-v1.json b/docs/roadmap/policy-governance-v1.json new file mode 100644 index 0000000..44e5563 --- /dev/null +++ b/docs/roadmap/policy-governance-v1.json @@ -0,0 +1,22 @@ +{ + "document_kind": "ARCHITECTURE_ROADMAP_DAG", + "schema_version": "1.0", + "increment_id": "POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1", + "execution_authority": false, + "runtime_configuration": false, + "implementation_status": "PLANNED", + "semantic_contract": "docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md", + "nodes": [ + {"id": "POL-0", "owners": ["forge", "engineering-platform", "workspace", "forge-platform"], "kind": "documentation", "depends_on": [], "status": "PROPOSED_DOCUMENTATION"}, + {"id": "POL-F", "owners": ["forge"], "kind": "implementation", "depends_on": ["POL-0"], "status": "PLANNED"}, + {"id": "POL-E", "owners": ["engineering-platform"], "kind": "implementation", "depends_on": ["POL-0"], "status": "PLANNED"}, + {"id": "POL-WC", "owners": ["workspace"], "kind": "consumer_contract", "depends_on": ["POL-0"], "status": "PLANNED"}, + {"id": "POL-B", "owners": ["forge", "engineering-platform"], "kind": "integration", "depends_on": ["POL-F", "POL-E"], "status": "PLANNED"}, + {"id": "POL-Q", "owners": ["forge", "engineering-platform"], "kind": "qualification", "depends_on": ["POL-B"], "status": "PLANNED"}, + {"id": "POL-W", "owners": ["workspace"], "kind": "ui", "depends_on": ["POL-WC", "POL-Q"], "status": "PLANNED", "first_canary_blocker": false}, + {"id": "VR-F", "owners": ["forge"], "kind": "implementation", "depends_on": ["POL-F"], "status": "PLANNED"}, + {"id": "VR-X", "owners": ["engineering-platform"], "kind": "implementation", "depends_on": ["POL-E"], "status": "PLANNED"}, + {"id": "VR-Q", "owners": ["forge", "engineering-platform"], "kind": "qualification", "depends_on": ["VR-F", "VR-X", "POL-Q"], "status": "PLANNED"}, + {"id": "POL-P", "owners": ["forge-platform"], "kind": "composition_qualification", "depends_on": ["POL-Q", "VR-Q"], "status": "PLANNED", "first_canary_blocker": false} + ] +} diff --git a/knowledge/bootstrap/10_ROADMAP.md b/knowledge/bootstrap/10_ROADMAP.md index 6d48878..270fabf 100644 --- a/knowledge/bootstrap/10_ROADMAP.md +++ b/knowledge/bootstrap/10_ROADMAP.md @@ -4,6 +4,31 @@ This is Forge's canonical strategic roadmap. Roadmap presence does not authorize execution; bounded Engineering Intents/Missions and governance remain required. Forge evolves capability-first while preserving repository-first knowledge, human governance and execution-host independence. +## Policy governance and native release management — documented target + +The coordinated `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1` increment defines +[policy ownership and lifecycle](../../docs/architecture/POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES.md), +a [source-pinned policy inventory](../../docs/architecture/POLICY_INVENTORY.md), and +the [scoped implementation roadmap/DAG](../../docs/roadmap/POLICY_GOVERNANCE_V1.md) +with its [machine-readable documentary graph](../../docs/roadmap/policy-governance-v1.json). +These are documentation deliverables; the services and management UI remain PLANNED. + +Forge owns planning/progression and native `VERSION_RELEASE_MANAGEMENT_V1`; +EP owns effective execution/assurance profiles and operational repair accounting; +Workspace owns Policy & Automation UX; Forge Platform owns policy-aware artifact +composition and installation. Policies, grants, runtime consumption and hard +implementation limits are distinct. A new candidate SHA does not reset repairs. + +Local progression is `POL-0 -> POL-F -> POL-B -> POL-Q`, with native release +planning `POL-F -> VR-F -> VR-Q`. EP-owned POL-E/VR-X join at the corresponding +integration gates; POL-WC can be designed in parallel, POL-W is post-autonomy UI, +and POL-P qualifies production installer composition after release evidence. +The scoped DAG does not alter the executable bootstrap node set or live grants. +Relevant policy/provenance seams must be real for the operations being claimed; +full UI or migration of every legacy setting is not a new first-canary prerequisite. +Pending Forge #48 and #49 retain their respective graph and implementation lanes; +this documentation neither merges them nor claims their features implemented. + ## Strategic progression ```text