chore: import upstream snapshot with attribution

scripts/declared-annotation.ts

@@ -0,0 +1,125 @@
+/**
+ * Declared-profile annotation helper (plan-tune cathedral T7).
+ *
+ * Given a kebab signal_key from scripts/question-registry.ts, returns a
+ * one-line plain-English annotation when the user's declared profile is in
+ * a strong band on the matching dimension, else null. Read-only — never
+ * mutates the profile.
+ *
+ * Signature uses kebab signal_key per D2/Codex correction. Internally maps
+ * to the underscore Dimension key by consulting SIGNAL_MAP and picking the
+ * dimension this signal influences most strongly.
+ *
+ * Used by:
+ *   - hosts/claude/hooks/question-preference-hook (Layer 3 injection path,
+ *     when AUQ mutation lands)
+ *   - scripts/resolvers/question-tuning.ts preamble (Layer 9 fallback,
+ *     host-portable path on Codex / older Claude Code)
+ *
+ * NOT used for AUTO_DECIDE. Annotation is advisory only — declared-only
+ * per TODOS.md E1 substrate-risk guidance. Inferred-driven AUTO_DECIDE
+ * remains v2.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+import { SIGNAL_MAP, type Dimension, ALL_DIMENSIONS } from './psychographic-signals';
+
+const STRONG_HIGH = 0.7;
+const STRONG_LOW = 0.3;
+
+/**
+ * Plain-English phrasing per dimension + band. Keep one sentence each.
+ * Used directly in question prose, so phrasing matters.
+ */
+const DIMENSION_PHRASING: Record<Dimension, { high: string; low: string }> = {
+  scope_appetite: {
+    high: 'Your declared profile leans complete-implementation (boil the ocean).',
+    low: 'Your declared profile leans ship-small-fast.',
+  },
+  risk_tolerance: {
+    high: 'Your declared profile leans move-fast.',
+    low: 'Your declared profile leans check-carefully.',
+  },
+  detail_preference: {
+    high: 'Your declared profile leans verbose-with-tradeoffs.',
+    low: 'Your declared profile leans terse, just-do-it.',
+  },
+  autonomy: {
+    high: 'Your declared profile leans delegate-and-trust.',
+    low: 'Your declared profile leans consult-me-first.',
+  },
+  architecture_care: {
+    high: 'Your declared profile leans get-the-design-right.',
+    low: 'Your declared profile leans pragmatic-ship-it.',
+  },
+};
+
+interface DeveloperProfile {
+  declared?: Partial<Record<Dimension, number>>;
+}
+
+function stateRoot(): string {
+  return (
+    process.env.GSTACK_STATE_ROOT ||
+    process.env.GSTACK_HOME ||
+    path.join(os.homedir(), '.gstack')
+  );
+}
+
+function readProfile(): DeveloperProfile | null {
+  try {
+    const p = path.join(stateRoot(), 'developer-profile.json');
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Determine which dimension a signal_key influences most strongly.
+ * Sums |delta| across all user_choice → DimensionDelta[] entries for that
+ * signal, returns the dimension with the largest total influence.
+ * Returns null if the signal_key isn't in the map.
+ */
+export function primaryDimensionFor(signalKey: string): Dimension | null {
+  const entry = SIGNAL_MAP[signalKey];
+  if (!entry) return null;
+  const totals: Partial<Record<Dimension, number>> = {};
+  for (const choice of Object.keys(entry)) {
+    for (const dd of entry[choice]) {
+      totals[dd.dim] = (totals[dd.dim] ?? 0) + Math.abs(dd.delta);
+    }
+  }
+  let best: Dimension | null = null;
+  let bestVal = -Infinity;
+  for (const d of ALL_DIMENSIONS) {
+    const v = totals[d] ?? 0;
+    if (v > bestVal) {
+      bestVal = v;
+      best = d;
+    }
+  }
+  return bestVal > 0 ? best : null;
+}
+
+/**
+ * Given a signal_key, return a one-line plain-English annotation when
+ * the user's declared profile is in a strong band on the primary dim,
+ * else null.
+ */
+export function getDeclaredAnnotation(signalKey: string): string | null {
+  if (!signalKey || typeof signalKey !== 'string') return null;
+  const dim = primaryDimensionFor(signalKey);
+  if (!dim) return null;
+
+  const profile = readProfile();
+  const declared = profile?.declared?.[dim];
+  if (typeof declared !== 'number') return null;
+
+  if (declared >= STRONG_HIGH) return DIMENSION_PHRASING[dim].high;
+  if (declared <= STRONG_LOW) return DIMENSION_PHRASING[dim].low;
+  return null;
+}