Agent orchestration v1: three-party loops, agentic settings, spawn knobs, mission-control fixes (L8-L18, mcp-v3.0.0rc3)

.agents/GEMINI.md

@@ -1,23 +1,17 @@
 # Antigravity Workspace Instructions
 
-MANDATORY FIRST ACTION for this workspace:
+**Agents Remember — session start.**
 
-You are not allowed to read, write, or execute code on any repository until you
-read `<PATH/TO/YOUR/PROJECTS_FOLDER>/ar-coordination/AGENTS.md` and started its
-`l-01` procedure.
+If `AR_SPAWN_ROLE` is set, or your first user message is a role brief from an
+orchestrating agent: **ignore this notice entirely — your brief is your session
+start.**
 
-Read and follow `<PATH/TO/YOUR/PROJECTS_FOLDER>/ar-coordination/AGENTS.md`
-before working in any sibling project.
-Treat those rules as workspace instructions.
-
-Until the build/job decision is made, read managed-repo source with the
-`read_ar_files` MCP tool — not the harness's native read tool. One call returns
-each file paired with its onboarding plus the repository and governing route
-overviews. Native read is reserved as the edit precondition once building begins.
-
-During the `l-01` deep research step, keep a tally of the retrieval strategies
-used from `c-04-retrieval-strategy-router` (Semantics, Relationship, Intent), and
-keep a running count of your `read_ar_files` calls. Include the onboarding files
-inspected and every CGC, GrepAI, and `read_ar_files` call made as evidence.
+Otherwise you are the developer-facing session, i.e. the **orchestrator**: read
+`<PATH/TO/YOUR/PROJECTS_FOLDER>/ar-coordination/AGENTS.md` and treat those rules
+as workspace instructions, then run your lifecycle at
+`skills/l-01-agent-lifecycles/roles/orchestrator.md` — trust checkpoint before
+relying on memory, `read_ar_files` (paired source+onboarding) until the build
+decision, retrieval-strategy tally as evidence, notify-and-stop at every
+developer hand-off.
 
 @<PATH/TO/YOUR/PROJECTS_FOLDER>/ar-coordination/AGENTS.md

.agents/skills/c-01-findings-capture/SKILL.md

@@ -13,7 +13,7 @@ Companion file:
 
 ## Operating Modes
 
-1. Inside a task workflow (an `l-01-session-job-lifecycle` build job or a `w-02-light-task-workflow` task, including a master + light sub-task series).
+1. Inside a task workflow (an `l-01-agent-lifecycles` orchestrator build phase or a `w-02-light-task-workflow` task, including a master + light sub-task series).
 2. Standalone during direct clarification.
 
 ## Durable Destinations

.agents/skills/c-03-repo-bootstrap/SKILL.md

@@ -1240,7 +1240,7 @@ The orchestrator remains thin throughout.
 | `c-05-create-or-update-onboarding-files`          | Owns final file-level onboarding semantics and routes structural slice maintenance back to the `c-03-repo-bootstrap` skill. The `c-03-repo-bootstrap` skill creates cards/waves and delegates file output rules to the `c-05-create-or-update-onboarding-files` skill. |
 | `c-04-retrieval-strategy-router`                  | Consumes bootstrapped overviews and file maps as the Intent substrate and can route to semantic/relationship providers first. |
 | `c-02-memory-quality-control`                     | Becomes relevant after bootstrap; touched files can be promoted from deferred to covered.                     |
-| `l-01-session-job-lifecycle`                      | May trigger targeted bootstrap when an active job enters an uncovered area.                                   |
+| `l-01-agent-lifecycles`                           | May trigger targeted bootstrap when an active job enters an uncovered area.                                   |
 | `confluence-search` / documentation search skills | Feed the docs evidence pass through approved sources from the input ledger.                                   |
 
 ---

.agents/skills/c-04-retrieval-strategy-router/SKILL.md

@@ -160,7 +160,7 @@ names an unresolved source question.
 
 ### Rules:
 
-- During the research phase (the lifecycle up to the build/job decision), read managed-repo
+- During the research phase (the lifecycle up to the build decision), read managed-repo
   source with `read_ar_files`, not the native read tool — one call returns each file paired
   with its onboarding plus the repository and governing route overviews (the recipe above,
   batched and observable).

.agents/skills/c-09-git-worktree-manager/SKILL.md

@@ -7,7 +7,7 @@ description: "Create, attach to, report on, integrate, finalize, and clean up Ag
 
 Use this skill when a task should run through an explicit code/memory worktree wrapper.
 
-The `c-09-git-worktree-manager` skill wraps the existing chat-build, light-task, or external workflow. It owns Git worktree state, series contracts, leaf enclosures, external-memory compatibility checks, integration, lifecycle finalization, and cleanup. It does not replace the workflow that performs the actual implementation.
+The `c-09-git-worktree-manager` skill wraps the existing light-task or external workflow (a build that fits one session still rides a THIN `w-02-light-task-workflow` doc — chat is never a build route, per the `l-01-agent-lifecycles` invariant). It owns Git worktree state, series contracts, leaf enclosures, external-memory compatibility checks, integration, lifecycle finalization, and cleanup. It does not replace the workflow that performs the actual implementation.
 
 For closeout, use the `c-12-closeout` skill. The `c-09-git-worktree-manager` skill only supplies the worktree-specific
 contract path and integration/finalization follow-up rules.
@@ -67,7 +67,7 @@ The intended order is:
 1. run the `c-08-ar-coordination-context-resolver` skill for the target repository
 2. run the `c-02-memory-quality-control` skill's task-start drift check and follow the existing AGENTS Gate 3/4 choice point
 3. when onboarding is refreshed, commit the memory content and ledger before starting any worktree
-4. decide whether the work is a chat build, a `w-02-light-task-workflow` light task (or master + light sub-task series), or external workflow
+4. decide whether the work is a `w-02-light-task-workflow` light task — possibly a THIN one for single-session work; chat never builds — a master + light sub-task series, or external workflow
 5. read the repository's `system/git-workflow.md` and identify the parent branch
    edge. For a standalone task, the leaf worktree branches from the approved
    source branch. For a master series, the master owns a root `series-contract.md`
@@ -198,7 +198,9 @@ moved since task start.
 
 ## Integration
 
-Integration is explicitly human-gated and runs only after closeout completed. It lands the closed task branches back onto the recorded source branches and records the landed commits separately from the closeout commits.
+Integration is explicitly human-gated and runs only after closeout completed. It lands the closed task branches back onto the recorded source branches and records the landed commits separately from the closeout commits. Orchestrated-run carve-out (ruled 2026-07-06): dependency-ordered leaf→master and master→super integrations ride the series' standing approval (the developer's portfolio-gate approval recorded in the planner master) — the developer hand-off concentrates at the super PR/carry-over gate per the `l-01-agent-lifecycles` loop/orchestrator doctrine; a raised durable `integration-approval` gate still awaits the developer.
+
+On an orchestrated master's exit (master → super integration) the integrate step additionally enforces the delegated `master-handover-approval` seam: an undecided or policy-invalid handover gate addressed to the master (by `enclosure` = master task name) returns `handover-gate-blocked` instead of landing — decide the gate per the `l-01-agent-lifecycles` seam doctrine, then rerun. When no gate addresses the integrating master but open `master-handover-approval` gates exist elsewhere, integrate still proceeds and its result carries a `handover_gate_warning` naming them — treat it as a spelling check on the raised gate's `enclosure`.
 
 Run `worktree_integrate(..., dry_run=true)` first, then **hand off**: call
 `lifecycle_turn_end_notification(summary={…the integration plan…})` as the **last tool call**, then

.agents/skills/c-12-closeout/SKILL.md

@@ -40,7 +40,7 @@ records the developer's explicit commit approval. Agents must not treat
 implementation approval, a previous "looks good", or their own judgment as
 commit approval.
 
