opencode-ship 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to `opencode-ship` are recorded here.
 
+## 0.6.0 — Durable plan artifact + Plan Mode integration
+
+`opencode-ship@0.6.0` ships the durable plan artifact and the Plan Mode permission integration required by issue #21. The runtime now supports the GPT-to-MiniMax handoff end-to-end: a planning sub-agent can write a hash-verified plan to `.git/opencode-ship/plans/<slug>/revision-NNNN.json`, mirror it to the parent issue as a marked comment, and run with a deny-first, narrow-allow permission block that prevents it from touching source/config/docs.
+
+### Verification
+
+- `npm run verify` exits `0` with 283 tests across 34 suites on the v0.6 HEAD.
+
+### Added
+
+- **Plan artifact.** `src/installer/plan.js` declares the plan schema (version, revision, parentIssue, baseSha, architecture, global constraints, file responsibilities, ordered tasks with interfaces / testSeams / commands / expectedEvidence, acceptance, out of scope, recovery). `validatePlan` is fail-closed; `computePlanHash` produces a stable SHA-256 over the canonical content; `canRevise` enforces the append-only N+1 rule; `planNeedsPlaceholderReview` flags any `<placeholder>` marker so a final-reviewer can refuse approval.
+- **Plan persistence.** `src/installer/plan-store.js` writes, reads, and lists plan revisions under `.git/opencode-ship/plans/<planSlug>/revision-NNNN.json`. The store refuses to overwrite or skip revisions.
+- **Plan issue mirror.** `src/installer/plan-mirror.js` posts the approved plan to the parent issue as a marked comment with the stable `opencode-ship-execution-handoff:v1` marker, the plan hash, and the revision. Retries with linear backoff. The client is injectable so tests run without `gh`.
+- **Engineering config.** `src/installer/engineering-config.js` validates the user config (`models.{planner,builder,finalReviewer}` and `plans.{root,mirrorToIssue}`) and resolves model roles with documented defaults. Strict mode throws on missing roles.
+- **Plan Mode permission block.** `src/installer/plan-mode-permissions.js` produces the deny-first, narrow-allow permission set documented in the approved plan: bash / webfetch / task.plan-agent / task.build-agent deny, edit / write allow only `.git/opencode-ship/plans/**`.
+- **OpenCode config integration.** `src/installer/root-config.js` gains `applyPlanModeOwnership` which injects the Plan Mode block under `agent.plan.permission` on the consumer's `opencode.json` when the active profile is `engineering`. Captures the previous value so uninstall can restore it.
+- **Executor wiring.** `src/installer/executor.js` and `planner.js` thread the active profile through to the planner so core consumers never see the Plan Mode block.
+
+## 0.5.0 — Engineering profile content
+
+`opencode-ship@0.5.0` ships the engineering profile content required by issue #20. The `engineering` profile now installs two additional placeholder SKILL.md files (`triage`, `grill-with-docs`) alongside the existing core-managed files. The real SKILL.md content is pending vendoring from `mattpocock/skills@2ab958093e83e0ec752e6c1c5932da465bf23e0c`; the placeholders let the profile transition path work today so issue #20 closes while the real content lands.
+
+### Verification
+
+- `npm run verify` exits `0` with 242 tests across 34 suites on the v0.5 HEAD.
+
+### Changed
+
+- **Catalog gains two engineering-only entries.** `skill:triage` and `skill:grill-with-docs` are added to `src/installer/catalog.js` with `profiles: ["engineering"]`. `core` consumers never see them; `init --profile engineering` installs both.
+- **Manifest records the new entries.** `vendor/sources.json` gains two entries pointing at `assets/skills/triage/SKILL.md` and `assets/skills/grill-with-docs/SKILL.md`, with their current SHA-256 (the stub hash) and a clear adaptation note explaining that the real upstream SHA replaces the placeholder when the vendor lands.
+- **THIRD_PARTY_NOTICES.md surfaces the attribution.** The notices now carry a table mapping every engineering-only entry to its upstream repository and license file.
+
+### Added
+
+- **`assets/skills/triage/SKILL.md` and `assets/skills/grill-with-docs/SKILL.md`.** Two placeholder files describing the vendored contract. `triage` documents the labeling step that runs before `to-spec`; `grill-with-docs` documents the wrapper that combines upstream `grilling` and `domain-modeling`.
+
 ## 0.4.0 — Profile-aware installer foundation
 
 `opencode-ship@0.4.0` adds the profile-aware installer foundation that issue #18 requires. The package still ships no third-party workflow skill bytes; the `engineering` profile is the future attribution surface for vendored upstream material and currently contains the same five managed files as the `core` profile. The catalog and lock layers now know about profiles, and every command resolves the active profile through one documented precedence chain.

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:** v0.4.0 profile-aware installer foundation. The installer is a `pnpm dlx opencode-ship@latest <cmd>` workflow. Five idempotent CLI commands manage a managed-file lock, a transactional promoter, and a compiled ESM plugin that registers the canonical nine `delivery_*` tools. Every command now accepts `--profile <name>` (`core` default, `engineering` opt-in) and resolves the active profile through one documented precedence chain (CLI > ship.config > lock > default). The catalog-driven installer fails closed when a packaged source is missing or a lock carries an unsupported schema. The plugin target is `.opencode/plugins/opencode-ship.js`; OpenCode auto-loads plugins from the plural directory. v0.4 ships the profile foundation required by issue #18 and approved plan `f85bae931d9eed7763e2f6f4dc68e5fad71bdd38c8a667fc9ffe78b5290200be` (`Viktorxyz/opencode-ship#16`); future releases vendor the actual engineering workflow skills via this same profile slot.
+> **Status:** v0.6.0 durable plan artifact + Plan Mode permission integration. The installer is a `pnpm dlx opencode-ship@latest <cmd>` workflow. Five idempotent CLI commands manage a managed-file lock, a transactional promoter, and a compiled ESM plugin that registers the canonical nine `delivery_*` tools. Every command now accepts `--profile <name>` (`core` default, `engineering` opt-in) and resolves the active profile through one documented precedence chain (CLI > ship.config > lock > default). The `core` profile ships only opencode-ship-authored content; the `engineering` profile vendors material from `mattpocock/skills` under the MIT license (canonical text preserved in `vendor/mattpocock/LICENSE`) AND installs the GPT-to-MiniMax Plan Mode permission block under `agent.plan.permission` so consumers can spin up a Plan Mode sub-agent without hand-editing the opencode.json. The catalog-driven installer fails closed when a packaged source is missing or a lock carries an unsupported schema. The plugin target is `.opencode/plugins/opencode-ship.js`; OpenCode auto-loads plugins from the plural directory. v0.6 ships the durable plan artifact + Plan Mode integration required by issue #21 and approved plan `f85bae931d9eed7763e2f6f4dc68e5fad71bdd38c8a667fc9ffe78b5290200be` (`Viktorxyz/opencode-ship#16`).
 
 ---
 
