docs: OpenCode plugin live-verification learning#192
Merged
Conversation
fro-bot
approved these changes
Jul 10, 2026
fro-bot
left a comment
fro-bot
left a comment
Owner
There was a problem hiding this comment.
Verdict: PASS
Docs-only addition (docs/solutions/workflow-issues/opencode-plugin-hooks-need-live-verification-2026-07-10.md, +128/-0). No code, config, or CI changes — verified via gh pr diff.
Blocking issues
None
Non-blocking concerns
None
Missing tests
Not applicable — documentation-only change with no runtime or release impact.
Risk assessment
LOW — this is a solutions-doc entry with no code, dependency, auth, or workflow changes. Verified:
- All four cross-linked docs in the "Related" section exist in the repo (
unit-green-is-not-feature-done...,pwa-service-worker-registration-invisible-to-unit-tests...,dev-server-hang-background-no-watch-kill-orphans...,local-fixture-harness-must-mirror-wire-contract...). - Frontmatter shape (
category,problem_type,applies_when,tags) matches conventions used elsewhere indocs/solutions/workflow-issues/. - No secrets, tokens, or credentials present in the file.
Run Summary
| Field | Value |
|---|---|
| Event | pull_request |
| Repository | fro-bot/dashboard |
| Run ID | 29131030260 |
| Cache | hit |
| Session | ses_0b194e51bffeqE57BUGnx02QR0 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures the durable lesson from building the OpenCode Impeccable plugin (#191): an OpenCode plugin's real contract — the host loader's export semantics and the subprocess env/stdin/stdout contract — lives outside the unit-test boundary. Four distinct silent-failure bugs each passed the full unit suite,
tsc, and lint clean, and were caught only by live-session verification, one restart cycle each.The doc records the verification protocol that would have caught them sooner: restart after any plugin change, confirm the plugin actually loaded (grep the host log), exercise the real path, cross-check side-effect evidence (subprocess cache mtime) rather than just the visible result, keep the plugin module to a single function export, probe the subprocess boundary directly to isolate bugs without a restart per hypothesis, and design a fail-loud path that can actually fire when the subprocess always exits 0.
Cross-linked into the existing "local green ≠ production truth" cluster (unit-green, pwa-service-worker, dev-server-hang, fixture-harness). Docs-only — no runtime or release impact.