Merge pull request #486 from dmoliveira/fix/gateway-hook-stderr-overlay

Harden gateway hook error surfacing and build typing

Author: dmoliveira

docs/command-handbook.md

@@ -488,7 +488,7 @@ This index is sourced from `opencode.json` and is used as the complete catalog r
 /rules - Inspect conditional rules (status|explain|disable-id|enable-id|doctor)
 /safe-edit - Plan semantic safe-edit execution (status|plan|doctor)
 /session - Inspect indexed sessions (list|show|search|handoff|doctor)
-/ship - Run release intent preflight with safety gates and policy-aware reviewer routing
+/ship - Run release intent preflight, readiness diagnostics, delivery/release context summaries, and policy-aware reviewer routing (doctor|create-pr)
 /stack - Apply cross-command profile bundles
 /telemetry - Manage telemetry forwarding (status|doctor|profile|enable|disable|set)
 /todo - Inspect todo compliance state (status|enforce)

docs/plan/current-roadmap-tracker.md

@@ -145,9 +145,16 @@ Delivered:
 - added lease-backed writer guarantee diagnostics and surfaced disjoint write parallel candidates
 - enabled a tiny lease-backed write-capable parallel allowlist for disjoint `implement` lanes
 - added lane-level `lease_identity` metadata and enforced it for writer activation
+- started E4 ops automation readiness diagnostics with `/ship doctor` and umbrella `/doctor` coverage for canonical issue/PR/release/hotfix flows
+- added canonical `/delivery` handoff summaries to `/ship doctor` and `/ship create-pr --issue <id>` template generation
+- added latest-closure follow-up linkage auditing to `/hotfix doctor` so umbrella diagnostics can surface incident follow-up drift
+- added latest-run status summaries and stalled-handoff warnings to `/delivery doctor`
+- added `/release-train draft` narrative pickup to `/ship doctor` and `/ship create-pr` template generation
+- added umbrella `/doctor` ops-readiness aggregation across delivery, ship, release-train, and hotfix surfaces
 
 Remaining:
 - broaden write-capable parallelism beyond the tiny `implement` allowlist only when stronger lane-level lease identity and ownership guarantees exist
+- deepen E4 from readiness diagnostics into higher-touch issue/PR/release/hotfix workflow automation without introducing overlapping command surfaces
 
 ## Doing Now
 
@@ -163,6 +170,7 @@ Remaining:
 | AI-native autopilot orchestration design | doing | New design plan in `docs/plan/ai-native-autopilot-orchestration-plan.md` proposes autonomous task claims, same-worktree write leases, hard completion gates, policy injection, and retry routing for lower-touch autopilot execution; first execution slice now lives in `docs/plan/ai-autopilot-completion-gates-execution-plan.md` and is intentionally `/autopilot` + shared task-metadata first, with `/autoflow` convergence documented as follow-up adoption work rather than current-slice behavior. |
 | Gateway E2E parity refinements | doing | Tighten fail-closed behavior for critical hooks, isolate hook execution failures, align continuity wording with canonical commands, and remove hard-coded agent metadata discovery. |
 | E13 lane lease identity | doing | Active implementation tracker lives at `docs/plan/e13-shared-memory-swarm-plugin-ops-plan.md`; current slice adds lane-level lease identity to writer activation. |
+| E13 ops automation readiness diagnostics | doing | First E4 slice adds `/ship doctor`, umbrella `/doctor` coverage, and refreshed handbook/quickstart guidance so canonical issue/PR/release/hotfix automation can be audited before deeper automation lands. |
 
 ## Done Recently
 

docs/plan/docs-automation-summary.md

@@ -10,7 +10,7 @@ Generated artifact that tracks docs-automation publication coverage.
 - reason_groups: none
 - recommended_next_step: none
 
-- generated_at_utc: 2026-03-13T01:06:12Z
+- generated_at_utc: 2026-03-13T10:42:30Z
 - indexed_release_count: 22
 - latest_indexed_release: v0.4.21
 - publication_target_coverage: 3/3

docs/plan/e13-ops-automation-readiness-slice-2026-03-13.md

