opencode-ship 1.1.2-rc.1 → 1.1.2-rc.4

package/CHANGELOG.md

@@ -2,54 +2,149 @@
 
 All notable changes to `opencode-ship` are recorded here.
 
-## 1.1.2-rc.1 — Complete contract correction
+## 1.1.2-rc.4 — Plan Mode write access
+
+> Branch: `release/1.1.2-rc.4`.
+
+- **Plan Mode write access for brainstorming / writing-plans products.**
+  The installer now owns two leaf pointers under
+  `agent.plan.permission` so OpenCode's Plan mode can write its
+  brainstorming / writing-plans / wayfinder output:
+
+  - `/agent/plan/permission/edit/docs/superpowers/**` = `allow`
+  - `/agent/plan/permission/edit/.git/opencode-ship/plans/**` = `allow`
+
+  The whole `/agent/plan/permission` block is still consumer-owned;
+  the installer only owns these two glob leaves. When the consumer
+  previously declared `agent.plan.permission.edit` as a scalar
+  string (e.g. `"deny"`), the installer promotes it to
+  `{ "*": <scalar>, ... }` on install and records the previous
+  scalar so uninstall can restore it byte-for-byte. A consumer
+  that explicitly sets `docs/superpowers/**: "deny"` is a
+  fail-closed conflict.
+
+## 1.1.2-rc.3 — Complete contract correction (round 2)
+
+> Branch: `fix/1.1.2-rc.3-contract`.
+> Tracker: https://github.com/Viktorxyz/opencode-ship/issues/56.
+
+`1.1.2-rc.2` shipped green CI but its CHANGELOG claimed more than the
+codebase delivered: the B2 dispatch work stayed on an unmerged branch,
+the B4 matrix was wired but the per-leaf pointer records were not
+written by `init`, the B5 setup-complete command cleared the
+setup-pending marker BEFORE validating the artifacts (so a failed
+validation lost the marker with no compensating lock write), and the
+B7 trusted-skill install wrote a placeholder `SKILL.md` whose hash
+matched the inventory by construction.
+
+This release corrects those gaps and ships only what is true at the
+byte level:
+
+- **`ship_skill_install`** materialises real bytes via the public
+  `skills` CLI pinned to a known version, copies them through a
+  staging directory, hashes every installed file, and verifies the
+  on-disk bytes match the staged bytes before appending to the
+  inventory. The tool fails closed when the CLI is unavailable; no
+  placeholder `SKILL.md` is ever written.
+- The inventory is now append-only schema v2 with a hash-chained
+  event log. Install events carry per-file sha256 + provenance
+  (registry snapshot, cli package, registryId); uninstall events
+  append a tombstone that references the install hash and never
+  splices the chain.
+- `ship_skill_install` validates the destination worktree via
+  `git worktree list --porcelain -z`. It refuses the main checkout,
+  unregistered paths, symlink traversal, and any destination whose
+  ancestor is a symlink. Paths that lexically contain `..` or
+  absolute segments are refused at append time.
+- The root permission matrix is the single source of truth.
+  `desiredPointersForProfile("engineering")` derives its pointer
+  list from `rootPermissionMatrix()` (no parallel `POINTER_ENTRIES`
+  list); the wildcard `*` default is never serialised as a literal
+  pointer, and bash policy is left to the OpenCode runtime instead
+  of being installer-owned state. Empty intermediate containers
+  (`agent.<name>.permission: {}`) are pruned on install/uninstall so
+  byte-identical restoration holds for empty consumer configs.
+- `setup-complete` validates lock, models, docs, and AGENTS.md
+  BEFORE any writes. The setup-pending marker is no longer part of
+  the gate (it is a chat-time signal, not an artifact). When the
+  gate passes, the lock is written with `setupComplete: true` and
+  the marker is cleared as part of the same commit. When validation
+  fails, no state changes.
+- The 32-tool public surface is unchanged. The eight new tools
+  (`ship_task_start`, `ship_task_commit`, `ship_task_complete`,
+  `ship_final_review`, `ship_skill_discover`, `ship_skill_install`,
+  `ship_skill_audit`, `ship_skill_uninstall`) are still first-class.
+- Regressions covered by new test suites: `tests/skills/install.test.mjs`,
+  `tests/skills/inventory.test.mjs`, `tests/skills/worktree.test.mjs`,
+  `tests/installer/root-permission-matrix.test.mjs`,
+  `tests/installer/setup-pending.test.mjs` (extended).
+
+## 1.1.2-rc.2 — Rejected, incomplete
+
+`1.1.2-rc.2` is published on npm `next` but is rejected as an
+incomplete candidate. The CHANGELOG for that release claimed
+behavior the source tree did not contain: the B2 dispatch work
+lived only on the unmerged branch `fix/1.1.2-rc.2-contract`, the
+root permission matrix was dead-code (POINTER_ENTRIES was the
+active source), the setup-complete command cleared the marker
+before validating, and `ship_skill_install` wrote a placeholder
+`SKILL.md` whose hash matched the inventory by construction. The
+published `1.1.2-rc.2` tarball is byte-equivalent to this rejected
+release.
 
 > Active stabilization branch: `fix/1.1.2-self-hosting`.
 > Parent tracker: https://github.com/Viktorxyz/opencode-ship/issues/56.
