---  
name: Development operating guide  
version: 4.0.2
status: active  
owner: Stoirm Arnold  
last_updated: 30-Sep-2026
---


# Development


## Purpose


Development is Arco's maintained mechanism for proposing, building, testing, reviewing and resolving changes to the Arco system itself.


It is not a Module. It is the system-evolution mechanism used by both Arco Core and deployments.


A Development item may originate from a governed user, Defrag, Dry Run, Updater, another Function or another maintained process. The source process owns evidence of how the issue was found; Development owns the proposed system change.


Development begins when there is a substantive proposal or demonstrated need to alter Arco. General exploratory thoughts may remain in Notes; the retired Ideation module is not a current runtime dependency.


## System scope


Every Development item records `system_scope`:


- `core` — the proposal is intended to change reusable Arco Core behaviour;  
- `local` — the proposal is intended to change only the current deployment unless later deliberately generalised.


`system_scope` describes where the system change belongs. It does not replace deployment `scope`.


Where a local Development item has an intended reach, continue to use:


- **Personal**  
- **Multi-user**  
- **Unit**  
- **Cross-functional**  
- **Organisational**


Where the item is being trialled, `testing_scope` uses the same vocabulary. Core items may omit deployment scope where it is not meaningful.


## Identity


Every substantive Development item receives one sequential local identifier:


`DEV-###`


Each Development runtime has one continuous DEV sequence across both `core` and `local` system scope and across all source types. IDs are never reused.


When allocating a new DEV ID, read both the unresolved and resolved Development Registers in that runtime and choose the next number after the highest allocated DEV ID.


Routine Development retrieval does not need the resolved Register.


### Runtime-qualified references


`DEV-###` is the stored local identity. When Development from more than one runtime is shown, discussed or reconciled together, use a qualified human-facing reference:


`DEV-###-RRR`


where `RRR` is the runtime's stable three-letter Development code. `ARC` is reserved for Arco Core. Deployment codes are configured once in the deployment's `readme-development-local.md` and must remain stable.


Examples:


- `DEV-025-ARC` — Arco Core DEV-025;  
- `DEV-019-TUR` — Turntabl DEV-019;  
- `DEV-019-STO` — Stoirm Ltd DEV-019.


The qualified reference is a display/reference namespace, not a replacement `dev_id`, and it does not change `system_scope`. Local Registers and records may therefore keep `DEV-###`; cross-runtime outputs must qualify references or otherwise state the runtime unambiguously.


Filename remains:


`YYYY-MM-DD-DEV-###.md`


Do not add the runtime code to existing filenames solely for identification. Development records are lifecycle records with stable local identity; cross-runtime provenance belongs in the qualified reference and source fields.


## Source provenance


The source process is provenance, not Development identity.


A Development record should capture, where applicable:


- `source_type` — for example `user`, `defrag`, `dry-run`, `updater`, another Function or `migration`;  
- `source_id` — the stable source identifier where one exists;  
- `source_record` — the durable source artifact where one exists;  
- `proposed_by` — the individual or identifiable system originating the durable proposal.


A Function report or source artifact remains the evidence record for that run. It should link to the DEV item rather than becoming a second Development tracker.


## Runtime structure


### Arco Core


