Skip to content

Scheduled Artifact Reconciliation

Scheduled Artifact Reconciliation automatically detects when your deployed project artifacts have drifted from their collection originals and surfaces gated proposals for you to review. No automatic changes are ever made — you accept or reject each proposal explicitly.

v1.0 scope (Pillar A — local edition): drift detection for deployed artifacts against collection. Enterprise pull-queue and upstream drift detection (Pillar B) are in v1.1.

Overview

When reconciliation is enabled, a background deployment.reconcile job runs hourly (with jitter). It compares the content hash of every deployed project artifact against its collection original and emits a drift_update proposal when drift is detected.

Proposals accumulate in the Reconciliation Proposals queue. You review them in the sync-status tab of any artifact's detail view, or from the CLI. Accepting a proposal applies the updated content through the standard deploy rail and records a version entry. Rejecting or letting a proposal expire discards it with zero writes to your project files.

Propose-only guarantee: The worker never mutates project content. Mutations happen exclusively when you call accept — the same code path as a manual skillmeat deploy.

Enabling Reconciliation

Reconciliation is OFF by default. Enable it in your SkillMeat configuration:

# ~/.skillmeat/config.toml  (or set via env var)
[features]
reconciliation_enabled = true

Or via environment variable:

export SKILLMEAT_RECONCILIATION_ENABLED=true

After enabling, restart the background worker:

skillmeat web dev          # dev mode — restarts automatically
# or, for a running service:
systemctl --user restart skillmeat-worker

The worker also respects the master kill-switch: setting SKILLMEAT_WORKER_ENABLED=false disables all background jobs including reconciliation regardless of reconciliation_enabled.

Using the Web UI

Viewing Proposals in the Sync-Status Tab

  1. Open any artifact's detail view (click the artifact in /artifacts).
  2. Select the Sync tab.
  3. A Reconciliation Proposals panel appears when there are open proposals for this artifact.
  4. Each proposal shows:
  5. The drift type (drift_update)
  6. When it was detected
  7. A DiffViewer with the unified diff between your deployed content and the collection original

Accepting a Proposal

Click Accept on a proposal to apply the collection version to your project.

  • The artifact is re-deployed via the standard deploy rail.
  • A version entry is recorded in the artifact's version history.
  • The proposal status moves to accepted.

If the proposal involves a cross-axis conflict (both collection and upstream changed simultaneously), the accept button shows a warning; you must resolve the conflict interactively before accepting.

Rejecting a Proposal

Click Reject to dismiss a proposal without making any changes to your project files. Rejected proposals are retained for audit but will not recur until drift is detected again in a subsequent reconciliation run.

Using the CLI

# List all open proposals across all projects
skillmeat reconcile list

# List proposals for a specific project
skillmeat reconcile list --project <project-id>

# Show details + diff for a specific proposal
skillmeat reconcile show <proposal-id>

# Accept a proposal (applies the collection version to the project)
skillmeat reconcile accept <proposal-id>

# Reject a proposal (no project writes; proposal closed)
skillmeat reconcile reject <proposal-id>

# Trigger an immediate reconciliation run (bypasses hourly schedule)
skillmeat reconcile run
skillmeat reconcile run --project <project-id>   # single project only

Safety Guarantees

Propose-Only Invariant

The deployment.reconcile job is structurally prohibited from writing to your project files. The only code path that applies changes is POST /api/v1/reconciliation-proposals/{id}/accept, which is the same deploy rail used by skillmeat deploy. This is enforced by a test in the CI suite (PRD AC-1).

Rolling Back an Accepted Proposal

If you accept a proposal and want to undo it, use the standard version history rollback:

# List version history for the artifact in your project
skillmeat versions list <artifact-id> --project <project-id>

# Restore a previous version
skillmeat versions restore <artifact-id> <version-sha> --project <project-id>

The version recorded at accept-time appears as the entry immediately before the restore point in the version graph, making rollbacks straightforward.

Proposal Expiry

Open proposals that are not acted on within the configured TTL (default: 7 days) automatically expire. Expiry does not touch project files. A new proposal will be emitted on the next reconciliation run if drift persists.

Feature Flags Reference

Flag Default Description
reconciliation_enabled false Enables the deployment.reconcile periodic job and the proposals queue
SKILLMEAT_WORKER_ENABLED true Master kill-switch for all background worker jobs

Set reconciliation_enabled = true in [features] of ~/.skillmeat/config.toml, or via the SKILLMEAT_RECONCILIATION_ENABLED environment variable.

  • Version history and rollback: docs/user/guides/collection-refresh-rollback.md
  • Edition feature matrix: docs/user/guides/edition-feature-matrix.md (Pillar B enterprise features in v1.1)
  • Architecture decision (propose-only): docs/dev/architecture/ADRs/adr-reconcile-1-propose-only.md