Keeper Boundary And Mission Requests

Keel's normal path is direct and local: a human or agent uses mission, epic, voyage, and story commands to shape the board inside the repo.

That is still the primary way to learn and use Keel.

This page covers the boundary that matters when Keel is embedded inside a larger runtime such as Keeper or when external systems need to request work without bypassing the board contract.

Keel still owns planning truth

Keel owns:

• the mission, epic, voyage, and story hierarchy
• the authored planning artifacts that constrain work
• the lifecycle states that decide what is real on the board
• the proof and acceptance contract for closure

That means external providers should not invent .keel state directly.

They should lower requests into Keel through a formal planning boundary.

Keeper owns runtime ingress and execution

If you run Keel inside Keeper, Keeper becomes the runtime boundary around the board:

• provider polling and webhooks
• provider authentication and request retrieval
• request revision tracking and replay
• execution routing, leases, and runtime coordination
• provider-facing acknowledgement delivery

That split is intentional. Keel stays authoritative for planning semantics. Keeper stays authoritative for runtime coordination.

Formal mission requests

The documented external-ingress shape is a provider-neutral mission request.

The first provider form is GitHub issues.

First documented GitHub issue shape

Title:

Keel Mission Request: Add Keel Mission Request Feature

Body sections:

• Summary
• Problem
• Desired Outcome
• Constraints
• Requested Scope / In Scope
• Requested Scope / Out Of Scope

The important rule is not GitHub itself. The important rule is that the request becomes a canonical envelope before it touches planning state.

The command boundary

The documented direction is a native keel mission request ... namespace with stages like:

• template
• parse
• validate
• draft
• apply
• ack

That is a contract for external composition, not the required day-one workflow for ordinary repo use.

Until that namespace ships, the same architectural rule still applies:

• normalize the external request first
• preserve provider identity and revision metadata
• validate before mutating planning state
• lower into ordinary Keel planning commands
• keep acknowledgement rendering separate from provider delivery

The stabilized IO and failure rules are:

• required caller fields are the planning payload itself, not provider-only IDs
• provider identity and revision metadata are derivable after normalization
• template, parse, validate, draft, and ack stay side-effect free
• apply is the only stage allowed to mutate .keel
• validation failures are recoverable request errors
• execution failures are runtime or policy failures after a request already passed validation

The replay and acknowledgement rules are:

• provider runtimes bind requests to explicit source identity and revision
• duplicate deliveries for the same revision do not replay planning mutations
• edited requests produce a new normalized revision and a fresh Keel evaluation
• Keeper owns provider-facing acknowledgement delivery and retries
• Keel owns acknowledgement payload rendering from the normalized request and planning result

Mission stacks after ingress

Mission requests explain how work enters another board. They do not, by themselves, define how execution should continue when one outcome spans multiple repositories.

That follow-on coordination lives in the Mission Stack contract.

A Mission Stack is a federation of independent Keel boards:

• each member repository keeps its own Keel board
• each member reactor remains authoritative for its own planning state
• one reactor may act as the stack steward for coordination
• one repo does not write another repo's .keel directory directly
• cross-repo work starts with a mission request and reactor negotiation
• the target reactor materializes its own local mission lineage after negotiation instead of accepting external board mutation

Mission Stack also introduces explicit flow-control modes:

• exclusive(<repo>)
• shared([repos...])
• checkpoint(<name>, required_members...)

Those modes tell a reactor whether it may continue locally, yield to another member, or stop at an integration gate.

The branch and handoff rules are:

• every stack member uses branch stack/<id>
• commit is still the local closure boundary inside a repo
• push is the inter-reactor handoff boundary between repos
• the first pushed receipt can stay git-native: stack id, repo identity, branch, head sha, and optional checkpoint or role context

The coordination sequence is:

1. local work proceeds inside the current member repo
2. commit seals the local result
3. push publishes stack/<id>
4. the pushed receipt tells the next reactor exactly which stack state to fetch
5. the target reactor negotiates and materializes its own local mission lineage
6. acknowledgment or integration closes the handoff and yields to the next stack mode boundary

Foreign execution uses managed worktrees

If a reactor needs to execute work inside another stack member repository from the outside, it should not run in that member repo's primary checkout.

The required contract is:

• outside execution uses a managed git worktree
• that worktree targets stack/<id> or an approved stack-derived head
• create, reuse, inspection, and cleanup behavior belong to the stack lifecycle
• managed foreign worktrees are garbage-collected when the stack closes
• ambiguous leftovers are reported instead of being deleted silently

This keeps local ownership and cross-repo traceability legible at the same time.

Multiplayer security without a hard backend dependency

Keel's documented multiplayer security model is boundary-focused, not consensus-heavy.

The important ideas are:

• Keel remains backend-agnostic
• Transit may be a strong backend, but it is optional
• stronger auditability should come from append-only checkpoints plus inclusion and consistency proofs
• threshold attestation belongs on high-consequence transitions and published checkpoints, not on every local move
• private provider or connector payloads should stay at the runtime boundary, not leak into public planning artifacts

This keeps the single-repo local workflow simple while still giving multiplayer deployments a stronger contract to build on.

What changes for normal single-repo use?

Usually, nothing.

If you are working directly in a repo:

• keep using the ordinary planning commands
• keep treating Keel as the source of truth for board state
• think of mission requests and Keeper as the external boundary, not the center of the day-one experience

This page exists so teams can scale outward without changing the core rule: planning truth stays in Keel.