-The relay follows the `l-01-session-job-lifecycle` skill hand-off protocol: run the
+The relay follows the `l-01-agent-lifecycles` orchestrator hand-off protocol: run the
 preview/dry-run first, then call
 `lifecycle_turn_end_notification(summary={…the preview facts + the commit ask…})` as the **last tool
 call**, then deliver the preview facts and proposed messages as plain

.agents/skills/c-13-install-and-onboard/SKILL.md

@@ -52,10 +52,12 @@ Run this sequence in order:
 0. Preflight: verify the copied package and MCP setup are usable enough to
    continue.
 1. Runtime scaffold: run or verify `runtime_install()`.
-2. Memory repo: ask scaffold-new vs use-existing, unless memory already exists.
-3. Bootstrap: when a new memory repo was scaffolded, hand off to
+2. Agentic settings: walk the developer through the orchestration defaults in
+   the seeded global settings file.
+3. Memory repo: ask scaffold-new vs use-existing, unless memory already exists.
+4. Bootstrap: when a new memory repo was scaffolded, hand off to
    `c-03-repo-bootstrap`.
-4. Providers: when providers are enabled, start/refresh indexing and verify
+5. Providers: when providers are enabled, start/refresh indexing and verify
    readiness.
 
 This skill orchestrates and delegates. It does not reimplement
@@ -79,7 +81,9 @@ Check, in order:
 3. **Settings sane.** Confirm `server_info` reports the expected
    `coordinationRoot`, `workspaceRoot`, allowed repositories, and providers.
    Surface the resolved absolute paths because wrong paths are the common cause
-   of resolver failures.
+   of resolver failures. Also report whether the global agentic settings file
+   (`<coordinationRoot>/system/settings.json`) exists yet; Stage 1 seeds it
+   when missing and Stage 2 configures it.
 4. **Runtime state.** Check whether the coordinator scaffold already exists under
    `coordinationRoot` (`AGENTS.md`, `skills/`, `tasks/`, `memory-repos/`,
    `system/` as applicable). If it is missing or stale, Stage 1 will run
@@ -118,36 +122,90 @@ Do not run `skills_install()` as part of first-run setup. The harness starter
 package already carries the skills. `skills_install()` remains available for
 manual maintenance or non-package setups, but it is not the default path.
 