@@ -0,0 +1,58 @@
+# E13 Ops Automation Readiness Slice - 2026-03-13
+
+Status: `doing`
+Branch: `feat/ops-automation-slice-1`
+Worktree: `/Users/cauhirsch/Codes/Projects/my_opencode-wt-ops-automation-slice-1`
+
+## Why this slice first
+
+E13 still lists operations automation expansion as a P0 gap. The current runtime already has canonical commands for the main operator lanes:
+
+- issue delivery: `/delivery`
+- release PR prep: `/ship`
+- release packaging/publish: `/release-train`
+- incident response: `/hotfix`
+
+The immediate gap is not missing commands. It is missing cross-surface readiness visibility before operators depend on those commands more heavily.
+
+## Open requirements extracted from current docs
+
+- improve issue, PR, release, and hotfix automation without creating a second overlapping command family
+- keep canonical commands as the source of truth
+- land docs, diagnostics, and validation in the same slice when workflow behavior changes
+- make the first slice small enough to ship quickly, then deepen toward higher-touch automation later
+
+Primary source references:
+
+- `docs/plan/e13-shared-memory-swarm-plugin-ops-plan.md`
+- `docs/plan/current-roadmap-tracker.md`
+- `docs/plan/release-milestone-automation-runbook.md`
+
+## First-slice scope
+
+1. add `/ship doctor` so PR/release readiness can be audited directly from the canonical ship surface
+2. wire `/ship doctor` into umbrella `/doctor`
+3. refresh operator docs so the canonical issue/PR/release/hotfix path is easier to discover
+4. add selftest coverage for the new readiness path
+
+## Explicit non-goals
+
+- no new top-level ops command
+- no issue creation wrapper yet
+- no automatic PR/release execution beyond current guarded flows
+- no hotfix workflow redesign in this slice
+
+## Next slice candidates after this lands
+
+1. add higher-touch delivery-to-ship handoff summaries from canonical runtime state
+2. add release PR scaffolding that consumes delivery/workflow evidence directly
+3. add deterministic hotfix-to-followup issue linkage audits in umbrella doctor output
+
+## Follow-up landed in same worktree
+
+- `/ship doctor` now surfaces the latest canonical `/delivery` run summary when runtime state exists
+- `/ship create-pr --issue <id>` can inject the matched delivery handoff summary into the generated PR template without adding a new command family
+- `/hotfix doctor` now audits the latest closure for follow-up linkage completeness so umbrella `/doctor` can surface incident follow-up drift through canonical command wiring
+- `/delivery doctor` now surfaces the latest run summary and warns when the issue flow is stalled in `handoff-pending` or failed workflow states
+- `/ship create-pr` now injects `/release-train draft --include-milestones` context into the PR template so release PRs start from the latest canonical release narrative
+- umbrella `/doctor` now exposes an aggregated ops readiness summary across `/delivery`, `/ship`, `/release-train`, and `/hotfix`

docs/plan/e13-shared-memory-swarm-plugin-ops-plan.md

@@ -27,7 +27,7 @@ Status: doing
 | E1 Local shared memory runtime | P0 | doing | add durable local shared memory with deterministic retrieval | initial slice is schema + command/runtime baseline |
 | E2 Swarm coordination on current runtime | P0 | doing | layer multi-agent coordination on `workflow`, `claims`, `reservation`, and `agent-pool` | prototype lives under `/workflow swarm` first |
 | E3 Plugin platform expansion | P1 | pending | turn `gateway-core` into a safer plugin-pack platform | keep MCP out of scope |
-| E4 Operations automation expansion | P0 | pending | improve issue, PR, release, and hotfix automation | route through existing canonical commands |
+| E4 Operations automation expansion | P0 | doing | improve issue, PR, release, and hotfix automation | route through existing canonical commands; first slice is readiness diagnostics across `/delivery`, `/ship`, `/release-train`, and `/hotfix` |
 
 ## E1 Local shared memory runtime
 
@@ -92,3 +92,9 @@ Status: doing
 | 2026-03-10T17:20:00Z | E2 writer lease diagnostics | doing | Added lease-backed writer guarantee checks and surfaced disjoint write parallel candidates without enabling writer parallel execution. |
 | 2026-03-10T17:35:00Z | E2 tiny writer allowlist | doing | Enabled lease-backed parallel activation for disjoint `implement` lanes while keeping all other writer lanes serialized. |
 | 2026-03-10T17:50:00Z | E2 lane lease identity | doing | Added lane-level `lease_identity` metadata and enforced it for write-capable activation paths. |
+| 2026-03-13T21:10:00Z | E4 ops automation diagnostics slice | doing | Added `/ship doctor` and umbrella `/doctor` coverage so issue, PR, release, and hotfix automation can be audited from canonical commands before deeper workflow automation lands. |
+| 2026-03-13T21:20:00Z | E4 delivery-to-ship handoff summary | doing | Added canonical `/delivery` runtime summary pickup in `/ship doctor` plus `/ship create-pr --issue <id>` template enrichment for matched delivery runs. |
+| 2026-03-13T21:28:00Z | E4 hotfix follow-up audit | doing | Added latest-closure follow-up linkage auditing in `/hotfix doctor` so umbrella `/doctor` can surface incident follow-up drift through canonical command wiring. |
+| 2026-03-13T21:31:00Z | E4 delivery doctor status audit | doing | Added latest-run delivery summaries plus handoff-pending/workflow-failed warnings in `/delivery doctor` so issue-flow drift surfaces through canonical diagnostics. |
+| 2026-03-13T21:36:00Z | E4 release narrative enrichment | doing | Added `/release-train draft` context pickup in `/ship doctor` and `/ship create-pr` so release PR templates start from canonical release narrative plus milestone context. |
+| 2026-03-13T21:40:00Z | E4 umbrella ops readiness summary | doing | Added aggregated ops readiness output in umbrella `/doctor` so delivery, ship, release-train, and hotfix drift surfaces in one operator-facing summary. |

docs/quickstart.md

@@ -44,6 +44,7 @@ Before you start a task, create a dedicated git worktree branch from the current
 /workflow template init ship --json
 /delivery start --issue issue-900 --role coder --workflow <workflow.json> --execute --json
 /delivery status --json
+/ship doctor --json
 /init-deep --max-depth 2 --json
 /autopilot go --goal "finish current objective" --json
 /autoflow start <plan.md> --json
@@ -53,6 +54,9 @@ Before you start a task, create a dedicated git worktree branch from the current
 Use this split to stay consistent:
 
 - `/delivery` for normal issue-to-close work
+- `/ship` to preflight PR/release readiness before opening or updating a release PR
+- `/ship create-pr --issue <id>` when you want the PR template to inherit the latest canonical `/delivery` handoff context for that issue
+- `/ship create-pr --issue <id>` also pulls in current `/release-train draft` context so the PR body starts from the latest release narrative
 - `/workflow` when you need direct workflow validation or resume controls
 - `/autopilot` for open-ended autonomous execution
 - `/autoflow` for plan markdown execution

plugin/gateway-core/dist/hooks/notify-events/index.js

@@ -221,7 +221,7 @@ function terminalNotifierPath() {
     else {
         terminalNotifierBin = null;
     }
-    return terminalNotifierBin;
+    return terminalNotifierBin ?? null;
 }
 function iconPrefix(eventName, mode) {
     const emoji = EMOJI_BY_EVENT[eventName];

plugin/gateway-core/dist/hooks/shared/hook-failure.js

@@ -43,7 +43,14 @@ export function isIntentionalHookBlock(error) {
         /(question tool is disabled|task\/todowrite tools are disabled)/i.test(trimmed) ||
         /require(?:s|d)? explicit/i.test(trimmed));
 }
+function shouldSurfaceGatewayHookFailureToStderr() {
+    return (process.env.CI === "true" ||
+        process.env.MY_OPENCODE_GATEWAY_HOOK_FAILURE_STDERR === "1");
+}
 export function surfaceGatewayHookFailure(message) {
+    if (!shouldSurfaceGatewayHookFailureToStderr()) {
+        return;
+    }
     const line = `[gateway-core] ${message}\n`;
     try {
         process.stderr.write(line);

plugin/gateway-core/src/hooks/notify-events/index.ts

@@ -317,7 +317,7 @@ function terminalNotifierPath(): string | null {
   } else {
     terminalNotifierBin = null;
   }
-  return terminalNotifierBin;
+  return terminalNotifierBin ?? null;
 }
 
 function iconPrefix(eventName: NotifyEvent, mode: NotifyIconMode): string {

plugin/gateway-core/src/hooks/shared/hook-failure.ts

@@ -52,7 +52,17 @@ export function isIntentionalHookBlock(error: unknown): boolean {
   );
 }
 
+function shouldSurfaceGatewayHookFailureToStderr(): boolean {
+  return (
+    process.env.CI === "true" ||
+    process.env.MY_OPENCODE_GATEWAY_HOOK_FAILURE_STDERR === "1"
+  );
+}
+
 export function surfaceGatewayHookFailure(message: string): void {
+  if (!shouldSurfaceGatewayHookFailureToStderr()) {
+    return;
+  }
   const line = `[gateway-core] ${message}\n`;
   try {
     process.stderr.write(line);