pan-wizard 3.5.2 → 3.7.10

package/pan-wizard-core/bin/lib/config.cjs

@@ -52,6 +52,7 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       plan_check: true,
       verifier: true,
       nyquist_validation: false,
+      phase_record_compact: false,
     },
     parallelization: true,
     brave_search: hasBraveSearch,
@@ -422,17 +423,27 @@ function cmdStandardsRecommend(cwd, raw) {
   if (/\b(enterprise|togaf|architecture\s*governance|compliance)\b/.test(lower)) detectedTypes.push('enterprise');
   if (/\b(cli|command.line|terminal|shell|argv)\b/.test(lower)) detectedTypes.push('cli');
 
-  if (detectedTypes.length === 0) detectedTypes.push('general');
+  const explicitlyDetected = detectedTypes.length > 0;
+  if (!explicitlyDetected) detectedTypes.push('general');
 
   const seen = new Set();
   const recommendations = [];
   for (const type of detectedTypes) {
     const recs = STANDARDS_RECOMMENDATIONS[type] || [];
+    let perTypeIndex = 0;
     for (const id of recs) {
       if (seen.has(id)) continue;
       seen.add(id);
       const s = STANDARDS_CATALOG[id];
-      recommendations.push({ id, name: s.name, reason: type + ' project detected', priority: recommendations.length < 3 ? 'high' : 'medium' });
+      const isHigh = explicitlyDetected && type !== 'general' && perTypeIndex === 0;
+      recommendations.push({
+        id,
+        name: s.name,
+        reason: type + ' project detected',
+        priority: isHigh ? 'high' : 'medium',
+        source_type: type,
+      });
+      perTypeIndex += 1;
     }
   }
 

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -21,6 +21,51 @@ function estimateTokens(text) {
   return Math.ceil(text.length / CHARS_PER_TOKEN);
 }
 
+/**
+ * Estimate a relevance signal for per-phase markdown content (P-RES-002).
+ *
+ * Per Chroma's "Context Rot" research (Hong & Huber, July 2025): a single
+ * semantically-similar-but-irrelevant distractor degrades performance even
+ * at modest context sizes. Distractor density matters more than token count.
+ *
+ * Computing TRUE topic-relevance requires embeddings or keyword analysis
+ * we can't do cheaply at zero deps. This v0 heuristic reports a simpler
+ * signal: structure-vs-content ratio. Markdown files heavy on headers,
+ * separators, empty bullet lists, and placeholder text are LESS dense in
+ * actual signal than files of equal length with concrete prose. The ratio
+ * isn't true distractor density but is correlated with it for the
+ * "thin/template-only context" failure mode.
+ *
+ * Returns ratio in [0, 1] where 1 = all content lines, 0 = all structure.
+ * Returns null if not enough lines to compute meaningfully.
+ *
+ * @param {string} text
+ * @returns {number|null}
+ */
+function estimateRelevanceRatio(text) {
+  if (!text) return null;
+  const lines = text.split(/\r?\n/);
+  if (lines.length < 5) return null;
+  let contentLines = 0;
+  let totalLines = 0;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;                              // skip blank
+    totalLines++;
+    if (/^#{1,6}\s/.test(line)) continue;             // skip header
+    if (/^[-*_]{3,}$/.test(line)) continue;           // skip separator
+    if (/^[-*]\s*$/.test(line)) continue;             // skip empty bullet
+    if (/^[-*]\s*\[\s*[\]x_]\s*\]\s*$/.test(line)) continue; // empty checkbox
+    if (/^\|\s*-+\s*\|/.test(line)) continue;         // table separator row
+    if (/^>\s*$/.test(line)) continue;                // empty blockquote
+    if (line.length < 10) continue;                   // very short — likely scaffolding
+    if (/^(TODO|TBD|FIXME|placeholder|todo|tbd|fixme|placeholder|coming soon)\b/i.test(line)) continue;
+    contentLines++;
+  }
+  if (totalLines === 0) return null;
+  return Math.round((contentLines / totalLines) * 1000) / 1000;
+}
+
 /**
  * Compute context budget for the current project state.
  * @param {string} cwd - Project root directory
@@ -101,6 +146,32 @@ function cmdContextBudget(cwd, raw) {
     recommendation = `Within budget. ~${additionalPlans} more plans could fit before degradation.`;
   }
 
+  // P-RES-002 signal: structure-vs-content ratio for per-phase markdown.
+  // High structure (lots of empty bullets, headers, placeholders) suggests
+  // the per-phase context is thin/templatey rather than substantive — a
+  // proxy for "context that's wasting tokens on filler."
+  let relevanceSignal = null;
+  if (phaseDir) {
+    const fullPhasePath = path.join(cwd, phaseDir);
+    const samples = [];
+    for (const fname of ['research.md', 'context.md']) {
+      const candidate = path.join(fullPhasePath, fname);
+      const content = safeReadFile(candidate);
+      if (content) {
+        const ratio = estimateRelevanceRatio(content);
+        if (ratio !== null) samples.push({ file: toPosix(path.join(phaseDir, fname)), ratio });
+      }
+    }
+    if (samples.length > 0) {
+      const avg = samples.reduce((a, s) => a + s.ratio, 0) / samples.length;
+      relevanceSignal = {
+        avg_ratio: Math.round(avg * 1000) / 1000,
+        samples,
+        note: 'P-RES-002 v0 heuristic — structure/content ratio. <0.4 suggests thin per-phase context (heavy on headers + empty buckets + placeholders).',
+      };
+    }
+  }
+
   // E-8: cache metrics — surface how much of the total context would be
   // served from prompt cache when Opus 4.7 cache_control is active.
   const { buildCachedContext } = require('./core.cjs');
@@ -141,6 +212,7 @@ function cmdContextBudget(cwd, raw) {
     contextWindow: CONTEXT_WINDOW,
     budgetUtilization: Math.round(utilization * 1000) / 1000,
     cache,
+    relevanceSignal,
     recommendation,
   };
 
@@ -174,4 +246,5 @@ function cmdContextBudget(cwd, raw) {
 module.exports = {
   cmdContextBudget,
   estimateTokens,
+  estimateRelevanceRatio,
 };

package/pan-wizard-core/bin/lib/core.cjs

@@ -48,6 +48,7 @@ const COST_MULTIPLIERS = { reasoning: 15, mid: 3, fast: 1 };
 // ─── Model Profile Table ─────────────────────────────────────────────────────
 
 const MODEL_PROFILES = {
+  // Original planning/execution agents (pre-v3.0)
   'pan-planner':              { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-roadmapper':           { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
   'pan-executor':             { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
@@ -60,6 +61,18 @@ const MODEL_PROFILES = {
   'pan-plan-checker':         { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
   'pan-integration-checker':  { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
   'pan-reviewer':             { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // Spec B v2 agents (v3.0–v3.4) — added v3.7.5 to close MODEL_PROFILES drift
+  'pan-conductor':            { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-counterfactual':       { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
+  'pan-hardener':             { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-meta-reviewer':        { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-knowledge':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-previewer':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // v3.5 agents
+  'pan-optimizer':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-distiller':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // v3.7.0 self-improvement loop — observation-only watchdog
+  'pan-experiment-runner':    { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
 };
 
 // ─── Output helpers ───────────────────────────────────────────────────────────

package/pan-wizard-core/bin/lib/doc-lint/frontmatter.js

@@ -0,0 +1,270 @@
+'use strict';
+/**
+ * frontmatter.js — minimal YAML-ish frontmatter parser.
+ *
+ * Supports the subset documented in DESIGN_SPEC.md §"YAML subset":
+ *   - Scalars: strings (quoted or bare), numbers, booleans, null
+ *   - Flow lists: [a, b, c]
+ *   - Block maps: key: value (one per line)
+ *   - Comments: # ... (skipped)
+ *
+ * Anything beyond this subset → error code 'frontmatter-malformed'.
+ *
+ * Returns: {data, bodyStart, errors}
+ *   data       — parsed object (empty {} if no frontmatter)
+ *   bodyStart  — line number (1-indexed) where the body starts (after closing ---)
+ *                Used for line-number arithmetic in violation reports.
+ *   errors     — array of {line, message} for parse problems (NOT validation —
+ *                that's validate.js's job)
+ */
+
+const FENCE = '---';
+
+function parseFrontmatter(text) {
+  if (text == null) return { data: {}, bodyStart: 1, errors: [] };
+
+  const lines = text.split(/\r?\n/);
+  if (lines.length === 0 || lines[0] !== FENCE) {
+    // No frontmatter. Body starts at line 1.
+    return { data: {}, bodyStart: 1, errors: [], hasFrontmatter: false };
+  }
+
+  // Find closing fence
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === FENCE) {
+      closingIndex = i;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    return {
+      data: {},
+      bodyStart: 1,
+      errors: [{ line: 1, message: 'frontmatter opening --- has no matching closing ---' }],
+      hasFrontmatter: true,
+    };
+  }
+
+  const fmLines = lines.slice(1, closingIndex);
+  const result = parseFrontmatterBlock(fmLines);
+
+  return {
+    data: result.data,
+    bodyStart: closingIndex + 2, // 1-indexed line AFTER the closing ---
+    errors: result.errors,
+    hasFrontmatter: true,
+  };
+}
+
+function parseFrontmatterBlock(lines) {
+  const data = {};
+  const errors = [];
+
+  // Extended after dogfood gate (see .planning/optimization/traces/.../trace.jsonl event 2026-04-27T11:50:00Z):
+  // Block-style lists are the dominant real-world format. The DESIGN_SPEC originally
+  // scoped them out — that decision was wrong. Block-list support added per deviation R1.
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 2; // 1-indexed in source file (line 1 is opening ---)
+    let line = lines[i];
+
+    // Strip trailing comments
+    line = stripTrailingComment(line);
+
+    // Skip blank/comment-only lines
+    if (line.trim() === '') continue;
+
+    // Match `key:` (no value) — start of a block list or block map
+    const blockKeyMatch = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*$/);
+    if (blockKeyMatch) {
+      const key = blockKeyMatch[1];
+
+      // Look ahead: collect subsequent lines that are list items ("  - x") or
+      // sub-map entries ("  k: v") indented under this key. Stop at next top-level
+      // key (no leading whitespace) or end of block.
+      const childLines = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const next = lines[j];
+        if (next.trim() === '' || next.trim().startsWith('#')) { j++; continue; }
+        // Top-level key (no indent) ends the child block
+        if (/^[A-Za-z_]/.test(next)) break;
+        // Indented line — accumulate
+        childLines.push({ raw: next, line: j + 2 });
+        j++;
+      }
+
+      // Detect: is this a block list (- items) or a block map (key: val)?
+      const looksList = childLines.length > 0 && childLines.every(c => /^\s+-\s+/.test(c.raw));
+      if (looksList) {
+        const items = [];
+        for (const cl of childLines) {
+          const itemMatch = cl.raw.match(/^\s+-\s+(.*)$/);
+          if (!itemMatch) {
+            errors.push({ line: cl.line, message: `expected "- value" in block list, got: ${JSON.stringify(cl.raw)}` });
+            continue;
+          }
+          const itemRaw = stripTrailingComment(itemMatch[1]).trim();
+          const parsed = parseScalarOrList(itemRaw, cl.line);
+          if (parsed.error) {
+            errors.push({ line: cl.line, message: `in list item: ${parsed.error}` });
+            continue;
+          }
+          items.push(parsed.value);
+        }
+        if (key in data) {
+          errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+        } else {
+          data[key] = items;
+        }
+        i = j - 1; // resume after the block
+        continue;
+      }
+      // Block map shape: not supported in v0.1, but don't error — treat the
+      // key as null-valued and let validation handle it.
+      if (childLines.length > 0) {
+        // Block-style maps are out of scope per DESIGN_SPEC. Surface a warning
+        // rather than a crash so the rest of the file still validates.
+        errors.push({ line: lineNum, message: `block-map values not supported in v0.1 for key "${key}" (use a flow map or scalar)` });
+        i = j - 1;
+        continue;
+      }
+      // No child lines → just an empty value
+      if (key in data) {
+        errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      } else {
+        data[key] = null;
+      }
+      continue;
+    }
+
+    // Match `key: value` (scalar / flow list / etc.)
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) {
+      errors.push({ line: lineNum, message: `expected "key: value", got: ${JSON.stringify(line)}` });
+      continue;
+    }
+
+    const key = m[1];
+    const rawValue = m[2];
+
+    if (key in data) {
+      errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      continue;
+    }
+
+    const parsed = parseScalarOrList(rawValue, lineNum);
+    if (parsed.error) {
+      errors.push({ line: lineNum, message: parsed.error });
+      continue;
+    }
+    data[key] = parsed.value;
+  }
+
+  return { data, errors };
+}
+
+function stripTrailingComment(line) {
+  // Naive: strip from first # not inside quotes. PAN frontmatter doesn't put
+  // # in values, so this is safe for our subset. If a user does, they'll see
+  // a frontmatter-malformed error and can quote it.
+  const inSingle = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === "'") q++;
+    return q % 2 === 1;
+  };
+  const inDouble = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === '"') q++;
+    return q % 2 === 1;
+  };
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '#' && !inSingle(line, i) && !inDouble(line, i)) {
+      return line.slice(0, i).trimEnd();
+    }
+  }
+  return line;
+}
+
+function parseScalarOrList(raw, lineNum) {
+  const trimmed = raw.trim();
+
+  if (trimmed === '') return { value: null };
+
+  // Flow list: [a, b, c]
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === '') return { value: [] };
+    const items = splitFlowItems(inner);
+    const parsedItems = [];
+    for (const item of items) {
+      const sub = parseScalarOrList(item, lineNum);
+      if (sub.error) return { error: `in list: ${sub.error}` };
+      parsedItems.push(sub.value);
+    }
+    return { value: parsedItems };
+  }
+
+  if (trimmed.startsWith('{')) {
+    return { error: `inline maps not supported in v0.1 (got ${JSON.stringify(trimmed)})` };
+  }
+
+  // Quoted strings
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    if (trimmed.length < 2) return { error: 'unterminated quoted string' };
+    return { value: trimmed.slice(1, -1) };
+  }
+
+  // Bare keywords
+  if (trimmed === 'true') return { value: true };
+  if (trimmed === 'false') return { value: false };
+  if (trimmed === 'null' || trimmed === '~') return { value: null };
+
+  // Numbers
+  if (/^-?\d+$/.test(trimmed)) return { value: parseInt(trimmed, 10) };
+  if (/^-?\d+\.\d+$/.test(trimmed)) return { value: parseFloat(trimmed) };
+
+  // Bare string (catch-all)
+  return { value: trimmed };
+}
+
+function splitFlowItems(inner) {
+  // Simple comma-split that respects quoted strings and nested brackets.
+  const items = [];
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let current = '';
+
+  for (const ch of inner) {
+    if (inSingle) {
+      current += ch;
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      current += ch;
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+    if (ch === "'") { inSingle = true; current += ch; continue; }
+    if (ch === '"') { inDouble = true; current += ch; continue; }
+    if (ch === '[' || ch === '{') { depth++; current += ch; continue; }
+    if (ch === ']' || ch === '}') { depth--; current += ch; continue; }
+    if (ch === ',' && depth === 0) {
+      items.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim() !== '') items.push(current.trim());
+  return items;
+}
+
+module.exports = { parseFrontmatter };

package/pan-wizard-core/bin/lib/doc-lint/reporter.js

@@ -0,0 +1,45 @@
+'use strict';
+/**
+ * reporter.js — format violations for output.
+ *
+ * Two formats per DESIGN_SPEC.md §"CLI surface":
+ *   - human: <file>:<line> — <code> — <message>   (multi-line, colorless for v0.1)
+ *   - json:  NDJSON, one violation per line
+ */
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatHuman(violations) {
+  if (!violations || violations.length === 0) return '';
+  const lines = [];
+  for (const v of violations) {
+    const sev = v.severity === 'warning' ? '[warn]' : '[err] ';
+    lines.push(`${sev} ${v.file}:${v.line} — ${v.code} — ${v.message}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatJson(violations) {
+  if (!violations || violations.length === 0) return '';
+  return violations.map(v => JSON.stringify(v)).join('\n');
+}
+
+/**
+ * Returns a one-line summary suitable for end-of-run output.
+ * @param {Array<Violation>} violations
+ * @param {number} fileCount
+ * @returns {string}
+ */
+function summaryLine(violations, fileCount) {
+  const errors = violations.filter(v => v.severity === 'error').length;
+  const warnings = violations.filter(v => v.severity === 'warning').length;
+  return `Linted ${fileCount} file(s): ${errors} error(s), ${warnings} warning(s)`;
+}
+
+module.exports = { formatHuman, formatJson, summaryLine };

package/pan-wizard-core/bin/lib/doc-lint/schema.js

@@ -0,0 +1,202 @@
+'use strict';
+/**
+ * schema.js — parse + validate schema definition files.
+ *
+ * Schema source format (also YAML-ish, parsed by frontmatter.js's parser
+ * applied to a fenced wrapper):
+ *
+ *   fields:
+ *     title:
+ *       required: true
+ *       type: string
+ *       pattern: ^[A-Z]
+ *
+ * Returns: {schema, errors} where schema is the normalized form with regexes
+ * compiled, types validated, etc.
+ *
+ * Note: we don't reuse the frontmatter parser's block style — schemas use a
+ * deeper nested map shape than v0.1 frontmatter supports. We hand-roll a tiny
+ * indentation-aware parser tuned for the schema shape only. This is a
+ * scope-bounded compromise documented in DESIGN_SPEC §"YAML subset".
+ */
+
+const VALID_TYPES = ['string', 'number', 'boolean', 'enum', 'array'];
+const FIELD_KEYS = ['required', 'type', 'pattern', 'values', 'default', 'items'];
+
+/**
+ * Parse a schema source string into a normalized schema or return errors.
+ * @returns {{schema: object|null, errors: Array<{line:number, message:string}>}}
+ */
+function parseSchema(text) {
+  const errors = [];
+  if (text == null || text.trim() === '') {
+    return { schema: null, errors: [{ line: 1, message: 'schema is empty' }] };
+  }
+
+  const lines = text.split(/\r?\n/);
+
+  // Find `fields:` line
+  let fieldsLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === 'fields:') {
+      fieldsLine = i;
+      break;
+    }
+  }
+
+  if (fieldsLine === -1) {
+    errors.push({ line: 1, message: 'schema must start with `fields:` block' });
+    return { schema: null, errors };
+  }
+
+  // Parse fields block
+  const fields = {};
+  let currentField = null;
+  let currentFieldLine = 0;
+
+  for (let i = fieldsLine + 1; i < lines.length; i++) {
+    const lineNum = i + 1; // 1-indexed
+    const raw = lines[i];
+
+    // Skip blank lines
+    if (raw.trim() === '') continue;
+    // Skip comment lines
+    if (raw.trim().startsWith('#')) continue;
+
+    // Field name: 2-space indent, ends with `:`
+    const fieldMatch = raw.match(/^  ([A-Za-z_][A-Za-z0-9_-]*):\s*$/);
+    if (fieldMatch) {
+      currentField = fieldMatch[1];
+      currentFieldLine = lineNum;
+      if (currentField in fields) {
+        errors.push({ line: lineNum, message: `duplicate field "${currentField}"` });
+      }
+      fields[currentField] = { _line: lineNum };
+      continue;
+    }
+
+    // Field property: 4-space indent
+    const propMatch = raw.match(/^    ([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (propMatch && currentField) {
+      const key = propMatch[1];
+      const rawValue = propMatch[2].trim();
+
+      if (!FIELD_KEYS.includes(key)) {
+        errors.push({ line: lineNum, message: `unknown field property "${key}" (allowed: ${FIELD_KEYS.join(', ')})` });
+        continue;
+      }
+
+      const parsed = parseSchemaValue(key, rawValue, lineNum);
+      if (parsed.error) {
+        errors.push({ line: lineNum, message: parsed.error });
+        continue;
+      }
+      fields[currentField][key] = parsed.value;
+      continue;
+    }
+
+    // Anything else (including incorrectly-indented lines)
+    if (raw.length > 0 && !/^\s*$/.test(raw)) {
+      errors.push({ line: lineNum, message: `unexpected line in fields block: ${JSON.stringify(raw)}` });
+    }
+  }
+
+  // Validate each field
+  const normalized = {};
+  for (const [name, def] of Object.entries(fields)) {
+    const fieldErrors = checkFieldDefinition(name, def);
+    errors.push(...fieldErrors);
+    if (fieldErrors.length === 0) {
+      // Strip the _line marker from the public shape; keep all other props
+      const { _line, ...publicDef } = def;
+      normalized[name] = publicDef;
+    }
+  }
+
+  return {
+    schema: errors.length === 0 ? { fields: normalized } : null,
+    errors,
+  };
+}
+
+function parseSchemaValue(key, rawValue, lineNum) {
+  if (key === 'required') {
+    if (rawValue === 'true') return { value: true };
+    if (rawValue === 'false') return { value: false };
+    return { error: `required must be true|false, got ${JSON.stringify(rawValue)}` };
+  }
+
+  if (key === 'type') {
+    if (!VALID_TYPES.includes(rawValue)) {
+      return { error: `type must be one of ${VALID_TYPES.join(', ')}, got ${JSON.stringify(rawValue)}` };
+    }
+    return { value: rawValue };
+  }
+
+  if (key === 'pattern') {
+    try {
+      return { value: new RegExp(rawValue) };
+    } catch (e) {
+      return { error: `invalid regex pattern: ${e.message}` };
+    }
+  }
+
+  if (key === 'values') {
+    // Inline list shape: [a, b, c]
+    if (!rawValue.startsWith('[') || !rawValue.endsWith(']')) {
+      return { error: `values must be a flow list [a, b, c], got ${JSON.stringify(rawValue)}` };
+    }
+    const inner = rawValue.slice(1, -1).trim();
+    if (inner === '') return { value: [] };
+    return { value: inner.split(',').map(s => s.trim()).filter(Boolean) };
+  }
+
+  if (key === 'default') {
+    return { value: rawValue }; // store raw
+  }
+
+  if (key === 'items') {
+    if (!VALID_TYPES.includes(rawValue)) {
+      return { error: `items must be one of ${VALID_TYPES.join(', ')}, got ${JSON.stringify(rawValue)}` };
+    }
+    return { value: rawValue };
+  }
+
+  return { error: `unknown property ${key}` };
+}
+
+function checkFieldDefinition(name, def) {
+  const errors = [];
+  const line = def._line || 1;
+
+  if (!('type' in def)) {
+    errors.push({ line, message: `field "${name}" missing required property "type"` });
+    return errors;
+  }
+
+  if (def.type === 'enum' && !('values' in def)) {
+    errors.push({ line, message: `field "${name}" type=enum requires "values:"` });
+  }
+
+  if (def.type === 'array' && !('items' in def)) {
+    errors.push({ line, message: `field "${name}" type=array requires "items:"` });
+  }
+
+  if (def.required === true && 'default' in def) {
+    errors.push({ line, message: `field "${name}" cannot have both required:true and default:` });
+  }
+
+  return errors;
+}
+
+/**
+ * Public API: validate that a parsed schema is well-formed (no extra checks
+ * beyond what parseSchema already does, but exposed for the CLI's
+ * `whooo schema check` subcommand).
+ */
+function checkSchema(schemaText) {
+  const result = parseSchema(schemaText);
+  return { ok: result.errors.length === 0, errors: result.errors };
+}
+
+module.exports = { parseSchema, checkSchema, VALID_TYPES, FIELD_KEYS };