---      
name: Arco design      
version: 1.12.1
status: active      
owner: Stoirm Arnold      
last_updated: 30-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 individual Development records. The unresolved Development Register indexes the current active pipeline; resolved records/Register retain historical provenance. 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view) 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view), [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view).




## 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view). 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view).




## 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view); deployment mechanism remains in [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view).




## 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-modules.md](https://drive.google.com/file/d/1GcMnF4pLmxIhPRUlrPalmdAjjTkWUOX1/view).




## 1.7 Functions are bounded operations, not maintained knowledge domains




### Problem      
A named capability can be mistaken for a Module merely because it is reusable, or for a Skill merely because it contains instructions. That would make every useful operation a candidate subsystem and encourage duplicate capability before existing behaviour has been examined.




### Decision      
A Function is a bounded, invocable operation that performs a specific action on Arco or its operating environment. It does not own an independent domain of durable knowledge.




A Module owns a maintained domain with its own durable knowledge, behaviour and lifecycle. A Skill preserves a repeatable way of performing work. A Function is distinguished by the bounded operation it performs, even where its implementation uses maintained instructions or invokes a Skill.




Functions may be provided by Arco Core or created within a deployment at organisation, unit or other appropriate local scope.




Before creating a maintained capability, use this sequence:




`discover → reuse → configure → extend → create`




A local Function may reuse or adapt principles from an existing Function without becoming a duplicate of it. For example, a Finance File Cleaner may reuse Defrag principles for detecting duplication, inconsistency and safe remediation while retaining its own Finance-specific purpose and scope.




### Why      
The boundary preserves useful reuse without turning every operation into a Module or a new standalone architecture. It also makes creation the last step: existing capability is discovered and adapted before another maintained component is added.




### Rejected / avoided alternatives      
**Treat every reusable operation as a Module.** Rejected because an operation does not necessarily own an independent knowledge domain or lifecycle.




**Treat every Function as a Skill.** Rejected because the architectural distinction is the bounded action performed, not merely the existence of repeatable instructions.




**Copy an existing Function whenever local needs differ.** Rejected because principles can be reused or adapted without creating an unnecessary duplicate.




**Create a Functions README, Register or subsystem now.** Rejected because the operating mechanics have not yet been proven through enough real Functions.




### Implications      
Core Functions such as Dry Runs, Defrag, Token Totter and Sitemapper remain canonical Core operations. Deployments may add locally scoped Functions where a real operation requires one. Discovery, inheritance, scope representation and any future registry mechanics remain development questions until proven through use.




