gate-l3-lifecycle-integration

Files (16)

• SKILL.md
• evals.json · evals/
• .gitkeep · metrics/
• rich-gate-scorecard.md · metrics/
• adopted-patterns.md · references/
• anti-patterns.md · references/
• cqrs-boundaries.md · references/
• evaluation-checklist.md · references/
• gap-documentation.md · references/
• nine-surface-authority.md · references/
• perspective-rubrics.md · references/
• remediation-paths.md · references/
• sdk-compliance.md · references/
• triad-flow.md · references/
• run-gate-eval.sh · scripts/
• gate-report.md · templates/

SKILL.md (first lines)

# Gate: Lifecycle Integration

Internal quality gate for Hivemind harness architecture compliance. Not for end-user
shipping. Activates during every gatekeeping workflow related to harness or OpenCode
integration work.

## Activation Detection

Load this skill when:
- Code review of files in `src/` (any subdirectory)
- Phase audit or milestone verification touching harness modules
- Integration check after tool/hook/delegation changes
- Deployment readiness for `hivemind` npm package
- Any workflow referencing `gate-lifecycle-integration`

## Do NOT Load

Skip when working on `.opencode/` soft meta-concept authoring, end-user feature
development, non-Hivemind code reviews, documentation, or artifacts in
`src/shared/`/`src/schema-kernel/` (use lighter classification check instead).

## Two-Halves Classification (Q6)

Every artifact must land in exactly one of three roots:

| Root | Contents | State Authority |
|------|----------|-----------------|
| `src/` (Hard Harness) | Tools, hooks, plugin, shared, lib | Writes to `.hivemind/` via managers only |
| `.opencode/` (Soft Meta-Concepts) | Skills, agents, commands, rules | No persistent state — OpenCode primitives only |
| `.hivemind/` (Deep Module State) | Journals, continuity, delegation records | Canonical state root (Q6) |

Cross-contamination between roots is a **BLOCK** finding. Tools never write to
`.opencode/`. Hooks never write to `.hivemind/` directly — they route through
`DelegationManager` or `continuity.ts`.

## 9-Surface Mutation Authority

The architecture defines 9 surfaces across write-side (4), read-side (3), and
assembly (1). Each artifact must conform to its surface's authority boundaries.

> **Full table with constraints**: `references/nine-surface-authority.md`
>
> Source: `.planning/codebase/ARCHITECTURE.md` § "9-Surface Mutation Authority"

Quick summary — write-side: `continuity.ts`, `delegation-persistence.ts`,
`session-journal.ts`, `DelegationManager`. Read-side: hooks, tools, sidecar.
Assembly: `plugin.ts`.

## OpenCode SDK Surface Compliance

Validate against the real `@opencode-ai/plugin` v1.14.28 API surface. Three areas:

1. **tool() factory**: `description`, `args` (Zod), `execute` → string. Registered in plugin.ts.
2. **Hook handlers**: Exactly 4 hooks (`tool.execute.before/after`, `experimental.session.compacting`, `shell.env`).
3. **Plugin composition**: Async function, type-only imports, no inline business logic, lazy PTY.

> **Full checklists with real signatures**: `references/sdk-compliance.md`
>
> Additional context: `stack-opencode` skill for broader SDK reference.

## CQRS Boundary Enforcement

Write-side (tools) mutate state via managers. Read-side (hooks) observe events.
Events flow write→read, never reverse. 7 BLOCK-level anti-patterns detect violations
(e.g., `AP-WRITE-FROM-READ`, `AP-CROSS-ROOT-WRITE`, `AP-BYPASS-MANAGER`).

> **Full write/read checklists + anti-pattern table**: `references/cqrs-boundaries.md`
>
> Expanded anti-pattern catalog: `references/anti-patterns.md`

## Delegation Hierarchy Constraints

Validate against runtime constants from `src/lib/types.ts`:

| Constant | Value | Meaning |
|----------|-------|---------|
| `MAX_DELEGATION_DEPTH` | 3 | Max nested delegation depth |
| `MAX_DESCENDANTS_PER_ROOT` | 10 | Max child delegations per root session |
| `STABLE_POLLS_REQUIRED` | 3 | Consecutive unchanged polls for completion |
| `TASK_CLEANUP_DELAY_MS` | 600000 | Grace period before cleanup (10 min) |

Check: uses `DelegationManager.dispatch()`, valid category, depth ≤ 3, WaiterModel
dispatch, dual-signal completion, recovery guarantee via `recoverPending()`.

## Decision Tree

```
START → Classify the artifact by file location:
  ├─ src/tools/*.ts → TOOL: tool() registration, Zod, response envelope,
  │     SDK mutation via session-api.ts, state via continuity.ts, LOC < 200
  ├─ src/hooks/*.ts → HOOK: factory pattern, real SDK signature, CQRS readonly
  ├─ src/lib/*.ts → LIBRARY: dependency ≤ 2 levels, LOC < 500, no `any`, tests
  ├─ src/plugin.ts → COMPOSITION: LOC < 200, all registered, no inline logic
  ├─ src/shared/*.ts, src/schema-kernel/*.ts → LEAF: cross-cutting utility
  └─ DELEGATION participant? → DelegationManager, category, depth, dual-signal
```

For each branch, execute the detailed checklist in `references/evaluation-checklist.md`.

## Self-Correction

### Mode 1: When Classification Is Ambiguous

If a file straddles two classification roots (e.g., a test helper in `src/shared/` that also reads `.hivemind/` state), classify by primary purpose. Helpers that are pure utility = LEAF (src/shared/). Helpers that read persistent state = suspect — check if they route through a manager. Never classify as LEAF to bypass the lifecycle gate.

### Mode 2: When CQRS Boundary Is Fuzzy

Some tools produce side effects that look like state reads (e.g., delegation-status.ts reads delegation records). This is correct CQRS: the tool reads through a query API, not by subscribing to events. Distinguish: direct event subscription in a tool = BLOCK; query API call in a tool = PASS.

### Mode 3: When Plugin.ts Exceeds LOC Limit

If plugin.ts exceeds 200 LOC but the excess is purely registration boilerplate (many tools/hooks), document the finding as WARNING rather than BLOCK. If the excess includes inline business logic, BLOCK. Registration-only LOC inflation is acceptable; logic inflation is not.

### Mode 4: When Delegation Depth Is At Limit

A delegation chain at exactly MAX_DELEGATION_DEPTH (3) is PASS — the limit is inclusive. However, if depth=3 and the chain also uses queue keys without buildDelegationQueueKey(), flag as WARNING. At-limit depth with correct queue key construction = PASS. At-limit depth with manual key construction = WARNING (fragile).

## Gate Orchestrator Integration

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin