# Execution Parts Guide — large groups in parts, ledgers and resuming

A large group is built in parts (item 1a), under [parts-guide.md](parts-guide.md): the orchestrator, the brief and its rulings, the ledgers, read plans, forks and returns are stated there. This guide holds what a build adds.

1. **A project has one owner at a time** — a subagent or the orchestrator, handed on as [parts-guide.md](parts-guide.md) item 7 states; test-component groups sharing a project run sequentially. Only the owner runs the project's shared operations — Object Repository registration and linking, build, pack, package installs, host restarts — and edits its shared files: the workflows that route to or invoke several steps' files, the manifest, a code file several workflows use, the ledger, the progress file, the target spec, the registry and the link table. The owner may fork itself to author disjoint files in parallel (item 1c). Whoever builds a part performs the owning skill's contract ([execution-guide.md § 2.2](execution-guide.md) step 2) and reports the reads it performed.
1a. **Keep a project ledger with a skeleton before the first workflow, in two files** — the ledger of [parts-guide.md](parts-guide.md) item 3, for a project. Both live in the working folder outside every project. The **contract** (`<Project>.md`) opens with the skeleton, written by the first part after its reads: workflow file list and each file's argument names, directions and types; configuration keys; Object Repository screen and element names; the split into parts, with the activity kinds each part will use. Decisions with reasons and source object and line, open questions and the orchestrator's rulings follow it. Later work agrees with these contracts; a change is a decision naming the affected items. The **progress file** (`<Project>-progress.md`) tracks every planned item's written, validated and linked status (not applicable where appropriate), with plans and counts, such as derived elements and why each is needed.

    Read the contract whole before the first project action; assemble the group report from both files at the end, never leave an empty report skeleton as the record of progress.

    Plan parts when the workflow count makes compaction likely, small enough to finish without compacting, and split where few contracts cross. A migration opens with the source-fact tables and the target specs, one part of each per component, then the libraries; each set runs in parallel, except that a library starts after the libraries it depends on ([execution-guide.md § 1.5](execution-guide.md) item 7). A migrated process project then runs four parts: its configuration and framework surfaces with the once-per-run and end-of-run steps and the skeleton of the whole project; the non-UI per-item steps, which create argument-only files for the workflows a later part fills, so every invoke validates; the UI steps, with their targets registered from the target spec and their files linked, since a file whose target is not set does not validate; then verification, the gate, the framework exits and the acceptance verdicts. Each part opens with its read plan (item 1b), which starts with the brief and the ledger contract. Parts of one project run one after another; independent projects may run in parallel. Calibrate part size from trial runs, not a fixed file limit.
