---
name: Arco Defrag
version: 1.0.0
status: active
owner: Stoirm Arnold
last_updated: 15-Sep-2026
---

# Arco Defrag

## Purpose

Defrag is Arco's internal architecture-maintenance function.

It reviews Arco Core and, where requested, a deployed Arco system for structural coherence, drift and unnecessary complexity. Its objective is to keep the operating waterfall aligned so that each concern has one clear owner and downstream layers inherit rather than duplicate upstream behaviour.

Defrag is a **system function**, not an Arco module or Skill.

## Boundary

Defrag looks inward at Arco itself.

It may inspect:

- Core architecture and canonical files;
- module catalogue and module contracts;
- Governance relationships;
- maintained-file standards and release archives;
- deployment configuration and routing when reviewing a deployment;
- Design and Development where architectural rationale or unresolved work is relevant;
- repository structure, pointers and enabled-state alignment.

Defrag does not:

- review a host environment for compatibility before deployment — that is Arcopsy;
- validate one proposed material change in isolation — that is a Dry Run;
- replace the System Manual, Module Manual, Governance, Design or any other source it checks;
- invent unresolved architecture merely to make a review appear complete;
- create modules, roles, registers, schemas or processes without an existing architectural decision that requires them.

## Trigger

Defrag is manual in v1.

Run it when explicitly requested. It is also appropriate to recommend a Defrag after a concentrated period of architectural change, promotion or reconciliation where cross-file drift is reasonably likely.

There is no fixed recurring cadence in v1. Establish one only if real use demonstrates that scheduled Defrag provides value.

## Operating principle

Defrag must read the architecture it is checking rather than maintain a duplicate checklist of Arco rules.

Start from `arco-readme.md` and follow the current authoritative waterfall and repository references. Load only the sources required to test the relevant layer.

Where architecture rationale affects interpretation, consult `arco-design.md`. Use `arco-development.md` to distinguish unresolved work from established behaviour, not as a substitute for canonical operating files.

## Review sequence

A full Defrag should proceed in this order:

1. **Reconstruct the declared architecture** from `arco-readme.md` and the files it routes to.
2. **Compare declaration with reality** — repository structure, canonical filenames, catalogue entries, deployed routing and enabled state where applicable.
3. **Check maintained-file integrity** against `arco-system-manual.md`, including metadata, versioning, changelogs and required release archives.
4. **Check module integrity** against `arco-module-manual.md`, verifying that each module satisfies the universal contract without duplicating the Manual.
5. **Check Governance coherence** across Governance, Roles, Permissions and Approvals, using realistic behavioural scenarios where static wording alone is insufficient.
6. **Check pointer and ownership integrity** for duplicate rules, stale references, competing sources of truth, orphaned configuration and upstream/downstream contradictions.
7. **Check Core/deployment coherence** where a deployment is in scope, including routing versus enabled state and Core-derived file drift.
8. **Review Design and Development hygiene** — resolved architecture should not remain as competing Development instruction; unresolved questions should not be silently promoted.
9. **Perform a complexity check** for redundant, dead or superseded architecture that existing rules already make unnecessary.
10. **Correct deterministic defects** that are unambiguously resolved by existing Arco rules.
11. **Validate material corrections** through `arco-dry-runs.md` before promotion.
12. **Re-run affected checks** and report the final state.

A scoped Defrag may run only the relevant subset, but it should preserve the same dependency order.

## Defect classes

### Self-correctable

Defrag may correct a defect without requesting a new architectural decision when the existing maintained system already determines the correct result.

Examples include:

- stale or incorrect canonical pointers;
- filename/reference drift after an approved rename;
- repository indexes that no longer match canonical structure;
- catalogue entries inconsistent with already-promoted architecture;
- missing required metadata or changelog updates where the intended value is known;
- missing release archives that can be recovered exactly from authoritative revision history;
- downstream files that fail an already-established upstream contract;
- obsolete wording that contradicts a newer canonical rule with one clear interpretation.

All corrections still follow the System Manual. Material corrections still require Dry Run validation.

### Stop and surface

Defrag must not choose between legitimate architectural alternatives.

Surface the issue for deliberate design when resolution would require, for example:

- a new ownership boundary;
- a new module, Role, register or system component;
- a new schema or precedence rule;
- a new permission or approval model;
- a choice between multiple plausible sources of truth;
- a new deployment convention not already established;
- a material behavioural trade-off not resolved by current Design or canonical files.

The unresolved issue should be recorded in the appropriate Development source when it is durable and material.

## Relationship to Dry Runs

Defrag and Dry Runs serve different purposes.

```text
Defrag
reviews current system coherence

Dry Run
validates a proposed material change before promotion
```

Defrag may discover and construct a correction. If that correction materially changes purpose, scope, behaviour, routing, responsibility, dependencies or system structure, Defrag must invoke the Dry Run process before publishing it.

Dry Run evidence should remain in the configured Dry Run evidence location. Defrag does not create a second validation system.

## Relationship to Arcopsy

```text
Arcopsy → host environment versus Arco
Defrag  → Arco versus itself
```

Arcopsy is deployment-facing compatibility/reconciliation. Defrag is ongoing internal architecture maintenance. They may identify related issues but should remain separate functions with separate scopes.

## Output

A Defrag completion report should be concise and include:

1. overall health;
2. passes / areas that are coherent;
3. defects found;
4. corrections applied;
5. unresolved architectural questions;
6. material Dry Run results where applicable;
7. recommended next priorities.

When a manual cleanup is required, include the **direct URL of the specific file or folder** so the user can act without having to locate it independently.

Defrag does not require a separate durable report file for every clean run. Durable evidence is created through the files it changes, their changelogs/archives, and any required Dry Run records. A separate Defrag evidence artifact should be created only when it has a demonstrated use.

## Safety and restraint

Defrag should prefer the smallest correction that restores coherence.

Do not reorganise healthy architecture for aesthetic consistency alone. Do not convert every observation into a system change. Do not erase historical archives or changelog records merely because terminology has since changed.

Historical evidence should remain historically accurate unless it is itself corrupt.

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 15-Sep-2026 | 1.0.0 | Promoted Defrag from Development into a live Core maintenance function using evidence from the first full Arco Defrag; established its inward-looking scope, manual trigger, waterfall-driven review sequence, deterministic-correction boundary, Dry Run handoff, Arcopsy separation and concise reporting standard. | Stoirm Arnold | GPT-5.6 Sol |