Updates and rollback

allagma.yaml is study-owned selection intent. .allagma/lock.yaml resolves it to one release and exact content. .allagma/bundles/<bundle-id>/ contains all selected methods, resources, contracts and helper code. Dependencies are resolved within that release, not mixed across independently published module versions. Local variants are explicit overlays with their base and scope.

The lock records release/tag, publication status, content-addressed immutable source revision, selected module revisions and dependencies, inventory/digests, capabilities, generator/scaffold provenance, effective configuration, origins and profile/override input hashes. Local releases use a SHA-256 source snapshot and are marked local-unpublished; this is not a claim that a Git tag has been published. Published assets must retain the recorded source and tag unchanged.

The source revision hashes the complete distributable source inventory; the bundle inventory hashes the selected closure. Generated bytecode is ignored. The exporter rejects source edits observed during copying. Replaced role defaults do not enter the selected dependency closure unless another module actually depends on them. The bundled catalog records the resolved roles. Source and configuration are reproducible; this does not promise identical sampling from a closed hosted model service.

Campaigns and ownership

At campaign start, copy the lock and scientific materials. Resume and host entrypoints use that campaign snapshot. CLI execution dispatches to its exact bundled helper. Editing central source or a later active lock does not change the old campaign. New campaigns check selection intent and configuration input freshness and reject a mismatch; they never silently upgrade.

Keep user changes in overrides/ or modules-local/. Updates preserve the brief, domain code, raw data, paper, root instructions and unowned skills. .allagma/ownership.json identifies generated paths. Edits to them block an update and must be reconciled deliberately. The generator resolves preexisting names by using an Allagma-specific alternative and records its mapping.

All referenced bundles and evidence use retain-with-study. Do not delete a bundle while any campaign refers to it. Allagma has no automatic garbage collection in v0.2. Commit the small bundles, locks and evidence needed for a public study; handle credentials and large data separately.

Update commands

From a source checkout, with an explicit target source directory:

python3 -m allagma update check --study work/my-study --source /path/to/target
python3 -m allagma update plan --study work/my-study --source /path/to/target
python3 -m allagma update reconcile --study work/my-study --id u-ID
python3 -m allagma update validate --study work/my-study --id u-ID
python3 -m allagma update adopt --study work/my-study --id u-ID

check is read-only. plan exports a candidate and records changed paths, composition, configuration and compatibility without changing the active lock. reconcile checks base/local/target identities, ownership and input freshness. validate checks candidate integrity, contracts, capabilities and executable adapter examples. adopt requires those receipts and a campaign boundary. Paused and completed campaigns preserve their snapshots; a running execution blocks adoption. Routine updates do not require a new approval when already authorized.

The candidate is frozen when planned. A later central edit does not change it; later study or scaffold-baseline edits invalidate the plan. The lock records the scaffold baseline at resolution, and the plan separately identifies the target source’s scaffold version; a method update does not claim that a scaffold migration occurred. Events record completed operations and failures. Adoption journals preimages, writes entrypoints/ownership and commits the active lock last. An interrupted transaction blocks active use until:

python3 -m allagma update recover --study work/my-study

Recovery checks preimages and expected postimages before restoring any file. Edits made after the interruption block recovery for reconciliation. Earlier campaign snapshots remain usable. Reconcile and validate a fresh plan if intent has changed.

Rollback and scaffold migration

python3 -m allagma update rollback --study work/my-study --id u-ID

Rollback creates a new history record selecting the pre-update bundle and configuration. It restores the saved profile/override projection and intent; post-adoption edits to those files block rollback rather than being erased. Both bundles and all research results remain retained. Rollback does not apply an inverse scaffold migration automatically.

Scaffold migrations are separate JSON descriptors with from, to, generation answers, reason, and files mapping study-relative paths to target text (or null to remove a declared path). The baseline and preimages are retained. Base/local/target comparison preserves local changes when the template did not change and exposes conflicts when both changed. Bundles, campaigns and native entrypoints cannot be rewritten through a scaffold migration.

python3 -m allagma migrate plan --study work/my-study --spec migration.json
python3 -m allagma migrate apply --study work/my-study --id m-ID
python3 -m allagma migrate rollback --study work/my-study --id m-ID

The inverse restores exact pre-migration user files and refuses to erase work made afterward. The acceptance fixture demonstrates migration, conflict preservation and inverse rollback separately from a method update.

Application journals its preimage before changing user files. An interrupted multi-file migration blocks new active-lock work. Run migrate recover --study work/my-study --id m-ID to restore the preimage or finish an already committed migration. Edits made after interruption are exposed for reconciliation.

Local variants

Copy a method into modules-local/allagma-context-custom, give it a new ID and matching skill name, and retain its contract. For example, extend intent with:

{
  "roles": {"context": "context/custom"},
  "allow_experimental": true,
  "local_modules": [{
    "id": "context/custom",
    "path": "modules-local/allagma-context-custom",
    "base": "context/active-brief",
    "scope": "method"
  }]
}

Merge those fields into the existing intent rather than replacing it. Plan and adopt as usual. The exporter validates the replacement contract, copies declared resources and records local lineage/input digests. Subsequent local edits require a new resolution; active campaigns keep the captured variant. Other module kinds can be contributed to an explicit source release; v0.2’s study-local overlay supports method replacements only.

---

Canonical source · Generated from the maintained repository document at this build’s commit.