Musketeer logo Musketeer

Architecture

Musketeer operates on a strict two-namespace model. Canonical execution state is owned by the SMALL protocol. Musketeer adds an execution layer on top.

Ownership boundaries

SMALL owns

  • Replay identity (workspace.small.yml)
  • Intent (intent.small.yml)
  • Constraints (constraints.small.yml)
  • Plan (plan.small.yml)
  • Progress (progress.small.yml)
  • Handoff (handoff.small.yml)

All of these live in .small/. Musketeer reads from them but never writes to them.

Boundary rule: if it is intent, constraints, plan, progress, or handoff, SMALL owns it.

Musketeer owns

  • Workspace configuration (musketeer.yml)
  • Role packets (packets/)
  • Auditor verdicts (verdicts/<replayId>.verdict.yml)
  • Execution logs (runs/<replayId>/execution-log.yml)
  • Run metadata

All of these live in .musketeer/.

File layout

.small/
  workspace.small.yml
  intent.small.yml
  constraints.small.yml
  plan.small.yml
  progress.small.yml
  handoff.small.yml

.musketeer/
  musketeer.yml
  packets/
  verdicts/
    <replayId>.verdict.yml
  runs/
    <replayId>/
      execution-log.yml

What check validates

The check command validates both sides:

SMALL state:

  • All required .small/ files exist
  • Replay ID consistency across files
  • Progress sequence integrity (seq starts at 1, strictly increasing)
  • Plan task ID uniqueness

Musketeer execution state:

  • Verdict status (reject causes exit 23 with E_VERDICT_REJECTED)
  • Run directory structure

Legacy deprecation

Legacy workspaces stored all artifacts under .musketeer/runs/<uuid>/ using Musketeer-specific schemas. This layout is deprecated.

  • Use musketeer migrate to convert legacy workspaces to SMALL-native layout
  • SMALL-native is the canonical model going forward
  • Mixed-mode (some artifacts in both places) is not the preferred steady state
  • Legacy shadow artifacts are deprecated and will be removed in a future version