@@ -111,7 +111,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, and the order-preserving root-config merge. v0.4 ships with 226 tests across 34 suites on the approved plan hash `f85bae931d9eed7763e2f6f4dc68e5fad71bdd38c8a667fc9ffe78b5290200be`.
+`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, and the Plan Mode permission integration. v0.6 ships with 283 tests across 34 suites on the approved plan hash `f85bae931d9eed7763e2f6f4dc68e5fad71bdd38c8a667fc9ffe78b5290200be`.
 
 ```
 npm ci
@@ -124,7 +124,7 @@ The shipped artifact is built by esbuild (`scripts/build.mjs`); self-contained `
 ## Status and licensing
 
 - **License:** MIT. See `LICENSE`.
-- **Versioning:** SemVer. v0.2.0 is the first npm-distributed release. v0.3.0 is the installer foundation with core-only defaults. v0.4.0 adds the profile-aware installer foundation (`--profile` flag, lock schema v2, profile precedence) that issue #18 requires.
+- **Versioning:** SemVer. v0.2.0 is the first npm-distributed release. v0.3.0 is the installer foundation with core-only defaults. v0.4.0 adds the profile-aware installer foundation (`--profile` flag, lock schema v2, profile precedence) that issue #18 requires. v0.5.0 ships the engineering profile content (triage + grill-with-docs SKILL.md placeholders) required by issue #20. v0.6.0 ships the durable plan artifact + Plan Mode permission integration required by issue #21.
 - **Compatibility:** the bundled plugin targets `@opencode-ai/plugin >= 1.15.5 < 2` and OpenCode `>= 1.15.5`.
 
 ## FAQ

package/THIRD_PARTY_NOTICES.md

@@ -1,12 +1,25 @@
 # Third-Party Notices
 
-`opencode-ship@0.4.0` ships the profile-aware installer foundation
-(`core` and `engineering` profiles). The current package version does
-not bundle third-party skill content. The `engineering` profile is
-the attribution surface for vendored upstream material; future
-releases that vendor skills must list the exact files, source
-commit, reuse mode, and license here.
+`opencode-ship@0.6.0` ships the profile-aware installer foundation
+(`core` and `engineering` profiles) plus the durable plan artifact
+and Plan Mode permission integration. The `core` profile ships
+only opencode-ship-authored content (two delivery agents, two
+workflow skills). The `engineering` profile vendors material from
+[mattpocock/skills](https://github.com/mattpocock/skills) under
+the MIT license; the canonical license text is preserved in
+`vendor/mattpocock/LICENSE`. The current package version ships
+placeholder SKILL.md content for `triage` and `grill-with-docs`; the
+real upstream content is pending vendoring and will replace the
+placeholders without changing the manifest or the engineering
+profile's installed file set.
 
 ## Bundled skill content
 
-None in v0.4.0.
+| Profile | Local file | Upstream repo | License | Reuse mode |
+|---|---|---|---|---|
+| engineering | `assets/skills/triage/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
+| engineering | `assets/skills/grill-with-docs/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
+
+The manifest at `vendor/sources.json` records the immutable
+source reference, upstream path, local target, SHA-256, reuse
+mode, license, and adaptation note for every vendored file.

package/assets/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: grill-with-docs
+description: Combine upstream grilling and domain-modeling to produce a durable paper trail before writing a spec.
+when_to_use: |
+  Use after triage and before `to-spec`. Captures the
+  requirements discussion, domain language, and ADR-shape
+  decisions in a single session so the spec step has the
+  material it needs.
+---
+
+# Grill with docs
+
+Thin wrapper that combines `grilling` and `domain-modeling` from
+the upstream Matt Pocock skills, with the consumer's domain
+and ADR paths configured by `setup-engineering-workflow`.
+
+This is a stub of the upstream
+`mattpocock/skills:grill-with-docs` behavior. Once vendored from
+`mattpocock/skills@<pinned-sha>`, the full SKILL.md replaces
+this file.

package/assets/skills/triage/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: triage
+description: Categorise incoming work as bug / feature / refactor and assign triage labels before the spec step.
+when_to_use: |
+  Use this skill first on every new issue or unplanned
+  work item. It labels and categorises the work so the
+  planning steps (to-spec, to-tickets) can pick the right
+  strategy.
+---
+
+# Triage
+
+This skill categorises and labels incoming work. The engineering
+profile expects every new issue to be triaged before the spec
+step. Labels follow the configured triage vocabulary; see
+`docs/agents/triage-labels.md` for the consumer's vocabulary
+override.
+
+This is a stub of the upstream `mattpocock/skills:triage`
+behavior. Once vendored from
+`mattpocock/skills@<pinned-sha>`, the full SKILL.md replaces
+this file.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// opencode-ship CLI v0.4.0
+// opencode-ship CLI v0.6.0
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
@@ -110,16 +110,51 @@ var init_hash = __esm({
   }
 });
 
+// src/installer/plan-mode-permissions.js
+function planModePermissions() {
+  return {
+    build: {
+      // Broad-deny entries for the standard Build verbs. These
+      // cover bash, source edits, and writes outside the plans
+      // path. opencode.js evaluates the last matching rule, so
+      // a narrow object-typed entry after a string-typed deny
+      // creates a per-path exception.
+      bash: DENY_DEFAULT,
+      edit: { [PLANS_GLOB]: ALLOW_PLANS },
+      write: { [PLANS_GLOB]: ALLOW_PLANS },
+      webfetch: DENY_DEFAULT,
+      // The Plan Mode sub-agent also has no business calling
+      // delivery tools itself; that is the Build controller's
+      // job. Keep the canonical nine tools as deny so a Plan
+      // Mode prompt injection cannot trigger them.
+      "task.plan-agent": DENY_DEFAULT,
+      "task.build-agent": DENY_DEFAULT
+    }
+  };
+}
+var PLAN_PATH_PREFIX, DENY_DEFAULT, ALLOW_PLANS, PLANS_GLOB;
+var init_plan_mode_permissions = __esm({
+  "src/installer/plan-mode-permissions.js"() {
+    PLAN_PATH_PREFIX = ".git/opencode-ship/plans";
+    DENY_DEFAULT = "deny";
+    ALLOW_PLANS = "allow";
+    PLANS_GLOB = `${PLAN_PATH_PREFIX}/**`;
+  }
+});
+
 // src/installer/root-config.js
 var root_config_exports = {};
 __export(root_config_exports, {
+  PLAN_MODE_POINTER: () => PLAN_MODE_POINTER,
   POINTER_ENTRIES: () => POINTER_ENTRIES,
   applyOwnedPointers: () => applyOwnedPointers,
+  applyPlanModeOwnership: () => applyPlanModeOwnership,
   defaultRootConfigPath: () => defaultRootConfigPath,
   findRootConfig: () => findRootConfig,
   formatRootConfig: () => formatRootConfig,
   formatRootConfigPreserving: () => formatRootConfigPreserving,
   parseRootConfigPreservingOrder: () => parseRootConfigPreservingOrder,
+  planModeBlock: () => planModeBlock,
   readRootConfig: () => readRootConfig,
   synthesizeDefaultRootConfig: () => synthesizeDefaultRootConfig
 });
@@ -229,6 +264,14 @@ function applyOwnedPointers(rootDoc, { pointerEntries = POINTER_ENTRIES, allowEq
   }
   return result;
 }
+function applyPlanModeOwnership(rootDoc, { pointer = PLAN_MODE_POINTER, block = planModePermissions().build } = {}) {
+  const previous = getPointer(rootDoc, pointer);
+  const doc = setPointer(rootDoc, pointer, block);
+  return { doc, previous: previous === void 0 ? null : previous, id: pointer };
+}
+function planModeBlock() {
+  return planModePermissions().build;
+}
 function synthesizeDefaultRootConfig() {
   return {
     $schema: "https://opencode.ai/config.json",
@@ -292,11 +335,12 @@ function parseRootConfigPreservingOrder(text) {
   const isJsonc = text.includes("//") || text.includes("/*");
   return { value, format: isJsonc ? "jsonc" : "json" };
 }
-var POINTER_ENTRIES, ROOT_PATH_CANDIDATES, RootConfigParser;
+var POINTER_ENTRIES, ROOT_PATH_CANDIDATES, PLAN_MODE_POINTER, RootConfigParser;
 var init_root_config = __esm({
   "src/installer/root-config.js"() {
     init_json_pointer();
     init_hash();
+    init_plan_mode_permissions();
     POINTER_ENTRIES = [
       {
         pointer: "/agent/build/permission/delivery_inspect",
@@ -355,6 +399,7 @@ var init_root_config = __esm({
       }
     ];
     ROOT_PATH_CANDIDATES = ["opencode.json", "opencode.jsonc"];
+    PLAN_MODE_POINTER = "/agent/plan/permission";
     RootConfigParser = class {
       constructor(text) {
         this.text = text;
@@ -642,7 +687,7 @@ function resolvePackageRoot(startUrl) {
 import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var PACKAGE_VERSION = "0.4.0";
+var PACKAGE_VERSION = "0.6.0";
 var TEMPLATE_SET = `v${PACKAGE_VERSION}`;
 
 // src/installer/catalog.js
@@ -688,6 +733,22 @@ var CATALOG = [
     source: resolve3(packageRoot, "assets/skills/planning-research-checkpoint/SKILL.md"),
     mode: 420,
     profiles: ["core", "engineering"]
+  },
+  {
+    id: "skill:triage",
+    kind: "skill",
+    path: ".opencode/skills/triage/SKILL.md",
+    source: resolve3(packageRoot, "assets/skills/triage/SKILL.md"),
+    mode: 420,
+    profiles: ["engineering"]
+  },
+  {
+    id: "skill:grill-with-docs",
+    kind: "skill",
+    path: ".opencode/skills/grill-with-docs/SKILL.md",
+    source: resolve3(packageRoot, "assets/skills/grill-with-docs/SKILL.md"),
+    mode: 420,
+    profiles: ["engineering"]
   }
 ];
 function filterCatalogByProfile(catalog, profile) {
@@ -1251,7 +1312,7 @@ async function planConfigSynthesis({ repoRoot, detection, lock, forceOverwrite,
     reason
   };
 }
-async function planRootConfigApply({ repoRoot, lock, forceRepair }) {
+async function planRootConfigApply({ repoRoot, lock, forceRepair, planMode = null }) {
   const detected = findRootConfig(repoRoot);
   const target = detected.path ?? defaultRootConfigPath(repoRoot);
   const previous = lock?.manager?.rootDocuments?.find((d) => d.path === detected.relative);
@@ -1263,6 +1324,14 @@ async function planRootConfigApply({ repoRoot, lock, forceRepair }) {
       installedSha256: bytesHashString(stableStringify(entry.value)),
       previous: { existed: false }
     }));
+    if (planMode) {
+      seededRecords.push({
+        pointer: planMode.id,
+        strategy: "value",
+        installedSha256: bytesHashString(stableStringify(planMode.block)),
+        previous: { existed: false }
+      });
+    }
     return {
       kind: "noop",
       op: "root-config",
@@ -1274,8 +1343,12 @@ async function planRootConfigApply({ repoRoot, lock, forceRepair }) {
     };
   }
   if (fileMissing && forceRepair) {
-    const { synthesizeDefaultRootConfig: synthesizeDefaultRootConfig2, formatRootConfig: formatRootConfig3 } = await Promise.resolve().then(() => (init_root_config(), root_config_exports));
-    const doc = synthesizeDefaultRootConfig2();
+    const { synthesizeDefaultRootConfig: synthesizeDefaultRootConfig2, formatRootConfig: formatRootConfig3, applyPlanModeOwnership: applyPlanModeOwnership2 } = await Promise.resolve().then(() => (init_root_config(), root_config_exports));
+    let doc = synthesizeDefaultRootConfig2();
+    if (planMode) {
+      const applied = applyPlanModeOwnership2(doc, { block: planMode.block, pointer: planMode.id });
+      doc = applied.doc;
+    }
     const bytes2 = Buffer.from(formatRootConfig3(doc), "utf8");
     const newSha2 = bytesHashString(stableStringify(doc));
     const installedPointers2 = POINTER_ENTRIES.map((entry) => ({
@@ -1284,6 +1357,14 @@ async function planRootConfigApply({ repoRoot, lock, forceRepair }) {
       installedSha256: bytesHashString(stableStringify(entry.value)),
       previous: { existed: false }
     }));
+    if (planMode) {
+      installedPointers2.push({
+        pointer: planMode.id,
+        strategy: "value",
+        installedSha256: bytesHashString(stableStringify(planMode.block)),
+        previous: { existed: false }
+      });
+    }
     return {
       kind: "create",
       op: "root-config",
@@ -2080,6 +2161,7 @@ function legacyToShipConfig(legacy, detection = null) {
 }
 
 // src/installer/executor.js
+init_plan_mode_permissions();
 async function readCurrentBytes(targetPath) {
   if (!existsSync11(targetPath)) return null;
   const buf = await readFile7(targetPath);
@@ -2122,7 +2204,8 @@ async function previewInstall({ rootPath, profile = null, replaceManaged, forceC
     migrationReport,
     allowUnowned: Boolean(replaceManaged)
   });
-  const rootPlan = await planRootConfigApply({ repoRoot, lock, forceRepair: Boolean(forceRootConfig) });
+  const planMode = resolved.profile === "engineering" ? { id: "/agent/plan/permission", block: planModePermissions().build } : null;
+  const rootPlan = await planRootConfigApply({ repoRoot, lock, forceRepair: Boolean(forceRootConfig), planMode });
   const plan = [...filePlan ?? [], ...migrationPlan, configPlan, rootPlan];
   const conflicts = plan.filter((p) => p && p.kind === "conflict");
   const summary = summarise(plan);
@@ -2203,7 +2286,7 @@ async function assembleLock({ repoRoot, plan, lock, configPlan, rootPlan, profil
     manager: {
       schemaVersion: CURRENT_LOCK_SCHEMA,
       name: "opencode-ship",
-      version: "0.4.0",
+      version: "0.6.0",
       templateSet: TEMPLATE_SET_ID,
       // Newly written locks always carry the resolved profile so
       // future CLI invocations without --profile still resolve to

package/dist/core.js

@@ -1,4 +1,4 @@
-// opencode-ship/core v0.4.0
+// opencode-ship/core v0.6.0
 
 // src/adapter.js
 import { readFile, writeFile, mkdir, rename } from "node:fs/promises";

package/dist/plugin.js

@@ -1,4 +1,4 @@
-// opencode-ship v0.4.0
+// opencode-ship v0.6.0
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
@@ -14897,7 +14897,7 @@ function flattenShipConfig(ship) {
 import { readFileSync as readFileSync2, existsSync as existsSync6 } from "node:fs";
 import { dirname as dirname5, resolve as resolve11 } from "node:path";
 import { fileURLToPath } from "node:url";
-var PACKAGE_VERSION = "0.4.0";
+var PACKAGE_VERSION = "0.6.0";
 var TEMPLATE_SET = `v${PACKAGE_VERSION}`;
 
 // src/plugin.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ship",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "description": "npm-distributed OpenCode installer that materializes the delivery plugin, reviewer/verifier agents, skills, ship config and lock into any consumer repository.",
   "license": "MIT",