Commando / MPD

Commando is a local-only meta-harness for Model-Paired Development (MPD). It turns a change into an explicit sequence of design, architecture, security, implementation, test, documentation, deployment-readiness, and Git-delivery facts. GitHub Actions is not required and is not accepted as validation evidence.

Use MPD with ChatGPT or Claude Code

You focus on the outcome you want. The model drives the MPD workflow.

1. Open your MPD-enabled repository in ChatGPT/Codex or Claude Code. If MPD is not set up yet, see Everyday flow.
2. Paste the matching prompt below and replace only [describe the outcome you want].

ChatGPT / Codex

Use MPD to deliver this outcome: [describe the outcome you want].

You drive the workflow. Start with `mpd conduct`, follow every
`mpd next --harness codex --context` brief, complete and gate each applicable phase,
test the real result, and report outcomes, risks, and decisions — not command logs.
Do not ask me to run MPD commands.

ACTUALLY SPAWN THE PERSONAS. This is the whole point, and it is the one thing the tool
cannot enforce for you.
- Each phase is a SEPARATE subagent with its own context. A verdict you record on your
  own work is not a review, however well-formed the artifact.
- Use the model `mpd next` resolves for the phase: Sol for Architecture, Design and
  Doc Validation; Terra for Security, Build, Test and Documentation.
- Record which happened, every time:
  `mpd gate <phase> --pass --evidence <artifact> --delegated --model <id>`
  If you did NOT spawn a separate agent, say `--self-recorded --model <id>` instead.
  Omitting both records UNKNOWN. Do not guess, and do not claim --delegated loosely.
- A skipped review I can see is worth more to me than a passed gate I cannot trust.

CLASSIFY THE CHANGE CORRECTLY — it now drives real cost:
- `--fix` (defect) and `--chore` (refactor/tooling/perf) skip Documentation and Doc
  Validation; they change nothing the durable docs describe. `--ui` adds the three
  Design phases. A Feature with no UI runs eight gates, a fix runs six.
- Declare the manifest completely before Build — every tracked file you touch. The
  gate refuses an undeclared tracked edit, which is how unvalidated source used to ship.
  If the scope is prose only, MPD selects the docs lane by itself and never compiles.

SIZE THE VERIFICATION TO WHAT ACTUALLY CHANGED. Read the diff before you gate:
- Each lane runs once per Candidate. Build, Security(code) and Test validate the same
  immutable subject; never re-run a lane an earlier gate already passed against it.
- Re-run the full cycle only for a real defect, or a security issue with a demonstrated
  path of access. Never re-drive because prose was reworded, a comment moved, an
  artifact was reformatted, or a gate was re-recorded.
- Record non-blocking or comment-only findings as notes in the artifact, not as a FAIL.
- Author the plan and its artifacts completely before gating, so you are not rewinding
  to fix wording. Strip every `<!-- -->` placeholder before you archive.
- A trivial fix that is not really a change (a typo, a hotfix) can be committed directly
  without manufacturing a change for it. The secret scan still applies to every commit.

BUDGET: if this change has already cost more than one full re-drive, stop and tell me
what the next gate would buy before spending it. Endless cycling is a process defect,
not diligence.

Stop only for a genuine product decision or an external-release authorization you do
not already have.

Claude Code

Use MPD to deliver this outcome: [describe the outcome you want].

You drive the workflow. Start with `mpd conduct`, follow every
`mpd next --harness claude-code --context` brief, complete and gate each applicable phase,
test the real result, and report outcomes, risks, and decisions — not command logs.
Do not ask me to run MPD commands.

ACTUALLY SPAWN THE PERSONAS. This is the whole point, and it is the one thing the tool
cannot enforce for you.
- Each phase is a SEPARATE subagent with its own context. A verdict you record on your
  own work is not a review, however well-formed the artifact.
- Use the model `mpd next` resolves for the phase: Fable for Architecture, Design and
  Doc Validation; Sonnet for Security, Build, Test and Documentation.