1b. **Every part reads by plan (item 6), in the three turns of [parts-guide.md](parts-guide.md) item 4.** Turn 2's discovery covers every activity kind the skeleton lists for the part, with the listing of each package's per-activity doc folder — a class name is not a doc file name — and a search of those docs for the component and type docs they link, which a per-activity doc requires read with it; turn 3 reads the per-activity docs, the docs they link and the shapes that discovery returned. The part report names every mandated read the plan omitted and every read that missed.

    ```
    Read plan — part B1 (steps 10–11 and the Object Repository, UI)
      Turn 1  whole:    run brief; ledger contract; execution-parts-guide; component genome; owning skill's rule files,
                        cards and UI guides (its two-step reads split across turns 1 and 2); source-migration-guide;
                        offline guide
              headings: source-fact table; selector-translation-guide; pack source and selectors guides; owning skill's catalogs
      Turn 2  sections: source facts § Configuration, § Step 10, § Step 11, § shared, § Deviations;
                        selector-translation-guide and its SAP GUI guide; pack § Composite actions,
                        § Realised at execution, selectors § SAP GUI; catalog sections matching the part's activity kinds
              discovery for the part's activity kinds (skeleton)
      Turn 3  per-activity docs, the docs they link, and shapes; references the turn-2 reads route to
    ```

    Read by section: the source-fact table (configuration, the part's steps, the sections shared by every step, deviations), the framework pack's guides (the constructs the part builds), the owning skill's catalogs. A long ledger contract is a whole read above the single-read limit. An earlier part's workflows are known from the skeleton: open one only to edit or copy it, find the edit point with a search that prints the surrounding lines, and read that region. Another project's contract reaches the part through the brief: a library's packed surface, a shared helper's arguments. A targeted lookup for a detail the source-fact table leaves open (item 6) is not part of the plan: it runs before the file that needs it is written. A source-fact part writes the dumps of all its source objects with one command loop and reads them in one message.
1c. **Forks** follow [parts-guide.md](parts-guide.md) item 5. In a build the shared reads are the brief, the ledger contract and the owning skill's mandatory reads for what the forks author, and the shared decisions in the ledger are each fork's files with their arguments, the helpers they call, and the shared-file edits the owner makes; the owner forks before it reads any one fork's step material or authors a file. A fork reads its own steps' material — their source-fact sections, source objects and target-spec entries — writes only its assigned files, validates them per file, runs none of the shared operations of item 1, and returns the report of item 7 for its files. The owner reviews each fork's files against the source-fact sections and source defects of its steps before it registers and links them.
2. One authoring host serves all agents of a project: every CLI call carries the project directory; a busy or locked host is retried once after a pause; the owner's per-file mutations (validate, link, register) run sequentially inside one shell call per batch, following the owning skill's turn-batching guidance, while its forks validate their own files beside them (item 1c).
3. Object Repository linking follows the owning skill's target-attachment guidance (screen first, then elements; never two link commands on one file at once) and the ordering and verification rules in [ui-target-migration-guide.md § UI targets](ui-target-migration-guide.md) — link last, size batches by payload, check the file. The executor only orders the work.
4. **Progress is written through** ([parts-guide.md](parts-guide.md) item 3), so a part resumes after a compaction, a pause or in a new session. No signal precedes a compaction, so the progress file stays at most one item behind the work: an item's row is written in the turn its validate result arrives, batched with the next item's first call, never at the end of the part. The file opens with a `Resume` block rewritten with each row: the current part, the last item and its gate result, the next item, the files changed since their last validate, and the work in flight (an Object Repository or link batch, a scratch copy, a host restart owed). Beside the brief, `run-progress.md` lists every part of every project with its state, its report and its read plan, and the next parts in order; the orchestrator updates it at each part boundary. A pause is taken at the next clean boundary: the operation in hand is finished (a link batch recounted in its file, a written file validated), nothing new starts, and the Resume block and the run progress are written. To resume, read the run progress, the brief with its rulings, the ledger contract and the current part's Resume block and rows — a part that starts fresh does not read the progress file. Confirming a compaction summary's work on disk is validating again every file changed since its last validate and recounting a link batch in its file; the read plan a resumed part re-runs includes the owning skill's mandatory reads.
5. Solution-level mutations (project registration, resources) are done by the orchestrator alone, after the parts that touch the projects finish.
6. **One run brief, written before the first part starts** ([parts-guide.md](parts-guide.md) item 2). The orchestrator writes a single brief file in the build's working folder outside every project (the `migration/` folder of [source-migration-guide.md § What the executor records](source-migration-guide.md) when the run is a migration): absolute paths (build folder, working folder, export, local feed), the authoring mode ([execution-guide.md § 2.2](execution-guide.md) step 2, verbatim), the run's behavioural contracts (Object Repository rules, the cross-project Interface, verification verdicts), the source-fact table ([source-migration-guide.md § Migration preflight](source-migration-guide.md) step 4), each component's target spec from that preflight, the link table, each project's Object Repository registry and the run's target tool once it exists ([ui-target-migration-guide.md § UI targets](ui-target-migration-guide.md)), each project's ledger paths, the report path and format, the configuration answers, the libraries' packed surfaces once they exist, the environment workarounds the run finds (CLI environment variables, path quirks), and the numbered **Rulings** section, where every orchestrator decision lands — a contract question between a library and its consumers, a source-fact deviation, an interface change, a guard list. Each part's read plan is written into the run progress (item 4) and lists, in the turns of item 1b: the brief, its ledger contract and source-fact sections, parts-guide.md and this guide whole (the owner rule, forking, progress written through and the report the part owes), the owning skill's mandatory reads for what the part authors (UI reads only for a part that writes UI activities), the migration reads of [SKILL.md § Source Frameworks](../SKILL.md), never cut to sections, and the genome and pack sections the part's steps use. A group takes literals, counts, waits, flags and log texts from its steps' source-fact sections before it writes. For a missing detail, use the source guide's targeted lookup (`raw --lines` / `--find` where supported) and record the finding with its source object and line in the ledger. A whole-bot dump is only for a step the table does not cover at all. A skill's post-build context files are not written into a project — they would ship in the package. Reports, mapping files and scratch output go to the paths the brief names, never inside a project folder — a file inside a project ships in its package, and a `migration/` or `reports/` folder found inside a project is moved out before packing.
7. **A part's report** ([parts-guide.md](parts-guide.md) item 6) accounts for each contract per step and per file: for each step, every source defect the genome states for it ([extracted-genome-guide.md § Source Defects](extracted-genome-guide.md) — the process genome's index, or the step itself) and what was built for each; the step's source log points kept and its waits taken from the source; for each file, its validate result and link count; the forks the owner ran, each with its files, or none and the reason (item 1c); and the scripts the part ran, none of which wrote a workflow. The mechanical check before a part is accepted covers the packed surface with `uip rpa packages inspect`, the Object Repository identities and element count against the target spec and the registry, every element's semantic step and description ([ui-target-migration-guide.md](ui-target-migration-guide.md) rule 2), reconciling reuse, parametrisation and derived elements with the ledger, a search of the workflows for literal `idx=` values, the comparison literals and operators against the source export, the validate result re-run, a build of the project once the part's files are linked (per-file validate runs no analyzer rule, the owning skill's build guidance), a search of the working folder's scripts for any that write `.xaml` or `.cs` into a project.

## Anti-patterns

1. **Building a large group without a skeleton, a ledger and progress written through.** A compaction then loses the contracts, the decisions and every item the progress file never recorded; a part resumed from the summary instead of its read plan authors without the owning skill's reads, and mandatory reads and source dumps are paid twice (items 1a, 4).
2. **A part reading the build's files whole that it needs by section or not at all** — catalogs, the progress file, an earlier part's workflows, another project's ledger — beside the reads [parts-guide.md](parts-guide.md) anti-pattern 1 names (items 1a, 1b, 6).