-## Stage 2 - Memory Repo: Ask Scaffold Vs Existing
+## Stage 2 - Agentic Settings: Interview The Developer
+
+`runtime_install()` seeds the GLOBAL agentic settings file at
+`<coordinationRoot>/system/settings.json` copy-if-missing, with every knob at
+its documented default: all-human gate delegation, the standard three-party-loop
+defaults, no concurrency caps, no spawn harness preference. This stage turns
+those defaults into the developer's actual posture so the intended workflows
+run on ANY harness. The schema reference is `docs/reference/settings-json.md`
+(Agentic Settings); unknown `orchestration.*` keys fail loud, so write only
+documented keys.
+
+Walk the developer through the four knob families and edit the global file with
+their answers (leave a family at its seeded default when they have no
+preference):
+
+1. **Gate delegation posture** (`orchestration.gateDelegation`; GLOBAL file only - the
+   loader refuses it repo-locally and the boot snapshot reads the coordinator file) - keep every
+   gate human (`all-human`, the default), or delegate leaf gates with the
+   `manager-decides-leaf-gates` policy, optional per-kind `kinds` overrides,
+   and `requireReviewerVerdictAtSeams`. Say explicitly that this one key is
+   boot-snapshot: a change needs an MCP/harness restart.
+2. **Loop defaults** (`orchestration.loops`) - the review-round cap
+   (`defaults.maxRounds`), reviewer reuse (`defaults.reviewerReuse`),
+   complexity thresholds (`defaults.complexity`), and per-level loop postures
+   (`perLevel`). Read per-use; edits apply on the next use, no restart.
+3. **Concurrency caps** (`orchestration.concurrency`) - `maxParallelMasters`,
+   `maxParallelLeaves`, `maxSubAgents`. Default: uncapped.
+4. **Harness preference + role knobs** (`orchestration.spawn.harness`,
+   per-role `orchestration.roles.<role>`, per-level
+   `orchestration.rolesPerLevel.<level>.<role>`) - which installed harness
+   `spawn_agent_session` uses when the spawning seat passes none, per-role
+   harness/model/effort overrides, and per-LEVEL overrides
+   (leaf|master|portfolio) for tiered economics (e.g. a cheap leaf reviewer,
+   a smarter master-seam reviewer). Harness values must be known ids: the
+   builtin registry (`claude`, `codex`, `pi`) or an `orchestration.harnesses`
+   entry the developer defines (new TUIs, or a pre-customized launch argv for
+   a builtin). `effort` is validated per-harness at dispatch (claude:
+   `low|medium|high|xhigh|max` on the `--effort` flag plus the session-level
+   `ultracode`); mention the FREE-FORM escape hatch for anything outside the
+   vocabularies - `launchArgs` (verbatim argv), `sessionCommands` (pasted
+   before the brief), `promptKeywords` (prepended to the brief) - never
+   validated, recorded in spawn provenance. Default: detection-gated (the
+   first detected harness). The full spawn-surface manual is
+   `docs/reference/harnesses.md`.
+
+If the developer wants to skip the interview, confirm the seeded defaults
+apply and continue; tell them the file can be edited any time (picked up
+per-use, except the gateDelegation restart note above).
+
+Per-repo overrides: a code repo may carry its own `<repo>/system/settings.json`
+with the same `orchestration.*` shape; repo-local leaf values override the
+global file (arrays replace). Offer this only when the developer asks for
+repo-specific behavior; do not create the file unprompted.
+
+## Stage 3 - Memory Repo: Ask Scaffold Vs Existing
 
 Do not assume the developer wants a fresh memory repo. Ask which case applies,
 unless a memory repo is already present and resolvable:
 
 1. **Scaffold a new memory repo** - they have no existing memory for this code
    repo. Run `c-00-initialize-memory-repo` (internal by default; external only if
    the developer asks or the configured topology requires it). Continue to Stage
-   3.
+   4.
 2. **Use an existing memory repo** - they already have one. Clone or checkout it
    to the resolved memory location, then adopt it as the ledgered baseline with
-   `c-10-adopt-memory-baseline`. Skip Stage 3 because its onboarding already
+   `c-10-adopt-memory-baseline`. Skip Stage 4 because its onboarding already
    exists.
 
 Internal-memory note: pre-existing internal memory lives inside the code repo
 (`<repo>/ar-memory/`), so it is already present on checkout. Detect that through
 `c-08-ar-coordination-context-resolver` and skip the question when the memory
 layer is already there.
 
-## Stage 3 - Bootstrap
+## Stage 4 - Bootstrap
 
-Run this stage only when Stage 2 scaffolded a new memory repo.
+Run this stage only when Stage 3 scaffolded a new memory repo.
 
 Hand off to `c-03-repo-bootstrap` to generate initial onboarding. A thin
 `overview.md` is enough to start; deeper route-local overviews and file-level
 onboarding should grow as work touches new areas.
 
 Skip this stage when an existing memory repo was adopted.
 
-## Stage 4 - Configure Providers To Index
+## Stage 5 - Configure Providers To Index
 
 If providers are enabled, make them index the configured code and memory:
 
@@ -177,10 +235,12 @@ Summarize:
    step the developer must perform;
 2. runtime scaffold: `runtime_install()` run or already current, with the
    resolved coordination root;
-3. memory repo: scaffolded, existing-adopted, or already present, with the
+3. agentic settings: interviewed and written, or left at the seeded defaults,
+   with the global file path;
+4. memory repo: scaffolded, existing-adopted, or already present, with the
    resolved memory root;
-4. bootstrap: run via `c-03-repo-bootstrap` or skipped;
-5. providers: indexing status and any deferred/degraded state.
+5. bootstrap: run via `c-03-repo-bootstrap` or skipped;
+6. providers: indexing status and any deferred/degraded state.
 
 End by telling the developer whether the project is ready for normal work. Do
 not tell them to restart for hooks installed by this skill, because this skill no