+> Authoritative plan: docs/release/1.1.2-correction-plan.md.
 
-`1.1.1` shipped a partial contract: 24 of the 32 promised tools, an
-executor that conflated "all three model fields populated" with
-"setup workflow completed", a setup skill that left consumers
-without `docs/agents/**` or an `AGENTS.md` Ship workflow block, and
-root permissions that still used the legacy 11-pointer list with
-no controller delegation.
+`1.1.1` and `1.1.2-rc.1` shipped partial contracts: 24 of the 32
+promised tools, no real OpenCode dispatch, an executor that conflated
+"all three model fields populated" with "setup workflow completed",
+a setup skill that left consumers without `docs/agents/**` or an
+`AGENTS.md` Ship workflow block, and root permissions that still used
+a duplicated pointer list.
 
 This release corrects every one of those gaps:
 
 - 32 typed tools are registered. The previously missing
   `ship_task_start`, `ship_task_commit`, `ship_task_complete`,
   `ship_final_review`, `ship_skill_discover`, `ship_skill_install`,
-  `ship_skill_audit`, and `ship_skill_uninstall` are now first-class.
+  `ship_skill_audit`, and `ship_skill_uninstall` are first-class.
+- The workflow agents are dispatched through real OpenCode
+  sessions via `client.session.create` and `client.session.promptAsync`.
+  The controller session id is persisted in dispatch records so
+  plan/task/final-review tools can authorize the caller from the
+  ToolContext, not from a caller-supplied `submittedBy` string.
 - `ship_task_review` authorizes against the configured builder
