---
name: Arco Defrag
version: 1.7.1
status: active
owner: Stoirm Arnold
last_updated: 30-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 the Arco system being reviewed.








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 a deployment is in scope;
- Design and Development where rationale or unresolved work affects interpretation;
- repository structure, pointers and enabled-state alignment;
- enabled human artifacts, only when checking their coherence with the deployed system.








Defrag does not invent unresolved architecture merely to make a review appear complete. Where existing Arco rules do not determine one correct resolution, surface the issue for deliberate design instead.








## 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](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view) 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](https://drive.google.com/file/d/1gpksEY6NEge2Gm_ALJTEQ5l8vXlFkmfY/view). Use [arco-development.md](https://drive.google.com/file/d/1iInDSULzhX37AIRYFlIpBBdG3BSBslax/view) to distinguish unresolved work from established behaviour, not as a substitute for canonical operating files.








### Relationship to Token Totter








Defrag may identify over-broad routing, duplicated instructions or accumulated history as architecture defects. When the material question is the measured token/context cost of maintained files or realistic read paths, route the focused audit to [arco-token-totter.md](https://drive.google.com/file/d/1npsqxO1lgWSQaQjeIf9MqYmHfuNh9MPf/view) rather than duplicating its measurement and before/after method.








Token Totter does not replace Defrag's architecture-coherence review. Defrag establishes whether ownership and structure are coherent; Token Totter establishes whether the resulting context path is efficient without weakening Arco's purpose or controls.








## Review sequence








A full Defrag should proceed in this order:








1. **Reconstruct the declared architecture** from [arco-readme.md](https://drive.google.com/file/d/18BiUb3pyiHsF0JDj8ImtssObQciaDfrX/view) 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](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view), including metadata, versioning, changelogs and required release archives.
4. **Check module integrity** against [arco-module-manual.md](https://drive.google.com/file/d/1X3uzbh2_7cu_ZJGCwpcLSVyWihXHQxgZ/view), 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. **Check enabled human-artifact coherence** — where `arco-for-humans` is enabled, compare it with the current deployed architecture/configuration and flag removed, renamed, disabled, materially changed or materially omitted concepts. Human artifacts remain outside normal runtime context and are loaded here only for coherence checking.
9. **Review Design and Development hygiene** — resolved architecture should not remain as competing Development instruction; unresolved questions should not be silently promoted.
10. **Perform a complexity and output-hygiene check** for redundant, dead or superseded architecture, repeated fallback Outputs that indicate unclear ownership, obsolete Dry Run evidence and completed candidate workspaces; invoke or recommend Token Totter where measured context cost is the material issue.
11. **Correct deterministic defects** that are unambiguously resolved by existing Arco rules.
12. **Validate material corrections** through the existing Arco validation process before promotion.
13. **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;
- clean Dry Run evidence that is eligible for removal under the Dry Run standard;
- a completed deployment candidate workspace that is eligible for cleanup under the Deployment guide.








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.








A durable, material proposed system change that is not already owned by an existing DEV item must create or link to the appropriate `DEV-###` record under Development. The Defrag report/Register continues to own evidence of the Defrag run; Development owns the proposed system change.








## Output and filing








Every completed Defrag must create a durable report and add one row to the Defrag Register.








### Defrag report








Store Core reports under [Core Defrag reports](https://drive.google.com/drive/folders/1ZkDYTJYCHAsdYDi1Iz_zUvcOWbEwsrhH); deployments use the Defrag report location configured for that deployment, using the next `DFR-###` identifier from the Defrag Register. Name the filed report `DFR-###-YYYY-MM-DD.md` in accordance with the System Manual; do not prefix the filename with `defrag-`.








The report should remain concise and include:








1. overall health;
2. headline counts — maintained files reviewed, maintained files updated, files/folders deleted, and unresolved architecture questions surfaced;
3. material defects and corrections;
4. unresolved architectural questions;
5. recommended next priorities;
6. a final **Files reviewed** table listing every maintained file inspected, its state after review, and any version change made during the Defrag. When an enabled human artifact is checked, include it in this evidence.








Use simple states such as `Coherent`, `Updated`, `Flagged` or `Delete queued`. For an unchanged file, record the current version as `unchanged`; for an updated file, show `before → after`. Supporting deployment routing or archive structures inspected outside the maintained-file count should be noted separately.








### Defrag Register








The canonical Core [Defrag Register](https://drive.google.com/file/d/1kMYzbfexvuw7xxRImYQ9AlHbZhHFVZjL/view) is maintained in the [Defrag area](https://drive.google.com/drive/folders/1iuK2mzHbN3dNIq_dfhiMb76ywAbSBT1F). A deployment uses its own Defrag Register in the configured Defrag area. Register storage follows [arco-system-manual.md](https://drive.google.com/file/d/1doS7QXRtShzT45wHC13Vx0zxputK50l-/view). The Register is the lightweight index of completed Defrags and owns the next `DFR-###` identifier.








Each row records:








- Defrag ID;
- date;
- scope;
- overall health;
- files reviewed;
- files updated;
- files/folders deleted;
- unresolved questions;
- report link.








The report owns the detail. The Register should not duplicate findings or become a second report.








### Dry Run and Outputs cleanup




When a deployment is in scope, Defrag should inspect `outputs/` and the Dry Run Register as part of structural hygiene.




Repeated artifacts of the same type in the fallback `outputs/` area should be surfaced when they indicate that the system lacks a clear owner or filing rule. Do not invent a new subsystem merely because Outputs contains files; treat recurrence as evidence for deliberate design.




Defrag may remove a detailed Dry Run evidence file when all of the following are true:




- the run is complete;
- the Dry Run Register records the Dry Run ID, date, target/scope, material versions tested, final result and any exceptions;
- the final result is a clean pass;
- no accepted exception, unresolved failure or investigation still depends on the detailed evidence.




After deletion, update the Register's evidence status. Keep the Register row.




A pre-live candidate workspace may be removed after successful Live promotion and Live acceptance when the deployment report records no unresolved failed checks and no retained exceptional evidence depends on the workspace.




Do not delete release archives, canonical change history or evidence that still explains an unresolved failure or accepted exception.




### Manual deletion queue








If Defrag identifies a file or folder that existing Arco rules clearly make safe to delete, delete it directly when the available tooling supports that safely.








For Core, if manual deletion is required, move the item into `/Arco/Archive/Delete/` where possible. For a deployment, use that deployment's configured archive/delete area where one exists and include its direct Drive URL in the report and completion message. Do not count a queued item as deleted until deletion is confirmed.








Do not move valid historical archives into `Delete` merely because terminology or architecture has since changed. Historical evidence remains historical evidence.








## 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.









## Canonical references

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

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 1.7.1 | Restored exact Core evidence/Register filing pointers. | Stoirm Arnold — Defrag invocation | Codex Work |
| 23-Sep-2026 | 1.7.0 | Added coherence checking for enabled human artifacts and formalised Defrag → DEV handoff for durable material system proposals while keeping Defrag evidence in its own report/Register. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 22-Sep-2026 | 1.6.0 | Added Outputs hygiene and deterministic cleanup of clean Dry Run evidence and completed deployment candidate workspaces while preserving the durable Dry Run Register and exceptional evidence. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 21-Sep-2026 | 1.5.0 | Removed Defrag-level Register-format hardcoding so Defrag inherits the universal Register standard from the System Manual. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 21-Sep-2026 | 1.4.0 | Corrected Defrag filing to the numbered `04-functions` architecture, made the Defrag Register provider-native for deployments, and separated Core versus deployment delete/report locations. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |