# Spec 004: Masterplan and shared context

Status: draft revision 1 for review
Date: 2026-08-08
Depends on: [Spec 000](spec-000-system-overview.md) and [Spec 001](spec-001-core-and-live-work.md)

## Outcome

People can see what they are building, why, and in what order across projects.
Project members edit the same plan live. General Chat and FirstMate receive the
small relevant slice instead of guessing priorities from the whole account.

This spec owns planning state, timeline presentation, revision-safe editing,
and agent context. It does not schedule or execute work.

## Two plan scopes

Every Project has one shared Masterplan. Active project members see it according
to their role, and editors may change it.

Each user also has one private plan for personal outcomes. The top-level
Masterplan screen is a projection of that private plan plus every Project plan
the user may access. It is not one cross-project mutable document.

New nodes created while a Project is selected are project-linked by default.
Parent and child always belong to the same plan. Personal context never becomes
project context implicitly.

## Minimal node model

```text
id
plan_id
parent_id optional
kind = project | milestone | task
title
goal and short summary
status = idea | planned | active | blocked | paused | done
progress 0..100
start and end optional
color and sort order
budget and KPIs optional
linked conversation, execution, result, or Loop IDs optional
revision metadata and actor
```

Blank dates are valid and remain blank. The UI may place undated work in an
“unscheduled” lane, but it never invents dates. Dates describe intent; they do
not trigger execution.

Hierarchy must be acyclic. Deleting a parent requires an explicit archive or
confirmed subtree action. Normal history is retained through project events.

## One plan command path

Create, update, reparent, reorder, and archive are application Commands from
Spec 001. Each targets one exact plan revision. The node change and
`masterplan.changed` event commit together.

Stale edits return a revision conflict with the current node and plan revision.
The client reloads and lets the user reapply the edit; it never silently chooses
last write wins.

FirstMate, MCP, browser forms, and future Loops call the same commands. No tool
or integration edits plan storage directly.

## Interface direction

The visual reference is the public `joetann.com/masterplan` timeline, combined
with Godloop v1's live project integration and fixed ruler.

Desktop uses:

- a calm full-width timeline with project lanes and hierarchy edges;
- a ruler fixed to the top while the world pans and zooms;
- Today, fit, zoom, project, and status controls;
- compact color-coded cards with status, progress, and duration;
- a side inspector for goal, dates, parent, budget, KPIs, and linked work;
- an accessible list representing the same filtered data.

Layout is derived from plan, hierarchy, dates, and sort order. V2 does not store
arbitrary card coordinates or build a generic dashboard canvas.

On narrow screens, the default is an ordered list grouped into Now, Next,
Blocked, and Later. A timeline toggle is available, with horizontal time
navigation and the ruler retained. Users should not need to pinch a desktop
canvas to understand the plan at 320px or 390px.

Selection is encoded in the URL. Personal pan, zoom, filters, and chosen view
may stay in browser state and never overwrite another member's view.

## Context for agents

A project Command may include a bounded Masterplan snapshot containing:

- selected node and ancestors;
- active siblings and direct dependencies;
- goals, status, progress, constraints, and linked accepted decisions;
- revision and project identity.

It excludes private plans, unrelated projects, budgets not authorized for the
agent, personal notes, and the entire visual layout.

FirstMate may propose or perform an allowed plan update through a normal
attributed command. Completing an Execution does not automatically mark a node
done; the result or human must explicitly update it.

## Live collaboration

Masterplan uses Spec 001's snapshot and SSE. A committed change updates the
timeline, list, inspector, project dashboard, General Chat link, and every
authorized collaborator without refresh.

Viewers cannot mutate. Removing a member closes their live stream. Project
revocation preserves previously attributed history.

## Acceptance

1. Create a Project plan with dated and undated nodes, hierarchy, progress, one
   blocked item, and one linked Work execution.
2. Two editors open desktop and mobile views. Both see the same plan while
   keeping independent selection and camera state.
3. Update and reparent nodes in one browser; the other updates without refresh.
4. Submit two edits from the same revision; one commits and one receives a
   useful conflict without losing its draft.
5. Verify the fixed ruler, Today line, filters, inspector, accessible list, and
   default mobile Now/Next view at 320px and 390px.
6. Start FirstMate from a selected node. It receives only the bounded project
   context and links its child Work chats back to that node.
7. Restart v2 and reconnect both browsers; plan, revisions, links, and blank
   dates remain exact.

## Not in this spec

- a scheduler, backlog runner, calendar sync, Gantt dependency optimizer, or
  automatic progress inference;
- freeform whiteboarding, stored canvas coordinates, shared cursor positions,
  or collaborative unsaved drafts;
- public sharing, v1 import, or destructive migration.