-  model (the task reviewer is rendered with the builder model),
-  not the final reviewer. The factory now passes the config so
-  the tool can resolve model roles.
-- New `opencode-ship setup-complete` command is the sole writer
-  of `lock.manager.setupComplete: true`. The lock flip requires
-  all three model roles populated AND the install-owned docs
-  (`docs/agents/{issue-tracker,domain,triage-labels}.md`) AND
-  the `AGENTS.md` "Ship workflow" block AND the setup-pending
-  marker absent. The five predicates are deterministic from
-  on-disk artifacts.
-- `update` no longer auto-clears the setup-pending marker.
-  Marker removal is exclusively the setup-complete command's
-  responsibility.
-- Executor refuses to set `setupComplete: true` on `init` or
-  `update`; the flag is only ever passed through
-  `commitInstall(..., { fullSetupComplete: true })`.
-- Doctor reports setup-complete state as informational so
-  already-installed neutral consumers do not regress.
-- Root permission matrix wires `subagent_depth: 2` and the
-  Build → ship-controller delegation. The legacy 11-pointer
-  list is augmented with the depth and delegation surfaces.
-- Lock schema v4 (`schema/ship-lock.schema.json`) now accepts
-  `manager.setupComplete` and the `support` file kind, and
-  explicitly drops `cleanupPending` (it lives under the Git
-  common directory).
-- New `src/skills/{policy,registry,inventory}.js` modules
-  back the four `ship_skill_*` tools. The inventory is
-  hash-chained and recorded in `.opencode/ship.skills.lock.json`
-  under the consumer repo.
+  model (the task reviewer is rendered with the builder model).
+  `ship_final_review` requires the configured finalReviewer model.
+  Both gate on the controller session id.
+- The setup-complete command is the sole writer of
+  `lock.manager.setupComplete: true`. It validates models + docs +
+  AGENTS.md + lock BEFORE the lock write, then removes the
+  setup-pending marker in the same critical section. A failed
+  validation leaves the marker untouched.
+- The root permission matrix is the single source of truth. The
+  legacy `POINTER_ENTRIES` list is replaced by `rootPermissionMatrix()`.
+  `subagent_depth: 2` and the Build → ship-controller delegation
+  are wired so the deep plan / build / review chain works without
+  manual permission patching.
+- JSONC reads and writes use `jsonc-parser`. The apply step merges
+  sibling section insertions into a single JSONC edit insert so the
+  `applyEdits` call does not throw on overlapping ranges. Plain
+  JSON files are preserved key-by-key by the same matrix.
+- The `setup-ship-workflow` skill is GitHub-only. The 1.1.2
+  controller's delivery tool belt is GitHub-bound; the skill
+  refuses to drive GitLab, Jira, Linear, or local markdown.
+  The command is a thin wrapper that just invokes the skill.
+- Lock schema v4 explicitly accepts `manager.setupComplete` and
+  the `support` file kind, and drops `cleanupPending` (its state
+  lives under the Git common directory).
+
+## 1.1.2-rc.1 — (incomplete) placeholder
+
+The 1.1.2-rc.1 release shipped with a partial contract and is
+deprecated as soon as 1.1.2 stable is published. Upgrade to
+1.1.2-rc.2 or later.
 
 ## 1.1.1 — Stabilization + first self-hosting release (UNRELEASED)
 

package/README.md

@@ -2,7 +2,7 @@
 
 > npm-distributed OpenCode installer and delivery plugin: a single command materialises the lifecycle plugin, reviewer/verifier agents, and skills into any consumer repository, with a recoverable lock and never silently overwrites managed files.
 >
