Skip to content

e6c3f410.md

Latest commit

 

History

History
237 lines (173 loc) · 14.8 KB

e6c3f410.md

File metadata and controls

237 lines (173 loc) · 14.8 KB
Raw
uid e6c3f410
type decision
status done
state active
title ADR-032 — Three-Layer Boot Configuration Model
description Decomposes the agent boot primitive into three governed layers: OS (.tropo/), vault admin (.tropo-studio/), and agent (agents/<name>/). Defines the vault administrator role.
owner argus
created 2026-04-13
modified 2026-04-19
tags
adr-032
boot
configuration
governance
three-layer
vault-admin
p0
file_ext md
schema_version 2
extraction_scope ship
decision_number ADR-032
proposer Argus A22
member_of
created_by argus-a22
subsystem_hub
8dd772a0
capsule_version 2.5

ADR-032 — Three-Layer Boot Configuration Model

📍 Vault Path: tropo-subsystems → Tropo Governance → ADR-032 — Three-Layer Boot Configuration Model

🔗 This file — UID e6c3f410 · type decision · state active · status done

📥 Cited by (17):

Status

LOCKED. Argus A22 proposed April 13, 2026. Cleared with Mike at end of G40 session. Metis G41 sign-off: April 13, 2026.

Context

The current agent boot primitive is a single file — .tropo/playbooks/agent-boot.playbook.md — that every executive agent reads and follows. It is OS-maintained, ships in every vault, and is updated through the Tropo update pipeline.

This is correct for the OS layer. But it conflates three distinct concerns that belong to three different owners:

  1. What every agent on any Tropo vault must do — OS responsibility
  2. What every agent on THIS vault must do — vault administrator responsibility
  3. What THIS agent specifically must do — agent responsibility

Currently, vault-specific and agent-specific boot behavior is scattered across individual activation files, charter files, and informally documented conventions. There is no governed layer for a vault administrator to declare vault-wide boot requirements without modifying OS files. There is no formal role called "vault administrator."

This ADR formalizes the boot configuration as a three-layer governed construct with a clean override contract, and defines the vault administrator role.

Decision

The agent boot primitive is decomposed into three configuration layers. Each layer is a governed file that the boot playbook reads in sequence. The layers compose — each extends the one above without removing required steps.

The Three Layers

Layer 1 — OS Boot Config (.tropo/boot-config.md)

  • Owner: Tropo
  • Updated by: Tropo update pipeline only
  • Scope: Applies to every agent on every Tropo vault
  • Contains: Required boot steps, phase sequence, minimum viable boot definition, override contract rules
  • Cannot be modified by vault admin or agents

Layer 2 — Vault Boot Config (.tropo-studio/boot-config.md)

  • Owner: Vault administrator (see Role Definition below)
  • Updated by: Vault administrator
  • Scope: Applies to every agent on this vault
  • Contains: Vault-specific required steps, worker registry location, orientation artifact paths, vault-specific health checks
  • Can add required steps; cannot remove OS-required steps

Layer 3 — Agent Boot Config (agents/<name>/boot-config.md)

  • Owner: The agent
  • Updated by: The agent at each generation
  • Scope: Applies to this agent only
  • Contains: Agent-specific steps — channel scan targets, board path, briefing package, generation-specific work plan
  • Can add agent-specific steps; cannot remove OS or vault required steps

The Override Contract

.tropo/boot-config.md (OS — floor, cannot be overridden)
 ↓ extends
.tropo-studio/boot-config.md (vault admin — adds vault defaults)
 ↓ extends
agents/<name>/boot-config.md (agent — adds agent-specific steps)

Each layer reads the layer above it first. A step marked required: true in any layer cannot be removed by a lower layer. A step marked required: false can be omitted by a lower layer. A lower layer can add steps the layers above did not declare.

The Vault Administrator Role

The vault administrator is the human or agent responsible for vault-wide governance that sits between the OS layer (Tropo) and the agent layer (individual crew members).

Responsibilities:

  • Owns and maintains .tropo-studio/boot-config.md
  • Owns and maintains STUDIO.md
  • Manages the agent registry (.tropo-studio/registries/agent-registry.yaml)
  • Manages the worker registry (.tropo-studio/registries/agent-registry.yaml — worker class)
  • Commissions and decommissions agents
  • Sets vault-wide defaults that all agents inherit

In the Argo vault: Mike Maziarz (human principal) is the vault administrator. Vela (Chief of Staff) acts as the vault administrator's operational delegate — she maintains the registries and boot infrastructure on Mike's behalf.

In a user vault: The vault administrator is the human who set up the vault. In single-person vaults, the human principal and the vault administrator are the same person. In team vaults, a designated operations agent (the "Vela equivalent") may serve as delegate.

Clearance: Vault administrator has write access to .tropo-studio/ and STUDIO.md. Cannot modify .tropo/ (OS-only).

The Canonical Configuration Matrix

This table is the authoritative reference for what each boot layer controls. When in doubt about which layer owns a configuration, consult this table.

Configuration Area .tropo/ (OS) .tropo-studio/ (Vault Admin) agents/<name>/ (Agent)
Boot phase sequence Defines phases 1-4, required order Cannot change order Cannot change order
Identity checkpoint Defines the check (tropo-agent-id) Can add vault-specific identity rules Provides own ID
Agent registry Defines the schema Owns the registry file Reads own entry
Worker registry Defines the schema and check protocol Owns the registry, sets schedules Executes stale workers on boot
Mission context Declares context/mission-brief.md as required read Can add vault-specific mission context Reads as declared
Crew brief Declares 00-crew-brief.md as required read Can point to different crew brief location Reads as declared
Channel scan Defines the scan-channels skill Can set default channels for all agents Declares own channels
Board regeneration Defines the regenerate-board skill Can set board synthesizer defaults Declares own board path
Memory loading Defines vault-level memory path Owns vault-level memory content Owns agent-level memory
Health check Defines check-vault-health skill Points to vault health report location Runs as declared
Startup signal Defines required startup signal format Can add vault-specific signal requirements Owns signal content
Operating values Defines the values as required reading Can add vault-specific values Reads as declared
Orientation files Defines .tropo/orientation.md Can add vault-specific orientation Reads own briefing package

Authoritative Sources

Item Source
Boot phase sequence agent-boot.playbook.md
Identity checkpoint rules TROPO-CONTROL.md §2
Agent registry schema agent-registry.yaml
Worker registry + check protocol agent-registry.yaml (worker class)
Mission brief context/mission-brief.md
Crew brief 00-crew-brief.md
scan-channels skill .tropo/skills/scan-channels.skill.md
regenerate-board skill .tropo/skills/regenerate-board.skill.md
check-vault-health skill .tropo/skills/check-vault-health.skill.md
Vault-level memory .tropo-studio/memory/MEMORY.md
Operating values design/tropo-operating-values.md
Override contract This ADR (ADR-032)

Rationale

Why three layers, not one? The single-file boot playbook works for a crew that never changes. It breaks down when a vault administrator wants to add a vault-wide boot requirement (e.g., "all agents must check the worker registry") without modifying OS files and without requiring every agent to independently add the step. The three-layer model gives the vault administrator a governed place to set vault-wide defaults.

Why is the override contract unidirectional? Lower layers can add but not remove. This preserves the integrity of required boot steps — an agent cannot opt out of the identity checkpoint, and a vault administrator cannot opt out of OS-required steps. The system's safety guarantees are non-negotiable.

Why formalize the vault administrator role? The role already exists — Vela and Mike perform it in Argo. Without a formal definition, new vault owners don't know who should maintain .tropo-studio/ or what authority that person has. The role definition is the missing piece that makes the three-layer model usable outside Argo.