- Record which happened, every time:
  `mpd gate <phase> --pass --evidence <artifact> --delegated --model <id>`
  If you did NOT spawn a separate agent, say `--self-recorded --model <id>` instead.
  Omitting both records UNKNOWN. Do not guess, and do not claim --delegated loosely.
- A skipped review I can see is worth more to me than a passed gate I cannot trust.

CLASSIFY THE CHANGE CORRECTLY — it now drives real cost:
- `--fix` (defect) and `--chore` (refactor/tooling/perf) skip Documentation and Doc
  Validation; they change nothing the durable docs describe. `--ui` adds the three
  Design phases. A Feature with no UI runs eight gates, a fix runs six.
- Declare the manifest completely before Build — every tracked file you touch. The
  gate refuses an undeclared tracked edit, which is how unvalidated source used to ship.
  If the scope is prose only, MPD selects the docs lane by itself and never compiles.

SIZE THE VERIFICATION TO WHAT ACTUALLY CHANGED. Read the diff before you gate:
- Each lane runs once per Candidate. Build, Security(code) and Test validate the same
  immutable subject; never re-run a lane an earlier gate already passed against it.
- Re-run the full cycle only for a real defect, or a security issue with a demonstrated
  path of access. Never re-drive because prose was reworded, a comment moved, an
  artifact was reformatted, or a gate was re-recorded.
- Record non-blocking or comment-only findings as notes in the artifact, not as a FAIL.
- Author the plan and its artifacts completely before gating, so you are not rewinding
  to fix wording. Strip every `<!-- -->` placeholder before you archive.
- A trivial fix that is not really a change (a typo, a hotfix) can be committed directly
  without manufacturing a change for it. The secret scan still applies to every commit.

BUDGET: if this change has already cost more than one full re-drive, stop and tell me
what the next gate would buy before spending it. Endless cycling is a process defect,
not diligence.

Stop only for a genuine product decision or an external-release authorization you do
not already have.

That is the whole user workflow. The model creates the change, calls the stages in order, writes the required artifacts, validates the result in proportion to what changed, fixes failures, and reports what actually shipped. If MPD is missing or the repository is not configured, the model should report the blocker and the exact setup step instead of pretending the workflow ran.

MPD is deliberately not an oracle or an independent attestation service. Its trust boundary is a cooperative repository owner. An owner can replace the executable, edit Git state, or bypass hooks with --no-verify; MPD records and checks the normal path but does not claim to resist that owner. Actor/model/session labels are cooperative provenance unless an external harness authenticates them.

Everyday flow

Install the current source while developing Commando:

cargo install --path crates/mpd --force --locked

Start and drive a strict change:

mpd conduct my-change

# Repeat until phase=done.
mpd next --harness codex --context
# Perform exactly the named role and author its artifact when required.
mpd gate <phase> --pass --by <actor> --evidence <artifact>

mpd status
mpd archive --yes
git commit
git push
mpd publish --verify

mpd status --json is the automation interface. It emits one JSON document and keeps these facts separate: worktree, candidate, gate freshness, local validation, archive, commit coherence, push authorization, observed transfer, remote parity, installation, and containment certification. Remote parity does not repair missing or bypassed push authorization. A Build receipt does not fill the full Test-profile field.

Quality, cost, and time maturity

MPD's quality controls are managed and evidence-gated: written intent, separated roles, adversarial Security review, and distinct Deploy/publication observations are enforced by the ledger. When local_validation is configured, objective gates also bind exact Candidate identity and structured validation receipts. Without it, strict Build/Test use the configured legacy test command and secret scan, and Deploy uses the legacy command or readiness path; those passes do not claim a Candidate, structured receipt, containment certification, typed Build output, or installed-byte identity. This is strong local process assurance, not proof that a model answer is correct and not protection from a repository owner who replaces or bypasses the coordinator.

Cost and time controls are coverage-aware, but less mature than the quality gates. .mpd/config.json defines risk-specific soft/hard token and wall-time budgets plus the fixed two-consecutive-blocker/30-minute anti-stall rule. Soft limits warn; hard limits and anti-stall stop issuance of a new brief, not status, evidence inspection, or already-recorded truth. Missing provider usage is never inferred: token, active-time, currency, and cost totals remain UNREPORTED, PARTIAL, or UNAVAILABLE unless bounded attempt evidence covers the applicable attempts.

