@litfamily/litmuse 0.1.0 → 0.1.2

package/plugin/lib/rewind/gauge.mjs

@@ -0,0 +1,72 @@
+// Progress gauges for the lit-adhd brief. Code draws them so the model copies them and never
+// invents its own: `[▉▉▉░░] 3/5`, one cell per item up to ten, scaled to ten cells above that.
+// A gauge renders only when both numbers are real. Otherwise the brief shows what is known as a
+// fact line: an indeterminate pulse plus the finished count, or just the pulse. A `?` glyph must
+// never reach the user on any surface.
+
+const MAX_CELLS = 10;
+const known = (value) => Number.isInteger(value) && value >= 0;
+
+/** The fully-unknown pulse: nothing is known, not even a finished count. */
+export const PULSE_UNKNOWN = '[…] running';
+
+/** `[▉▉▉░░] 3/5`; an unknown total reads `[…] n steps`, an unknown count the pulse. */
+export const gauge = (done, total) => {
+  if (!known(total)) return known(done) ? `[…] ${done} step${done === 1 ? "" : "s"}` : PULSE_UNKNOWN;
+  const k = known(done) ? Math.min(done, total) : 0;
+  const cells = Math.min(total, MAX_CELLS);
+  let filled = k;
+  if (total > MAX_CELLS) filled = k === total ? MAX_CELLS : k === 0 ? 0 : Math.min(MAX_CELLS - 1, Math.max(1, Math.floor((k * MAX_CELLS) / total)));
+  return `[${"▉".repeat(filled)}${"░".repeat(cells - filled)}] ${k}/${total}`;
+};
+
+/** `{done, total, gauge, remaining}` with `remaining` as recorded, or `["unknown"]`. */
+export const progressOf = (done, total, remaining) => ({
+  done: known(done) ? done : null,
+  total: known(total) ? total : null,
+  gauge: gauge(done, total),
+  remaining: Array.isArray(remaining) && remaining.length ? remaining : known(total) && known(done) && done >= total ? [] : ["unknown"],
+});
+
+/** One gauge over several: the summed totals, or the pulse line when any total is unknown. */
+export const aggregateProgress = (items) => {
+  const done = items.reduce((sum, item) => sum + (known(item.done) ? item.done : 0), 0);
+  const total = items.length && items.every((item) => known(item.total)) ? items.reduce((sum, item) => sum + item.total, 0) : null;
+  return { done, total, gauge: gauge(items.length ? done : null, total) };
+};
+
+// Terminal columns a character takes: combining marks and Hangul medial/final jamo take none, East
+// Asian wide and fullwidth characters and most emoji take two.
+const charWidth = (codePoint) => {
+  if (codePoint === 0 || codePoint < 32 || (codePoint >= 0x7f && codePoint < 0xa0)) return 0;
+  if (/\p{Mn}|\p{Me}|\p{Cf}/u.test(String.fromCodePoint(codePoint)) || (codePoint >= 0x1160 && codePoint <= 0x11ff)) return 0;
+  if (
+    (codePoint >= 0x1100 && codePoint <= 0x115f)
+    || (codePoint >= 0x2e80 && codePoint <= 0xa4cf)
+    || (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+    || (codePoint >= 0xf900 && codePoint <= 0xfaff)
+    || (codePoint >= 0xfe30 && codePoint <= 0xfe4f)
+    || (codePoint >= 0xff00 && codePoint <= 0xff60)
+    || (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+    || (codePoint >= 0x1f300 && codePoint <= 0x1faff)
+    || (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  ) return 2;
+  return 1;
+};
+
+export const displayWidth = (text) => [...String(text)].reduce((sum, ch) => sum + charWidth(ch.codePointAt(0)), 0);
+
+/** Clips to `width` display columns, ending in `…` when anything was cut. */
+export const clipToWidth = (text, width) => {
+  const value = String(text);
+  if (displayWidth(value) <= width) return value;
+  let out = "";
+  let used = 0;
+  for (const ch of value) {
+    const w = charWidth(ch.codePointAt(0));
+    if (used + w > width - 1) break;
+    out += ch;
+    used += w;
+  }
+  return `${out}…`;
+};

package/plugin/lib/rewind/next-step.mjs

@@ -0,0 +1,91 @@
+// The one next step a lit-adhd brief offers, chosen by a fixed priority over the collected records,
+// and the small record `go` reads back:
+//   1. this session's paused spine frame          -> resume-frame   (`lit continue`)
+//   2. a start-work paused at a boundary           -> approve-boundary (shown only, never automatic)
+//   3. an active start-work of this session        -> continue-work
+//   4. a single open plan with no work running     -> start-plan     (`go` runs it)
+//   5. otherwise                                  -> none
+import { closeSync, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const chooseNextStep = (data, sessionId) => {
+  const ownStack = data.workflows.find((frame) => frame.sessionId === sessionId && frame.role === 'spine' && frame.status === 'paused');
+  if (sessionId && ownStack) {
+    return { kind: 'resume-frame', target: { skill: ownStack.skill, stage: ownStack.stage, progress: ownStack.progress.gauge }, say: 'lit continue' };
+  }
+  const paused = data.startWork.find((work) => work.status === 'paused' && work.pendingBoundary);
+  if (paused) {
+    return { kind: 'approve-boundary', target: { workId: paused.workId, plan: paused.plan, ...paused.pendingBoundary }, say: 'lit approve', automatic: false };
+  }
+  const own = data.startWork.find((work) => work.status === 'active' && sessionId && work.sessionId === sessionId);
+  if (own) return { kind: 'continue-work', target: { workId: own.workId, plan: own.plan }, say: 'go' };
+  const running = data.startWork.some((work) => ['active', 'paused'].includes(work.status));
+  const open = data.roadmap.plans.filter((plan) => plan.local && plan.progress.total !== null && plan.progress.done < plan.progress.total);
+  if (!running && open.length === 1) {
+    return { kind: 'start-plan', target: { plan: open[0].plan }, say: 'go', command: `go ${open[0].plan}` };
+  }
+  return { kind: 'none', target: null };
+};
+
+const fileName = (sessionId) => `next-${String(sessionId ?? 'session').replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128) || 'session'}.json`;
+
+export const nextStepPath = (stateRoot, sessionId) => join(stateRoot, '.litmuse', 'adhd', fileName(sessionId));
+
+/**
+ * Every component from the state root down must be a real directory: a `.litmuse`
+ * that is itself a link would otherwise smuggle the record outside the workspace.
+ */
+const dirOk = (root, dir) => {
+  const base = resolve(root);
+  const parts = [base, ...dirname(resolve(dir)).replace(base, '').split('/').filter(Boolean).map((_, i, all) => join(base, ...all.slice(0, i + 1)))];
+  for (const part of parts) {
+    try {
+      if (lstatSync(part).isSymbolicLink()) return false;
+    } catch { /* not there yet */ }
+  }
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return false;
+  }
+  try {
+    return !lstatSync(dir).isSymbolicLink() && lstatSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/** Exclusive staging write: a linked staging file is refused, a stale one is replaced. */
+const writeStaging = (staging, text) => {
+  const once = () => {
+    const fd = openSync(staging, 'wx');
+    try {
+      writeSync(fd, text);
+    } finally {
+      closeSync(fd);
+    }
+  };
+  try {
+    once();
+    return;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  if (lstatSync(staging).isSymbolicLink()) throw new Error(`refusing to write through a linked staging file: ${staging}`);
+  unlinkSync(staging);
+  once();
+};
+
+/**
+ * Writes `{kind, target, at}` for this session, whole, through a temporary file.
+ * Refuses linked state dirs and staging files, so the record never lands outside
+ * the workspace; callers treat a throw as not recorded.
+ */
+export const writeNextStep = (stateRoot, sessionId, step, now = new Date()) => {
+  const path = nextStepPath(stateRoot, sessionId);
+  if (!dirOk(stateRoot, dirname(path))) throw new Error(`refusing to write through a linked state dir: ${dirname(path)}`);
+  const staging = `${path}.${process.pid}.tmp`;
+  writeStaging(staging, `${JSON.stringify({ kind: step.kind, target: step.target, at: now.toISOString() })}\n`);
+  renameSync(staging, path);
+  return path;
+};

package/plugin/lib/rewind/redact.mjs

@@ -0,0 +1,83 @@
+// Redaction for every string the lit-adhd collector emits. Credential shapes and URI userinfo come
+// from the shared secret-shape set; `NAME=value` pairs with a secret-like name lose their value; any
+// substring equal to a current environment value is replaced (compared here, never printed:
+// 8+ characters, 24+ for URL-form values such as webhooks); the home directory becomes `~`.
+// Plain filesystem paths and locale/terminal values are not credentials and stay, or every path
+// in the brief would be blanked.
+
+import { SECRET_SHAPE_PATTERNS, URI_USERINFO_PATTERN } from '../secret-shapes.mjs';
+
+const MASK = '[redacted]';
+
+// Terminal escape sequences never reach collected text: a commit subject or plan row
+// carrying them could repaint the brief or smuggle in a hyperlink when printed. ESC
+// opens an OSC run (to BEL or ST) or a CSI run (to its final byte); the remaining C0
+// controls, DEL and C1 go, except the tab that joins multi-line subjects upstream.
+const stripTerminalRuns = (text) => {
+  let out = '';
+  let index = 0;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if (code === 27) {
+      index += 1;
+      if (text[index] === ']' || text[index] === '[') {
+        const osc = text[index] === ']';
+        index += 1;
+        if (osc) {
+          while (index < text.length && text.charCodeAt(index) !== 7 && text.charCodeAt(index) !== 27) index += 1;
+          if (text.charCodeAt(index) === 27) index += 2;
+          else index += 1;
+        } else {
+          while (index < text.length && !/[A-Za-z]/.test(text[index])) index += 1;
+          index += 1;
+        }
+      }
+      continue;
+    }
+    if (code < 32 ? code !== 9 : code === 127 || (code >= 128 && code <= 159)) {
+      index += 1;
+      continue;
+    }
+    out += text[index];
+    index += 1;
+  }
+  return out;
+};
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASS|AUTH|COOKIE/iu;
+const JSON_SECRET = /("[A-Za-z_][A-Za-z0-9_]*"|'[A-Za-z_][A-Za-z0-9_]*')\s*:\s*("[^"]*"|'[^']*'|[^\s"'`,}]+)/gu;
+const ASSIGNMENT = /\b([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|[^\s"'`]+)/gu;
+const PLAIN_ENV_NAMES = /^(?:PATH|HOME|PWD|OLDPWD|SHELL|USER|LOGNAME|LANG|LANGUAGE|TERM|TERM_PROGRAM|TERM_PROGRAM_VERSION|COLORTERM|EDITOR|VISUAL|PAGER|TMPDIR|SHLVL|LC_[A-Z]+|XPC_[A-Z_]+|__CF[A-Z_]*|COMMAND_MODE|_)$/u;
+const globalOf = (pattern) => new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+const SHAPES = [...SECRET_SHAPE_PATTERNS.map(globalOf)];
+const USERINFO = globalOf(URI_USERINFO_PATTERN);
+
+const envSecrets = (env) =>
+  Object.entries(env ?? {})
+    .filter(([name, value]) => {
+      if (typeof value !== 'string' || PLAIN_ENV_NAMES.test(name) || /^(?:true|false|\d+)$/iu.test(value)) return false;
+      // URL-form values (webhooks, signed URLs) are masked from a higher bar; a lone
+      // ':/' that is not '://' keeps the old exemption.
+      if (value.includes('://')) return value.length >= 24;
+      if (value.length < 8 || value.includes(':/')) return false;
+      // Plain filesystem paths stay readable unless they carry a query string or userinfo.
+      if (/^[~/]/u.test(value)) return value.includes('?') || value.includes('@');
+      return true;
+    })
+    .map(([, value]) => value)
+    .sort((a, b) => b.length - a.length);
+
+/** A redactor bound to one environment and home, so the env scan happens once per run. */
+export const makeRedactor = ({ env = process.env, home = env?.HOME } = {}) => {
+  const values = envSecrets(env);
+  return (input) => {
+    if (typeof input !== 'string' || input === '') return input;
+    let text = input;
+    for (const value of values) if (text.includes(value)) text = text.split(value).join(MASK);
+    text = text.replace(USERINFO, (match) => match.replace(/\/\/[^/?#\s]+@/u, `//${MASK}@`));
+    text = text.replace(ASSIGNMENT, (match, name) => (SECRET_NAME.test(name) ? `${name}=${MASK}` : match));
+    text = text.replace(JSON_SECRET, (match, key) => (SECRET_NAME.test(key) ? `${key}: ${MASK}` : match));
+    for (const pattern of SHAPES) text = text.replace(pattern, MASK);
+    if (typeof home === 'string' && home.length > 1) text = text.split(home).join('~');
+    return stripTerminalRuns(text);
+  };
+};

package/plugin/lib/rewind/transcripts.mjs

@@ -0,0 +1,227 @@
+// Muse session transcripts for the lit-adhd collector. Muse stores one JSONL file per session
+// under `<data>/muse/sessions/YYYY/MM/DD/<session-id>/session.jsonl`, with subagent turns in a
+// `subagent/` child folder. Files reach tens of thousands of lines, so each is read as its head
+// and tail only, under a budget shared by the whole run, through a descriptor opened without
+// following links. Subagent transcripts are not sessions of their own and are skipped. Anything
+// a log cannot answer reads `unknown`.
+
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const HEAD_BYTES = 64 * 1024;
+export const TAIL_BYTES = 256 * 1024;
+export const TOTAL_BUDGET_BYTES = 8 * 1024 * 1024;
+const ACTIVE_MS = 15 * 60 * 1000;
+
+/** A byte budget shared by every read of one collector run. */
+export const makeBudget = (limit = TOTAL_BUDGET_BYTES) => ({ limit, used: 0, exhausted: false });
+
+const readSlice = (fd, position, length, budget) => {
+  const allowed = Math.min(length, budget.limit - budget.used);
+  if (allowed <= 0) {
+    budget.exhausted = true;
+    return '';
+  }
+  const buffer = Buffer.alloc(allowed);
+  const read = readSync(fd, buffer, 0, allowed, position);
+  budget.used += read;
+  if (allowed < length) budget.exhausted = true;
+  return buffer.subarray(0, read).toString('utf8');
+};
+
+/** The parsed lines of a transcript's head and tail; a link or a non-file reads as null. */
+export const readTranscriptLines = (path, budget, { head = HEAD_BYTES, tail = TAIL_BYTES } = {}) => {
+  let fd;
+  try {
+    if (!lstatSync(path).isFile()) return null;
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const { size } = fstatSync(fd);
+    const chunks = size <= head + tail
+      ? [readSlice(fd, 0, size, budget)]
+      : [readSlice(fd, 0, head, budget), readSlice(fd, size - tail, tail, budget)];
+    const lines = [];
+    for (const chunk of chunks) {
+      for (const line of chunk.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed && typeof parsed === 'object') lines.push(parsed);
+        } catch {
+          // A line cut at a slice edge, or a malformed one, is skipped.
+        }
+      }
+    }
+    return lines;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+};
+
+// Newest session logs first, capped, so a huge store stays cheap. `subagent/` children are lanes
+// of their parent session, not sessions.
+const newestLogs = (storeDir, cap = 400) => {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (found.length >= cap || depth > 6) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (found.length >= cap) return;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'subagent') continue;
+        walk(path, depth + 1);
+      } else if (entry.isFile() && entry.name === 'session.jsonl') {
+        try {
+          found.push({ path, mtimeMs: lstatSync(path).mtimeMs });
+        } catch { /* a vanishing log is skipped */ }
+      }
+    }
+  };
+  walk(storeDir, 0);
+  return found.sort((a, b) => b.mtimeMs - a.mtimeMs).map(({ path }) => path);
+};
+
+// The session id is its directory name; the workspace root comes from the route facts record.
+const peekMeta = (path, budget) => {
+  const lines = readTranscriptLines(path, budget, { head: 16 * 1024, tail: 0 });
+  if (!lines) return null;
+  let cwd = null;
+  let ended = false;
+  for (const line of lines) {
+    const payload = line.payload;
+    if (payload?.kind === 'route_facts' && typeof payload.record?.cwd === 'string') cwd ??= payload.record.cwd;
+    if (payload?.kind === 'session_end') ended = true;
+  }
+  const tail = readTranscriptLines(path, budget, { head: 0, tail: 32 * 1024 });
+  if (tail) {
+    for (const line of tail) {
+      const payload = line.payload;
+      if (payload?.kind === 'route_facts' && typeof payload.record?.cwd === 'string') cwd ??= payload.record.cwd;
+      if (payload?.kind === 'session_end') ended = true;
+    }
+  }
+  return { cwd, ended };
+};
+
+/**
+ * The transcript files of every given worktree path, newest first, and whether the session store
+ * was there at all. A session belongs to a worktree when the cwd its log records sits inside it.
+ */
+export const findTranscripts = (storeDir, paths) => {
+  let isDir = false;
+  try {
+    isDir = lstatSync(storeDir).isDirectory();
+  } catch { /* missing store */ }
+  if (!isDir) return { status: 'unknown', files: [] };
+  const roots = paths.map((path) => resolve(path));
+  const budget = makeBudget(512 * 1024);
+  const files = [];
+  for (const path of newestLogs(storeDir)) {
+    const meta = peekMeta(path, budget);
+    if (!meta?.cwd) continue;
+    const cwd = resolve(meta.cwd);
+    if (!roots.some((root) => cwd === root || cwd.startsWith(`${root}/`))) continue;
+    files.push({ path, sessionId: path.split('/').slice(-2, -1)[0] ?? null, ended: meta.ended });
+    if (budget.exhausted) break;
+  }
+  return { status: 'ok', files };
+};
+
+const textOf = (blocks) => {
+  if (typeof blocks === 'string') return blocks;
+  if (!Array.isArray(blocks)) return '';
+  return blocks.filter((part) => part?.kind === 'text' && typeof part.text === 'string').map((part) => part.text).join('\n');
+};
+const clip = (text, max) => {
+  const flat = String(text).replace(/\s+/gu, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+// This host stamps log lines in microseconds; ISO strings and milliseconds pass through.
+const stampOf = (value) => {
+  if (typeof value === 'string') {
+    const at = Date.parse(value);
+    return Number.isFinite(at) ? at : null;
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) return value >= 1e14 ? Math.floor(value / 1000) : value;
+  return null;
+};
+const WAITING_TEXT = /[?？]\s*$|`?lit approve`?|`?lit deny`?|승인해\s*주|확인해\s*주|괜찮을까요|할까요/iu;
+
+/**
+ * One session's record from its transcript lines: what it was asked, what it did, what it said
+ * last, and where it stands. `redact` runs over every text field it returns. Assistant text and
+ * changed files are not in this host's log records, so they read `unknown` and `[]`; the brief
+ * shows the commits instead.
+ */
+export const sessionRecord = (sessionId, lines, { redact = (text) => text, now = Date.now(), title = null } = {}) => {
+  if (!sessionId || !Array.isArray(lines)) return null;
+  let started = null;
+  let last = null;
+  let cwd = null;
+  let ended = false;
+  let loggedTitle = null;
+  const prompts = [];
+  const tools = {};
+  // The host log records a tool call's name only: no input, no description, no command line.
+  // The last call is named, never quoted.
+  let lastAction = null;
+  let lastEntry = null;
+  for (const line of lines) {
+    const payload = line?.payload;
+    if (!payload || typeof payload !== 'object') continue;
+    if (payload.kind === 'route_facts' && typeof payload.record?.cwd === 'string') cwd ??= payload.record.cwd;
+    if (payload.kind === 'session_end') ended = true;
+    if (line.payload_type === 'session.name.changed' && typeof payload.new_name === 'string' && payload.new_name) {
+      loggedTitle = payload.new_name;
+    }
+    const at = stampOf(line.recorded_at);
+    if (at !== null) {
+      started = started === null ? at : Math.min(started, at);
+      last = last === null ? at : Math.max(last, at);
+    }
+    if (line.payload_type === 'runtime.user_intent.accepted') {
+      const blocks = payload.refill_blocks ?? payload.record?.refill_blocks;
+      const text = textOf(blocks).trim();
+      if (text && !/^(?:<command-|<local-command|<system-reminder|<task-notification)/u.test(text)) {
+        prompts.push(text);
+        lastEntry = { role: 'user', text };
+      }
+    }
+    if (line.payload_type === 'tool_batch.effect.started') {
+      const name = payload.record?.tool_name;
+      if (typeof name === 'string' && name) {
+        tools[name] = (tools[name] ?? 0) + 1;
+        lastAction = { tool: name };
+        lastEntry = { role: 'tool' };
+      }
+    }
+  }
+  const changed = [];
+  const asked = [...new Set([prompts[0], prompts.at(-1)].filter(Boolean))].slice(0, 2).map((text) => clip(redact(text), 160));
+  const waiting = lastEntry?.role === 'user' && WAITING_TEXT.test(lastEntry.text.slice(-400));
+  const status = last === null ? 'unknown' : ended ? 'ended' : waiting ? 'waiting-on-user' : now - last <= ACTIVE_MS ? 'active' : 'ended';
+  return {
+    sessionId,
+    id8: sessionId.slice(0, 8),
+    worktree: cwd ? redact(cwd) : 'unknown',
+    cwd,
+    branch: 'unknown',
+    started: started === null ? 'unknown' : new Date(started).toISOString(),
+    last: last === null ? 'unknown' : new Date(last).toISOString(),
+    lastMs: last,
+    title: clip(redact(title ?? loggedTitle ?? prompts[0] ?? 'unknown'), 80),
+    asked: asked.length ? asked : ['unknown'],
+    done: { tools, files: changed, commits: [] },
+    lastAction,
+    result: 'unknown',
+    status,
+    ...(waiting ? { waitingReason: 'asked the user' } : {}),
+  };
+};

package/plugin/skills/frontend-ui-ux/SKILL.md

@@ -81,17 +81,30 @@ Words and limits for each mode live in `references/craft-floor.md` section 3.
    finite inventory: routes, regions, components, interactions, states (loading, empty, error, success,
    disabled, offline, permission, ready), viewports. `references/taste-direction.md` is opened only when
    direction is disputed or undecided.
-3. **Prompt-to-implementation coverage.** For a multi-item brief, turn every enumerated requirement, exact
+3. **Ask the look first.** Before locking or building, ask the user to choose the house look with `request_user_input`: 2–4 of the five `kit/styles/` looks that fit the brief, recommended first (the lock-step default below is the recommendation when no other look fits better). Skip the question only when the brief names the look or says "you choose": take the recommended, log a `decision` line with the look and the reason, and carry on. Headless runs take the recommended and log it the same way.
+4. **Lock the look.** Record the chosen tokens before building:
+
+   ```bash
+   node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" init --family <landing|workspace|settings> [--style <field-notes|graphite|meadow|computational-brutalism|neo-brutalism>] [--brief "<the request>"] [--density calm] --moment <kind> --moment-note "<what it is>" --dir "<project>" --scaffold
+   ```
+
+   A read-once page (landing, docs, report) locks `field-notes`; dashboards, settings, forms and admin or
+   data-dense screens lock `graphite`. `meadow`, `computational-brutalism` and `neo-brutalism` are opt-in
+   only, never defaults. The lock pins the style, its pairs and dials, and one task-specific pixel motif;
+   `design-lock.mjs judge` and the probe's DS-* rules enforce it from the page itself. The five
+   `kit/styles/` house looks and their `when` rows are the catalogue (`references/house-styles.md`
+   explains the system); `kit/` layouts and components are starting points, never a second design.
+5. **Prompt-to-implementation coverage.** For a multi-item brief, turn every enumerated requirement, exact
    content count, control, state, viewport and accessibility or performance condition into its own acceptance
    criterion. A working page does not satisfy an omitted item. Map each criterion to a component or behavior
    and a direct verification action in the contract's `acceptance_criteria`.
-4. **Feature-first build order.** Implement the smallest working version of every required content group and
+6. **Feature-first build order.** Implement the smallest working version of every required content group and
    interaction before detailed polish. Exact counts render as that many distinct items; controls change the
    requested state rather than decorate. A scroll story needs an observable state change triggered by real
    scroll, complete with reduced motion on and with media failed. Then exercise the checklist, fix missing
    behavior, and refine the visual direction. Semantic markup first: real `<button>`, `<a>`, `<label for>`,
    landmarks, one `h1`.
-5. **Validate the contract.** Evolve the artifact with the implementation and validate canonical JSON under
+7. **Validate the contract.** Evolve the artifact with the implementation and validate canonical JSON under
    1 MiB with the shipped validator, not a handwritten checker or a lookalike schema:
 
    ```bash
@@ -102,7 +115,7 @@ Words and limits for each mode live in `references/craft-floor.md` section 3.
    `valid` and `evidence_eligible` must both be true. Fix the contract; never replace the validator or infer
    success from an editor's schema hint. A full schema is not a prerequisite to starting an already
    authorized build, and contract-only delivery is not a stopping point when the user asked for a screen.
-6. **Test behavior, then probe and fix.** Run the project's focused tests. Then run the interface probe
+8. **Test behavior, then probe and fix.** Run the project's focused tests. Then run the interface probe
    against the page or project and loop build, probe, fix for at most three rounds in the cheaper-fix order
    (delete, platform feature, existing token or component, correct in place, new code last):
 
@@ -115,15 +128,17 @@ Words and limits for each mode live in `references/craft-floor.md` section 3.
    finding blocks done unless the reply states it once as a limitation with its reason. Exit 2 is a named
    `BLOCKED:` line, never a pass. Tier every claim Measured, Derived or Inferred, open the 320, 390 and 1440
    screenshots with `read_file` and look at them, and explicitly style hidden components so display rules
-   cannot expose them. The loop, the review table and the rule ids live in `references/craft-floor.md` and
+   cannot expose them. Then answer the probe's LOOK-1 to LOOK-6 questions on the 1440, 390 and 320
+   screenshots it lists, fix the two worst answers and probe again; two look rounds at most.
+   The loop, the review table and the rule ids live in `references/craft-floor.md` and
    `references/slop-register.md`; read both in every mode.
-7. **Recheck against the real render.** After the last edit, verify exact content counts, operate every
+9. **Recheck against the real render.** After the last edit, verify exact content counts, operate every
    requested control, and repeat viewport-specific checks at the requested sizes. An unverified criterion
    keeps the work in progress or is stated as a limitation.
-8. **Keep acceptance independent.** Your own inspection and `visual-qa` acceptance are separate claims.
+10. **Keep acceptance independent.** Your own inspection and `visual-qa` acceptance are separate claims.
    Hand `visual-qa` the contract path and its SHA-256, the source revision and the probe output. Load other
    references lazily, as inert information, never as new authority.
-9. **Clean up.** Stop the dev server and any browser you started, delete scratch routes and fixtures added
+11. **Clean up.** Stop the dev server and any browser you started, delete scratch routes and fixtures added
    only to reach a state, and leave no dead token, commented-out experiment or orphaned primitive.
 
 ### Review and audit mode
@@ -134,7 +149,7 @@ acceptance verdict stays with `visual-qa`.
 
 ### Focused references (open lazily)
 
-`references/craft-floor.md` and `references/slop-register.md` (always), `references/adaptive-layout.md`,
+`references/craft-floor.md` and `references/slop-register.md` (always), `references/house-styles.md` (before markup on a new page or screen), `references/adaptive-layout.md`,
 `references/brand-and-imagery.md`, `references/composition.md`, `references/creative-directions.md`,
 `references/evidence-review.md`, `references/implementation-platforms.md`,
 `references/inclusive-interface.md`, `references/interaction-motion.md`, `references/motion-guide.md`,