---
name: Arco design
version: 1.5.0
status: active
owner: Stoirm Arnold
last_updated: 15-Sep-2026
---

# Arco design

## Purpose

`arco-design.md` is Arco's architectural memory.

It records **why** Arco is designed the way it is: the problems architectural choices were intended to solve, the alternatives deliberately avoided or rejected, the trade-offs accepted, and the implications future designers should understand before changing the system.

It is as important to record why Arco **did not** choose an approach as why it did.

An unexplained constraint can easily be mistaken for accidental complexity. Design exists so deliberate constraints remain understandable after the original conversations and designers are gone.

## What this file is not

This file is not an operating manual.

It does not define runtime behaviour, deployment configuration, module instructions or maintenance procedure. Those rules belong to the canonical file that owns them.

The relationship is:

```text
arco-design.md
explains WHY
        ↓
canonical Arco / subsystem file
defines WHAT / HOW
```

If Design conflicts with a current canonical operating file, the canonical operating file governs current behaviour. The conflict should then be reviewed because it may indicate that the rationale has become stale or the operating change was made without updating Design.

## How to use Design

Consult Design when:

- proposing a structural change to Arco;
- adding, removing or merging a module or subsystem;
- changing a major ownership boundary;
- questioning why an apparent constraint exists;
- reviewing whether an older architectural assumption still holds;
- designing a deployment pattern that might affect Core architecture;
- performing architecture review or Defrag work.

A new architectural decision should record:

1. **Problem** — what problem or risk needed solving?
2. **Decision** — what architectural choice was made?
3. **Why** — why was this approach preferred?
4. **Rejected / avoided alternatives** — what meaningful alternatives were considered or deliberately not chosen, and why?
5. **Implications** — what should future designers understand before changing it?
6. **Canonical implementation** — which maintained file owns the actual operating rule?

Design is organised by architectural area rather than by date. It should preserve useful historical reasoning without becoming a development diary.

## Superseded decisions

When an architectural decision changes, do not silently erase the old reasoning.

Update the relevant design section so the current decision is clear, then retain enough of the superseded choice and the reason it changed to prevent future maintainers from accidentally recreating an already-understood failure or trade-off.

Detailed chronological development history remains in version history, changelogs, archives and `arco-development.md`. Design retains only the historical reasoning that remains useful to future architecture decisions.

# 1. Overall architecture

## 1.1 Durable state lives outside chat

### Problem
AI work naturally happens in conversations, but conversations are poor durable operating infrastructure. Context fragments across threads, instructions become inconsistent, and a future AI may not have access to the conversation in which an important rule was established.

### Decision
Durable organisational context, capabilities, perspectives, governance and operating rules live in maintained sources outside individual chats. Chats are working sessions, not sources of truth.

### Why
Arco needs continuity across people, models, interfaces and time. The system should not depend on a particular conversation being available or remembered. This also makes changes inspectable, versioned and maintainable.

### Rejected / avoided alternatives
**Use chat history or model memory as the operating system.** Rejected because availability and retrieval are inconsistent, important rules become difficult to audit, and organisational state becomes tied to an interface rather than controlled maintained sources.

**Put everything into one giant master prompt.** Rejected because it creates unnecessary context load, poor ownership boundaries and a single file that becomes increasingly difficult to maintain safely.

### Implications
If something matters to future system behaviour, it should eventually reach the maintained source that owns it. Not every conversation insight deserves promotion; real evidence should drive durable change.

### Canonical implementation
`arco-readme.md` and the relevant subsystem/module files.

## 1.2 Arco Core is separate from organisational deployment

### Problem
Some Arco behaviour is reusable across organisations, while paths, people, sources, permissions, enabled components and organisational knowledge are inherently local.

### Decision
Arco uses three conceptual layers:

```text
Arco Core
   ↓
deployed readme-*.md
   ↓
readme-*-local.md where local configuration is required
```

Core contains reusable organisation-agnostic behaviour. The deployed README is the organisation's runtime operating copy. Local configuration is isolated where necessary.

### Why
This allows Arco to improve centrally while deployments remain private, understandable and independently operable. It also distinguishes a reusable design improvement from a local organisational requirement.

### Rejected / avoided alternatives
**Keep Stoirm Ltd's working files as the universal Arco source.** Rejected because organisation-specific paths and assumptions would leak into a supposedly reusable system.

**Make every deployment directly use the remote Core file.** Rejected because runtime would depend on external availability and local organisations would have no stable operational copy.

**Put local configuration into every deployed operating README.** Avoided where the configuration can change independently, because it increases merge/update friction and mixes reusable behaviour with local state.

