stack/docs/plans/2026-09-07_agent-context-templates-and-migration.md

# Agent context, templates, and staged migration

Plan ID: ACT-1
Date: 2026-09-07
Recorder: Codex, at Jason's request
Status: owner decisions captured; execution sequence proposed; runtime migration deferred
Acceptance owner: Jason
Coordinator, implementers, and independent reviewers: unassigned

## Purpose and authority

`/home/jwoltje/src/mosaic-stack-dev-test` is the next-generation development leg
of `/mnt/storage/src/mosaic-stack`, being rewritten from the ground up to replace
that codebase. Earlier descriptions of this repository as only a standalone POC
do not fully describe its intended destination.

Jason requested a durable shared plan after agreeing to the context-file
responsibilities, personality improvements, template approach, and behavioral
evaluation described below. This request authorizes recording the plan. It does
not activate the implementation tasks or assign work to existing agents.

The current demo path must remain usable until Jason verifies it and the
transition is coordinated. Darkwing, Rocko, and Filbert have ongoing tmux work;
this plan must not change their sessions, launch inputs, assignments, or frozen
review candidates. Broad codebase organization for scaling comes AFTER demo
validation. Do not implement a monorepo move as preliminary cleanup.

At capture, [CURRENT.md](CURRENT.md) records a pending inspector correction and
independent review before owner demo acceptance. Read that live record on every
handoff; this document is not a competing next-action queue. Checkout HEAD was
`9a5fbdbda74b16adf488fe28138b2ba69ea5e669`, with substantial uncommitted work.
That SHA alone does not identify the working files or an accepted demo baseline.

## Agreed owner decisions

| ID | Decision |
|---|---|
| D1 | Each instruction file has a defined responsibility; avoid duplicating personality, governance, procedures, and runtime facts across layers. |
| D2 | Agent personality should produce concrete behavior: direct answers, evidence-backed recommendations, early challenges to flawed assumptions, useful brevity, and natural optional humor. Confidence must not erase uncertainty. |
| D3 | The agent's SOUL.md is the ONLY SOUL injected. Each agent has one canonical SOUL file. No shared default SOUL fallback or personality layering in the target system. |
| D4 | System bootstrap and agent bootstrap use a SOUL template to initialize each agent's own file. Templates also create appropriate agent-specific and deployed versions of other context files/contracts. |
| D5 | `docs/reference/templates/` was imported whole-cloth as an example. It is reference material to adapt, not an approved deployment source. Existing `contracts/*` are initial-session boilerplate; their eventual placement needs incremental treatment. |
| D6 | Evaluate behavior using test agents; Darkwing, Filbert, Heffer, and Rocko are available candidates. Their active sessions must be preserved. |
| D7 | Preserve the existing option through Jason's demo verification and a properly coordinated migration. |
| D8 | Organize for a scalable monorepo after demo validation; avoid premature source moves. |
| D9 | Annex adopted concepts as Mosaic documentation in docs/concepts; remove upstream runtime nomenclature rather than retaining foreign product instructions. Supporting source lineage and required license attribution remain in docs/reference/concepts. |

Proposed lifecycle details requiring design/review: templates initialize instances
without silently overwriting later edits; template updates are explicit migrations;
launch snapshots preserve historical bytes without becoming editable canonical
SOULs. These details implement the ownership intent and must be reconciled with
the existing foundation contracts before runtime changes.

## File responsibilities

| Resource | Intended responsibility | Must not become |
|---|---|---|
| CONSTITUTION.md | Shared boundaries, principles, authority relationships | Agent personality or a substitute for runtime permission enforcement |
| STANDARDS.md | Quality expectations and evidence requirements | A startup-marker-only contract or repeated repository procedures |
| Agent SOUL.md | Voice, temperament, judgment, and interaction style | A mission, capability grant, operational history, or second workflow manual |
| AGENTS.md | Repository procedures and working conventions | A universal worker prompt injected into every scope regardless of authority |
| USER.md / scoped user context | Relevant authorized preferences and personal context | Automatic distribution of the whole user profile to every agent |
| Runtime launch context | Actual identity, workspace, tools, skills, session semantics | Unverified capability claims or permanent persona instructions |
| Template sources | Reviewed defaults and bootstrap inputs | Live runtime fallbacks or competing editable agent identities |
| Execution snapshots | Evidence of exactly what an execution loaded | A second canonical configuration source |

Final paths, packaging, and update authority are intentionally unresolved. File
names and Markdown section order alone do not enforce precedence or security.

## Current behavior to preserve and then migrate

These are source observations from the preceding groundwork, not proof of full
runtime conformance. Reinspect the relevant files before preparing a candidate.

- [scripts/agent.sh](../../scripts/agent.sh) defaults to the existing container
  lifecycle. Explicit leading `--host-dev` delegates to
  [scripts/agent-host-dev.sh](../../scripts/agent-host-dev.sh).
- Container context comes from [src/load-contracts.sh](../../src/load-contracts.sh):
  image-baked governance, a default contract SOUL or a seat override, optional
  identity, live user Markdown, and mission context. The current fallback
  conflicts with D3 and needs a deliberate migration, not immediate removal.
- The native helper loads the selected agent SOUL, repository governance,
  deployment USER.md, repository AGENTS.md, and agent CONTEXT.md. It keeps
  launch snapshots and separate native sessions. It is a host development
  path, not proof of managed workspace isolation or role enforcement.
- Root SOUL.md is not loaded by these inspected paths. Do not delete it or
  `contracts/SOUL.md` until consumer inventory and evidence-preservation needs
  are resolved. Their presence does not make them authoritative in the target.
- POC startup-marker behavior is embedded in existing contracts and verification
  expectations. Any separation into explicit test fixtures must preserve valid
  health checks and cannot relabel skipped checks as passed.

## Relation to existing plans

- [Agent/project/workspace foundation](2026-09-06_agent-project-workspace-foundation.md):
  R16 already requires canonical agent SOUL and current approved context at
  Resume/Fresh launch; R17 describes configuration fingerprints and mismatch
  notices; R28 scopes personal context; R30 requires explicit legacy adoption.
  Extend and reconcile these decisions rather than designing a parallel lifecycle.
- [Phase-2 contract](2026-09-06_foundation-phase2-contract.md) and
  [workspace/schema/audit discussion](2026-09-06_workspace-schema-and-audit.md):
  reuse identity, revision, scope, and evidence concepts after checking their
  current approval state. A document reference is not runtime enforcement.
- [Installation/onboarding requirements](2026-09-06_foundation-install-onboarding-topics.md):
  bootstrap must integrate personality/style choices, trait compatibility,
  resumable initialization, and user privacy without granting extra permissions.
- [Monorepo source layout](2026-09-06_monorepo-source-layout.md): build on its
  source/build/install/state separation and component migration method. Reconcile
  historical milestone sequencing with Jason's explicit demo-first direction.
- [SOUL concept guide](../concepts/soul.md): use as personality design input;
  do not import its rewrite prompt as an instruction to modify deployed agents.

## Phases and gates

Concept documentation is maintained in [Mosaic Stack concepts](../concepts/README.md).
These are Mosaic explanations with current/proposed status, not a mirrored product
manual. [Provenance](../reference/concepts/README.md) records original lineage
separately from current content identity. Documentation adoption does not waive
the runtime migration gates below.

### Phase A — documentation and candidate design before demo acceptance

Record owner decisions, inventory context consumers, and define a migration and
evaluation proposal in separate planning artifacts. Any additional groundwork
requires a recorded assignment; this capture does not dispatch workers.

Outputs: source-backed loading/ownership matrix, candidate template responsibilities,
compatibility cases, isolated test design, and unresolved decisions. Preserve
active contracts, bootstraps, launchers, generated installations, session state,
credentials, and the current demo/review candidate.

Exit evidence: reviewed plan with owners, affected paths, current consumer list,
and concrete acceptance checks. This is planning readiness, not demo acceptance.

### Gate G1 — Jason verifies the current demo

Record Jason's acceptance and the exact candidate/evidence it covers in the
existing demo records, then link it here. Do not infer acceptance from green
tests, an agent verdict, or elapsed time. Acceptance of that demo does not
automatically activate every task in this plan; reconcile the next bounded scope.

### Phase B — bounded context/bootstrap migration

After G1 and assignment of the implementation increment, create reviewed template
sources and bootstrap-owned instances. Implement agent-only SOUL resolution with
clear missing/invalid-agent errors. Separate verification fixtures from normal
personality. Reuse existing config, lifecycle, and launch interfaces where suitable.

Prove idempotence, preservation of existing edits, interrupted-bootstrap recovery,
Resume/Fresh behavior, context provenance, and rollback in isolated fixtures.
Freeze a candidate, obtain independent review, and let Jason test the increment
before promoting it or retiring the old path. No running session silently reloads.

### Phase C — personality evaluation and controlled promotion

Use isolated test registrations/workspaces or distinct test identities derived
from the approved Darkwing/Filbert/Heffer/Rocko definitions. Decide the mechanism
before launch; a familiar name does not permit reusing live session directories.
Record model/harness settings, context hashes, scenario inputs, actual outputs,
reviewer findings, and Jason's preference verdict. Record model-call scope and
budget before live evaluations. Failed candidates remain evidence, not deployments.

Offline evaluation preparation may accompany Phase A; live trials and promotion
require their assigned scope. This phase must not become an unattended
self-rewrite loop or an automatic template rollout to all agents.

### Phase D — monorepo organization after validated behavior

Use the existing source-layout plan to define package boundaries, declarative
resource ownership, dependency directions, development installations, and release
artifacts. Move one component at a time with compatibility entry points and
verified rollback. Do not select a new package manager or copy the legacy tree
merely to give the repository a monorepo appearance.

## Collaboration work register

ACT-01 is complete. A later owner request authorized reference import and test
preparation under ACT-04; its draft pack is ready for review, not live execution.
Other tasks remain unassigned. Readiness does not dispatch another agent.

| Task | Deliverable | Dependency / gate | Status |
|---|---|---|---|
| ACT-01 | Capture owner decisions and staged shared plan | Current user request | Recorded by Codex |
| ACT-02 | Inventory all bootstrap, launch, health-check, retry, and packaging context consumers | Assigned documentation scope | Unassigned |
| ACT-03 | Specify template ownership, instance creation/update, provenance, and conflict rules | ACT-02; reconcile onboarding/foundation | Unassigned |
| ACT-04 | Define isolated behavioral scenarios, fixture identities, scoring, and model budget | Owner-authorized preparation; reconcile ACT-02/03 before trials | Draft prepared by Codex: [test package](act-1-tests/README.md); live budget and evaluation binding unset |
| ACT-05 | Freeze bounded migration candidate, compatibility checks, and rollback procedure | G1; ACT-03; implementation assignment | Deferred |
| ACT-06 | Implement and independently review context/bootstrap migration | ACT-05 | Deferred |
| ACT-07 | Run approved test-agent evaluations and obtain Jason's acceptance | ACT-04/06; evaluation assignment | Deferred |
| ACT-08 | Reconcile and execute component layout migration | Validated demo and affected behavior; layout assignment | Deferred |

For each assignment record task ID, author, independent reviewer, exact file scope,
workspace/worktree, baseline plus dirty-file identities where relevant, deliverable
path, dependencies, and acceptance owner. Do not preassign the active demo agents.

Use one designated editor for this plan's status and decisions. Concurrent authors
should write separate task notes named `2026-09-07_act-XX-<topic>.md` in this folder
and submit evidence pointers to the coordinator. A written assignment is not a
filesystem lock; source work requires coordinated ownership and isolated worktrees
where necessary. Preserve the shared Git index ownership recorded in CURRENT.md.
Direct communications and worker dispatch require actual assignment/authorization;
merely storing this file does not deliver it to another tmux session.

## Acceptance and evaluation cases

- **Single identity:** exactly one agent SOUL in effective context; root/default
  SOUL absent. Missing agent SOUL refuses launch rather than using another persona.
