@sugar-crash-studios/vibe-forge 0.4.0

package/docs/architecture/vibe-lab-integration.md

@@ -0,0 +1,684 @@
+# vibe-forge / vibe-lab Integration Architecture
+
+**Status:** Proposed — pending vibe-lab review
+**Date:** 2026-04-01
+**Version:** 2.1 (blockers resolved)
+**Authors:** vibe-forge architect, vibe-lab architect (synthesized)
+
+---
+
+## Platform Model
+
+vibe-forge and vibe-lab are one platform delivered in two configurations:
+
+```
+vibe-forge (standalone)
+  The interactive session layer.
+  For developers who want forge's agent model without a CI/CD pipeline.
+  Installs independently. Works without lab.
+
+vibe-lab (includes forge)
+  The full platform.
+  Lab is the pipeline protocol layer.
+  Forge is the execution runtime.
+  Installing lab installs forge. Starting lab starts forge.
+  Lab without forge is not a supported configuration.
+```
+
+The previous framing ("two systems with an integration boundary") is retired. There is one platform. The boundary that exists is between **protocol** (lab) and **execution** (forge), not between two optional peer systems.
+
+---
+
+## Why This Model
+
+Lab's existing execution model — `claude -p` headless subprocesses — is opaque by design. Status indicators on a dashboard are not the same as visibility. The "stuck" feeling is structural: you cannot distinguish a working agent from a hung one without attaching to its process.
+
+Forge terminal sessions are inherently observable. You can watch any worker in real time. You know in seconds whether it is making progress.
+
+The platform model resolves this permanently: all story execution runs through forge workers. Lab provides orchestration, handoff protocol, and release management. Forge provides every agent that does work.
+
+---
+
+## Installation and Dependency
+
+Lab declares forge as a versioned dependency:
+
+```json
+// vibe-lab/package.json
+{
+  "dependencies": {
+    "vibe-forge": "^1.0.0"
+  }
+}
+```
+
+`lab install` (or `npm install` in the lab directory) pulls forge. No separate forge install step for lab users. vibe-forge standalone users install forge directly via `npx vibe-forge` as today — unchanged.
+
+**Version constraints:** The IPC protocol between lab's dispatcher and forge's daemon is versioned independently of both packages. On startup, lab and forge perform a handshake:
+
+```
+lab → forge daemon: { "protocol": "ipc-v1", "project_id": "..." }
+forge → lab:        { "ok": true }  |  { "error": "protocol_mismatch", "supported": "ipc-v1" }
+```
+
+Transport: `POST http://localhost:2800/api/handshake` — forge's dashboard server already runs HTTP at port 2800. IPC-1 must specify this explicitly. The port is configurable in `_vibe-chain/config.yaml` under `forge.dashboard_port`.
+
+If versions are incompatible, lab falls back to degraded mode and logs a warning. Lab never fails to start because forge is on an unexpected version — it degrades gracefully.
+
+**Upgrades:** Forge updates follow semver. Minor and patch versions are compatible. Major versions may break the IPC protocol — lab's package.json pins to a major version range (`^1.0.0`) and the CI matrix validates the combination before publishing.
+
+---
+
+## Deployment Architecture
+
+When `lab start` runs, it starts two services:
+
+```
+lab start
+  ├── sentinel          (lab: filesystem watcher, pipeline state, hub sync)
+  ├── relay             (lab: WebSocket fan-out for dashboard)
+  ├── hub               (lab: API server, dashboard frontend)
+  └── forge-daemon      (forge: worker lifecycle manager, task router)
+        ├── anvil       (forge worker: frontend)
+        ├── furnace     (forge worker: backend)
+        ├── crucible    (forge worker: testing)
+        ├── sentinel    (forge worker: code review)
+        ├── architect   (forge worker: arch review)
+        └── pixel       (forge worker: UX review)
+```
+
+Forge workers run as **persistent background processes**, not terminal tabs that a human opens. The forge daemon owns worker lifetimes. Workers start with lab, run continuously, and stop with lab.
+
+Workers run with `--dangerously-skip-permissions`. There is no user-required interaction during execution. Overnight runs, unattended runs, and active session runs are identical from the pipeline's perspective.
+
+### Visibility On Demand
+
+Workers run in the background by default. When you want to observe:
+
+```bash
+forge attach anvil     # live terminal session, watch in real time
+                       # detach with Ctrl+D, worker keeps running
+```
+
+The session persists independently of whether you are watching it. This is the tmux attach model applied to agent workers.
+
+---
+
+## Security Model for Background Workers: Heimdall
+
+Forge workers run with `--dangerously-skip-permissions`. In the terminal tab model, a human can observe and intervene. In background daemon mode there is no runtime human gate. The compensating control is **Heimdall** — a pre-tool hook interceptor that guards every action before it executes.
+
+Heimdall is named for the Norse watchman of the gods, guardian of the Bifrost bridge between realms. The Bifrost here is the bridge between lab's pipeline and forge's workers. Heimdall sits at the crossing and decides what passes.
+
+```
+bin/lib/heimdall.js
+```
+
+### How Heimdall Works
+
+Claude Code's hook system fires before each tool execution. Heimdall is registered as a `PreToolUse` hook. It receives the tool name and input as JSON on stdin, checks against policy, and returns:
+
+- Exit `0` — allow (optionally with audit log entry)
+- Exit `2` — block, explanation written to stdout and fed back to the model as context
+
+The model receives the block message and reasons about it, typically self-correcting without retrying the same action.
+
+The forge daemon writes `.claude/settings.local.json` into each worker's working directory at startup:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash",       "hooks": [{ "type": "command", "command": "node bin/lib/heimdall.js" }] },
+      { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "node bin/lib/heimdall.js" }] }
+    ]
+  }
+}
+```
+
+### What Heimdall Blocks (Hard Block)
+
+**Catastrophic filesystem operations:**
+- `rm -rf` targeting any path outside `worktree_path`
+- `rm -rf /`, `rm -rf ~`, `rm -rf ..`
+- `DROP TABLE`, `TRUNCATE` (without explicit `has_db_migration: true` flag)
+- `DELETE FROM` without a WHERE clause
+
+**Path escapes:**
+- Any Write or Edit to a path outside `worktree_path`, `handoff_dir`, or `worker-inbox/`
+
+**Credential access:**
+- Any read of `.env`, `~/.ssh/*`, `~/.aws/credentials`, `**/secrets/**`
+- Any bash command assigning or echoing `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*API_KEY*`
+
+**Dangerous git operations:**
+- `git push --force` or `git push --force-with-lease`
+- `git reset --hard HEAD~` (more than one commit back)
+- `git clean -fd`
+- Any git push to a branch other than the assigned story branch
+- Any git operation targeting a remote other than `origin`
+
+### What Heimdall Logs But Allows
+
+High-risk but legitimate operations — allowed with audit log entry:
+
+- `npm install`, `pip install`, `cargo build` — dependency changes are high-signal
+- `git commit --amend` — legitimate but noted
+- Any `curl` or `wget` — destination logged
+- DB migrations when `has_db_migration: true` — explicitly authorized
+- Writes to `_vibe-chain-output/` — allowed, every write logged
+
+### Context File
+
+The forge daemon writes a context file alongside each inbox task:
+
+```json
+// _vibe-chain-output/worker-inbox/anvil/{story-id}.context.json
+{
+  "story_id": "FORGE-3",
+  "agent": "anvil",
+  "worktree_path": "G:/dev/vibe-lab/.worktrees/forge-3-events-api",
+  "assigned_branch": "feature/forge-3-events-api",
+  "handoff_dir": "G:/dev/vibe-lab/_vibe-chain-output/handoffs",
+  "has_db_migration": false,
+  "has_api_changes": true,
+  "allowed_paths": [
+    "G:/dev/vibe-lab/.worktrees/forge-3-events-api",
+    "G:/dev/vibe-lab/_vibe-chain-output/handoffs",
+    "G:/dev/vibe-lab/_vibe-chain-output/worker-inbox"
+  ]
+}
+```
+
+Heimdall reads this on every invocation. Policy is derived from task context, not global config.
+
+### Escalation: Sounding the Gjallarhorn
+
+If a worker accumulates 3 or more blocks in a single task (configurable), Heimdall writes a `{story-id}.escalation` signal file. The forge daemon detects it, logs `HEIMDALL SOUNDED`, and writes an escalation handoff. Lab's sentinel routes the story to a human review queue rather than retrying.
+
+Audit log format:
+
+```
+[2026-04-01T12:34:00Z] HEIMDALL BLOCKED anvil/FORGE-3: path escape — rm -rf ../
+[2026-04-01T12:34:01Z] HEIMDALL BLOCKED anvil/FORGE-3: credential access — read .env
+[2026-04-01T12:34:02Z] HEIMDALL SOUNDED  anvil/FORGE-3: 3 violations, escalating to human review
+```
+
+### Story
+
+**PLAT-1: Heimdall** is a prerequisite for IPC-7 (background worker daemon mode). Running workers in visible terminal tabs with a human present is an acceptable substitute. Running them as unattended background services is not — SEC-1 ships before IPC-7.
+
+```
+PLAT-1: Heimdall — forge worker pre-tool hook interceptor
+  - bin/lib/heimdall.js
+  - Context file schema (.context.json alongside each inbox task)
+  - Daemon writes .claude/settings.local.json at worker startup
+  - Audit log in forge daemon output
+  - HEIMDALL SOUNDED escalation on N violations (default: 3, configurable)
+  - Policy config in _vibe-chain/config.yaml
+  Prerequisite for: IPC-7
+  Parallel with: IPC-1 through IPC-6
+  Note: SEC-1 is already assigned to "Relay server security hardening" in the lab pipeline.
+        PLAT-1 is intentionally in a new epic (PLAT) for cross-cutting platform stories.
+```
+
+### Trust Model
+
+Workers are granted the same trust level as a human developer. This is a trust policy, not a technical capability limit. `--dangerously-skip-permissions` removes confirmation prompts — Heimdall replaces those prompts with automated policy enforcement. The underlying OS permissions are unchanged. The security gate at merge time (lab's review chain) remains the final control for output correctness.
+
+### Compromise Scenario
+
+If a worker is compromised or misbehaving, blast radius is bounded by:
+- `VIBE_LAB_FORGE_TOKEN` scope: `create_story` and `post_events` only, matching `project_id`
+- Worktree isolation: changes are in a branch, not main
+- Heimdall: blocks path escapes, credential access, and destructive operations at execution time
+- Lab's review chain: output must pass arch review, code review, and tests before merge
+
+---
+
+## Execution Layer: IPC Inbox Mechanism
+
+Lab's dispatcher does not spawn `claude -p` subprocesses for execution stages. It routes to running forge workers via the **IPC inbox mechanism**.
+
+### Inbox Location
+
+Inbox files live in the project directory alongside other handoffs:
+
+```
+_vibe-chain-output/
+  handoffs/           (existing — PR handoffs, review approvals, etc.)
+  worker-inbox/       (new — lab task files for forge workers)
+    anvil/
+      {story-id}.md
+    furnace/
+      {story-id}.md
+    sentinel/
+      {story-id}.md
+```
+
+This keeps all pipeline state visible in one place, scoped to the project, with no global `~/.forge/` state. Two lab projects on the same machine cannot collide.
+
+### Inbox Task File Format
+
+```markdown
+---
+story_id: FORGE-3
+project_id: vibe-lab
+worktree_path: G:/dev/vibe-lab/.worktrees/forge-3-events-api
+project_root: G:/dev/vibe-lab
+handoff_dir: G:/dev/vibe-lab/_vibe-chain-output/handoffs
+agent: furnace
+task_type: backend
+ipc_protocol: ipc-v1
+submitted_at: 2026-04-01T12:00:00Z
+---
+
+[lab operational instructions for this story, including exact handoff frontmatter]
+```
+
+The `worktree_path` field is mandatory — Anvil or Furnace must know which worktree to work in. This is IPC-3 territory and must be in the spec.
+
+### Routing Flow
+
+```
+Lab dispatcher has a story to execute:
+
+  1. GET http://localhost:2800/api/workers/available?task_type=backend
+     → { "available": true, "agent": "furnace", "idle_since": "..." }
+
+  2. Write _vibe-chain-output/worker-inbox/furnace/{story-id}.md
+
+  3. Forge worker's stop hook fires on next idle cycle (5-10s)
+     Worker checks worker-inbox/<self>/ before exiting
+     Finds {story-id}.md, picks it up
+
+  4. Worker writes {story-id}.picked-up to signal acceptance
+
+  5. Worker executes story in assigned worktree
+     Uses forge personality + lab operational instructions (hybrid model)
+
+  6. Worker writes pr-handoff.md to _vibe-chain-output/handoffs/
+
+  7. Lab sentinel detects the handoff, continues the pipeline
+```
+
+### Agent Availability API
+
+The forge dashboard server exposes availability at a stable endpoint:
+
+```
+GET http://localhost:2800/api/workers/available?task_type=frontend
+
+Response:
+{
+  "available": true,
+  "agent": "anvil",
+  "idle_since": "2026-04-01T12:00:00Z",
+  "current_task": null
+}
+
+Response (busy):
+{
+  "available": false,
+  "agent": "anvil",
+  "idle_since": null,
+  "current_task": "FORGE-2",
+  "estimated_free": null
+}
+
+Response (no matching worker):
+{
+  "available": false,
+  "agent": null,
+  "reason": "no_worker_configured"
+}
+```
+
+If no worker is available for the requested `task_type`, lab falls back to degraded spawn (spawn-per-story with forge personality adapter). The port `2800` is configurable in `_vibe-chain/config.yaml` under `forge.dashboard_port`. Defaults to `2800`.
+
+### Timeout and Orphan Policy
+
+**Orphan** — a task file written to the inbox but not picked up by a worker within 5 minutes. Cause: worker is crashed, stuck, or not running.
+
+**Hung task** — a task picked up (`.picked-up` signal present) but no handoff written within the stage timeout.
+
+**Stage timeouts:**
+
+| Stage | Timeout |
+|---|---|
+| Dev (frontend, backend, fullstack) | 30 minutes |
+| Code review | 15 minutes |
+| Arch review | 15 minutes |
+| UX review | 10 minutes |
+| Test runner | 20 minutes |
+
+**On orphan (not picked up within 5 min):**
+- Forge daemon writes `{story-id}.orphaned` signal file
+- Lab sentinel detects it, removes the inbox task file, falls back to degraded spawn
+- Degraded spawn proceeds identically to the Way 2 model
+
+**On timeout (picked up but no handoff within stage timeout):**
+- Forge daemon writes `{story-id}.timeout` signal file
+- Lab sentinel detects it, marks the run as failed in pipeline.db
+- Writes `{story-id}-error-handoff.md` with `status: failed, reason: worker_timeout`
+- Dispatcher picks up the error handoff on next cycle and decides retry vs escalation (same policy as today's agent failures)
+
+**Tracking:** Forge daemon maintains a `_vibe-chain-output/worker-inbox/.tracking.json` file with timestamps for each task: `submitted_at`, `picked_up_at`, `completed_at`. This is the daemon's orphan/timeout detection source. Sentinel reads it on each cycle.
+
+**Inbox cleanup:** When a story completes — handoff written and confirmed by sentinel — the forge daemon is responsible for removing `{story-id}.md`, `{story-id}.picked-up`, and the tracking entry from `.tracking.json`. Lab sentinel writes a `{story-id}.confirmed` signal file after consuming the handoff; the forge daemon watches for this before cleaning up. Ownership: forge daemon cleans, sentinel signals. IPC-5 must specify this protocol explicitly.
+
+---
+
+## Worker Context: Benefit and Tradeoff
+
+Workers accumulate codebase context across tasks within a session. A worker that just implemented a frontend feature already has the component structure loaded when the next frontend story arrives — no re-reading. This is a genuine velocity advantage.
+
+**The tradeoff:** Accumulated context means accumulated assumptions. A worker finishing UX-3 brings UX-3's mental model into UX-4. In the cold-start model, each story starts clean.
+
+**Mitigation:** The lab operational instructions delivered via the IPC inbox (IPC-3) must include a context-reset prompt at task start:
+
+```
+Before reading this task, set aside any assumptions from previous tasks.
+Treat this story as independent. Read the handoff file and the worktree
+state to form your understanding of what is needed.
+```
+
+This is a prompt instruction, not a process restart. It does not eliminate context bleed entirely but reduces the risk of a worker importing the wrong frame. Document this tradeoff in IPC-3's spec.
+
+---
+
+## Handoff Model: Hybrid Execution
+
+Forge personality files contain forge-specific task execution patterns that have no meaning in a lab worktree. Lab's sentinel validates handoff frontmatter against a schema registry — a malformed `pr-handoff.md` stalls the pipeline.
+
+**The split:** forge personalities handle the work, lab operational instructions handle the handoffs.
+
+When the stop hook delivers a lab task, the prompt is structured as:
+
+```
+[forge personality adapter — identity, principles, domain expertise, coding standards]
+[explicit: forge task execution instructions are SUSPENDED for this task]
+
+---
+
+[lab operational instructions — worktree_path, exact handoff frontmatter,
+ completion signal protocol, sprint-status update procedure]
+```
+
+Personality adapter documents live at `_vibe-chain/agents/forge/<agent>.md` — maintained in the lab repo, containing Identity and Principles from each forge personality with forge-operational sections omitted.
+
+---
+
+## Fallback: Degraded Mode
+
+When forge workers are unavailable (daemon not running, worker crashed, orphan timeout), lab falls back to spawn-per-story with forge personality adapters as prompt prefixes. This is the safety net, not the normal path.
+
+In degraded mode:
+- Lab spawns `claude -p` with the forge personality adapter prepended to the prompt
+- Execution is headless — the visibility model does not apply
+- Pipeline correctness is maintained — handoff format is identical to IPC mode
+- Workers recovering in the background resume IPC routing automatically
+
+Degraded mode is transparent from a pipeline correctness standpoint. It is visible in the forge dashboard (workers show as offline or degraded).
+
+---
+
+## Agent Roster Mapping
+
+| Pipeline Stage | Forge Worker | Notes |
+|---|---|---|
+| Dev — frontend | anvil | Frontend specialist |
+| Dev — backend | furnace | Backend/infra specialist |
+| Dev — fullstack | anvil | Default to frontend lead |
+| Code review | temper | Adversarial reviewer — NOT crucible |
+| Arch review | architect | Structural and design review |
+| UX review | pixel | Design and accessibility review |
+| Test runner | crucible | Tester and coverage writer |
+| Release manager | **lab agent-7** | Must stay lab — see below |
+
+**Crucible → test runner, forge Sentinel → code review.** This mapping is fixed.
+
+### Why Release Manager Must Stay Lab
+
+Lab's `agent-7-release-manager` is the pipeline termination agent. It is hardcoded in `SubagentManager.check_completed()`:
+
+```python
+if agent.agent_type == "release-manager" and status == "completed":
+    log_pipeline_run_complete(...)
+    remove_story_worktree(project_path, agent.story_id)
+```
+
+Any other agent in this slot means worktrees are never pruned. Stories pile up as orphans. Lab's release agent must stay lab's. Herald (forge's release agent) does not know this protocol and must not own this slot.
+
+---
+
+## Story Submission: Forge → Lab
+
+> **Long-term transport note:** `create_story` and `get_story_status` currently use sentinel's local MCP server (stdio) as transport. This is intentional for now — forge is local, sentinel is local, no network hop required. The sentinel MCP surface is a candidate for deprecation as hub MCP matures. When hub MCP reaches parity on these two tools, forge should migrate to hub MCP as the stable external-facing transport. This migration is not in the current story set but should not be designed out — forge's MCP call sites should be abstracted behind a thin client so the transport swap is a one-line config change.
+
+```
+MCP tool: create_story
+Transport: stdio (local sentinel MCP server)
+
+Required fields:
+  forge_task_id    string     task filename without extension
+  source           string     always "forge"
+  session_id       string     forge daemon session ID (correlation key)
+  task_type        enum       frontend | backend | arch | docs | test | devops | security
+  urgency          enum       low | normal | high
+  skip_reviews     string[]   default []
+  has_db_migration boolean    default false
+  has_api_changes  boolean    default false
+
+Optional fields:
+  estimated_scope  enum       small | medium | large (defaults to "medium" when absent)
+```
+
+**urgency → priority mapping** (resolved in FORGE-1):
+
+| urgency (forge) | priority (lab) |
+|---|---|
+| low | low |
+| normal | medium |
+| high | high |
+
+`has_db_migration: true` — suppresses fast-lane, forces full arch review.
+`has_api_changes: true` — forces code review even on small scope.
+Both fields must be wired to Dispatcher routing logic at FORGE-1 time. Storing without acting is not sufficient.
+
+---
+
+## Event Stream: Forge → Lab
+
+```
+HTTP POST /api/projects/:id/events
+Auth: Bearer VIBE_LAB_FORGE_TOKEN
+
+{
+  "source": "forge",
+  "type": "forge-session-started | forge-session-ended | forge-agent-started |
+            forge-agent-idle | forge-task-started | forge-task-completed |
+            forge-task-escalated",
+  "agent": "anvil",
+  "task_id": "task-042",
+  "session_id": "abc123",
+  "timestamp": "<ISO8601>",
+  "metadata": { "agent_display_name": "Anvil", "task_title": "Add login form" }
+}
+```
+
+Fire-and-forget. `|| true`. Never blocks worker execution.
+
+---
+
+## Status Feedback: Lab → Forge
+
+**Story status query (FORGE-5)**
+
+```
+MCP tool: get_story_status
+Parameters: forge_task_id, project_path
+Returns: { lab_story_id, found, status, title, assigned_to, started, completed, pr, branch }
+```
+
+Called by the forge daemon at idle maintenance cycles. Non-fatal if lab is unreachable.
+
+**Real-time relay subscription (FORGE-6)**
+
+```
+WebSocket: wss://<relay-host>/subscribe?project=<project-id>
+Auth: first-message → { "auth": "<VIBE_LAB_FORGE_TOKEN>" }
+
+Forge subscribes to: story_transition, agent_completed, queue_summary
+Forge ignores: heartbeat, agent_start
+
+Relay event envelope (all forge-originated events):
+{
+  "project_id": "vibe-lab",        ← explicit project ID, not just "project" alias
+  "project": "vibe-lab",           ← existing field, kept for relay compatibility
+  "event": "story_transition",
+  "story": "FORGE-3",
+  "forge_task_id": "FORGE-TASK-42",
+  "from_status": "in-progress",
+  "to_status": "review",
+  "timestamp": "<ISO8601>"
+}
+
+Both `project_id` and `forge_task_id` must be present on all events for forge-originated stories.
+Thread through: DB → sentinel event → relay broadcast.
+`project_id` is the authoritative cross-project discriminator. Forge uses it, not `story`, to correlate events.
+
+Forge maintains one relay connection per lab project. If forge manages multiple lab projects simultaneously,
+it opens one WebSocket subscription per project_id and routes incoming events by project_id before
+dispatching to the appropriate local tracking entry.
+```
+
+Relay validates `VIBE_LAB_FORGE_TOKEN` against hub DB on connect. Fail closed if hub unreachable.
+
+---
+
+## Authentication
+
+**One credential: `VIBE_LAB_FORGE_TOKEN`**
+
+- Environment variable only — never written to any committed file or log
+- Injected into forge daemon process only, not passed to worker subprocesses
+- Hub enforces scope: `create_story` and `post_events`, `source == "forge"`, matching `project_id` only. All other calls 403.
+- Rate limit: 5 `create_story` per 10-second window per `session_id`. 429 + `Retry-After`. Forge retries on next sync cycle.
+- Relay: validated against hub DB on connect, cached for session lifetime, re-validated on reconnect, fail closed.
+
+---
+
+## Story Ownership
+
+Once a story enters the lab pipeline, **lab owns the execution lifecycle unconditionally.**
+
+Forge creates a story and submits it. Lab routes it to forge workers for execution, sequences the review chain, merges, and releases. Forge workers cannot modify, reprioritize, or cancel an in-progress story.
+
+Forge must not re-submit a story that already has an entry in `.forge/lab-stories.json`. The tracking file is keyed by `{project_id}/{forge_task_id}` — not by story ID alone — because vibe-lab manages multiple projects and story IDs are only unique within a project, not across them.
+
+```json
+// .forge/lab-stories.json
+{
+  "vibe-lab/FORGE-TASK-42": {
+    "project_id": "vibe-lab",
+    "forge_task_id": "FORGE-TASK-42",
+    "lab_story_id": "FORGE-3",
+    "status": "in-progress",
+    "last_checked": "2026-04-01T12:00:00Z"
+  },
+  "vibe-api/FORGE-TASK-07": {
+    "project_id": "vibe-api",
+    "forge_task_id": "FORGE-TASK-07",
+    "lab_story_id": "FORGE-3",
+    "status": "backlog",
+    "last_checked": "2026-04-01T11:00:00Z"
+  }
+}
+```
+
+Note both entries above have `lab_story_id: "FORGE-3"` — valid, because they are in different projects. The `{project_id}/{forge_task_id}` composite key is what makes them distinct.
+
+---
+
+## Full Story Set and Sequencing
+
+### FORGE Stories — pipeline plumbing
+
+```
+FORGE-7 (ownership policy doc, co-authored)
+    ↓
+FORGE-1 (create_story forge fields + DB migration + urgency mapping + routing wiring)
+    ↓
+FORGE-5 (get_story_status MCP tool)
+    ↓
+FORGE-2 (CORS + scoped forge token)
+    ↓
+FORGE-3 (events API)                                    ┐
+FORGE-4 (forge sessions dashboard panel, relay push)    ├── parallel
+FORGE-6 (relay subscription + forge_task_id threading)  ┘
+```
+
+### LAB-FORGE Stories — personality execution layer
+
+```
+LAB-FORGE-1 (agent_personalities config schema)              ─── start now
+LAB-FORGE-2 (personality adapter docs: all agents)           ─── parallel
+    ↓
+LAB-FORGE-3 (SubagentManager personality_prefix + context-reset prompt)
+    ↓
+LAB-FORGE-4 (Dispatcher personality routing)
+    ↓
+LAB-FORGE-5 (integration test — forge personality end-to-end, validates handoff format)
+```
+
+### IPC Stories — persistent worker routing (the full vision)
+
+*Starts after LAB-FORGE-5 confirms handoff format correctness.*
+
+```
+IPC-1 (forge daemon: agent availability API at /api/workers/available)
+IPC-2 (forge: worker-inbox/ directory structure + stop hook lab inbox check)    ┐ parallel
+IPC-3 (forge: inbox task file format, worktree_path field, context-reset prompt)┘
+    ↓
+IPC-4 (lab: Dispatcher routing — availability check → inbox write vs degraded spawn)
+IPC-5 (lab: sentinel inbox watcher + .picked-up detection + timeout policy + orphan fallback)
+    ↓
+IPC-6 (lab: integration test — warm worker story end-to-end)
+    ↓
+IPC-7 (forge: background worker lifecycle — daemon-managed processes, forge attach)
+  Spec note: `forge attach` on Windows requires explicit design. tmux is not native on Windows.
+  Candidates: Windows Terminal tab re-attach, named pipe, or Node.js/Bun PTY multiplexer.
+  IPC-7's spec must choose and document the mechanism before implementation starts.
+```
+
+```
+PLAT-1 (Heimdall — pre-tool hook interceptor)   ─── parallel with IPC-1 through IPC-6
+                                                     prerequisite for IPC-7
+  Applicability note: Heimdall also applies to LAB-FORGE degraded spawn (which also runs
+  with --dangerously-skip-permissions). LAB-FORGE-3 (SubagentManager personality prefix
+  injection) must write .claude/settings.local.json to the worktree at spawn time, the same
+  as IPC workers. Heimdall is not IPC-7-only — it applies to every worker that runs
+  with --dangerously-skip-permissions, supervised or not.
+```
+
+IPC-7 is the final piece: daemon-managed background workers replace human-spawned terminal tabs. After IPC-7, forge workers are always running as part of lab, with no human startup required.
+
+---
+
+## What Stays Separate
+
+- **Codebases and repositories.** Deployment merger, not code merger. Forge's bash daemon, worker loop, personality files, and filesystem-as-state remain in the forge repo. Lab's sentinel, hub, relay, and review chain remain in the lab repo. Lab declares forge as an npm dependency.
+- **vibe-forge standalone.** Continues to ship and work independently. Forge-only users install and use forge without lab. Unchanged.
+- **Forge's internal task model.** `backlog/`, `in-progress/`, `completed/` filesystem is unchanged for forge-native tasks. Lab stories arrive via `worker-inbox/` — a separate path that does not disturb forge's own task queue.
+
+---
+
+## What This Is Not
+
+- Forge is not being rewritten to fit lab's stack. Language boundary preserved.
+- Lab is not adopting bash. Lab's sentinel, hub, and relay remain Python/TypeScript.
+- The release manager is never a forge worker. It must remain `lab/agent-7-release-manager`.
+- Forge workers in lab's pipeline are not headless subprocesses. They are real Claude Code sessions, observable on demand via `forge attach`.
+- Human presence is not required for the pipeline to run. Workers run as background services. Human presence enables visibility, not operation.
+- Background workers with `--dangerously-skip-permissions` are not ungated. Heimdall provides pre-execution policy enforcement at tool-call time. Lab's review chain provides output correctness validation at merge time. Both gates are active.