@hegemonart/get-design-done 1.39.5 → 1.40.5

package/reference/schemas/generated.d.ts

@@ -101,6 +101,60 @@ export interface DesignConfigJson {
    * Latest plugin tag (e.g. "v1.0.7.3") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears.
    */
   update_dismissed?: string;
+  /**
+   * Phase 40.5 CLI locale override for GDD's own --help, error messages, and skill prompt headers. Set via /gdd:locale <code>. Precedence: this key > env LANG/LC_ALL > en. Missing message keys fall back to English per scripts/lib/i18n/index.cjs (locale -> base -> en). en + ru are complete; uk/de/fr/zh/ja are placeholders that fall back to English.
+   */
+  locale?: 'en' | 'ru' | 'uk' | 'de' | 'fr' | 'zh' | 'ja';
+  /**
+   * Phase 40 sectional handoff. designer = Brief + Explore only; dev = Plan + Design + Verify; full = all stages (default). scripts/lib/collab/cycle-mode.cjs gates STATE writes by stage so a designer and a dev can hand a cycle back and forth without overwriting each other's sections.
+   */
+  gdd_cycle_mode?: 'designer' | 'dev' | 'full';
+  /**
+   * Phase 40 per-section write permissions (scripts/lib/collab/permissions.cjs). Permissive by default (absent = everyone is owner). A team narrows it, e.g. only @lead-designer may lock decisions. A CI gate enforces on PRs.
+   */
+  permissions?: {
+    /**
+     * Role for any actor not listed in `actors`. Default owner.
+     */
+    default?: 'owner' | 'contributor' | 'reviewer' | 'viewer';
+    /**
+     * Per-actor role map (git user/handle -> role).
+     */
+    actors?: {
+      [k: string]: 'owner' | 'contributor' | 'reviewer' | 'viewer';
+    };
+    /**
+     * Restrictive rules: a (section, action) is limited to the listed roles. No matching rule = allowed (permissive).
+     */
+    rules?: {
+      /**
+       * STATE.md section (decisions/prototyping/rollout_status/status/progress/blockers) or '*'.
+       */
+      section?: string;
+      action?: 'write' | 'lock' | 'unlock' | 'approve' | '*';
+      roles?: ('owner' | 'contributor' | 'reviewer' | 'viewer')[];
+      [k: string]: unknown;
+    }[];
+    [k: string]: unknown;
+  };
+  /**
+   * Phase 40 team-collaboration settings.
+   */
+  collab?: {
+    /**
+     * When true, the gdd-state advisory lock uses the team-mode policy (longer wait + backoff) via scripts/lib/collab/lock-policy.cjs. Default false (single-process).
+     */
+    multi_writer_enabled?: boolean;
+    /**
+     * Override the team-mode lock acquire maxWaitMs (default 30000).
+     */
+    lock_timeout_ms?: number;
+    /**
+     * Cross-machine .design/ sync backend (scripts/lib/collab/sync-backend.cjs). Default git (existing push/pull). s3 / git-lfs are opt-in declarations; a live client is not bundled this phase.
+     */
+    sync_backend?: 'git' | 's3' | 'git-lfs';
+    [k: string]: unknown;
+  };
   [k: string]: unknown;
 }
 

package/scripts/lib/collab/attribution.cjs