-> **Status:** `1.1.0` is on `npm dist-tag latest`. The `1.1.x` stabilization line (parent issue #40) is in progress on the `fix/1.1.1-stabilization` branch. When `1.1.1` ships it becomes the first self-hosting release and `1.1.0` is deprecated. The `release/1.1.0-engineering-only` branch ships the engineering profile directly without a separate `core` profile. The `1.1.0` tag is immutable; consumers should use `opencode-ship@1.1.0` today and switch to `opencode-ship@1.1.1` once it is promoted to `latest`. See `docs/release/1.1.1-stabilization-plan.md` for the authoritative plan and issue #40 for the bounded evidence ledger.
+> **Status:** `1.1.1` is on `npm dist-tag latest`. The `1.1.2` stabilization line is in progress on the `release/1.1.2-rc.4` branch of the `1.1.2 stabilization`. `1.1.2-rc.1`, `1.1.2-rc.2`, and `1.1.2-rc.3` are published on `next` but are rejected, incomplete candidates; the next candidate is `1.1.2-rc.4`, adding the Plan Mode write access required by the brainstorming / writing-plans / wayfinder skills. Once `1.1.2` ships it becomes the first fully self-hosting release and `1.1.1` is deprecated. The `1.1.0` tag is immutable. See `docs/release/1.1.2-correction-plan.md` for the authoritative plan and issue #56 for the bounded evidence ledger.
 >
 > Consumers should use `opencode-ship@1.1.0` (or `@latest`) until `1.1.1` ships. The previous `1.0.0` is on `next`; consumers who pinned to `1.0.x` will continue to receive updates on that channel.
 
@@ -145,7 +145,7 @@ Existing consumers of `opencode-delivery@0.1.x` (commit-pinned shim) can run `pn
 
 ## Development
 
-`npm run verify` runs `format:check`, `lint`, `typecheck`, `build`, and the auto-discovered test suite. The tests cover the installer CLI, the lock and root-config planners, the catalog validator, the schema validator, agents, the packed-artifact smoke check, the transaction-recovery contract, the profile-resolution precedence chain, the catalog profile filter, the order-preserving root-config merge, the engineering↔core transition, the durable plan artifact, the Plan Mode permission integration, the M3 task loop contract (run store + task brief + Spec/Quality verdicts + 3-round breaker + commit binding + compaction context), the Ready gate (parallel GPT Standards/Spec + verifier + CI on one HEAD; Build cannot self-record), the transition matrix smoke (core omits engineering, engineering adds engineering, lock tracks the active profile), the static release-policy tests (Node matrix wiring, prerelease metadata, runtime-source digest wiring, 1.0 promotion policy), the runtime-source digest algorithm tests (deterministic across clean checkouts; ignores version and release-metadata changes; tracks every runtime-source modification), and the OpenCode live-server discovery smoke (24-tool canonical set exposed via `/experimental/tool/ids` on a real `opencode serve` instance for both `core` and `engineering` profiles). The suite count and per-test count are derived from the test runner at qualification time; this README intentionally does not lock in a specific test-count baseline.
+`npm run verify` runs `format:check`, `lint`, `typecheck`, `build`, and the auto-discovered test suite. The tests cover the installer CLI, the lock and root-config planners, the catalog validator, the schema validator, agents, the packed-artifact smoke check, the transaction-recovery contract, the profile-resolution precedence chain, the catalog profile filter, the order-preserving root-config merge, the engineering↔core transition, the durable plan artifact, the Plan Mode permission integration, the M3 task loop contract (run store + task brief + Spec/Quality verdicts + 3-round breaker + commit binding + compaction context), the Ready gate (parallel GPT Standards/Spec + verifier + CI on one HEAD; Build cannot self-record), the transition matrix smoke (core omits engineering, engineering adds engineering, lock tracks the active profile), the static release-policy tests (Node matrix wiring, prerelease metadata, runtime-source digest wiring, 1.0 promotion policy), the runtime-source digest algorithm tests (deterministic across clean checkouts; ignores version and release-metadata changes; tracks every runtime-source modification), and the OpenCode live-server discovery smoke (32-tool canonical set exposed via `/experimental/tool/ids` on a real `opencode serve` instance for both `core` and `engineering` fixtures). The suite count and per-test count are derived from the test runner at qualification time; this README intentionally does not lock in a specific test-count baseline.
 
 ```
 npm ci

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices
 
-`opencode-ship@1.1.2-rc.1` ships the complete Matt Pocock and Superpowers
+`opencode-ship@1.1.2-rc.4` ships the complete Matt Pocock and Superpowers
 methodology under the MIT license, plus the Ship-owned installer,
 plugin, agents, and skills. The complete immutable pin list is in
 `vendor/sources.json`; the upstream snapshots are under

package/assets/agents/delivery-reviewer.md

@@ -4,6 +4,7 @@ mode: subagent
 temperature: 0.2
 steps: 8
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny

package/assets/agents/delivery-verifier.md

@@ -4,6 +4,7 @@ mode: subagent
 temperature: 0.1
 steps: 8
 permission:
+  "*": deny
   edit: deny
   bash: deny
   external_directory: deny

package/assets/agents/ship-controller.md

@@ -5,6 +5,7 @@ temperature: 0.1
 model: <model-from-config>
 steps: 12
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny
@@ -53,34 +54,46 @@ permission:
     "pnpm test *": allow
     "pnpm run verify *": allow
   task:
-    "*": allow
+    "*": deny
+    ship-planner: allow
+    ship-task-builder: allow
+    ship-task-reviewer: allow
+    ship-final-standards-reviewer: allow
+    ship-final-spec-reviewer: allow
+    delivery-verifier: allow
   delivery_inspect: allow
   delivery_issue: allow
   delivery_worktree: allow
-  delivery_verify: allow
+  delivery_verify: deny
   delivery_review: deny
   delivery_pr: allow
   delivery_ready: allow
-  delivery_merge: deny
+  delivery_merge: ask
   delivery_cleanup: allow
   delivery_github_read: allow
   delivery_issue_comment: allow
   delivery_issue_labels: allow
   delivery_issue_link: allow
-  delivery_issue_close: deny
+  delivery_issue_close: ask
   delivery_sync: allow
-  delivery_publish: deny
+  delivery_publish: allow
   ship_plan_start: allow
-  ship_plan_submit: allow
-  ship_plan_approve: deny
+  ship_plan_submit: deny
+  ship_plan_approve: ask
   ship_run_start: allow
+  ship_task_start: allow
+  ship_task_commit: allow
+  ship_task_complete: allow
   ship_task_report: deny
   ship_task_review: deny
+  ship_final_review: deny
   ship_resume: allow
   ship_status: allow
   ship_deliver: allow
   ship_skill_discover: allow
   ship_skill_install: allow
+  ship_skill_audit: allow
+  ship_skill_uninstall: allow
 ---
 
 # ship-controller

package/assets/agents/ship-final-spec-reviewer.md

@@ -1,10 +1,11 @@
 ---
-description: Strong Spec final reviewer. Records the Spec axis of the final review through `delivery_review` with `axis: spec`. Independent of the Standards reviewer and the controller.
+description: Strong Spec final reviewer. Records the Spec axis through `ship_final_review`. Independent of the Standards reviewer and the controller.
 mode: subagent
 temperature: 0.2
 model: <model-from-config>
 steps: 10
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny
@@ -26,7 +27,7 @@ permission:
   delivery_issue: deny
   delivery_worktree: deny
   delivery_verify: deny
-  delivery_review: allow
+  delivery_review: deny
   delivery_pr: deny
   delivery_ready: deny
   delivery_merge: deny
@@ -37,6 +38,7 @@ permission:
   ship_run_start: deny
   ship_task_report: deny
   ship_task_review: deny
+  ship_final_review: allow
   ship_resume: deny
   ship_status: deny
   ship_deliver: deny
@@ -70,7 +72,7 @@ refuses to mark Ready if either axis is missing or fails.
 2. Score the Spec axis against the contract above. Every
    acceptance criterion the plan promised must be
    demonstrable from the final HEAD.
-3. Call `delivery_review` exactly once with
+3. Call `ship_final_review` exactly once with
    `axis: "spec"`, the merge-base SHA, the HEAD SHA, the
    package hash, and a single verdict. The verdict is
    `pass` only when every Spec criterion is met; any

package/assets/agents/ship-final-standards-reviewer.md

@@ -1,10 +1,11 @@
 ---
-description: Strong Standards final reviewer. Records the Standards axis of the final review through `delivery_review` with `axis: standards`. Independent of the Spec reviewer and the controller.
+description: Strong Standards final reviewer. Records the Standards axis through `ship_final_review`. Independent of the Spec reviewer and the controller.
 mode: subagent
 temperature: 0.2
 model: <model-from-config>
 steps: 10
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny
@@ -26,7 +27,7 @@ permission:
   delivery_issue: deny
   delivery_worktree: deny
   delivery_verify: deny
-  delivery_review: allow
+  delivery_review: deny
   delivery_pr: deny
   delivery_ready: deny
   delivery_merge: deny
@@ -37,6 +38,7 @@ permission:
   ship_run_start: deny
   ship_task_report: deny
   ship_task_review: deny
+  ship_final_review: allow
   ship_resume: deny
   ship_status: deny
   ship_deliver: deny
@@ -66,7 +68,7 @@ to mark Ready if either axis is missing or fails.
    you. The package includes the task-by-task commits, the
    verification report, the CI report, and the manifest.
 2. Score the Standards axis against the contract above.
-3. Call `delivery_review` exactly once with
+3. Call `ship_final_review` exactly once with
    `axis: "standards"`, the merge-base SHA, the HEAD SHA,
    the package hash, and a single verdict. The verdict is
    `pass` only when every Standards criterion is met; any

package/assets/agents/ship-planner.md

@@ -5,6 +5,7 @@ temperature: 0.3
 model: <model-from-config>
 steps: 10
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny

package/assets/agents/ship-task-builder.md

@@ -5,6 +5,7 @@ temperature: 0.2
 model: <model-from-config>
 steps: 8
 permission:
+  "*": deny
   edit: allow
   external_directory: deny
   webfetch: deny

package/assets/agents/ship-task-reviewer.md

@@ -5,6 +5,7 @@ temperature: 0.2
 model: <model-from-config>
 steps: 8
 permission:
+  "*": deny
   edit: deny
   external_directory: deny
   webfetch: deny

package/assets/commands/setup-ship-workflow.md

@@ -1,173 +1,15 @@
 ---
-description: Configure the opencode-ship workflow for this repo: issue tracker, triage labels, domain docs, and AI model roles. Run once after `init` with /setup-ship-workflow.
+description: Configure the opencode-ship workflow for this repo: GitHub tracker, triage labels, domain docs, and AI model roles. Run once after `init` with /setup-ship-workflow.
 ---
 
 # Setup Ship Workflow
 
-First-run setup for `opencode-ship@1.1`. Run this exactly once after `init` and before any `ship-deliver`. It is prompt-driven, idempotent, and refuses to return until every step is committed or explicitly skipped.
+This command is a thin wrapper around the canonical
+`setup-ship-workflow` skill. OpenCode will load the skill
+and follow its procedure.
 
-## When you trigger
-
-- The user runs `/setup-ship-workflow` or types "set up ship" / "continue ship setup".
-- The installer creates `.opencode/ship.setup-pending.json` after `init`; the controller also routes `ship-deliver` here until this skill has cleared the marker.
-
-Do **not** trigger on a normal planning or delivery request.
-
-## Process
-
-Take the sections in order. Lead every question with a recommended default so the user can accept in one word. Skip a section only when exploration already settled it.
-
-### 1. Explore
-
-```bash
-git remote -v
-git status --short
-ls -la AGENTS.md CLAUDE.md docs/ .opencode/ 2>/dev/null || true
-cat .opencode/opencode.json 2>/dev/null || true
-cat .opencode/ship.config.json 2>/dev/null || true
-cat .opencode/ship.lock.json 2>/dev/null || true
-cat .opencode/ship.setup-pending.json 2>/dev/null || true
-opencode providers list 2>/dev/null || true
-```
-
-Also check:
-
-- is `.opencode/ship.setup-pending.json` present? (it makes this run mandatory)
-- is the `triage` skill installed? (decides whether Section B runs)
-- monorepo signals (`pnpm-workspace.yaml`, `packages/*`)
-
-### 2. Section A — Issue tracker
-
-Default: GitHub (the most common case). If `git remote` points at GitLab, propose GitLab. Otherwise offer:
-
-- GitHub (uses `gh`)
-- GitLab (uses `glab`)
-- Local markdown (writes under `.scratch/<feature>/`)
-- Other (Jira, Linear, etc.) — describe in one paragraph
-
-Write the choice to `docs/agents/issue-tracker.md`. Use the seed template in `assets/skills/setup-engineering-workflow/issue-tracker-<choice>.md` as the starting point.
-
-### 3. Section B — Triage labels
-
-Only if the `triage` skill is installed. Ask one question:
-
-> Keep the default triage labels? (recommended: yes)
-> Defaults: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`.
-
-On **no**, capture the user's overrides so `triage` reuses existing labels instead of creating duplicates.
-
-Write `docs/agents/triage-labels.md`.
-
-### 4. Section C — Domain docs
-
-Default: **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Skip the question unless monorepo signals were found.
-
-Write `docs/agents/domain.md`.
-
-### 5. Section D — AI model roles
-
-Three questions, one at a time. Default to `openai/gpt-5.6-sol` and `minimax/MiniMax-M3`; offer alternative families below.
-
-| Role | Default | Suggestion |
-|---|---|---|
-| planner | `openai/gpt-5.6-sol` | strong model for plan writing |
-| builder | `minimax/MiniMax-M3` | cheap/fast model for code |
-| finalReviewer | `openai/gpt-5.6-sol` | strong model for final Standards + Spec review |
-
-Alternatives to mention if the user has no OpenAI/MiniMax:
-
-- Anthropic: `anthropic/claude-opus-4.1`, `anthropic/claude-sonnet-4.5`
-- Google: `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
-- Or any `<provider>/<model>` string the user has credentials for
-
-After the user answers, **update `.opencode/ship.config.json`** so it looks like:
-
-```json
-{
-  "schemaVersion": 2,
-  "profile": "engineering",
-  "project": { ... },
-  "delivery": { ... },
-  "workflow": {
-    "models": {
-      "planner": "<answer>",
-      "builder": "<answer>",
-      "finalReviewer": "<answer>"
-    },
-    "approval": { "mirrorToIssue": true, "maxFailedRounds": 3 }
-  }
-}
-```
-
-Then run `opencode-ship update` to write the change with full transactional coverage.
-
-### 6. Section E — Provider auth probe
-
-```bash
-opencode providers list
-```
-
-If the planner/builder/finalReviewer names are missing credentials, surface a warning and tell the user how to log in:
-
-```bash
-opencode providers login openai
-opencode providers login minimax
-```
-
-Do not invent credentials. Do not retry.
-
-### 7. Section F — Permissions sanity
-
-Run `opencode-ship doctor`. If any pointer is missing, prompt the user to run:
-
-```bash
-opencode-ship update --force-root-config
-```
-
-Do not auto-rewrite root configs without consent.
-
-### 8. Section G — AGENTS.md / CLAUDE.md
-
-Pick the file to edit:
-
-- If `CLAUDE.md` exists, edit it.
-- Else if `AGENTS.md` exists, edit it.
-- If neither, ask the user to pick one — never create both.
-
-If an `## Ship workflow` block exists, update in place. Otherwise append:
-
-```markdown
-## Ship workflow
-
-This repo uses opencode-ship. Read `.opencode/ship.config.json` for the active model roles and approval policy. Issues live in [tracker]. See `docs/agents/issue-tracker.md`. Triage labels are documented in `docs/agents/triage-labels.md`.
-
-For a single-issue delivery, the user invokes `/setup-ship-workflow` once, then `ship-deliver <issue-number>` (or types "Ship issue N"). The controller dispatches the planner, builder, and reviewers; no further user action is required until Ready.
-```
-
-Include the `### Triage labels` sub-block only when the `triage` skill is installed.
-
-### 9. Done
-
-- Delete `.opencode/ship.setup-pending.json`.
-- Print the next-step block below.
-- Tell the user they can edit `docs/agents/*.md` directly; re-running this skill is only necessary to switch trackers or re-configure models.
-
-## Next steps (always print)
-
-```text
-Setup complete.
-
-Next:
-1. Restart OpenCode in this repo (if you haven't already).
-2. Try: Ship issue 1    (or any issue number)
-3. The controller will: plan -> ask approve -> implement -> review -> ready -> wait for "merge it"
-```
-
-## Hard rules
-
-- One question per turn. Never batch.
-- Re-run safe: skip sections already settled by existing config or docs.
-- Never edit the same `docs/agents/*.md` twice in one run.
-- Never silently overwrite a user-owned value in `ship.config.json`; always show the diff first.
-- Never tell the user to "merge it" automatically. The merge step is the only autonomy break.
-- Never hide step failures. If a write fails, surface the error and stop.
+To run the skill from this command, the user types
+`/setup-ship-workflow` in OpenCode. The CLI's
+`setup-complete` command is the transactional gate that
+commits the lock flip and clears the marker once the skill
+has produced every artifact.