empirical-sdd 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -8,6 +8,42 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-09-09
+
+### Added
+
+- Added a saved **Create mockups before coding?** Yes/No preference to init and
+  configuration, exposed as `mockupsBeforeCoding` through MCP. Existing
+  repositories retain enabled behavior until explicitly changed. Disabling it
+  skips mandatory UI mockups while retaining fidelity checks for approved designs.
+- Added a terminal-only fresh-repository demo with recorded CLI, MCP, worktree,
+  verification, review, and integration scenarios.
+
+### Changed
+
+- Setup shows proposed defaults for new repositories and actual saved values
+  for existing repositories, with one applicable menu and explicit Save.
+- Init prefers permitted host-native selection controls and uses one text
+  prompt when they are unavailable, without duplicating the same question.
+- Linear MCP discovery resolves actual host tools by provider and capability,
+  including lazy-loaded tools, and distinguishes configuration, tool exposure,
+  authentication, permissions, and transient failures before offering recovery.
+
+### Fixed
+
+- Fixed initialization rejecting valid Linear MCP policies after discovery and
+  preview by routing them through the existing credential-free MCP setup path.
+- Prevented missing tool-name prefixes or unavailable future write operations
+  from triggering an automatic Linear API-key fallback.
+- Preserved an explicit mockup preference through repeated initialization and
+  unrelated configuration updates, while rejecting invalid values before writes.
+- Limited product test discovery to `tests/` so generated demo repositories do
+  not accidentally enter the product suite.
+
+### Migration
+
+No migration required.
+
 ## [0.32.0] - 2026-09-08
 
 ### Added
@@ -438,7 +474,8 @@ Published through GitHub Actions trusted publishing with npm provenance.
 
 - Prepared and released package version `0.20.2`.
 
-[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.32.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.33.0...HEAD
+[0.33.0]: https://github.com/goempirical/empirical-sdd/compare/v0.32.0...v0.33.0
 [0.32.0]: https://github.com/goempirical/empirical-sdd/compare/v0.31.0...v0.32.0
 [0.31.0]: https://github.com/goempirical/empirical-sdd/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/goempirical/empirical-sdd/compare/v0.29.0...v0.30.0

package/dist/cli.js

@@ -14853,7 +14853,7 @@ function verifyReceiptDigest(receipt) {
     throw new Error(`Evidence receipt ${parsed.id} has an asserted result inconsistent with its provenance.`);
   }
 }
