---
name: Arco module manual
version: 0.6.0
status: draft
owner: Stoirm Arnold
last_updated: 30-Sep-2026
---




# Arco module manual




## Purpose
This file defines the universal contract that every Arco module must follow.




It exists so new modules can be created consistently without each module redefining shared module architecture.




The System Manual owns universal maintained-file rules. Governance owns Permissions and Approvals mechanics. Individual modules must explicitly define how their own resources and actions connect to those shared layers.




## Position in the waterfall




```text
arco-readme.md
        ↓
arco-module-manual.md
        ↓
module README
        ↓
deployment/local module configuration
        ↓
module outputs
```




## Universal module requirements
Every Arco module must define:




1. **Purpose** — what durable system knowledge or behaviour the module owns.
2. **Boundary** — what belongs inside the module and what does not.
3. **Outputs** — what the module creates, maintains or makes available.
4. **Dependencies** — other Arco layers/modules/external authoritative sources it relies on.
5. **Access scope** — the resource/scope Governance uses to determine who may access/use it.
6. **Governance integration** — the module-owned resources/actions that may be permissioned or approval-gated, and how the module hands authority/consent to Governance without recreating Governance mechanics.
7. **Deployment/local requirements** — configuration a deployment must supply, including local Governance mappings where organisational attributes such as Unit membership or Position affect permission groups/authorities.
8. **Lifecycle state** — maturity/status in the module catalogue.
9. **Maintenance route** — maintained files follow the System Manual.




A module should contain only the structure needed for actual use.




## Standard module controls




Every enabled module exposes the universal Output approval control defined below.




Core update distribution and deployment reconciliation are system-level responsibilities owned by Deployment and Updater, not per-module configuration. Do not create or retain an `automatic_system_updates` module toggle.




### Output approval




```yaml
output_approval: false
```




Default: `false` unless the deployment deliberately enables it.




Controls whether the module's outputs require approval before becoming final/effective.




If `false`, authorised users may create/update eligible outputs without a second approval step.




If `true`, the module sends the proposed output/change to the shared Approvals mechanism after the relevant Permission check succeeds.




Permissions always determine who is authorised to act. Approval never creates authority that Permissions do not grant.




## Required Governance integration
Every module README must make the following explicit where applicable:




- what the module treats as its permissionable resource/scope;
- what actions exist against that scope, such as view, propose, update, publish or execute;
- which module outputs are subject to the universal Output approval control;
- what organisational Context may be used by Governance to resolve membership/authority;
- what deployment-local mappings are required before those controls can operate safely;
- what happens when those mappings are not yet configured.




The module must not define Permission Groups or approval workflow mechanics itself. It should identify the module-owned resource/action and hand off to Governance.




The deployment/local configuration owns the selected value and any safe fallback required while local Governance mappings are incomplete.




## Advanced controls
More granular approval/workflow controls may be added where real use requires them, but they are not part of normal setup by default.




Verification and specialised lifecycle states belong to the relevant module where proven necessary.








## Module retirement




Retiring a module removes it from the live runtime; it is not represented as a permanently disabled live component merely for historical reference.




When a module is deliberately retired from a deployment:




1. remove it from the active System Setup manifest rather than retaining a legacy `module: false` entry solely for history;
2. remove its live first-hop routing and other active runtime references;
3. move the complete retired module runtime into the deployment module-level `Archive/<module-name>/` location, preserving enough provenance to understand what was retired;
4. treat that retired module archive as history only and keep it outside normal runtime discovery/routing;
5. preserve any separate per-file release archives already required by the System Manual; whole-module retirement storage does not replace release-version archives;
6. validate that live routing, configuration and enabled-component checks no longer resolve to the retired module.




Restoring a retired module is a deliberate deployment change: restore/reconcile the required runtime, add it back to System Setup, reinstate the intended routing and validate it before treating it as live. Merely finding an archived copy must never reactivate a module.




A deployment must not delete a retired module merely because it is no longer live unless a separate approved retention decision explicitly requires deletion.




## Relationship to Governance
Governance owns:
- [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view) — authority to perform actions against resources/scopes;
- [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view) — consent mechanism after permission is satisfied;
- Roles/Permission Groups and mappings from organisational Context into authority.




Modules own their domain resources/actions and the proposal/output being acted upon.




## Relationship to the System Manual
All maintained module files follow [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view) for naming, metadata, versioning, changelogs, archives, change control and Dry Runs.




## Module creation
A new module should be built by:
1. reading [arco-readme.md](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view);
2. reading this Module Manual;
3. following [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view);
4. defining module-specific purpose, boundary, outputs, dependencies, access scope and Governance integration;
5. defining required local configuration, including Governance mappings where needed;
6. adding the module to [arco-modules.md](https://drive.google.com/file/d/1GcMnF4pLmxIhPRUlrPalmdAjjTkWUOX1/view);
7. validating material architecture/change before promotion.




## Boundaries
This manual does not define detailed Permission or Approval mechanics, deployment-selected values, or individual module behaviour.








## Canonical references




[arco-governance.md](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view).




## Changelog




| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 0.6.0 | Removed the obsolete per-module `automatic_system_updates` control; Core update distribution/reconciliation remains owned centrally by Deployment and Updater. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 30-Sep-2026 | 0.5.1 | Restored canonical provider-link references; Rolled the live changelog to five entries with archived history. | Stoirm Arnold — Defrag invocation | Codex Work |
| 25-Sep-2026 | 0.5.0 | Added the universal module-retirement lifecycle: remove retired modules from live System Setup/routing, preserve the complete runtime under the module-level Archive, exclude it from normal discovery, and require deliberate validated restoration. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 21-Sep-2026 | 0.4.0 | Changed `automatic_system_updates` to default `false` so deployments do not claim an update mechanism that has not been implemented and proven. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 18-Sep-2026 | 0.3.1 | Completed the Boolean Output approval block with explicit `output_approval: false` configuration and default after verification found the value had not been written into the canonical section. | Stoirm Arnold | GPT-5.6 Sol |
| 18-Sep-2026 | 0.3.0 | Standardised universal module toggles as machine-readable Boolean configuration (`automatic_system_updates: true/false`, `output_approval: true/false`) in line with the System Manual; semantics unchanged. | Stoirm Arnold | GPT-5.6 Sol |