### Implications
Core improvements should be generalised deliberately. Organisation-specific changes remain local unless there is a conscious decision to promote them. Local companion files should only exist when there is real local configuration to isolate.

### Canonical implementation
`arco-readme.md`, `arco-deployment.md`, `arco-system-manual.md`.

## 1.3 Runtime independence and public distribution are different concerns

### Problem
External organisations need a stable way to obtain and compare Arco Core, but their live operation should not fail because Stoirm Ltd's distribution endpoint is unavailable.

### Decision
Arco Core is authored and maintained separately, then distributed through a public machine-readable surface such as `arco.stoirm.co.uk`. A deployment records its upstream Core source for comparison/update purposes, but runs from its local deployed copy.

### Why
Distribution enables adoption and future updates. Runtime independence preserves resilience, organisational control and predictable behaviour. The public distribution layer is therefore a source for installation and reconciliation, not a remote dependency that every AI request must call.

### Rejected / avoided alternatives
**Use the public Arco endpoint directly at runtime.** Rejected because an organisation's operating system should not depend on an external website being available and unchanged.

**Treat the public website as the editable source of truth.** Rejected because publication and authoring have different responsibilities. The public surface should distribute approved Core rather than become a second editing environment.

### Implications
The future distribution mechanism can become more automated without changing the principle that deployments remain locally runnable. The human-facing explanation at `arco.stoirm.co.uk` is useful, but the architectural importance of the endpoint is distribution of approved Core.

### Canonical implementation
`arco-readme.md`, `arco-deployment.md`. Distribution mechanics remain under development.

## 1.4 One responsibility, one source, one next hop

### Problem
As Arco grows, the same path, ID, rule or instruction can easily be repeated in several files. Repetition makes a system look convenient initially but creates drift when one copy changes and another does not.

### Decision
Arco follows a singular-pointer waterfall. A file owns its concern and points to the next authoritative layer rather than duplicating everything downstream.

### Why
The architecture becomes easier to change because there is one authoritative place to update. Higher layers remain stable when lower-level implementation changes. It also helps AI reason about authority: follow the waterfall rather than reconcile competing copies.

### Rejected / avoided alternatives
**Repeat important IDs and rules everywhere they might be useful.** Rejected because convenience at read time creates ambiguity and maintenance debt.

**Use cross-linked files that all describe each other.** Avoided because it produces a mesh rather than a directional operating model and makes authority harder to determine.

### Implications
When adding a pointer, first ask which file genuinely owns it. A downstream detail should not be added to an upstream router simply because it may save one read.

### Canonical implementation
`arco-readme.md`, `arco-system-manual.md`.

## 1.5 Selective loading and the deployment-specific AI guide

### Problem
Loading the entire operating system into every AI interaction wastes context and increases the chance that irrelevant instructions interfere with the task. Different organisations also enable different components.

### Decision
Each deployment has a small `readme-ai-guide.md` acting as the first-hop router to the smallest relevant set of enabled sources. There is no universal Core AI guide that every runtime uses verbatim.

### Why
Routing should reflect the actual deployment, not everything Arco could theoretically support. Keeping the first hop small improves context efficiency and reinforces the singular-pointer model.

### Rejected / avoided alternatives
**Load all Arco files for every task.** Rejected because most tasks do not need most of the operating system.

**Make Core's AI guide the universal runtime router.** Rejected because Core cannot know which modules, sources and local configuration an organisation has enabled.

### Implications
The AI guide is generated/configured as part of deployment and should reflect system setup rather than independently becoming the authority for enabled state.

### Canonical implementation
`arco-readme.md`; deployment mechanism remains in `arco-deployment.md`.

## 1.6 Modular architecture without empty architecture

### Problem
A monolithic system file becomes difficult to own and evolve. The opposite failure is to create a module, register and framework for every conceivable future requirement before it is needed.

### Decision
Arco uses separable modules where a body of maintained knowledge or behaviour has a genuine independent lifecycle and can be enabled where useful. Potential future needs remain in Development until their boundary is proven.

### Why
Modules create useful ownership boundaries. Restraint prevents architecture becoming an administrative project in its own right. The aim is less systems, not more.

### Rejected / avoided alternatives
**One monolithic Arco instruction file.** Rejected because unrelated concerns would become coupled.

**Pre-build every plausible module.** Rejected because speculative structure hardens assumptions before real use provides evidence.

### Implications
A feature is not a module merely because it has a name. The module catalogue should reflect architectural decisions already made, not act as a wish list.

### Canonical implementation
`arco-readme.md`, `arco-modules.md`.

# 2. System maintenance and validation

## 2.1 The System Manual is universal infrastructure, not a module

### Problem
All maintained Arco files need shared rules for naming, metadata, versioning, archives and changes. Repeating those rules in every module would create duplication.

### Decision
The System Manual owns universal maintained-file behaviour and sits beneath Arco as a universal operating layer rather than an optional module.

### Why
Maintenance rules apply to the operating system itself, regardless of which optional modules a deployment uses.

### Rejected / avoided alternatives
**Put maintenance rules inside each module.** Rejected because the same rules would be duplicated and drift.

**Treat maintenance as an optional module.** Rejected because Arco cannot safely maintain canonical operating files without a shared maintenance standard.

### Canonical implementation
`arco-system-manual.md`.

## 2.2 Dry Runs validate material changes without becoming another instruction layer

### Problem
A structurally valid file can still cause AI to interpret the system incorrectly. Architectural changes therefore need behavioural validation, not only proofreading.

### Decision
Material maintained-system changes are validated through Dry Runs before promotion. The System Manual owns the trigger; `arco-dry-runs.md` owns the mechanics; outputs are evidence only.

### Why
This separates **when must we validate?** from **how do we validate?**, preserving the waterfall. Evidence remains inspectable without becoming runtime instruction.

### Rejected / avoided alternatives
**Put dry-run procedure in every changed module or Development.** Rejected because the validation process would be duplicated.

**Route runtime AI to dry-run evidence.** Rejected because historical test evidence should not influence normal operating behaviour.

### Canonical implementation
`arco-system-manual.md`, `arco-dry-runs.md`.

# 3. Skills

## 3.1 Skills describe repeatable capability, not perspective

### Problem
Instructions that explain how work is performed are fundamentally different from instructions that tell AI how to think or review.

### Decision
Skills are maintained repeatable capabilities and workflows. They are separate from Personas.

### Why
A capability has procedure, inputs, outputs and operating behaviour. A perspective can be reused across many capabilities without becoming the workflow itself.

### Rejected / avoided alternatives
**Store workflow and thinking style together as generic prompts.** Rejected because it couples two independently reusable concerns.

### Canonical implementation
`/modules/skills/arco-skills.md`.

## 3.2 Skills use a Register because independently maintained assets need visible state

### Problem
As Skills multiply, filenames alone do not provide reliable identity, ownership, status or discoverability.

### Decision
Skills use stable IDs and a structured Register. The Register indexes state and governance metadata; it does not duplicate the Skill instructions themselves.

### Why
The asset can evolve or be renamed without losing identity, while operating instructions remain in the canonical Skill file.

### Rejected / avoided alternatives
**Use filenames as identity.** Rejected because names can change and filenames do not carry enough governance state.

**Copy Skill instructions into the Register.** Rejected because it creates a second source of truth.

### Canonical implementation
`/modules/skills/arco-skills.md` and deployment-specific Skills configuration.

# 4. Personas

## 4.1 Personas are separate from Skills

### Problem
A reusable reviewer or mode of thinking can be valuable across many workflows. Treating it as a workflow makes it difficult to reuse independently.

### Decision
Personas define how AI thinks, interprets or reviews. They do not define the operational procedure for completing a task.

### Why
Separating perspective from capability allows the same Persona to be applied to different Skills and conversations.

### Rejected / avoided alternatives
**Model a Persona as a Skill.** Rejected because "how to think" and "how to do" have different lifecycles and invocation needs.

### Canonical implementation
`/modules/personas/arco-personas.md`.

# 5. Context

## 5.1 Context should use existing authoritative sources rather than replace them

### Problem
Organisations already maintain people, structure and business facts in systems such as org charts, HR systems, documents and operational tools. Copying all of that into Arco would create competing truth.

### Decision
Context identifies authoritative sources and may maintain machine-readable representations for reliable AI use, but those representations do not silently replace the authoritative source.

### Why
Arco is an operating layer, not an excuse to rebuild every business system.

### Rejected / avoided alternatives
**Move all organisational information into Arco.** Rejected because it creates unnecessary migration, duplicated maintenance and authority conflicts.

**Allow AI to infer missing organisational facts freely.** Rejected because plausible inference is not a safe substitute for maintained fact.

### Canonical implementation
`/modules/context/arco-context.md`.

## 5.2 The Context Register separates identity/state from content

### Problem
Permissions, verification, freshness and accountability need stable reference points. Human-readable Context names can change, and embedding governance state into every Context file creates repetition.

### Decision
Organisational deployments maintain a structured Context Register containing stable Context IDs and lifecycle/governance state. The Context record owns the substantive Context; the Register indexes its state.

### Why
A stable ID lets Permissions and other systems refer to Context without depending on mutable wording. It also centralises verification and accountability without copying the Context itself.

