Operator Guide

This guide is for people and agents maintaining a Slipway workspace.

State Authority

Path	Role	Git policy
.slipway.yaml	Repository-local Slipway configuration.	Commit when project defaults change.
artifacts/changes/<slug>/change.yaml	Current lifecycle and routing authority for an active change. Archived snapshots stay in the owning workspace, omit machine-local worktree_path, and use archive-local artifact paths.	Trackable project record.
artifacts/changes/<slug>/*.md	Intent, research, requirements, decisions, tasks, and assurance.	Trackable project records.
artifacts/changes/<slug>/events/lifecycle.jsonl	Append-only trace for mutating lifecycle events.	Local-only raw proof by default.
artifacts/changes/<slug>/verification/*.yaml	Skill and verification evidence.	Local-only raw proof by default.
artifacts/changes/<slug>/evidence/**	Command, review, run, and governance proof bodies.	Local-only raw proof by default.
artifacts/codebase/**	Advisory codebase maps generated by slipway codebase-map.	Local-only by default.
.worktrees/<slug>	Dedicated governed worktree checkout.	Local-only by default.

Do not treat events/lifecycle.jsonl as a replacement for change.yaml. It is audit evidence only. slipway init, slipway new, and slipway codebase-map maintain the Slipway local-state .gitignore block idempotently.

Worktrees

Governed work may be bound to a dedicated worktree under .worktrees/<slug>. Use the worktree that owns the active governed diff:

git status --short --branch
go run . status --json

Avoid deciding readiness from main...HEAD alone. Pair branch comparisons with direct worktree status and diff checks. After slipway done, Git-safe archived records remain in the owning worktree; commit or merge them before removing that worktree.

Health And Repair

Inspect before mutating:

slipway health --doctor --json
slipway validate --json
slipway status --json

Run repair only when the doctor output matches the observed issue:

slipway repair --json

Repair is intended for bounded local integrity issues such as stale locks, interrupted archives, corrupt config, or repairable layout drift.

Verification Stack

Use targeted checks while implementing:

go test ./internal/stringutil ./internal/engine/progression ./internal/engine/governance -run 'TestHasBlockingOpenQuestions|TestAdvanceIntake_OpenQuestionsUseResolvedItemSemantics|TestTraceability.*OpenQuestions' -count=1

Use the full proof before closeout:

go test -timeout=20m ./... -count=1
go build ./...
go vet ./...
mkdocs build --strict

Run docs build only when MkDocs dependencies are available locally. CI installs MkDocs dependencies for docs verification.

Adapter Refresh

Refresh generated AI-tool surfaces after changing templates or command contracts:

slipway init --tools all --refresh

Check generated path changes before committing. Codex prompt files may be written outside the project under $CODEX_HOME/prompts.

Closeout

Before done:

1. Confirm go run . validate --json reports the relevant gates approved.
2. Confirm task evidence is fresh for the current run version.
3. Confirm git diff --check.
4. Stage intended files only.
5. Confirm git diff --cached --check.
6. Run slipway done --json when the change is done-ready.