@codedology/code-forge 0.1.0 → 0.2.1

package/src/install/wizard/answers.mjs

@@ -12,7 +12,7 @@ import { defaultsForProvider } from '../../config/defaults/index.mjs';
 import { detectGates } from '../../gates/detect.mjs';
 import { detectAgentEnv } from '../agent-env.mjs';
 import { detectAll } from '../detect.mjs';
-import { ANSWER_FLAGS, PROVIDERS } from './flags.mjs';
+import { ANSWER_FLAGS, GATE_NAMES, PROOF_KEYS, PROVIDERS } from './flags.mjs';
 
 /** Harnesses that expose a subagent tool (§5.1: Claude Code's `Agent`, [A13]). */
 export const SUBAGENT_HARNESSES = Object.freeze(['claude']);
@@ -29,28 +29,33 @@ export const COPY_UNTRACKED = Object.freeze({
   python: ['.env'],
 });
 
-/** `link_dirs` per stack: the dependency directories an export links instead of copying. */
-const LINK_DIRS = Object.freeze({
-  laravel: ['vendor', 'node_modules'],
-  php: ['vendor'],
-  node: ['node_modules'],
-  python: ['.venv'],
-  rust: ['target'],
-  go: [],
-  unknown: ['vendor', 'node_modules'],
-});
+/** The proof profiles {@link proofProfile} can return. */
+const PROFILES = Object.freeze(['laravel', 'php', 'node', 'python', 'rust', 'go', 'unknown']);
 
