@golden-frijoles/kit 0.3.0 → 0.5.0

package/dist/config.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// config.mjs — `gf-kit config`: read and change golden-frijoles.config.json (golden-frijoles-plugin S4.1, D10).
+//
+//   gf-kit config list [--json]            every section's effective value, where it came from, any duplicates
+//   gf-kit config get <key> [--json]       one key's effective value (or its registry default)
+//   gf-kit config set <key> <value>        write one key; <value> is parsed as JSON when it is valid JSON
+//   gf-kit config migrate [--dry-run]      fold the legacy files into golden-frijoles.config.json (never edits them)
+//
+// A thin front end: every rule (precedence, the secret guard, what migrate folds) lives in lib/config.mjs, which the
+// `gf` CLI imports too. Exit 0 ok · 1 usage · 2 configuration error (a malformed file, a secret, an unknown section).
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILENAME, ConfigError, getKey, loadConfig, migrate, setKey } from './lib/config.mjs';
+
+const USAGE = 'usage: gf-kit config list|get <key>|set <key> <value>|migrate [--dry-run] [--json]';
+
+/** Pure — a CLI value: JSON when it parses (true, 3, ["a"], null), otherwise the literal string. */
+export function parseValue(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export function main(argv, { out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s) } = {}) {
+  const json = argv.includes('--json');
+  const args = argv.filter((a) => a !== '--json' && a !== '--dry-run');
+  const [verb, key, ...rest] = args;
+  try {
+    if (verb === 'list') {
+      const c = loadConfig();
+      if (json) return out(`${JSON.stringify(c, null, 2)}\n`), 0;
+      const names = Object.keys(c.sections);
+      if (!names.length) out(`No settings yet: no ${CONFIG_FILENAME} and no legacy config files.\n`);
+      for (const name of names) {
+        out(`${name}  (${c.sources[name].map((s) => s.split('/').pop()).join(' + ')})\n`);
+        out(`${JSON.stringify(c.sections[name], null, 2).replace(/^/gm, '  ')}\n`);
+      }
+      if (c.duplicates.length) out(`\nset in both the new file and a legacy file (the new file wins): ${c.duplicates.join(', ')}\n`);
+      return 0;
+    }
+    if (verb === 'get' && key) {
+      const value = getKey(key);
+      out(json ? `${JSON.stringify({ key, value })}\n` : `${typeof value === 'string' ? value : JSON.stringify(value)}\n`);
+      return 0;
+    }
+    if (verb === 'set' && key && rest.length) {
+      setKey(key, parseValue(rest.join(' ')));
+      out(json ? `${JSON.stringify({ key, value: getKey(key) })}\n` : `${key} = ${JSON.stringify(getKey(key))}\n`);
+      return 0;
+    }
+    if (verb === 'migrate') {
+      const dryRun = argv.includes('--dry-run');
+      const r = migrate({ dryRun });
+      if (json) return out(`${JSON.stringify({ dryRun, ...r }, null, 2)}\n`), 0;
+      if (!r.folded.length) out('Nothing to migrate: no legacy settings the new file does not already have.\n');
+      else if (dryRun) out(`Would write ${CONFIG_FILENAME}:\n${JSON.stringify(r.config, null, 2)}\n`);
+      else out(`Wrote ${CONFIG_FILENAME} (${r.folded.length} setting(s) folded; the legacy files are untouched).\n`);
+      if (r.skipped.length) out(`Skipped (look like secrets; keep them in .env.local): ${r.skipped.join(', ')}\n`);
+      return 0;
+    }
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      err(`gf-kit config: ${e.message}\n`);
+      return 2;
+    }
+    throw e;
+  }
+  err(`${USAGE}\n`);
+  return 1;
+}
+
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) process.exitCode = main(process.argv.slice(2));

package/dist/lib/config-registry.mjs