@@ -0,0 +1,83 @@
+'use strict';
+// Phase 40 — attribution.cjs — PURE, dep-free parser/formatter for multi-author decision attribution.
+//
+// A STATE.md decision line carries an OPTIONAL attribution suffix so multiple developers' decisions
+// survive a merge with provenance intact (SC#5). The canonical line form is:
+//
+//   D-NN: <text> (<status>) [author=<git-user> co-author=<gdd-instance-id>]
+//
+// The suffix is optional and backward-compatible — a plain `D-01: text (locked)` parses with
+// author/coAuthor = null. This module does ONLY string parse/format + grouping; no fs, no clock.
+//
+// No `require` — pure. Deterministic.
+
+const STATUSES = Object.freeze(['locked', 'tentative']);
+
+/**
+ * Parse a single decision line into its parts. Returns null when the line is not a decision line.
+ * @returns {{id, text, status, author, coAuthor} | null}
+ */
+function parseDecisionLine(line) {
+  const s = String(line).trim().replace(/^[-*]\s+/, ''); // tolerate list-bullet prefixes
+  const m = s.match(/^(D-\d+)\s*:\s*(.*)$/);
+  if (!m) return null;
+  const id = m[1];
+  let rest = m[2].trim();
+  let author = null;
+  let coAuthor = null;
+  // Pull a trailing [author=... co-author=...] suffix (order-independent, both optional).
+  const attr = rest.match(/\[([^\]]*)\]\s*$/);
+  if (attr) {
+    const inner = attr[1];
+    const am = inner.match(/\bauthor=([^\s\]]+)/);
+    const cm = inner.match(/\bco-author=([^\s\]]+)/);
+    if (am) author = am[1];
+    if (cm) coAuthor = cm[1];
+    if (am || cm) rest = rest.slice(0, attr.index).trim();
+  }
+  // Pull a trailing (status).
+  let status = null;
+  const st = rest.match(/\(([a-z]+)\)\s*$/i);
+  if (st && STATUSES.includes(st[1].toLowerCase())) {
+    status = st[1].toLowerCase();
+    rest = rest.slice(0, st.index).trim();
+  }
+  return { id, text: rest, status, author, coAuthor };
+}
+
+/** Format a decision object back into the canonical line (omitting absent optional parts). */
+function formatDecisionLine(d) {
+  if (!d || !d.id) throw new Error('attribution: formatDecisionLine needs {id}');
+  let line = `${d.id}: ${String(d.text || '').trim()}`;
+  if (d.status) line += ` (${d.status})`;
+  const bits = [];
+  if (d.author) bits.push(`author=${d.author}`);
+  if (d.coAuthor) bits.push(`co-author=${d.coAuthor}`);
+  if (bits.length) line += ` [${bits.join(' ')}]`;
+  return line;
+}
+
+/** Group an array of decision objects by author → { '<author>': [decision,...], '<unattributed>': [...] }. */
+function groupByAuthor(decisions) {
+  if (!Array.isArray(decisions)) throw new Error('attribution: groupByAuthor needs an array');
+  const out = {};
+  for (const d of decisions) {
+    const key = d && d.author ? d.author : '<unattributed>';
+    (out[key] = out[key] || []).push(d);
+  }
+  return out;
+}
+
+/** Parse a whole `<decisions>` block body into decision objects (skips blanks/comments). */
+function parseDecisionsBlock(body) {
+  const out = [];
+  for (const line of String(body).replace(/\r\n/g, '\n').split('\n')) {
+    const t = line.trim();
+    if (!t || t.startsWith('<!--')) continue;
+    const d = parseDecisionLine(t);
+    if (d) out.push(d);
+  }
+  return out;
+}
+
+module.exports = { STATUSES, parseDecisionLine, formatDecisionLine, groupByAuthor, parseDecisionsBlock };

package/scripts/lib/collab/cycle-mode.cjs

@@ -0,0 +1,41 @@
+'use strict';
+// Phase 40 — cycle-mode.cjs — PURE, dep-free sectional-handoff gate (SC#8).
+//
+// `.design/config.json#gdd_cycle_mode` partitions a cycle by role so a designer can hand a brief to a
+// dev (and vice versa) without either overwriting the other's stages:
+//   designer → Brief, Explore
+//   dev      → Plan, Design, Verify
+//   full     → all stages (the default / current single-operator behavior)
+// `stagePermitted(mode, stage)` gates a STATE write by the stage that produced it.
+//
+// No `require` — pure. Deterministic.
+
+const MODES = Object.freeze(['designer', 'dev', 'full']);
+const ALL_STAGES = Object.freeze(['brief', 'explore', 'plan', 'design', 'verify']);
+
+const STAGES_BY_MODE = Object.freeze({
+  designer: Object.freeze(['brief', 'explore']),
+  dev: Object.freeze(['plan', 'design', 'verify']),
+  full: ALL_STAGES,
+});
+
+/** Normalize a mode value; unknown/missing → 'full' (the safe, backward-compatible default). */
+function normalizeMode(mode) {
+  const m = String(mode || 'full').toLowerCase().trim();
+  return MODES.includes(m) ? m : 'full';
+}
+
+/** Resolve the cycle mode from a parsed `.design/config.json` (defaults to 'full'). */
+function resolveMode(config) {
+  return normalizeMode(config && config.gdd_cycle_mode);
+}
+
+/** True when `stage` is writable under `mode`. Unknown stage → false. */
+function stagePermitted(mode, stage) {
+  const m = normalizeMode(mode);
+  const s = String(stage || '').toLowerCase().trim();
+  if (!ALL_STAGES.includes(s)) return false;
+  return STAGES_BY_MODE[m].includes(s);
+}
+
+module.exports = { MODES, ALL_STAGES, STAGES_BY_MODE, normalizeMode, resolveMode, stagePermitted };

