Skip to content

v5.31.0 — Governed Development Mission Protocol

Choose a tag to compare

View all tags
@samibs samibs released this 04 Sep 05:04
· 25 commits to main since this release
v5.31.0
856ea78
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Adds the durable half of SkillFoundry's engineering record, plus the final enforce stage of the AgentOS output-contract rollout begun in v5.29.0.

Both are additive and opt-in — nothing changes for an existing project until it starts a mission or flips the contract mode.

Why

Run state in .skillfoundry/runs/ describes one execution and dies with it. The next agent — a new session, a different model, a colleague's machine — starts from nothing but chat history, which is the least reliable record in the system.

.ai/ lives in the repository and survives the agent:

Git             what exact content changed over time
Attestation     where, and under what conditions, did the worker operate
Patch guide     what changed and why
Evidence        what proves the implementation satisfies the requirement
Ledger          what is the project's current authoritative engineering state
──────────────────────────────────────────────────────────────────────────
                = governed engineering history

Enforcement is code, not prose. Agents never hand-write .ai/*.json — seven TypeScript modules write and validate it, and refuse claims the repository cannot substantiate.

What it catches that a green test run does not

Failure How it is blocked
"Tests passed" while the runner hung Normal termination is an acceptance criterion; a killed or orphaning run is NOT A CLEAN VALIDATION
A dev server orphaned after the run Per-PID identity fingerprints; a recycled PID is refused, not killed. Broad pkill node is impossible by construction
A contribution silently dropped in a merge git patch-id --stable + blob-level final-tree check; LOST / UNKNOWN block acceptance
"Pushed" mistaken for "published" The remote SHA, tree and contribution content are re-read after the push
"It was probably already broken" Requires a baseline run at the accepted baseline SHA, or the claim is not substantiated
Retry loops burning budget NO_PROGRESS after two identical failures with no state change
Fixing working code for a broken environment Defect-origin classification before any remediation
Two agents writing in one directory Registration refuses a second ACTIVE write agent per worktree

Evidence-gated promotion

/mission set STORY-042 acceptance_status PASS

  ✗ Refused: acceptance_status stays NOT_STARTED

  The ledger must never claim more than evidence proves:
    · blocked by unsatisfied AC dispositions: AC8=BLOCKED_BY_AUTHORIZATION
    · blocked by open gaps: GAP-001
Status Requires
implementation_status = COMPLETE a worker SHA and an existing patch guide
acceptance_status = PASS evidence on disk, every AC dispositioned, no blocking gaps
integration_status = INTEGRATION_VALIDATED provenance that is not LOST / UNKNOWN
publication_status = PUBLISHED a remote-verified SHA and tree

Five dimensions advance independently — a feature can be implemented but not accepted, accepted but not published.

Multi-agent execution

MULTI_AGENT_PROTOCOL.md installs into every scaffolded project. One dependency graph across all PRDs; collision-aware wave planning that defers rather than merges; one git-native worktree per writer, with sharing refused; serial integration in dependency order.

Parallel implementation is not parallel merging.

Getting started

/mission init STORY-042 --title "JWT refresh rotation"
/mission attest STORY-042 --worker claude-coder-042 --agent claude
/mission gate STORY-042                      # WRITES AUTHORIZED / BLOCKED

  ... implement ...

/mission evidence STORY-042 --kind tests --run "npm test"
/mission commit STORY-042
/mission verify STORY-042                    # Definition of Done

/mission help lists all 25 subcommands.

Part 2 — AgentOS enforce mode

A fourth tier for message_contracts (off | permissive | strict | enforce). In enforce, agent output contracts become binding: an agent whose structured result violates its contract is downgraded to failed rather than merely logged. Off by default; prose-only results are never a violation, so free-text agents are never failed.

Tests

296 new across 8 files, all passing. Integration-style rather than mocked: real git repositories, real linked worktrees, real bare remotes, real cherry-picks, and spawned child processes exercising orphan detection, ownership verification and PID-recycling refusal.

Three defects were found by dogfooding the protocol on SkillFoundry itself and fixed before release — including a mistyped command that exited 0 and was recorded as CLEAN VALIDATION with zero tests run, exactly the false green the protocol exists to prevent.

Compatibility

  • Fully backward-compatible. Projects without a .ai/ ledger are unaffected; a ledger written before the execution plane existed is normalized on read.
  • Evidence payloads are redacted and size-bounded at 256 KiB. Raw logs live outside git and are referenced, never inlined.
  • All git invocations use execFileSync with argument arrays; every identifier is validated so none can escape the artifact tree.
  • All artifact writes are atomic (temp + rename).

Full detail: CHANGELOG [5.31.0] · release notes · MULTI_AGENT_PROTOCOL.md · PR #49

Assets 2
Loading