@marver-design/marver 0.20.0 → 0.22.0

package/src/shared/board-types.ts

@@ -0,0 +1,103 @@
+/**
+ * Board types (spec 20) - what a board is FOR in the workspace, one vocabulary every canvas
+ * shares so any sidebar reads at a glance. A board states its own `"type"`, or wears the type of
+ * the nearest typed folder above it (its folder, then that folder's parent), else it is plain.
+ * Moving a board changes an inherited type, never one the board states itself.
+ *
+ * Pure and shared: the dev API, the manifest, the build, the shell and the CLI all read types
+ * through here, so a type means one thing everywhere.
+ */
+
+export const BOARD_TYPES = ['start', 'feature', 'surface', 'project', 'feedback', 'context', 'deck', 'archive'] as const
+export type KnownType = (typeof BOARD_TYPES)[number]
+export type BoardType = KnownType | 'plain'
+
+/** What each type is for - the sidebar's tooltip, the CLI's help, the docs. */
+export const TYPE_ROLES: Record<BoardType, string> = {
+  start: 'the way in: the index, the shipped record, the timeline',
+  feature: 'one capability: its spec, lo-fi and hi-fi',
+  surface: 'the whole product to walk, from frames on feature boards',
+  project: 'a deliverable or a question',
+  feedback: 'one frame per theme',
+  context: 'what came in from outside: meetings, threads, competitors',
+  deck: 'slides',
+  archive: 'snapshots and retired work',
+  plain: 'a board',
+}
+
+/** The grammar a stored type keeps to. Any on-grammar word survives a write - a newer Marver's
+ *  type is never dropped by an older shell - while only the known ones are drawn. */
+export const TYPE_GRAMMAR = /^[a-z][a-z-]{0,31}$/
+/** A type off a file: the word when it is on-grammar, else absent. */
+export const readType = (v: unknown): string | undefined => (typeof v === 'string' && TYPE_GRAMMAR.test(v) ? v : undefined)
+/** A type this Marver draws. */
+export const knownType = (v: unknown): KnownType | undefined =>
+  (BOARD_TYPES as readonly string[]).includes(v as string) ? (v as KnownType) : undefined
+
+/** A board's type: its own when it states one (an unknown word reads as plain - the board spoke
+ *  for itself), else its folder's, else that folder's parent's, else plain. */
+export function resolveType(own: unknown, folder?: unknown, parent?: unknown): BoardType {
+  if (readType(own)) return knownType(own) ?? 'plain'
+  return knownType(folder) ?? knownType(parent) ?? 'plain'
+}
+
+/** The publish type a board's type proposes when its publish row names none - how a board
+ *  PRESENTS when published, a separate question from what it is for. */
+export const PROPOSED_PUBLISH: Partial<Record<BoardType, 'slides' | 'refs' | 'doc' | 'mix'>> = {
+  deck: 'slides',
+  context: 'refs',
+  project: 'doc',
+  feature: 'mix',
+  surface: 'mix',
+}
+
+/** The types that carry a status (spec 20, open question 2: features and projects - the others
+ *  have no lifecycle of their own). */
+export const HAS_STATUS: readonly BoardType[] = ['feature', 'project']
+
+/** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
+ *  record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
+export const DECISIONS = ['archived', 'paused', 'blocked'] as const
+export const BY_HAND = ['in-progress', 'todo', 'backlog'] as const
+export const STATUS_WORDS = [...DECISIONS, ...BY_HAND, 'done'] as const
+export type StatusWord = (typeof STATUS_WORDS)[number]
+export const readStatusWord = (v: unknown): StatusWord | undefined =>
+  (STATUS_WORDS as readonly string[]).includes(v as string) ? (v as StatusWord) : undefined
+/** The statuses a person may set on a feature or project board, in the order a picker lists them:
+ *  the three decisions always; Backlog, To do and In progress only where there is no `context/`
+ *  (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
+export const settableStatuses = (contextPresent: boolean): StatusWord[] =>
+  contextPresent ? ['blocked', 'paused', 'archived'] : ['backlog', 'todo', 'in-progress', 'blocked', 'paused', 'archived']
+
+/** A capability slug - the same grammar as a board name, so a feature board and its contract
+ *  share it. */
+export const readCapability = (v: unknown): string | undefined =>
+  typeof v === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v) ? v : undefined
+/** A blocked board's reason: one sentence, trimmed and capped. */
+export const REASON_MAX = 300
+export const readReason = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  const s = v.trim().replace(/\s+/g, ' ').slice(0, REASON_MAX)
+  return s || undefined
+}
+
+/** The sidebar every canvas shares (spec 19, The canvas): folder modules, each typed, so a board
+ *  made inside one wears its type. `marver init --kind` creates a kind's set on a fresh canvas;
+ *  `marver folders add <module>` adds one later. Names are slugs; only Start here needs a title. */
+export const FOLDER_MODULES: Record<string, { name: string; title?: string; type: KnownType }> = {
+  start: { name: 'start-here', title: 'Start here', type: 'start' },
+  features: { name: 'features', type: 'feature' },
+  surfaces: { name: 'surfaces', type: 'surface' },
+  projects: { name: 'projects', type: 'project' },
+  feedback: { name: 'feedback', type: 'feedback' },
+  context: { name: 'context', type: 'context' },
+  decks: { name: 'decks', type: 'deck' },
+  archive: { name: 'archive', type: 'archive' },
+}
+/** A kind of work's folders, in sidebar order: the core (Start here, Feedback, Context, Archive)
+ *  around the kind's own modules. Decks are an add-on for either. */
+export const KIND_FOLDERS = {
+  product: ['start', 'features', 'surfaces', 'feedback', 'context', 'archive'],
+  knowledge: ['start', 'projects', 'feedback', 'context', 'archive'],
+} as const
+export type Kind = keyof typeof KIND_FOLDERS