package/scripts/lib/collab/lock-policy.cjs

@@ -0,0 +1,37 @@
+'use strict';
+// Phase 40 — lock-policy.cjs — PURE, dep-free advisory-lock policy for gdd-state multi-writer mode (SC#6).
+//
+// Phase 20's sdk/state/lockfile.ts already implements PID+timestamp advisory locks with retry
+// (staleMs / maxWaitMs / pollMs). "Multi-writer mode" is a POLICY layered on top: when a project
+// enables team mode (`.design/config.json#collab.multi_writer_enabled`), the state write path should
+// wait LONGER and poll on a backoff before giving up, because a teammate's write may be in flight.
+// This module derives the acquire-options object from config; the MCP write path passes it to acquire().
+//
+// No `require` — pure. Deterministic.
+
+// sdk/state/lockfile.ts defaults (single-process baseline).
+const SINGLE = Object.freeze({ staleMs: 60000, maxWaitMs: 5000, pollMs: 50 });
+// Team mode: a stuck teammate write is rare but a normal queued one is not — wait up to 30s,
+// poll slower (100ms) to reduce contention, and treat a lock older than 2min as stale.
+const TEAM = Object.freeze({ staleMs: 120000, maxWaitMs: 30000, pollMs: 100 });
+
+/** True when team multi-writer mode is enabled in config. */
+function isMultiWriter(config) {
+  return !!(config && config.collab && config.collab.multi_writer_enabled === true);
+}
+
+/**
+ * Resolve the acquire() options for the current config. A numeric `collab.lock_timeout_ms`
+ * overrides the team-mode maxWaitMs. Returns a fresh object (never the frozen constants).
+ */
+function acquireOpts(config) {
+  const base = isMultiWriter(config) ? TEAM : SINGLE;
+  const out = { staleMs: base.staleMs, maxWaitMs: base.maxWaitMs, pollMs: base.pollMs };
+  if (isMultiWriter(config)) {
+    const t = Number(config.collab.lock_timeout_ms);
+    if (Number.isFinite(t) && t > 0) out.maxWaitMs = t;
+  }
+  return out;
+}
+
+module.exports = { isMultiWriter, acquireOpts, SINGLE, TEAM };

package/scripts/lib/collab/permissions.cjs

@@ -0,0 +1,53 @@
+'use strict';
+// Phase 40 — permissions.cjs — PURE, dep-free section-write permission model (SC#10).
+//
+// `.design/config.json#permissions` declares who may perform which action on which STATE.md section.
+// The model is permissive-by-default (single-operator projects are unaffected): with no `permissions`
+// block, everyone is an `owner` and `can(...)` is always true. A team narrows it, e.g. "only
+// @lead-designer can `lock` decisions". A CI gate calls `can()` to enforce on PRs.
+//
+// Shape of config.permissions:
+//   {
+//     "default": "owner",                     // role for any actor not listed
+//     "actors": { "@alice": "reviewer", ... },// per-actor role
+//     "rules": [ { "section": "decisions", "action": "lock", "roles": ["owner"] }, ... ]
+//   }
+// A rule restricts (section, action) to the listed roles. No matching rule ⇒ allowed (permissive).
+//
+// No `require` — pure. Deterministic.
+
+const SECTIONS = Object.freeze(['decisions', 'prototyping', 'rollout_status', 'status', 'progress', 'blockers']);
+const ACTIONS = Object.freeze(['write', 'lock', 'unlock', 'approve']);
+const ROLES = Object.freeze(['owner', 'contributor', 'reviewer', 'viewer']);
+
+/** The role assigned to `actor` by the config (falls back to config.default, then 'owner'). */
+function roleOf(config, actor) {
+  const perms = (config && config.permissions) || {};
+  const actors = perms.actors || {};
+  if (actor && Object.prototype.hasOwnProperty.call(actors, actor)) return actors[actor];
+  return perms.default || 'owner';
+}
+
+/**
+ * May `actor` perform `action` on `section` under this config?
+ * Permissive by default: a (section, action) with no matching rule is allowed. A matching rule
+ * allows only its listed roles. `viewer` is denied any mutating action even absent a rule.
+ */
+function can(config, actor, section, action) {
+  const role = roleOf(config, actor);
+  if (role === 'viewer') return false; // viewers never mutate
+  const perms = (config && config.permissions) || {};
+  const rules = Array.isArray(perms.rules) ? perms.rules : [];
+  const matching = rules.filter(
+    (r) => r && (r.section === section || r.section === '*') && (r.action === action || r.action === '*'),
+  );
+  if (matching.length === 0) return true; // no restriction → allowed
+  return matching.some((r) => Array.isArray(r.roles) && r.roles.includes(role));
+}
+
+/** The default permissive policy (used when config has no permissions block). */
+function defaultPolicy() {
+  return { default: 'owner', actors: {}, rules: [] };
+}
+
+module.exports = { SECTIONS, ACTIONS, ROLES, roleOf, can, defaultPolicy };

package/scripts/lib/collab/review-queue.cjs

@@ -0,0 +1,64 @@
+'use strict';
+// Phase 40 — review-queue.cjs — PURE, dep-free async-review state machine for decisions (SC#7).
+//
+// Each decision under review lives at .design/reviews/<decision-id>/ and moves through:
+//   proposed → reviewing → approved → locked
+// `locked` is terminal and HARD: a locked decision cannot be amended. The only way back is an
+// explicit, AUDITED unlock (/gdd:unlock-decision <id> --approver <who>), which records who reopened
+// it and why. This module is the pure transition core — the skill does the filesystem I/O.
+//
+// No `require` — pure. Deterministic.
+
+const STATES = Object.freeze(['proposed', 'reviewing', 'approved', 'locked']);
+
+// Allowed forward transitions per state. `locked` has none (terminal — unlock() is the escape hatch).
+const TRANSITIONS = Object.freeze({
+  proposed: ['reviewing'],
+  reviewing: ['approved', 'proposed'], // can bounce back for revision
+  approved: ['locked', 'reviewing'],
+  locked: [],
+});
+
+/** True while a decision may still be edited (before it is locked). */
+function canAmend(state) {
+  return state === 'proposed' || state === 'reviewing';
+}
+
+/**
+ * Apply a transition. `event` is the TARGET state.
+ * @returns the new state string. Throws on an invalid transition.
+ */
+function transition(state, event) {
+  if (!STATES.includes(state)) throw new Error(`review-queue: unknown state "${state}"`);
+  if (!STATES.includes(event)) throw new Error(`review-queue: unknown target "${event}"`);
+  const allowed = TRANSITIONS[state];
+  if (!allowed.includes(event)) {
+    throw new Error(`review-queue: illegal transition ${state} -> ${event} (allowed: ${allowed.join(', ') || 'none'})`);
+  }
+  return event;
+}
+
+/**
+ * Explicit audited unlock of a locked decision. Moves locked -> reviewing and returns the new entry
+ * with an appended audit record. Requires a non-empty approver. Throws if the entry is not locked.
+ * @param {{id, state, audit?: Array}} entry
+ * @param {{approver: string, reason?: string}} opts
+ */
+function unlock(entry, opts) {
+  if (!entry || entry.state !== 'locked') {
+    throw new Error('review-queue: unlock() requires a locked decision');
+  }
+  const approver = opts && opts.approver ? String(opts.approver).trim() : '';
+  if (!approver) throw new Error('review-queue: unlock() requires an approver');
+  const audit = Array.isArray(entry.audit) ? entry.audit.slice() : [];
+  audit.push({ action: 'unlock', from: 'locked', to: 'reviewing', approver, reason: (opts && opts.reason) || '' });
+  return Object.assign({}, entry, { state: 'reviewing', audit });
+}
+
+/** Filter queue entries that still need a human action (not yet locked). */
+function pending(entries) {
+  if (!Array.isArray(entries)) throw new Error('review-queue: pending() needs an array');
+  return entries.filter((e) => e && e.state !== 'locked');
+}
+
+module.exports = { STATES, TRANSITIONS, canAmend, transition, unlock, pending };

