--- name: Arco approvals version: 0.5.0 status: draft owner: Stoirm Arnold last_updated: 15-Sep-2026 --- # Arco approvals ## Purpose Approvals is the reusable Governance mechanism for actions that require explicit consent before execution. Approvals does not own the action being approved. The calling subsystem owns the proposed action. Approvals owns: - whether an approval route applies; - who or what authority may approve; - the approval request; - the approval outcome; - the return of that outcome to the calling subsystem. Approvals sits beneath `arco-governance.md`. ## Core principle Do not duplicate approval logic inside every module. A subsystem should be able to state: ```text This action requires approval. → use Approvals ``` Examples: ```text Decision requires approval ↓ Approvals Context change requires approval ↓ Approvals Skill publication requires approval ↓ Approvals Governance change requires approval ↓ Approvals ``` ## Module configuration boundary `arco-module-manual.md` owns the universal approval-related controls that every enabled module exposes. Approvals does not redefine those controls. When a module's configured control requires consent, this file owns the approval mechanism used to obtain and return that consent. Permissions still determine who belongs inside the module's authorised population. The module README owns what its outputs/actions actually are. Deployment/System Setup owns the selected values for that deployment. More granular approval routes may be added where real use requires them, but they must use the shared Approvals mechanism rather than creating module-specific approval engines. ## Learning and proposed-change queue Arco should learn from real interactions without turning every useful observation into an immediate edit. Where an interaction exposes a material weakness or improvement in a maintained deployed/local file: 1. identify the maintained file that owns the behaviour; 2. create a proposed change against that file rather than silently editing another layer; 3. where approval is required, submit the proposal into the owning file's proposal queue without requiring the user to manually ask for submission; 4. if multiple proposals are waiting against the same file, reconcile them together rather than sending separate competing edits to the approver; 5. construct the combined candidate change; 6. run the relevant Dry Runs against that combined candidate, including realistic outcome tests; 7. surface conflicts, failed tests or material trade-offs; 8. present the System Governor or other configured approving authority with one reconciled proposed change and the validation evidence; 9. only publish the maintained change after approval. Conceptually: ```text user interactions ↓ material improvement detected ↓ proposal against owning file ↓ proposal queue ↓ reconcile overlapping proposals ↓ combined candidate ↓ Dry Runs ↓ reconciled proposal + evidence ↓ approving authority ↙ ↘ approve reject ↓ publish ``` The approval unit is therefore the reconciled maintained change, not necessarily each individual observation that contributed to it. Where **automatic system updates are ON**, the same learning loop may publish eligible deployed/local operating changes after the required validation and maintenance steps without waiting for approval. Where automatic system updates are OFF, the reconciled candidate waits for approval before publication. Module outputs follow the separate **output approval** setting. ## Relationship to Permissions Permissions defines the population that may access/use a module or perform an action within its scope. Approval configuration then determines whether members of that authorised population may execute/update directly or require a second consent step. Conceptually: ```text requested action ↓ permission check ↙ ↘ not eligible eligible ↓ ↓ stop approval required? ↙ ↘ no yes ↓ ↓ execute Approvals ↓ approve / reject ↙ ↘ execute stop ``` A Permission does not bypass an approval requirement configured for the action/module. Equally, an approval must not create authority that the Governance model explicitly forbids. ## Approval rules An Approval Rule defines when approval is required and the authority that can provide it. A rule will likely need to identify at least: - the action or action class; - the governed resource or scope where relevant; - the required approving authority; - the outcome required before execution. The exact schema is not yet canonical. Approval rules should use maintained Roles, Permission Groups or other Governance authorities rather than hard-coding named individuals wherever possible. ## Approving authority An approval rule may target: - an Arco Role; - a Permission Group with approval authority; - an organisational group/team whose membership is resolved through Context and Governance mappings; - a person holding the required permission; - a specifically named person where the deployment deliberately requires that; - another governance authority deliberately defined later. Examples: ```text System Governor approval required ``` or ```text Approval required from someone with: approve → CTX-### ``` Approvals should not independently infer authority from a job title. Where organisational information is relevant, use the maintained Context / authoritative organisational source and the Governance mappings built from it. ## System Governor The System Governor is the fallback approval authority only where the system cannot resolve a more specific maintained approval authority. When **Automatic system updates are OFF** for the relevant module and no more specific maintained approving authority is configured, proposed changes to deployed/local Arco operating or configuration instructions default to System Governor approval. This does not turn the System Governor into the automatic approver for every governed domain action. ## Champion proposals Champion actions provide a useful default pattern for organisational deployments. A Champion may be granted permission to propose a change without being granted permission to publish or execute it directly. Example: ```text Champion ↓ propose change ↓ approval required ↓ System Governor ↓ approve / reject ``` The deployment may configure different approval authorities for different Champion actions. ## Approval stages The default Approval flow should use one approval stage. A deployment or module may require multiple sequential approval stages where a real workflow needs them. Each stage should identify its required authority and must complete before the next stage becomes effective. Do not introduce multiple stages by default. Quorum, parallel approval and voting semantics remain unresolved until demonstrated use requires them. ## Approval request An approval request should contain enough information for the approver to understand the action without reconstructing the full conversation. At minimum, it should identify: - proposed action; - relevant resource or scope; - proposer/requester; - required approving authority; - reason/context sufficient for the approval; - current approval state. Where the calling subsystem already has a stable record ID, the approval should reference that record rather than duplicate its full contents. ## Approval state The minimum useful states are likely: ```text pending approved rejected ``` Additional states such as `cancelled`, `expired`, `superseded` or `needs-information` should only be added when real workflows require them. ## Approval result Approvals returns the result to the calling subsystem. Approvals does not itself complete the domain action unless that action is explicitly part of the approval mechanism. Example: ```text Skill proposes publish ↓ Approvals returns: approved ↓ Skills performs publication ``` ## Reusable decisions and ambiguity Where an approval resolves a reusable governance ambiguity rather than a one-off case, the durable rule should be written to the maintained source that owns it. Do not force future actions to request the same approval merely because the governing rule was never recorded. ## Approval records Pending and materially significant approvals may need durable records. The exact Approval Register/log design is not yet canonical. An approval record should not duplicate the underlying Decision, Context change, Skill change or other domain record. It should reference the relevant stable record where possible. ## Relationship to Decisions Decisions is a separate optional module. When a Decision requires approval, Decisions should call Approvals. Approvals owns the approval process; Decisions owns the Decision record, dependencies, rationale and final durable organisational memory. Not every Decision requires approval. Not every Approval creates a Decision. ## Boundaries Approvals does not: - own the underlying domain action; - determine organisational job titles; - maintain the org chart; - define Role responsibilities; - define atomic Permissions; - create duplicate copies of Decision or Context records; - assume every durable change requires approval; - require the System Governor to approve everything. ## Still to define - canonical Approval Rule schema; - exact rule precedence and conflict resolution; - quorum / parallel approval / voting semantics beyond the established sequential-stage model; - delegation, expiry and absence behaviour; - approval notification and reminder behaviour; - Approval Register/log requirements and the exact proposal-queue representation; - what minimum audit evidence is required; - the exact distinction and data model for approval, verification and acknowledgement; - whether some approval categories may be automatically satisfied by sufficiently trusted Roles; - how external systems execute approval actions where Arco itself cannot enforce them. ## Changelog | Date | Version | Change | Approved by | Changed by | |---|---|---|---|---| | 15-Sep-2026 | 0.5.0 | Removed the stale global-Approvals toggle condition from the System Governor fallback and aligned maintained deployed/local change approval with the Module Manual: Automatic system updates OFF invokes the shared approval route. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.4.1 | Updated the live module-configuration boundary pointer to `arco-module-manual.md`; historical changelog references remain unchanged. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.4.0 | Moved ownership of the universal per-module controls to `arco-module-standard.md`; Approvals now owns only the shared consent mechanism invoked when a module/deployment setting requires approval. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.3.0 | Replaced the single module approval flag with two simple per-module controls: Automatic system updates (ON by default) and Output approval; added plain-language onboarding and reserved granular approval points for optional advanced controls. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.2.1 | Clarified the boundary between Permissions and Approvals: Permissions define the authorised module population, while `approvals: false` means any user within that population may update eligible module-owned content/records without a second approval step. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.2.0 | Added deployment/module-level approval enablement, the maintained-file proposal queue and reconcile→Dry Run→approval learning loop, organisational-group approving authorities, and one-stage-by-default with optional sequential approval stages; clarified that deployment approval settings do not govern upstream Core. | Stoirm Arnold | GPT-5.6 Sol | | 15-Sep-2026 | 0.1.0 | Established Approvals as the reusable Governance approval mechanism, including its relationship to Permissions, approval rules and authorities, System Governor fallback, Champion proposal flow, minimal request/state/result model, and separation from Decisions and calling subsystems. | Stoirm Arnold | GPT-5.6 Sol |