### Rejected / avoided alternatives
**Use the display name as the permission/resource identifier.** Rejected because names can change.

**Create a second Governance-owned Context catalogue.** Rejected because Context already owns the resource identity.

### Implications
Governance references the Context Register's stable ID rather than inventing its own Context tags.

### Canonical implementation
`/modules/context/arco-context.md`, `arco-permissions.md`.

## 5.3 Foundational Context is separated from fast-changing operating state

### Problem
Purpose, history, business model and enduring responsibilities change at a different rate from annual strategy, current priorities, short-term risks and live plans.

### Decision
Foundational Context stores relatively durable knowledge. Faster-changing strategy/priorities should live in separate appropriate Context sources.

### Why
Different information needs different freshness, ownership and loading behaviour.

### Rejected / avoided alternatives
**Put all useful organisational information into one company profile.** Rejected because the profile becomes bloated and mixes very different maintenance lifecycles.

### Canonical implementation
`/modules/context/arco-context.md`.

## 5.4 Context is selectively loaded and privacy distinctions are preserved

### Problem
Not every user or task should receive every piece of organisational or personal Context. Private assessment, self-authored working context and organisational fact are not equivalent.

### Decision
Context preserves authority/privacy distinctions and loads only what is relevant and permitted for the task.

### Why
Useful organisational memory must not come at the cost of collapsing confidentiality or unnecessarily loading sensitive information.

### Rejected / avoided alternatives
**Make all Context globally visible once captured.** Rejected because organisational usefulness does not imply universal access.

### Canonical implementation
`/modules/context/arco-context.md`, Governance files.

# 6. Governance

## 6.1 Governance is foundational, not an optional module

### Problem
An organisational Arco deployment must know who may do what even if the organisation chooses not to enable optional modules such as Decisions.

### Decision
Governance is a foundational Arco subsystem for organisational deployments. Roles, Permissions and Approvals sit beneath Governance as components; they are not separate optional modules.

### Why
Authority cuts across Context, Skills, Decisions, deployment and system maintenance. It is infrastructure used by those areas rather than one domain feature among them.

### Rejected / avoided alternatives
**Make Governance a normal optional module.** Rejected because an organisational deployment still needs an authority model.

**Let every module define its own independent governance.** Rejected because users and roles would acquire inconsistent meanings across the system.

### Canonical implementation
`arco-governance.md`.

## 6.2 Governance starts simple and earns complexity

### Problem
A flexible authority system can easily become over-designed before an organisation has demonstrated a real need for multiple Roles, Permission Groups or approval layers. That creates setup friction and makes Arco feel like another administrative system rather than an operating layer.

### Decision
An organisational deployment should begin with the smallest workable governance model: one required System Governor, default user permissions for everyone else, and no additional Roles, Permission Groups or custom approval rules unless real use justifies them.

Additional structure is introduced only when a recurring responsibility, trust boundary, access requirement or approval need has been demonstrated.

### Why
Governance exists to make authority clear, not to maximise the number of controls. A simple baseline makes Arco deployable and understandable while preserving a path to finer control when the organisation actually needs it.

This also avoids confusing organisational complexity with governance maturity: a large organisation may still begin with a small Arco authority model and expand it from evidence.

### Rejected / avoided alternatives
**Design a complete RBAC model before deployment.** Rejected because it forces speculative decisions about roles and access before real use shows which distinctions matter.

**Create Permission Groups for every team or job title.** Rejected because organisational structure does not automatically imply a distinct Arco authority requirement.

**Make every user an explicit Arco Role.** Rejected because ordinary access can be represented by default user permissions without manufacturing unnecessary Roles.

### Implications
New Roles and Permission Groups should be justified by a concrete recurring need. If a one-off edge case appears, first ask whether existing permissions or an approval route can handle it before adding permanent governance structure.

### Canonical implementation
`arco-governance.md`, `arco-roles.md`, `arco-permissions.md`, `arco-approvals.md`.

## 6.3 Roles represent Arco responsibility, not organisational job title

### Problem
Organisational seniority or job title does not necessarily reflect someone's capability or authority to maintain Arco.

### Decision
Arco Roles represent named system responsibilities. Organisational job titles remain organisational facts. A deployment may map a job title, team or unit to an Arco Role or Permission Group, but the concepts remain separate.

### Why
This allows authority to follow actual system responsibility or trust rather than being hard-coded to hierarchy.

### Rejected / avoided alternatives
**Treat every organisational job title as an Arco Role.** Rejected because it duplicates the org chart and creates unnecessary system roles.