- **Bootstrap ownership:** initial system agent and subsequent agents each receive
  their own canonical instance. Rerun, interruption, and template revision never
  silently discard approved edits or create duplicate identities.
- **Stable execution:** record the approved inputs used by Resume and Fresh;
  changes to source do not alter already-loaded context. Historical snapshots
  remain immutable evidence and are not offered as editable canonical files.
- **Compatibility:** exercise every affected launch/verification consumer from
  ACT-02. Preserve session history and startup verification; demonstrate rollback
  without restoring or overwriting an active agent's conversation or work records.
- **Personality:** a simple question gets a direct answer; a flawed proposal gets
  a respectful challenge; an uncertain fact is labeled honestly; a failed action
  is reported accurately; an out-of-scope request does not gain authority from tone.
- **Style adaptation:** technical depth follows the task; humor is optional;
  public/shared communication fits its audience. Avoid rewarding profanity,
  contrarianism, verbosity, or confident guesses as evidence of personality.
- **Evaluation integrity:** compare baseline and candidate under recorded settings,
  retain actual responses, separate subjective style judgments from hard
  requirements, and repeat ambiguous cases. A few good responses are not a
  guarantee of behavior or security enforcement.

## Open design decisions

1. Final template source and deployed instance locations, including eventual
   ownership of constitution/standards and preservation of current contract fixtures.
2. Version/provenance representation and who may approve instance edits or upgrades;
   align with foundation context fingerprints instead of inventing a second scheme.
3. Explicit context precedence and consistent behavior across container and host
   modes, including scoped user information and all affected headless workers.
4. Trait composition during bootstrap, required versus optional template inputs,
   handling of contradictory choices, and existing-instance migration rules.
5. Concrete test-agent isolation, writer/reviewer allocation, evaluation rubric,
   budget, and sufficient evidence for owner acceptance.
6. Exact compatibility lifetime and rollback triggers before retiring boilerplate
   paths, followed by component layout decisions under the monorepo plan.

## Decision and handoff history

- 2026-09-07 — Jason agreed to responsibility separation, concrete personality,
  template-based instances, and evaluations; explicitly required one agent SOUL,
  demo compatibility, and post-validation structural work. Codex recorded ACT-1.
  No runtime implementation, agent launch, worker message, or task reassignment
  performed for this capture. Next planning task is ACT-02 when assigned; the
  operational next action remains in CURRENT.md.
- 2026-09-07 — Jason requested pulling the selected OpenClaw concepts and preparing
  testing with Darkwing. Copied twelve reference documents plus LICENSE with a
  source manifest; created eleven synthetic review scenarios, a candidate SOUL,
  NOT_RUN results and a preparation utility. See [Darkwing handoff](act-1-tests/README.md).
  `node scripts/prepare-concept-tests.mjs --check` verified thirteen imported files
  and eleven cases. Existing launcher regressions passed two tests in isolated
  fixtures. Prepared `/tmp/mosaic-act1-l2id7s` with 22 NOT_RUN baseline/candidate
  rows and mode 0700. This temporary workspace is reproducible, not durable test
  evidence. No model trials, active-session changes, demo-candidate changes,
  messages or migration implementation followed. Darkwing readiness review is
  prepared but not delivered or assigned automatically.
- 2026-09-07 — Owner directed full annexation and Mosaic nomenclature. Rewrote the
  twelve imported references plus the existing SOUL guide as thirteen Mosaic
  concept pages in docs/concepts, with an index and explicit implementation status.
  Replaced the old reference copies; source lineage and LICENSE now live under
  docs/reference/concepts. Renamed the benchmark concept to agent-behavior-tests.
  Updated ACT-1's cases and preparation utility to validate current Mosaic hashes,
  preserve original-source metadata and stage concepts/provenance separately.
  Thirteen concepts, license attribution, eleven scenarios and fifty local links
  verified; fresh review workspace /tmp/mosaic-act1-xVwXtF prepared with behavioral
  results still NOT_RUN. Earlier import/history records retain their original facts.
  No runtime launcher, deployed context, active session, or demo candidate changed.