-/** High-risk paths per stack (v1 §2 step 8: migrations, policies, money, auth/middleware, webhooks). */
-const HIGH_PATHS = Object.freeze({
-  laravel: ['database/migrations/**', 'app/Policies/**', 'app/Http/Middleware/**', '**/*Money*', '**/*Webhook*'],
-  php: ['**/*Money*', '**/*Webhook*', '**/Auth/**'],
-  node: ['**/migrations/**', '**/auth/**', '**/*money*', '**/*webhook*'],
-  python: ['**/migrations/**', '**/auth/**', '**/*money*', '**/*webhook*'],
-  rust: ['**/auth/**', '**/*money*'],
-  go: ['**/auth/**', '**/*money*'],
-  unknown: [],
+/**
+ * The one source of truth for `link_dirs` (B24): each dependency folder an export links instead of
+ * copying, with the manifests that make it right to propose. A folder is proposed when one of its
+ * manifests exists, whether or not the dependencies are installed yet.
+ */
+export const LINK_DIR_MANIFESTS = Object.freeze({
+  vendor: Object.freeze(['composer.json', 'go.mod']),
+  node_modules: Object.freeze(['package.json']),
+  '.venv': Object.freeze(['pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile']),
+  target: Object.freeze(['Cargo.toml']),
 });
 
+/**
+ * The `link_dirs` entries whose manifest exists in `cwd`, in {@link LINK_DIR_MANIFESTS} order, each
+ * with the manifests found for it.
+ * @param {string} cwd
+ * @returns {Array<{dir: string, manifests: string[]}>}
+ */
+export function linkDirsFromManifests(cwd) {
+  return Object.entries(LINK_DIR_MANIFESTS)
+    .map(([dir, manifests]) => ({ dir, manifests: manifests.filter((m) => existsSync(path.join(cwd, m))) }))
+    .filter((e) => e.manifests.length > 0);
+}
+
 /**
  * The proof profile is decided from the project, not from the gate detector's stack name alone:
  * `detectGates` (B5) names only `php-pest`, so a Laravel app on PHPUnit reaches here as `node`
@@ -65,7 +70,7 @@ export function proofProfile(stack, cwd) {
   if (php && existsSync(path.join(cwd, 'artisan'))) return 'laravel';
   if (stack.startsWith('php')) return 'php';
   // a detected non-PHP stack keeps its word; only an undetected project falls back on composer.json
-  if (stack !== 'unknown' && Object.hasOwn(LINK_DIRS, stack)) return stack;
+  if (stack !== 'unknown' && PROFILES.includes(stack)) return stack;
   return composer ? 'php' : 'unknown';
 }
 
@@ -109,16 +114,33 @@ export function proposeJudge(provider) {
 }
 
 /**
- * Step 8's proposal for a stack.
+ * Step 8's `copy_untracked` candidates for a profile, before the project is looked at.
+ * @param {string} profile
+ * @returns {string[]}
+ */
+export function copyCandidates(profile) {
+  return [...(COPY_UNTRACKED[profile] ?? [])];
+}
+
+/**
+ * Step 8's proposal (B24): nothing is asked. High-risk paths are a deliberate blank (the project
+ * never says which paths are high-risk) and isolation is `export`. `link_dirs` is every folder whose
+ * manifest ({@link LINK_DIR_MANIFESTS}) exists in `cwd`, installed or not, whatever the profile (a
+ * PHP app with a `package.json` links `node_modules` too); `copy_untracked` keeps the profile's
+ * candidates that exist in `cwd` themselves. Nothing kept gives `[]`. Without `cwd` nothing can be
+ * looked at: `link_dirs` is `[]` and `copy_untracked` the unfiltered candidates.
  * @param {string} profile
+ * @param {string} [cwd]
  * @returns {{high: string[], isolation: 'export', link_dirs: string[], copy_untracked: string[]}}
  */
-export function proposeProof(profile) {
+export function proposeProof(profile, cwd) {
+  const candidates = copyCandidates(profile);
+  if (cwd === undefined) return { high: [], isolation: 'export', link_dirs: [], copy_untracked: candidates };
   return {
-    high: [...(HIGH_PATHS[profile] ?? [])],
+    high: [],
     isolation: 'export',
-    link_dirs: [...(LINK_DIRS[profile] ?? LINK_DIRS.unknown)],
-    copy_untracked: [...(COPY_UNTRACKED[profile] ?? [])],
+    link_dirs: linkDirsFromManifests(cwd).map((e) => e.dir),
+    copy_untracked: candidates.filter((rel) => existsSync(path.join(cwd, rel))),
   };
 }
 
@@ -272,6 +294,12 @@ function gateArgv(gate) {
  * @property {boolean} doctor
  */
 
+/**
+ * Where each gate and each proof value came from (B24): `flag`, `existing` (the current
+ * `.code-forge.yml`), `detected` (the project on disk) or `default`.
+ * @typedef {{gates: Record<string, 'flag'|'existing'|'detected'>, proof: Record<string, 'flag'|'existing'|'detected'|'default'>}} Origins
+ */
+
 /** The answer keys in step order. */
 export const ANSWER_KEYS = Object.freeze([
   'tools', 'yes_tools', 'harnesses', 'scope', 'method', 'provider', 'levels', 'refresh_models',
@@ -283,11 +311,13 @@ export const ANSWER_KEYS = Object.freeze([
  * @param {Record<string, any>|null} existing - the current `.code-forge.yml`, when there is one.
  * @param {Record<string, any>|null} user - the current user-level config (`~/.code-forge/`).
  * @param {Array<{flag: string, value: any}>} given - parsed answer flags.
- * @returns {{values: Answers, sources: Record<string, 'default'|'existing'|'flag'>}}
+ * @returns {{values: Answers, sources: Record<string, 'default'|'existing'|'flag'>, origins: Origins}}
  */
 export function resolveAnswers(ctx, existing, user, given) {
   /** @type {Record<string, 'default'|'existing'|'flag'>} */
   const sources = {};
+  /** @type {Origins} */
+  const origins = { gates: {}, proof: {} };
   const ex = existing ?? {};
   /** @type {any} */
   const v = {};
@@ -352,38 +382,64 @@ export function resolveAnswers(ctx, existing, user, given) {
   set('solo_project', user?.solo?.project_id, () => null);
   if (lastFlag('solo_project')) override('solo_project', lastFlag('solo_project').value);
 
+  // Gates and proof are never asked (B24): each value comes from a flag, else the existing
+  // config, else the project. `origins` records which, per gate and per proof key. A gate the
+  // existing config left blank is filled when the project now shows one; a set gate is kept.
   const detectedGates = {
     test: gateArgv(ctx.detected.test),
     lint: gateArgv(ctx.detected.lint),
     types: gateArgv(ctx.detected.types),
     format: gateArgv(ctx.detected.format),
   };
-  const exGates = ex.gates && typeof ex.gates === 'object' ? ex.gates : undefined;
-  set('gates', exGates ? { ...detectedGates, ...exGates } : undefined, () => detectedGates);
+  const exGates = ex.gates && typeof ex.gates === 'object' ? ex.gates : {};
+  // keys beyond the four gates (`extra`, `full_suite_threshold_files`, …) are kept as they are
+  const gates = /** @type {Record<string, any>} */ (clone(exGates));
+  for (const name of GATE_NAMES) {
+    const kept = exGates[name];
+    const keep = kept !== undefined && kept !== null;
+    gates[name] = keep ? clone(kept) : detectedGates[/** @type {keyof typeof detectedGates} */ (name)];
+    origins.gates[name] = keep ? 'existing' : 'detected';
+  }
+  set('gates', Object.keys(exGates).length > 0 ? gates : undefined, () => gates);
   if (flagsFor('gates').length > 0) {
-    const gates = clone(v.gates);
-    for (const g of flagsFor('gates')) gates[g.value.name] = g.value.argv;
-    override('gates', gates);
+    const flagged = clone(v.gates);
+    for (const g of flagsFor('gates')) {
+      flagged[g.value.name] = g.value.argv;
+      origins.gates[g.value.name] = 'flag';
+    }
+    override('gates', flagged);
   }
 
-  const proposal = proposeProof(ctx.profile);
-  const exProof = ex.proof && typeof ex.proof === 'object'
-    ? {
-        high: ex.proof.tiers?.high?.paths ?? proposal.high,
-        isolation: ex.proof.isolation ?? proposal.isolation,
-        link_dirs: ex.proof.export?.link_dirs ?? proposal.link_dirs,
-        copy_untracked: ex.proof.export?.copy_untracked ?? proposal.copy_untracked,
-      }
-    : undefined;
-  set('proof', exProof, () => proposal);
+  const proposal = proposeProof(ctx.profile, ctx.cwd);
+  const exProof = ex.proof && typeof ex.proof === 'object' ? ex.proof : {};
+  /** @type {Record<string, unknown>} */
+  const exProofValues = {
+    high: exProof.tiers?.high?.paths,
+    isolation: exProof.isolation,
+    link_dirs: exProof.export?.link_dirs,
+    copy_untracked: exProof.export?.copy_untracked,
+  };
+  const proof = /** @type {Record<string, any>} */ ({});
+  for (const key of PROOF_KEYS) {
+    const kept = exProofValues[key];
+    const keep = kept !== undefined && kept !== null;
+    proof[key] = keep ? clone(kept) : proposal[/** @type {keyof typeof proposal} */ (key)];
+    // without a cwd nothing was looked at, so the lists are defaults, not detections
+    const looked = ctx.cwd !== undefined && (key === 'link_dirs' || key === 'copy_untracked');
+    origins.proof[key] = keep ? 'existing' : looked ? 'detected' : 'default';
+  }
+  set('proof', ex.proof && typeof ex.proof === 'object' ? proof : undefined, () => proof);
   if (flagsFor('proof').length > 0) {
-    const proof = clone(v.proof);
-    for (const g of flagsFor('proof')) proof[g.value.key] = g.value.value;
-    override('proof', proof);
+    const flagged = clone(v.proof);
+    for (const g of flagsFor('proof')) {
+      flagged[g.value.key] = g.value.value;
+      origins.proof[g.value.key] = 'flag';
+    }
+    override('proof', flagged);
   }
 
   set('doctor', undefined, () => true);
   if (lastFlag('doctor')) override('doctor', false);
 
-  return { values: v, sources };
+  return { values: v, sources, origins };
 }

package/src/install/wizard/run.mjs

@@ -1,7 +1,9 @@
 /**
  * `code-forge init` — the nine-step setup wizard (plan §2; block B13a).
  *
- * Order: answers (defaults ← existing config ← flags; then questions when interactive) → step 5
+ * Order: answers (defaults ← existing config ← flags; then questions when interactive) → the
+ * "Project settings (detected)" summary of gates and proof (B24; interactive: one "Use these /
+ * Customize now / Leave for later" choice, and the eight pre-filled questions on Customize) → step 5
  * key source → build + merge + validate the config (nothing is written when it is invalid or a
  * required answer is missing) → write `.code-forge.yml` only when it changes → tools (step 1),
  * model refresh (3), harness links (2), user config → the §5.1 stop line when the harness has no
@@ -9,7 +11,7 @@
  *
  * Output: an agent harness (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_SANDBOX*`, `AI_AGENT`) or
  * a non-TTY stdin gets exactly ONE JSON line on stdout — `{ok, wrote, harnesses, engine_stop,
- * doctor, log, log_tail}` on success, `{ok: false, error, wrote, log, log_tail}` on any failure
+ * doctor, settings, blank, log, log_tail}` on success, `{ok: false, error, wrote, log, log_tail}` on any failure
  * after the flags parsed; a person gets the lines (and `init: <error>` on stderr). Either way the
  * lines go to `~/.code-forge/logs/init-<ts>.log`, on failure too. Every line passes through
  * `redact`; a key typed at the prompt goes to the key store and nowhere else — the config holds its
@@ -34,7 +36,8 @@ import { install, installsPath } from '../link.mjs';
 import { currentHarness, effectiveProvider, gatherContext, judgeCollision, proposeJudge, resolveAnswers, SUBAGENT_HARNESSES } from './answers.mjs';
 import { changedPaths, generatedConfig, mergeConfig, mergeInto, serializeConfig } from './project-file.mjs';
 import { parseInitArgs, UsageError } from './flags.mjs';
-import { askAnswers, askJevSource, CancelledError } from './steps.mjs';
+import { askAnswers, askJevSource, askProjectSettings, askSettingsChoice, CancelledError, HINTS, withHint } from './steps.mjs';
+import { summarizeSettings } from './summary.mjs';
 
 /** §5.1's stop text, printed at setup (not at the first run) when there is no engine to use. */
 export const NO_ENGINE_STOP_TEXT = [
@@ -164,6 +167,10 @@ export async function runInit(args, deps = {}) {
   let engineStop = false;
   /** @type {{ok: boolean, counts: Record<string, number>} | null} */
   let doctor = null;
+  /** @type {import('./summary.mjs').SettingsSummary | null} */
+  let summary = null;
+  // lines already on stdout (the settings summary): `finish` prints only the rest
+  let printed = 0;
 
   /**
    * The one exit: writes the log, then either the success shape or `{ok: false, error, wrote, …}`.
@@ -186,11 +193,12 @@ export async function runInit(args, deps = {}) {
     const tail = lines.slice(-10);
     if (jsonMode) {
       const body = error === null
-        ? { ok: code === 0, wrote, harnesses: linked, engine_stop: engineStop, doctor, log, log_tail: tail }
+        ? { ok: code === 0, wrote, harnesses: linked, engine_stop: engineStop, doctor, settings: summary?.settings ?? null, blank: summary?.blank ?? [], log, log_tail: tail }
         : { ok: false, error, wrote, log, log_tail: tail };
       writeAgentJson(JSON.parse(redact(JSON.stringify(body))), { stdout });
     } else if (error === null) {
-      stdout.write(`${lines.join('\n')}\nlog: ${log}\n`);
+      const rest = lines.slice(printed);
+      stdout.write(`${rest.length > 0 ? `${rest.join('\n')}\n` : ''}log: ${log}\n`);
     }
     return code;
   };
@@ -215,12 +223,34 @@ export async function runInit(args, deps = {}) {
     const userFile = path.join(cfDir, USER_CONFIG_FILE);
     const userCfg = await readUserConfig(userFile);
 
-    const { values, sources } = resolveAnswers(ctx, existing, userCfg, parsed.given);
+    const { values, sources, origins } = resolveAnswers(ctx, existing, userCfg, parsed.given);
     if (interactive) {
       ui = deps.ui ?? /** @type {any} */ (await import('@clack/prompts'));
       await askAnswers(values, sources, ctx, ui);
     }
 
+    // Gates and proof are never asked (B24): the summary says what was found and what is blank.
+    // A person sees it now, before anything is written; agent mode gets it in the JSON line.
+    summary = summarizeSettings(values, origins, ctx);
+    /** @param {string[]} shown - logged, and printed at once for a person */
+    const showNow = (shown) => {
+      for (const line of shown) say(line);
+      if (jsonMode) return;
+      stdout.write(`${lines.slice(printed).join('\n')}\n`);
+      printed = lines.length;
+    };
+    showNow(summary.lines);
+    if (interactive) {
+      const choice = await askSettingsChoice(ui);
+      if (choice === 'customize') {
+        const changedKeys = await askProjectSettings(values, origins, ui);
+        say(`settings: customized (${changedKeys.length > 0 ? changedKeys.join(', ') : 'no change'})`);
+      } else if (choice === 'later') {
+        const keys = summary.blank.length > 0 ? summary.blank : Object.keys(summary.settings);
+        showNow([`settings: edit .code-forge.yml later: ${keys.join(', ')} — then run \`code-forge validate\``]);
+      }
+    }
+
     // Step 5 — where the Jev key comes from. Only a reference is ever kept: `env:NAME` when the
     // environment holds it, else `user` (the key store holds it, whatever backend the store
     // reports — keychain, file, a cached 1Password read…); the backend name is recorded as the
@@ -278,7 +308,7 @@ export async function runInit(args, deps = {}) {
       say(`${DEFAULT_CONFIG_FILENAME}: unchanged`);
     } else {
       if (existing) say(`${DEFAULT_CONFIG_FILENAME}: changes ${changed.join(', ')}`);
-      const go = existing && interactive ? await ui.confirm({ message: `Apply ${changed.length} change(s) to ${DEFAULT_CONFIG_FILENAME}?`, initialValue: true }) : true;
+      const go = existing && interactive ? await ui.confirm({ message: withHint(`Apply ${changed.length} change(s) to ${DEFAULT_CONFIG_FILENAME}?`, HINTS.apply), initialValue: true }) : true;
       if (ui?.isCancel(go) || go !== true) throw new CancelledError('cancelled — nothing written');
       await writeText(configFile, serializeConfig(merged));
       wrote.push(configFile);

package/src/install/wizard/steps.mjs

@@ -1,6 +1,8 @@
 /**
  * The interactive half of `code-forge init` (plan §2, block B13a): one question per answer that
- * no flag already fixed, default on Enter. `ui` has `@clack/prompts`' shape (`select`,
+ * no flag already fixed, default on Enter, each with a one-line hint (B24). Gates and proof
+ * settings come from the project and are shown in a summary (B24); they are asked only when the
+ * person picks "Customize now" at {@link askSettingsChoice}. `ui` has `@clack/prompts`' shape (`select`,
  * `multiselect`, `text`, `confirm`, `password`, `isCancel`), so the real module is passed in
  * production and a scripted fake in tests. Step 5's key question lives in {@link askJevSource}
  * because it is asked only when the chain resolves nothing.
@@ -15,7 +17,7 @@ export class CancelledError extends Error {}
 
 /**
  * @typedef {object} Ui
- * @property {(o: {message: string, options: Array<{value: any, label?: string}>, initialValue?: any}) => Promise<any>} select
+ * @property {(o: {message: string, options: Array<{value: any, label?: string, hint?: string}>, initialValue?: any}) => Promise<any>} select
  * @property {(o: {message: string, options: Array<{value: any, label?: string}>, initialValues?: any[], required?: boolean}) => Promise<any>} multiselect
  * @property {(o: {message: string, initialValue?: string, placeholder?: string}) => Promise<any>} text
  * @property {(o: {message: string, initialValue?: boolean}) => Promise<any>} confirm
@@ -30,6 +32,43 @@ async function answer(ui, pending) {
   return value;
 }
 
+/** The 1Password option's hint: where to find the reference in the app. */
+export const OP_REF_HINT = 'In the 1Password app, right-click the key field → Copy Secret Reference (op://vault/item/field).';
+
+/** The one-sentence hint line under each question (B24). */
+export const HINTS = Object.freeze({
+  tools: 'Recommended adds Solo and the Codex, Grok, Gemini and 1Password CLIs, each only after its own yes.',
+  harnesses: 'The skill is linked into each harness you pick; detected ones are marked.',
+  scope: 'project puts the link inside this repository; global puts it under your home folder.',
+  method: 'A symlink follows package updates; a copy stays as installed.',
+  provider: 'The model family every level uses unless a level names its own provider.',
+  levels: 'L0 is the cheapest model and L3 the strongest; Enter keeps all four.',
+  level: 'Enter keeps this level as shown.',
+  refresh_models: 'Reads only local cache files; nothing is sent anywhere.',
+  multimodel: 'Two providers review each block and a third one judges; it costs more per block.',
+  second_provider: 'This provider reviews each block next to the L2 reviewer.',
+  judge: 'The judge settles disagreements between the two reviewers.',
+  engine: 'auto uses Solo when present, otherwise the subagents of the current harness.',
+  solo_project: 'The Solo project that coder processes run in; leave blank for none.',
+  jev: 'Jev is the small fast classifier behind System 1; skip uses rules only.',
+  env: 'That variable must hold the key whenever code-forge runs.',
+  paste: 'The key goes to the OS key store; the config keeps only a reference.',
+  settings: 'Pick how to treat the gate and proof values shown above.',
+  apply: 'Only the listed keys change; your other edits stay.',
+});
+
+/** The one-line hints of the "Customize now" questions, in the order they are asked (B24). */
+export const SETTING_HINTS = Object.freeze({
+  test: 'the command that runs your tests; the block cannot close if it fails (blank = no test gate)',
+  lint: 'the command that runs your linter; the block cannot close if it fails (blank = no lint gate)',
+  types: 'the command that runs your type checker; the block cannot close if it fails (blank = no types gate)',
+  format: 'the command that runs your format check; the block cannot close if it fails (blank = no format gate)',
+  high: 'globs where mistakes are costly (auth, billing); these files get deeper reviews and need red→green proof to close (blank = none)',
+  isolation: 'export = run proof tests in a temporary copy (safe with parallel coders); lock = run in your folder and pause other coders',
+  link_dirs: 'big folders the copy links to instead of copying, e.g. node_modules, vendor',
+  copy_untracked: 'files git does not track but your tests need, e.g. .env, .env.testing',
+});
+
 /**
  * A comma list split only at brace depth 0, so a glob like `app/**\/*.{php,vue}` stays one item
  * and Enter on a pre-filled list gives the list back unchanged.
@@ -53,6 +92,14 @@ function csv(text) {
   return items.map((s) => s.trim()).filter((s) => s.length > 0);
 }
 
+/**
+ * A question with its hint on the line below (clack prints a multi-line message as is).
+ * @param {string} message @param {string} hint @returns {string}
+ */
+export function withHint(message, hint) {
+  return `${message}\n${hint}`;
+}
+
 /**
  * The `model[:effort][@provider]` text a level is pre-filled with — the exact form `parseLevel`
  * reads back, so Enter keeps the level unchanged (provider override included).
@@ -63,7 +110,8 @@ export function levelText(level) {
 }
 
 /**
- * Asks every answer whose source is not `flag`, in step order. Mutates and returns `values`.
+ * Asks every answer whose source is not `flag`, in step order — gates and proof excepted (B24:
+ * see {@link askProjectSettings}). Mutates and returns `values`.
  * @param {import('./answers.mjs').Answers} values
  * @param {Record<string, string>} sources
  * @param {import('./answers.mjs').WizardContext} ctx
@@ -75,52 +123,52 @@ export async function askAnswers(values, sources, ctx, ui) {
 
   if (open('tools')) {
     values.tools = await answer(ui, ui.select({
-      message: 'Install the recommended tools, or use only the current harness?',
+      message: withHint('Install the recommended tools, or use only the current harness?', HINTS.tools),
       options: [{ value: 'current', label: 'current harness' }, { value: 'recommended', label: 'recommended tools' }],
       initialValue: values.tools,
     }));
   }
   if (open('harnesses')) {
     values.harnesses = await answer(ui, ui.multiselect({
-      message: 'Install the skill into:',
+      message: withHint('Install the skill into:', HINTS.harnesses),
       options: HARNESSES.map((h) => ({ value: h.id, label: `${h.label}${ctx.detectedHarnesses.includes(h.id) ? ' (detected)' : ''}` })),
       initialValues: values.harnesses,
       required: false,
     }));
   }
   if (open('scope')) {
-    values.scope = await answer(ui, ui.select({ message: 'Scope', options: [{ value: 'project' }, { value: 'global' }], initialValue: values.scope }));
+    values.scope = await answer(ui, ui.select({ message: withHint('Scope', HINTS.scope), options: [{ value: 'project' }, { value: 'global' }], initialValue: values.scope }));
   }
   if (open('method')) {
-    values.method = await answer(ui, ui.select({ message: 'Method', options: [{ value: 'symlink' }, { value: 'copy' }], initialValue: values.method }));
+    values.method = await answer(ui, ui.select({ message: withHint('Method', HINTS.method), options: [{ value: 'symlink' }, { value: 'copy' }], initialValue: values.method }));
   }
   if (open('provider')) {
-    values.provider = await answer(ui, ui.select({ message: 'Default provider', options: PROVIDERS.map((p) => ({ value: p })), initialValue: values.provider }));
+    values.provider = await answer(ui, ui.select({ message: withHint('Default provider', HINTS.provider), options: PROVIDERS.map((p) => ({ value: p })), initialValue: values.provider }));
   }
   if (open('levels')) {
     const summary = ['L0', 'L1', 'L2', 'L3'].map((l) => `${l}=${levelText(values.levels[l])}`).join(' ');
-    const keep = await answer(ui, ui.confirm({ message: `Keep the level matrix? ${summary}`, initialValue: true }));
+    const keep = await answer(ui, ui.confirm({ message: withHint(`Keep the level matrix? ${summary}`, HINTS.levels), initialValue: true }));
     if (!keep) {
       for (const level of ['L0', 'L1', 'L2', 'L3']) {
         const shown = levelText(values.levels[level]);
-        const typed = await answer(ui, ui.text({ message: `${level} model[:effort][@provider]`, initialValue: shown }));
+        const typed = await answer(ui, ui.text({ message: withHint(`${level} model[:effort][@provider]`, HINTS.level), initialValue: shown }));
         // Enter (unchanged text) keeps the level object as it is, `fallback` included
         if (String(typed).trim() !== shown) values.levels[level] = parseLevel(`${level}=${String(typed).trim()}`).spec;
       }
     }
   }
   if (open('refresh_models')) {
-    values.refresh_models = await answer(ui, ui.confirm({ message: 'Read model ids from the Codex/Grok CLI caches on this machine?', initialValue: false }));
+    values.refresh_models = await answer(ui, ui.confirm({ message: withHint('Read model ids from the Codex/Grok CLI caches on this machine?', HINTS.refresh_models), initialValue: false }));
   }
   if (open('multimodel')) {
-    values.multimodel = await answer(ui, ui.confirm({ message: 'Multimodel review (consensus)?', initialValue: values.multimodel }));
+    values.multimodel = await answer(ui, ui.confirm({ message: withHint('Multimodel review (consensus)?', HINTS.multimodel), initialValue: values.multimodel }));
   }
   if (values.multimodel && open('second_provider')) {
     // R5: the second reviewer must differ from the provider L2 actually runs on, not the default one
     const reviewer1 = effectiveProvider(values, 'L2');
     const others = PROVIDERS.filter((p) => p !== reviewer1);
     values.second_provider = await answer(ui, ui.select({
-      message: `Second provider (must differ from the effective L2 provider, ${reviewer1})`,
+      message: withHint(`Second provider (must differ from the effective L2 provider, ${reviewer1})`, HINTS.second_provider),
       options: others.map((p) => ({ value: p })),
       initialValue: others.includes(values.second_provider) ? values.second_provider : others[0],
     }));
@@ -132,34 +180,86 @@ export async function askAnswers(values, sources, ctx, ui) {
   for (let collision = reviewersDiffer ? judgeCollision(values) : null; collision; collision = judgeCollision(values)) {
     const proposal = collision.third ? levelText(proposeJudge(collision.third)) : '';
     const typed = await answer(ui, ui.text({
-      message: `L3 judge — must come from a third provider (reviewers: ${collision.reviewers.join(', ')}); model[:effort][@provider]`,
+      message: withHint(`L3 judge — must come from a third provider (reviewers: ${collision.reviewers.join(', ')}); model[:effort][@provider]`, HINTS.judge),
       initialValue: proposal,
     }));
     values.levels.L3 = parseLevel(`L3=${String(typed).trim()}`).spec;
   }
   // `subprocess` is never offered (R2); an existing `engine: subprocess` is kept, not asked.
   if (open('engine') && values.engine !== 'subprocess') {
-    values.engine = await answer(ui, ui.select({ message: 'Engine', options: ENGINE_CHOICES.map((e) => ({ value: e })), initialValue: values.engine }));
+    values.engine = await answer(ui, ui.select({ message: withHint('Engine', HINTS.engine), options: ENGINE_CHOICES.map((e) => ({ value: e })), initialValue: values.engine }));
   }
   if (open('solo_project') && ctx.solo && values.engine !== 'harness') {
-    const typed = await answer(ui, ui.text({ message: 'Solo project id (blank: none)', initialValue: values.solo_project === null ? '' : String(values.solo_project) }));
+    const typed = await answer(ui, ui.text({ message: withHint('Solo project id (blank: none)', HINTS.solo_project), initialValue: values.solo_project === null ? '' : String(values.solo_project) }));
     values.solo_project = /^[1-9]\d{0,9}$/.test(String(typed).trim()) ? Number(String(typed).trim()) : null;
   }
-  if (open('gates')) {
-    for (const name of GATE_NAMES) {
-      const current = values.gates[name];
-      const typed = await answer(ui, ui.text({ message: `Gate ${name} (blank or "none": no gate)`, initialValue: current ? current.join(' ') : '' }));
-      const text = String(typed ?? '').trim();
-      values.gates[name] = text === '' || text === 'none' ? null : shellWords(text);
-    }
+  return values;
+}
+
+/**
+ * The one question after the settings summary (B24), asked every time in interactive mode.
+ * @param {Ui} ui
+ * @returns {Promise<'use'|'customize'|'later'>}
+ */
+export async function askSettingsChoice(ui) {
+  return answer(ui, ui.select({
+    message: withHint('Gates and proof settings:', HINTS.settings),
+    options: [
+      { value: 'use', label: 'Use these', hint: 'keep the detected values; blanks stay blank' },
+      { value: 'customize', label: 'Customize now', hint: 'ask each gate and proof value, pre-filled with what was detected' },
+      { value: 'later', label: 'Leave for later', hint: 'keep the detected values and print the keys to edit later' },
+    ],
+    initialValue: 'use',
+  }));
+}
+
+/**
+ * "Customize now": the gate and proof questions, each pre-filled with the value shown in the
+ * summary (Enter keeps it), in the order test, lint, types, format, high-risk paths, isolation,
+ * link_dirs, copy_untracked. A value a flag set is not asked (flags override). Mutates `values`
+ * and returns the config keys whose value changed.
+ * @param {import('./answers.mjs').Answers} values
+ * @param {import('./answers.mjs').Origins} origins
+ * @param {Ui} ui
+ * @returns {Promise<string[]>}
+ */
+export async function askProjectSettings(values, origins, ui) {
+  /** @type {string[]} */
+  const changed = [];
+  for (const name of GATE_NAMES) {
+    if (origins.gates[name] === 'flag') continue;
+    const gates = /** @type {Record<string, string[]|null>} */ (values.gates);
+    const current = gates[name];
+    const typed = await answer(ui, ui.text({
+      message: withHint(`Gate ${name} (blank or "none": no gate)`, SETTING_HINTS[/** @type {keyof typeof SETTING_HINTS} */ (name)]),
+      initialValue: current ? current.join(' ') : '',
+    }));
+    const text = String(typed ?? '').trim();
+    const next = text === '' || text === 'none' ? null : shellWords(text);
+    if (JSON.stringify(next) !== JSON.stringify(current)) changed.push(`gates.${name}`);
+    gates[name] = next;
   }
-  if (open('proof')) {
-    values.proof.high = csv(await answer(ui, ui.text({ message: 'High-risk paths (comma list of globs)', initialValue: values.proof.high.join(',') })));
-    values.proof.isolation = await answer(ui, ui.select({ message: 'Proof isolation', options: [{ value: 'export' }, { value: 'lock' }], initialValue: values.proof.isolation }));
-    values.proof.link_dirs = csv(await answer(ui, ui.text({ message: 'Export: directories to link', initialValue: values.proof.link_dirs.join(',') })));
-    values.proof.copy_untracked = csv(await answer(ui, ui.text({ message: 'Export: untracked files to copy', initialValue: values.proof.copy_untracked.join(',') })));
+  const proof = values.proof;
+  /** @param {'high'|'link_dirs'|'copy_untracked'} key @param {string} message @param {string} path */
+  const list = async (key, message, path) => {
+    if (origins.proof[key] === 'flag') return;
+    const next = csv(await answer(ui, ui.text({ message: withHint(message, SETTING_HINTS[key]), initialValue: proof[key].join(',') })));
+    if (JSON.stringify(next) !== JSON.stringify(proof[key])) changed.push(path);
+    proof[key] = next;
+  };
+  await list('high', 'High-risk paths (comma list of globs)', 'proof.tiers.high.paths');
+  if (origins.proof.isolation !== 'flag') {
+    const next = await answer(ui, ui.select({
+      message: withHint('Proof isolation', SETTING_HINTS.isolation),
+      options: [{ value: 'export' }, { value: 'lock' }],
+      initialValue: proof.isolation,
+    }));
+    if (next !== proof.isolation) changed.push('proof.isolation');
+    proof.isolation = next;
   }
-  return values;
+  await list('link_dirs', 'Export: directories to link', 'proof.export.link_dirs');
+  await list('copy_untracked', 'Export: untracked files to copy', 'proof.export.copy_untracked');
+  return changed;
 }
 
 /**
@@ -171,9 +271,9 @@ export async function askAnswers(values, sources, ctx, ui) {
  */
 export async function askJevSource(ui, getStore) {
   const choice = await answer(ui, ui.select({
-    message: 'Where is the Jev key?',
+    message: withHint('Where is the Jev key?', HINTS.jev),
     options: [
-      { value: 'op', label: '1Password reference' },
+      { value: 'op', label: '1Password reference', hint: OP_REF_HINT },
       { value: 'env', label: 'environment variable name' },
       { value: 'paste', label: 'paste now (hidden)' },
       { value: 'skip', label: 'skip (rules-only System 1)' },
@@ -181,17 +281,17 @@ export async function askJevSource(ui, getStore) {
     initialValue: 'skip',
   }));
   if (choice === 'op') {
-    const ref = String(await answer(ui, ui.text({ message: '1Password reference (op://vault/item/field)' }))).trim();
+    const ref = String(await answer(ui, ui.text({ message: withHint('1Password reference (op://vault/item/field)', OP_REF_HINT) }))).trim();
     if (!isOpRef(ref)) throw new UsageError('not an op://vault/item/field reference');
     return { ref, source: 'op' };
   }
   if (choice === 'env') {
-    const name = String(await answer(ui, ui.text({ message: 'Environment variable name' }))).trim();
+    const name = String(await answer(ui, ui.text({ message: withHint('Environment variable name', HINTS.env) }))).trim();
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new UsageError('not an environment variable name');
     return { ref: `env:${name}`, source: 'env' };
   }
   if (choice === 'paste') {
-    const typed = await answer(ui, ui.password({ message: 'Jev key (input hidden)' }));
+    const typed = await answer(ui, ui.password({ message: withHint('Jev key (input hidden)', HINTS.paste) }));
     if (typeof typed !== 'string' || typed.length === 0) return { ref: null, source: 'none' };
     const store = await getStore();
     await store.put('jev', typed, { source: 'user', exp: null });