cli-five 0.2.13 → 0.2.16

package/src/util/merge.mjs

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname } from 'node:path';
+
+const JSON_EXTENSIONS = new Set(['.json']);
+
+/**
+ * Surgically merge a named block into an existing file **without touching the
+ * rest of it**. Unlike init's blunt overwrite gate (which replaces whole files),
+ * `mergeBlock` is designed for `cli-five add` against repos that are already
+ * scaffolded.
+ *
+ * Two strategies, chosen by file extension:
+ *
+ *   JSON (.json)
+ *     `content` (a plain object or a JSON string) is deep-merged into the file.
+ *     Existing keys are preserved; overlapping scalar/array keys are replaced.
+ *     Passing `fenceKey` nests the patch under that top-level key instead of
+ *     merging at the root (e.g. `{ fenceKey: 'mcp' }` for `opencode.json`).
+ *
+ *   Markdown / other text
+ *     `content` is wrapped in HTML-comment fences derived from `markerFence`:
+ *       <!-- NAME_START -->
+ *       ...content...
+ *       <!-- NAME_END -->
+ *     If the fences already exist the body between them is replaced in place;
+ *     otherwise the block is appended. Re-running is idempotent.
+ *
+ * @param {string} filePath              Absolute path to the target file.
+ * @param {string|{name?:string,start?:string,end?:string}} markerFence
+ *        Block name (e.g. "codegraph"), or explicit `{ start, end }` markers.
+ * @param {string|object} content        Markdown body, or object / JSON string.
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun]     Compute but do not write.
+ * @param {string|null} [options.fenceKey] JSON only — nest the merge under this key.
+ * @param {boolean} [options.track]      JSON only — record the block name under `$cliFive`.
+ * @param {string} [options.metaKey]     JSON only — metadata key (default `$cliFive`).
+ * @returns {{path:string, block:string, action:'created'|'updated'|'unchanged', dryRun:boolean}}
+ */
+export function mergeBlock(filePath, markerFence, content, options = {}) {
+  const { dryRun = false, fenceKey = null, track = false, metaKey = '$cliFive' } = options;
+  const block = fenceName(markerFence);
+
+  const ext = extname(filePath).toLowerCase();
+  const result = JSON_EXTENSIONS.has(ext)
+    ? mergeJson(filePath, block, content, { fenceKey, track, metaKey })
+    : mergeText(filePath, markerFence, content);
+
+  if (!dryRun && (result.action === 'created' || result.action === 'updated')) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, result.contents);
+  }
+
+  return { path: filePath, block, action: result.action, dryRun };
+}
+
+// ── Markdown / text ───────────────────────────────────────────────────
+
+function mergeText(filePath, markerFence, content) {
+  const { start, end } = fenceMarkers(markerFence);
+  const body = String(content ?? '').replace(/\s+$/, '');
+  const core = `${start}\n${body}\n${end}`;
+
+  if (!existsSync(filePath)) {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const existing = readFileSync(filePath, 'utf8');
+  if (existing.trim() === '') {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
+  if (pattern.test(existing)) {
+    const next = existing.replace(pattern, core);
+    return { contents: next, action: next === existing ? 'unchanged' : 'updated' };
+  }
+
+  const next = `${existing.replace(/\s+$/, '')}\n\n${core}\n`;
+  return { contents: next, action: 'updated' };
+}
+
+function fenceMarkers(markerFence) {
+  if (isPlainObject(markerFence) && markerFence.start && markerFence.end) {
+    return { start: markerFence.start, end: markerFence.end };
+  }
+  const name = fenceName(markerFence).toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return { start: `<!-- ${name}_START -->`, end: `<!-- ${name}_END -->` };
+}
+
+// ── JSON ──────────────────────────────────────────────────────────────
+
+function mergeJson(filePath, block, content, { fenceKey, track, metaKey }) {
+  let existing = {};
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, 'utf8').trim();
+    if (raw) {
+      try {
+        existing = JSON.parse(raw);
+      } catch (err) {
+        throw new Error(`mergeBlock: ${filePath} is not valid JSON: ${err.message}`);
+      }
+    }
+  }
+
+  if (!isPlainObject(existing)) {
+    throw new Error(`mergeBlock: ${filePath} must contain a JSON object at the root`);
+  }
+
+  let patch = content;
+  if (typeof patch === 'string') {
+    try {
+      patch = JSON.parse(patch);
+    } catch (err) {
+      throw new Error(`mergeBlock: content for ${filePath} is not valid JSON: ${err.message}`);
+    }
+  }
+  if (!isPlainObject(patch)) {
+    throw new Error(`mergeBlock: content for ${filePath} must be a JSON object`);
+  }
+
+  const before = JSON.stringify(existing);
+
+  const target = fenceKey
+    ? (isPlainObject(existing[fenceKey]) ? existing[fenceKey] : (existing[fenceKey] = {}))
+    : existing;
+  deepMerge(target, patch);
+
+  if (track) {
+    const meta = isPlainObject(existing[metaKey]) ? existing[metaKey] : (existing[metaKey] = {});
+    const blocks = Array.isArray(meta.blocks) ? meta.blocks : (meta.blocks = []);
+    if (!blocks.includes(block)) blocks.push(block);
+  }
+
+  const contents = `${JSON.stringify(existing, null, 2)}\n`;
+  const action = before === JSON.stringify(existing) && existsSync(filePath) ? 'unchanged' : (existsSync(filePath) ? 'updated' : 'created');
+  return { contents, action };
+}
+
+function deepMerge(target, patch) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (isPlainObject(value) && isPlainObject(target[key])) {
+      deepMerge(target[key], value);
+    } else if (isPlainObject(value)) {
+      target[key] = deepMerge({}, value);
+    } else if (Array.isArray(value)) {
+      target[key] = [...value];
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function fenceName(markerFence) {
+  if (typeof markerFence === 'string' && markerFence.trim()) return markerFence.trim();
+  if (isPlainObject(markerFence) && typeof markerFence.name === 'string' && markerFence.name.trim()) {
+    return markerFence.name.trim();
+  }
+  throw new Error('mergeBlock: markerFence must be a non-empty string or { name }');
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/util/models.mjs

@@ -0,0 +1,148 @@
+// Model catalogs and defaults per provider.
+// Provider IDs match the values used in OpenCode config (`provider/model-id`).
+
+export const PROVIDER_COPILOT = 'copilot';
+export const PROVIDER_ZEN = 'opencode';
+export const PROVIDER_GO = 'opencode-go';
+
+export const PROVIDERS = [PROVIDER_COPILOT, PROVIDER_ZEN, PROVIDER_GO];
+
+export const PROVIDER_LABELS = {
+  [PROVIDER_COPILOT]: 'GitHub Copilot',
+  [PROVIDER_ZEN]: 'OpenCode Zen',
+  [PROVIDER_GO]: 'OpenCode Go',
+};
+
+const AGENTS = ['Orchestrator', 'Planner', 'Coder', 'Designer', 'Reviewer'];
+
+export const DEFAULT_MODEL_MAP = {
+  [PROVIDER_COPILOT]: {
+    Orchestrator: 'Claude Sonnet 4.6 (copilot)',
+    Planner: 'Claude Opus 4.6 (copilot)',
+    Coder: 'GPT-5.3-Codex (copilot)',
+    Designer: 'Gemini 3.1 Pro (Preview) (copilot)',
+    Reviewer: 'Claude Sonnet 4.6 (copilot)',
+  },
+  [PROVIDER_ZEN]: {
+    Orchestrator: 'opencode/gpt-5.3-codex',
+    Planner: 'opencode/claude-opus-4-6',
+    Coder: 'opencode/gpt-5.3-codex',
+    Designer: 'opencode/gemini-3.1-pro',
+    Reviewer: 'opencode/claude-sonnet-4-6',
+  },
+  [PROVIDER_GO]: {
+    Orchestrator: 'opencode-go/qwen3.8-max',
+    Planner: 'opencode-go/deepseek-v4-pro',
+    Coder: 'opencode-go/qwen3.8-max',
+    Designer: 'opencode-go/gpt-5.6-luna',
+    Reviewer: 'opencode-go/kimi-k2.7-code',
+  },
+};
+
+// Curated model choices shown in the interview picker.
+// Each entry is a full model reference string for the given provider.
+export const PROVIDER_MODEL_CATALOG = {
+  [PROVIDER_COPILOT]: [
+    'Claude Sonnet 4.6 (copilot)',
+    'Claude Opus 4.6 (copilot)',
+    'Claude Opus 4.5 (copilot)',
+    'GPT-5.3-Codex (copilot)',
+    'GPT-5.2-Codex (copilot)',
+    'GPT-5.1-Codex (copilot)',
+    'GPT-5 (copilot)',
+    'GPT-5 mini (copilot)',
+    'GPT-4.1 (copilot)',
+    'GPT-4o (copilot)',
+    'Gemini 3.1 Pro (Preview) (copilot)',
+    'Gemini 3 Flash (Preview) (copilot)',
+  ],
+  [PROVIDER_ZEN]: [
+    'opencode/gpt-5.3-codex',
+    'opencode/gpt-5.2-codex',
+    'opencode/gpt-5.1-codex',
+    'opencode/gpt-5.1-codex-max',
+    'opencode/gpt-5.1-codex-mini',
+    'opencode/gpt-5',
+    'opencode/gpt-5-nano',
+    'opencode/claude-opus-4-6',
+    'opencode/claude-opus-4-5',
+    'opencode/claude-sonnet-4-6',
+    'opencode/claude-sonnet-4-5',
+    'opencode/gemini-3.1-pro',
+    'opencode/gemini-3-flash',
+    'opencode/kimi-k2.7-code',
+    'opencode/kimi-k2.6',
+    'opencode/qwen3.8-max',
+    'opencode/qwen3.8-flash',
+    'opencode/qwen3.7-plus',
+    'opencode/deepseek-v4-pro',
+    'opencode/deepseek-v4.1-flash',
+  ],
+  [PROVIDER_GO]: [
+    'opencode-go/qwen3.8-max',
+    'opencode-go/qwen3.8-flash',
+    'opencode-go/qwen3.7-max',
+    'opencode-go/qwen3.7-plus',
+    'opencode-go/qwen3.6-plus',
+    'opencode-go/deepseek-v4-pro',
+    'opencode-go/deepseek-v4.1-flash',
+    'opencode-go/deepseek-v4-flash',
+    'opencode-go/kimi-k3',
+    'opencode-go/kimi-k2.7-code',
+    'opencode-go/kimi-k2.6',
+    'opencode-go/glm-5.3',
+    'opencode-go/glm-5.2',
+    'opencode-go/glm-5.1',
+    'opencode-go/glm-5.3-flash',
+    'opencode-go/minimax-m3',
+    'opencode-go/minimax-m2.7',
+    'opencode-go/gpt-6-luna',
+    'opencode-go/gpt-5.6-luna',
+    'opencode-go/muse-spark-1.3-contributor',
+    'opencode-go/muse-spark-1.2-contributor',
+    'opencode-go/mimo-v2.6-flash',
+    'opencode-go/mimo-v2.6-pro',
+    'opencode-go/grok-4.7',
+    'opencode-go/grok-4.6',
+    'opencode-go/longcat-2.0',
+    'opencode-go/space-bunny-free',
+  ],
+};
+
+export function getDefaultModelMap(provider) {
+  return { ...DEFAULT_MODEL_MAP[provider] };
+}
+
+export function getModelCatalog(provider) {
+  return PROVIDER_MODEL_CATALOG[provider] || [];
+}
+
+export function isValidProvider(value) {
+  return PROVIDERS.includes(value);
+}
+
+export function normalizeProvider(value) {
+  if (!value) return PROVIDER_COPILOT;
+  const lower = String(value).toLowerCase();
+  if (lower === 'zen') return PROVIDER_ZEN;
+  if (lower === 'go') return PROVIDER_GO;
+  if (lower === 'opencode') return PROVIDER_ZEN;
+  if (lower === 'opencode-go') return PROVIDER_GO;
+  if (lower === 'copilot' || lower === 'github-copilot') return PROVIDER_COPILOT;
+  return isValidProvider(lower) ? lower : PROVIDER_COPILOT;
+}
+
+export function providerLabel(provider) {
+  return PROVIDER_LABELS[provider] || provider;
+}
+
+export function agentNames() {
+  return [...AGENTS];
+}
+
+export function providerForPlatform(platform, provider) {
+  if (platform === 'opencode') {
+    return normalizeProvider(provider || PROVIDER_ZEN);
+  }
+  return PROVIDER_COPILOT;
+}

package/src/util/platforms.mjs

@@ -0,0 +1,25 @@
+// Supported cli-five platforms and CodeGraph pairing.
+
+export const PLATFORM_COPILOT = 'copilot';
+export const PLATFORM_OPENCODE = 'opencode';
+
+export const PLATFORMS = [PLATFORM_COPILOT, PLATFORM_OPENCODE];
+
+export function isValidPlatform(value) {
+  return PLATFORMS.includes(value);
+}
+
+export function platformLabel(value) {
+  return value === PLATFORM_OPENCODE ? 'OpenCode' : 'GitHub Copilot';
+}
+
+export function agentDirFor(platform) {
+  return platform === PLATFORM_OPENCODE ? '.opencode/agents' : '.github/agents';
+}
+
+export function agentFileFor(platform, name) {
+  if (platform === PLATFORM_OPENCODE) {
+    return `${name}.md`;
+  }
+  return `${name}.agent.md`;
+}

package/src/util/project.mjs

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// README variants checked in order. First match wins.
+const README_CANDIDATES = [
+  'README.md',
+  'readme.md',
+  'Readme.md',
+  'README.MD',
+  'README.markdown',
+  'README.txt',
+  'README',
+];
+
+/**
+ * Best-effort auto-extraction of a project name and one-liner from the
+ * workspace itself (package.json and/or README), used by the minimal init
+ * interview so it only has to ask when the answer is genuinely missing or
+ * ambiguous.
+ *
+ * Returns:
+ *   {
+ *     name:     { value, ambiguous, sources: [{ source, value }] },
+ *     oneLiner: { value, ambiguous, sources: [{ source, value }] },
+ *   }
+ *
+ * `value` is the first candidate (a safe fallback), `ambiguous` is true when
+ * two or more distinct candidates were found. Callers should ask the user
+ * whenever `ambiguous` is true or `value` is empty.
+ */
+export function autoProjectInfo(cwd) {
+  const nameSources = [];
+  const oneLinerSources = [];
+
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (isNonEmptyString(pkg?.name)) {
+        nameSources.push({ source: 'package.json', value: pkg.name.trim() });
+      }
+      if (isNonEmptyString(pkg?.description)) {
+        oneLinerSources.push({ source: 'package.json', value: pkg.description.trim() });
+      }
+    } catch {
+      /* malformed package.json — ignore */
+    }
+  }
+
+  for (const file of README_CANDIDATES) {
+    const filePath = join(cwd, file);
+    if (!existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const hints = extractReadmeHints(content);
+    if (hints.name) nameSources.push({ source: file, value: hints.name });
+    if (hints.oneLiner) oneLinerSources.push({ source: file, value: hints.oneLiner });
+
+    break; // first README found wins — don't blend multiple README variants
+  }
+
+  return {
+    name: summarize(nameSources),
+    oneLiner: summarize(oneLinerSources),
+  };
+}
+
+/** Pull a name (first H1) and one-liner (first prose line) out of a README. */
+export function extractReadmeHints(content) {
+  const lines = String(content || '').split('\n');
+  let name = '';
+  let oneLiner = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    if (!name) {
+      const h1 = /^#\s+(.+?)\s*$/.exec(line);
+      if (h1) {
+        name = stripInlineMarkdown(h1[1]);
+        continue;
+      }
+    }
+
+    // Wait for the first H1 before reading prose — otherwise the README may
+    // start with a logo/badge that is not a name.
+    if (!name || oneLiner) continue;
+
+    if (isProseLine(line)) {
+      oneLiner = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+    }
+  }
+
+  return { name, oneLiner };
+}
+
+function summarize(sources) {
+  if (sources.length === 0) {
+    return { value: '', ambiguous: false, sources: [] };
+  }
+
+  const distinct = [];
+  for (const entry of sources) {
+    if (!distinct.includes(entry.value)) distinct.push(entry.value);
+  }
+
+  return {
+    value: sources[0].value,
+    ambiguous: distinct.length > 1,
+    sources,
+  };
+}
+
+function isProseLine(line) {
+  // Skip headings, badges/images, code fences, lists, tables, blockquotes, HTML.
+  if (/^[#>|`*\-_]/.test(line)) return false;
+  if (/^\[!\[/.test(line)) return false;
+  if (/^!\[/.test(line)) return false;
+  if (/^<[a-zA-Z!/]/.test(line)) return false;
+  if (/^\|/.test(line)) return false;
+  return true;
+}
+
+function stripInlineMarkdown(value) {
+  return String(value)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](url) → text
+    .replace(/[*_`]/g, '')
+    .trim();
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}

package/templates/AGENTS.md.tmpl

@@ -23,3 +23,5 @@ and Copilot all read `AGENTS.md` per the [agents.md](https://agents.md) conventi
 3. Check `decisions.md` for architectural decisions already locked in.
 4. Per-agent memory lives in `histories/<agent>.md`.
 5. Append a session summary to `agent-diary.md` when work completes.
+
+{{CODEGRAPH_BLOCK}}

package/templates/opencode/agents/coder.md

@@ -0,0 +1,74 @@
+---
+name: Coder
+description: "Writes production code following workspace conventions. Use when: implementing features, fixing bugs, writing tests, creating modules."
+mode: subagent
+model: opencode/gpt-5.3-codex
+permission:
+  read: allow
+  edit: allow
+  write: allow
+  glob: allow
+  grep: allow
+  list: allow
+  bash: allow
+  webfetch: allow
+  websearch: allow
+  skill: allow
+  lsp: allow
+---
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | GPT 5.3 Codex | 1x |
+| **Cheap** | Qwen 3.8 Max | 0x |
+
+To switch: change the `model` key in frontmatter above.
+
+## Subagent Output Contract
+
+When invoked by the Orchestrator, only your **final message** is returned. Internal tool results, build output, and earlier turns are invisible.
+
+**Your response MUST contain:**
+- A list of every file created or modified (absolute paths)
+- A concise summary of what each change does
+- Build/test status if you ran them
+- Any blockers, assumptions, or deviations from the assigned task
+
+Do not say "see the diff above" — the caller cannot see your internal turns.
+
+## Required Reading
+
+ALWAYS read relevant documentation before implementation. Your training data is stale — verify, don't assume. If CodeGraph is configured, use `codegraph explore` to answer codebase questions.
+
+Before writing code, read (if they exist):
+- `decisions.md` — prior team decisions
+- `histories/coder.md` — your accumulated learnings
+- `AGENTS.md` — project mandates
+- All `.github/instructions/*.instructions.md` matching the languages involved
+- All relevant `.opencode/skills/*/SKILL.md` or `.github/skills/*/SKILL.md`
+
+## Mandatory Coding Principles
+
+1. **Structure** — Consistent project layout. Group by feature. Simple entry points. Shared patterns over duplication.
+2. **Architecture** — Flat, explicit code. No clever patterns, metaprogramming, or unnecessary indirection. Minimize coupling.
+3. **Functions** — Linear control flow. Small-to-medium functions. Pass state explicitly. No globals.
+4. **Naming** — Descriptive-but-simple names. Comment only for invariants, assumptions, or external requirements.
+5. **Logging** — Detailed, structured logs at key boundaries. Explicit, informative errors.
+6. **Regenerability** — Any file can be rewritten from scratch without breaking the system. Prefer declarative configuration.
+7. **Platform** — Use framework conventions directly and simply without over-abstracting.
+8. **Modifications** — Follow existing patterns. Prefer full-file rewrites over micro-edits unless told otherwise.
+9. **Quality** — Deterministic, testable behavior. Simple, focused tests.
+
+## Decisions (MANDATORY)
+
+Before finishing, if any implementation choice was made (library selection, pattern choice, API approach), append an entry to `decisions.md` using the format in that file. Skip silently if no decisions were made.
+
+## README.md (MANDATORY)
+
+After any session that adds, changes, or removes user-facing functionality, update `README.md` at the project root. The README must contain at minimum: project name & one-liner, **copy-paste quickstart commands** (install deps + run), usage notes, and tech stack. If `README.md` does not exist, create it as the FIRST file before any other work. A new developer must go from clone → running app in < 2 minutes.
+
+## History (MANDATORY)
+
+Before finishing, append at least one bullet to `histories/coder.md` below the `<!-- Append entries below this line -->` marker. Record: build quirks, API gotchas, pattern preferences, file structure observations, test insights. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.

package/templates/opencode/agents/designer.md

@@ -0,0 +1,65 @@
+---
+name: Designer
+description: "Handles all UI/UX design tasks. Use when: creating screens, layouts, theming, navigation flows, design systems."
+mode: subagent
+model: opencode/gemini-3.1-pro
+permission:
+  read: allow
+  edit: allow
+  write: allow
+  glob: allow
+  grep: allow
+  list: allow
+  webfetch: allow
+  websearch: allow
+  skill: allow
+---
+
+## Model Selection
+
+| Mode | Model | Premium Cost |
+|---|---|---|
+| **Default** | Gemini 3.1 Pro | 1x |
+| **Cheap** | GPT 5.6 Luna | 0x |
+
+To switch: change the `model` key in frontmatter above.
+
+## Subagent Output Contract
+
+When invoked by the Orchestrator, only your **final message** is returned. Internal tool results and earlier turns are invisible.
+
+**Your response MUST contain:**
+- A list of every UI file created or modified (absolute paths)
+- Design decisions made and accessibility/UX choices applied
+- Any open design questions or follow-ups
+
+Do not reference "the layout above" — re-state inline.
+
+## Required Reading
+
+Before design work, read (if they exist):
+- `decisions.md` — prior team decisions
+- `histories/designer.md` — your accumulated learnings
+- `AGENTS.md` — project mandates
+- All `.github/instructions/*.instructions.md` matching UI file types
+- All relevant `.opencode/skills/*/SKILL.md` or `.github/skills/*/SKILL.md`
+
+## Identity
+
+Do not let anyone tell you how to do your job. Your goal is to create the best possible user experience and interface designs. Focus on usability, accessibility, and aesthetics.
+
+## Design Principles
+
+- Accessibility first: contrast ratios, touch targets, screen reader support
+- Minimal cognitive load
+- Platform conventions over custom patterns
+- Responsive/adaptive layouts
+- Use the project's designated design system and component library
+
+## Decisions (MANDATORY)
+
+Before finishing, if any design choice was made (layout approach, component library, color/type system, responsive strategy), append an entry to `decisions.md` using the format in that file. Skip silently if no decisions were made.
+
+## History (MANDATORY)
+
+Before finishing, append at least one bullet to `histories/designer.md` below the `<!-- Append entries below this line -->` marker. Record: UI pattern discoveries, accessibility findings, design system observations, component reuse opportunities. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.