Use:
- [Arco Core Development](https://drive.google.com/drive/folders/1NdbQ05WRpoIJGYf5GyxvfsWcK96lD7nN)
- [dev-unresolved-register.csv](https://drive.google.com/file/d/1F9n6nas_5u0FH17aq1Nd7YEjZxMypcuZ/view)
- [dev-resolved-register.csv](https://drive.google.com/file/d/1cTp6ACLI3l7IL1_vdSskDU5QHJHWcMAG/view)
- [Development logs](https://drive.google.com/drive/folders/1tnujJ9tHWRf1eAZSMcLah21sEseicK_t)


### Deployment


A deployment provides its own `readme-development.md`, `readme-development-local.md`, unresolved/resolved Registers and unresolved/resolved record locations.


The local configuration must point to those maintained sources using full provider file links. Do not encode or reconstruct storage paths in the operating guide.


`readme-development.md` is the deployed Core-derived operating guide. `readme-development-local.md` owns deployment-specific links, provider identifiers, the stable three-letter Development runtime code, and local exceptions.


## Development records


A DEV record must be sufficient for its destination reviewer to act without reconstructing the originating chat or Function run.


Each substantive record should identify:


- DEV ID;  
- date;  
- system scope;  
- problem or proposed change;  
- exact affected canonical owner(s);  
- required behaviour/change;  
- dependencies and downstream reconciliation;  
- what is already proven or changed locally;  
- unresolved decisions, if any;  
- evidence/testing;  
- validation criteria;  
- outcome once resolved.


Where relevant it should also retain deployment `scope`, `testing_scope`, owner, contributors and source provenance.


Use concise sections that fit the item. Do not force empty headings merely to satisfy a template.


### One DEV per idea or change


Each DEV owns **one substantive idea, problem or change needed**.


A single conversation, note, scan or deployment interaction may expose several Development ideas at once. Shared timing or provenance is not a reason to combine them. Create a separate DEV for each independently resolvable proposition.


A DEV may contain several questions only when those questions are necessary to resolve the same central change, share the same architectural boundary/owner and would normally be implemented or closed together.


Use this test: **if one part could be implemented, rejected, deferred or resolved while another part remains independently open, they should be separate DEV items.**


Do not group unrelated Development merely because it:
- arose in the same conversation or source;
- affects the same module;
- came from the same deployment;
- would be convenient to discuss together.


If an existing DEV is found to span multiple independent propositions, partition the live propositions into new DEV IDs and resolve the broad original record as superseded/partitioned with links to each replacement.


## Development Registers


Each Development runtime maintains exactly two Registers:


- `dev-unresolved-register.csv` — the active Development index;  
- `dev-resolved-register.csv` — the historical resolved index.


The unresolved Register is the normal read path for Development work. The resolved Register is consulted only when history, provenance, duplication, supersession or new DEV-ID allocation materially requires it.


Both Registers follow the System Manual Register standard.


Minimum useful fields are:


- DEV ID  
- Date  
- System scope  
- Scope where relevant  
- Status  
- Source type  
- Source ID  
- Proposed by  
- Owner  
- Summary  
- Affected owners  
- Record link


The resolved Register additionally records:


- Outcome  
- Resolved date  
- Destination / Core version where applicable


Do not duplicate the full Development record in a Register.


## Development status


`Status` records the current state of an unresolved DEV now. It does not describe where the DEV came from, where it may eventually be promoted, or whether a related change has already been deployed somewhere else.


Use only these active statuses:


- **Idea** — a substantive Development idea or need has been captured, but its direction is not yet developed enough for implementation or testing.
- **Issue** — a demonstrated problem, omission, inconsistency or broken behaviour in the maintained system has been identified and requires Development handling.
- **Discussion** — the proposition is developed enough to require a specific design, governance or architectural discussion before it should progress.
- **Trial** — a direction exists and is actively being built, tested, used or otherwise evidenced. The DEV record must state where the trial/evidence is occurring using the relevant runtime-qualified reference or deployment name; do not add a separate Register field solely for this.
- **Ready** — the Development question is sufficiently settled and evidenced for its next approved outcome to be executed. Ready does not mean deployed or resolved.
- **On hold** — deliberately paused. Record why it is paused and, where useful, the condition for resuming it.


These are states, not mandatory sequential gates. A DEV may be captured directly as Idea or Issue according to its current state, move directly to Ready where sufficiently settled, return from Trial to Discussion, or move into On hold from any active state. Do not add a separate item-type field to duplicate Idea / Issue classification.


`Resolved` is not an active unresolved status. Once the DEV's outcome has actually been completed, move it to resolved history under the normal lifecycle.


The same status vocabulary applies in Arco Core and in every deployment. A Core DEV may be in Trial while its evidence is being generated in one or more deployments.


## Lifecycle


New active DEV records are filed under `logs/unresolved/` and indexed in the unresolved Register.


When an item is resolved:


1. write the final outcome into the DEV record;  
2. move the DEV record to `logs/resolved/`;  
3. remove its row from the unresolved Register;  
4. add the durable final row to the resolved Register;  
5. retain the same DEV ID and filename.


Resolution may include promoted, rejected, merged, superseded, withdrawn or another explicit outcome.


Resolved records remain durable provenance but are not part of the normal active read path.


### Refinement and supersession


Keep updating an existing DEV item while its central proposal, architectural boundary, canonical owner and intended operating model remain materially the same.


When later evidence materially changes one of those things, create a new DEV item instead of allowing the original record to become an indefinite history of different propositions.


For a material change:


1. allocate the next DEV ID;  
2. make the new record self-sufficient and link it to the earlier DEV;  
3. resolve the earlier DEV as `superseded`, identifying the replacement DEV;  
4. move the earlier record and Register row to resolved history;  
5. keep only the current proposition in the unresolved Register.


Use supersession to keep active Development concise, not for ordinary refinement or wording changes.


## Bounded retrieval


Normal Development work follows this route:


1. read `arco-development.md` / `readme-development.md`;  
2. in a deployment, read `readme-development-local.md` where present;  
3. read only `dev-unresolved-register.csv`;  
4. filter to unresolved rows relevant to the requested task/system scope;  
5. open only those linked records under `logs/unresolved/`.


Do not scan `logs/resolved/` or the resolved Register during routine Development work.


Read resolved history only when provenance, duplication, supersession, prior reasoning or DEV-ID allocation materially requires it.


## Function linkage


When Defrag, Dry Run, Updater or another Function materially identifies a proposed system change that is not already owned by an existing DEV item:


1. keep Function-run evidence in the Function's own report/Register;  
2. create the next DEV item;  
3. record the Function provenance on the DEV record;  
4. link the Function evidence to the DEV item where the Function's format supports it.


Do not create a DEV item for every observation. The issue must represent a durable, substantive proposed change to Arco.


If the Function can deterministically correct an issue under already-established rules, it may correct it without opening a new Development item unless a separate unresolved system proposal remains.


## Incidental Development capture


While performing ordinary Arco work, an operator may notice a substantive maintained-system ambiguity, gap, contradiction, repeated failure or material Development activity that is not the task it was originally asked to perform.


Development capture is not limited to change requests or faults. When a maintained Arco behaviour is intentionally designed, built, prototyped or trialled in Core or a deployment, create or update the relevant DEV record before or at the same time as that material Development begins. A local DEV may exist solely to record a local Idea, Discussion or Trial; it does not imply a request to change Core.


When that happens:


1. check the unresolved Development Register for a materially overlapping item;
2. if one exists, preserve the new evidence against that DEV rather than creating a duplicate;
3. if none exists and the issue represents a durable proposed change to Arco, create the next DEV item even when the user did not explicitly ask to log Development;
4. preserve the immediate source/evidence and keep the proposal within the correct local or Core `system_scope`;
5. continue the user's requested work where the issue does not make that work unsafe or materially ambiguous.


Do not create Development for cosmetic observations, harmless implementation choices or one-off execution errors that do not imply a maintained-system change.


Automatic capture does not grant automatic implementation or promotion authority. Governance, approval and the normal Development lifecycle still apply. Where an issue can be deterministically corrected under an already-established maintained rule, the owning process may correct it without opening a separate DEV unless unresolved system design remains.


## Collaboration and Governance


Before creating a new DEV item, check the unresolved Register and relevant active records for overlap.


If substantially the same Development already exists, contribute to the existing item rather than creating a duplicate.


If the new evidence materially changes the proposition rather than merely refining it, use the supersession rule above instead of forcing the change into the existing item.


Visibility does not grant promotion authority. Promotion remains subject to the applicable Governance and approval model.


## Cross-runtime reconciliation


A deployment must not develop materially overlapping Development in isolation from relevant unresolved Core Development. **Arco Development Reconciliation ([arco-dev-rec.md](https://drive.google.com/file/d/1NTNbXkRBnexXrD3vS26u0KbT6omuNRTZ/view)) owns cross-runtime reconciliation** across Core and one or more deployments.


When reconciliation is invoked, compare each relevant unresolved deployment DEV with relevant unresolved Core DEV items. Do not load all Core DEV records indiscriminately; use the Core unresolved Register to identify candidates, then open only materially related records.


Before carrying an existing DEV proposition or unresolved bullet forward, compare it with the **current canonical owners and current implemented Core behaviour**. The record's historical `Unresolved` label is not sufficient evidence that the question remains open.


Where current maintained Core has already implemented the behaviour, assigned it deliberately to Local/another owner, or otherwise settled the boundary:
- treat that portion as resolved or superseded;
- do not reproduce it as an active unresolved question;
- preserve historical reasoning only in the resolved provenance where useful.


If a deployment DEV or older Core DEV contains several independent propositions, apply the one-DEV-per-change rule before reconciliation or promotion. Reconcile each live proposition separately rather than promoting the broad bundle unchanged.


Classify an overlap as one of:


- **same proposition** — link the deployment item to the Core DEV and resolve/merge local responsibility where appropriate;  
- **local evidence for Core** — preserve or link the evidence against the Core DEV, then resolve the local item once handoff is verified;  
- **local-only divergence** — retain the deployment DEV when the difference is genuinely deployment-specific;  
- **material contradiction** — surface for explicit resolution; do not silently prefer either branch;  
- **Core supersession** — resolve the deployment proposition as superseded when a later Core direction invalidates it.


Reconciliation changes Development relationships, ownership and provenance, not deployment runtime state by itself. It must not resolve a local DEV that is still an active Idea, Discussion, Trial, Ready item or otherwise remains relevant to that deployment. Local resolution occurs only when the local Development responsibility is actually complete. Approved Core behaviour reaches a deployment through the normal Core change and Updater path.


When cross-runtime Development is reported, use runtime-qualified references such as `DEV-025-ARC` and `DEV-007-TUR`.


## Testing and promotion


Development may be tested at any appropriate scope.


Use real use and Dry Runs as evidence where appropriate.


A typical lifecycle is:


```text  
need / evidence  
    ↓  
DEV item  
    ↓  
build / refine / test  
    ↓  
Dry Run where material  
    ↓  
approval where required  
    ↓  
promotion to canonical owner or other explicit outcome  
    ↓  
move record + row to resolved history  
```


Do not treat this as a mandatory linear workflow.


Core Development items do not automatically become deployment Development items. A deployment may submit a `system_scope: core` proposal to Core, but Core review and implementation remain separate from the deployment's local runtime state.


When a deployment has completed its own Development responsibility by promoting a reusable proposal into Core Development with traceable provenance, the source deployment DEV may be resolved as promoted at that handoff boundary. The Core DEV then owns the separate Core review, implementation and resolution lifecycle.


## Migration


When migrating an older Development Log/workspace:


- preserve existing record content and stable provider file IDs where practical;  
- assign DEV IDs deterministically without collision;  
- migrate active items to the unresolved Register and `logs/unresolved/`;  
- preserve resolved historical records in the resolved path where still useful;  
- retire competing Development Logs after migration evidence is preserved;  
- update routing so only the new Development operating guide and Registers own the path.



## Canonical references

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

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 30-Sep-2026 | 4.0.2 | Removed the retired Ideation dependency from current Development guidance; Rolled the live changelog to five entries with archived history. | Stoirm Arnold — Defrag invocation | Codex Work |
| 29-Sep-2026 | 4.0.1 | Added `Issue` to the active Development lifecycle for demonstrated problems, omissions, inconsistencies or broken behaviour; confirmed Idea / Issue remain lifecycle statuses rather than a separate item-type field. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 26-Sep-2026 | 3.7.0 | Assigned cross-runtime Development reconciliation to the dedicated `arco-dev-rec.md` Function while retaining Dev Scan for Development processing. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 26-Sep-2026 | 3.6.0 | Enforced one DEV per independently resolvable idea/change; added partitioning for broad legacy DEVs; and required reconciliation to check historical unresolved claims against current canonical implementation before carrying them forward. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |
| 25-Sep-2026 | 3.5.1 | Corrected v3.5.0 so the approved incidental Development-capture behaviour exists in the operating body, not only its changelog. | Stoirm Arnold | ChatGPT Chat — GPT-5.6 Sol (Medium) |