package/scripts/lib/collab/section-merge.cjs

@@ -0,0 +1,77 @@
+'use strict';
+// Phase 40 — section-merge.cjs — PURE, dep-free per-section semantic merge for STATE.md (SC#1).
+//
+// The chosen multi-writer model (ROADMAP default) is a git-merge-driver with PER-SECTION semantic
+// conflict detection — strictly safer than a line-based merge for the append-mostly `<decisions>`
+// block. Two developers each adding a new D-NN on parallel branches should merge cleanly (union by
+// id); a real conflict is ONLY when the SAME id diverges in text or status. This module is the merge
+// core: it takes three decision arrays (base/ours/theirs, already parsed by attribution.cjs) and
+// returns the merged set plus any genuine conflicts for the conflict-resolver agent to resolve.
+//
+// No `require` — pure. Deterministic (stable id-sorted output).
+
+function byId(list) {
+  const m = new Map();
+  for (const d of list || []) if (d && d.id) m.set(d.id, d);
+  return m;
+}
+
+function sameDecision(a, b) {
+  return a.text === b.text && (a.status || null) === (b.status || null) &&
+    (a.author || null) === (b.author || null) && (a.coAuthor || null) === (b.coAuthor || null);
+}
+
+/** Numeric sort by the D-NN id (D-2 before D-10). */
+function idNum(id) {
+  const m = String(id).match(/(\d+)/);
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+/**
+ * Three-way merge of `<decisions>` (base = common ancestor; ours/theirs = the two branches).
+ * @returns {{merged: Decision[], conflicts: [{id, ours, theirs}], added: string[]}}
+ *   - id only in one side (vs base) → kept (union).
+ *   - id in both sides, equal → kept once.
+ *   - id in both sides, divergent → CONFLICT (and `ours` is kept provisionally so the merged set is
+ *     still complete; the resolver overwrites after the human picks).
+ *   - id removed on one side but unchanged on the other → kept (deletions are never auto-applied —
+ *     decisions are durable; an explicit unlock/removal flow handles that).
+ */
+function mergeDecisions(base, ours, theirs) {
+  const B = byId(base);
+  const O = byId(ours);
+  const T = byId(theirs);
+  const ids = new Set([...O.keys(), ...T.keys(), ...B.keys()]);
+  const merged = [];
+  const conflicts = [];
+  const added = [];
+  for (const id of ids) {
+    const o = O.get(id);
+    const t = T.get(id);
+    const b = B.get(id);
+    if (o && t) {
+      if (sameDecision(o, t)) { merged.push(o); }
+      else { conflicts.push({ id, ours: o, theirs: t }); merged.push(o); }
+    } else if (o && !t) {
+      merged.push(o);
+      if (!b) added.push(id); // ours added it
+    } else if (!o && t) {
+      merged.push(t);
+      if (!b) added.push(id); // theirs added it
+    }
+    // (!o && !t) — present only in base, removed on both → drop.
+  }
+  merged.sort((a, x) => idNum(a.id) - idNum(x.id));
+  added.sort((a, x) => idNum(a) - idNum(x));
+  return { merged, conflicts, added };
+}
+
+/** Scalar merge for a single-value section (e.g. status): equal → value; divergent → conflict marker. */
+function mergeStatusScalar(base, ours, theirs) {
+  if (ours === theirs) return { value: ours, conflict: false };
+  if (ours === base) return { value: theirs, conflict: false }; // only theirs changed
+  if (theirs === base) return { value: ours, conflict: false }; // only ours changed
+  return { value: ours, conflict: true }; // both changed differently
+}
+
+module.exports = { mergeDecisions, mergeStatusScalar, sameDecision };

package/scripts/lib/collab/sync-backend.cjs

@@ -0,0 +1,36 @@
+'use strict';
+// Phase 40 — sync-backend.cjs — PURE, dep-free cross-machine sync backend selector (SC#9).
+//
+// `.design/` syncs between teammates over git by DEFAULT (existing behavior). Orgs whose git
+// push/pull cadence is too slow can opt into an `s3` or `git-lfs` backend. This module is the
+// SELECTOR + contract: it resolves which backend a config asks for and whether sync is opted in.
+// A live S3/LFS client is explicitly out of scope this phase — the selector ships, the backend is
+// pluggable. Defaulting to `git` means single-operator + most-team projects are unaffected.
+//
+// No `require` — pure. Deterministic.
+
+const BACKENDS = Object.freeze(['git', 's3', 'git-lfs']);
+const DEFAULT_BACKEND = 'git';
+
+/** True when the project opted into a non-git sync backend. */
+function isOptIn(config) {
+  const b = config && config.collab && config.collab.sync_backend;
+  return !!b && b !== 'git' && BACKENDS.includes(b);
+}
+
+/**
+ * Resolve the sync backend. Unknown/missing → 'git' (the safe default).
+ * @returns {{backend, optIn, supported}}  supported=false for opt-in backends whose live client
+ *   is not bundled this phase (the caller falls back to git + warns).
+ */
+function resolveBackend(config) {
+  const raw = config && config.collab && config.collab.sync_backend;
+  const backend = BACKENDS.includes(raw) ? raw : DEFAULT_BACKEND;
+  const optIn = backend !== DEFAULT_BACKEND;
+  // Phase 40 ships the selector only; no live S3/LFS client → opt-in backends are "declared but not
+  // yet executable". git is always supported (it's the existing push/pull path).
+  const supported = backend === DEFAULT_BACKEND;
+  return { backend, optIn, supported };
+}
+
+module.exports = { BACKENDS, DEFAULT_BACKEND, isOptIn, resolveBackend };

package/scripts/lib/i18n/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+// Phase 40.5 — i18n/index.cjs — GDD CLI localization resolver.
+//
+// Resolves a locale (config override > env LANG > English), a fallback chain (locale → base → en),
+// and translates a message key against per-locale flat-JSON tables. The pure functions (baseLocale,
+// fallbackChain, resolveLocale, translate, descriptionFor) take their data as arguments and touch
+// neither fs nor env directly — so they are trivially unit-testable. `loadTable` is the only fs reader.
+//
+// Contract: reference/cli-localization.md. Fallback is always to `en` (the complete source table).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KNOWN_LOCALES = Object.freeze(['en', 'ru', 'uk', 'de', 'fr', 'zh', 'ja']);
+const DEFAULT_LOCALE = 'en';
+const MESSAGES_DIR = path.join(__dirname, 'messages');
+
+/** Normalize a raw locale token: lowercase, `_`→`-`, strip an encoding suffix (`ru_RU.UTF-8` → `ru-ru`). */
+function normalizeLocale(code) {
+  if (!code) return '';
+  return String(code).split('.')[0].split(':')[0].trim().toLowerCase().replace(/_/g, '-');
+}
+
+/** The base of a locale (`de-de` → `de`; `en` → `en`). */
+function baseLocale(code) {
+  return normalizeLocale(code).split('-')[0];
+}
+
+/** Resolution chain: [normalized, base, 'en'] with duplicates removed. */
+function fallbackChain(code) {
+  const norm = normalizeLocale(code);
+  const chain = [];
+  for (const c of [norm, baseLocale(norm), DEFAULT_LOCALE]) {
+    if (c && !chain.includes(c)) chain.push(c);
+  }
+  return chain.length ? chain : [DEFAULT_LOCALE];
+}
+
+/**
+ * Resolve the active locale. Precedence: explicit config.locale > env.LANG/LC_ALL > 'en'.
+ * @param {{env?: object, configLocale?: string}} [opts]
+ */
+function resolveLocale(opts) {
+  const o = opts || {};
+  const fromConfig = normalizeLocale(o.configLocale);
+  if (fromConfig) return fromConfig;
+  const env = o.env || {};
+  const fromEnv = normalizeLocale(env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE);
+  if (fromEnv && fromEnv !== 'c' && fromEnv !== 'posix') return fromEnv;
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * Translate `key` for `locale` against the supplied `tables` map ({ <locale>: {<key>: <string>} }).
+ * Walks the fallback chain; returns the first hit, else the key itself (so a missing key is visible,
+ * never throws).
+ */
+function translate(tables, key, locale) {
+  const map = tables || {};
+  for (const loc of fallbackChain(locale)) {
+    const t = map[loc];
+    if (t && Object.prototype.hasOwnProperty.call(t, key) && typeof t[key] === 'string') return t[key];
+  }
+  return key;
+}
+
+/**
+ * Resolve a skill/agent description for `locale`: frontmatter.description_i18n[<chain>] || .description.
+ * Opt-in + backward-compatible — absent description_i18n falls straight back to the English description.
+ */
+function descriptionFor(frontmatter, locale) {
+  const fm = frontmatter || {};
+  const i18n = fm.description_i18n;
+  if (i18n && typeof i18n === 'object') {
+    for (const loc of fallbackChain(locale)) {
+      if (typeof i18n[loc] === 'string' && i18n[loc].trim()) return i18n[loc];
+    }
+  }
+  return fm.description || '';
+}
+
+/** Read a locale's flat-JSON table from disk. Returns {} on missing/parse error (fail-safe → fallback). */
+function loadTable(locale, dir) {
+  const file = path.join(dir || MESSAGES_DIR, `${normalizeLocale(locale) || DEFAULT_LOCALE}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  KNOWN_LOCALES, DEFAULT_LOCALE, MESSAGES_DIR,
+  normalizeLocale, baseLocale, fallbackChain, resolveLocale, translate, descriptionFor, loadTable,
+};

package/scripts/lib/i18n/messages/de.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "de", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Eine Design-Qualitäts-Pipeline für KI-Coding-Agenten.",
+  "status.complete": "Fertig.",
+  "status.in_progress": "In Bearbeitung.",
+  "status.blocked": "Blockiert."
+}

package/scripts/lib/i18n/messages/en.json

@@ -0,0 +1,27 @@
+{
+  "_meta": { "locale": "en", "coverage": "complete", "fallback": null },
+  "help.usage": "Usage: gdd <command> [options]",
+  "help.tagline": "A design-quality pipeline for AI coding agents.",
+  "help.commands_header": "Commands",
+  "help.options_header": "Options",
+  "help.more": "Run `gdd help <command>` for details on a command.",
+  "help.pipeline": "Pipeline: brief -> explore -> plan -> design -> verify",
+  "error.no_state": "No .design/STATE.md found. Run /gdd:start to initialize a cycle.",
+  "error.no_config": "No .design/config.json found; using defaults.",
+  "error.stage_locked": "This stage is locked under the current cycle mode.",
+  "error.permission_denied": "Permission denied: your role cannot perform this action on this section.",
+  "error.budget_cap": "Budget cap reached. Raise the cap in .design/budget.json or wait for the next task.",
+  "error.connection_unavailable": "Connection unavailable. Configure it via /gdd:connections.",
+  "error.invalid_locale": "Unknown locale. Known locales: en, ru, uk, de, fr, zh, ja.",
+  "error.merge_conflict": "STATE.md has a merge conflict. Run the conflict-resolver to reconcile per section.",
+  "error.decision_locked": "This decision is locked. Use /gdd:unlock-decision <id> --approver <who> to reopen it.",
+  "error.no_telemetry": "No cost telemetry yet. Run a cycle first.",
+  "prompt.brief_header": "Stage 1 of 5 - Brief: capture the problem, audience, constraints, and metrics.",
+  "prompt.explore_header": "Stage 2 of 5 - Explore: inventory the design surface and interview for intent.",
+  "prompt.plan_header": "Stage 3 of 5 - Plan: decompose the work into tasks.",
+  "prompt.design_header": "Stage 4 of 5 - Design: execute the plan.",
+  "prompt.verify_header": "Stage 5 of 5 - Verify: score and audit against the design system.",
+  "status.complete": "Complete.",
+  "status.in_progress": "In progress.",
+  "status.blocked": "Blocked."
+}

package/scripts/lib/i18n/messages/fr.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "fr", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Un pipeline de qualité de conception pour les agents de codage IA.",
+  "status.complete": "Terminé.",
+  "status.in_progress": "En cours.",
+  "status.blocked": "Bloqué."
+}

package/scripts/lib/i18n/messages/ja.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "ja", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "AI コーディングエージェントのためのデザイン品質パイプライン。",
+  "status.complete": "完了。",
+  "status.in_progress": "進行中。",
+  "status.blocked": "ブロック中。"
+}

package/scripts/lib/i18n/messages/ru.json

@@ -0,0 +1,27 @@
+{
+  "_meta": { "locale": "ru", "coverage": "complete", "fallback": "en" },
+  "help.usage": "Использование: gdd <команда> [параметры]",
+  "help.tagline": "Конвейер качества дизайна для ИИ-агентов программирования.",
+  "help.commands_header": "Команды",
+  "help.options_header": "Параметры",
+  "help.more": "Выполните `gdd help <команда>` для подробностей о команде.",
+  "help.pipeline": "Конвейер: brief -> explore -> plan -> design -> verify",
+  "error.no_state": "Файл .design/STATE.md не найден. Выполните /gdd:start, чтобы инициализировать цикл.",
+  "error.no_config": "Файл .design/config.json не найден; используются значения по умолчанию.",
+  "error.stage_locked": "Этот этап заблокирован в текущем режиме цикла.",
+  "error.permission_denied": "Доступ запрещён: ваша роль не может выполнить это действие в этом разделе.",
+  "error.budget_cap": "Достигнут лимит бюджета. Увеличьте лимит в .design/budget.json или дождитесь следующей задачи.",
+  "error.connection_unavailable": "Подключение недоступно. Настройте его через /gdd:connections.",
+  "error.invalid_locale": "Неизвестная локаль. Доступные локали: en, ru, uk, de, fr, zh, ja.",
+  "error.merge_conflict": "В STATE.md конфликт слияния. Запустите conflict-resolver для согласования по разделам.",
+  "error.decision_locked": "Это решение заблокировано. Используйте /gdd:unlock-decision <id> --approver <кто>, чтобы открыть его повторно.",
+  "error.no_telemetry": "Телеметрия затрат пока отсутствует. Сначала выполните цикл.",
+  "prompt.brief_header": "Этап 1 из 5 - Brief: зафиксируйте задачу, аудиторию, ограничения и метрики.",
+  "prompt.explore_header": "Этап 2 из 5 - Explore: исследуйте поверхность дизайна и уточните намерение.",
+  "prompt.plan_header": "Этап 3 из 5 - Plan: разбейте работу на задачи.",
+  "prompt.design_header": "Этап 4 из 5 - Design: выполните план.",
+  "prompt.verify_header": "Этап 5 из 5 - Verify: оцените и проверьте по дизайн-системе.",
+  "status.complete": "Готово.",
+  "status.in_progress": "В процессе.",
+  "status.blocked": "Заблокировано."
+}

package/scripts/lib/i18n/messages/uk.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "uk", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "Конвеєр якості дизайну для ШІ-агентів програмування.",
+  "status.complete": "Готово.",
+  "status.in_progress": "У процесі.",
+  "status.blocked": "Заблоковано."
+}

package/scripts/lib/i18n/messages/zh.json

@@ -0,0 +1,7 @@
+{
+  "_meta": { "locale": "zh", "coverage": "placeholder", "fallback": "en" },
+  "help.tagline": "面向 AI 编码代理的设计质量流水线。",
+  "status.complete": "完成。",
+  "status.in_progress": "进行中。",
+  "status.blocked": "已阻塞。"
+}