Authenticated model/session provenance is NOT DEPLOYED in this repository. The configured mode is cooperative with no external issuers. An omitted attestation does not block; actor/model/session labels remain cooperative. Required mode is fail-closed and is suitable only after a real external issuer is configured and independently verified. Fixtures or owner-self-signed samples are test evidence, not production provenance.

When evidence is available, bind it to the exact gate attempt:

mpd gate <phase> --pass --by <actor> --evidence <artifact> \
  --attestation <attestation.json>

Routing optimization is controlled experimental. The versioned blind suite is in benchmarks/routing-v1/, but no sufficient adoption-evidence envelope is committed by default. Current Sol/Terra mappings are therefore not claimed Pareto-optimal:

mpd routing evaluate --evidence <routing-evidence.json>
mpd routing apply --evidence <routing-evidence.json>       # preview only
mpd routing apply --evidence <routing-evidence.json> --yes # revalidate, then write

See the scored maturity assessment for evidence requirements and limitations.

Ordered gates

Every strict change follows:

Design Mock -> Architecture -> Design Review -> Security (plan) -> Build ->
Security (code) -> Design Sign-off -> Test -> Documentation ->
Doc Validation -> Deploy

Two axes select which phases apply:

• The three Design phases run when the change has a UI/UX surface (--ui), and are otherwise inapplicable with a stored no-human-visible-impact rationale.
• The two Documentation phases run for a Feature. A --fix restores behavior the documentation already describes and a --chore changes no functional behavior, so neither pays a Documenter pass plus a two-persona deep-tier validation. A defect fix walks Test -> Deploy.

Architecture, Security (plan), Build, Security (code), Test, and final Deploy/readiness are mandatory for every change. A FAIL blocks. A CONDITIONAL PASS remains open until every condition is resolved.

Each gate records how the verdict was produced. mpd next offers the flags and mpd stats reports them:

mpd gate <phase> --pass --evidence <artifact> --delegated --model fable
mpd gate <phase> --pass --evidence <artifact> --self-recorded --model sonnet

--delegated states that a distinct persona agent ran; --self-recorded states that the driving session recorded the verdict on its own work. Omitting both records UNKNOWN — absence is never defaulted into either. --model is compared against the model mpd next resolved for that exact attempt, so route compliance becomes measurable rather than merely printed. A self-recorded PASS is honest bookkeeping; it is not an adversarial review, and the ledger no longer conflates the two.

Strict judgment artifacts contain the required sections, exactly one ## Actor, and exactly one ## Verdict whose first nonblank line is PASS, CONDITIONAL PASS, or FAIL. The artifact Actor must exactly match --by and must differ from the latest applicable upstream gate actor. Commando has no artifact-waiver flag. Older ledgers with waiver records remain readable but cannot satisfy strict archive.

Builder tasks use an explicit contract sentence—Every box is required and has a stable ID.—and canonical checkbox lines such as - [ ] 3.1 .... Test and archive fail closed while required tasks are open or a deferral is stale.

Exact candidate and freshness

Planning gates name the planning subject and report Candidate: NOT CAPTURED. Build materializes an immutable, read-only projection of base HEAD plus the manifest-scoped staged/unstaged tracked postimages, declared untracked files, deletions, and modes. Build, Security(code), and Test reopen and rehash that same Candidate before and after execution. Candidate receipts and Commit/HEAD receipts are different subjects.

The manifest is the change boundary. Any causal input change projects the earliest affected rewind before the next brief or effect. A tracked file edited outside that boundary refuses the strict Build/Security(code)/Test gates — declare it in the manifest or stash it — so a change can no longer silently ship a source file the sandbox never validated; an untracked out-of-scope file stays user-owned (a note, not a refusal). If a landing commit still drifts, mpd publish --verify names the offending paths. mpd repair-state --to <phase> --reason <text> previews a legacy repair; add --yes to append the rewind. It never creates a PASS or erases history. Effective risk is the maximum of requested and derived risk; configuration cannot lower it.