-var SCHEMA_VERSION = 5, POLICY_SCHEMA_VERSION = 2, MANIFEST_SCHEMA_VERSION = 2, RECEIPT_SCHEMA_VERSION = 1, PRODUCT_VERSION = "0.32.0", workflowSchema, executionModeSchema, riskFloorSchema, completionLevelSchema, phaseSchema, workflowStatusSchema, criterionSchema, evidenceKindSchema, qaCheckKindSchema, qaAttemptOutcomeSchema, commandPolicySchema, evidencePolicySchema, projectPolicySchema, impactManifestSchema, authorizationSchema, COMPLETION_ORDER, receiptProvenanceSchema, receiptBaseSchema, executedReceiptSchema, artifactRecordSchema, qaCommandRecordSchema, qaResultRecordSchema, qaAttemptSchema, qaReceiptSchema, collectedReceiptSchema, evidenceReceiptSchema;
+var SCHEMA_VERSION = 5, POLICY_SCHEMA_VERSION = 2, MANIFEST_SCHEMA_VERSION = 2, RECEIPT_SCHEMA_VERSION = 1, PRODUCT_VERSION = "0.33.0", workflowSchema, executionModeSchema, riskFloorSchema, completionLevelSchema, phaseSchema, workflowStatusSchema, criterionSchema, evidenceKindSchema, qaCheckKindSchema, qaAttemptOutcomeSchema, commandPolicySchema, evidencePolicySchema, projectPolicySchema, impactManifestSchema, authorizationSchema, COMPLETION_ORDER, receiptProvenanceSchema, receiptBaseSchema, executedReceiptSchema, artifactRecordSchema, qaCommandRecordSchema, qaResultRecordSchema, qaAttemptSchema, qaReceiptSchema, collectedReceiptSchema, evidenceReceiptSchema;
 var init_protocol = __esm(() => {
   init_zod();
   workflowSchema = exports_external.enum(["fast", "complex"]);
@@ -25762,6 +25762,9 @@ function isRecord(value) {
 function normalizeConfig(config2) {
   assertSupportedSchema(config2);
   const value = config2;
+  if (value.mockupsBeforeCoding !== undefined && typeof value.mockupsBeforeCoding !== "boolean") {
+    throw new EmpiricalError("INVALID_CONFIG", "mockupsBeforeCoding must be a boolean");
+  }
   const isolation = isRecord(value.isolation) ? value.isolation : {};
   const decisions = isRecord(value.decisions) ? value.decisions : {};
   const interaction = isRecord(value.interaction) ? value.interaction : {};
@@ -25788,6 +25791,7 @@ function normalizeConfig(config2) {
     ...config2,
     schemaVersion: SCHEMA_VERSION,
     profile: normalizeProfile(config2.profile),
+    mockupsBeforeCoding: value.mockupsBeforeCoding === undefined ? true : value.mockupsBeforeCoding,
     evidence: {
       required: typeof evidence.required === "boolean" ? evidence.required : true,
       browserForUi: typeof evidence.browserForUi === "boolean" ? evidence.browserForUi : true,
@@ -25944,6 +25948,52 @@ first and private \`empirical __internal\` fallbacks only when MCP is unavailabl
 If the config is missing, invalid, or incomplete, do not initialize implicitly;
 tell the user to invoke \`empirical-init\` explicitly.
 ${END}`;
+var LINEAR_MCP_DISCOVERY_GUIDANCE = `### Discover the host's Linear connection
+
+Discover by capability, not by a guessed tool prefix. Inspect the actual host
+registry/tool metadata (including provider/server identity, descriptions and input
+schemas). Use host tool search or lazy loading when exposed; search for Linear
+and the needed operation, not just one namespace string. In code-mode hosts,
+inspect the available tool catalog (for example ALL_TOOLS) before invoking its
+actual callable name. Names such as mcp__linear__list_teams,
+mcp__plugin_linear__list_teams, or linear.list_teams are examples, not a whitelist.
+A failed prefix filter is not evidence that Linear is absent. Do not substitute
+an unrelated tool merely because its name or description contains "Linear";
+confirm provider provenance and a compatible input schema.
+
+Keep three facts separate: configured server, exposed callable tools, and a
+successful authenticated request. An enabled OAuth entry in a host's MCP list
+proves configuration, not that this session loaded its tools or can authenticate.
+When the user selected Linear discovery, verify access with a bounded read-only
+team-list request using the smallest supported limit. Never probe with a write.
+Only claim authenticated access after a successful provider response. Classify
+401/login failures, 403/permission failures, transport/rate-limit failures, and
+missing tool exposure separately; none means "Linear is not installed".
+
+For setup, discover only the needed read capabilities first: list teams, list
+projects and list issue statuses. Do not require save_issue, save_comment, or
+other future sync operations to begin read-only catalog discovery. Resolve later
+capabilities when required and report the exact missing operation. A partial
+capability set never authorizes changing authentication mode or pretending sync
+is available.
+
+Treat canonical linear.* names returned by the Empirical bridge as operation
+identifiers, not literal host tool names. Map each to the discovered actual
+callable tool and its documented schema. Preserve operation semantics, target,
+authorized fields, bounded pagination and normalized result validation. Do not
+invent an argument translation, drop a required field, or replace an unavailable
+write with another operation; report the precise capability/schema gap instead.
+
+Before reporting missing tools, exhaust the exposed registry and any available
+host search/lazy-load path. If the user shows an enabled OAuth server but tools
+remain unexposed, say "Linear is configured, but this session does not expose
+<needed capability>" and give host-specific exposure/reload recovery. Do not ask
+them to add an already configured server or log in again without an authentication
+failure. Do not infer a need for an API key from missing names, partial tools,
+permission errors or transient failures. Keep the chosen MCP/OAuth route; offer
+host-file credentials only after actual discovery/recovery checks and an explicit
+user choice to use that alternative. Never inspect private host OAuth stores.
+`;
 var INIT_SKILL_BODY = `# Empirical Init
 
 Use this skill only when the user explicitly asks to initialize, set up, or
@@ -25956,9 +26006,10 @@ Present setup as a wizard inside the current agent conversation. On each setup
 turn, show \`Empirical init — Step N of 6: <name>\` and a compact progress line
 using these stable stages, in order:
 
-1. **Setup** — inspect the repository and choose Apply recommended settings,
-   Keep current settings, Customize, Configure tracker, or Cancel as applicable.
-2. **Preferences** — verification, parallel work, decisions, and question detail.
+1. **Setup** — inspect the repository, explain the proposed or saved settings,
+   and offer only the actions applicable to that configuration.
+2. **Preferences** — verification, mockups before coding, parallel work, decisions,
+   and question detail.
 3. **Review bot** — resolve the optional bot choice once or keep its saved value.
 4. **Tracking** — keep the saved choice or complete the existing tracker flow.
 5. **Confirm** — show all effective settings; offer Save, Edit a section, or Cancel.
@@ -25968,13 +26019,22 @@ Mark each stage \`[done]\`, \`[current]\`, \`[pending]\`, or \`[blocked]\`.
 For example, while choosing tracking:
 \`[done] Setup > [done] Preferences > [done] Review bot > [current] Tracking > [pending] Confirm > [pending] Apply\`.
 Before Apply, \`[done]\` means a decision is resolved, not that settings were
-saved. Keep stage numbers stable when skipping or revisiting decisions. Use a
-host-native choice widget when available, with the same numbered text fallback;
-do not invent an interactive widget or require a browser or terminal screen.
+saved. Keep stage numbers stable when skipping or revisiting decisions. Present each pending question exactly once. Prefer a callable host-native choice
+tool permitted in the current mode: Claude Code's AskUserQuestion, Codex's
+request_user_input when available, or the equivalent exposed by another agent.
+Follow that tool's schema and option limits; do not switch host mode to unlock it.
+Native tools supply keyboard/arrow selection where supported by the host; skill
+text cannot create keyboard controls. Put choices in the native tool only, with
+one step heading/progress summary; do not also print a numbered menu. If no
+permitted choice tool is available, end the turn with one numbered text question.
+Do not render the same step, summary or question in both commentary and final.
+After asking, wait for the answer without echoing the prompt. Do not invent an
+interactive widget or require a browser or terminal screen.
 
 Show only the current section's detail and ask one material question at a time.
-Apply recommended settings and Keep current settings resolve unchanged preference
-steps without redundant questions; they never bypass the one-time bot choice,
+Use recommended settings and Keep current settings resolve unchanged preference
+steps without redundant questions; they never bypass an unresolved mockup choice,
+the one-time bot choice,
 an unconfigured tracker choice, provider authorization, or final Save. On repair,
 mark saved bot and tracker choices kept without offering them again. A user who
 already answered a question in the request need not answer it again.
@@ -26010,16 +26070,48 @@ These are presentation stages, not feature workflow phases or new durable state.
    Determine whether this is first setup or a repair. Preserve existing
    configuration values and durable workflow history unless the user explicitly
    changes a value.
-2. At Setup, show a compact overview and offer Apply recommended settings (or
-   Keep current settings), Customize, Configure tracker, and Cancel. At Confirm,
+2. At Setup, choose the menu from inspected repository configuration, never from
+   whether Empirical or its skills are globally installed:
+   - Fresh repository (no saved configuration): say "No settings saved in this
+     repository yet". Show the proposed defaults: verification required, browser
+     and screenshot evidence for UI changes, isolated code review, ask before
+     creating worktrees, automatic Git base, worktree path ../{repo}-{feature},
+     branch pattern {type}/{feature}, Complex decision records required, and
+     concise questions. Propose mockups before coding for UI changes, but resolve
+     the explicit Yes/No choice in Preferences. Label reviewer bot and tracking
+     as "Not chosen yet".
+     Offer **Use recommended settings**, **Customize**, and **Cancel** only.
+     Explain Use recommended settings as "Continue with the defaults shown;
+     nothing is saved until Save". Never offer Keep current settings here.
+   - Valid saved configuration: show its actual Verification, Parallel work,
+     Mockups before coding, Decisions, Interaction, Review bot and Tracker values, labeled "Saved in
+     this repository". Offer **Keep current settings**, **Customize**,
+     **Configure tracker**, and **Cancel**. Explain Keep as retaining the values
+     shown; never show recommended and current as competing primary choices.
+   - Invalid or incomplete configuration: explain what is missing or invalid,
+     preserve readable values in the draft, and resolve the missing choices;
+     do not claim a complete saved setup or silently replace it with defaults.
+   Keep this overview compact and put all action choices in the single native
+   tool or text fallback described above. At Confirm,
    before any mutation, render the complete effective Empirical setup summary for
-   Verification, Pull-request review, Parallel work, Decisions, Interaction,
-   and Tracker. For question detail in Preferences, offer
+   Verification, Mockups before coding, Pull-request review, Parallel work,
+   Decisions, Interaction, and Tracker. In Preferences ask **Create mockups before
+   coding?** with **Yes (Recommended)** — approve a mockup before coding UI changes,
+   and **No** — start UI implementation without mandatory mockups. Resolve this
+   once on fresh setup even after Use recommended settings, unless already answered.
+   Save the boolean as \`mockupsBeforeCoding\` through \`empirical_init\` or
+   \`empirical_configure\` (private CLI: \`--mockups on/off\`). Show Yes/No in
+   Confirm. Keep an existing value, including No, on repeat setup and unrelated
+   configuration; revisit only on Customize/Edit or an explicit change request.
+   Older configurations without the field retain Yes. This applies to UI-feature
+   mockups, not terminal/backend work; browser/screenshot verification remains
+   independent. Previously approved mockups still require fidelity verification.
+   For question detail in Preferences, offer
    \`concise\` questions (recommended for new setup) or \`detailed\` questions;
    concise means ask only a question whose answer changes scope, architecture,
    authorization, or a safety gate. When tracker setup is unconfigured, Tracker
    MUST present \`Track work by type\` as the recommended default and
-   \`No tracking\` as the explicit alternative. Applying recommended
+   \`No tracking\` as the explicit alternative. Using recommended
    settings or customizing MUST NOT bypass that choice. On repair with an
    explicitly disabled or configured tracker, Preserve current tracker is the
    default and MUST make no provider request. On Customize, visit Preferences,
@@ -26054,6 +26146,7 @@ These are presentation stages, not feature workflow phases or new durable state.
 3. \`Track work by type\` selects Linear, GitHub Projects, or Jira and starts with
    OAuth. First check for callable authenticated Linear MCP tools and prefer
    the sibling MCP bridge when available, including during legacy policy repair.
+   Follow the shared host-discovery procedure below before any unavailable claim.
    Preserve target, states, ticket rules, visibility and enforcement; remove
    credentialEnv only in the previewed Policy v2 MCP migration. The installed \`empirical mcp\` server supplies an in-memory client for
    Linear's official remote MCP OAuth endpoint when no embedding resolver is
@@ -26076,20 +26169,21 @@ These are presentation stages, not feature workflow phases or new durable state.
    Codex, verify that \`linear\` is enabled with OAuth, and resume tracker setup.
    Explain that this enables direct Linear MCP tools but does not authorize
    Empirical tracker mirroring. Do not read or reuse Codex's private OAuth
-   credential store. Whenever callable \`linear.list_teams\`, \`linear.list_projects\`,
-   \`linear.list_issue_statuses\`, \`linear.list_issues\`, \`linear.get_issue\`,
-   \`linear.save_issue\`, \`linear.list_comments\`, and \`linear.save_comment\`
-   tools are available, use real Linear MCP-backed tracking: collect a bounded
-   catalog, call \`empirical_tracker_linear_mcp_discover\`, preview and save a
+   credential store. Resolve the actual callable names for the read capabilities
+   using the shared host-discovery procedure. Collect a bounded catalog, call
+   \`empirical_tracker_linear_mcp_discover\`, preview and save a
    Linear Policy v2 with \`connection: "linear-mcp"\` and no \`credentialEnv\`,
    then call \`empirical_tracker_linear_mcp_prepare\`. Execute only the exact
-   returned \`linear.*\` tool and arguments, exhaust bounded pagination when
+   returned \`linear.*\` operation through its discovered host tool and compatible
+   arguments, exhaust bounded pagination when
    the result shape requires \`complete: true\`, normalize only its documented safe
    IDs/keys/URLs/names/state/comment fields, submit them with
    \`empirical_tracker_linear_mcp_accept\`, and repeat prepare/tool/accept until
    tracker health is \`synced\`. Never claim that login alone synchronized
-   Empirical. If those Linear tools are unavailable, present the secure
-   alternative and say exactly
+   Empirical. A discovery or tool-exposure failure alone does not authorize
+   credential fallback. Only after the shared discovery/recovery checks and the
+   user explicitly chooses host-file credentials, present the secure alternative
+   and say exactly
    \`Never paste credentials into chat\`, show the expanded
    host-only file path (\`\${XDG_CONFIG_HOME:-$HOME/.config}/empirical/secrets.env\`
    on POSIX or \`%APPDATA%\\Empirical\\secrets.env\` on Windows), and name only
@@ -26134,7 +26228,9 @@ These are presentation stages, not feature workflow phases or new durable state.
    or archive, and do not create or select feature workflow state.
 
 Never scan other repositories, overwrite unmanaged files, follow unsafe paths,
-or claim automatic activation for a repository without valid completed config.`;
+or claim automatic activation for a repository without valid completed config.
+
+${LINEAR_MCP_DISCOVERY_GUIDANCE}`;
 var LOCAL_AUTOMATIC_SKILL_BODY = `# Empirical
 
 Automatically route, track, resume, and complete Empirical work in this
@@ -26202,7 +26298,8 @@ the user does not need to mention Empirical or choose a profile.
    require an exact choice; Empirical never guesses.
    After each local workflow mutation is durably committed, inspect the tracker
    policy. Before a Linear credential operation, check authenticated sibling
-   Linear MCP tools. Prefer that connection even when a legacy API-key policy
+   Linear MCP tools using the shared host-discovery procedure below. Prefer
+   that connection even when a legacy API-key policy
    exists: call the MCP prepare operation to obtain its migration candidate,
    discover and preview through MCP, then configure the candidate preserving
    target, states, ticket rules and enforcement. Policy v1 maps to manual
@@ -26211,7 +26308,8 @@ the user does not need to mention Empirical or choose a profile.
    empirical_integrations; package upgrades alone do not rewrite repository files.
    For Linear Policy v2 with \`connection: "linear-mcp"\`, call
    \`empirical_tracker_linear_mcp_prepare\` with the exact feature id, execute
-   only its returned \`linear.*\` tool/arguments, submit the bounded normalized
+   only its returned \`linear.*\` operation via the discovered equivalent host
+   tool/schema, submit the bounded normalized
    result through \`empirical_tracker_linear_mcp_accept\`, and repeat until
    synced. For issue results, copy attachment URLs from Linear get_issue into
    attachmentUrls. For reconciliation, paginate the entire bounded team/project
@@ -26230,7 +26328,8 @@ the user does not need to mention Empirical or choose a profile.
    Tracker operations are granular MCP tools, not additional skills or user
    commands. OAuth authorization is out-of-band through negotiated URL mode.
    Raw credentials are never chat text or tool arguments/results. If OAuth is
-   unavailable and authenticated Linear MCP access has been checked, tell the human \`Never paste credentials into chat\` and pause
+   unavailable, host discovery/recovery has been checked, and the user explicitly
+   chooses host-file credentials, tell the human \`Never paste credentials into chat\` and pause
    for direct host-file configuration at
    \`\${XDG_CONFIG_HOME:-$HOME/.config}/empirical/secrets.env\` on POSIX or
    \`%APPDATA%\\Empirical\\secrets.env\` on Windows.
@@ -26258,7 +26357,10 @@ the user does not need to mention Empirical or choose a profile.
    isolated boundary on that exact remote base/head diff; request changes keep
    the PR draft and a new head requires a new packet. Report the exact highest
    completion level. Stop only at Done, Blocked, or Awaiting Human.
-9. When a phase asks for a mockup, build the directions it names, then run
+9. The saved \`mockupsBeforeCoding\` preference controls new required UI mockups.
+   Honor No without asking again; change it only on an explicit user request via
+   \`empirical_configure\`. Existing approved designs retain fidelity checks.
+   When a phase asks for a mockup, build the directions it names, then run
    \`empirical mockups\` and give the user the address it prints. That command is
    public on purpose: a person clicks through and chooses. Record their choice,
    and anything the mockup revealed that the criteria do not cover, before the
@@ -26268,7 +26370,9 @@ the user does not need to mention Empirical or choose a profile.
    another runtime requires explicit approval of its exact target, cwd, and argv.
 
 Do not invent state, weaken acceptance criteria, expose credentials, or persist
-private chain-of-thought. Files under .empirical/ are the durable source of truth.`;
+private chain-of-thought. Files under .empirical/ are the durable source of truth.
+
+${LINEAR_MCP_DISCOVERY_GUIDANCE}`;
 function skillContent(name, description, body, explicitOnly = false) {
   const invocationMetadata = explicitOnly ? `disable-model-invocation: true
 ` : "";
@@ -42762,6 +42866,8 @@ async function evaluateMockupGate(input) {
   if (input.phase === MOCKUP_GATE_PHASE) {
     if (!interfaceSurface)
       return empty(false);
+    if (input.mockupsBeforeCoding === false)
+      return empty(true);
     const path = mockupApprovalPath(input.feature);
     const entry = featureMockupEntryPath(input.feature);
     const requiredPaths = [entry, path];
@@ -45742,7 +45848,7 @@ class EmpiricalProject {
   static async initialize(root = process.cwd(), options = {}) {
     const absoluteRoot = resolve16(root);
     const trackerChange = options.tracker ? parseTrackerSetupChange(options.tracker) : undefined;
-    if (trackerChange?.mode === "apply") {
+    if (trackerChange?.mode === "apply" && !isLinearMcpPolicy(trackerChange.policy)) {
       await previewTrackerPolicy(trackerChange.policy, withTrackerRepositoryRoot2(options.trackerDependencies ?? {}, absoluteRoot));
     }
     await mkdir9(absoluteRoot, { recursive: true });
@@ -45936,6 +46042,7 @@ class EmpiricalProject {
     const current = await this.store.loadConfig();
     const configured = await this.store.configure({
       ...current,
+      mockupsBeforeCoding: input.mockupsBeforeCoding === undefined ? current.mockupsBeforeCoding : input.mockupsBeforeCoding,
       evidence: { ...current.evidence, ...input.evidence },
       isolation: { ...current.isolation, ...input.isolation },
       decisions: { ...current.decisions, ...input.decisions },
@@ -47853,6 +47960,7 @@ class EmpiricalProject {
       feature,
       phase: state.phase,
       criteria,
+      mockupsBeforeCoding: (await store.loadConfig()).mockupsBeforeCoding,
       read: async (path) => {
         try {
           const absolute = join20(store.root, path);
@@ -47940,6 +48048,7 @@ function defaultConfig(profile, legacySource, options = {}) {
     schemaVersion: SCHEMA_VERSION,
     profile,
     maxRepairAttempts: 2,
+    mockupsBeforeCoding: options.mockupsBeforeCoding === undefined ? true : options.mockupsBeforeCoding,
     evidence: {
       required: options.evidence?.required ?? true,
       browserForUi: options.evidence?.browserForUi ?? true,
@@ -47972,9 +48081,10 @@ function initializationConfiguration(options) {
   const decisions = options.decisions && Object.keys(options.decisions).length > 0 ? options.decisions : undefined;
   const interaction = options.interaction && Object.keys(options.interaction).length > 0 ? options.interaction : undefined;
   const review = options.review && Object.keys(options.review).length > 0 ? options.review : undefined;
-  if (!evidence && !isolation && !decisions && !interaction && !review && options.setupComplete === undefined)
+  if (!evidence && !isolation && !decisions && !interaction && !review && options.setupComplete === undefined && options.mockupsBeforeCoding === undefined)
     return null;
   return {
+    ...options.mockupsBeforeCoding !== undefined ? { mockupsBeforeCoding: options.mockupsBeforeCoding } : {},
     ...evidence ? { evidence } : {},
     ...isolation ? { isolation } : {},
     ...decisions ? { decisions } : {},
@@ -51255,6 +51365,7 @@ var reviewSubmissionSchema = exports_external.object({
   reviewerInvocationId: exports_external.string().min(1).max(200)
 }).strict();
 var configurationSchema = {
+  mockupsBeforeCoding: exports_external.boolean().optional(),
   evidenceRequired: exports_external.boolean().optional(),
   browserForUi: exports_external.boolean().optional(),
   screenshotForUi: exports_external.boolean().optional(),
@@ -51361,7 +51472,7 @@ function createMcpServer(defaultRoot = mcpDefaultRoot(), options = {}) {
     description: operationSummary("init"),
     inputSchema: { root: exports_external.string().optional(), profile: profileSchema.optional(), tracker: trackerSetupSchema.optional(), ...configurationSchema },
     annotations: operationAnnotations("init")
-  }, async ({ root, profile, tracker, evidenceRequired, browserForUi, screenshotForUi, codeReview, reviewMode, reviewerTokenEnv, isolation, base, worktreePath, branchPattern, decisions, questions }) => toolResult(async () => {
+  }, async ({ root, profile, tracker, evidenceRequired, browserForUi, screenshotForUi, codeReview, reviewMode, reviewerTokenEnv, isolation, base, worktreePath, branchPattern, decisions, questions, mockupsBeforeCoding }) => toolResult(async () => {
     const initialized = await EmpiricalProject.initialize(root ?? defaultRoot, {
       ...profile ? { profile } : {},
       evidence: {
@@ -51376,6 +51487,7 @@ function createMcpServer(defaultRoot = mcpDefaultRoot(), options = {}) {
         ...worktreePath ? { worktreePath } : {},
         ...branchPattern ? { branchPattern } : {}
       },
+      ...mockupsBeforeCoding !== undefined ? { mockupsBeforeCoding } : {},
       decisions: { ...decisions ? { complexRecords: decisions } : {} },
       interaction: { ...questions ? { questions } : {} },
       review: {
@@ -51417,7 +51529,7 @@ function createMcpServer(defaultRoot = mcpDefaultRoot(), options = {}) {
     description: operationSummary("configure"),
     inputSchema: { root: exports_external.string().optional(), policy: exports_external.unknown().optional(), tracker: trackerSetupSchema.optional(), ...configurationSchema },
     annotations: operationAnnotations("configure")
-  }, async ({ root, policy, tracker, evidenceRequired, browserForUi, screenshotForUi, codeReview, reviewMode, reviewerTokenEnv, isolation, base, worktreePath, branchPattern, decisions, questions }) => toolResult(async () => {
+  }, async ({ root, policy, tracker, evidenceRequired, browserForUi, screenshotForUi, codeReview, reviewMode, reviewerTokenEnv, isolation, base, worktreePath, branchPattern, decisions, questions, mockupsBeforeCoding }) => toolResult(async () => {
     const project = await EmpiricalProject.open(root ?? defaultRoot, { selection: "selected" });
     const configurationSupplied = [
       evidenceRequired,
@@ -51431,7 +51543,8 @@ function createMcpServer(defaultRoot = mcpDefaultRoot(), options = {}) {
       worktreePath,
       branchPattern,
       decisions,
-      questions
+      questions,
+      mockupsBeforeCoding
     ].some((value) => value !== undefined);
     if (policy !== undefined && (tracker !== undefined || configurationSupplied)) {
       throw new EmpiricalError("INVALID_CONFIG", "Configure project policy, project settings, and tracker setup in separate exact requests");
@@ -51453,6 +51566,7 @@ function createMcpServer(defaultRoot = mcpDefaultRoot(), options = {}) {
         ...worktreePath ? { worktreePath } : {},
         ...branchPattern ? { branchPattern } : {}
       },
+      ...mockupsBeforeCoding !== undefined ? { mockupsBeforeCoding } : {},
       decisions: { ...decisions ? { complexRecords: decisions } : {} },
       interaction: { ...questions ? { questions } : {} },
       review: {
@@ -52651,6 +52765,7 @@ function characterWidth(character) {
 // src/setup.ts
 function recommendedSetupSettings() {
   return {
+    mockupsBeforeCoding: true,
     evidence: {
       required: true,
       browserForUi: true,
@@ -52673,6 +52788,7 @@ function recommendedSetupSettings() {
 }
 function setupSettingsFromConfig(config2) {
   return {
+    mockupsBeforeCoding: config2.mockupsBeforeCoding,
     evidence: { ...config2.evidence },
     isolation: { ...config2.isolation },
     decisions: { ...config2.decisions },
@@ -52682,6 +52798,7 @@ function setupSettingsFromConfig(config2) {
 }
 function setupConfigurationInput(settings) {
   return {
+    mockupsBeforeCoding: settings.mockupsBeforeCoding,
     evidence: { ...settings.evidence },
     isolation: { ...settings.isolation },
     decisions: { ...settings.decisions },
@@ -52691,6 +52808,9 @@ function setupConfigurationInput(settings) {
   };
 }
 function validateSetupSettings(settings) {
+  if (typeof settings.mockupsBeforeCoding !== "boolean") {
+    throw new EmpiricalError("INVALID_CONFIG", "mockupsBeforeCoding must be a boolean");
+  }
   if (settings.isolation.mode !== "ask" && settings.isolation.mode !== "off") {
     throw new EmpiricalError("INVALID_CONFIG", "Isolation must be ask or off");
   }
@@ -52736,6 +52856,7 @@ function renderSetupSummary(settings, options = { current: false }) {
       "Questions: concise · only material blockers",
       `Verification: ${verification}`,
       `Worktrees: ${settings.isolation.mode} · base ${base} · ${settings.isolation.branchPattern}`,
+      `Mockups before coding: ${settings.mockupsBeforeCoding ? "Yes (UI changes)" : "No"}`,
       `Decisions: ${settings.decisions.complexRecords}`,
       `Review: ${settings.review.mode} · ${settings.review.mode === "bot" ? `credential name ${settings.review.reviewerTokenEnv}` : "fallback · no second credential"} · ${state}`,
       reviewSetupGuidance(settings.review),
@@ -52763,6 +52884,8 @@ function renderSetupSummary(settings, options = { current: false }) {
     `│    Path: ${settings.isolation.worktreePath}`,
     `│    Branch: ${settings.isolation.branchPattern}`,
     "│",
+    `│  Mockups before coding: ${settings.mockupsBeforeCoding ? "Yes — approve UI mockups before coding" : "No — skip required mockups"}`,
+    "│",
     "│  Decisions",
     `│  ${marker2(settings.decisions.complexRecords === "required")} ${settings.decisions.complexRecords === "required" ? "Require reviewable decision records for Complex work" : "Do not require Complex decision records"}`,
     "│",
@@ -53615,6 +53738,9 @@ ${renderSetupSummary(settings, {
     const firstChoice = await askEnumDefault(prompt, `Choice [${primary}]: `, primary, new Set([primary, current ? "k" : "a", "customize", "c", "tracker", "t", "cancel", "x", "q"]));
     if (["cancel", "x", "q"].includes(firstChoice))
       throw setupCancelled();
+    if (!current && !["customize", "c"].includes(firstChoice)) {
+      settings.mockupsBeforeCoding = await askMockupPreference(prompt, settings.mockupsBeforeCoding);
+    }
     if (firstChoice === primary || firstChoice === (current ? "k" : "a")) {
       if (currentTrackerSetup.mode !== "unconfigured") {
         return { configuration: setupConfigurationInput(settings), tracker: { mode: "preserve" } };
@@ -53929,6 +54055,7 @@ async function customizeSetup(prompt, current) {
   } else {
     console.log("Worktree base and templates are inactive and will keep their stored values.");
   }
+  const mockupsBeforeCoding = await askMockupPreference(prompt, current.mockupsBeforeCoding);
   console.log(`
 ◆ Decisions`);
   const complexRecords = await askEnumDefault(prompt, `Complex decision records [${current.decisions.complexRecords}] (required/off): `, current.decisions.complexRecords, new Set(["required", "off"]));
@@ -53938,11 +54065,15 @@ async function customizeSetup(prompt, current) {
   return {
     evidence: { required: required2, browserForUi, screenshotForUi, codeReview },
     isolation: { mode, baseBranch, worktreePath, branchPattern },
+    mockupsBeforeCoding,
     decisions: { complexRecords },
     interaction: { questions },
     review: { mode: reviewMode, reviewerTokenEnv }
   };
 }
+async function askMockupPreference(prompt, current) {
+  return await askEnumDefault(prompt, `Create mockups before coding? [${current ? "yes" : "no"}] (yes/no, UI changes): `, current ? "yes" : "no", new Set(["yes", "no"])) === "yes";
+}
 async function askOnOff(prompt, label, current) {
   const fallback = current ? "on" : "off";
   return await askEnumDefault(prompt, `${label} [${fallback}] (on/off): `, fallback, new Set(["on", "off"])) === "on";
@@ -54318,6 +54449,7 @@ function parseGlobals(argv) {
   return { args, root, json: json2 };
 }
 function readConfigurationFlags(args) {
+  const mockupsBeforeCoding = takeOnOffOption(args, "--mockups");
   const evidenceRequired = takeOnOffOption(args, "--evidence");
   const browserForUi = takeOnOffOption(args, "--ui-browser");
   const screenshotForUi = takeOnOffOption(args, "--ui-screenshot");
@@ -54349,10 +54481,11 @@ function readConfigurationFlags(args) {
   const questions = takeOption(args, "--questions");
   if (questions && questions !== "concise" && questions !== "detailed")
     throw new EmpiricalError("INVALID_CONFIG", "--questions must be concise or detailed");
-  const explicit = [evidenceRequired, browserForUi, screenshotForUi, codeReview].some((value) => value !== undefined) || Boolean(reviewMode || reviewerTokenEnv || mode || baseBranch || worktreePath || branchPattern || complexRecords || questions);
+  const explicit = [mockupsBeforeCoding, evidenceRequired, browserForUi, screenshotForUi, codeReview].some((value) => value !== undefined) || Boolean(reviewMode || reviewerTokenEnv || mode || baseBranch || worktreePath || branchPattern || complexRecords || questions);
   return {
     explicit,
     input: {
+      ...mockupsBeforeCoding !== undefined ? { mockupsBeforeCoding } : {},
       ...evidenceRequired !== undefined || browserForUi !== undefined || screenshotForUi !== undefined || codeReview !== undefined ? { evidence: {
         ...evidenceRequired !== undefined ? { required: evidenceRequired } : {},
         ...browserForUi !== undefined ? { browserForUi } : {},