heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/settings-registry.mjs

@@ -0,0 +1,232 @@
+/**
+ * HeySpex close-out settings registry — the single declaration of every close-out
+ * setting: its dotted key, type, shipped default, description, CLI flag, admin-only
+ * marker, enforced marker, and which vault templates ship it.
+ *
+ * WHY: nothing today says which close-out settings exist, so a shipped default has
+ * nowhere to live and a mistyped key fails silently ([[HS-FCF5-15XI-RES-user-editable-close-out-settings-with]]).
+ * This registry is the one source every face is meant to read — `hs settings`, the
+ * MCP settings tools, and (later) the console — instead of each guessing its own
+ * fallback.
+ *
+ * DECLARATION ONLY (HS-6TDH): this module does not read or write
+ * `.heyspex/config.yaml`, does not import `config-settings.mjs`, and does not change
+ * any existing settings behavior. A later task in the same epic
+ * ([[HS-KW38-15XI-EPIC-settings-registry-core]]) teaches `config-settings.mjs` to
+ * resolve reads/writes through this registry (defaults, unknown-key refusal,
+ * enforced-entry refusal, type/enum validation).
+ *
+ * DEPENDENCY-FREE: Node stdlib only, no filesystem access at all — same rationale as
+ * the sibling module's "DEPENDENCY-FREE" note.
+ *
+ * Traceability: [[HS-KW38-15XI-EPIC-settings-registry-core]] ·
+ * [[HS-FCF5-15XI-RES-user-editable-close-out-settings-with]] ·
+ * [[HS-6TDH-15XI-TASK-declare-every-close-out-setting-in-one]]
+ */
+
+/**
+ * @typedef {'boolean' | 'string' | 'enum'} SettingType
+ *
+ * @typedef {Object} SettingEntry
+ * @property {string} key - Dotted key, e.g. "close_out.update_docs".
+ * @property {SettingType} type - The value's declared type.
+ * @property {*} default - The shipped default value (absent-key resolution target).
+ * @property {string} description - One or two sentences a person can read as help text.
+ * @property {string|null} cliFlag - The `hs close` / `hs settings` flag name (e.g.
+ *   "--update-docs"), or `null` for an enforced entry with no user-facing flag.
+ * @property {boolean} adminOnly - True for a HeySpex-admin-only entry; a non-admin
+ *   vault must treat the key as unknown.
+ * @property {boolean} enforced - True for a hard rule that cannot be changed by
+ *   anyone through any face, including a HeySpex admin.
+ * @property {string[]} templates - Which vault templates ship this entry:
+ *   "heyspex" (the HeySpex platform vault) and/or "customer" (the shipped customer
+ *   template).
+ * @property {string[]} [values] - Allowed values; present only when `type` is "enum".
+ */
+
+/**
+ * The ordered list of every declared close-out setting. Order is the order the
+ * close-out runner is meant to evaluate them in (a later task); it is also the
+ * order `hs settings list` should render them in.
+ *
+ * @type {ReadonlyArray<Readonly<SettingEntry>>}
+ */
+export const SETTINGS_REGISTRY = Object.freeze(
+  [
+    {
+      key: 'close_out.update_docs',
+      type: 'boolean',
+      default: true,
+      description:
+        'Updates docs/user and docs/admin per the docs-action rule (create/edit/append) at every close-out.',
+      cliFlag: '--update-docs',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.review_grain',
+      type: 'enum',
+      values: ['milestone', 'task'],
+      default: 'milestone',
+      description:
+        'Chooses the close-out review unit: "milestone" flips a completed task straight to closed with no per-task review companion, "task" is the canonical per-task close-out protocol with one HS-REV per task.',
+      cliFlag: '--review-grain',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.review_backlog_never_blocks',
+      type: 'boolean',
+      default: true,
+      description:
+        'A review backlog sitting at in_review/review_pending never blocks a new claim and never needs owner permission.',
+      cliFlag: '--review-backlog-never-blocks',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.flip_completed_to_closed',
+      type: 'boolean',
+      default: true,
+      description: 'Flips a completed task straight to closed at close-out.',
+      cliFlag: '--flip-completed-to-closed',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.append_review_seed',
+      type: 'boolean',
+      default: true,
+      description: 'Appends a one-line review seed to the task change-log at close-out.',
+      cliFlag: '--append-review-seed',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.rolling_review_doc',
+      type: 'boolean',
+      default: true,
+      description: 'Accumulates one rolling review doc per milestone at close-out.',
+      cliFlag: '--rolling-review-doc',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.run_command_drift_doctor',
+      type: 'boolean',
+      default: true,
+      description:
+        'Runs the HeySpex command-drift doctor at close-out. HeySpex-admin-only; a customer vault never sees this key.',
+      cliFlag: '--run-command-drift-doctor',
+      adminOnly: true,
+      enforced: false,
+      templates: ['heyspex'],
+    },
+    // Hard rules: enforced entries cannot be changed by anyone through any face,
+    // including a HeySpex admin, so they carry no user-facing CLI flag.
+    {
+      key: 'close_out.alignment',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: alignment stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.capture',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: capture stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.research',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: research stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    // `close_out.git_commit` moved OUT of the hard-rule set above (owner ruling
+    // 2026-09-11, [[HS-PROTO-spexsource-agent-protocol]]): whether an agent
+    // ever commits at close-out is now a real, permission-gated toggle instead
+    // of an unconditional refusal. Default stays `false` for every vault —
+    // heyspex and customer alike — so nobody's out-of-box behavior changes; an
+    // owner opts in per vault via the normal settings-write-permission flow
+    // (`heyspex_settings_set` / `hs settings set --confirmed-by-user`). When
+    // `true`, the agent does not commit unconditionally — it still obeys the
+    // existing mode logic: the close-out commit lands at the boundary of the
+    // *active review grain* (`close_out.review_grain` — task / epic /
+    // milestone), routes only through the sanctioned `hs source preflight` →
+    // `hs source commit` path, and stays bound by every entry in
+    // spexsource-agent-protocol's always-forbidden list (no `--no-verify`, no
+    // force, no push — pushing is the separate `close_out.git_push` key,
+    // still enforced below). An explicit owner instruction for the session
+    // (e.g. "don't commit this one") overrides the setting for that session;
+    // the setting only changes the *default* when the owner said nothing.
+    {
+      key: 'close_out.git_commit',
+      type: 'boolean',
+      default: false,
+      description:
+        'Whether the agent commits automatically at close-out. Default false (a dirty tree is the expected hand-off; the human reviewer commits on Pass). When true, the agent still obeys the active review grain (close_out.review_grain) for WHEN to commit and the spexsource-agent-protocol always-forbidden list for HOW — never a bypass of those rules, just an opt-in default.',
+      cliFlag: '--git-commit',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.git_push',
+      type: 'boolean',
+      default: false,
+      description: 'Hard rule: an agent never pushes at close-out.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+  ].map((entry) => Object.freeze(entry)),
+);
+
+/** Fast key → entry lookup, built once from `SETTINGS_REGISTRY`. */
+const BY_KEY = new Map(SETTINGS_REGISTRY.map((entry) => [entry.key, entry]));
+
+/**
+ * Look up one registry entry by its dotted key.
+ * @param {string} key
+ * @returns {Readonly<SettingEntry>|null}
+ */
+export function getSettingEntry(key) {
+  if (typeof key !== 'string') return null;
+  return BY_KEY.get(key) ?? null;
+}
+
+/** True when `key` names a declared registry entry. */
+export function isKnownSetting(key) {
+  return getSettingEntry(key) !== null;
+}
+
+/** Every declared key, in registry order. */
+export function listRegistryKeys() {
+  return SETTINGS_REGISTRY.map((entry) => entry.key);
+}
+
+/** Every declared key the given vault template ships ("heyspex" or "customer"). */
+export function listKeysForTemplate(template) {
+  return SETTINGS_REGISTRY.filter((entry) => entry.templates.includes(template)).map(
+    (entry) => entry.key,
+  );
+}

package/vendor/heyspex-mcp/settings-tools.mjs

@@ -1,10 +1,21 @@
 /**
  * HeySpex settings MCP tools — the agent face over the settings core
- * (config-settings.mjs), mounted in cli.mjs as:
+ * (config-settings.mjs) and the settings registry (settings-registry.mjs),
+ * mounted in cli.mjs as:
  *   - heyspex_settings_list  (read — open)
  *   - heyspex_settings_get   (read — open)
  *   - heyspex_settings_set   (WRITE — permission-gated two-step confirm)
  *
+ * THIRD FACE (HS-OTEQ): these tools resolve every read through
+ * `getEffectiveSetting` (file value → registry default → absent) and the
+ * registry's key list, and every write through `validateSettingWrite` — the
+ * same functions the CLI face (`hs settings`) and, later, the console face
+ * resolve through. No fallback of its own: a registry-governed key answers
+ * identically no matter which face asks. A key the registry does not declare
+ * (e.g. `agent_behaviors.*`, `mvp_mode.*`) keeps working exactly as before —
+ * registry entries are additive, never a replacement for the freeform
+ * `.heyspex/config.yaml` surface.
+ *
  * WRITE-PERMISSION GUARDRAIL (owner directive 2026-07-11, documented in
  * specs/protocols/agent-settings-protocol.md): a settings write is a protected
  * class. `heyspex_settings_set` without `confirm_token` never writes — it records
@@ -16,31 +27,62 @@
  * (scripts/claude-hooks/settings-write-gate.mjs) additionally routes the confirm
  * call through the harness permission prompt in Claude Code.
  *
+ * `requestSettingsWrite` (step 1) and `confirmSettingsWrite`/`setConfigLeaf`
+ * (step 2) already run every write through `validateSettingWrite` inside the
+ * core, so this file does not re-validate — it only shapes the core's
+ * `{ ok:false, error, message }` refusal into the tool's response unchanged
+ * (never re-worded), which keeps the reason identical to what the CLI face
+ * gives for the same refused write.
+ *
  * Pattern source: procedure-tools.mjs (pure-logic execute* functions; cli.mjs wraps).
  */
 
 import {
   listConfigLeaves,
-  getConfigLeaf,
+  getEffectiveSetting,
   requestSettingsWrite,
   confirmSettingsWrite,
   validateSettingKey,
   CONFIG_REL,
 } from './config-settings.mjs';
+import { getSettingEntry, listRegistryKeys } from './settings-registry.mjs';
 
 const MCP_FACE = 'mcp';
 
+/** True when `key` equals `prefix` or is nested under it (dotted-segment match). */
+function matchesPrefix(key, prefix) {
+  return !prefix || key === prefix || key.startsWith(prefix + '.');
+}
+
 export function executeSettingsList(vaultRoot, args = {}) {
   const prefix = typeof args.prefix === 'string' ? args.prefix.trim() : '';
-  let settings = listConfigLeaves(vaultRoot);
-  if (prefix) {
-    settings = settings.filter((s) => s.key === prefix || s.key.startsWith(prefix + '.'));
+
+  const fileLeaves = listConfigLeaves(vaultRoot);
+  const seen = new Set();
+  const settings = [];
+
+  // Registry-declared keys first, in registry order, resolved through the same
+  // file → registry-default chain every face reads through — so a key never
+  // written to disk still appears, carrying its shipped default.
+  for (const key of listRegistryKeys()) {
+    if (!matchesPrefix(key, prefix)) continue;
+    const effective = getEffectiveSetting(vaultRoot, key);
+    settings.push({ key, value: effective.value, source: effective.source, found: effective.found });
+    seen.add(key);
   }
+
+  // Then any file leaf outside the registry's namespaces (agent_behaviors.*,
+  // mvp_mode.*, …) — additive, unchanged from the pre-registry behavior.
+  for (const leaf of fileLeaves) {
+    if (seen.has(leaf.key) || !matchesPrefix(leaf.key, prefix)) continue;
+    settings.push({ key: leaf.key, value: leaf.value, source: 'file', found: true });
+  }
+
   return {
     ok: true,
     config_file: CONFIG_REL.replace(/\\/g, '/'),
     count: settings.length,
-    settings: settings.map(({ key, value }) => ({ key, value })),
+    settings,
   };
 }
 
@@ -48,13 +90,26 @@ export function executeSettingsGet(vaultRoot, args = {}) {
   const key = typeof args.key === 'string' ? args.key.trim() : '';
   const check = validateSettingKey(key);
   if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
-  const leaf = getConfigLeaf(vaultRoot, key);
+
+  const effective = getEffectiveSetting(vaultRoot, key);
+  let note;
+  if (effective.source === 'registry_default') {
+    const entry = getSettingEntry(key);
+    note = `Key absent from .heyspex/config.yaml — resolved to the registry default (${entry?.description ?? 'see settings-registry.mjs'}).`;
+  } else if (effective.source === 'absent') {
+    note = 'Key absent from .heyspex/config.yaml and not declared in the settings registry — consumers fall back to their documented default.';
+  } else if (effective.source === 'computed') {
+    note =
+      'Computed live from the machine-local hs trust store (~/.heyspex/trusted-folders.json) — ' +
+      'never read from .heyspex/config.yaml. Read-only: revoke a folder with "hs trust revoke <path>".';
+  }
   return {
     ok: true,
     key,
-    found: leaf.found,
-    value: leaf.found ? leaf.value : null,
-    ...(leaf.found ? {} : { note: 'Key absent from .heyspex/config.yaml — consumers fall back to their documented default.' }),
+    found: effective.found,
+    value: effective.value,
+    source: effective.source,
+    ...(note ? { note } : {}),
   };
 }
 
@@ -81,14 +136,32 @@ export function executeSettingsSet(vaultRoot, args = {}) {
       face: MCP_FACE,
     });
     if (!result.ok) return result;
+    // MEASURED, NOT ASSUMED ([[HS-IOJW-5YDH-DIAG]] sweep). "applied and audited"
+    // used to be printed unconditionally while `appendSettingsAudit`'s boolean
+    // was thrown away inside `setConfigLeaf`, so a settings write with no audit
+    // row — the one artifact that makes a protected-class write reviewable after
+    // the fact — read exactly like a fully audited one. The config write itself
+    // DID land, so `ok` stays true and nothing is retried; `audited` + `status`
+    // are what let the caller tell a full success from a partial one.
+    const audited = result.audited === true;
     return {
       ok: true,
-      status: 'applied',
+      status: audited ? 'applied' : 'applied_not_audited',
+      partial: !audited,
+      audited,
       key: result.key,
       previous: result.previous,
       value: result.value,
       created: result.created,
-      note: 'Setting applied and audited to .heyspex/settings-history.jsonl.',
+      // HS-4C76 fix 3: the core seeds a missing config.yaml from the template on
+      // the first write instead of refusing; surface that so the caller can say so.
+      ...(result.seeded === true ? { seeded: true } : {}),
+      note: audited
+        ? `Setting applied and audited to .heyspex/settings-history.jsonl.${result.seeded === true ? ' (.heyspex/config.yaml was missing and was seeded from the template first.)' : ''}`
+        : 'Setting APPLIED to .heyspex/config.yaml, but the audit append to ' +
+          '.heyspex/settings-history.jsonl FAILED — this write has NO audit row. The value is live; do not ' +
+          're-apply it. Tell the user the change is in effect but unaudited, and check that ' +
+          '.heyspex/settings-history.jsonl is writable.',
     };
   }