@soleur/opencode 0.0.0-stage → 1.0.0

package/lib/pr-merge-poll.ts

@@ -0,0 +1,103 @@
+/**
+ * PR merge-state polling helpers — BEHIND detection and resync contract.
+ *
+ * Ship Phase 7 embeds the full poll loop; this module is the portable spec
+ * Grok Build agents use when polling outside Monitor tool (ad-hoc CI watch,
+ * PR babysit, post-merge verify prep).
+ *
+ * Failure mode (#6347 session): Grok polled `statusCheckRollup` pending/failed
+ * but ignored `mergeStateStatus: BEHIND` — burned 17 ticks while main moved.
+ */
+
+import type { Harness } from "./harness";
+
+/** GitHub `mergeStateStatus` values we act on during poll loops. */
+export const MERGE_STATE_BEHIND = "BEHIND" as const;
+export const MERGE_STATE_DIRTY = "DIRTY" as const;
+export const MERGE_STATE_BLOCKED = "BLOCKED" as const;
+export const MERGE_STATE_CLEAN = "CLEAN" as const;
+
+export const MAX_BEHIND_SYNCS_DEFAULT = 6;
+
+/** Sentinel for drift-guarded docs/scripts. */
+export const PR_BEHIND_SYNC_SENTINEL = "pr-behind-sync-protocol";
+
+/** `gh pr view` jq template — MUST include mergeStateStatus, not just checks. */
+export const PR_VIEW_POLL_JQ =
+  '"\\(.state) \\(.mergeStateStatus)"';
+
+export function formatPrPollState(state: string, mergeStateStatus: string): string {
+  return `${state} ${mergeStateStatus}`;
+}
+
+export function isBehindPollState(pollLine: string): boolean {
+  return pollLine.includes(MERGE_STATE_BEHIND);
+}
+
+export function isTerminalPollState(pollLine: string): boolean {
+  return /^(MERGED|CLOSED)\b/.test(pollLine.trim());
+}
+
+export function isDirtyPollState(pollLine: string): boolean {
+  return pollLine.includes(MERGE_STATE_DIRTY);
+}
+
+/**
+ * When true, stop CI-only polling and resync branch with origin/main first.
+ * BEHIND: auto-merge will not fire until head catches up to base.
+ * DIRTY: GitHub computed a conflict; locally-clean DIRTY (kb-index) still resyncs.
+ */
+export function shouldResyncBeforePoll(mergeStateStatus: string): boolean {
+  return (
+    mergeStateStatus === MERGE_STATE_BEHIND ||
+    mergeStateStatus === MERGE_STATE_DIRTY
+  );
+}
+
+/**
+ * Harness-specific BEHIND/DIRTY resync instructions. The script discriminates:
+ * DIRTY auto-syncs only when `git merge-tree` proves the local merge clean
+ * (kb-index class); a real conflict exits 6 for manual resolution.
+ */
+export function behindSyncInstructions(harness: Harness): string {
+  // ADR-179: the installed plugin root, never a repo-relative path (a customer
+  // repo has no plugins/soleur/ tree).
+  const script = 'bash "${CLAUDE_PLUGIN_ROOT}/scripts/sync-pr-behind.sh"';
+  switch (harness) {
+    case "grok":
+      return [
+        "**BEHIND/DIRTY resync (Grok Build)**",
+        `- When \`gh pr view --jq '.mergeStateStatus'\` returns \`BEHIND\` or \`DIRTY\`, **STOP** CI-only polling.`,
+        `- Exception (first): when \`main\` has a merge queue and the PR is armed (the Phase 7 poll prints \`[ship.phase7.queue_wait]\`) the PR is waiting for GitHub to enqueue it — keep polling; never run the sync script, update-branch or --admin it until \`[ship.phase7.queue_wait_expired]\`, a push line, MERGED, a dequeue or any poll exit. This holds for a BEHIND reading only (a conflicting DIRTY PR still needs its sync). The script itself answers \`kind=queue_wait\` (exit 0, nothing synced) for that PR: a wait, not a failure.`,
+        `- Otherwise, from the PR worktree: \`${script} <PR-number>\` (fetch → merge origin/main → push). Use the Phase 7 loop; never write your own poll loop or wrap the script in one.`,
+        `- \`DIRTY\` auto-syncs only when the local merge is clean; a real conflict exits for manual resolution.`,
+        `- Match AwaitShell \`pattern\`: \`BEHIND detected|auto-sync.*pushed|BEHIND resolved|BEHIND unchanged|merge conflict|\\[pr-behind-sync\\] kind=|\\[ship\\.phase7\\.\`.`,
+        `- Exit 11 is a no-op: \`kind=noop\` is GitHub state lag. \`kind=queued\` means the PR is IN the merge queue and nothing was pushed (a push dequeues it): it exits 0 here and 11 only with \`--step\` — keep polling for MERGED, never push, update-branch or --admin it; re-poll, then re-run. Exit 13 (\`kind=dequeued\`) means it left the queue unmerged (a failed merge_group run or a removal; auto-merge may still read armed) — follow the recovery on that line. Exit 12 (\`kind=wrong_branch\`) means this worktree is not the PR's branch — cd to it. Any other \`kind=\` line names its next action.`,
+        `- Re-poll after push; do NOT ask the operator to update the branch.`,
+      ].join("\n");
+
+    case "claude":
+      return [
+        "**BEHIND/DIRTY resync (Claude Code)**",
+        `- When mergeStateStatus is \`BEHIND\` or \`DIRTY\`, the ship Phase 7 Monitor loop calls \`sync-pr-behind.sh <PR-number> --step\` once per attempt (the Phase 7 fence's call, never yours; unguarded by design). Never write your own poll loop — use that one. The standalone entry is \`${script} <PR-number>\`: it refuses an armed PR on a merge-queue repo with \`kind=queue_wait\` (exit 0, a wait, not a failure); DIRTY auto-syncs only when locally clean.`,
+        `- FORBIDDEN: heartbeating on pending checks while BEHIND or DIRTY — auto-merge is blocked — unless the script reported \`kind=queued\` (exit 11 with \`--step\`): a PR in the merge queue is not blocked, the queue merges it, so keep heartbeating and never sync it; likewise when \`main\` has a merge queue and the PR is armed (the Phase 7 poll prints \`[ship.phase7.queue_wait]\`) on a BEHIND reading (a conflicting DIRTY PR still syncs) — GitHub enqueues it, in force until \`[ship.phase7.queue_wait_expired]\`, a push line, MERGED, a dequeue or any poll exit; \`kind=dequeued\` (exit 13) stops the poll with the recovery.`,
+      ].join("\n");
+
+    case "cursor":
+      return [
+        "**BEHIND/DIRTY resync (Cursor CLI)**",
+        "- No wait primitive has been measured on the Cursor CLI.",
+        "- This run cannot finish that gate.",
+        "- Continue that merge on a harness that already has a wait, or stop.",
+        "- Do not invent a wait. Do not hand the wait to the operator.",
+        "- This stop does not make the plugin supported.",
+      ].join("\n");
+
+    default:
+      return [
+        "**BEHIND/DIRTY resync**",
+        `- Exception (first): when \`main\` has a merge queue and the PR is armed (the Phase 7 poll prints \`[ship.phase7.queue_wait]\`) the PR is waiting for GitHub to enqueue it — keep polling; never merge origin/main into it, resync-push, update-branch or --admin it (a fix commit for a red check is fine) until \`[ship.phase7.queue_wait_expired]\`, a push line, MERGED, a dequeue or any poll exit. This holds for a BEHIND reading only (a conflicting DIRTY PR still needs its sync). The script itself answers \`kind=queue_wait\` (exit 0, nothing synced) for that PR: a wait, not a failure.`,
+        `- Otherwise, mergeStateStatus \`BEHIND\` or \`DIRTY\` → run \`${script} <PR-number>\` from the PR worktree (fetch → merge origin/main → push; DIRTY only when the local merge is clean; it refuses an armed BEHIND PR on a merge-queue repo with \`kind=queue_wait\`, so never hand-merge instead). Use the Phase 7 loop; never write your own poll loop — on a harness without a Monitor tool, run that block itself inside the waiting subagent or shell.`,
+      ].join("\n");
+  }
+}

