lazyopencode-core 0.0.1

package/docs/product-audit.md

@@ -0,0 +1,187 @@
+# Product Audit
+
+## Verdict
+
+LazyOpenCode should be positioned as an OpenCode-native governed team runtime.
+
+It should not be framed as only a scope gate, only an agent pack, or only a
+prompt toolbox. The product combines three things:
+
+- A zero-config OpenCode team runtime.
+- A governance layer for scope, risk, budget, permissions, and closure.
+- A future Desktop distribution that makes those defaults visible and easy.
+
+The current `0.0.1` core is close to a usable kernel: commands, agents, skills,
+runtime state, job board, council guard, token control, doctor output, and close
+report all exist and pass verification. The next work is mostly deepening,
+simplifying, and making the boundaries sharper.
+
+## Product Positioning
+
+### Category
+
+OpenCode-native governed team runtime.
+
+### Promise
+
+Turn OpenCode into a small, visible, budgeted, reviewable AI coding team.
+
+### Audience
+
+- OpenCode users who want a complete default setup.
+- Users who want subagents, but do not want unmanaged agent sprawl.
+- Developers who care about risk control, review, and closure.
+- Future Desktop users who expect the system to work without hand-assembling
+  config.
+
+### Enemy
+
+- Vague requests entering implementation.
+- Agent work that cannot be reconciled.
+- Background jobs that disappear from working memory.
+- Large changes without success criteria or must-not-break constraints.
+- “Done” responses without tests, review, simplification, or risk notes.
+- Tooling that requires users to assemble too many pieces manually.
+
+### North Star
+
+Small scope, visible work, bounded context, reviewed output.
+
+## Product Capabilities
+
+### Current Strengths
+
+- `lazy` primary agent plus focused subagents.
+- `/lazy start` classification and workflow gate.
+- `/lazy status` with mode, workflow, jobs, token control, OpenCode snapshot,
+  and recent decisions.
+- `/lazy close` with a structured close report.
+- `/lazy doctor` for install and runtime health.
+- Background job state machine with running, terminal, reusable, and stale jobs.
+- Guarded council escalation for high-risk, ambiguous, or debug work.
+- Message-count context budget with pruning stats.
+- Permission guard for destructive operations.
+- Zero-config defaults with optional `lazyopencode` config.
+- Deno maintainer toolchain with npm ESM runtime output.
+
+### Current Gaps
+
+- `LazyRuntime` is too broad and owns too many responsibilities.
+- Close evidence collection is useful but heuristic.
+- OpenCode control-plane integration is best-effort and needs real-client
+  hardening as OpenCode v2 surfaces mature.
+- Worktree isolation is advice/policy, not full automation.
+- Doctor output checks the important basics, but should become a deeper module
+  with structured checks.
+- Desktop is intentionally not implemented in `0.0.1`.
+
+## Project Design
+
+### Desired Layers
+
+1. OpenCode adapter layer:
+   - v2 registration
+   - legacy hook adapter
+   - control-plane snapshot
+   - tool/session/permission/event bridge
+
+2. Governance core:
+   - classifier
+   - gate
+   - delegation discipline
+   - job board
+   - token budget
+   - close report
+   - doctor
+
+3. Distribution layer:
+   - default config
+   - documentation
+   - Desktop packaging and health UI in `0.1.0`
+
+### Current Structure
+
+The current package layout is understandable:
+
+- `src/agents`
+- `src/hooks`
+- `src/council`
+- `src/skills`
+- `src/tools`
+- `src/opencode-control-plane.ts`
+- `src/v2.ts`
+
+The main structural issue is that `src/hooks/runtime.ts` has become a central
+god module. It works, but future changes will be easier if runtime becomes a
+small facade over deeper modules.
+
+## Framework And Technical Choices
+
+### Keep
+
+- npm ESM package as the user runtime.
+- Deno as the maintainer all-in-one toolchain.
+- TypeScript strict mode.
+- Local rule-based classifier for `0.0.x`.
+- Message-count budget instead of provider-specific token accounting.
+- No new runtime dependencies unless a feature truly requires one.
+- Legacy hook adapter while v2 lacks equivalent governance hook coverage.
+
+### Revisit
+
+- The minimum supported `@opencode-ai/plugin` version should be explicit.
+- Runtime internals should be split before adding more features.
+- Close report evidence should eventually use stronger sources such as diff,
+  test command results, and OpenCode todos when available.
+- Worktree isolation should remain advisory until OpenCode exposes a stable
+  project-copy/worktree control plane.
+
+## Code Quality Audit
+
+### Good
+
+- `npm run verify` passes.
+- Generated package includes `dist`, docs, README, license, attribution, and
+  lazy skills.
+- Old JS test copies are removed; TS/Deno tests are the authority.
+- Stale renamed agent files are absent from `dist`.
+- Public agent names avoid known collision-prone generic names.
+- Persistence stays outside the project repo by default.
+
+### Needs Work
+
+- `runtime.ts` is approximately 900 lines and mixes config, persistence,
+  workflow state, doctor, OpenCode snapshot, close report, and formatting.
+- `messages-transform.ts` mixes pruning, image handling, job-board injection,
+  workflow gate, and skill filtering.
+- `background-job-board.ts` is large but more cohesive; it can stay until runtime
+  is split.
+- Tests are integration-heavy; after module split, add narrower tests for
+  doctor, close report, status formatting, and persistence.
+
+## Product Boundary
+
+LazyOpenCode should not require another OpenCode plugin to provide its core team
+runtime. It can learn from adjacent products, but the public product should feel
+complete on its own.
+
+Compared with lightweight agent-routing plugins, LazyOpenCode includes routing
+but adds governance and closure.
+
+Compared with autonomous coding assistants, LazyOpenCode stays OpenCode-native
+and prioritizes controlled engineering workflow over long independent runs.
+
+Compared with future Desktop distributions, `@lazyopencode/core` is the source
+of truth. Desktop should package and visualize core behavior, not duplicate it.
+
+## Release Readiness
+
+`0.0.1` is releaseable once these stay true:
+
+- `npm run verify` passes.
+- README and docs use governed team runtime positioning.
+- No stale renamed agents are packed.
+- No JS test duplicates remain.
+- `/lazy start`, `/lazy status`, `/lazy close`, and `/lazy doctor` remain covered
+  by tests.
+- Desktop work is documented as a later stage, not implied as complete.

package/docs/product-plan.md

@@ -0,0 +1,56 @@
+# LazyOpenCode 0.0.1 Governed Runtime Plan
+
+LazyOpenCode 0.0.1 ships a minimum complete governed team runtime for OpenCode:
+
+`/lazy start <task>` -> classify -> gate or allow -> track -> close with review or simplification.
+
+The long-term product shape is OpenCode-native: core provides the governed team
+runtime, and Desktop becomes the preinstalled distribution in `0.1.0`.
+
+## Product Contract
+
+- Classify task risk and ambiguity.
+- Gate high-risk or ambiguous work until scope is clear.
+- Track background jobs, terminal jobs, reusable sessions, and stale sessions.
+- Budget message context and council escalation.
+- Ask before destructive commands.
+- Close implementation work with review, simplify, and verification.
+
+## 0.0.1 Boundaries
+
+Included:
+
+- Governed team runtime positioning and docs.
+- `/lazy` command namespace.
+- Runtime config and persistence.
+- Rule-based workflow classifier.
+- Shared runtime for hooks.
+- Token-control layer for bounded messages, image redirects, skill filtering, summarized job state, and mini job board status.
+- Council eligibility guard for high-risk, ambiguous, or debug escalation.
+- Permission guard for destructive OpenCode permission requests.
+- Hardened job board semantics.
+- Skill output contracts.
+- Verification scripts and tests.
+- deepwork mode for focused single-goal sessions.
+- OpenCode v2 default registration with legacy hook adapter.
+- `/lazy doctor`, close evidence capture, and Desktop health snapshot support.
+
+Not included:
+
+- UI.
+- Desktop fork implementation.
+- MCP marketplace.
+- GitHub issue automation.
+- Provider marketplace.
+- Full worktree automation.
+- Model-based classification.
+- Deno as user runtime requirement.
+- Desktop copying core governance rules.
+
+## Release Criteria
+
+- README and docs describe governed team runtime positioning.
+- `/lazy start`, `status`, `reset`, `mode`, `explain`, `review`, `simplify`, `debug`, `close`, `doctor`, and `deepwork` work in integration tests.
+- Runtime state survives save/load and marks previously running jobs as stale.
+- Permission guard and zero-config merge tests pass.
+- `npm run verify` passes.

package/docs/state-machine.md

@@ -0,0 +1,35 @@
+# Job State Machine
+
+## States
+
+- `running`: task has launched and may still produce output
+- `completed`: task ended successfully and is terminal unreconciled
+- `error`: task ended with an error and is terminal unreconciled
+- `cancelled`: task was cancelled and is terminal unreconciled
+- `reconciled`: successful completed task acknowledged by the parent session
+- `stale`: task was running before process restart and cannot be trusted as running
+
+## Transitions
+
+- launch -> `running`
+- task output completed -> `completed` + terminal unreconciled
+- task output error -> `error` + terminal unreconciled
+- task output cancelled -> `cancelled` + terminal unreconciled
+- session idle reconcile completed -> `reconciled`
+- persisted running load -> `stale`
+- session deleted -> removed
+
+## Reusable Sessions
+
+`reusable` is derived, not stored as a state.
+
+A job is reusable only when:
+
+- state is `reconciled`
+- terminal unreconciled is false
+
+`error`, `cancelled`, and `stale` jobs are never reusable.
+
+## Restart Recovery
+
+Persisted `running` jobs become `stale` after load. They remain visible in `/lazy status` so the user can see the interrupted work, but they are not reused.