From 43d4cb67fc0b3a2ffe7bf4f28723e350f3bbc1b0 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:00:04 +0200
Subject: [PATCH 1/8] feat(adopt): add AdoptValuesGate confirm-or-override
 component (#104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adopt collects values before classification (the planner renders the
shard's .njk against them), but its user already has a populated vault —
the full step-by-step InstallWizard reads as a fresh-install flow
shoehorned onto a retrofit.

AdoptValuesGate opens on a single page that surfaces the exact values
that will drive classification (resolved defaults, computed defaults,
--values prefill) each labelled with provenance, plus the module default,
and offers Use these values / Override individually / Cancel. "Override"
reuses InstallWizard verbatim rather than forking its value-iteration /
computed-preview / module-review logic. Required values with no default
and no prefill open straight into the wizard (no confident set to
confirm) — the predicate feeds missingValueKeys the *merged* map, exactly
as the --yes path does, so all-defaults shards land on the confirm page.

formatValue is exported from InstallWizard for reuse. The --yes/--values
non-interactive paths never reach this component, so they are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/components/AdoptValuesGate.tsx    | 170 ++++++++++++++++++
 source/components/InstallWizard.tsx      |   2 +-
 tests/component/AdoptValuesGate.test.tsx | 214 +++++++++++++++++++++++
 3 files changed, 385 insertions(+), 1 deletion(-)
 create mode 100644 source/components/AdoptValuesGate.tsx
 create mode 100644 tests/component/AdoptValuesGate.test.tsx

diff --git a/source/components/AdoptValuesGate.tsx b/source/components/AdoptValuesGate.tsx
new file mode 100644
index 0000000..24528d2
--- /dev/null
+++ b/source/components/AdoptValuesGate.tsx
@@ -0,0 +1,170 @@
+import { useState, useMemo, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { Select } from './ui.js';
+import type { ShardManifest, ShardSchema } from '../runtime/types.js';
+import Header from './Header.js';
+import InstallWizard, { type WizardResult, formatValue } from './InstallWizard.js';
+import {
+  mergePrefill,
+  missingValueKeys,
+  resolveComputedDefaults,
+  defaultModuleSelections,
+} from '../core/install-planner.js';
+import { isComputedDefault } from '../core/schema.js';
+
+/**
+ * Adopt's value-collection gate (#104).
+ *
+ * Install interrogates a clean target step-by-step; adopt's user already
+ * *has* a populated vault, so opening with the full `InstallWizard` reads
+ * as a fresh-install flow shoehorned onto a retrofit. Instead, adopt opens
+ * on a single page that surfaces the exact values that will drive
+ * classification (`adopt-planner.ts::classifyAdoption` renders the shard's
+ * `.njk` against them) — resolved defaults, computed defaults, and any
+ * `--values` prefill, each labelled with its provenance — and lets the user
+ * accept them in one keystroke or drop into the wizard to edit.
+ *
+ * "Override individually" reuses `InstallWizard` verbatim rather than
+ * forking the value-iteration / computed-preview / module-review logic.
+ *
+ * The `--yes` / `--values` non-interactive paths never reach this component
+ * (the machine resolves values directly), so they are unchanged.
+ */
+interface AdoptValuesGateProps {
+  manifest: ShardManifest;
+  schema: ShardSchema;
+  /** Raw `--values` prefill (pre-merge), used for provenance + override seed. */
+  prefillValues: Record<string, unknown>;
+  onComplete: (result: WizardResult) => void;
+  onCancel: () => void;
+  onError: (err: Error) => void;
+}
+
+type Provenance = 'from --values' | 'computed' | 'default';
+
+export default function AdoptValuesGate({
+  manifest,
+  schema,
+  prefillValues,
+  onComplete,
+  onCancel,
+  onError,
+}: AdoptValuesGateProps) {
+  const merged = useMemo(
+    () => mergePrefill(schema, prefillValues),
+    [schema, prefillValues],
+  );
+
+  // Required values with no default and not supplied via `--values`: there
+  // is no confident "use these" set to confirm, so fall straight through to
+  // the per-value wizard (adopt's pre-#104 behaviour for this shard shape).
+  // `missingValueKeys` is fed the *merged* map (literal defaults filled),
+  // exactly as the `--yes` path does (`use-adopt-machine.ts::runNonInteractive`)
+  // — feeding it the raw prefill would flag every default-bearing key as
+  // "missing" and wrongly force override for the common all-defaults shard.
+  const hasMissingRequired = useMemo(
+    () => missingValueKeys(schema, merged).length > 0,
+    [schema, merged],
+  );
+
+  const [mode, setMode] = useState<'confirm' | 'override'>(
+    hasMissingRequired ? 'override' : 'confirm',
+  );
+  const [resolved, setResolved] = useState<Record<string, unknown>>(merged);
+
+  // Resolve computed defaults once, before the confirm page reads them.
+  // Done in an effect (not render) to keep onError off the render path and
+  // dodge React 18 strict-mode double-fire — same pattern as InstallWizard.
+  useEffect(() => {
+    if (hasMissingRequired) return;
+    try {
+      setResolved(resolveComputedDefaults(schema, merged));
+    } catch (err) {
+      onError(err as Error);
+    }
+    // Mount-only — schema/prefill are stable within a gate session.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  if (mode === 'override') {
+    return (
+      <InstallWizard
+        manifest={manifest}
+        schema={schema}
+        prefillValues={prefillValues}
+        // Adopt has no "X files would be installed" guess at this point —
+        // the planner needs values first. Zero counts keep ModuleReview
+        // rendering cleanly; the Summary shows real bucket counts at the end.
+        moduleFileCounts={Object.fromEntries(
+          Object.keys(schema.modules).map((id) => [id, 0]),
+        )}
+        alwaysIncludedFileCount={0}
+        onComplete={onComplete}
+        onCancel={onCancel}
+        onError={onError}
+      />
+    );
+  }
+
+  const moduleCount = Object.keys(schema.modules).length;
+  const valueKeys = Object.keys(schema.values);
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Header manifest={manifest} />
+
+      <Text>These values will be used to compare the shard against your vault:</Text>
+
+      <Box flexDirection="column">
+        {valueKeys.length === 0 ? (
+          <Text dimColor>  (this shard declares no values)</Text>
+        ) : (
+          valueKeys.map((key) => (
+            <Text key={key}>
+              <Text>  {key}: </Text>
+              <Text color="cyan">{formatValue(resolved[key])}</Text>
+              <Text dimColor>  ({provenanceOf(key, schema, prefillValues)})</Text>
+            </Text>
+          ))
+        )}
+      </Box>
+
+      <Text dimColor>
+        Modules: all {moduleCount} included (override to customize)
+      </Text>
+
+      <Select
+        options={[
+          { label: 'Use these values', value: 'use' },
+          { label: 'Override individually', value: 'override' },
+          { label: 'Cancel', value: 'cancel' },
+        ]}
+        onChange={(v) => {
+          if (v === 'use') {
+            onComplete({
+              values: resolved,
+              selections: defaultModuleSelections(schema),
+            });
+          } else if (v === 'override') {
+            setMode('override');
+          } else {
+            onCancel();
+          }
+        }}
+      />
+    </Box>
+  );
+}
+
+function provenanceOf(
+  key: string,
+  schema: ShardSchema,
+  prefillValues: Record<string, unknown>,
+): Provenance {
+  if (Object.prototype.hasOwnProperty.call(prefillValues, key)) return 'from --values';
+  const def = schema.values[key];
+  if (def && def.default !== undefined && isComputedDefault(def.default)) {
+    return 'computed';
+  }
+  return 'default';
+}
diff --git a/source/components/InstallWizard.tsx b/source/components/InstallWizard.tsx
index e49b9e3..0e1a258 100644
--- a/source/components/InstallWizard.tsx
+++ b/source/components/InstallWizard.tsx
@@ -345,7 +345,7 @@ function ConfirmStep({
   );
 }
 
-function formatValue(value: unknown): string {
+export function formatValue(value: unknown): string {
   if (value === undefined) return '(unset)';
   if (value === null) return 'null';
   if (typeof value === 'boolean') return value ? 'true' : 'false';
diff --git a/tests/component/AdoptValuesGate.test.tsx b/tests/component/AdoptValuesGate.test.tsx
new file mode 100644
index 0000000..9b8c486
--- /dev/null
+++ b/tests/component/AdoptValuesGate.test.tsx
@@ -0,0 +1,214 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from 'ink-testing-library';
+import React from 'react';
+import AdoptValuesGate from '../../source/components/AdoptValuesGate.js';
+import type { ShardManifest, ShardSchema } from '../../source/runtime/types.js';
+import { ENTER, ARROW_DOWN, tick, waitFor, waitForCall } from './helpers.js';
+
+afterEach(() => {
+  cleanup();
+});
+
+const manifest: ShardManifest = {
+  apiVersion: 'v1',
+  name: 'mini',
+  namespace: 'breferrari',
+  version: '0.1.0',
+  dependencies: [],
+  hooks: {},
+};
+
+/** All-defaults schema → the gate opens on the confirm page. */
+const confirmSchema: ShardSchema = {
+  schema_version: 1,
+  values: {
+    user_name: { type: 'string', message: 'Your name', default: 'Ada', group: 'g' },
+    vault_purpose: {
+      type: 'string',
+      message: 'Purpose',
+      default: 'engineering',
+      group: 'g',
+    },
+    auto_tag: {
+      type: 'string',
+      message: 'Auto tag',
+      default: '{{ "autogen" }}',
+      group: 'g',
+    },
+  },
+  groups: [{ id: 'g', label: 'Setup' }],
+  modules: {
+    core: { label: 'Core', paths: ['core/'], removable: false },
+    extras: { label: 'Extras', paths: ['extras/'], removable: true },
+  },
+  signals: [],
+  frontmatter: {},
+  migrations: [],
+};
+
+async function mount(node: React.ReactElement) {
+  const r = render(node);
+  await tick(40);
+  return r;
+}
+
+describe('AdoptValuesGate', () => {
+  it('confirm page lists each value with its provenance label', async () => {
+    const { lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={confirmSchema}
+        prefillValues={{ vault_purpose: 'research' }}
+        onComplete={vi.fn()}
+        onCancel={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('autogen'));
+    const frame = lastFrame() ?? '';
+    // Literal default.
+    expect(frame).toMatch(/user_name:\s+Ada\s+\(default\)/);
+    // Supplied via --values prefill.
+    expect(frame).toMatch(/vault_purpose:\s+research\s+\(from --values\)/);
+    // Computed default resolved to its rendered value.
+    expect(frame).toMatch(/auto_tag:\s+autogen\s+\(computed\)/);
+    // Module defaults surfaced too — no hidden defaults.
+    expect(frame).toMatch(/Modules: all 2 included/);
+  });
+
+  it('"Use these values" → onComplete with resolved values + all-default selections', async () => {
+    const onComplete = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={confirmSchema}
+        prefillValues={{}}
+        onComplete={onComplete}
+        onCancel={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    stdin.write(ENTER); // first option focused
+    await waitForCall(onComplete);
+    const result = onComplete.mock.calls[0]![0] as {
+      values: Record<string, unknown>;
+      selections: Record<string, string>;
+    };
+    expect(result.values['user_name']).toBe('Ada');
+    expect(result.values['auto_tag']).toBe('autogen'); // computed resolved
+    expect(result.selections).toEqual({ core: 'included', extras: 'included' });
+  });
+
+  it('"Override individually" → drops into the InstallWizard', async () => {
+    const { stdin, lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={confirmSchema}
+        prefillValues={{}}
+        onComplete={vi.fn()}
+        onCancel={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    stdin.write(ARROW_DOWN); // → "Override individually"
+    await tick(40);
+    stdin.write(ENTER);
+    // The wizard's header step announces the question count.
+    await waitFor(lastFrame, (f) => /questions? to answer/.test(f));
+    expect(lastFrame() ?? '').toMatch(/questions? to answer/);
+  });
+
+  it('"Cancel" → onCancel', async () => {
+    const onCancel = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={confirmSchema}
+        prefillValues={{}}
+        onComplete={vi.fn()}
+        onCancel={onCancel}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    stdin.write(ARROW_DOWN);
+    await tick(40);
+    stdin.write(ARROW_DOWN);
+    await tick(40);
+    stdin.write(ENTER); // → "Cancel"
+    await waitForCall(onCancel);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('required value with no default and no prefill → opens directly in override (no confirm page)', async () => {
+    const requiredSchema: ShardSchema = {
+      ...confirmSchema,
+      values: {
+        token: { type: 'string', required: true, message: 'API token', group: 'g' },
+      },
+    };
+    const { lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={requiredSchema}
+        prefillValues={{}}
+        onComplete={vi.fn()}
+        onCancel={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => /question to answer/.test(f));
+    // The confirm page's hallmark string must never have rendered.
+    expect(lastFrame() ?? '').not.toContain('Use these values');
+  });
+
+  it('computed default that fails to evaluate → onError, no crash', async () => {
+    const onError = vi.fn();
+    const badSchema: ShardSchema = {
+      ...confirmSchema,
+      values: {
+        // number-typed computed default that resolves to a non-number →
+        // resolveComputedDefaults throws COMPUTED_DEFAULT_INVALID.
+        count: { type: 'number', message: 'Count', default: '{{ "abc" }}', group: 'g' },
+      },
+    };
+    await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={badSchema}
+        prefillValues={{}}
+        onComplete={vi.fn()}
+        onCancel={vi.fn()}
+        onError={onError}
+      />,
+    );
+    await waitForCall(onError);
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect((onError.mock.calls[0]![0] as Error).message).toMatch(/computed default/i);
+  });
+
+  it('schema with zero values → confirm page still renders and confirms', async () => {
+    const onComplete = vi.fn();
+    const emptyValuesSchema: ShardSchema = {
+      ...confirmSchema,
+      values: {},
+    };
+    const { stdin, lastFrame } = await mount(
+      <AdoptValuesGate
+        manifest={manifest}
+        schema={emptyValuesSchema}
+        prefillValues={{}}
+        onComplete={onComplete}
+        onCancel={vi.fn()}
+        onError={vi.fn()}
+      />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('declares no values'));
+    stdin.write(ENTER);
+    await waitForCall(onComplete);
+    const result = onComplete.mock.calls[0]![0] as { values: Record<string, unknown> };
+    expect(result.values).toEqual({});
+  });
+});

From cfadfe77ecd9c6a7b4e4ab25248fb98cb6727419 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:03:32 +0200
Subject: [PATCH 2/8] feat(adopt): open on the values confirm-or-override gate
 (#104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Render AdoptValuesGate for the wizard phase instead of InstallWizard.
Adopt's user already has a populated vault, so a single confirm page
("here are the values that will drive classification: Use / Override /
Cancel") beats a fresh-install-style per-value interview. "Override
individually" still drops into the full InstallWizard.

The --yes/--values non-interactive paths never reached the wizard
component, so they are unchanged.

Test sweep (folded in to keep the commit self-consistent — the wire-up is
what changes the interactive flow):
- Layer 1 (adopt-flow): replace driveAdoptWizard with driveAdoptConfirm;
  scenarios 19/20/21 drive the gate; add 25 (Override → wizard → adopt)
  and 26 (values surfaced before classification).
- Layer 2 (adopt-diff PTY, macOS/Linux): drive the confirm gate instead
  of driveMinimalWizard before the diff loop. The shared driveMinimalWizard
  helper is untouched — install Layer 1/2 still use it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/commands/adopt.tsx                  |  21 ++---
 source/commands/hooks/use-adopt-machine.ts |   7 ++
 tests/component/flows/adopt-flow.test.tsx  | 101 ++++++++++++++++-----
 tests/e2e/tui/adopt-diff.test.ts           |  14 ++-
 4 files changed, 105 insertions(+), 38 deletions(-)

diff --git a/source/commands/adopt.tsx b/source/commands/adopt.tsx
index 4c75bd9..44db3fb 100644
--- a/source/commands/adopt.tsx
+++ b/source/commands/adopt.tsx
@@ -4,7 +4,7 @@ import zod from 'zod';
 import { ShardMindError, assertNever } from '../runtime/types.js';
 
 import { Spinner, StatusMessage, Alert } from '../components/ui.js';
-import InstallWizard from '../components/InstallWizard.js';
+import AdoptValuesGate from '../components/AdoptValuesGate.js';
 import AdoptDiffView from '../components/AdoptDiffView.js';
 import AdoptSummary from '../components/AdoptSummary.js';
 import CommandFrame from '../components/CommandFrame.js';
@@ -83,21 +83,16 @@ export default function Adopt({ args, options }: Props) {
     case 'wizard':
       return (
         <CommandFrame dryRun={dryRun} selfUpdateBanner={banner}>
-          <InstallWizard
+          {/* Adopt opens on a values confirm-or-override page (#104)
+              instead of the full install wizard: the user already has a
+              populated vault, so a single "here's what will drive
+              classification" page beats a fresh-install-style interview.
+              "Override individually" inside the gate drops into the
+              InstallWizard for per-value + module editing. */}
+          <AdoptValuesGate
             manifest={phase.ctx.manifest}
             schema={phase.ctx.schema}
             prefillValues={phase.ctx.prefillValues}
-            // Adopt's wizard reuses install's value-collection UI but
-            // shows file counts as zero — adopt has no clean
-            // "X files would be installed" guess at this point because
-            // the planner needs values first. We pass empty maps so the
-            // module-review step still renders cleanly without bogus
-            // counts; the Summary view shows the real bucket counts at
-            // the end.
-            moduleFileCounts={Object.fromEntries(
-              Object.keys(phase.ctx.schema.modules).map((id) => [id, 0]),
-            )}
-            alwaysIncludedFileCount={0}
             onComplete={onWizardComplete}
             onCancel={onWizardCancel}
             onError={onWizardError}
diff --git a/source/commands/hooks/use-adopt-machine.ts b/source/commands/hooks/use-adopt-machine.ts
index 7b87d1f..2a608b8 100644
--- a/source/commands/hooks/use-adopt-machine.ts
+++ b/source/commands/hooks/use-adopt-machine.ts
@@ -11,6 +11,13 @@
  *   diff-review (loop over `differs`) → executing →
  *   running-hook → summary
  *
+ * The `wizard` phase renders `AdoptValuesGate` (not `InstallWizard`
+ * directly): adopt opens on a values confirm-or-override page (#104) since
+ * the user already has a populated vault. The phase still means "collect
+ * values interactively", and the `onWizard*` callbacks are unchanged — the
+ * gate's "Override individually" path renders `InstallWizard` and returns
+ * the same `WizardResult`.
+ *
  * Reuses `useSigintRollback` and `appendHookOutput` from `shared.ts`, and
  * the hook orchestrator from `core`, so install / update / adopt can't
  * drift on any of those concerns.
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index de47303..c5db840 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -1,11 +1,14 @@
 /**
- * Layer 1 adopt command flow tests — scenarios 19-23 of [#111](https://github.com/breferrari/shardmind/issues/111) Phase 1.
+ * Layer 1 adopt command flow tests — scenarios 19-26 of [#111](https://github.com/breferrari/shardmind/issues/111) Phase 1.
  *
- * Adopt always fires the InstallWizard first (no shard-values.yaml
- * exists yet on the user side), then plans against the user's vault
- * to classify each shard path as `matches` / `differs` / `shard-only`.
- * Each `differs` file gets an AdoptDiffView prompt; iteration shape is
- * the same #109 surface as DiffView.
+ * Adopt opens on the `AdoptValuesGate` confirm-or-override page (#104):
+ * a single page surfacing the values that will drive classification,
+ * with Use these values / Override individually / Cancel. "Override"
+ * drops into the full InstallWizard. After values are settled, adopt
+ * plans against the user's vault to classify each shard path as
+ * `matches` / `differs` / `shard-only`. Each `differs` file gets an
+ * AdoptDiffView prompt; iteration shape is the same #109 surface as
+ * DiffView.
  */
 
 import { describe, it, expect, afterEach } from 'vitest';
@@ -32,7 +35,7 @@ import { createInstalledVault, type Vault } from '../../e2e/helpers/vault.js';
 
 const SLUG_VERSION_MISMATCH = 'acme/adopt-future-engine';
 
-describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)', () => {
+describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)', () => {
   const getCtx = setupFlowSuite({
     shards: {
       [SHARD_SLUG]: {
@@ -51,18 +54,17 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)',
   });
 
   /**
-   * Drive the standard 4-question wizard, then advance through modules
-   * + Confirm. Adopt's wizard has the same shape as install's but is
-   * followed by the planning + diff-review phases rather than directly
-   * by the install summary.
+   * Drive adopt's default `AdoptValuesGate` path (#104): wait for the
+   * confirm page, then ENTER on the focused "Use these values" option.
+   * The minimal-shard schema's four values all carry literal defaults,
+   * so the gate opens on the confirm page (not the override wizard) and
+   * a single keystroke settles values + all-default module selections.
+   * Adopt then moves to planning + diff-review.
    */
-  async function driveAdoptWizard(
+  async function driveAdoptConfirm(
     r: ReturnType<typeof mountAdopt>,
-    userName = 'Alice',
   ): Promise<void> {
-    await driveMinimalWizard(r, userName, 15_000);
-    r.stdin.write(ENTER); // module review default selections
-    await waitFor(r.lastFrame, (f) => f.includes('Ready to install'));
+    await waitFor(r.lastFrame, (f) => f.includes('Use these values'), 30_000);
     r.stdin.write(ENTER);
   }
 
@@ -77,7 +79,7 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)',
         shardRef: `${SHARD_REF}#v0.1.0`,
         vaultRoot: vault,
       });
-      await driveAdoptWizard(r);
+      await driveAdoptConfirm(r);
       // No differing files → planner goes straight to executing →
       // running-hook → summary. Capture the matched frame from
       // waitFor; reading r.lastFrame() afterwards races the 100 ms
@@ -117,13 +119,11 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)',
         '.claude/settings.json',
         '{ "user-only": true, "no": "match" }\n',
       );
-      // Wizard's prefill arg comes via --values; we'd rather drive
-      // through the wizard interactively to mirror real usage.
       const r = mountAdopt({
         shardRef: `${SHARD_REF}#v0.1.0`,
         vaultRoot: vault,
       });
-      await driveAdoptWizard(r);
+      await driveAdoptConfirm(r);
       // Walk three AdoptDiffView prompts via the shared iteration
       // helper. ENTER on default option = "Keep mine". The #109
       // regression would manifest as iteration 2 timing out on
@@ -151,7 +151,7 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)',
         shardRef: `${SHARD_REF}#v0.1.0`,
         vaultRoot: vault,
       });
-      await driveAdoptWizard(r);
+      await driveAdoptConfirm(r);
       await waitFor(r.lastFrame, (f) => /\(1 of 1\)/.test(f), 20_000);
       // ARROW_DOWN + ENTER → use_shard.
       r.stdin.write(ARROW_DOWN);
@@ -277,6 +277,65 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-23)',
       await cleanupVault(vault);
     }
   }, 45_000);
+
+  // ───── Scenario 25: confirm gate → Override individually → wizard → Summary (#104) ─────
+
+  it('25. "Override individually" drops into the wizard and still adopts', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s25-override');
+    try {
+      const r = mountAdopt({
+        shardRef: `${SHARD_REF}#v0.1.0`,
+        vaultRoot: vault,
+      });
+      // Confirm gate up first; select "Override individually" (option 2).
+      await waitFor(r.lastFrame, (f) => f.includes('Override individually'), 30_000);
+      r.stdin.write(ARROW_DOWN);
+      await tick(40);
+      r.stdin.write(ENTER);
+      // The full InstallWizard now drives — same 4-question shape install
+      // uses. Empty vault → all shard-only → Summary (no diff prompts).
+      await driveMinimalWizard(r, 'Override Tester', 15_000);
+      r.stdin.write(ENTER); // module review default selections
+      await waitFor(r.lastFrame, (f) => f.includes('Ready to install'));
+      r.stdin.write(ENTER); // confirm → planning
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => /Adopted shardmind\/minimal/.test(f),
+        30_000,
+      );
+      expect(frame).toMatch(/installed fresh/i);
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
+
+  // ───── Scenario 26: confirm page surfaces the values before classification (#104) ─────
+
+  it('26. confirm page surfaces the values that will drive classification', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s26-surfaced');
+    try {
+      const r = mountAdopt({
+        shardRef: `${SHARD_REF}#v0.1.0`,
+        vaultRoot: vault,
+      });
+      // The default vault_purpose ("engineering") must be visible on the
+      // confirm page *before* any classification/diff/summary frame — the
+      // #104 acceptance criterion that no defaults are hidden.
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => f.includes('Use these values'),
+        30_000,
+      );
+      expect(frame).toMatch(/vault_purpose:\s+engineering/);
+      expect(frame).toMatch(/Modules: all \d+ included/);
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 45_000);
 });
 
 async function writeRel(vault: string, rel: string, content: string): Promise<void> {
diff --git a/tests/e2e/tui/adopt-diff.test.ts b/tests/e2e/tui/adopt-diff.test.ts
index 152882f..6fbb41f 100644
--- a/tests/e2e/tui/adopt-diff.test.ts
+++ b/tests/e2e/tui/adopt-diff.test.ts
@@ -28,7 +28,6 @@ import {
   spawnCliPty,
   ENTER,
   PTY_VIEWPORT_ROWS,
-  driveMinimalWizard,
 } from './helpers/pty-cli.js';
 import { tick } from '../../component/helpers.js';
 
@@ -103,7 +102,7 @@ describe.skipIf(skipOnWindows)(
             '{ "user-only": true, "no": "match" }\n',
           );
 
-          // Pin to v0.1.0 via the SHA-routed ref path so the wizard
+          // Pin to v0.1.0 via the SHA-routed ref path so the gate
           // resolves quickly and the planner runs against a known
           // tarball.
           const handle = await spawnCliPty(['adopt', `${SHARD_REF}#v0.1.0`], {
@@ -112,8 +111,15 @@ describe.skipIf(skipOnWindows)(
             rows: PTY_VIEWPORT_ROWS,
           });
           try {
-            await driveMinimalWizard(handle);
-            handle.write(ENTER); // commit at confirm
+            // Adopt opens on the AdoptValuesGate confirm page (#104); the
+            // minimal shard's values all carry defaults, so ENTER on the
+            // focused "Use these values" settles values + all modules and
+            // moves straight to classification.
+            await handle.waitForScreen((s) => /Use these values/.test(s), {
+              timeoutMs: 30_000,
+              description: 'adopt values confirm page',
+            });
+            handle.write(ENTER);
 
             // Walk three sequential AdoptDiffView prompts. ENTER
             // alone selects "Keep mine" (first option). The #109

From 67d83885cac4f530e770df86b875ef5291baf849 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:05:36 +0200
Subject: [PATCH 3/8] docs(adopt): document the values confirm-or-override gate
 (#104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ARCHITECTURE §10.5: rewrite adopt step 2 (values gate, not full wizard);
  refresh the --yes/--values/--dry-run flag descriptions and the
  implementation-modules line with AdoptValuesGate.
- IMPLEMENTATION §3.5: adopt data-flow node now shows the confirm /
  override-into-wizard shape.
- CLAUDE.md: add AdoptValuesGate.tsx to the component source tree.
- CHANGELOG: [Unreleased] Changed entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md           | 12 ++++++++++++
 CLAUDE.md              |  1 +
 docs/ARCHITECTURE.md   | 10 +++++-----
 docs/IMPLEMENTATION.md |  2 +-
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d798e8..6e95c11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,18 @@ Closes [#121](https://github.com/breferrari/shardmind/issues/121). The guard tha
 
 - **Tests**: `tests/unit/manifest.test.ts` (range parse + reject incl. empty/whitespace → `MANIFEST_VALIDATION_FAILED` and deliberate `*`/`x` match-all; `assertEngineCompatible` matrix — satisfied / lower-bound / too-old / absent / unknown-version skip / prerelease-ahead / match-all) and Layer 1 flow tests refusing `>=99.0.0` before any write across all three commands: install (scenario 12, no `state.json`), update (scenario 18, `state.json` byte-unchanged), adopt (scenario 24, no `.shardmind/`). **Docs**: `docs/AUTHORING.md` (field reference + §6 note), `docs/ERRORS.md` (`SHARDMIND_VERSION_MISMATCH`), `schemas/shard.schema.json` (`requires.shardmind`).
 
+### Changed (adopt values confirm-or-override — #104)
+
+Closes [#104](https://github.com/breferrari/shardmind/issues/104). Adopt is for users who already have a populated vault, but it reused the full step-by-step install wizard to collect the values classification needs (the planner renders the shard's `.njk` against them before hashing). Being interrogated value-by-value reads as a fresh-install flow shoehorned onto a retrofit.
+
+- **`shardmind adopt` opens on a values confirm page** (`source/components/AdoptValuesGate.tsx`) instead of `InstallWizard`. It surfaces the exact values that will drive classification — resolved defaults, computed defaults, and any `--values` prefill, each labelled with its provenance (`default` / `computed` / `from --values`) — plus the module default, with **Use these values / Override individually / Cancel**. No more hidden defaults: the values are shown before classification runs.
+
+- **"Override individually" reuses `InstallWizard` verbatim** (per-value + module editing) rather than forking its value-iteration / computed-preview / module-review logic. A required value with no default and no prefill opens straight into the wizard (no confident set to confirm) — the predicate feeds `missingValueKeys` the *merged* map, exactly as the `--yes` path does, so the common all-defaults shard lands on the confirm page.
+
+- **`--yes` / `--values` unchanged.** Those non-interactive paths resolve values in the machine and never reach the gate, so adopt's scripted contract is byte-identical.
+
+- **Tests**: `tests/component/AdoptValuesGate.test.tsx` (provenance labels, Use → `onComplete` with resolved values + all-default selections, Override → wizard, Cancel, computed-resolve + computed-throw → `onError`, required-no-default → override, zero-values shard); Layer 1 adopt flow scenarios 19/20/21 re-driven through the confirm gate + new 25 (Override → wizard → adopt) and 26 (values surfaced before classification); Layer 2 PTY adopt scenario 20 drives the gate. **Docs**: `docs/ARCHITECTURE.md §10.5`, `docs/IMPLEMENTATION.md §3.5`, `CLAUDE.md` component tree.
+
 ### Added (multiselect value type — #101)
 
 Closes [#101](https://github.com/breferrari/shardmind/issues/101). Promotes `multiselect` from a partially-wired type (engine validation existed; the wizard rendered a comma-separated text fallback flagged in-code as v0.2 polish) to a first-class value type. Lets a shard author ask one checkbox question ("Which agents do you use?") instead of N booleans. Scope is the value type + widget; gating *which modules install* on a multiselect value remains [#80](https://github.com/breferrari/shardmind/issues/80) (v0.2).
diff --git a/CLAUDE.md b/CLAUDE.md
index dc7266d..42fb2cf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,6 +145,7 @@ shardmind/
 │   │   ├── CollisionReview.tsx        # Install: backup / overwrite / cancel
 │   │   ├── ExistingInstallGate.tsx    # Install: existing-install disambiguation
 │   │   ├── DiffView.tsx               # Three-way diff + conflict resolution
+│   │   ├── AdoptValuesGate.tsx        # Adopt: values confirm-or-override page (#104)
 │   │   ├── AdoptDiffView.tsx          # Adopt: 2-way diff (no merge base) + per-file prompt
 │   │   ├── AdoptSummary.tsx           # Final adopt report (matched / mine / shard / fresh)
 │   │   ├── NewValuesPrompt.tsx        # Update: prompt for newly required values
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b959116..1b419d5 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -872,7 +872,7 @@ Two pre-flight guards run before the network resolve, so a deterministically-wro
 Phase ordering (logical; UI may interleave loading messages — see IMPLEMENTATION §3.5 for the data-flow diagram):
 
 1. **Fetch** — resolve + download into a temp directory.
-2. **Wizard** — collect values + module selections via the same `InstallWizard` component install uses. Wizard runs **before** classification because `.njk` templates need values to render before their output bytes can be hashed.
+2. **Values gate** (`source/components/AdoptValuesGate.tsx`, #104) — adopt's user already has a populated vault, so it opens on a single confirm page that surfaces the values that will drive classification (resolved defaults, computed defaults, `--values` prefill, each labelled with its provenance) plus the module default, with **Use these values / Override individually / Cancel**. "Override individually" drops into the same `InstallWizard` install uses (per-value + module editing). Required values with no default and no prefill open straight into the wizard (no confident set to confirm). This step runs **before** classification because `.njk` templates need values to render before their output bytes can be hashed.
 3. **Classify** (`source/core/adopt-planner.ts::classifyAdoption`) — for every shard output, render or read, hash, stat the user's vault, and assign one of four buckets:
    - **matches** — byte-identical post-render → managed silently.
    - **differs** — bytes differ → 2-way diff prompt (`AdoptDiffView`); user picks `keep_mine` (record user's hash, ownership=`modified`) or `use_shard` (overwrite with shard bytes, ownership=`managed`).
@@ -883,16 +883,16 @@ Phase ordering (logical; UI may interleave loading messages — see IMPLEMENTATI
 6. **Re-hash** — recompute managed-file hashes per `state.ts::rehashManagedFiles` so any hook edits to managed paths land in the recorded state.
 
 Flags:
-- `--yes` — skip wizard + auto-pick `keep_mine` on every `differs`. Preserves the user's bytes on every divergence; safe default for retroactive adoption.
-- `--values <file>` — prefill wizard answers (same shape as `install --values`).
+- `--yes` — skip the values gate + auto-pick `keep_mine` on every `differs`. Preserves the user's bytes on every divergence; safe default for retroactive adoption.
+- `--values <file>` — prefill value answers (same shape as `install --values`); shown on the gate's confirm page as `(from --values)`.
 - `--verbose` — show per-file action history during the apply phase.
-- `--dry-run` — run the full pipeline (fetch, wizard, classify) without touching the vault. Summary reports what *would* happen.
+- `--dry-run` — run the full pipeline (fetch, values gate, classify) without touching the vault. Summary reports what *would* happen.
 
 Volatile templates (`{# shardmind: volatile #}`) skip the differs prompt entirely — their rendered output is expected to vary across renders, so a content prompt would be meaningless. User's bytes are accepted as-is; missing-on-disk falls through to shard-only.
 
 Excluded modules' files in the user's vault are not classified — adopt mirrors install's "module excluded → file not installed" rule, so user content at those paths stays user-content without any prompt.
 
-Implementation modules: `source/core/adopt-planner.ts` (IMPLEMENTATION §4.17), `source/core/adopt-executor.ts` (§4.18). Orchestration lives in `source/commands/hooks/use-adopt-machine.ts`; UI components are `source/components/AdoptDiffView.tsx` + `source/components/AdoptSummary.tsx`.
+Implementation modules: `source/core/adopt-planner.ts` (IMPLEMENTATION §4.17), `source/core/adopt-executor.ts` (§4.18). Orchestration lives in `source/commands/hooks/use-adopt-machine.ts`; UI components are `source/components/AdoptValuesGate.tsx` (values confirm-or-override), `source/components/AdoptDiffView.tsx` + `source/components/AdoptSummary.tsx`.
 
 ### 10.6 Install Location
 
diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md
index d98ac41..d151d1f 100644
--- a/docs/IMPLEMENTATION.md
+++ b/docs/IMPLEMENTATION.md
@@ -158,7 +158,7 @@ graph TD
     B["registry + download<br/>Resolve + extract to temp"] --> C
     C["manifest + schema<br/>Parse new shard.yaml, shard-schema.yaml"] --> D
 
-    D["InstallWizard — Ink TUI<br/>① Value prompts from schema.groups<br/>② Module review<br/>③ Confirm<br/>(runs BEFORE classification — .njk needs values to render)"] --> E
+    D["AdoptValuesGate — Ink TUI (#104)<br/>Confirm page: values + provenance + module default<br/>Use these values / Override individually / Cancel<br/>Override → InstallWizard (value + module editing)<br/>(runs BEFORE classification — .njk needs values to render)"] --> E
 
     E["adopt-planner.ts::classifyAdoption<br/>resolveModules walks shard, render or read each output<br/>per-output sha256 vs sha256(user vault path)<br/>→ matches | differs | shard-only buckets"] --> F1
 

From 5bb5b4c4c8921a1cb96fff5c5f9a0b9e34444d75 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:10:58 +0200
Subject: [PATCH 4/8] =?UTF-8?q?refactor(adopt):=20simplify=20pass=20?=
 =?UTF-8?q?=E2=80=94=20gateProps=20test=20helper,=20trim=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/simplify findings (reuse/efficiency/altitude agents found the source
clean; these are the two in-scope test-readability fixes):
- AdoptValuesGate.test.tsx: add a gateProps() default-props helper so each
  test spells out only the prop it asserts on, not all six.
- adopt-flow scenario 25: tighten two narrative comments to the decision-
  critical line.

No behavior change. Skipped (noted in PR): moving formatValue to a shared
format util and a hideFileCounts prop on InstallWizard — out-of-scope
follow-ups, not blockers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 tests/component/AdoptValuesGate.test.tsx  | 85 +++++++----------------
 tests/component/flows/adopt-flow.test.tsx |  6 +-
 2 files changed, 28 insertions(+), 63 deletions(-)

diff --git a/tests/component/AdoptValuesGate.test.tsx b/tests/component/AdoptValuesGate.test.tsx
index 9b8c486..e66697c 100644
--- a/tests/component/AdoptValuesGate.test.tsx
+++ b/tests/component/AdoptValuesGate.test.tsx
@@ -52,17 +52,28 @@ async function mount(node: React.ReactElement) {
   return r;
 }
 
+/**
+ * Default props with `vi.fn()` callbacks; each test overrides only what it
+ * exercises, so the assertion-relevant prop is the only one spelled out.
+ */
+function gateProps(
+  overrides: Partial<React.ComponentProps<typeof AdoptValuesGate>> = {},
+): React.ComponentProps<typeof AdoptValuesGate> {
+  return {
+    manifest,
+    schema: confirmSchema,
+    prefillValues: {},
+    onComplete: vi.fn(),
+    onCancel: vi.fn(),
+    onError: vi.fn(),
+    ...overrides,
+  };
+}
+
 describe('AdoptValuesGate', () => {
   it('confirm page lists each value with its provenance label', async () => {
     const { lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={confirmSchema}
-        prefillValues={{ vault_purpose: 'research' }}
-        onComplete={vi.fn()}
-        onCancel={vi.fn()}
-        onError={vi.fn()}
-      />,
+      <AdoptValuesGate {...gateProps({ prefillValues: { vault_purpose: 'research' } })} />,
     );
     await waitFor(lastFrame, (f) => f.includes('autogen'));
     const frame = lastFrame() ?? '';
@@ -79,14 +90,7 @@ describe('AdoptValuesGate', () => {
   it('"Use these values" → onComplete with resolved values + all-default selections', async () => {
     const onComplete = vi.fn();
     const { stdin, lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={confirmSchema}
-        prefillValues={{}}
-        onComplete={onComplete}
-        onCancel={vi.fn()}
-        onError={vi.fn()}
-      />,
+      <AdoptValuesGate {...gateProps({ onComplete })} />,
     );
     await waitFor(lastFrame, (f) => f.includes('Use these values'));
     stdin.write(ENTER); // first option focused
@@ -101,16 +105,7 @@ describe('AdoptValuesGate', () => {
   });
 
   it('"Override individually" → drops into the InstallWizard', async () => {
-    const { stdin, lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={confirmSchema}
-        prefillValues={{}}
-        onComplete={vi.fn()}
-        onCancel={vi.fn()}
-        onError={vi.fn()}
-      />,
-    );
+    const { stdin, lastFrame } = await mount(<AdoptValuesGate {...gateProps()} />);
     await waitFor(lastFrame, (f) => f.includes('Use these values'));
     stdin.write(ARROW_DOWN); // → "Override individually"
     await tick(40);
@@ -123,14 +118,7 @@ describe('AdoptValuesGate', () => {
   it('"Cancel" → onCancel', async () => {
     const onCancel = vi.fn();
     const { stdin, lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={confirmSchema}
-        prefillValues={{}}
-        onComplete={vi.fn()}
-        onCancel={onCancel}
-        onError={vi.fn()}
-      />,
+      <AdoptValuesGate {...gateProps({ onCancel })} />,
     );
     await waitFor(lastFrame, (f) => f.includes('Use these values'));
     stdin.write(ARROW_DOWN);
@@ -150,14 +138,7 @@ describe('AdoptValuesGate', () => {
       },
     };
     const { lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={requiredSchema}
-        prefillValues={{}}
-        onComplete={vi.fn()}
-        onCancel={vi.fn()}
-        onError={vi.fn()}
-      />,
+      <AdoptValuesGate {...gateProps({ schema: requiredSchema })} />,
     );
     await waitFor(lastFrame, (f) => /question to answer/.test(f));
     // The confirm page's hallmark string must never have rendered.
@@ -174,16 +155,7 @@ describe('AdoptValuesGate', () => {
         count: { type: 'number', message: 'Count', default: '{{ "abc" }}', group: 'g' },
       },
     };
-    await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={badSchema}
-        prefillValues={{}}
-        onComplete={vi.fn()}
-        onCancel={vi.fn()}
-        onError={onError}
-      />,
-    );
+    await mount(<AdoptValuesGate {...gateProps({ schema: badSchema, onError })} />);
     await waitForCall(onError);
     expect(onError).toHaveBeenCalledTimes(1);
     expect((onError.mock.calls[0]![0] as Error).message).toMatch(/computed default/i);
@@ -196,14 +168,7 @@ describe('AdoptValuesGate', () => {
       values: {},
     };
     const { stdin, lastFrame } = await mount(
-      <AdoptValuesGate
-        manifest={manifest}
-        schema={emptyValuesSchema}
-        prefillValues={{}}
-        onComplete={onComplete}
-        onCancel={vi.fn()}
-        onError={vi.fn()}
-      />,
+      <AdoptValuesGate {...gateProps({ schema: emptyValuesSchema, onComplete })} />,
     );
     await waitFor(lastFrame, (f) => f.includes('declares no values'));
     stdin.write(ENTER);
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index c5db840..ab1be7a 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -289,13 +289,13 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
         shardRef: `${SHARD_REF}#v0.1.0`,
         vaultRoot: vault,
       });
-      // Confirm gate up first; select "Override individually" (option 2).
+      // Confirm gate up first; select "Override individually" (option 2)
+      // to route into the full InstallWizard.
       await waitFor(r.lastFrame, (f) => f.includes('Override individually'), 30_000);
       r.stdin.write(ARROW_DOWN);
       await tick(40);
       r.stdin.write(ENTER);
-      // The full InstallWizard now drives — same 4-question shape install
-      // uses. Empty vault → all shard-only → Summary (no diff prompts).
+      // Empty vault → all shard-only → Summary (no diff prompts).
       await driveMinimalWizard(r, 'Override Tester', 15_000);
       r.stdin.write(ENTER); // module review default selections
       await waitFor(r.lastFrame, (f) => f.includes('Ready to install'));

From 18a27fbc11a1a3d917b6df0d2f713bbec1722330 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:20:20 +0200
Subject: [PATCH 5/8] =?UTF-8?q?fix(adopt):=20harden=20AdoptValuesGate=20?=
 =?UTF-8?q?=E2=80=94=20sync=20resolve=20+=20double-fire=20guard=20(#104)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/harden round 1 (adversarial + correctness agents, confirmed against repo
precedent CollisionReview/DiffView):

- Resolve computed defaults synchronously in useMemo instead of a mount
  effect. The effect-based setResolved left a window where a fast ENTER
  on "Use these values" submitted pre-resolution values (computed keys
  absent), which the machine's validator would then reject; the
  setResolved re-render also re-rendered the live Select. The memo
  resolves before first paint; errors still surface via an effect to keep
  the onError parent-setState off the render path.
- Guard the Select onChange with firedRef — Select can re-fire on Ink
  re-focus, and a double-fire would advance the adopt machine twice. Same
  defense CollisionReview and DiffView already carry.

Tests: parity assertion (Use ≡ resolveComputedDefaults(mergePrefill) +
default selections, the --yes contract); "no submit before ENTER" for a
computed-default shard (race guard); double-ENTER fires onComplete once.

Docs: SHARD-LAYOUT.md §Adopt — "values wizard" → AdoptValuesGate gate +
InstallWizard-on-override (stale reuse reference).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/SHARD-LAYOUT.md                     |  2 +-
 source/components/AdoptValuesGate.tsx    | 45 +++++++++++++------
 tests/component/AdoptValuesGate.test.tsx | 55 ++++++++++++++++++++++--
 3 files changed, 83 insertions(+), 19 deletions(-)

diff --git a/docs/SHARD-LAYOUT.md b/docs/SHARD-LAYOUT.md
index 0b426b0..e3fcb0b 100644
--- a/docs/SHARD-LAYOUT.md
+++ b/docs/SHARD-LAYOUT.md
@@ -229,7 +229,7 @@ Phases (logical order; UI may interleave loading messages):
 
 Future `shardmind update` calls work normally — merge base is the adopt-time cache.
 
-Reuses: drift detection (`core/drift.ts`), install-executor, values wizard, hook runtime. New surfaces: 2-way diff UI component (`AdoptDiffView`), adopt-planner, adopt-executor.
+Reuses: drift detection (`core/drift.ts`), install-executor, value collection (`AdoptValuesGate` confirm page → `InstallWizard` on override, #104), hook runtime. New surfaces: 2-way diff UI component (`AdoptDiffView`), adopt-planner, adopt-executor.
 
 ## Naming decisions
 
diff --git a/source/components/AdoptValuesGate.tsx b/source/components/AdoptValuesGate.tsx
index 24528d2..1b763d1 100644
--- a/source/components/AdoptValuesGate.tsx
+++ b/source/components/AdoptValuesGate.tsx
@@ -1,4 +1,4 @@
-import { useState, useMemo, useEffect } from 'react';
+import { useState, useMemo, useEffect, useRef } from 'react';
 import { Box, Text } from 'ink';
 import { Select } from './ui.js';
 import type { ShardManifest, ShardSchema } from '../runtime/types.js';
@@ -70,21 +70,36 @@ export default function AdoptValuesGate({
   const [mode, setMode] = useState<'confirm' | 'override'>(
     hasMissingRequired ? 'override' : 'confirm',
   );
-  const [resolved, setResolved] = useState<Record<string, unknown>>(merged);
 
-  // Resolve computed defaults once, before the confirm page reads them.
-  // Done in an effect (not render) to keep onError off the render path and
-  // dodge React 18 strict-mode double-fire — same pattern as InstallWizard.
+  // Resolve computed defaults *synchronously* so the confirm page — and the
+  // "Use these values" action that reads `resolved` — never observe a
+  // pre-resolution frame. An effect-based setState would leave a window
+  // where a fast ENTER submits unresolved values (computed keys still
+  // absent), and the re-render would re-fire the live Select. Skipped in
+  // override mode: the wizard resolves computed defaults itself after
+  // collecting values. Errors are surfaced from an effect below, not here,
+  // to keep the onError call (a parent setState) off the render path.
+  const { values: resolved, error: resolveError } = useMemo(
+    (): { values: Record<string, unknown>; error: Error | null } => {
+      if (hasMissingRequired) return { values: merged, error: null };
+      try {
+        return { values: resolveComputedDefaults(schema, merged), error: null };
+      } catch (err) {
+        return { values: merged, error: err as Error };
+      }
+    },
+    [schema, merged, hasMissingRequired],
+  );
+
   useEffect(() => {
-    if (hasMissingRequired) return;
-    try {
-      setResolved(resolveComputedDefaults(schema, merged));
-    } catch (err) {
-      onError(err as Error);
-    }
-    // Mount-only — schema/prefill are stable within a gate session.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+    if (resolveError) onError(resolveError);
+  }, [resolveError, onError]);
+
+  // `Select` can fire onChange more than once if Ink re-focuses the
+  // instance (see CollisionReview / DiffView). Every branch is a one-shot
+  // decision, so guard all of them against a double-fire that would advance
+  // the adopt machine twice.
+  const firedRef = useRef(false);
 
   if (mode === 'override') {
     return (
@@ -140,6 +155,8 @@ export default function AdoptValuesGate({
           { label: 'Cancel', value: 'cancel' },
         ]}
         onChange={(v) => {
+          if (firedRef.current) return;
+          firedRef.current = true;
           if (v === 'use') {
             onComplete({
               values: resolved,
diff --git a/tests/component/AdoptValuesGate.test.tsx b/tests/component/AdoptValuesGate.test.tsx
index e66697c..ef0c105 100644
--- a/tests/component/AdoptValuesGate.test.tsx
+++ b/tests/component/AdoptValuesGate.test.tsx
@@ -3,6 +3,11 @@ import { render, cleanup } from 'ink-testing-library';
 import React from 'react';
 import AdoptValuesGate from '../../source/components/AdoptValuesGate.js';
 import type { ShardManifest, ShardSchema } from '../../source/runtime/types.js';
+import {
+  mergePrefill,
+  resolveComputedDefaults,
+  defaultModuleSelections,
+} from '../../source/core/install-planner.js';
 import { ENTER, ARROW_DOWN, tick, waitFor, waitForCall } from './helpers.js';
 
 afterEach(() => {
@@ -87,10 +92,16 @@ describe('AdoptValuesGate', () => {
     expect(frame).toMatch(/Modules: all 2 included/);
   });
 
-  it('"Use these values" → onComplete with resolved values + all-default selections', async () => {
+  it('"Use these values" → onComplete equals the --yes (runNonInteractive) value set', async () => {
+    // Parity invariant: the confirm gate's "Use these values" must feed the
+    // adopt machine exactly what the --yes path (runNonInteractive) would —
+    // resolveComputedDefaults(mergePrefill(prefill)) + all-default module
+    // selections. The machine validates both identically in runPlanning, so
+    // matching the pre-validation set is the contract.
+    const prefill = { vault_purpose: 'research' };
     const onComplete = vi.fn();
     const { stdin, lastFrame } = await mount(
-      <AdoptValuesGate {...gateProps({ onComplete })} />,
+      <AdoptValuesGate {...gateProps({ prefillValues: prefill, onComplete })} />,
     );
     await waitFor(lastFrame, (f) => f.includes('Use these values'));
     stdin.write(ENTER); // first option focused
@@ -99,9 +110,45 @@ describe('AdoptValuesGate', () => {
       values: Record<string, unknown>;
       selections: Record<string, string>;
     };
-    expect(result.values['user_name']).toBe('Ada');
+    const expectedValues = resolveComputedDefaults(
+      confirmSchema,
+      mergePrefill(confirmSchema, prefill),
+    );
+    expect(result.values).toEqual(expectedValues);
     expect(result.values['auto_tag']).toBe('autogen'); // computed resolved
-    expect(result.selections).toEqual({ core: 'included', extras: 'included' });
+    expect(result.values['vault_purpose']).toBe('research'); // prefill wins
+    expect(result.selections).toEqual(defaultModuleSelections(confirmSchema));
+  });
+
+  it('does not submit before ENTER, even for a computed-default shard', async () => {
+    // Computed defaults resolve synchronously (useMemo), so mounting the
+    // gate must NOT auto-fire onComplete via an effect-driven re-render of
+    // the Select. Guards the stale-closure / spurious-fire race.
+    const onComplete = vi.fn();
+    const { lastFrame } = await mount(
+      <AdoptValuesGate {...gateProps({ onComplete })} />, // confirmSchema has a computed default
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    await tick(60); // give any stray effect a chance to fire
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+
+  it('double ENTER on "Use these values" fires onComplete exactly once', async () => {
+    // firedRef guard — Select can re-fire on Ink re-focus; a double-fire
+    // would advance the adopt machine twice (CollisionReview/DiffView defense).
+    const onComplete = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptValuesGate {...gateProps({ onComplete })} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    stdin.write(ENTER);
+    await waitForCall(onComplete);
+    // A second ENTER after the first selection is processed must not
+    // re-fire — the component is not unmounted in-test (the machine would
+    // do that in production), so this isolates the firedRef guard.
+    stdin.write(ENTER);
+    await tick(60);
+    expect(onComplete).toHaveBeenCalledTimes(1);
   });
 
   it('"Override individually" → drops into the InstallWizard', async () => {

From 8f4867b8b04d4a8939836994e369f092f9ba213b Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:25:00 +0200
Subject: [PATCH 6/8] =?UTF-8?q?docs(roadmap):=20check=20#104=20=E2=80=94?=
 =?UTF-8?q?=20adopt=20confirm-or-override=20values=20flow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ROADMAP.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 4ad0a2f..5547f1b 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -126,7 +126,7 @@ UX gaps surfaced during real obsidian-mind v6 install + adopt runs. None block t
 
 - [x] Wizard scroll indicator + boolean prompt consistency (Y/n typed input → selectable Yes/No) ([#100](https://github.com/breferrari/shardmind/issues/100)) — smallest item, recommended starting point.
 - [x] `multiselect` value type for module-set questions ([#101](https://github.com/breferrari/shardmind/issues/101)) — pairs with #100 (shortens module list). First-class value type + scrollable widget + per-option `default` + min/max; value→module gating stays #80.
-- [ ] Adopt: replace step-by-step install wizard with confirm-or-override values flow ([#104](https://github.com/breferrari/shardmind/issues/104))
+- [x] Adopt: replace step-by-step install wizard with confirm-or-override values flow ([#104](https://github.com/breferrari/shardmind/issues/104))
 - [ ] Adopt batch operations (keep all mine / use all theirs / auto-merge non-conflicting) ([#120](https://github.com/breferrari/shardmind/issues/120)) — pairs with #104.
 - [ ] Hook stderr presentation in Summary (truncate, dim, label as non-fatal) ([#105](https://github.com/breferrari/shardmind/issues/105))
 

From 8d878d04ca0cb1b92b819534e3a5154eb5acefb4 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:45:13 +0200
Subject: [PATCH 7/8] =?UTF-8?q?fix(adopt):=20address=20Copilot=20review=20?=
 =?UTF-8?q?=E2=80=94=20blocking=20predicate,=20provenance,=20error=20guard?=
 =?UTF-8?q?=20(#104)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three Copilot review comments on AdoptValuesGate, all valid:

1. The confirm/override decision used `missingValueKeys(merged)`, which (by
   design, for the install wizard's prompt list) returns optional unset keys
   too — so a shard with any optional no-default value wrongly forced the
   wizard. Replace with a dedicated predicate: a value blocks the confirm
   page only if it is *required*, has no default (literal or computed), and
   isn't in --values. Optional unset values confirm fine (validator accepts).

2. Provenance label was always printed, so a no-default/no-prefill value
   rendered as "(unset) (default)" — a lie. provenanceOf now returns null in
   that case and the label is omitted.

3. On a computed-default resolution failure, the confirm Select still
   rendered until the error effect fired, leaving a window to submit the
   unresolved set. Render a non-interactive "Preparing values…" placeholder
   when resolveError is set, so there is no submittable Select in that window.

Test: optional-no-default value stays on the confirm page with no misleading
provenance label. Existing required-no-default → override and computed-throw
→ onError cases still hold.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/components/AdoptValuesGate.tsx    | 77 ++++++++++++++++--------
 tests/component/AdoptValuesGate.test.tsx | 23 +++++++
 2 files changed, 75 insertions(+), 25 deletions(-)

diff --git a/source/components/AdoptValuesGate.tsx b/source/components/AdoptValuesGate.tsx
index 1b763d1..61230b4 100644
--- a/source/components/AdoptValuesGate.tsx
+++ b/source/components/AdoptValuesGate.tsx
@@ -6,7 +6,6 @@ import Header from './Header.js';
 import InstallWizard, { type WizardResult, formatValue } from './InstallWizard.js';
 import {
   mergePrefill,
-  missingValueKeys,
   resolveComputedDefaults,
   defaultModuleSelections,
 } from '../core/install-planner.js';
@@ -55,20 +54,27 @@ export default function AdoptValuesGate({
     [schema, prefillValues],
   );
 
-  // Required values with no default and not supplied via `--values`: there
-  // is no confident "use these" set to confirm, so fall straight through to
-  // the per-value wizard (adopt's pre-#104 behaviour for this shard shape).
-  // `missingValueKeys` is fed the *merged* map (literal defaults filled),
-  // exactly as the `--yes` path does (`use-adopt-machine.ts::runNonInteractive`)
-  // — feeding it the raw prefill would flag every default-bearing key as
-  // "missing" and wrongly force override for the common all-defaults shard.
-  const hasMissingRequired = useMemo(
-    () => missingValueKeys(schema, merged).length > 0,
-    [schema, merged],
+  // A value blocks the confirm page only if it is **required**, has no
+  // default (literal or computed), and wasn't supplied via `--values` —
+  // there is no value to confirm, so fall straight through to the per-value
+  // wizard. Optional unset values do NOT block: "Use these values" simply
+  // leaves them unset, which the validator accepts. (This is deliberately
+  // not `missingValueKeys`, which — by design, for the install wizard's
+  // prompt list — also returns optional unset keys and would wrongly force
+  // override for a shard with any optional no-default value.)
+  const hasBlockingValue = useMemo(
+    () =>
+      Object.entries(schema.values).some(
+        ([key, def]) =>
+          def.required === true &&
+          def.default === undefined &&
+          !Object.prototype.hasOwnProperty.call(prefillValues, key),
+      ),
+    [schema, prefillValues],
   );
 
   const [mode, setMode] = useState<'confirm' | 'override'>(
-    hasMissingRequired ? 'override' : 'confirm',
+    hasBlockingValue ? 'override' : 'confirm',
   );
 
   // Resolve computed defaults *synchronously* so the confirm page — and the
@@ -81,14 +87,14 @@ export default function AdoptValuesGate({
   // to keep the onError call (a parent setState) off the render path.
   const { values: resolved, error: resolveError } = useMemo(
     (): { values: Record<string, unknown>; error: Error | null } => {
-      if (hasMissingRequired) return { values: merged, error: null };
+      if (hasBlockingValue) return { values: merged, error: null };
       try {
         return { values: resolveComputedDefaults(schema, merged), error: null };
       } catch (err) {
         return { values: merged, error: err as Error };
       }
     },
-    [schema, merged, hasMissingRequired],
+    [schema, merged, hasBlockingValue],
   );
 
   useEffect(() => {
@@ -121,6 +127,20 @@ export default function AdoptValuesGate({
     );
   }
 
+  // resolveComputedDefaults threw. The error effect above is calling
+  // onError, which moves the adopt machine to its error phase and unmounts
+  // this gate. Render a non-interactive placeholder for that brief window
+  // so the user can't select "Use these values" and submit the unresolved
+  // value set before the transition lands.
+  if (resolveError) {
+    return (
+      <Box flexDirection="column" gap={1}>
+        <Header manifest={manifest} />
+        <Text dimColor>Preparing values…</Text>
+      </Box>
+    );
+  }
+
   const moduleCount = Object.keys(schema.modules).length;
   const valueKeys = Object.keys(schema.values);
 
@@ -134,13 +154,18 @@ export default function AdoptValuesGate({
         {valueKeys.length === 0 ? (
           <Text dimColor>  (this shard declares no values)</Text>
         ) : (
-          valueKeys.map((key) => (
-            <Text key={key}>
-              <Text>  {key}: </Text>
-              <Text color="cyan">{formatValue(resolved[key])}</Text>
-              <Text dimColor>  ({provenanceOf(key, schema, prefillValues)})</Text>
-            </Text>
-          ))
+          valueKeys.map((key) => {
+            const provenance = provenanceOf(key, schema, prefillValues);
+            return (
+              <Text key={key}>
+                <Text>  {key}: </Text>
+                <Text color="cyan">{formatValue(resolved[key])}</Text>
+                {/* No label when the value has no default and no prefill —
+                    it renders as (unset); "(default)" there would be a lie. */}
+                {provenance && <Text dimColor>  ({provenance})</Text>}
+              </Text>
+            );
+          })
         )}
       </Box>
 
@@ -177,11 +202,13 @@ function provenanceOf(
   key: string,
   schema: ShardSchema,
   prefillValues: Record<string, unknown>,
-): Provenance {
+): Provenance | null {
   if (Object.prototype.hasOwnProperty.call(prefillValues, key)) return 'from --values';
   const def = schema.values[key];
-  if (def && def.default !== undefined && isComputedDefault(def.default)) {
-    return 'computed';
+  if (def && def.default !== undefined) {
+    return isComputedDefault(def.default) ? 'computed' : 'default';
   }
-  return 'default';
+  // No default and not prefilled — the value is unset; there is no
+  // provenance to report.
+  return null;
 }
diff --git a/tests/component/AdoptValuesGate.test.tsx b/tests/component/AdoptValuesGate.test.tsx
index ef0c105..ceba0ad 100644
--- a/tests/component/AdoptValuesGate.test.tsx
+++ b/tests/component/AdoptValuesGate.test.tsx
@@ -177,6 +177,29 @@ describe('AdoptValuesGate', () => {
     expect(onCancel).toHaveBeenCalledTimes(1);
   });
 
+  it('optional value with no default → stays on the confirm page, no misleading provenance', async () => {
+    // Regression for the over-broad blocking predicate: only *required*
+    // no-default-no-prefill values force the wizard. An optional unset value
+    // confirms fine (it renders as "(unset)" with no provenance label —
+    // "(default)" there would be a lie).
+    const optionalUnsetSchema: ShardSchema = {
+      ...confirmSchema,
+      values: {
+        user_name: { type: 'string', message: 'Your name', default: 'Ada', group: 'g' },
+        nickname: { type: 'string', message: 'Nickname', group: 'g' }, // optional, no default
+      },
+    };
+    const { lastFrame } = await mount(
+      <AdoptValuesGate {...gateProps({ schema: optionalUnsetSchema })} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Use these values'));
+    const frame = lastFrame() ?? '';
+    expect(frame).toMatch(/user_name:\s+Ada\s+\(default\)/);
+    // Unset optional value: shown, but with no provenance label.
+    expect(frame).toMatch(/nickname:\s+\(unset\)/);
+    expect(frame).not.toMatch(/nickname:[^\n]*\(default\)/);
+  });
+
   it('required value with no default and no prefill → opens directly in override (no confirm page)', async () => {
     const requiredSchema: ShardSchema = {
       ...confirmSchema,

From 155e37cbbcb7d7ac82966ceb9b1831c574e9adc9 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Sun, 31 May 2026 14:52:18 +0200
Subject: [PATCH 8/8] =?UTF-8?q?test(adopt):=20fix=20flaky=20scenario=2024?=
 =?UTF-8?q?=20=E2=80=94=20assert=20on=20captured=20frame=20(#104)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Scenario 24 (the #121 version-mismatch refusal) waited on one regex then
re-read r.lastFrame() for a different regex, which races the 100 ms exit()
that clears the testing-library buffer — the second read can return '\n'.
A slow windows-latest/node-22 CI cell (718s suite) surfaced it on this PR.

Capture the matched frame from waitFor and assert both the message and the
SHARDMIND_VERSION_MISMATCH code on it — the same capture pattern scenarios
19 and 22 already use. The error phase renders message + code in one frame.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 tests/component/flows/adopt-flow.test.tsx | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index ab1be7a..f3a10c3 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -261,12 +261,16 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
         shardRef: `github:${SLUG_VERSION_MISMATCH}#v0.1.0`,
         vaultRoot: vault,
       });
-      await waitFor(
+      // Capture the matched frame and assert both the message and the code
+      // on it — a second r.lastFrame() races the 100 ms exit() that clears
+      // the testing-library buffer (same capture pattern as scenarios 19/22;
+      // a slow CI cell surfaced the race here).
+      const frame = await waitFor(
         r.lastFrame,
         (f) => /requires shardmind >=99\.0\.0/.test(f),
         30_000,
       );
-      expect(r.lastFrame() ?? '').toMatch(/SHARDMIND_VERSION_MISMATCH/);
+      expect(frame).toMatch(/SHARDMIND_VERSION_MISMATCH/);
       // No engine state written — the vault was never adopted.
       const stateExists = await fs
         .stat(path.join(vault, '.shardmind', 'state.json'))