### Canonical implementation      
[arco-readme.md](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view), [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view), [arco-defrag.md](https://drive.google.com/file/d/1UdSitmm8FEgmoIOC4tqGV6_ugKh7r0nk/view), [arco-token-totter.md](https://drive.google.com/file/d/1npsqxO1lgWSQaQjeIf9MqYmHfuNh9MPf/view), [arco-sitemapper.md](https://drive.google.com/file/d/1-hJQ6kYzlp9jwUSUergxT8okciwuNgqj/view).




# 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](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view).




## 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](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view) 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](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view), [arco-dry-runs.md](https://drive.google.com/file/d/1Fe2PJd-IGIE5UlZmOlr0d3mThRkKbhX7/view).




# 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      
[arco-skills.md](https://drive.google.com/file/d/1k5LCI4ElPgVN4wpkMmc39T3YIEq8X6E1/view).




## 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      
[arco-skills.md](https://drive.google.com/file/d/1k5LCI4ElPgVN4wpkMmc39T3YIEq8X6E1/view) 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      
[arco-personas.md](https://drive.google.com/file/d/1J7UIPd1YVF9ve4Au7kQCP3uZA-UHOrlD/view).




# 5. Context




## 5.1 Context normalises source material into one maintained runtime authority

### Problem
Mixed external sources need a consistent runtime representation without competing copies of organisational truth.

### Current decision and why
Context normalises deliberate ingestion into canonical Arco Context. Once verified, that Context is the maintained runtime authority for the ingested information; the input remains provenance and is visibly archived or superseded. Continuing operational sources feed the configured update/verification process rather than becoming a parallel runtime Context layer.

### Superseded choice
Earlier Design described external input as continuing runtime authority after ingestion. The Context v1.4.0 clarification replaced that interpretation to prevent search from treating old source copies and maintained Context as competing truth. Organisations still keep operational systems as configured sources; Arco does not require wholesale replacement of those systems.

### Canonical implementation
[arco-context.md](https://drive.google.com/file/d/1cHuOYhziNB8Iv1BMs-iP-5r4YEnS1XZp/view) and its Core Context templates.

## 5.2 The Context Register is the pre-load identity and lifecycle index, not another Governance layer




### Problem      
Arco must resolve names and aliases before it knows which Context record to load. Human-readable names can change or legitimately collide, while verification/freshness/accountability need stable reference points. Putting all of that inside each record would require opening records merely to identify them; moving it into Governance would duplicate resource identity.




### Decision      
Organisational deployments maintain a structured Context Register. It owns stable Context IDs, canonical lookup names, aliases/alternative terms, canonical record pointers and Context lifecycle/verification state. Governance may reference those stable IDs, but permission and approval mechanics remain owned by Governance.




If a lookup matches more than one valid record, Arco uses already-known qualifying context such as linked Person, Unit or stable ID where that makes the match unambiguous; otherwise it surfaces the ambiguity rather than silently choosing.




### Why      
This allows `alias → stable ID → canonical record` resolution before loading the record, keeps lifecycle state observable, and lets Governance address Context resources without creating a second catalogue. The Turntabl dry run directly exposed both requirements: aliases such as `Storm` needed pre-load resolution, while duplicate titles such as `Systems Administrator` proved that canonical names are not guaranteed unique.




### Rejected / avoided alternatives      
**Store aliases only inside Person/Position records.** Rejected because the system would have to open candidate records before it could know which record the alias meant.




**Use display names as unique identifiers.** Rejected because names can change and legitimate duplicates exist.




**Create a separate alias registry.** Rejected because the Context Register can own lookup identity without another maintained index.




**Put Permissions/Approvals into the Context Register.** Rejected because Context owns resource identity/state while Governance owns authority.




### Canonical implementation      
[arco-context.md](https://drive.google.com/file/d/1cHuOYhziNB8Iv1BMs-iP-5r4YEnS1XZp/view), [arco-context-register-template.md](https://drive.google.com/file/d/12_MMZPTct0KvoLLp0iwFSvDNAg8-BtSJ/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view).




## 5.3 Person and Position have separate lifecycles




### Problem      
A person can join, leave or change job while the organisational position and reporting structure persist. Treating job title/reporting relationships as attributes of a Person makes structural Context fragile and forces widespread rewrites when occupancy changes.




### Decision      
Position is a foundational Context entity separate from Person. Reporting normally resolves Position-to-Position; a Person occupies a Position through an assignment that can carry effective dates.




### Why      
This preserves structural continuity, represents vacancies, and lets person movement update occupancy without rewriting the underlying organisational model. The Turntabl prototype and dry run demonstrated real positions with separate occupants and reusable reporting relationships.




### Rejected / avoided alternatives      
**Store manager/team/title directly as the primary Person structure.** Rejected because it duplicates organisation structure and couples person identity to a temporary assignment.




### Canonical implementation      
[arco-context.md](https://drive.google.com/file/d/1cHuOYhziNB8Iv1BMs-iP-5r4YEnS1XZp/view), [arco-context-position-template.md](https://drive.google.com/file/d/1CPnlWn7vI8h8KIEl1ImQDFjPOd0NTw5T/view), [arco-context-person-template.md](https://drive.google.com/file/d/1NPGo-OlLtqhdjWiRc3KfsVQ62OP0ja2X/view).




## 5.4 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 information expected to remain useful beyond a single planning cycle. Faster-changing strategy/priorities should live in separate appropriate Context areas rather than being mixed into foundational records.




### Why      
Different information needs different freshness, ownership and loading behaviour. The Turntabl migration deliberately excluded the existing Strategy and Current Position material from foundational Organisation Context.




### 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      
[arco-context.md](https://drive.google.com/file/d/1cHuOYhziNB8Iv1BMs-iP-5r4YEnS1XZp/view).




## 5.5 Person Working Context is shared collaboration Context, not manager assessment




### Problem      
Information about how to communicate with and work effectively with somebody is broadly useful, but strengths assessment, development interests, behavioural evidence, coaching and performance observations have a different audience, sensitivity and evidence lifecycle. Combining them would turn foundational Context into a management dossier.




### Decision      
Person Working Context contains durable collaboration information useful to colleagues and AI, such as communication, information-format, decision, feedback/challenge, escalation and working-pattern preferences. Manager-oriented assessment remains outside foundational Context and is reserved for the emerging People Management module.




### Why      
This keeps onboarding lighter, preserves the distinction between self-provided collaboration Context and manager-oriented evidence, and allows future People Management to infer longitudinal understanding from real interactions rather than forcing people to self-label unnecessarily.




### Rejected / avoided alternatives      
**Ask every person to self-declare strengths, expertise and development areas as foundational Context.** Avoided because those claims can be subjective, manager-specific and better supported by evidence accumulated over time.




### Canonical implementation      
[arco-context-working-profile-template.md](https://drive.google.com/file/d/13DZbqdA8tYAOqyADKd_EV4wKntGyxwPl/view); future manager-oriented capability remains in `development/people-management.md` while active Development continues.




## 5.6 Context is selectively loaded and should influence answers without unnecessary narration




### Problem      
Not every task needs every piece of organisational or personal Context. Loading everything wastes context, increases privacy exposure and can make answers annoyingly recite background facts simply because the system knows them.




### Decision      
Arco resolves the relevant records through the Context Register, loads only the smallest useful Context set permitted for the task, and uses that Context to shape the answer. Background Context should not be narrated merely to demonstrate that it was loaded.




### Why      
The value of Context is better decisions and more relevant behaviour, not repeated trivia. The Turntabl behavioural dry run explicitly tested this invisible-influence requirement alongside uncertainty preservation and Governance boundaries.




### Rejected / avoided alternatives      
**Load all Context into every request.** Rejected for efficiency, relevance and confidentiality.




**Echo background facts whenever Context influences an answer.** Rejected because it creates noisy responses and confuses useful influence with citation-like narration.




### Canonical implementation      
[arco-context.md](https://drive.google.com/file/d/1cHuOYhziNB8Iv1BMs-iP-5r4YEnS1XZp/view), Governance files for access boundaries.




# 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](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view).




## 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](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), [arco-roles.md](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view), [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view).




## 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](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view).




## 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](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view), [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view).




## 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](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view), [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view).




## 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-log.md` and the relevant Development record 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](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view).




## 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](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view) 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](https://drive.google.com/file/d/1JmdNUNPVJLxFbNQKYS3cJTnDPJ6hRvxb/view), [arco-permissions.md](https://drive.google.com/file/d/1dSRRfHv8Bz3aDBy8OxiP-IjnuskCEVy5/view).




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




### Problem      
Skill publication, Decisions and system changes may need approval. Context factual verification is separately owned by Context and is not an Approvals action. 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](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view).




## 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 use `automatic_system_updates: false` by default; the former ON default was superseded by Module Manual v0.4.0. The configured Boolean determines 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](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view) owns the universal module controls; [arco-approvals.md](https://drive.google.com/file/d/1-LpCSwdAQliIM6bnnUrQCl8ywk5cVGP-/view) owns consent mechanics; deployment configuration remains under development in [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view) and any relevant Development record.




## 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](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view) 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view) → [arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view) → module-specific README/local configuration. Existing and future modules should point/inherit rather than restate universal requirements.




### Canonical implementation      
[arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view); [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view) 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 a confirmed Arco Module at Draft maturity. It owns the durable organisational decision domain — proposals, decisions, lifecycle/state, acknowledgement or verification where relevant, supersession, history and associated maintained records.




Decisions consumes Governance for Roles, Permissions and Approvals where required rather than owning or redefining those 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 Draft Module status: [arco-modules.md](https://drive.google.com/file/d/1GcMnF4pLmxIhPRUlrPalmdAjjTkWUOX1/view); detailed Decisions operating files remain deliberately unbuilt while the module is designed.




## 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 Draft 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 Draft design 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](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view).




## 8.2 Core authoring and deployment are separate runtimes

### Current decision and why
Core maintenance works directly on canonical Core sources. A deployment, including one operated by the Core author, works from its own deployed operating copies and local configuration so it remains independent of upstream access.

### Superseded choice
An earlier authoring-host exemption permitted a deployment to read Core directly to avoid mirrors. Deployment independence and the later deployment-first Development boundary supersede that exemption. Avoiding pointless copies remains valid within Core authoring itself; it does not remove runtime separation for a deployment.

### Canonical implementation
[arco-readme.md](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view), [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view) and [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view).

## 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      
`readme-system-setup.md` owns deployment enabled/configured state. The deployment’s `readme-arco-guide.md` reflects that state through bounded conditional routing.




### 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](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view) ; unresolved extensions remain in Development.




## 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](https://drive.google.com/file/d/1UdSitmm8FEgmoIOC4tqGV6_ugKh7r0nk/view). Arcopsy remains in `development/arcopsy.md` until promoted.




## 8.5 Defrag evidence stays lightweight but durable




### Problem      
A Defrag can materially change several files at once. Without a durable run-level record, later reviews can reconstruct individual file history from changelogs but cannot easily answer how broad a review was, what it changed, or how system health evolved over time.




### Decision      
Every completed Defrag creates one concise report and one row in a Google Sheets Defrag Register. The report owns findings and the reviewed-file/version ledger; the Register owns the lightweight historical index and run-level counts.




Manual deletion candidates that cannot be removed safely by available tooling are moved to `/Arco/Archive/Delete/` so cleanup remains obvious and deliberate.




### Why      
This creates enough evidence to compare Defrags over time — files reviewed, files updated, deletions and unresolved questions — without creating a second operating system around the review itself.




### Rejected / avoided alternatives      
**No filed report for clean runs.** Avoided because absence of defects is still useful historical evidence and otherwise makes review coverage impossible to verify later.




**Put all file-level detail in the Register.** Avoided because it would turn a lightweight index into a duplicate report and make the Sheet increasingly difficult to scan.




### Canonical implementation      
[arco-defrag.md](https://drive.google.com/file/d/1UdSitmm8FEgmoIOC4tqGV6_ugKh7r0nk/view), `/Arco/defrag/arco-defrag-register` and `/Arco/defrag/reports/`.




# 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](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view) defines how system Development works. The unresolved Development Register indexes the current pipeline and routes to unresolved records; the resolved Register and records preserve historical outcomes. `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. Separating the operating guide from the working Log also prevents current pipeline churn from bloating the Development rules.




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




**Mix Development rules and the active pipeline in one file.** Rejected because routine pipeline changes and stable operating rules have different maintenance needs.




**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. The completed record and row move to resolved history only when the item’s own Development responsibility is complete.




### Canonical implementation      
[arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view), its unresolved/resolved Registers and records, and this file.




## 9.2 Development is an architecture mechanism, not a Module




### Problem      
Development owns changes to Arco itself, while Modules own durable system domains that can be enabled and operated as part of the runtime. Treating Development as a Module would blur system evolution with the things the system operates.




### Decision      
Development is confirmed as a non-module architecture mechanism.




It exists in Core and may be deployed into an organisation so the System Governor and Champions can collaborate on system changes.




Development owns proposals to alter Arco. The former separate Ideation module is retired; general exploratory working thoughts may remain in Notes.




### Why      
System change needs shared visibility, collaboration and testing without pretending that the change pipeline is an independent business knowledge domain.




### Rejected / avoided alternatives      
**Make Development a Module.** Rejected because Development changes the operating system rather than owning a durable runtime domain.




**Keep Development only in Core.** Rejected because deployments need a governed shared place for their own system changes and multi-user testing.




**Keep each Champion's Development private until promotion.** Rejected because it increases duplicate work and prevents collaboration on overlapping ideas.




### Implications      
Deployments maintain `readme-development.md`, local configuration, unresolved/resolved Development Registers and individual unresolved/resolved records where Development is enabled. Scope and testing scope are separate, and testing may begin at any appropriate scope rather than requiring Personal testing first.




### Canonical implementation      
[arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view), [arco-deployment.md](https://drive.google.com/file/d/1RUQFHpdhcreslWIHgxtKNm9MZB78-6A-/view) and [arco-roles.md](https://drive.google.com/file/d/1FaKj8DJygVGb0MTfoyF5lOe-K7Igw4vg/view).




## 9.3 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view) 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. **Discover → reuse → configure → extend → create before adding a maintained capability.**      
11. **Do not create a module, register, role or process merely because one could exist.**      
12. **Keep governance simple first, granular when necessary.**      
13. **Separate responsibility, permission and approval.**      
14. **Preserve rejected alternatives when their reasoning will matter to future designers.**      
15. **Prefer provider-agnostic architecture where practical.**      
16. **Arco should reduce systems and coordination overhead, not become another source of it.**




## Deployment learning before Core promotion




**Decision:** every deployment, including the Stoirm Ltd authoring environment, owns its own Development runtime. A deployment does not write directly into Arco Core Development merely because Core is maintained by the same person or organisation.




**Why:** an authoring-environment exception hides whether the deployment architecture actually works. Local Development should own local evidence, testing and resolution. Reusable learning is then promoted across an explicit boundary into Core Development with source provenance.




The resulting pattern is:




```text      
deployment evidence      
    ↓      
deployment Development      
    ↓      
local validation / resolution      
    ↓ reusable proposal      
Arco Core Development      
    ↓      
Core validation / resolution      
    ↓      
Updater reconciliation      
```




Promotion does not automatically resolve a local DEV. It remains active while local testing, implementation or other responsibility continues; resolution records the actual destination and implementation outcome once that responsibility is complete. The Core DEV owns its separate Core lifecycle. The earlier handoff-only resolution rule is superseded by Development and Dev Rec.




One [arco-dev-scan.md](https://drive.google.com/file/d/1fLP7dT_2ATZTu39RO9w6tK2c2uXj9gXO/view) now applies the shared method with `local`, `core` or `full` scope. A full run processes the supplied deployment and Core, uses Dev Rec for material overlap, and invokes Updater once after the complete approved delta is known. This supersedes the former separate Local/Core child Functions while preserving their authority boundaries.

### Dev Scan evidence is separate from Development


**Problem:** Development records exist to describe proposed system changes and their lifecycle. Treating every Dev Scan execution as another DEV item would mix proposals with operational evidence and make the Development Registers a history of scans rather than a pipeline of changes.


**Decision:** Dev Scan owns a separate Core-only durable run history using `SCA-###` identifiers in one shared [Dev Scan Register](https://drive.google.com/file/d/1PJyOiQO-HdWN4z_xis5G_NMSI2vKM7Qg/view). A top-level scan records `scan_type` as `local`, `core` or `full`. A full scan creates one SCA record for the whole Local → Core → Updater run rather than separate child-run records.


Development records may note the SCA ID that processed them. A local deployment does not need access to the Core scan report merely because its DEV record retains that provenance.


**Why:** This preserves a clean distinction between **what change is proposed** (DEV) and **what processing run acted on it** (SCA). Keeping the scan register in Core gives the Core Function one authoritative run history across deployments without requiring each deployment to mirror Function evidence.


**Rejected / avoided alternatives:** logging scan runs as DEV items was rejected because it pollutes the change pipeline with execution evidence. Maintaining a separate Dev Scan Register inside each deployment was rejected because Dev Scan is a Core Function and local deployments do not need its run history to operate.


**Canonical implementation:** [Arco Dev Scan](https://drive.google.com/file/d/1fLP7dT_2ATZTu39RO9w6tK2c2uXj9gXO/view), and the [Dev Scan Register](https://drive.google.com/file/d/1PJyOiQO-HdWN4z_xis5G_NMSI2vKM7Qg/view).




## Emergent Context trial




The individual-first Context trial is owned in Core by [DEV-028-ARC](https://docs.google.com/document/d/1z6-fMpBFVp7oq56I4E5_fhZKGIMwz0kXa-0UjvV3xJI/edit), with deployment evidence retained under [DEV-002-STO](https://drive.google.com/file/d/13hU4Dy5Bjqv_jxIPGwjQy-V_phKWMS1i/view).




The hypothesis is that a deployment can start with a small evidenced set of durable Context objects, let useful record structure emerge through real use, and standardise proven patterns retrospectively through Defrag. One Context ID identifies the durable object rather than every section or assertion.




The trial uses **Current / Unresolved / History** for information state and a separate History Register for Context objects that leave the live set.




This is architectural evidence under test, **not yet a replacement for the current Core Context contract**. If the trial proves materially better, its reusable behaviour should be promoted through normal Development rather than silently changing Core Context.





## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 1.12.1 | Reconciled superseded Context authority, Development storage and promotion/scan rationale; Rolled the live changelog to five entries with archived history. | Stoirm Arnold — Defrag invocation | Codex Work |
| 24-Sep-2026 | 1.12.0 | Separated Dev Scan operational evidence from Development: Core-only SCA IDs/register, scan type, one record per top-level invocation, and DEV-to-SCA provenance. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 24-Sep-2026 | 1.11.1 | Recorded the `90-` convention for Core-adjacent, non-deployable authoring/marketing infrastructure. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 24-Sep-2026 | 1.11.0 | Added the deployment-first Development boundary, Local/Core Dev Scan split and the Stoirm emergent-Context trial rationale; kept the Context trial non-canonical pending evidence. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 21-Sep-2026 | 1.10.3 | Rolled the live changelog to the five-entry System Manual limit; older history remains preserved in the archived v1.10.2 release. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |