# WP3: plugins/mosaic-framework — OC Rails Injection Plugin

## Context

Port the OpenClaw framework plugin from ~/src/mosaic-stack/oc-plugins/mosaic-framework/ to `plugins/mosaic-framework` in this monorepo. This plugin injects Mosaic framework contracts (rails, completion gates, worktree requirements) into every OpenClaw agent session.

**This is SEPARATE from plugins/macp:**

- `mosaic-framework` = passive enforcement — injects rails into all OC sessions
- `macp` = active runtime — provides ACP backend for MACP task execution

## Source Files

**Source:** `~/src/mosaic-stack/oc-plugins/mosaic-framework/`

- `index.ts` — plugin hooks (before_agent_start, subagent_spawning)
- `openclaw.plugin.json` — plugin manifest
- `package.json`

## What It Does

### For OC native agents (before_agent_start hook):

- Injects Mosaic global hard rules via `appendSystemContext`
- Completion gates: code review ✓ | security review ✓ | tests GREEN ✓ | CI green ✓
- Worker completion protocol: open PR → fire system event → EXIT — never merge
- Worktree requirement: `~/src/{repo}-worktrees/{task-slug}`, never `/tmp`
- Injects dynamic mission state via `prependContext` (reads from project's `.mosaic/orchestrator/mission.json`)

### For ACP coding workers (subagent_spawning hook):

- Writes `~/.codex/instructions.md` or `~/.claude/CLAUDE.md` BEFORE the process starts
- Full runtime contract: mandatory load order, hard gates, mode declaration
- Global framework rules + worktree + completion gate requirements

## Implementation

Port the TypeScript source, updating hardcoded paths to be configurable. The OC plugin SDK imports should reference the installed OpenClaw location dynamically (not hardcoded `/home/jarvis/` paths like the OLD version).

**Structure:**

```
plugins/mosaic-framework/
├── src/
│   └── index.ts
├── openclaw.plugin.json
├── package.json
└── tsconfig.json
```

## Key Constraint

The plugin SDK imports in the OLD version use absolute paths:

```typescript
import type { OpenClawPluginApi } from '/home/jarvis/.npm-global/lib/node_modules/openclaw/dist/plugin-sdk/index.js';
```

This must be resolved dynamically or via a peer dependency. Check how `plugins/macp` handles this in the new repo and follow the same pattern.

## Tests

Minimal — plugin hooks are integration-tested against OC runtime. Unit test the context string builders and config resolution.