**Give all senior leaders broad Arco authority by default.** Rejected because organisational seniority is not the same as system competence or trusted operating responsibility.

### Canonical implementation
`arco-roles.md`.

## 6.4 System Governor is a Role because it carries accountability

### Problem
Arco needs a human authority for system-level ambiguity, governance and integrity. A permission bundle alone does not express who is accountable for that responsibility.

### Decision
Every organisational deployment has a System Governor Role.

### Why
The Role represents continuing responsibility, while Permissions express the atomic rights needed to perform it. This also avoids tying the concept permanently to one named individual.

### Rejected / avoided alternatives
**Make System Governor a Permission Group.** Rejected because the concept is accountability/responsibility, not simply access rights.

**Use "Administrator".** Avoided because Arco governance is broader than technical administration and should not inherit conventional platform-admin assumptions.

### Implications
The System Governor can change holder without changing the architectural responsibility. The Governor is a fallback authority, not the approver for every action.

### Canonical implementation
`arco-roles.md`, `arco-permissions.md`, `arco-approvals.md`.

## 6.5 Champion exists to enable contribution without full control

### Problem
Trusted people should be able to help Arco improve without receiving the full authority of the System Governor.

### Decision
Champion is an optional Arco Role for trusted contributors who can be granted proposal/contribution rights while publication or execution may still require approval.

### Why
This creates a participation path between ordinary user and system owner.

### Rejected / avoided alternatives
**Require the System Governor to originate every improvement.** Rejected because it creates a bottleneck and prevents distributed learning.

**Give Champions unrestricted publication rights by definition.** Rejected because contribution and final authority are different concerns.

### Canonical implementation
`arco-roles.md`, `arco-permissions.md`, `arco-approvals.md`.

## 6.6 VIP is deliberately not yet a Core Role

### Problem
There is a legitimate concept of a person who deserves broader authority because of demonstrated skill/trust rather than job title, but the precise responsibility and permission boundary is not yet proven.

### Decision
VIP remains an emerging Role concept in Development and is not yet part of the Core Roles definition.

### Why
Naming a useful concept is not enough evidence to harden its permissions into Core.

### Rejected / avoided alternatives
**Promote VIP immediately because the use case is plausible.** Rejected because Arco should build from demonstrated organisational need rather than speculative completeness.

### Implications
Turntabl or another real deployment can prove whether VIP is a genuine recurring Role, a Permission Group, or unnecessary.

### Canonical implementation
`arco-development.md` until deliberately promoted.

## 6.7 Permissions are atomic; Permission Groups are bundles

### Problem
If permissions are defined only through named roles/groups, it becomes difficult to understand exactly what someone can do or reuse the same right in different combinations.

### Decision
A Permission is an atomic `action + resource/scope` right. Permission Groups are reusable bundles of Permissions. Roles may grant Permissions or Permission Groups.

### Why
This separates responsibility, access and convenience:

```text
Role = responsibility
Permission = right
Permission Group = reusable bundle of rights
```

### Rejected / avoided alternatives
**Make Permission Groups the smallest unit of authority.** Rejected because groups would become opaque and difficult to compose.

**Encode permissions directly in job titles.** Rejected because organisational identity and system authority have different lifecycles.

### Canonical implementation
`arco-permissions.md`.

## 6.8 Governed resources use identifiers owned by their subsystem

### Problem
Permissions need stable targets, but Governance should not become the owner of every module's resource catalogue.

### Decision
Permissions reference stable resource identifiers maintained by the subsystem that owns the resource. For Context, that means the Context Register's stable Context ID.

### Why
It preserves ownership and prevents Governance from duplicating indexes already maintained elsewhere.

### Rejected / avoided alternatives
**Create one central Governance registry containing every resource.** Rejected because it would become a second catalogue that must be synchronised with every subsystem.

### Canonical implementation
`arco-permissions.md` plus the owning subsystem.

## 6.9 Mediated AI use and direct source access are separate rights

### Problem
A person may legitimately need an answer derived from maintained Core or organisational Context without needing direct access to browse, copy or edit the underlying source files.

### Decision
Governance treats AI-mediated use and direct source-file access as distinct permissions where the platform allows enforcement.

### Why
The useful unit of access is not always "can open the file". Arco is an operating layer through which controlled information may be used.

### Rejected / avoided alternatives
**Anyone who can use the knowledge can automatically open the source.** Rejected because it unnecessarily expands exposure and weakens governance.

### Canonical implementation
`arco-governance.md`, `arco-permissions.md`.

## 6.10 Approvals is a shared mechanism, not repeated module logic

### Problem
Context changes, Skill publication, Decisions and system changes may all need approval. If each implements approval independently, the organisation gets multiple incompatible approval systems.

### Decision
Approvals is a reusable Governance mechanism. The calling subsystem owns **what is being proposed**. Approvals owns **how required consent is obtained and returned**.

### Why
This creates one approval model that can be used across Arco while allowing each domain to retain ownership of its action.

### Rejected / avoided alternatives
**Make Approvals part of Decisions.** Rejected because many non-decision actions need approval.

**Let each module define its own approval workflow.** Rejected because it duplicates mechanics and authority rules.

### Implications
Not every action requires approval, and not every Approval creates a Decision.

### Canonical implementation
`arco-approvals.md`.


## 6.11 Approval complexity is configured, while learning is consolidated before approval

### Problem
If every module and every small interaction-derived improvement requires the System Governor to approve each edit individually, Governance becomes a bottleneck and Arco stops learning effectively from normal use. The opposite extreme — letting every interaction silently rewrite maintained files — weakens control and can create conflicting edits.

### Decision
The normal configuration model deliberately uses two simple approval dimensions per enabled module: **Automatic system updates** and **Output approval**. Their universal existence/default presentation is owned by the Module Manual rather than repeated across Governance and Deployment files. Automatic system updates are ON by default and determine whether validated deployed/local operating changes can publish automatically. Output approval determines whether the module's actual work products need consent before becoming final.

When approval is required, interaction-derived improvements are captured as proposals against the maintained file that owns the behaviour. Multiple proposals against the same file are reconciled into one candidate, validated through Dry Runs, then presented to the configured approving authority.

This separation prevents two different governance questions from being collapsed into one switch. A module may allow its outputs to be created freely while still requiring approval for changes to how the module operates, or vice versa. Permissions remain responsible for who can access the module. Deployment settings never grant authority over upstream Arco Core.

The default approval path is one stage; additional sequential stages are added only where a real workflow requires them.

### Why
This preserves two things at once: distributed learning from everyone's interactions, and controlled publication of material maintained changes. The Governor reviews coherent, tested changes rather than a queue of low-level observations.

It also allows modules with trusted operational owners — for example a future Policies module maintained by People Operations — to evolve their module-owned content locally without forcing every authorised content change through the System Governor, while preserving Governor control over changes to the module's operating/configuration layer.

### Rejected / avoided alternatives
**Require Governor approval for every maintained edit in every module.** Rejected because it creates an unnecessary central bottleneck and suppresses learning.

**Let every useful interaction immediately rewrite maintained files.** Rejected because concurrent observations can conflict and bypass governance/validation.

**Approve each proposal independently even when several target the same file.** Rejected because the proposals may interact; they should be evaluated together before publication.

**Use deployment approval settings to change upstream Core.** Rejected because Core and deployment authority are separate layers.

### Implications
System Setup should represent these two standard controls for each enabled module. More granular approval points may exist behind an optional advanced-control layer, but should not burden normal onboarding. Approvals still needs a proposal-queue/reconciliation mechanism, while Dry Runs remain responsible for testing candidate system changes.

### Canonical implementation
`arco-module-manual.md` owns the universal module controls; `arco-approvals.md` owns consent mechanics; deployment configuration remains under development in `arco-deployment.md` / `arco-development.md`.

## 6.12 Modules inherit one universal contract

### Problem
If every module README independently defines its required structure, governance hooks, update controls and setup behaviour, new modules will drift and a future Module Builder would need to carry a duplicate copy of Arco's module rules. If those same rules are put into the System Manual, file-maintenance standards and module architecture become unnecessarily coupled.

### Decision
Arco maintains one `arco-module-manual.md` defining the universal contract inherited by every module. Individual module READMEs contain only module-specific behaviour. The Module Manual points to the System Manual for maintained-file construction/maintenance and to Governance for Permission/Approval mechanics rather than copying those rules.

A future Module Builder consumes the Module Manual; it does not become another owner of module rules.

### Why
This preserves the singular-pointer waterfall while making module creation repeatable. New modules can be generated consistently without bloating each README or turning the System Manual into a catch-all architecture file.

### Rejected / avoided alternatives
**Copy the standard controls and structure into every module README.** Rejected because changes would need to be reconciled across every module.

**Put module architecture into the System Manual.** Rejected because the System Manual owns how maintained files are constructed/changed, not what makes a valid module.

**Let a future Module Builder embed its own template rules.** Rejected because the Builder should execute the canonical standard rather than become a second source of truth.

### Implications
A module can be created by following `arco-readme.md` → `arco-module-manual.md` → module-specific README/local configuration. Existing and future modules should point/inherit rather than restate universal requirements.

### Canonical implementation
`arco-module-manual.md`; `arco-system-manual.md` remains the sole owner of universal maintained-file construction/maintenance rules.

# 7. Decisions

## 7.1 Decisions is separate from Approvals

### Problem
An approval answers whether a proposed action may proceed. A Decision records what the organisation decided and why. These overlap sometimes but are not the same lifecycle.

### Decision
Decisions is an optional module candidate that consumes Governance/Approvals where required rather than owning approval mechanics.

### Why
Organisations may want approval flows without a Decision Register, and meaningful decisions can exist without a separate approval flow.

### Rejected / avoided alternatives
**Combine Decisions and Approvals into one module.** Rejected because it conflates organisational memory with consent workflow.

### Canonical implementation
Current module status: `arco-modules.md`; detailed Decisions module remains in development.

## 7.2 Decisions should preserve organisational reasoning, not become task management

### Problem
Tasks are operationally transient. The reason an organisation chose a path can remain important years later.

### Decision
The emerging Decisions model focuses on decision candidates, owners, dependencies, parent/child relationships, state, rationale and final durable decision memory. Tasks are deliberately outside the architecture.

### Why
The long-term question Arco should answer is often "why did we decide this?" rather than "what tasks existed around it?"

### Rejected / avoided alternatives
**Use the Decisions system as a task tracker.** Rejected because Arco is not intended to duplicate project-management tooling.

### Canonical implementation
Development until a Decisions Core module is promoted.

## 7.3 Candidate decisions are captured liberally before promotion

### Problem
If AI must decide with high confidence whether something is a real decision before recording it, meaningful decisions can be silently missed. If every possible decision enters the permanent register, noise overwhelms the system.

### Decision
The emerging model includes a temporary candidate/triage layer. AI should favour recall when detecting possible decisions. Candidates can then be promoted, clarified or discarded before entering the permanent Decision record.

### Why
This separates liberal detection from high-quality durable memory.

### Rejected / avoided alternatives
**Let AI silently filter uncertain decisions out.** Rejected because false negatives are difficult for humans to discover later.

**Put every candidate directly into the permanent Decision Register.** Rejected because false positives would clog durable organisational memory.

### Canonical implementation
Development until Decisions is promoted.

# 8. Deployment

## 8.1 Deployment copies Core instead of remotely referencing it

### Problem
An organisation needs a known local operating system that can be governed, inspected and run independently.

### Decision
Deployment installs the relevant Core-derived operating files locally.

### Why
Local runtime independence and organisational control outweigh the convenience of a single remote runtime source.

### Rejected / avoided alternatives
**Remote runtime references to Core.** Rejected for resilience, control and change-management reasons.

### Canonical implementation
`arco-deployment.md`.

## 8.2 The Core host does not create redundant mirrors of itself

### Problem
Applying the Core → deployed rule mechanically inside the organisation that authors Core can create pointless duplicate files whose only purpose is to mirror the same source.

### Decision
The Core-hosting environment may use the relevant Core definition directly where Core is intentionally its source of truth. If an external deployment needs a local copy of `arco-readme.md`, it is named `readme-arco.md`, never `readme-readme.md`.

### Why
The purpose of deployment copies is runtime separation, not duplication for its own sake.

### Rejected / avoided alternatives
**Require Stoirm Ltd to mirror every Core file solely for pattern purity.** Rejected because it violates the principle of less systems, not more.

### Canonical implementation
`arco-deployment.md`.

## 8.3 System setup should own enabled state

### Problem
Arco Core describes what can exist. The AI guide routes what the deployment actually uses. Without a distinct enabled-state source, the router can accidentally become configuration itself.

### Decision
The architecture is moving toward a small canonical system-setup/configuration record that owns deployment enabled/configured state. The AI guide should reflect that state.

### Why
It separates capability, configuration and routing:

```text
Arco Core = what can exist
        ↓
system setup = what this deployment has enabled/configured
        ↓
AI guide = routes what is actually enabled
```

### Rejected / avoided alternatives
**Treat `readme-ai-guide.md` as the authority for enabled state.** Avoided because routing and configuration are different responsibilities.

### Canonical implementation
`arco-deployment.md` and `arco-development.md` until finalised.

## 8.4 Arcopsy looks outward; Defrag looks inward

### Problem
Deployment compatibility and ongoing internal architecture coherence are different review problems.

### Decision
**Arcopsy** reviews the host environment for compatibility, duplication, conflict and reusable sources during adoption/deployment. **Defrag** is a live Core maintenance function that reviews Arco itself for internal architectural coherence over time.