package/lib/workflow-fidelity.ts

@@ -0,0 +1,388 @@
+/**
+ * Workflow fidelity contract — prevents Grok Build (and Claude) agents from
+ * cherry-picking pipeline steps after `/go` routes to a registered skill, or
+ * stopping mid-chain when a lifecycle skill is invoked standalone.
+ *
+ * Failure mode (#6325 session): `/go` routed to one-shot; the parent ran
+ * worktree setup + inline implementation and stopped — skipping plan, review, ship.
+ * Extension (#6320 lifecycle): same bypass at `/brainstorm`, `/plan`, `/work` entry.
+ */
+
+import type { Harness } from "./harness";
+import { cursorSkillSlash } from "../scripts/sync-cursor-name-map";
+
+/** Skills that own a multi-phase pipeline — must be invoked, never inlined. */
+export const PIPELINE_SKILLS = [
+  "one-shot",
+  "brainstorm",
+  "drain-labeled-backlog",
+  "drain-prs",
+] as const;
+
+export type PipelineSkill = (typeof PIPELINE_SKILLS)[number];
+
+/** Exploration handoff after brainstorm completes (shortcut: one-shot when reqs clear). */
+export const BRAINSTORM_CHILD_SKILLS = ["plan", "one-shot"] as const;
+
+/** Planning prefix before the shared implementation tail. */
+export const PLAN_PIPELINE_PREFIX = ["plan", "deepen-plan"] as const;
+
+/** Shared implementation tail — one-shot Steps 3–8 and standalone `/work` Phase 4. */
+export const IMPLEMENTATION_TAIL = [
+  "work",
+  "review",
+  "qa",
+  "compound",
+  "ship",
+] as const;
+
+/** Child skills one-shot must invoke in order (Steps 1–7). */
+export const ONE_SHOT_CHILD_SKILLS = [
+  ...PLAN_PIPELINE_PREFIX,
+  ...IMPLEMENTATION_TAIL,
+] as const;
+
+/** Standalone skills with mandatory successor invokes (not full orchestrators). */
+export const HANDOFF_SKILLS = ["plan", "work", "review", "compound", "ship"] as const;
+
+export type HandoffSkill = (typeof HANDOFF_SKILLS)[number];
+
+/** Post-merge production verification — ship Step 3.8, one-shot Step 8 prerequisite. */
+export const POST_MERGE_VERIFICATION_SKILLS = ["postmerge"] as const;
+
+/** Emitted only after merge + release workflows + postmerge verification (one-shot Step 8). */
+export const ONE_SHOT_DONE_MARKER = "<promise>DONE</promise>";
+
+/** Sentinel markers skills/docs must retain — drift-guarded in tests. */
+export const GO_POST_ROUTE_SENTINEL = "go-post-route";
+export const ONE_SHOT_ANTI_BYPASS_SENTINEL = "one-shot-anti-bypass-protocol";
+export const GROK_PRE_PUSH_GATE_SENTINEL = "grok-pre-push-gate";
+
+/** Repo-relative path — run from root before `git push` under Grok Build. */
+export const GROK_PRE_PUSH_GATE_SCRIPT = "plugins/soleur/scripts/grok-pre-push-gate.sh";
+export const BRAINSTORM_ANTI_BYPASS_SENTINEL = "brainstorm-anti-bypass-protocol";
+export const PLAN_ANTI_BYPASS_SENTINEL = "plan-anti-bypass-protocol";
+export const WORK_ANTI_BYPASS_SENTINEL = "work-anti-bypass-protocol";
+export const LIFECYCLE_HANDOFF_SENTINEL = "lifecycle-handoff-protocol";
+export const SHIP_MERGE_DEPLOY_SENTINEL = "ship-merge-deploy-protocol";
+export const POSTMERGE_HARNESS_SENTINEL = "postmerge-harness-protocol";
+
+/**
+ * Grok has no Skill or Monitor tool. Do not invent matchers for them.
+ * Distinct from an untrusted session (no live grok --trust token on the
+ * 2026-09-11 host). Drain-prs Grok polling is AwaitShell, not Monitor.
+ */
+export const GROK_HOOK_SKIP_NO_TOOL = "SOLEUR_HOOK_SKIP reason=no-tool";
+export const GROK_HOOK_SKIP_UNTRUSTED = "SOLEUR_HOOK_SKIP reason=untrusted-session";
+
+/** Re-export for workflow tests — BEHIND resync lives in pr-merge-poll.ts. */
+export { PR_BEHIND_SYNC_SENTINEL } from "./pr-merge-poll";
+
+export function isPipelineSkill(skill: string): skill is PipelineSkill {
+  return (PIPELINE_SKILLS as readonly string[]).includes(skill);
+}
+
+export function isHandoffSkill(skill: string): skill is HandoffSkill {
+  return (HANDOFF_SKILLS as readonly string[]).includes(skill);
+}
+
+/** Map /go routing labels to soleur skill names (soleur: prefix stripped at dispatch). */
+export const GO_SKILL_ROUTES: Record<string, string> = {
+  fix: "one-shot",
+  implement: "one-shot",
+  drain: "drain-labeled-backlog",
+  "drain-prs": "drain-prs",
+  review: "review",
+  incident: "incident",
+  questionnaire: "questionnaire-generate",
+  glossary: "kb-glossary",
+  default: "brainstorm",
+};
+
+export function resolveGoSkillRoute(label: string): string {
+  return GO_SKILL_ROUTES[label] ?? GO_SKILL_ROUTES.default;
+}
+
+export function isOneShotRoute(label: string): boolean {
+  return resolveGoSkillRoute(label) === "one-shot";
+}
+
+export function isBrainstormRoute(label: string): boolean {
+  return resolveGoSkillRoute(label) === "brainstorm";
+}
+
+/** Mandatory successors when a handoff skill runs standalone (no parent orchestrator). */
+export function mandatorySuccessors(skill: string): readonly string[] {
+  switch (skill) {
+    case "brainstorm":
+      return BRAINSTORM_CHILD_SKILLS;
+    case "plan":
+      return ["work"];
+    case "work":
+      return ["review", "compound", "ship"];
+    case "review":
+      return ["compound"];
+    case "compound":
+      return ["ship"];
+    case "ship":
+      return [...POST_MERGE_VERIFICATION_SKILLS];
+    default:
+      return [];
+  }
+}
+
+/**
+ * The operator-typed / adapter-rendered form of one skill on one harness. The cursor
+ * arm is `formatSkillRef`-only until `detectHarness` returns `cursor`. `formatSkillInvocation`
+ * does not share that arm in slice 1. Docs name skills as `soleur:<name>` and
+ * leave THIS to the adapter (ADR-226); every fidelity string below goes through it so no
+ * harness receives another harness's form (arch F3, #8299).
+ */
+export function formatSkillRef(skill: string, harness: Harness): string {
+  switch (harness) {
+    case "codex":
+      return `$soleur:${skill}`;
+    case "grok":
+      return `/${skill}`;
+    case "devin":
+      return `/soleur:${skill}`;
+    case "antigravity":
+      return `/soleur:${skill}`;
+    case "cursor":
+      return cursorSkillSlash(skill);
+    case "opencode":
+      // The bare id is OpenCode's registration key (measurements §2.3): it has no namespaced form.
+      return skill;
+    default:
+      return `soleur:${skill}`;
+  }
+}
+
+/**
+ * The declared TRANSITION set — every edge a session may legally take, including
+ * back-edges.
+ *
+ * DELIBERATELY SEPARATE FROM `mandatorySuccessors()`, which is not a transition
+ * set: its result is rendered into the prompt as
+ * "When standalone, invoke next: /X, /Y" (see `workflowFidelityInstructions`).
+ * A permitted transition is legal-if-taken; a mandatory successor is a directive.
+ * Putting `plan` into `work`'s successors to express the `work -> plan` back-edge
+ * would instruct the model to re-enter planning after EVERY work run.
+ *
+ * The four back-edges are operator-approved: `review -> work` (review produced
+ * findings that need implementing), `ship -> work` (a pre-merge gate —
+ * preflight/QA — failed), `postmerge -> work` (post-merge verification failed;
+ * declared 2026-09-19 on #8325 — 7 sessions took it, 5 re-entered
+ * `work -> review -> compound -> ship -> postmerge` in full, 2 ended at `work`,
+ * none skipped `ship`) and `work -> plan` (implementation invalidated the
+ * plan). The first, second and fourth were approved on #8302.
+ *
+ * `plan -> ship` is deliberately ABSENT. It is the path that lets a session skip
+ * `review` entirely, which surfaces only after merge — the operator-facing loss
+ * this edge set exists to make visible. Its absence is asserted directly in
+ * `workflow-fidelity.test.ts`, because nothing else in the suite would notice if
+ * it were added.
+ *
+ * This is a bundled TypeScript const, NOT a runtime read of
+ * `.claude/phase-surface-map.json`. The plugin ships as `./plugins/soleur`
+ * (`.claude-plugin/marketplace.json`) and does not carry `.claude/`, so a runtime
+ * read returns nothing on a customer install — and `mandatorySuccessors()` would
+ * then silently emit no next-step directive at all. The JSON is a derived view
+ * kept honest by a parity test; the same reasoning already produced the bundled
+ * web copy at `apps/web-platform/server/phase-surface-map.ts`. See ADR-229.
+ */
+export const DECLARED_TRANSITIONS: Readonly<Record<string, readonly string[]>> = {
+  brainstorm: ["plan", "one-shot"],
+  plan: ["work"],
+  work: ["review", "compound", "ship", "plan"],
+  review: ["compound", "work"],
+  compound: ["ship"],
+  ship: ["postmerge", "work"],
+  postmerge: ["work"],
+};
+
+/**
+ * Node skills that another node's SKILL.md invokes as a designed SUB-STEP of
+ * its own run, keyed by the invoking node. Each entry names the section that
+ * makes the call (pinned per entry by the anchor test in workflow-fidelity.test.ts):
+ *   - brainstorm: runs `compound` to capture learnings, then hands off to
+ *     `plan`, so the log shows `brainstorm compound plan` for the handoff.
+ *   - plan: §Exit Gate step 1 runs `compound` (direct invocation only; in a
+ *     pipeline the gate is skipped and the entry is simply unused — sound
+ *     either way, since `plan -> work` is the only pair it can declare).
+ *   - postmerge: §Phase 6 (Update Issue and Compound) runs `compound`.
+ *   - ship: §Phase 2 (Capture Learnings) runs `compound` inside ship.
+ *     §Phase 1.5 (Review Evidence Gate: the missing-evidence option and the
+ *     `sequential-fallback` re-run) and §Phase 5.5 (Pre-Ship Review Gates ->
+ *     Code Review Completion Gate) run `review` inside ship. These are
+ *     interactive arms only; headless aborts instead (PR #8627). The log
+ *     records starts only, so the classifier collapses ANY review whose
+ *     previous kept node is ship, whatever invoked it; see ADR-229's
+ *     2026-09-23 re-baseline for what that masks.
+ * The classifier drops a record whose skill is a sub-step of the PREVIOUS KEPT
+ * node before pairing, so `plan compound work` pairs as `plan -> work`. This is
+ * NOT an edge: no `K -> compound` edge is declared for any key K, and because
+ * the collapse joins K to its NEXT node, `plan compound ship` surfaces as the
+ * review skip `plan -> ship` instead of hiding behind the declared
+ * `compound -> ship` (#8399). `review: ["compound"]` is the entry the rules
+ * below forbid: `compound` is a declared successor of `review`, so the collapse
+ * would turn `review compound work` into the declared `review -> work`.
+ * Mirrored in .claude/workflow-transitions.json under `sub_steps`
+ * (parity-pinned). See ADR-229 (amended 2026-09-21, #8399; 2026-09-23, PR #8627).
+ *
+ * To add an entry: the key and every value must be DECLARED_TRANSITIONS nodes
+ * (a non-node is removed by the classifier's node filter first, so the entry
+ * would be dead); a value must not be a declared successor of its key (the
+ * collapse would silently delete a declared pair from `pairs`). An entry also
+ * hands the value's outgoing edges to the key: any successor of the key that is
+ * not a successor of the value becomes a declared pair after the collapse, so
+ * measure which pairs vanish before adding one. Edit this const first, then
+ * mirror it in the JSON view (and its `_comment` amendment list), then update in
+ * the same PR: the exact-set pin, the `ANCHORS` heading list and its heading
+ * total in workflow-fidelity.test.ts (a new KEY also moves the view key-set pin
+ * there and `LOOP_KEYS` in the classifier suite), a case in
+ * scripts/classify-workflow-transitions.test.sh (plus its `MIN_CASES` floor),
+ * and ADR-229's Status line, a re-baseline bullet and its Verification counts.
+ * Run `bun test plugins/soleur/test/workflow-fidelity.test.ts`.
+ */
+export const DECLARED_SUB_STEPS: Readonly<Record<string, readonly string[]>> = {
+  brainstorm: ["compound"],
+  plan: ["compound"],
+  postmerge: ["compound"],
+  ship: ["compound", "review"],
+};
+
+/** Edges declared FROM `skill`. Unknown nodes declare nothing. */
+export function declaredTransitions(skill: string): readonly string[] {
+  return DECLARED_TRANSITIONS[skill] ?? [];
+}
+
+/** Whether `from -> to` is a declared edge. */
+export function isDeclaredTransition(from: string, to: string): boolean {
+  return declaredTransitions(from).includes(to);
+}
+
+function formatSkillList(skills: readonly string[], harness: Harness): string {
+  return skills.map((s) => `\`${formatSkillRef(s, harness)}\``).join(", ");
+}
+
+/**
+ * Markdown block appended to harness routing instructions.
+ * Cite in go.md Step 2.1 (`<!-- workflow-fidelity:block:go-post-route:start -->`).
+ */
+export function workflowFidelityInstructions(harness: Harness): string {
+  if (harness === "cursor") {
+    return [
+      "**Workflow fidelity (Cursor CLI)**",
+      "- Read the canonical file the stub names, relative to the plugin root, and follow that file.",
+      `- \`${formatSkillRef("go", harness)}\` and \`${formatSkillRef("sync", harness)}\` stay bare. Every other name is prefixed, including \`${formatSkillRef("plan", harness)}\`, \`${formatSkillRef("help", harness)}\`, and \`${formatSkillRef("review", harness)}\`.`,
+      "- Slice 1 does not run hooks and does not classify the session as cursor.",
+    ].join("\n");
+  }
+
+  const invokeSurface =
+    harness === "codex"
+      ? "skill loading (skills.read when available; otherwise read the installed SKILL.md and execute its full workflow)"
+      : harness === "grok"
+        ? "slash command (`/brainstorm`, `/one-shot`, `/plan`, `/work`, `/review`, `/ship`, …)"
+        : harness === "antigravity"
+          ? "slash command or reading SKILL.md (`/soleur:brainstorm`, `/soleur:one-shot`, …)"
+          : harness === "claude"
+            ? "Skill tool (`soleur:<skill>`)"
+            : harness === "opencode"
+              ? "**skill** tool with the bare id (`soleur:plan` → `plan`, `soleur:one-shot` → `one-shot`, …)"
+              : "registered skill invocation";
+
+  const brainstormNext = formatSkillList(BRAINSTORM_CHILD_SKILLS, harness);
+  const workTail = formatSkillList(
+    ["review", "qa", "compound", "ship"] as const,
+    harness,
+  );
+
+  const ref = (skill: string): string => `\`${formatSkillRef(skill, harness)}\``;
+  const go = ref("go");
+
+  const nextActionLine =
+    harness === "grok"
+      ? "- After `/go` routes to a pipeline skill (`one-shot`, `brainstorm`, `drain-*`), your **next action** MUST be to Read that skill's SKILL.md in this process and run it to completion (Grok has no nested Skill tool). Forbidden is executing a subset or writing product code before the child skill finishes — not the Read itself."
+      : `- After ${go} routes to a pipeline skill (\`one-shot\`, \`brainstorm\`, \`drain-*\`), your **next action** MUST be that skill's ${invokeSurface} — not reading SKILL.md and executing steps selectively.`;
+
+  const lines = [
+    "**Workflow fidelity (never bypass)**",
+    nextActionLine,
+    `- **FORBIDDEN after routing to \`brainstorm\`:** product code (Write/Edit/Shell); ending after spec/brainstorm doc without handoff. **REQUIRED next:** ${brainstormNext}.`,
+    `- **FORBIDDEN after routing to \`one-shot\`:** inline implementation before Steps 1–8 complete; ending after push/draft PR; reporting "done" without \`${ONE_SHOT_DONE_MARKER}\`.`,
+    `- **FORBIDDEN on standalone \`plan\` / \`work\`:** implementing or pushing without the mandated successor chain. \`plan\` → ${ref("work")}; \`work\` → ${workTail}.`,
+    `- **Merge → deploy (never ask the operator):** after ${ref("ship")} queues merge, YOU poll through release workflows and invoke ${ref("postmerge")} — do not ask "want me to monitor?" or end the turn at MERGED.`,
+    `- **Parking finished work is not a hand-off:** a stop is legitimate only for something you cannot clear — an in-flight CI run or agent, authorization for an irreversible production action (\`hr-menu-option-ack-not-prod-write-auth\`), cost/scope, an outward-facing effect, or a genuine requirements fork. Handing a reviewed, green PR back for a merge/review/ship is none of those: \`rf-never-skip-qa-review-before-merging\` requires carrying it to MERGED in-session, and "review-gated" means ${ref("review")} RAN and its findings were fixed, never that a person approves. Claude Code blocks this at its Stop hook; you have no hook, so this line is your copy of the rule.`,
+    `- **\`${ONE_SHOT_DONE_MARKER}\` gate:** emit ONLY after merge + release workflows + ${ref("postmerge")} verification complete — not at draft PR, not at merge alone.`,
+    `- **Deliverables:** brainstorm = artifacts + handoff; plan = plan file + ${ref("work")}; work/one-shot = **merged PR + healthy deploy**. Draft PRs are checkpoints only.`,
+    "- Skill exit summaries (`## Work Phase Complete`, `## Review Phase Complete`) are **continuation gates**, not turn boundaries.",
+  ];
+
+  if (harness === "grok") {
+    lines.push(
+      `- **Before \`git push\`:** run \`bash ${GROK_PRE_PUSH_GATE_SCRIPT}\` from repo root (local CI parity: \`test-all.sh\` + fast required checks + \`grok-fidelity\`). Abort push on non-zero exit; do not wait for CI.`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Strengthen skill invocation text for pipeline and handoff skills. Every skill named in the
+ * suffix is rendered in the ACTIVE harness's form. `harness` is REQUIRED, not defaulted: a
+ * default of "grok" would reproduce the pre-ADR-226 strings (`/postmerge`, `/ship`) for any
+ * caller that forgot it — the exact defect this function was changed to remove — and would do
+ * so silently on three of four harnesses. A required parameter makes forgetting a type error — the grok arm reads exactly as before, and
+ * `invokeSkill("ship")` on Codex names `$soleur:postmerge`, never `/postmerge` (arch F3).
+ */
+export function pipelineInvocationSuffix(skill: string, harness: Harness): string {
+  const ref = (s: string): string => formatSkillRef(s, harness);
+  if (skill === "one-shot") {
+    return (
+      ` Run **all** Steps 0–8 to completion. ` +
+      `Do NOT implement product code inline. ` +
+      `Poll merge→deploy yourself; invoke ${ref("postmerge")} after ${ref("ship")}. ` +
+      `Emit \`${ONE_SHOT_DONE_MARKER}\` only after postmerge completes.`
+    );
+  }
+  if (skill === "brainstorm") {
+    return (
+      " Run the full brainstorm pipeline to completion. " +
+      "Do NOT write product code. " +
+      `Hand off via ${ref("plan")} or ${ref("one-shot")} when exploration is done.`
+    );
+  }
+  if (skill === "plan") {
+    return (
+      " Run the full plan pipeline. " +
+      `Do NOT implement product code inline — invoke ${ref("work")} when the plan artifact is ready.`
+    );
+  }
+  if (skill === "work") {
+    return (
+      ` Run implementation then the post-work tail (${ref("review")} → ${ref("compound")} → ${ref("ship")} → ${ref("postmerge")}). ` +
+      "Do NOT stop after push — merged PR + deploy verification is the deliverable."
+    );
+  }
+  if (skill === "ship") {
+    return (
+      ` Poll merge and release workflows to completion; invoke ${ref("postmerge")} before cleanup. ` +
+      "Do NOT ask the operator to monitor — you own the wait."
+    );
+  }
+  if (skill === "postmerge") {
+    return " Run all postmerge phases through Phase 7 report — production health gate.";
+  }
+  if (isPipelineSkill(skill)) {
+    return " Run the skill's full pipeline — do not stop after the first phase.";
+  }
+  if (isHandoffSkill(skill)) {
+    const next = mandatorySuccessors(skill);
+    if (next.length > 0) {
+      return ` When standalone, invoke next: ${next.map(ref).join(", ")} — do not end the turn at artifacts.`;
+    }
+  }
+  return "";
+}

package/opencode/INSTRUCTIONS.md

@@ -0,0 +1,152 @@
+# Soleur on OpenCode — routing
+
+Generated by `scripts/sync-opencode-adapter.ts`. Do not edit by hand.
+
+## Skills
+
+Soleur skills register from the canonical tree through the `skills` config key, so this
+harness has no generated skill tree. A skill id is the **bare directory basename**
+(`plan`, `one-shot`, `work`): there is no `soleur:` namespace here (measurement §2.3).
+
+Canonical Soleur prose is written for Claude Code and says `soleur:<name>`. On this
+harness that prefix is dropped: invoke `soleur:plan` as `plan`. An agent-read document
+keeps the canonical form; an operator-typed or tool-invoked reference is bare.
+
+## Agents
+
+An agent id is derived from its file path, not from frontmatter `name:`, so
+`soleur:engineering:cto` is spawned as `engineering/cto` (measurement §3.0). Every
+Soleur agent is generated with `mode: subagent`; without that field an agent registers
+as primary and the `subagent` tool cannot reach it.
+
+Spawn subagents through the **`subagent`** tool. It takes the path-derived id
+(`engineering/cto`), a one-line `description`, and a complete `prompt` — the child sees
+nothing but that prompt. Foreground waits for the result; `background: true` returns
+immediately and notifies the parent when the child finishes.
+
+**Nesting depth is one.** A spawned child must not spawn further children: when a skill's
+step says *the leader spawns X*, the leader is the session that invoked the skill. A child
+that finds it needs a specialist reports back instead of delegating.
+
+## Commands
+
+`/go`, `/help`, `/sync` and `/version` register from the **config directory's** `commands/`
+(`install-opencode-adapter.ts` copies `opencode/commands/*.md` there). The committed tree's
+`opencode/commands/` is the source the installer copies, not a discovery root. If `/go` is
+absent, the adapter is not installed: run
+`bun "${CLAUDE_PLUGIN_ROOT}/scripts/install-opencode-adapter.ts" --check` (see *Paths and
+entry points* below for the token) — it names what is missing (measurement §4.0).
+
+A stub's body carries the literal text `$ARGUMENTS`. OpenCode's docs say the token is
+replaced with the invocation's arguments (§4.0 is docs-sourced, not measured); the stub is
+written on that basis. If the token is still present when the command runs, read it as the
+arguments you were given — the stub's job is to route you, not to parse them.
+
+## Paths and entry points
+
+Soleur's canonical prose calls scripts as `bash "${CLAUDE_PLUGIN_ROOT}/<path>"`, with the
+token substituted at delivery time on Claude Code. **Nothing on this harness substitutes
+it**, so a copied call reaches the shell with the token expanded to nothing, collapses to a
+workdir-relative path, and surfaces as `source=none verified=false` in the `go` gate rather
+than as anything that looks like a missing variable.
+
+The resolved root for this install is the line below — the installer rewrites it when it
+copies this file:
+
+    __SOLEUR_PLUGIN_ROOT__
+
+Before running any canonical `bash` call, type that absolute path in place of the token. It
+is the prefix for every path in the plugin (`skills/`, `agents/`, `commands/`, `hooks/`,
+`scripts/`) and the prefix of the `skills` entry in `opencode.json`, so either source
+disambiguates the other. Do not export or default a variable for it: the value is a literal
+path here. A `subagent` child does not inherit your shell environment, so hand it the
+absolute path in its prompt rather than assuming a variable exists.
+
+## Tools
+
+Canonical Soleur prose names Claude Code tools. This table is the translation, and the
+property it is held to is that **every** name Soleur's agent-read corpus uses has a row
+here (`test/harness-tool-map.test.ts`). The OpenCode side is the V2 built-in set
+(measurement §12.8); V1 called the shell tool `bash` and V2 calls it `shell`.
+
+| Soleur instruction | OpenCode execution |
+| --- | --- |
+| Read / Glob / Grep | `read`, `glob`, `grep` |
+| Write / Edit / MultiEdit | `write` for a new file, `edit` for a change (`replaceAll` replaces every match, which is all `MultiEdit` ever was); `patch` adds, moves or deletes several files in one call on the models that expose it |
+| Bash / Shell | `shell`. Set `workdir` instead of putting `cd` in the command, `timeout` in milliseconds, and `background: true` for a long-running process |
+| Skill `soleur:<name>` | The `skill` tool with the **bare** id: load `soleur:plan` as `plan`. The id must be in the advertised set, so a wrong one fails loudly instead of silently loading nothing |
+| Task / Agent / spawn_subagent | The `subagent` tool with the path-derived id (`engineering/cto`) |
+| AskUserQuestion | `question` — a real blocking prompt with a free-form answer always available |
+| TodoWrite / TodoRead | No `todo` tool exists. Track the steps in the skill's own Markdown, or in a scratch file in the project |
+| Monitor / AwaitShell / TaskOutput | `shell` with `background: true` returns immediately and notifies the session when the process finishes, retaining the full output in a managed file. There is no await/poll primitive and no background output reader; for a wait-until-event watch, run a bounded `shell` poll loop and keep progress visible |
+| WebSearch / WebFetch / ToolSearch | `websearch`, `webfetch`. No tool-search tool exists: the built-in set is advertised up front, so name the tool the step wants |
+| SendMessage / ListAgents | No equivalent. `subagent` starts a child and, in the background form, notifies on completion — there is no message-without-a-turn and no enumeration. Pass the returned `sessionID` to continue that same child |
+| TaskCreate / TaskGet / TaskList / TaskUpdate / TaskStop | No equivalent, and no inventory of running children exists. Track steps in the skill's own Markdown or a project file |
+| RemoteTrigger / PushNotification / ScheduleWakeup / CronCreate / CronDelete / CronList | No equivalent. Report the unsupported gate rather than simulating it — a scheduled or push-triggered step that silently does not fire is worse than one that refuses |
+| NotebookEdit | No equivalent; edit the file with `edit` |
+| Workflow scripts | Translate the orchestration into `subagent` calls; do not execute Claude tool calls as shell JavaScript |
+
+A gate with no OpenCode equivalent is stated as unsupported above, never silently
+skipped — the same posture the hook ledger takes. A step that cannot fire must say so.
+
+## Hooks and completion
+
+The plugin module `plugin.ts` (installed as `<configdir>/plugins/soleur-plugin.ts`) is the hook
+carrier. `.claude/hooks/opencode-dispositions.tsv` is its ledger: one row per canonical
+registration, every row carrying a disposition, so a gate with no equivalent here is
+**reported, never silently skipped**.
+
+OpenCode V2 has **no Stop hook**. Every hook surface communicates only by mutating the event
+object it is handed, and `ctx.event.subscribe` is a one-way iterator with no return channel,
+so no hook can defer a stop, force a continuation, or veto a completion. Soleur's completion
+marker is therefore **advisory** on this harness: a session that goes quiet is observed and
+nothing more. The structural checks inside the invoked skill are the contract, and the marker
+is a report, not a gate.
+
+The guards are real, and they reuse the canonical scripts unchanged. A shell call is handed to
+`browser-snapshot-credential-guard.sh` and `destructive-command-guard.sh` in the order
+`hooks.json` registers them, and the decision is written onto the permission event: a `deny`
+becomes `effect = "deny"` and a guard's `ask` becomes `effect = "ask"`, a real prompt. The tool
+then reports `permission.rejected` carrying the guard's reason, which the model reads. Neither
+value is downgraded — `deny` blocks, `ask` waits (measurement §12.2).
+
+The shell tool's wire name here is **`shell`**, not `bash`; the plugin maps both to Claude's
+`Bash` before handing the call to a guard (measurement §12.1). Code-mode `execute` calls carry
+JavaScript rather than a command and are not decided by the Bash guards — a limitation this
+harness shares with the guard scripts' own input contract.
+
+The post-compaction re-read is **armed, not guaranteed**, unlike Codex and Devin:
+`ctx.session.hook("compaction")` sets state and the next `ctx.session.hook("context")`
+re-injects the rule corpus plus the re-read directive. §12.3 captured that `context` fire
+once; §14.0 records a later probe where it did **not** fire, unreconciled (#10587). No
+compaction-support claim is published from this. Operationally: after a compaction you
+notice, re-read `AGENTS.rules.md` yourself rather than assuming the injection happened.
+What is not reproduced at all is `compaction-state.sh`'s transcript-bounded window
+bookkeeping, which counts `compact_boundary` records in a Claude Code transcript this
+harness has no equivalent of.
+
+## Uninstall / removal
+
+There is **no `--uninstall` flag** on `install-opencode-adapter.ts` today (tracked in
+#10591 item 4), so removal is done by hand against the config dir the installer wrote to.
+Four things were created; remove all four, because a partial removal is worse than none:
+
+1. **The generated `agents/` and `commands/` stubs.** These directories are **shared** with
+   the operator, so delete only the files whose body names the canonical plugin path (the
+   stubs' signature) — never the whole directory.
+2. **`<configdir>/soleur/`** — the installed instructions tree.
+3. **`<configdir>/plugins/soleur-plugin.ts`** — the hook carrier. Leaving it behind keeps
+   Soleur live after you meant to remove it: it still registers the Bash guards and still
+   re-injects the rule corpus on every session. It does **not** fail closed by itself — the
+   `guard-did-not-run` deny fires only when a guard *script* cannot be spawned (the checkout
+   moved or was removed, or `__SOLEUR_PLUGIN_ROOT__` never resolved), which is a checkout
+   problem rather than a leftover-file one.
+4. **The `skills` and `instructions` entries the installer added to `<configdir>/opencode.json`.**
+   Edit the file and drop those two keys; leaving them behind points OpenCode at a tree that
+   no longer exists.
+
+Do **not** use `install-opencode-adapter.ts --check` to confirm removal. It is an
+idempotence check for an *installed* adapter: it reports `MISSING` for every path it expects
+and exits 1, so a correct removal is indistinguishable from a broken install. Verify by hand
+instead — the four paths above are absent, and a fresh OpenCode session no longer
+re-injects the Soleur rule corpus or emits a `[soleur] guard-run-failure` line.

package/opencode/agents/engineering/cto.md

@@ -0,0 +1,10 @@
+---
+mode: subagent
+description: "Participates in brainstorm and planning phases to assess technical implications, flag architecture concerns, and identify engineering risks for proposed features. Use individual engineering agents (review, research, design) for focused tasks; use this agent for cross-cutting technical assessment during feature exploration."
+---
+
+Stub for the canonical agent `soleur:engineering:cto`. OpenCode derives an agent's id from this
+file's path, so the canonical `name:` frontmatter is deliberately not repeated here.
+
+Read and follow the canonical agent definition at `__SOLEUR_PLUGIN_ROOT__/agents/engineering/cto.md`,
+then work as that agent.