@@ -0,0 +1,145 @@
+// config-registry.mjs — every setting Golden Frijoles can ask for, in one table (golden-frijoles-plugin S4.3, D11).
+//
+// This is the audit §4.3 table as data. Setup reads it for its questions, a script reads it before asking
+// just-in-time (lib/config.mjs `needSetting`), and `gf doctor` reads it to say which modules are configured. A new
+// setting is a new row here, never a question hard-coded in a skill.
+//
+//   key       dotted, `<section>.<name>`: the path in golden-frijoles.config.json
+//   module    the product module doctor groups it under (Plan · Build · Ship · Measure · Spend · Operate)
+//   askWhen   'setup' | 'first-groom' | 'first-pr' | 'first-smoke' | 'first-report' | 'first-prune'
+//             | 'first-high-risk-groom' | 'never-yet' (declared so the schema is ready; nothing reads it this wave)
+//   default   what a skipped question means. `null` = "unanswered", which a rail must treat as its safest choice
+//   question  the plain words an agent asks, once
+//   choices   optional allowed values; `store: 'env'` means the answer lives in .env.local (gf init), never here
+//
+// Zero deps, no imports: config.mjs imports THIS, so it must not import back.
+
+export const REGISTRY = Object.freeze([
+  // ── Setup (golden-frijoles-plugin S5.1: Q1, Q2, Q4 are asked; Q3, Q5 wait for their modules, X18) ──
+  {
+    key: 'project.mode',
+    module: 'Plan',
+    askWhen: 'setup',
+    required: true,
+    default: 'existing',
+    choices: ['existing', 'new', 'planning-only'],
+    question: 'What are we working on: an existing repo (adds Roadmap/, keeps everything else), a new project, or planning only (no repo changes)?',
+  },
+  {
+    key: 'project.startPoint',
+    module: 'Plan',
+    askWhen: 'setup',
+    default: 'idea',
+    choices: ['idea', 'plan', 'building'],
+    question: 'Where are you starting: an idea, you know what to build, or you are already building?',
+  },
+  {
+    key: 'project.account',
+    module: 'Ship',
+    askWhen: 'setup',
+    default: 'later',
+    choices: ['later', 'now'],
+    store: 'env',
+    question: 'Connect a Golden Frijoles account now (gf login + gf init), or later?',
+  },
+  {
+    key: 'board.sink',
+    module: 'Plan',
+    askWhen: 'never-yet',
+    default: 'terminal',
+    choices: ['terminal', 'golden-frijoles', 'notion'],
+    question: 'Where should the board live?',
+  },
+  {
+    key: 'verify.depth',
+    module: 'Build',
+    askWhen: 'never-yet',
+    default: 'light',
+    choices: ['off', 'light', 'standard', 'deep'],
+    question: 'How much proof do you want on risky stories?',
+  },
+  // ── Just in time ──
+  {
+    key: 'roadmap.areas',
+    module: 'Plan',
+    askWhen: 'first-groom',
+    default: ['09 Platform & Infra'],
+    question: 'Which areas (macro-sections) does this roadmap have? 09 Platform & Infra is reserved.',
+  },
+  {
+    key: 'ways.fillIns',
+    module: 'Plan',
+    askWhen: 'first-groom',
+    default: 'Roadmap/fill-ins.yml',
+    question: 'Where are this project\'s WAYS-OF-WORKING fill-ins?',
+  },
+  {
+    key: 'review.families',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: ['claude'],
+    question: 'Which reviewer CLIs do you have (codex, agy, vibe, claude)?',
+  },
+  {
+    key: 'review.reviewScope',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: 'security-paths-only',
+    choices: ['every-pr', 'security-paths-only'],
+    question: 'Review every PR, or only PRs that touch security paths?',
+  },
+  {
+    key: 'review.securityPaths',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: null,
+    question: 'Which paths are security-sensitive (globs)? Skipping keeps the template\'s list.',
+  },
+  {
+    key: 'jev.egress',
+    module: 'Build',
+    askWhen: 'first-pr',
+    default: null,
+    choices: [true, false],
+    question: 'Send PR review text and report drafts to TypeSafe (Jev) to judge their quality? Nothing is sent until you say yes.',
+  },
+  {
+    // NOT `smoke.envs`: that is live-smoke's own {name: url} map, and a list saved there broke it (review of #49).
+    key: 'smoke.defaultEnv',
+    module: 'Build',
+    askWhen: 'first-smoke',
+    default: 'local',
+    question: 'Which environment should live-smoke check when you don\'t name one (local, preview, production)?',
+  },
+  {
+    key: 'reporting.destination',
+    module: 'Operate',
+    askWhen: 'first-report',
+    default: null,
+    question: 'Where should standups and recaps go (Telegram, Slack, or print to the terminal)? Secrets stay in .env.local.',
+  },
+  {
+    key: 'deploy.vercelProject',
+    module: 'Operate',
+    askWhen: 'first-prune',
+    default: null,
+    question: 'Which Vercel project should stale previews be counted for?',
+  },
+  {
+    key: 'ship.killSwitchPolicy',
+    module: 'Ship',
+    askWhen: 'first-high-risk-groom',
+    default: 'every-risk-high-story-names-its-flag',
+    question: 'Should every risk:high story name its kill-switch flag?',
+  },
+  {
+    key: 'spend.telemetry',
+    module: 'Spend',
+    askWhen: 'never-yet',
+    default: 'off',
+    choices: ['off', 'on'],
+    question: 'Export cost telemetry?',
+  },
+]);
+
+export const MODULES = Object.freeze(['Plan', 'Build', 'Ship', 'Measure', 'Spend', 'Operate']);

package/dist/lib/config.d.mts

@@ -0,0 +1,73 @@
+// Types for lib/config.mjs, the one config core (golden-frijoles-plugin D10). Shipped in @golden-frijoles/kit as
+// `@golden-frijoles/kit/config` so the TypeScript `gf` CLI imports the same rules instead of re-implementing them.
+
+export declare const CONFIG_FILENAME: 'golden-frijoles.config.json';
+export declare const SECTIONS: readonly string[];
+export declare const LEGACY: Readonly<Record<string, string>>;
+export declare const NEEDS_SETTING: 'GF-NEEDS-SETTING';
+export declare const EXIT_NEEDS_SETTING: 7;
+
+export declare class ConfigError extends Error {}
+
+export interface IoOptions {
+  root?: string;
+  read?: (path: string, encoding: 'utf8') => string;
+  exists?: (path: string) => boolean;
+}
+
+export interface Section {
+  raw: Record<string, unknown> | null;
+  /** True when either file has the section, even when its value is `null` in the legacy file. */
+  present: boolean;
+  sources: string[];
+  duplicates: string[];
+}
+
+/** The project root: GF_PROJECT_ROOT, else (installed) the nearest ancestor of `cwd` with Roadmap/ or .git, else `cwd`. */
+export declare function projectRoot(opts?: { env?: Record<string, string | undefined>; cwd?: string }): string;
+export declare function readConfigFile(opts?: IoOptions): Record<string, unknown> | null;
+export declare function readSection(
+  name: string,
+  opts?: IoOptions & {
+    legacyPath?: string;
+    onLegacyError?: (path: string, error: Error) => never;
+    legacyRead?: IoOptions['read'];
+    legacyExists?: IoOptions['exists'];
+  }
+): Section;
+export declare function loadConfig(opts?: IoOptions): {
+  sections: Record<string, Record<string, unknown>>;
+  sources: Record<string, string[]>;
+  duplicates: string[];
+  /** Top-level keys of golden-frijoles.config.json that are not a known section (ignored on read). */
+  unknown: string[];
+};
+export declare function getKey(key: string, opts?: IoOptions): unknown;
+export declare function setKey(
+  key: string,
+  value: unknown,
+  opts?: IoOptions & { write?: (path: string, obj: unknown) => void }
+): Record<string, unknown>;
+export declare function migrate(
+  opts?: IoOptions & { write?: (path: string, obj: unknown) => void; dryRun?: boolean }
+): { config: Record<string, unknown>; folded: string[]; skipped: string[] };
+export declare function looksLikeSecret(key: string, value: unknown): boolean;
+export declare function needsSettingLine(entry: { key: string; question: string; default: unknown }): string;
+export declare function needSetting(
+  key: string,
+  opts?: IoOptions & { blocking?: boolean; write?: (s: string) => void; exit?: (code: number) => void }
+): unknown;
+
+export interface RegistryEntry {
+  key: string;
+  module: 'Plan' | 'Build' | 'Ship' | 'Measure' | 'Spend' | 'Operate';
+  askWhen: string;
+  default: unknown;
+  question: string;
+  required?: boolean;
+  choices?: readonly unknown[];
+  store?: 'env';
+}
+
+export declare const REGISTRY: readonly RegistryEntry[];
+export declare const MODULES: readonly ['Plan', 'Build', 'Ship', 'Measure', 'Spend', 'Operate'];