When a rewind leaves the Candidate byte-identical, a strict Build/Test gate may reuse the prior validation receipt instead of re-executing the sandbox: mpd gate <phase> --pass --reuse <receipt>, offered by mpd next. The Candidate binds the change's source, config, specs, and manifest — but not its own process prose (design.md/proposal.md/tasks.md and the judgment artifacts): those are excluded from the Candidate id (schema v2) and instead covered by a dedicated fail-closed secret-scan lane at every strict Build/Security(code)/Test gate. So an uncommitted edit to the change's prose leaves the Candidate byte-identical and is reusable — the common "fixed a wording or closed a review condition after its gate" rewind no longer re-runs the sandbox. Anything that changes the validated bytes still re-executes: any in-scope source/config/spec/manifest edit, a committed prose edit (base HEAD moves), a history/** shuffle, and Security(code) always. Reuse is fail-closed — it requires the same Candidate id, gate profile, policy digest, revalidated build output, and a hermetic-complete receipt bound to the coordinator's own executable digest; any drift re-executes. It is enabled by .mpd/config.json's closure.hermetic_reuse, whose external_state: "none" attests that no unpinned external mutable state feeds validation — the ambient reads that remain (cargo config under $CARGO_HOME, the SDK via DEVELOPER_DIR, the cargo/rustc binaries, OS beyond os-arch) are pinned by offline+locked builds, Cargo.lock checksums, and execution-time tool-digest verification against security/tool-lock.json.

Validation receipts also identify each check as executed or reused. Check reuse is limited to a current-change/current-subject passing executed origin with the same check digest and complete Candidate/profile/policy/tool/host/adapter/environment identity. Reuse chains flatten to that executed origin. Security(code), outgoing secret scanning, Commit, and pre-push validation retain their fresh-execution floors.

Effective risk drives depth, not attempt pressure: at High, Security and Tester resolve to the deep model with a raised effort floor and Test runs the heavier high-risk-test profile; High in fact loosens the attempt limit relative to Medium/Low. A documentation-only change derives Low; other changes derive High because their source and .mpd/ policy files are verification authority. mpd next --harness <h> prints the resolved per-phase model — authoritative over any prose.

Local validation and containment

Authoritative checks use typed program/argv data, pinned tool identities, offline Cargo and advisory inputs, bounded logs/resources, private HOME/Git/XDG/temp state, and a network-denying platform adapter. There is no hosted, shell-string, ambient-PATH, unsandboxed, or broad-read fallback.

The production certification boundary for this release is intentionally narrow:

• Apple silicon, aarch64-apple-darwin;
• macOS 27.0 build 26A5378n;
• the exact compiled adapter ABI and fixed security/sandbox/validation.sb profile;
• a canonical root inventory and current denial/inheritance/non-escalation canaries; and
• the complete high-risk local profile.

Every other host is NOT CERTIFIED. Linux code remains experimental and cannot produce this release's certified claim.

The macOS adapter uses deprecated custom-profile Seatbelt entry points and undocumented sandbox-extension SPI. It is a fail-closed exact-host compatibility mechanism, not a supported or portable Apple API. Its certified claim is limited to accepted-root file content reads, writes to one private runtime root plus /dev/null, and network denial. It does not claim global path-metadata or literal-root-entry confidentiality, nor same-user process isolation.

The complete high-risk profile runs formatting, warning-denied Clippy, locked/offline workspace tests, release build, cargo-audit without updating, gitleaks, Semgrep, the phase-model lane, and the explicit 10k-path/100MB closure workload. A narrower cargo -> rustc -> linker -> test binary probe is feasibility evidence only.

Local setup and policy activation

Clone-private inputs live under the Git common directory and are never committed. Bootstrap is explicit and network-enabled; validation itself is offline:

bash scripts/bootstrap-local-ci.sh

The sole activation route binds an immutable reviewed commit, canonical policy digest, absolute coordinator bytes, tracked wrappers, and .githooks. Read the digest for the commit you reviewed first — it is SHA-256 over the serialized local_validation policy, not a hash of .mpd/config.json, so it cannot be reproduced with shasum or jq:

mpd policy digest --commit <full-commit-oid>     # or --json | jq -r .policy_digest

mpd policy activate \
  --commit <full-commit-oid> \
  --confirm-policy-digest <digest from the previous command> \
  --coordinator <canonical-absolute-mpd-path> \
  --confirm-executable-digest <sha256 of that binary> \
  --hooks .githooks \
  --yes

policy digest is read-only: it activates nothing and changes no trust state. It does not weaken the confirmation — activate still refuses a mismatch without revealing the expected value, so naming the digest remains the operator's statement of which reviewed policy they are binding. Any .mpd/config.json change produces a new digest, so re-read it before reactivating.

Activation is a clone-local owner trust decision, not independent proof. It installs owner-only clone-private launchers and configures core.hooksPath to that directory. Missing or drifted policy, coordinator, wrapper, tool, host, profile, ABI, or canary blocks validation. There is no legacy trust-bootstrap policy route.

Useful local commands:

# Full current-commit profile through the activated coordinator.
bash scripts/ci-local.sh --profile high-risk-test --commit HEAD

# Read-only diagnostics; neither command runs validation or installs anything.
mpd doctor --scope validator-policy --enforce
mpd doctor --scope runtime-health --enforce

# Fast staged check, normally called by pre-commit.
bash scripts/ci-local.sh --staged

# Read-only candidate-cache inventory and preview-first pruning.
mpd cache inspect
mpd cache prune
mpd cache prune --yes

mpd doctor --fix only heals .mpd/.gitignore additively. It does not change policy, hooks, configuration, receipts, installation, or remote state.

Bare mpd doctor reports typed pre-commit states instead of trusting marker text as proof of an activated wrapper. mpd status and mpd status --json likewise distinguish active, archived-current, pending-archive, awaiting-commit, closed, and invalid current-pointer states without recreating active state.

Git-local enforcement and publication

The activated pre-commit hook performs bounded staged secret and artifact/task checks. Pre-push reads Git's four-field protocol from stdin, validates every outgoing commit, tag, message, and blob, and issues an invocation-local authorization bound to the exact remote, baseline, update rows, object set, policy, and nonce. It never pushes, fetches, or writes refs; normal Git owns transport.

Deletion-only pushes still run trust, policy, and ref checks. Main and tag deletion are denied. A non-main branch deletion requires one exact one-use approval:

mpd hook approve-deletion --help

After Git returns, mpd publish --verify freshly compares the coherent closure commit with the configured remote ref. Publication status distinguishes authorization, transfer observation, and parity.

Deployment and installation

With typed Build/Deploy output configured, Build records one candidate-bound release file. Execute Deploy copies those already tested bytes through an exclusive temporary, syncs/atomically replaces the destination, then reopens and checks mode, length, and SHA-256. It does not rebuild or execute the installed candidate for identity. Legacy-command and readiness-only Deploy are reported without claiming installed-byte identity or installation.

Repository verification

The direct development commands are:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --offline --locked -- -D warnings
cargo test --workspace --all-targets --offline --locked
cargo test --release -p mpd scoped_digest_throughput_over_10k_paths_100mb \
  --offline --locked -- --ignored --nocapture
cargo build --workspace --release --offline --locked
bash scripts/check-doc-staleness.sh

The local profile is authoritative because it binds the exact subject and containment receipt; these direct commands are useful during development but do not by themselves create an MPD gate receipt.

Recovery and truth labels

• mpd next records a required freshness rewind before returning a new brief.
• mpd reconcile --continue <reason> authorizes one bounded excess review attempt.
• mpd archive --recover completes an interrupted owned archive transaction.
• mpd archive --abandon removes only owned closure metadata at the allowed stage.
• mpd use <change> restores a cleared current-change pointer.
• mpd status always shows the next safe action and never treats parity, install, or a narrower receipt as proof of a wider state.

See ARCHITECTURE.md, SECURITY.md, and CONTRIBUTING.md for design, threat-model, and contribution details.