### Why
Combining them would create a broad system-review function with unclear scope and ownership. The first full Defrag demonstrated that this inward review is best treated as a Core maintenance function rather than a module or Skill: it does not own a domain capability or output, but consumes the existing architecture to test coherence and invokes Dry Runs only for material corrections.

### Rejected / avoided alternatives
**One generic integrity review for everything.** Rejected because deployment compatibility and ongoing internal coherence require different questions and triggers.

### Canonical implementation
Defrag: `arco-defrag.md`. Arcopsy remains in `arco-development.md` until promoted.

# 9. Design, Development and architecture review

## 9.1 Design and Development have different jobs

### Problem
Active exploration and durable rationale both involve architecture, but mixing them makes it difficult to distinguish unresolved thinking from decisions the system is intentionally built around.

### Decision
`arco-development.md` holds emerging architecture, experiments and unresolved questions. `arco-design.md` holds durable rationale for architectural decisions that have been made.

### Why
Development can remain fluid without weakening the clarity of established architectural memory.

### Rejected / avoided alternatives
**Use Development as permanent rationale history.** Rejected because the file accumulates unresolved and superseded thinking and is not organised for future decision guidance.

**Put rationale inside every operating file.** Rejected as a default because it bloats operational sources and risks mixing explanation with executable instruction.

### Implications
When development resolves into architecture, the operating rule moves to its canonical owner and the important rationale moves into Design.

### Canonical implementation
`arco-development.md`, this file.

## 9.2 Design should guide change without governing runtime

### Problem
If Design becomes another rule source, Arco recreates the duplication it is intended to prevent.

### Decision
Design is consultative architectural memory. Canonical operating files remain authoritative for behaviour.

### Why
The system needs historical reasoning without another runtime instruction layer.

### Rejected / avoided alternatives
**Route ordinary runtime work through Design.** Rejected because most tasks do not need architectural rationale and it would waste context.

### Implications
Design is especially important for architecture work, Defrag and future Core evolution, but should not be loaded routinely.

### Canonical implementation
`arco-readme.md` and deployment routing when architecture work warrants it.

# 10. Principles for future design decisions

When extending Arco, prefer choices that preserve these architectural intentions:

1. **Durable state outside chat.**
2. **One responsibility, one authoritative source.**
3. **A directional waterfall rather than duplicated cross-linking.**
4. **Core remains organisation-agnostic.**
5. **Deployments remain runtime-independent.**
6. **Existing organisational sources remain authoritative where appropriate.**
7. **Load the smallest useful context set.**
8. **Separate reusable behaviour from local configuration.**
9. **Build from demonstrated need rather than speculative completeness.**
10. **Do not create a module, register, role or process merely because one could exist.**
11. **Keep governance simple first, granular when necessary.**
12. **Separate responsibility, permission and approval.**
13. **Preserve rejected alternatives when their reasoning will matter to future designers.**
14. **Prefer provider-agnostic architecture where practical.**
15. **Arco should reduce systems and coordination overhead, not become another source of it.**

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 15-Sep-2026 | 1.5.0 | Promoted Defrag from an emerging concept to a live Core maintenance function, preserving its separation from Arcopsy and establishing why it is neither a module nor Skill and why material repairs still hand off to Dry Runs. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.4.1 | Updated current architectural-memory references to the renamed `arco-module-manual.md` while preserving historical release records. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.4.0 | Added the rationale for a single inherited Module Standard, separated module architecture from System Manual file-maintenance rules, and established that a future Module Builder consumes rather than duplicates the standard. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.3.0 | Simplified module approval design to two standard controls—Automatic system updates and Output approval—while reserving granular approval points for optional advanced controls and keeping Permissions as the access boundary. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.2.1 | Clarified the architectural separation between module Permission scope and approval gating: Permissions define who belongs to the authorised population; `approvals: false` allows that population to update eligible module-owned content without a second approval step. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.2.0 | Added the design rationale for globally/per-module configurable Approvals and for consolidating interaction-derived proposals by owning file before Dry Run and Governor approval, while preserving the Core/deployment authority boundary. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.1.0 | Added the explicit design rationale for simple-by-default Governance after behavioural dry-run testing showed that the existing file explained Governance mechanics but not strongly enough why Roles, Permission Groups and approval complexity must be earned through demonstrated need. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 1.0.0 | Created Arco's architectural memory, recording the rationale, rejected alternatives and future implications behind the established Core/deployment/local architecture, runtime independence, singular-pointer waterfall, selective routing, modularity, System Manual and Dry Runs, Skills, Personas, Context, Governance, emerging Decisions design, Deployment, Arcopsy/Defrag boundaries, and the separation between Design and Development. | Stoirm Arnold | GPT-5.6 Sol |