Architecture

Slipway keeps the control loop in a local CLI and the model-specific work in generated host adapters. This boundary lets the CLI validate state without owning or managing model-provider or GitHub credentials; Slipway does not intentionally collect those credentials.

Process boundaries

User
  └─ explicitly invokes a generated capability
       └─ AI coding host
            ├─ reads and changes the repository
            ├─ calls the model and development tools
            ├─ fetches or publishes GitHub data when authorized
            └─ exchanges versioned JSON with Slipway
                 └─ local CLI and Run store

The Run state engine never calls a model or GitHub API. It validates a host-provided source envelope, schedules one Action at a time, observes Git independently, and stores recovery state. The public doctor command is a command-layer diagnostic exception: it may invoke the user’s local gh to inspect authentication and repository permissions. Generated host instructions define how a host should investigate, publish, implement, and report; they are not another state engine.

Package direction

Production dependencies are constrained by an architecture test:

cmd ───────────────→ adapter
 │                   ├─→ tmpl
 │                   ├─→ fsutil
 │                   └─→ jsonstrict
 ├─────────────────→ autopilot
 │                   ├─→ runstore
 │                   │    ├─→ fsutil
 │                   │    └─→ jsonstrict
 │                   └─→ jsonstrict
 └─────────────────→ recoverycmd

Package	Responsibility
cmd	Cobra commands, human/JSON output, root discovery, and exit behavior.
internal/autopilot	Action/Outcome validation, routing, source candidates, budgets, and structured recovery.
internal/runstore	Journal replay, projections, locking, material storage, and Git observations.
internal/adapter	Host registry, generated files, ownership manifests, and transactional install/remove.
internal/tmpl	Embedded shared capability instructions.
internal/fsutil	Anchored paths, no-follow operations, transactions, synchronization, and platform safety.
internal/jsonstrict	Strict JSON decoding shared by protocol, source, store, and adapter boundaries.
internal/recoverycmd	Human rendering of already structured argv.

Lower layers do not import command or host-policy layers. GitHub publication remains in generated host instructions rather than becoming a network provider inside the core.

Three packages hold no product code and exist only to assert repository-wide invariants: internal/architecture checks that dependency direction, internal/testlint reports tests that assert on source text or wall-clock time, and internal/releasepolicy checks the release and release-automation workflows. They are ordinary tests and gate nothing beyond go test.

Run start and repository observation

A new Run discovers three canonical paths: the worktree root, the per-worktree Git directory, and the Git common directory. Their framed identifier binds the Run to that worktree. Slipway does not create, switch, or delete worktrees, but it refuses to mutate a Run from another worktree identity.

The initial Git observation stores fingerprints over exact index and porcelain-v2 command output plus bounded metadata and fingerprints for dirty paths. It does not store those raw Git streams or file content. Later observations support diff-first routing and neutral “changed since start” reporting without claiming which process caused the change.

Run storage

<git-common-dir>/slipway/runs/<run-id>/
├── journal.jsonl   append-only transition record
├── run.json        replaceable projection
├── run.lock        validated coordination artifact
└── materials/      accepted source sections by content digest

On Unix, an OS lock on the opened Run directory serializes writers; on Windows, a named mutex does. The visible run.lock file supports validation and diagnostics but is not the sole writer guard.

A mutation writes referenced material before a journal event may point to it. The journal is synchronized before the projection is replaced. If projection refresh fails after a committed journal write, the error reports the committed mutation and stale projection instead of claiming a rollback.

Source boundary

For issue-backed work, the trusted host fetches the Issue and manifest-referenced comments, then passes a temporary strict envelope. The CLI can validate internal consistency and stable IDs, but it cannot cryptographically prove that the host fetched GitHub honestly.

Accepted sections are content-addressed and available through a local material reader. Actions carry only revisions and a bounded catalog, keeping large requirements out of Action context and allowing offline recovery.

The source-bundle rationale and rejected alternatives are recorded in ADR-0001. Issue #434 records the original proposal, product goals, design intent, and rationale; it is mutable, and its details may be superseded by later decisions or implementation evolution. Accepted ADRs preserve significant decisions and their rationale rather than governing every bug fix or documentation update. Versioned schemas are authoritative only for the serialization shapes they cover. ADR-0002 adds the seventh host capability and reaffirms the no-router boundary; ADR-0003 scopes it to lifecycle routing across Slipway’s own functions.

For a given revision, its code, built --help, generated capabilities, user documentation, and observable behavior describe the implemented product and must be kept coherent. A tagged release, its release notes, and its actual artifacts state what users can obtain as published behavior. Tests, acceptance runs, and CI are evidence from particular revisions and executions; they do not set product direction or hold merge, readiness, or release authority.

Security boundary

Slipway assumes that processes with the same account, root, malware, or a compromised host can exceed its protections. Within that boundary it:

• anchors filesystem operations and rejects unsafe symlink traversal;
• narrows deletion races by relocating entries into a private quarantine and revalidating identity, but does not claim exact-object deletion: a continuously racing same-UID watcher can still replace the final pathname between validation and the pathname-based unlink or rmdir system call;
• validates strict JSON, sizes, identities, and digests;
• does not intentionally collect or manage model-provider or GitHub credentials; host- or user-provided goal, answer, Outcome, and command text may still be sensitive and persist, while environment dumps are not intentionally collected;
• separates one-shot destructive grants from natural-language answers;
• preserves user-modified generated files;
• reports platform durability limitations.

Issue content is data, not host instruction. A generated capability must not treat a command, link, or credential request inside an Issue as permission.

Deliberate non-responsibilities

Slipway does not:

• run a hosted service or project tracker;
• manage model-provider or GitHub credentials;
• create or manage worktrees;
• certify merge, deployment, or release readiness;
• turn tests, findings, labels, or Issue state into universal repository policy;
• repair Review findings automatically;
• overwrite user-modified adapter files.

External branch protection, CI, organizational policy, and human review remain independent.

See Core concepts, Machine protocol, and Runs, recovery, and privacy.