Establish periodic upstream review process for OpenWolf developments

[jcmrs]

Summary

OpenWolf (cytostack/openwolf) is our upstream project. While OpenOwl is architecturally different (OpenCode vs Claude Code), many concepts, patterns, and security findings are transferable. We need a structured process for periodically reviewing upstream developments without attempting mechanical feature porting.

Proposed Process

Periodic Upstream Review (suggested: bi-weekly or on notable upstream activity)

Each OpenWolf PR/issue gets classified into one of three buckets:

Classification	Meaning	Action
Adopt	Concept applies directly to OpenOwl	Implement or investigate promptly
Adapt	Concept is relevant but needs OpenCode-native reimplementation	Design and schedule
Skip	Claude-specific or not applicable	No action, note why

What to extract, not what to port

The key distinction: we port concepts and problems solved, not implementations. The implementation layer is fundamentally different (Claude Code SDK hooks vs OpenCode plugin hooks).

Example: OpenWolf PR #18 (worktree brain sharing) — the problem (shared brain files across worktrees) is universal. The implementation (parsing .git file, two-tier .wolf/ structure) may be transferable but must be validated against OpenCode's architecture.

Special categories

• Security items — Always triage as Adopt regardless of scope. Dashboard auth, network exposure, and input validation issues likely apply to both projects.
• Scanner enhancements — Language/framework support may differ since Claude Code and OpenCode may have different file-type affinities, but the pattern of extending scanner heuristics is transferable.
• Dashboard features — UI/UX improvements and data visualizations are likely directly applicable since both use React.

Known Caveats and Gaps

1. Hook architecture mismatch — OpenWolf uses Claude Code's PreToolUse/PostToolUse SDK hooks. OpenOwl uses OpenCode's tool.before/tool.after plugin hooks. A feature that depends on Claude-specific hook capabilities (e.g., tool parameter interception semantics) may not have a direct OpenCode equivalent.

2. Command structure divergence — OpenWolf's CLI is openwolf init, openwolf scan, etc. OpenOwl's is npx openowl init, npx openowl scan. Feature parity at the CLI level doesn't mean implementation parity.

3. Upstream may adopt our patterns — PR #9 (OpenCode support) shows upstream is aware of OpenCode. Future upstream changes may already account for OpenCode patterns, reducing the need for separate adaptation.

4. Dependency differences — OpenWolf and OpenOwl may diverge in optional dependencies (chokidar, express, node-cron, ws). A feature relying on a dependency we've dropped may need rearchitecting.

5. No guarantee of forward compatibility — Upstream breaking changes could invalidate assumptions in our adaptation layer. We should pin review to specific upstream versions/tags, not just follow main.

6. Review scope may miss indirect changes — Focusing on PRs/issues may miss refactors, internal API changes, or dependency updates that affect our adaptation assumptions.

Practical Implementation

• Create a .owl/upstream-review.md to track triaged PRs with classification and notes
• Use gh CLI to automate fetching new upstream PRs since last review
• Include upstream review as a standing agenda item or periodic task