package/dist/lib/config.mjs

@@ -0,0 +1,384 @@
+// config.mjs — one config file a person can read, and one place that decides where each setting comes from
+// (golden-frijoles-plugin D9, S4.1).
+//
+// `golden-frijoles.config.json` at the project root holds every non-secret setting, one section per module. The
+// seven legacy files keep working: for each section this module merges the legacy file and the new file's section,
+// the NEW FILE WINNING PER TOP-LEVEL KEY, and reports a key set in both as a duplicate (never an error).
+//
+// What this module deliberately does NOT do: validate a section. Every rail already owns a parser that knows its
+// shape and throws its own error (parseJevConfig, validateReportingConfig, live-smoke's validateConfig, …). This
+// only resolves SOURCES and hands the merged raw object to that parser, so a rule lives in one place, not two.
+//
+// Three answers, never two (LEARNINGS): an absent file is a quiet fallback; a present-but-malformed file is a
+// CONFIGURATION failure that names the file; and the rail decides what "no section anywhere" means for it.
+//
+// Secrets never go in this file, only the NAMES of the env vars that hold them. `setKey` refuses a value that looks
+// like a credential.
+//
+// Zero deps. Imported by the kit's `gf-kit config` and, via `@golden-frijoles/kit/config`, by the `gf` CLI (D10).
+
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { projectRoot } from './project-root.mjs';
+import { REGISTRY } from './config-registry.mjs';
+
+// One import for every front end (D10): the CLI's doctor and setup read the registry through this module too.
+export { REGISTRY, MODULES } from './config-registry.mjs';
+// The project root this core reads and writes under, exported so the `gf` CLI resolves the SAME directory (D10).
+export { projectRoot } from './project-root.mjs';
+
+export const CONFIG_FILENAME = 'golden-frijoles.config.json';
+
+export const SECTIONS = Object.freeze([
+  'project',
+  'board',
+  'verify',
+  'roadmap',
+  'ways',
+  'review',
+  'jev',
+  'smoke',
+  'reporting',
+  'deploy',
+  'ship',
+  'spend',
+]);
+
+/**
+ * The ONE table of legacy sources: section (or a dotted sub-section) → the file it used to live in, relative to the
+ * project root. A rail whose legacy path is computed (reporting's `REPORTING_CONFIG`) passes `legacyPath` instead.
+ * `ways` has no legacy file: its setting IS a path, `fillIns`, defaulting to the prose file that stays (X15).
+ */
+export const LEGACY = Object.freeze({
+  jev: 'jev.config.json',
+  reporting: 'reporting.config.json',
+  smoke: 'live-smoke.config.json',
+  'smoke.triage': 'smoke-triage.config.json',
+  'smoke.perf': 'perf-probe.config.json',
+  review: 'scripts/review-config.json',
+});
+
+/** The legacy file for a section, absolute. The one place REPORTING_CONFIG is honoured, for every caller. */
+export function legacyPathFor(name, { root = projectRoot(), env = process.env } = {}) {
+  if (name === 'reporting' && env.REPORTING_CONFIG) return resolve(root, env.REPORTING_CONFIG);
+  return LEGACY[name] ? resolve(root, LEGACY[name]) : null;
+}
+
+/** Sub-sections carved out of a parent: reading `smoke` for live-smoke must not hand it the triage/perf policies. */
+const CARVED = Object.freeze({ smoke: ['triage', 'perf'] });
+
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function parseJsonFile(path, { read, onError }) {
+  let text;
+  try {
+    text = read(path, 'utf8');
+  } catch (e) {
+    return onError(path, e);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    return onError(path, e);
+  }
+}
+
+const configFail = (path, e) => {
+  throw new ConfigError(`${path}: not valid JSON (${e.message})`);
+};
+
+/**
+ * A config file on the real filesystem must RESOLVE inside the project. `config list` prints what it reads, so a
+ * checkout whose golden-frijoles.config.json (or a legacy file) is a symlink to ~/.npmrc or a cloud credentials file
+ * would otherwise print or migrate that file (security lens on #49). Injected IO (tests) is not a filesystem: skipped.
+ */
+function assertContained(path, root, read) {
+  if (read !== readFileSync) return;
+  const realRoot = realpathSync(root);
+  const real = realpathSync(path);
+  if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+    throw new ConfigError(`${path} resolves outside the project (${real}); refusing to read it.`);
+  }
+}
+
+/** The project's `golden-frijoles.config.json`, parsed; `null` when absent. Malformed → ConfigError. */
+export function readConfigFile({ root = projectRoot(), read = readFileSync, exists = existsSync } = {}) {
+  const path = join(root, CONFIG_FILENAME);
+  if (!exists(path)) return null;
+  assertContained(path, root, read);
+  const json = parseJsonFile(path, { read, onError: configFail });
+  if (!isObject(json)) throw new ConfigError(`${path}: must be a JSON object of sections`);
+  // An unknown section is IGNORED here, never thrown: a file written by a newer kit or CLI must not break the
+  // older rails a consumer copied. `loadConfig` reports it, and `setKey` refuses to write one (typos on write).
+  return json;
+}
+
+/** Pure — sections a config object names that this version doesn't know. */
+export function unknownSections(json) {
+  return Object.keys(json ?? {}).filter((k) => !k.startsWith('$') && !SECTIONS.includes(k));
+}
+
+/** Walk a dotted path into an object; undefined when any step is missing. */
+function dig(obj, dotted) {
+  let cur = obj;
+  for (const part of dotted.split('.')) {
+    if (!isObject(cur) || !(part in cur)) return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+/**
+ * One section, merged. `name` may be dotted (`smoke.triage`).
+ *
+ * Returns `{ raw, sources, duplicates }`: `raw` is `null` when neither the new file nor the legacy file has it (the
+ * rail decides what that means), otherwise the legacy object with the new file's top-level keys laid over it.
+ *
+ * `legacyPath` overrides the table (absolute, or relative to the root). `onLegacyError(path, error)` lets a rail keep
+ * throwing ITS OWN error for an unparseable legacy file, so a legacy-only repo behaves byte-identically.
+ */
+export function readSection(
+  name,
+  {
+    root = projectRoot(),
+    read = readFileSync,
+    exists = existsSync,
+    legacyPath,
+    env = process.env,
+    onLegacyError = configFail,
+    // A rail's injected IO has always meant "my legacy file", and its tests rely on that, so it answers ONLY for
+    // the legacy file. The new file is looked up with `read`/`exists` (the real filesystem unless a test injects
+    // those too).
+    legacyRead = read,
+    legacyExists = exists,
+  } = {}
+) {
+  const file = readConfigFile({ root, read, exists });
+  let fromNew = file ? dig(file, name) : undefined;
+  if (fromNew !== undefined && !isObject(fromNew)) {
+    throw new ConfigError(`${join(root, CONFIG_FILENAME)}: "${name}" must be an object`);
+  }
+  if (fromNew && CARVED[name]) {
+    fromNew = Object.fromEntries(Object.entries(fromNew).filter(([k]) => !CARVED[name].includes(k)));
+  }
+  // `null` in the new file means "unset", never "override the legacy value with null": saving a registry default
+  // of null (jev.egress) must not re-enable something a legacy file had turned off.
+  if (fromNew) fromNew = Object.fromEntries(Object.entries(fromNew).filter(([, v]) => v !== null));
+
+  const legacyAbs = legacyPath ? resolve(root, legacyPath) : legacyPathFor(name, { root, env });
+  let fromLegacy;
+  if (legacyAbs && legacyExists(legacyAbs)) {
+    // REPORTING_CONFIG is the operator's env, not the checkout's: it may name a file anywhere.
+    if (!(name === 'reporting' && env.REPORTING_CONFIG && !legacyPath)) assertContained(legacyAbs, root, legacyRead);
+    fromLegacy = parseJsonFile(legacyAbs, { read: legacyRead, onError: onLegacyError });
+  }
+
+  const sources = [];
+  if (fromLegacy !== undefined) sources.push(legacyAbs);
+  if (fromNew !== undefined) sources.push(join(root, CONFIG_FILENAME));
+  // `present` is the rail's absence test, never `raw === null`: a legacy file holding JSON null is PRESENT and
+  // malformed, and must reach the rail's own parser (which throws), not fall back to defaults.
+  if (fromLegacy === undefined && fromNew === undefined) return { raw: null, present: false, sources, duplicates: [] };
+  if (fromNew === undefined) return { raw: fromLegacy, present: true, sources, duplicates: [] };
+  if (fromLegacy === undefined) return { raw: { ...fromNew }, present: true, sources, duplicates: [] };
+  // A legacy file that isn't an object is the rail's parser's error to report, even when the new file has keys.
+  if (!isObject(fromLegacy)) return { raw: fromLegacy, present: true, sources, duplicates: [] };
+  const duplicates = Object.keys(fromNew).filter((k) => k in fromLegacy && !k.startsWith('$'));
+  return { raw: { ...fromLegacy, ...fromNew }, present: true, sources, duplicates };
+}
+
+/** Every section's effective value, for `list`/`doctor`. Never throws for an absent file. */
+export function loadConfig({ root = projectRoot(), read = readFileSync, exists = existsSync } = {}) {
+  const sections = {};
+  const sources = {};
+  const duplicates = [];
+  const unknown = unknownSections(readConfigFile({ root, read, exists }));
+  for (const name of [...SECTIONS, ...Object.keys(LEGACY).filter((k) => k.includes('.'))]) {
+    const r = readSection(name, { root, read, exists });
+    if (r.raw === null) continue;
+    sections[name] = r.raw;
+    sources[name] = r.sources;
+    for (const k of r.duplicates) duplicates.push(`${name}.${k}`);
+  }
+  return { sections, sources, duplicates, unknown };
+}
+
+/** The effective value of a dotted key (`review.reviewScope`), falling back to the registry default. */
+export function getKey(key, opts = {}) {
+  const [head, ...rest] = key.split('.');
+  // A dotted sub-section with its own legacy file (smoke.triage.*) is resolved as that sub-section.
+  const sub = rest.length && LEGACY[`${head}.${rest[0]}`] ? `${head}.${rest.shift()}` : head;
+  const { raw } = readSection(sub, opts);
+  const value = rest.length ? dig(raw ?? {}, rest.join('.')) : raw ?? undefined;
+  if (value !== undefined) return value;
+  const reg = REGISTRY.find((r) => r.key === key);
+  return reg ? reg.default : undefined;
+}
+
+// ── Writing ─────────────────────────────────────────────────────────────────────────────────────
+
+const TOKEN_PREFIXES = /^(sk-|sk_|ghp_|gho_|ghs_|github_pat_|xox[abpr]-|AKIA|eyJ|npm_|glpat-|tsk_|gf_pat_)/;
+// A URL carrying a password in its userinfo (postgres://user:pass@host/db).
+const URL_WITH_PASSWORD = /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i;
+const TELEGRAM_BOT_TOKEN = /^\d{6,}:[A-Za-z0-9_-]{30,}$/;
+const SLACK_WEBHOOK = /^https:\/\/hooks\.slack\.com\//;
+const SECRET_KEY = /(token|secret|password|apikey|api_key|privatekey|webhook)$/i;
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Pure — does this key/value pair look like a credential rather than the NAME of an env var? A token prefix only
+ * counts on a value long enough to be a token (`sk-shop` or `npm_utils` is a name, not a key).
+ */
+export function looksLikeSecret(key, value) {
+  if (typeof value !== 'string') return false;
+  if (TOKEN_PREFIXES.test(value) && value.length >= 20) return true;
+  if (TELEGRAM_BOT_TOKEN.test(value) || SLACK_WEBHOOK.test(value) || URL_WITH_PASSWORD.test(value)) return true;
+  const leaf = key.split('.').pop();
+  return SECRET_KEY.test(leaf) && !ENV_NAME.test(value);
+}
+
+/** Pure — every dotted path under `key` whose value looks like a secret, walking nested objects and arrays. */
+export function findSecrets(key, value) {
+  if (Array.isArray(value)) return value.flatMap((v, i) => findSecrets(`${key}.${i}`, v));
+  if (isObject(value)) return Object.entries(value).flatMap(([k, v]) => findSecrets(`${key}.${k}`, v));
+  return looksLikeSecret(key, value) ? [key] : [];
+}
+
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function writeAtomic(path, obj) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(obj, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Set a dotted key in the project's config file (created if absent). The first segment must be a known section.
+ * A value that looks like a credential is refused: put the env var's NAME here, never its value.
+ */
+export function setKey(key, value, { root = projectRoot(), read = readFileSync, exists = existsSync, write = writeAtomic } = {}) {
+  const parts = key.split('.');
+  if (parts.length < 2 || !SECTIONS.includes(parts[0])) {
+    throw new ConfigError(`"${key}": a key is <section>.<name>, with section one of ${SECTIONS.join(', ')}`);
+  }
+  if (parts.some((p) => FORBIDDEN_SEGMENTS.has(p) || p === '')) throw new ConfigError(`"${key}": not a valid key`);
+  const secrets = findSecrets(key, value);
+  if (secrets.length) {
+    throw new ConfigError(
+      `"${secrets[0]}" looks like a secret. Secrets never go in ${CONFIG_FILENAME}: keep the value in .env.local ` +
+        'and put the env var NAME here (e.g. "TYPESAFE_API_KEY").'
+    );
+  }
+  const file = readConfigFile({ root, read, exists }) ?? {};
+  // A write deeper than <section>.<name> must not WIPE the legacy siblings of what it changes: the new file's
+  // top-level key replaces the legacy one wholesale (D9), so seed it from the effective merged value first.
+  if (parts.length > 2) {
+    const [section, top] = parts;
+    const own = file[section]?.[top];
+    if (own === undefined) {
+      const effective = readSection(section, { root, read, exists }).raw?.[top];
+      if (isObject(effective)) {
+        file[section] = isObject(file[section]) ? file[section] : {};
+        file[section][top] = structuredClone(effective);
+      }
+    }
+  }
+  let cur = file;
+  for (const part of parts.slice(0, -1)) {
+    if (!isObject(cur[part])) cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts.at(-1)] = value;
+  write(join(root, CONFIG_FILENAME), file);
+  return file;
+}
+
+/**
+ * Fold every legacy file into the new file's sections (new file wins per key). Legacy files are NEVER touched —
+ * they keep working as fallbacks. Keys that look like secrets are skipped and reported, never copied.
+ * Returns `{ config, folded, skipped }`; `dryRun` writes nothing.
+ */
+export function migrate({
+  root = projectRoot(),
+  read = readFileSync,
+  exists = existsSync,
+  write = writeAtomic,
+  env = process.env,
+  dryRun = false,
+} = {}) {
+  const config = readConfigFile({ root, read, exists }) ?? {};
+  const folded = [];
+  const skipped = [];
+  for (const name of Object.keys(LEGACY)) {
+    const abs = legacyPathFor(name, { root, env });
+    if (!exists(abs)) continue;
+    if (!(name === 'reporting' && env.REPORTING_CONFIG)) assertContained(abs, root, read);
+    const legacy = parseJsonFile(abs, { read, onError: configFail });
+    if (!isObject(legacy)) continue;
+    const [head, sub] = name.split('.');
+    config[head] = isObject(config[head]) ? config[head] : {};
+    const target = sub ? (config[head][sub] = isObject(config[head][sub]) ? config[head][sub] : {}) : config[head];
+    for (const [k, v] of Object.entries(legacy)) {
+      if (k.startsWith('$') || k.startsWith('_')) continue; // comments/notes stay with the legacy file
+      if (k in target) continue; // the new file wins
+      const secrets = findSecrets(`${name}.${k}`, v);
+      if (secrets.length) {
+        skipped.push(...secrets); // the whole key stays behind: a partial copy of a credentials block helps nobody
+        continue;
+      }
+      target[k] = v;
+      folded.push(`${name}.${k}`);
+    }
+  }
+  for (const head of Object.keys(config)) if (isObject(config[head]) && !Object.keys(config[head]).length) delete config[head];
+  if (!dryRun && folded.length) write(join(root, CONFIG_FILENAME), config);
+  return { config, folded, skipped };
+}
+
+// ── The ask protocol (D11) ──────────────────────────────────────────────────────────────────────
+
+export const NEEDS_SETTING = 'GF-NEEDS-SETTING';
+export const EXIT_NEEDS_SETTING = 7;
+
+/** Pure — the one stderr line an agent looks for. */
+export function needsSettingLine(entry) {
+  return `${NEEDS_SETTING} ${JSON.stringify({ key: entry.key, question: entry.question, default: entry.default })}`;
+}
+
+/**
+ * A script needs a registered setting that is unset. Prints the protocol line once per process. `blocking` exits 7
+ * (the script cannot continue without an answer); otherwise it returns the registry default and carries on.
+ * A set key returns its value and prints nothing.
+ */
+const asked = new Set();
+export function needSetting(
+  key,
+  { blocking = false, root = projectRoot(), read = readFileSync, exists = existsSync, write = (s) => process.stderr.write(s), exit = process.exit } = {}
+) {
+  const entry = REGISTRY.find((r) => r.key === key);
+  if (!entry) throw new ConfigError(`needSetting("${key}"): not in the registry (lib/config-registry.mjs)`);
+  const [head, ...rest] = key.split('.');
+  const { raw } = readSection(head, { root, read, exists });
+  const value = rest.length ? dig(raw ?? {}, rest.join('.')) : raw;
+  const isSet = value !== undefined && value !== null;
+  if (isSet) return value;
+  if (!asked.has(key)) {
+    asked.add(key);
+    write(`${needsSettingLine(entry)}\n`);
+  }
+  if (blocking) exit(EXIT_NEEDS_SETTING);
+  return entry.default;
+}
+
+/** Test seam: forget which keys this process already asked about. */
+export function _resetAsked() {
+  asked.clear();
+}
+

package/dist/lib/jev.mjs

@@ -14,6 +14,13 @@
 //   3. ONE COMMITTED SWITCH. `jev.config.json → rails.<rail>.mode: off | shadow | jev`. A missing file is
 //      the defaults (everything off); a MALFORMED file throws, so a typo never silently means "off".
 //      `egress:false` or no key makes the effective mode `off`, with the reason.
+//   4. EGRESS IS A TRI-STATE, AND UNANSWERED BEHAVES AS NO (golden-frijoles-plugin D12, S5.4). `egress`
+//      is `true | false | null`. The template ships `null`: a stranger's diffs never leave their machine
+//      until they say so. `null` and `false` both make the effective mode `off`; `null` ADDITIONALLY
+//      emits the D11 ask (`needSetting('jev.egress', { blocking: false })`) once per process, so an agent
+//      asks the question instead of the guard silently staying off forever. The fallback reason for `null`
+//      is `egress not answered`: `review-guard.mjs` wraps it into the reason `jev could not look (egress not
+//      answered)`, and `prose-guard.mjs`'s judgeProse returns it as `why`. Existing consumers keep their committed `egress: true`.
 //
 // Zero deps — Node 18+ (global fetch). Everything with I/O takes injectable deps, so specs never touch the
 // network.
@@ -22,6 +29,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { projectRoot } from './project-root.mjs';
+import { needSetting, readSection } from './config.mjs';
 
 export const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 export const DEFAULT_MODEL = 'jev-1.13.0';
@@ -74,8 +82,13 @@ export function parseJevConfig(json) {
     throw new JevConfigError(
       `jev.config.json: model "${model}" is an alias — pin a version such as ${DEFAULT_MODEL}`
     );
-  const egress = json.egress ?? true;
-  if (typeof egress !== 'boolean') throw new JevConfigError('jev.config.json: egress must be true or false');
+  // Tri-state (D12): `true | false | null`. An explicit `null` must survive as `null` — `??` would
+  // silently turn it back into `true`, which is exactly the "unanswered defaults to send" bug this
+  // decision exists to close. Only an ABSENT key falls back to `true` (today's behaviour for a
+  // consumer's committed config that never mentions egress at all).
+  const egress = Object.prototype.hasOwnProperty.call(json, 'egress') ? json.egress : true;
+  if (egress !== true && egress !== false && egress !== null)
+    throw new JevConfigError('jev.config.json: egress must be true, false or null');
   if (json.rails !== undefined && !isObj(json.rails))
     throw new JevConfigError('jev.config.json: rails must be an object');
   const rails = {};
@@ -112,15 +125,25 @@ export function parseJevConfig(json) {
 
 /** Read `<root>/jev.config.json`. Missing ⇒ defaults; unreadable or malformed ⇒ throws. */
 export function loadJevConfig({ root = repoRoot(), read = readFileSync, exists = existsSync } = {}) {
-  const path = join(root, 'jev.config.json');
-  if (!exists(path)) return parseJevConfig({});
-  let json;
-  try {
-    json = JSON.parse(read(path, 'utf8'));
-  } catch (e) {
-    throw new JevConfigError(`jev.config.json: unparseable (${e.message})`);
-  }
-  return parseJevConfig(json);
+  // The `jev` section of golden-frijoles.config.json over the legacy jev.config.json (D9); validation stays here.
+  const { raw, present } = readSection('jev', {
+    root,
+    legacyRead: read,
+    legacyExists: exists,
+    onLegacyError: (_path, e) => {
+      throw new JevConfigError(`jev.config.json: unparseable (${e.message})`);
+    },
+  });
+  // Absent everywhere → the defaults (every rail off). A PRESENT legacy file holding JSON null is malformed: the
+  // parser throws.
+  if (!present) return parseJevConfig({});
+  // D12: a section that never gives egress a non-null value is UNANSWERED, never `true`. readSection treats a
+  // `null` in golden-frijoles.config.json as unset, so without this a new-file `egress: null` (or a migrated
+  // template config) reached parseJevConfig as a MISSING key and became `true` — sending with nobody's yes
+  // (review of the S5 diff). Only parseJevConfig called directly keeps the absent → true fallback.
+  if (raw && typeof raw === 'object' && !Array.isArray(raw) && (raw.egress === undefined || raw.egress === null))
+    return parseJevConfig({ ...raw, egress: null });
+  return parseJevConfig(raw);
 }
 
 /** Parse `KEY=value` lines. Enough for .env.local; quotes stripped. */
@@ -161,7 +184,10 @@ export function readApiKey({
 export function effectiveMode(config, rail, { key } = {}) {
   const configured = config.rails[rail].mode;
   if (configured === 'off') return { mode: 'off', configured, why: 'configured off' };
-  if (!config.egress) return { mode: 'off', configured, why: 'egress disabled in jev.config.json' };
+  // Unanswered (D12): distinct from a deliberate `false` so the caller can ask once instead of
+  // staying silently off forever. `unanswered: true` is jevContext's cue to fire the D11 protocol.
+  if (config.egress === null) return { mode: 'off', configured, why: 'egress not answered', unanswered: true };
+  if (!config.egress) return { mode: 'off', configured, why: 'egress disabled (jev.egress: false)' };
   if (!key) return { mode: 'off', configured, why: 'no TYPESAFE_API_KEY' };
   return { mode: configured, configured, why: `configured ${configured}` };
 }
@@ -322,6 +348,18 @@ export function jevContext(rail, deps = {}) {
   const config = deps.config ?? loadJevConfig({ root });
   const key = 'key' in deps ? deps.key : readApiKey({ root });
   const eff = effectiveMode(config, rail, { key });
+  // D11's ask protocol, fired exactly once (needSetting's own dedup): egress was never answered, so
+  // tell the agent to ask instead of leaving the guard silently off forever. Non-blocking — a judge
+  // still returns a decision this run, via the regex fallback the caller already has for `mode:'off'`.
+  if (eff.unanswered) {
+    (deps.needSetting ?? needSetting)('jev.egress', {
+      blocking: false,
+      root,
+      ...(deps.read ? { read: deps.read } : {}),
+      ...(deps.exists ? { exists: deps.exists } : {}),
+      ...(deps.write ? { write: deps.write } : {}),
+    });
+  }
   return {
     root,
     config,

package/dist/lib/project-root.mjs

@@ -23,8 +23,8 @@
 // `--root <dir>` is parsed by kit/bin.mjs only, which exports it as GF_PROJECT_ROOT — no script's own argument
 // parser ever sees a new flag. Zero deps; no side effects at import.
 
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const KIT_PACKAGE_NAME = '@golden-frijoles/kit';
@@ -72,7 +72,27 @@ export function projectRoot({
 }
 
 /** A project-owned file with a kit default: the project's `scripts/<rel>` if present, else the kit's `<rel>`. */
-export function projectAsset(rel, { project = projectRoot(), root = kitRoot(), exists = existsSync } = {}) {
+export class ProjectAssetError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ProjectAssetError';
+  }
+}
+
+export function projectAsset(
+  rel,
+  { project = projectRoot(), root = kitRoot(), exists = existsSync, real = realpathSync } = {}
+) {
   const own = join(project, 'scripts', rel);
-  return exists(own) ? own : join(root, rel);
+  if (!exists(own)) return join(root, rel);
+  // A project-owned asset is read into prompts some rails send to an external model, so it must be the project's
+  // own file. A symlink that leaves the project (to .env.local's neighbours, ~/.ssh, …) is refused loudly: it is
+  // a configuration problem a person has to look at, never something to follow (golden-frijoles-plugin X20).
+  const realOwn = real(own);
+  const realProject = real(project);
+  if (realOwn !== realProject && !realOwn.startsWith(realProject + sep)) {
+    throw new ProjectAssetError(`${own} resolves outside the project (${realOwn}); refusing to read it.`);
+  }
+  // The REAL path, already checked: returning the symlink would let it be swapped between this check and the read.
+  return realOwn;
 }

package/dist/lib/prose-brief.mjs

@@ -24,10 +24,10 @@
 // report with the adjectives swapped.
 
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { loadPromptBody } from './cross-agent-cli.mjs';
 import { loadLessons, buildWriterPrompt } from './prose-writer.mjs';
-import { projectAsset } from './project-root.mjs';
+import { kitRoot, projectAsset, projectRoot } from './project-root.mjs';
 
 /**
  * Read a sprint doc's `**Status:**` line. Pure-ish (single read), used to describe sprint movement in
@@ -134,8 +134,14 @@ export function buildQuietBrief(windowLabel) {
 /** Load the shared persona + a per-surface task file. */
 export function loadPersonaAndTask(scriptsDir, surface) {
   return [
-    // The persona is a TEMPLATE FILL-IN the project owns (D2); the task file is the kit's.
-    loadPromptBody(projectAsset('prose/cpo-persona.md', { root: scriptsDir })),
+    // The persona is a TEMPLATE FILL-IN the project owns (D2); the task file is the kit's. An explicit scriptsDir that
+    // isn't this set's own names its project directly (golden-frijoles-plugin X20): a fixture gets ITS persona.
+    loadPromptBody(
+      projectAsset('prose/cpo-persona.md', {
+        root: scriptsDir,
+        project: resolve(scriptsDir) === kitRoot() ? projectRoot() : dirname(resolve(scriptsDir)),
+      })
+    ),
     loadPromptBody(join(scriptsDir, 'prose', `${surface}.task.md`)),
   ].join('\n\n');
 }

package/dist/lib/prose-guard.mjs

@@ -707,7 +707,9 @@ export async function judgeProse(draft, evidence = {}, deps = {}) {
   const units = proseUnits(draft);
   const questions = proseQuestions(units, evidence);
   if (ctx.mode === 'off' || !questions.length || !String(draft ?? '').trim()) {
-    return { ...regex, decider: 'regex', mode: ctx.mode, regexCodes, jevCodes: null, fallback: [] };
+    // `why` names what kept Jev out (`egress not answered`, `no TYPESAFE_API_KEY`, …), the way the review judge's
+    // reason does, so a regex-decided draft never reads like the configured path.
+    return { ...regex, decider: 'regex', mode: ctx.mode, why: ctx.why, regexCodes, jevCodes: null, fallback: [] };
   }
 
   const chunks = [];

package/dist/lib/reporting-config.mjs

@@ -29,6 +29,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { projectRoot } from './project-root.mjs';
+import { readSection } from './config.mjs';
 
 export const DEFAULT_ROOT = projectRoot(); // D2
 export const CONFIG_FILENAME = 'reporting.config.json';
@@ -219,7 +220,16 @@ export function loadReportingConfig({
   exists = existsSync,
 } = {}) {
   const path = configPath({ root, env });
-  if (!exists(path)) {
+  // The `reporting` section of golden-frijoles.config.json over the legacy file (D9); REPORTING_CONFIG still moves
+  // the legacy file, the local override still layers on top, and validation stays here.
+  const section = readSection('reporting', {
+    root,
+    legacyRead: read,
+    legacyExists: exists,
+    legacyPath: path,
+    onLegacyError: (p, e) => fail(p, `is not valid JSON (${e.message})`),
+  });
+  if (!section.present) {
     throw new ReportingConfigError(
       `${path} not found — the reporting scripts refuse to guess which repos to read or where to post.\n` +
         `  Copy ${EXAMPLE_FILENAME} to ${CONFIG_FILENAME} at the repo root, fill it in, and commit it.`
@@ -232,7 +242,7 @@ export function loadReportingConfig({
       return fail(p, `is not valid JSON (${e.message})`);
     }
   };
-  let raw = parse(path);
+  let raw = section.raw;
   const localPath = join(dirname(path), LOCAL_FILENAME);
   if (exists(localPath)) raw = mergeLocal(raw, parse(localPath));
   return validateReportingConfig(raw, path);

package/dist/live-smoke.mjs

@@ -35,6 +35,7 @@ import { existsSync, readFileSync, rmSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join, isAbsolute, normalize } from 'node:path';
 import { projectRoot } from './lib/project-root.mjs';
+import { readSection } from './lib/config.mjs';
 
 const REPO_ROOT = projectRoot(); // D2
 export const CONFIG_FILENAME = 'live-smoke.config.json';
@@ -209,13 +210,20 @@ export function planRun({ args, config, env = {}, dotenv = {} }) {
 
 export function loadConfig({ root = REPO_ROOT } = {}) {
   const path = join(root, CONFIG_FILENAME);
-  if (!existsSync(path)) {
+  // The `smoke` section of golden-frijoles.config.json over the legacy file (D9); validation stays here.
+  const { raw, present } = readSection('smoke', {
+    root,
+    onLegacyError: (_p, e) => {
+      throw e;
+    },
+  });
+  if (!present) {
     throw new Error(
       `${path} not found — live-smoke refuses to guess which app and which URLs to smoke.\n` +
         `  Copy live-smoke.config.example.json to ${CONFIG_FILENAME}, fill it in, and commit it.`
     );
   }
-  return validateConfig(JSON.parse(readFileSync(path, 'utf8')), path);
+  return validateConfig(raw, path);
 }
 
 function die(message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The scripts the Golden Frijoles skills run, packaged so they work in any repo: planning, build-order, reporting and verification rails. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -29,5 +29,13 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "exports": {
+    ".": "./bin.mjs",
+    "./config": {
+      "types": "./dist/lib/config.d.mts",
+      "default": "./dist/lib/config.mjs"
+    },
+    "./package.json": "./package.json"
   }
 }