Boatstack may create these reviewable paths through registered effects:
| Path | Owner | Meaning |
|---|---|---|
.boatstack/project.json |
repository policy | strict Boatstack configuration |
.boatstack/plans/<delivery>.source |
plan effect | exact source plan bytes |
.boatstack/approvals/<delivery>.json |
approval effect | plan-fingerprint and actor receipt |
.boatstack/evidence/<delivery>/*.json |
gate/evidence effects | revision-bound build, test, review, journey, change, or visual evidence |
.boatstack/publication/<delivery>.preview.json |
publication preview | exact base, head, PR body, and preview fingerprint |
These files are evidence inputs. Their presence alone never establishes engagement, authority, completion, or publication.
boatstack flow compile projects a repository-owned .flow.ts source into
committed runtime inputs:
| Path | Owner | Meaning |
|---|---|---|
.boatstack/flows/<program>.flow.ir.json |
Flow compiler | canonical IR plus source, lock, binding, and generated-file hashes |
.agents/skills/<program>-<entry>/.gitattributes |
Flow compiler | preserves exact Codex projection bytes across Git checkouts |
.agents/skills/<program>-<entry>/SKILL.md |
Flow compiler | Codex entry projection |
.agents/skills/<program>-<entry>/agents/openai.yaml |
Flow compiler | Codex skill metadata |
.claude/skills/<program>-<entry>/.gitattributes |
Flow compiler | preserves exact Claude projection bytes across Git checkouts |
.claude/skills/<program>-<entry>/SKILL.md |
Flow compiler | Claude entry projection |
.cursor/commands/.gitattributes |
Flow compiler | shared Cursor checkout-byte policy |
.cursor/commands/<program>-<entry>.md |
Flow compiler | Cursor entry projection |
.gemini/skills/.gitattributes |
Flow compiler | shared Gemini checkout-byte policy |
.gemini/skills/<program>-<entry>/SKILL.md |
Flow compiler | Gemini entry projection |
Skill identities are injective across program and entry pairs: hyphens in the
entry component are doubled. The boatstack-update identity is reserved for
kernel maintenance and cannot be generated by a repository Flow.
boatstack flow check rejects stale sources, dependency locks, trusted
bindings, program fingerprints, or skills. Runtime commands load only the
checked IR artifact; they do not execute the TypeScript source.
Each generated skill directory disables Git text conversion for its owned
files, so a later Windows worktree preserves the canonical artifact bytes.
Compilation also rejects repository module imports, concurrent projection, and
source or lock changes observed through projection commit. It requires an
explicit absolute frontend path, revalidates retirement authorization under the
projection lock, and publishes the artifact only after obsolete skills are
retired. Projection filesystem mutations use a repository-root capability, so
a parent-directory symlink swap cannot redirect them outside the repository.
The kernel maintenance projection uses the reserved boatstack-update identity
at the corresponding host paths: Codex and Claude skill directories, Cursor's
.cursor/commands/boatstack-update.md, and Gemini's
.gemini/skills/boatstack-update/SKILL.md. Selection is explicit. Boatstack
owns only paths recorded by its generated ownership manifests, never an entire
host directory. Manual edits to an owned path are rejected rather than adopted.
Boatstack uses only these canonical roots:
| Context | Root |
|---|---|
| embedded | <git-common>/boatstack |
| explicit state base | <BOATSTACK_STATE_ROOT>/boatstack |
| macOS | ~/Library/Application Support/boatstack |
| XDG | $XDG_STATE_HOME/boatstack |
It does not read or migrate generation-labelled roots. A run authorization record lives under the external repository and Git-common Flow root. It binds entry activation and optional delegation scopes to one run and is protected by its own lock before controller or effect locks.
Embedded worktree state is partitioned under the Git common directory. Detached and hybrid state is partitioned under the platform state directory. Clone-family journals, locks, receipts, and event streams use a repository ID plus Git-common ID, so two clones cannot collide through a first-match alias.
The durable state stores exact repository, Git-common, and worktree identities. Workspace transfer writes both the parked source state and destination state in one staged manifest. Recovery journals are clone-shared so interruption remains discoverable even if a worktree was removed.
All V1 machine state is unsupported and may be deleted. Boatstack never searches for or falls back to it.
The executable transition registry deterministically generates five checked architecture artifacts:
| Artifact | Regeneration command |
|---|---|
docs/architecture/boatstack-transition-catalog.md |
boatstack-helper catalog --format markdown |
docs/architecture/boatstack-transition-catalog.mmd |
boatstack-helper catalog --format mermaid |
docs/architecture/boatstack-standard-flow.mmd |
boatstack-helper catalog --format standard-flow-mermaid |
docs/architecture/boatstack-locus-safety.json |
boatstack-helper catalog --format locus-safety |
docs/architecture/boatstack-locus-liveness.json |
boatstack-helper catalog --format locus-liveness |
Repository and Go tests compare every checked byte with a fresh render and require both Locus alphabets to equal all 63 executable catalog transitions. The StandardFlow graph contains exactly the 30 transitions whose compiled origin is the program runtime. The Locus phase graph is intentionally conservative: it expands each declared source phase against each declared target phase. Facet predicates and reducer branches remain executable-test obligations.
Manual edits are not allowed. The generator is the compiled software-delivery
registry exposed by boatstack-helper catalog; the repository contract and
boatstack/internal/softwaredelivery/surfaces/artifacts_external_test.go are
the verifiers.