Connection to ADR-031: ADR-031's primary open constraint was the L3 scheduler gap — grooming agents had no continuous trigger. The vault boot config (Layer 2) is where the worker registry check is declared as a vault-wide requirement. Combined with the agent boot config (Layer 3), this creates the distributed boot-time responsibility model that closes ADR-031's L3 gap: every agent boot checks the worker registry and runs stale workers. No scheduler required.

Consequences

What becomes easier:

  • Crew-wide boot changes become a single edit to .tropo-studio/boot-config.md — no touching individual activation files
  • New agent onboarding is simpler — agent declares only agent-specific steps; vault and OS steps are inherited
  • Vault administrators have a governed, authoritative place to set vault-wide boot behavior
  • The vault administrator role is explicit — new vault owners know who owns what

What becomes more constrained:

  • Every vault needs a vault administrator — the role cannot be vacant
  • .tropo-studio/boot-config.md must exist in every vault; the update pipeline creates it on first apply if missing
  • Agents can no longer declare boot behavior that conflicts with vault or OS requirements

Implementation notes:

  • The three config files (.tropo/boot-config.md, .tropo-studio/boot-config.md, agents/<name>/boot-config.md) are NEW files — the existing agent-boot.playbook.md remains the execution engine; the config files are its inputs
  • The boot playbook reads all three config files in sequence during Phase 1, builds a composite boot plan, then executes it
  • Migration: existing agent activation files contain ad-hoc boot config; these should be progressively migrated to the agent boot-config file

Open Questions (for Mike to lock)

  1. Vault administrator clearance: Can the vault administrator modify agent-level files (agents/<name>/)? Current assumption: no — agent files are owned by the agent.
  2. Delegate model: In Argo, Vela acts as vault admin delegate. Should this delegation be formally declared somewhere (in the agent registry? in STUDIO.md?)?
  3. Config file format: Should the three boot-config files be YAML (structured, machine-parseable) or markdown with frontmatter (consistent with the rest of the vault)?

Amendments

2026-04-19 — Argus A28 — Tier Reachability Rule + Path-Base Resolution in Group 0

Trigger: Argus A28 boot, 2026-04-19 — silent path-base bypass. Absolute paths anchored at the repository root were used instead of vault root. Tier 1 and Tier 2 reads 404'd. The v2.1 activation playbook's "note the gap, proceed on defaults" rule permitted a structurally non-compliant boot to complete and deliver a startup signal. Metis G44's agent-configurator tier-chain-bypass finding (same day, different cause) is a parallel case.

Amendments:

  1. Tier Reachability rule. In any established Tropo-OS vault, Tier 1 (.tropo/boot-config.md) and Tier 2 (.tropo-studio/agent-boot.extension.md) MUST be present and readable. A failed read halts activation. Defaults apply only to first-generation vaults where tier files have never existed (detected: settings/env.md absent).

  2. Path-base resolution moved to Group 0. The activation playbook's Step 0.0 now resolves vault root explicitly, BEFORE any tier reads, using the activation file's location as primary anchor (fallback: settings/env.md). Previously, vault root was resolved in Step 2.2, which meant Tier 1/2 reads in Step 0.1/0.2 depended on implicit path resolution.

  3. Boot Retrospective step added (Step 4.2). One-line what-worked / what-didn't capture in startup signal. Process-general findings route to channels/ops.md. Closes the silent-drift failure mode where structural defects persist across generations because no step asks the activating agent "what did you actually experience."

Files modified:

Verification: Cold-boot stranger test dispatched via Vela V31 post-revision. See channels/argus-vela.md Argus A28 coordination post, 2026-04-19.

What this does NOT change: The three-layer override contract, the vault administrator role, the canonical configuration matrix, or the composition semantics of the tiers. The amendment tightens failure handling and reorders one resolution step; it does not restructure the three-layer model.

ADR-032 | Proposed | Argus A22, April 13, 2026 | Amended | Argus A28, April 19, 2026 "Three layers. One contract. The OS sets the floor, the vault sets the room, the agent sets the chair."