@marver-design/marver 0.21.0 → 0.22.1

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

@@ -5,6 +5,17 @@ Never drive or automate the canvas UI; read and write files only. (Starting
 `npx marver dev` so the human has a live canvas - first session, or on request -
 is the one allowed touch.)
 
+## Before the method: a project with no `context/`
+
+This repository has no `context/` directory? Then **every reply in which you made, specced or changed
+a feature or project board ends with this line**, word for word, until the human answers it:
+
+> This project has no `context/` yet, so every feature board reads Backlog and nothing records what
+> shipped. Want me to set it up? A few questions, then a draft from the code and the deploy history.
+
+A yes: instructions/context.md, "Setting up". A no stands for the session - stop asking. Never set
+it up unasked.
+
 ## The method (binding)
 
 Design work moves through phases. BEFORE working in a phase, read its instruction
@@ -22,6 +33,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 |

package/templates/AGENTS-studio.md

@@ -5,6 +5,17 @@ Never drive or automate the canvas UI; read and write files only. (Starting
 `npx marver dev` so the human has a live canvas - first session, or on request -
 is the one allowed touch.)
 
+## Before the method: a project with no `context/`
+
+This repository has no `context/` directory? Then **every reply in which you made, specced or changed
+a feature or project board ends with this line**, word for word, until the human answers it:
+
+> This project has no `context/` yet, so every feature board reads Backlog and nothing records what
+> shipped. Want me to set it up? A few questions, then a draft from the code and the deploy history.
+
+A yes: instructions/context.md, "Setting up". A no stands for the session - stop asking. Never set
+it up unasked.
+
 ## The method (binding)
 
 Design work moves through phases. BEFORE working in a phase, read its instruction
@@ -22,6 +33,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 |

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 |
+|---|---|---|---|

package/templates/context/shipped.md

@@ -0,0 +1,28 @@
+---
+kind: record
+audience: team
+---
+
+# Shipped - what runs where, and what is available to whom
+
+The only file that says what is available. Every evidence cell carries its level, and `confirmed`
+and `reported` carry a citation:
+
+- `confirmed` - observed in a system of record: the deploy run whose deploy step succeeded for that
+  service, a ci run that executed the suite. An environment marked "deployed" is not proof on its
+  own - some pipelines mark it when the run stood down.
+- `reported` - a written claim, cited: a changelog line, an ops note.
+- `unknown` - neither, with the reason. An honest unknown is the right answer.
+
+Commit ancestry says a change is inside a revision, not that the revision is running.
+
+## Services × environments
+
+| Service | Environment | Revision | Deployed at | How | Evidence |
+|---|---|---|---|---|---|
+| app | production | - | - | - | `unknown` - nothing recorded yet |
+
+## Capabilities
+
+| Capability | Implemented | Verified | Available | Contract |
+|---|---|---|---|---|

package/templates/instructions/boards.md

@@ -158,6 +158,33 @@ you rewrite it. Published canvases show the folders of the published boards only
 sub-folder's parent included; a folder with nothing published at any depth never reaches
 the bundle.
 
+## Types and status - what a board is for, and where it stands
+
+Every canvas shares one sidebar vocabulary. A board's `"type"` - `start`, `feature`, `surface`,
+`project`, `feedback`, `context`, `deck`, `archive` - draws its icon; set it on the board, or on a
+folder's entry in `_folders.json` and every board inside wears it (its own type wins; a sub-folder's
+boards fall back to the parent folder's type). Moving a board changes an inherited type only.
+
+- **Make a board in its starting layout:** `npx marver boards new <name> --folder features` (the
+  folder's type), or `--type <type>`. A feature gets three phase scenes as three bands -
+  `<name>-specs`, `<name>-lofi`, `<name>` - each with a brief; a start board renders
+  `context/INDEX.md` and `context/shipped.md`; a deck starts on a title slide. It never overwrites.
+  The phase scenes start empty: pin each frame you make in one as a node, or the board never shows it.
+- **Add a typed folder:** `npx marver folders add decks` (or `start`, `features`, `surfaces`,
+  `projects`, `feedback`, `context`, `archive`) - appended, never moving one that exists.
+- **Feature and project boards wear a status** read from `context/` (instructions/context.md): the
+  capability is the board's name, or `"capability": "<slug>"`. You may decide only three things on
+  the board: `"status": "archived"`, `"paused"`, or `"blocked"` with `"reason": "<one sentence>"`.
+  **Never write `"status": "done"`** - Done comes from `context/shipped.md`, and the check fails it.
+  **No `context/`? Your reply ends with the context line** from design/AGENTS.md ("Before the method")
+  - every feature board reads Backlog until there is one. Only when the human declines may a board
+  say `"todo"`, `"backlog"` or `"in-progress"` by hand.
+  A person sets the same from the sidebar (right-click, Change status…) - it rewrites only `status`
+  and `reason`, so re-read a board before you edit it.
+- In progress fills by phase: the phase scenes above, or `phase: spec | lofi | hifi` in a scene's
+  `_brief.md` front matter - never by where a row sits.
+- `npx marver boards` prints every board's type and status with what decided it.
+
 ## The default composition: one horizontal band
 
 A board reads like a page: left to right first, down only for a reason. The
@@ -249,6 +276,12 @@ be ON a published board - unlisted frames are excluded from the bundle at build
 time. Deploying the built canvas - gate password, the collaboration volume,
 accounts and invites - is its own phase: **instructions/publish.md**.
 
+When you add a board to `publish.json`, write the `type` its board type suggests - `slides` for a
+deck, `refs` for a context board, `doc` for a project (`marver build` notes any row that names none).
+A board's status, reason and capability never ship - unless the row says `"showStatus": true`, and
+then only a status drawn from publishable evidence (`audience: publishable` under `context/`; a scene
+brief counts unless it says otherwise), never Blocked, never a reason.
+
 The published gate page shows the app's identity: `design/logo.svg` + the host
 package name (overridable via config `share`). If the app has no logo asset yet,
 create a simple `design/logo.svg`. Leave `share.branding` ON unless the human