package/src/shared/context.ts

@@ -0,0 +1,265 @@
+/**
+ * Reading `context/` (spec 19) - pure parsers over file text, shared by the dev server (which
+ * reads status off them, spec 20) and `marver context check` (which keeps them true). No fs, no
+ * git: callers read the files and hand the text in, so every reader parses one way.
+ */
+
+/** The evidence levels a shipped-record cell carries. */
+export type Level = 'confirmed' | 'reported' | 'unknown'
+export const LEVEL = /`(confirmed|reported|unknown)`/g
+/** What counts as a citation beside a level: a `path:line`, a run id, a cited file, or a link to a
+ *  system of record (a deploy run's page). A cited file must also resolve - the check sees to it. */
+export const CITATION = /`[^`\s]+:\d+(-\d+)?`|\bruns? \d{6,}(, \d{6,})*|`[^`\s]+\.(md|json|ts|tsx|js|mjs|yml|yaml|sql)`|\]\(https?:\/\/[^)\s]+\)/
+/** A cited repository file inside a cell, with or without a line: `path/to/x.ts`, `CHANGELOG.md:12`. */
+export const CITED_FILE = /`((?:\.{0,2}[\w@.-]+\/)*[\w@.$-]+\.(?:md|json|ts|tsx|js|jsx|mjs|yml|yaml|sql|txt))(?::(\d+)(?:-(\d+))?)?`/g
+
+/** The audiences a context file declares (spec 19, Audiences): `team` when it says nothing. */
+export type Audience = 'publishable' | 'team' | 'restricted'
+export const readAudience = (v: unknown): Audience => (v === 'publishable' || v === 'restricted' ? v : 'team')
+const AUDIENCE_RANK: Record<Audience, number> = { publishable: 0, team: 1, restricted: 2 }
+/** The strictest of several audiences - what a conclusion drawn from them may be shown to. */
+export const strictest = (...a: Audience[]): Audience => a.reduce((x, y) => (AUDIENCE_RANK[y] > AUDIENCE_RANK[x] ? y : x), 'publishable' as Audience)
+
+/** Line endings normalized: every reader parses LF, so a CRLF file means the same thing. */
+export const lf = (text: string): string => text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n')
+/** The headers whose cells carry evidence in a shipped table. */
+export const EVIDENCE_COLUMN = /^(evidence|verified|available|delivered)$/i
+
+/** The context files' own front matter: a YAML subset - scalars, flow maps `{ a: b }`, flow
+ *  lists `[a, b]`, block lists. `error` names a block that opens and never closes; a file
+ *  with no front matter has `data: null`. */
+export interface FrontMatter { data: Record<string, unknown> | null; body: string; offset: number; error?: string }
+/** A Marver-managed file's first line (the playbooks Marver maintains) - front matter follows it. */
+const MANAGED_LINE = /^<!-- marver:managed [^\n]*-->\n/
+export function frontMatter(raw: string): FrontMatter {
+  const text = lf(raw)
+  const managed = MANAGED_LINE.exec(text)
+  if (managed) {
+    const r = frontMatter(text.slice(managed[0].length))
+    return { ...r, offset: r.offset + 1 }
+  }
+  if (!text.startsWith('---\n')) return { data: null, body: text, offset: 0 }
+  const m = text.match(/^---\n([\s\S]*?)\n---[ \t]*(\n|$)/)
+  if (!m) return { data: null, body: text, offset: 0, error: 'front matter opens with --- and never closes' }
+  const data: Record<string, unknown> = {}
+  let key: string | null = null
+  for (const line of m[1].split('\n')) {
+    const item = line.match(/^\s+-\s+(.*)$/)
+    if (item && key) {
+      if (!Array.isArray(data[key])) data[key] = []
+      ;(data[key] as unknown[]).push(scalar(item[1]))
+      continue
+    }
+    const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/)
+    if (!kv) continue
+    key = kv[1]
+    data[key] = kv[2] === '' ? [] : value(kv[2])
+  }
+  return { data, body: text.slice(m[0].length), offset: m[0].split('\n').length - 1 }
+}
+function scalar(s: string): string {
+  s = s.trim().replace(/\s+#.*$/, '')
+  if (/^".*"$|^'.*'$/.test(s)) return s.slice(1, -1)
+  return s
+}
+function splitTop(s: string): string[] {
+  const out: string[] = []
+  let depth = 0, cur = '', q: string | null = null
+  for (const ch of s) {
+    if (q) { cur += ch; if (ch === q) q = null; continue }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue }
+    if (ch === '{' || ch === '[') depth++
+    if (ch === '}' || ch === ']') depth--
+    if (ch === ',' && depth === 0) { out.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  if (cur.trim()) out.push(cur)
+  return out
+}
+function value(s: string): unknown {
+  s = s.trim().replace(/\s+#[^"'}\]]*$/, '')
+  if (s.startsWith('{') && s.endsWith('}')) {
+    const o: Record<string, unknown> = {}
+    for (const part of splitTop(s.slice(1, -1))) {
+      const i = part.indexOf(':')
+      if (i > 0) o[part.slice(0, i).trim()] = value(part.slice(i + 1))
+    }
+    return o
+  }
+  if (s.startsWith('[') && s.endsWith(']')) return splitTop(s.slice(1, -1)).map((x) => value(x))
+  return scalar(s)
+}
+
+/** Lines outside fenced code blocks, with their 1-based numbers in the whole file. */
+export function proseLines(text: string, offset = 0): [number, string][] {
+  const out: [number, string][] = []
+  let fenced = false
+  lf(text).split('\n').forEach((line, i) => {
+    if (/^\s*```/.test(line)) { fenced = !fenced; return }
+    if (!fenced) out.push([i + 1 + offset, line])
+  })
+  return out
+}
+
+/** Markdown tables outside code: each header and its rows, cells trimmed, with line numbers. */
+export interface Table { header: string[]; headerLine: number; rows: { line: number; cells: string[] }[] }
+export function tables(text: string): Table[] {
+  const out: Table[] = []
+  let cur: Table | null = null
+  for (const [n, line] of proseLines(text)) {
+    if (!/^\s*\|/.test(line)) { cur = null; continue }
+    if (/^\s*\|[\s|:-]+\|\s*$/.test(line)) continue
+    const cells = splitRow(line)
+    if (!cur) { cur = { header: cells, headerLine: n, rows: [] }; out.push(cur); continue }
+    cur.rows.push({ line: n, cells })
+  }
+  return out
+}
+/** A table row's cells - pipes inside backticks stay in their cell. */
+function splitRow(line: string): string[] {
+  const s = line.trim().replace(/^\|/, '').replace(/\|$/, '')
+  const out: string[] = []
+  let cur = '', code = false
+  for (const ch of s) {
+    if (ch === '`') code = !code
+    if (ch === '|' && !code) { out.push(cur.trim()); cur = ''; continue }
+    cur += ch
+  }
+  out.push(cur.trim())
+  return out
+}
+
+export const levelsIn = (cell: string): Level[] => [...cell.matchAll(LEVEL)].map((m) => m[1] as Level)
+
+/** A table whose header row has no outer pipes - Markdown renders it, the readers here do not. The
+ *  check rejects it rather than read past it. Returns the separator rows' line numbers. */
+export function looseTables(text: string): number[] {
+  return proseLines(text).filter(([, l]) => !/^\s*\|/.test(l) && /^\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/.test(l)).map(([n]) => n)
+}
+
+/** The levels an availability cell grants, clause by clause (`;` separates them). A clause counts
+ *  only when it claims availability: never one carrying a negation anywhere ("nowhere", "not
+ *  available", "rolled back", "withdrawn") - and, for a product's Available cell, never one scoped to
+ *  a pre-production place (staging, preview, sandbox) that does not also name production. A
+ *  knowledge-work Delivered cell has no environments: only negations void it. */
+const NEGATION = /\b(nowhere|none|never|no longer|not (yet )?(available|live|deployed|delivered|on|in|shipped|released|out)|not yet|pending|planned|scheduled|upcoming|awaiting|withdrawn|rolled back|reverted|removed|retired|pulled)\b|^\s*not\b/i
+/** The places a product is NOT yet available to its users, unless the clause also names production. */
+const PRE_PRODUCTION = /\b(staging|preview|sandbox|dev|development|local|locally|testing|test environment|qa)\b/i
+export function availableLevels(cell: string, kind: 'available' | 'delivered' = 'available'): Level[] {
+  const out: Level[] = []
+  for (const clause of cell.split(';')) {
+    const c = clause.replace(/\*\*/g, '').trim()
+    if (NEGATION.test(c)) continue
+    if (kind === 'available' && PRE_PRODUCTION.test(c) && !/\b(production|prod)\b/i.test(c)) continue
+    out.push(...levelsIn(c))
+  }
+  return out
+}
+
+/** The shipped record's capability rows: every table whose first column is "Capability" (a
+ *  product) or "Project" / "Deliverable" (knowledge work) and that has an "Available" or
+ *  "Delivered" column. The capability is the first backticked slug in the row's first cell;
+ *  `levels` are the ones its availability clauses grant (availableLevels). */
+export interface ShippedRow { capability: string; line: number; available: string; levels: Level[] }
+export const RECORD_KEY = /^(capability|project|deliverable)$/i
+export const RECORD_AVAILABLE = /^(available|delivered)$/i
+export const isRecordTable = (t: Table): boolean => RECORD_KEY.test(t.header[0] ?? '') && t.header.some((h) => RECORD_AVAILABLE.test(h))
+export function shippedRows(text: string): ShippedRow[] {
+  const out: ShippedRow[] = []
+  for (const t of tables(text)) {
+    if (!isRecordTable(t)) continue
+    const a = t.header.findIndex((h) => RECORD_AVAILABLE.test(h))
+    const kind = /^delivered$/i.test(t.header[a]) ? 'delivered' : 'available'
+    for (const r of t.rows) {
+      const slug = /`([a-z0-9][a-z0-9-]*)`/.exec(r.cells[0] ?? '')?.[1]
+      if (!slug) continue
+      const available = r.cells[a] ?? ''
+      out.push({ capability: slug, line: r.line, available, levels: availableLevels(available, kind) })
+    }
+  }
+  return out
+}
+
+/** Is this a glob the matcher reads? Balanced, unnested braces; no character classes. */
+export const validGlob = (g: string): boolean => {
+  if (typeof g !== 'string' || !g || /[[\]]/.test(g)) return false
+  let depth = 0
+  for (const c of g) { if (c === '{') { if (++depth > 1) return false } else if (c === '}') { if (--depth < 0) return false } }
+  return depth === 0
+}
+export const hasGlob = (g: string): boolean => /[*?{]/.test(g)
+/** A glob with **, *, ? and {a,b} as a RegExp over repo-relative paths (validGlob first). */
+export function globRe(glob: string): RegExp {
+  let re = '', brace = 0
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i++
+        if (glob[i + 1] === '/') { i++; re += '(?:[\\s\\S]*/)?' } else re += '[\\s\\S]*'
+      } else re += '[^/]*'
+    } else if (c === '?') re += '[^/]'
+    else if (c === '{') { brace++; re += '(?:' }
+    else if (c === '}' && brace) { brace--; re += ')' }
+    else if (c === ',' && brace) re += '|'
+    else re += c.replace(/[.+^$()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${re}$`)
+}
+
+/** `context/map.json`'s shape. */
+export interface CapabilityMap {
+  /** `summary` - a few words the index shows beside the slug, so a reader routes without opening the contract */
+  capabilities: Record<string, { contract?: string; summary?: string; paths: string[]; tests?: string[] }>
+  excluded: { path: string; reason: string }[]
+  /** the globs whose files must be mapped or excluded - the check reports any that is neither */
+  source?: string[]
+}
+/** Read a map's text: the map, or what is wrong with it - every field checked, every glob valid. */
+export function parseMap(text: string): CapabilityMap | string {
+  let raw: unknown
+  try { raw = JSON.parse(text) } catch { return 'context/map.json is not valid JSON' }
+  const m = raw as Partial<CapabilityMap> | null
+  if (!m || typeof m !== 'object' || !m.capabilities || typeof m.capabilities !== 'object' || Array.isArray(m.capabilities)) return 'context/map.json needs a "capabilities" object'
+  const globs = (where: string, v: unknown, required: boolean): string | null => {
+    if (v === undefined && !required) return null
+    if (!Array.isArray(v) || v.some((x) => typeof x !== 'string')) return `context/map.json: ${where} must be a list of paths`
+    const bad = (v as string[]).findIndex((g) => !validGlob(g))
+    return bad >= 0 ? `context/map.json: ${where} has an invalid glob "${(v as string[])[bad]}" (not empty; balanced, unnested {a,b}; no [...])` : null
+  }
+  for (const [k, c] of Object.entries(m.capabilities)) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(k)) return `context/map.json: "${k}" is not a capability slug`
+    const cc = c as Record<string, unknown> | null
+    if (!cc || typeof cc !== 'object') return `context/map.json: "${k}" must be an object`
+    const e = globs(`"${k}".paths`, cc.paths, true) ?? globs(`"${k}".tests`, cc.tests, false)
+    if (e) return e
+    if (cc.contract !== undefined && typeof cc.contract !== 'string') return `context/map.json: "${k}".contract must be a path`
+    if (cc.summary !== undefined && typeof cc.summary !== 'string') return `context/map.json: "${k}".summary must be text`
+  }
+  if (m.excluded !== undefined) {
+    if (!Array.isArray(m.excluded)) return 'context/map.json: "excluded" must be a list'
+    for (const x of m.excluded as unknown[]) {
+      const e = x as { path?: unknown; reason?: unknown } | null
+      if (!e || typeof e.path !== 'string' || !validGlob(e.path)) return 'context/map.json: every "excluded" entry needs a valid "path" glob'
+      if (typeof e.reason !== 'string' || !e.reason.trim()) return `context/map.json: excluded "${e.path}" needs a "reason"`
+    }
+  }
+  { const e = globs('"source"', (m as { source?: unknown }).source, false); if (e) return e }
+  const source = Array.isArray(m.source) ? m.source.filter((x): x is string => typeof x === 'string') : undefined
+  return { capabilities: m.capabilities as CapabilityMap['capabilities'], excluded: Array.isArray(m.excluded) ? m.excluded : [], ...(source ? { source } : {}) }
+}
+
+/** The index's generated capability table, between `<!-- generated ... -->` fences. */
+export const GENERATED = /<!-- generated[^>]*-->([\s\S]*?)<!-- \/generated -->/
+/** The table the index generates from the map: one row per capability, its contract linked. */
+export function capabilityTable(map: CapabilityMap): string {
+  const rows = Object.entries(map.capabilities).map(([k, c]) => {
+    const name = `\`${k}\`${typeof c.summary === 'string' && c.summary.trim() ? ` - ${c.summary.trim().replace(/\|/g, '/')}` : ''}`
+    const rel = c.contract?.replace(/^context\//, '')
+    return rel ? `| ${name} | [\`${rel}\`](${rel}) |` : `| ${name} | none yet - see the map |`
+  })
+  return ['| Capability | Contract |', '|---|---|', ...rows].join('\n')
+}
+
+/** Words in a document's body (front matter excluded) - the index's budget counts these. */
+export const wordCount = (text: string): number => frontMatter(text).body.split(/\s+/).filter(Boolean).length

package/src/shared/status.ts

@@ -0,0 +1,157 @@
+/**
+ * Status (spec 20) - one resolver, shared by the dev server and the build: files in, a status and
+ * its evidence out, pure. Feature and project boards wear it; read top to bottom, the first row
+ * that matches wins:
+ *
+ *   1-3  the board says archived, paused or blocked (with its reason)   - a decision, by hand
+ *   4    the evidence it needs cannot be read                           - Unknown, never a stale Done
+ *   5    an open plan names the capability                              - In progress, filling by phase
+ *   6    the shipped record shows it available, `confirmed`             - Done
+ *   7    ... `reported` only                                            - Done, reported
+ *   8    an accepted contract (`state: current`), no availability       - To do
+ *   9    anything else                                                  - Backlog
+ *
+ * Without `context/`, a board may also say in-progress, todo or backlog by hand. Done is never
+ * set by hand: `"status": "done"` is ignored here and reported by `marver context check`.
+ */
+import { DECISIONS, HAS_STATUS, type BoardType, type StatusWord } from './board-types.ts'
+import { strictest, type Audience, type Level } from './context.ts'
+
+export type Status = 'archived' | 'paused' | 'blocked' | 'unknown' | 'in-progress' | 'done' | 'done-reported' | 'todo' | 'backlog'
+export const STATUS_LABEL: Record<Status, string> = {
+  archived: 'Archived', paused: 'Paused', blocked: 'Blocked', unknown: 'Unknown', 'in-progress': 'In progress',
+  done: 'Done', 'done-reported': 'Done, reported', todo: 'To do', backlog: 'Backlog',
+}
+
+/** A phase, as the fill reads it: 1 spec, 2 lo-fi, 3 hi-fi. */
+export type Phase = 1 | 2 | 3
+export const PHASE_LABEL: Record<Phase, string> = { 1: 'spec', 2: 'lo-fi', 3: 'hi-fi' }
+
+/** What the resolver knows about `context/` - read once per pass by the caller. */
+export interface ContextFacts {
+  /** a `context/` directory exists */
+  present: boolean
+  /** evidence that could not be read: `'*'` for the whole record (shipped.md unreadable), else per capability */
+  unreadable: Map<string, string>
+  /** capability -> the levels its shipped row's availability grants, where, and the record's audience */
+  shipped: Map<string, { levels: Level[]; where: string; audience: Audience }>
+  /** capability -> its contract's state, where, and its audience */
+  contracts: Map<string, { state: string; where: string; audience: Audience }>
+  /** capability -> its open plans, each with its audience */
+  plans: Map<string, { where: string; audience: Audience }[]>
+}
+export const NO_CONTEXT: ContextFacts = { present: false, unreadable: new Map(), shipped: new Map(), contracts: new Map(), plans: new Map() }
+
+export interface BoardInput {
+  name: string
+  type: BoardType
+  capability?: string
+  status?: StatusWord
+  reason?: string
+  /** the scenes the board shows, with any `phase` their brief declares and that brief's audience */
+  scenes: { name: string; phase?: string; audience?: Audience }[]
+}
+
+export interface StatusResult {
+  status: Status
+  /** the table row that decided it */
+  row: number
+  /** In progress: the latest phase present */
+  fill?: Phase
+  /** Blocked: why */
+  reason?: string
+  /** the capability the evidence was read for */
+  capability: string
+  /** one line per piece of evidence, for the tooltip */
+  evidence: string[]
+  /** the strictest audience of the evidence the status was drawn from - a published canvas shows a
+   *  status only when this is `publishable` (spec 20, Publishing status) */
+  audience: Audience
+}
+
+const PHASE_WORDS: Record<string, Phase> = { spec: 1, specs: 1, lofi: 2, 'lo-fi': 2, hifi: 3, 'hi-fi': 3 }
+
+/** The latest phase a board's scenes show: a scene named `<cap>-specs` (spec), `<cap>-lofi`
+ *  (lo-fi) or `<cap>` itself (hi-fi), or a `phase` in a scene's brief. Never geometry. */
+export function phaseOf(capability: string, scenes: BoardInput['scenes']): Phase | undefined {
+  return phaseSource(capability, scenes)?.phase
+}
+/** The deciding phase and where it came from - a brief's phase carries that brief's audience. */
+function phaseSource(capability: string, scenes: BoardInput['scenes']): { phase: Phase; scene: string; fromBrief: boolean; audience: Audience } | undefined {
+  let best: { phase: Phase; scene: string; fromBrief: boolean; audience: Audience } | undefined
+  for (const s of scenes) {
+    const declared = s.phase ? PHASE_WORDS[s.phase.toLowerCase()] : undefined
+    const named = s.name === `${capability}-specs` || s.name === `${capability}-spec` ? 1 : s.name === `${capability}-lofi` ? 2 : s.name === capability ? 3 : undefined
+    const p = (declared ?? named) as Phase | undefined
+    if (p && (!best || p > best.phase)) best = { phase: p, scene: s.name, fromBrief: !!declared, audience: declared ? (s.audience ?? 'team') : 'publishable' }
+  }
+  return best
+}
+
+/** A board's status, or null when its type carries none. */
+export function resolveStatus(b: BoardInput, ctx: ContextFacts): StatusResult | null {
+  if (!HAS_STATUS.includes(b.type)) return null
+  const capability = b.capability ?? b.name
+  const out = (status: Status, row: number, evidence: string[], audience: Audience, extra: Partial<StatusResult> = {}): StatusResult => ({ status, row, capability, evidence, audience, ...extra })
+
+  // 1-3: a decision on the board
+  if (b.status && (DECISIONS as readonly string[]).includes(b.status)) {
+    const by = `design/boards/${b.name}.json: "status": "${b.status}"`
+    return out(b.status as Status, DECISIONS.indexOf(b.status as (typeof DECISIONS)[number]) + 1, [by], 'team', b.status === 'blocked' && b.reason ? { reason: b.reason } : {})
+  }
+
+  if (!ctx.present) {
+    // without context/ a project sets To do, Backlog and In progress by hand; Done needs a record
+    // the board's own word, and a board ships as written - publishable
+    if (b.status === 'in-progress') {
+      const f = fillOf(capability, b.scenes)
+      return out('in-progress', 5, [`design/boards/${b.name}.json: by hand`, ...f.evidence], strictest('publishable', ...f.audience), f.fill)
+    }
+    if (b.status === 'todo') return out('todo', 8, [`design/boards/${b.name}.json: by hand`], 'publishable')
+    return out('backlog', 9, [b.status === 'backlog' ? `design/boards/${b.name}.json: by hand` : 'no context/ - nothing records it'], 'publishable')
+  }
+
+  // 4: evidence that cannot be read is Unknown - never the last value seen
+  const bad = ctx.unreadable.get('*') ?? ctx.unreadable.get(capability)
+  if (bad) return out('unknown', 4, [bad], 'team')
+
+  const row = ctx.shipped.get(capability)
+  const live = row?.levels.includes('confirmed') ? 'confirmed' : row?.levels.includes('reported') ? 'reported' : null
+
+  // 5: an open plan - work on a shipped capability is version two being built, and says so
+  const plans = ctx.plans.get(capability)
+  if (plans?.length) {
+    const f = fillOf(capability, b.scenes)
+    const ev = [...plans.map((p) => `${p.where}: an open plan`), ...f.evidence]
+    if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`)
+    return out('in-progress', 5, ev, strictest(...plans.map((p) => p.audience), ...f.audience, ...(live && row ? [row.audience] : [])), f.fill)
+  }
+
+  // 6-7: the shipped record
+  if (live === 'confirmed') return out('done', 6, [`${row!.where}: available, \`confirmed\``], row!.audience)
+  if (live === 'reported') return out('done-reported', 7, [`${row!.where}: available, \`reported\` only`], row!.audience)
+
+  // 8: an accepted contract
+  const c = ctx.contracts.get(capability)
+  if (c?.state === 'current') return out('todo', 8, [`${c.where}: state current, nothing available yet`], strictest(c.audience, ...(row ? [row.audience] : [])))
+
+  // 9: nothing records it - which says nothing private
+  return out('backlog', 9, [c ? `${c.where}: state ${c.state}` : `no contract for ${capability}`], c ? c.audience : 'publishable')
+}
+
+/** The fill, the line that says where it came from, and the audience of that source. */
+const fillOf = (capability: string, scenes: BoardInput['scenes']): { fill: Partial<StatusResult>; evidence: string[]; audience: Audience[] } => {
+  const src = phaseSource(capability, scenes)
+  if (!src) return { fill: {}, evidence: [], audience: [] }
+  const where = src.fromBrief ? `design/scenes/${src.scene}/_brief.md: phase ${PHASE_LABEL[src.phase]}` : `design/scenes/${src.scene}: the ${PHASE_LABEL[src.phase]} scene`
+  return { fill: { fill: src.phase }, evidence: [where], audience: [src.audience] }
+}
+
+/** What a published canvas may show of a status (spec 20, Publishing status): rows 5-9 only, drawn
+ *  from `publishable` evidence only, and never a reason, a record path or other evidence. */
+export function publishableStatus(r: { status: Status; row?: number; fill?: Phase; audience?: Audience } | null | undefined): { status: Status; fill?: Phase } | null {
+  if (!r || !PUBLISHABLE.has(r.status) || r.audience !== 'publishable') return null
+  return { status: r.status, ...(r.fill ? { fill: r.fill } : {}) }
+}
+/** The statuses rows 5-9 produce - the only ones a published canvas may show. */
+export const PUBLISHABLE: ReadonlySet<Status> = new Set(['in-progress', 'done', 'done-reported', 'todo', 'backlog'])

package/templates/AGENTS-embedded.md

@@ -22,6 +22,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Iterate | changing a frame the human has seen, a round of feedback on a scene, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
+| Context | any question about what the product does or what is live; a behaviour change; a deploy; no `context/` yet | instructions/context.md |
 | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
@@ -197,9 +198,9 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. Boards can sit in **folders** (one level): put
-`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
-and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+every curated board carries one. Boards can sit in **folders**, two levels deep: put
+`"folder": "<name>"` on a board file (the folder it sits in directly); `design/boards/_folders.json`
+names empty folders, ranks them, and nests a sub-folder with `"parent"` - the human creates, renames, and drags folders in the sidebar too, so
 run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
 creating a board, organising boards, or publishing anything, read instructions/boards.md
 (the layout grammar, file format, folders and their moves, publishing rules).

package/templates/AGENTS-studio.md

@@ -22,6 +22,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Iterate | changing a frame the human has seen, a round of feedback on a scene, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
+| Context | any question about what the product does or what is live; a behaviour change; a deploy; no `context/` yet | instructions/context.md |
 | Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
@@ -197,9 +198,9 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. Boards can sit in **folders** (one level): put
-`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
-and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+every curated board carries one. Boards can sit in **folders**, two levels deep: put
+`"folder": "<name>"` on a board file (the folder it sits in directly); `design/boards/_folders.json`
+names empty folders, ranks them, and nests a sub-folder with `"parent"` - the human creates, renames, and drags folders in the sidebar too, so
 run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
 creating a board, organising boards, or publishing anything, read instructions/boards.md
 (the layout grammar, file format, folders and their moves, publishing rules).

package/templates/context/INDEX.md

@@ -0,0 +1,50 @@
+---
+audience: team
+---
+
+# {{NAME}} - the index
+
+Routing only. Read this, then at most two more files per question. It stays under 800 words -
+`npx marver context check` counts.
+
+## The product
+
+<!-- Five lines at most: what it is and for whom; what runs where; what is happening now. -->
+
+## Questions, and where they are answered
+
+| Question | Read |
+|---|---|
+| {{RECORD_QUESTION}} | [`shipped.md`](shipped.md) |
+| How does it work today? | its contract below; without one, [`map.json`](map.json) names the code and tests |
+| Why was it decided? | the decision log - say where this project keeps it |
+| What is next, and what counts as done? | the roadmap - say where |
+| Who asked for it, and what happened to it? | `feedback/` |
+| How do we do it? | "How we do things", below |
+
+## Capabilities
+
+<!-- generated: `npx marver context index` keeps this table equal to context/map.json -->
+| Capability | Contract |
+|---|---|
+<!-- /generated -->
+
+## Where each role lives
+
+<!-- Healthy homes left in place: the changelog, the decision log, research, test records, the canvas. -->
+
+## How we do things
+
+- [`reorganize-context`](playbooks/reorganize-context/PLAYBOOK.md) - when context exists but is
+  scattered: specs out of date, nobody sure what is live.
+- [`publish-canvas`](playbooks/publish-canvas/PLAYBOOK.md) - when the canvas should be on a URL.
+
+## Rules
+
+- **Availability is written only in `shipped.md`,** each cell `confirmed`, `reported` or `unknown`,
+  with a citation.
+- **A behaviour change updates its contract,** or the pull request says
+  `no-contract-change: <capability> - <why>`.
+- **Every deploy writes the record.**
+- **A plan lives in `plans/` while open** and folds into its contract when it lands.
+- `npx marver context check` checks these; ci runs it.

package/templates/context/map.json

@@ -0,0 +1,6 @@
+{
+  "about": "Which code each capability lives in - routing for agents, and the input of the pull-request rule in `npx marver context check`. A file may map to several capabilities. `source` names what must be mapped or excluded; the check reports any file that is neither. Only capabilities with a contract are checked on pull requests.",
+  "source": ["src/**", "app/**", "apps/**", "packages/**", "lib/**"],
+  "capabilities": {},
+  "excluded": []
+}

package/templates/context/shipped-knowledge.md

@@ -0,0 +1,19 @@
+---
+kind: record
+audience: team
+---
+
+# Delivered - what was delivered, to whom, and when
+
+The only file that says what is delivered. Every evidence cell carries its level, and `confirmed`
+and `reported` carry a citation:
+
+- `confirmed` - observed in a system of record: the client's written acceptance, the sent email,
+  the signed-off document.
+- `reported` - a written claim, cited: a meeting note, a changelog line.
+- `unknown` - neither, with the reason. An honest unknown is the right answer.
+
+## Projects
+
+| Project | Delivered | Evidence | Contract |
+|---|---|---|---|