@mindrian_os/install 1.13.0-beta.12 → 1.13.0-beta.14

package/lib/memory/packet-schema-validation.test.cjs

@@ -0,0 +1,317 @@
+'use strict';
+
+/*
+ * Phase 125-04 -- Schema superset extension validator tests.
+ *
+ * Adds $defs.FrameworkChainHint and the optional framework_chain_hint property
+ * to $defs.LocalGraphSummary.properties. Canon Part 8 invariants preserved:
+ *   - additionalProperties: false on every object node (leak-prevention teeth)
+ *   - 12-job D-02 closed-vocabulary UNTOUCHED
+ *   - LocalGraphSummary.required[] still has its original 6 entries
+ *     (framework_chain_hint is OPTIONAL -- NOT added to required[])
+ *
+ * The ajv2020 validator (the same path lib/core/brain-client.cjs uses via
+ * _validatorFor + _ensureSchema) picks up the new optional field automatically
+ * once the schema file is updated. These tests pin the contract.
+ *
+ * Test 1  -- hint-absent packet validates (existing Phase 110 packet path)
+ * Test 2  -- hint-present packet validates (Plan 03's enriched packet path)
+ * Test 3  -- existing required[] preserved (packet missing nearest_claims rejected)
+ * Test 4  -- additionalProperties:false on LocalGraphSummary (extra field rejected)
+ * Test 5  -- additionalProperties:false on FrameworkChainHint (extra field rejected)
+ * Test 6  -- slice_scope enum enforced (4 rejected)
+ * Test 7  -- slice_scope enum accepts 1, 2, 3
+ * Test 8  -- edges array maxItems 50 enforced (51 rejected)
+ * Test 9  -- 12 jobs closed-vocab UNTOUCHED (count match)
+ * Test 10 -- each edge requires from + to + hop_distance (missing 'to' rejected)
+ * Test 11 -- null tolerance in edges (confidence:null accepted)
+ */
+
+const { test } = require('node:test');
+const { ok, equal } = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const Ajv2020 = require('ajv/dist/2020').default || require('ajv/dist/2020');
+
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'data', 'brain-packet-schema.json');
+const SCHEMA = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+
+// The 12 D-02 closed-vocab jobs (Canon Part 8 invariant -- Plan 04 MUST NOT
+// touch this list). Mirrors scripts/build-brain-packet-schema.cjs SHIPPED_JOBS
+// and lib/core/brain-client.cjs SHIPPED_JOBS.
+const SHIPPED_JOBS = Object.freeze([
+  'select_methodology',
+  'suggest_next_move',
+  'detect_contradiction',
+  'summarize_neighborhood',
+  'classify_room_budding',
+  'rank_assumptions',
+  'generate_feynman_explanation',
+  'strengthen_minto',
+  'prepare_investor_brief',
+  'opportunity_react',
+  'opportunity_reflect',
+  'opportunity_rank',
+]);
+
+// Compile a validator for one (job, half). Mirrors brain-client.cjs::_validatorFor
+// -- the same wrapper-with-inline-$defs pattern (ajv@8 cannot resolve a deep
+// JSON pointer into a schema indexed only by its $id; the wrapper carries
+// $defs inline).
+function validatorFor(job, half) {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  return ajv.compile({
+    $id: 'urn:mindrian:test:' + job + ':' + half,
+    $ref: '#/$defs/' + job + '/' + half,
+    $defs: SCHEMA.$defs,
+  });
+}
+
+// A minimal, valid Phase 110 packet under the suggest_next_move job. Every
+// field that LocalGraphSummary.required[] requires is present with an empty
+// array (per Plan 02 -- empty is valid). The Plan 03 hint is NOT included
+// here; tests that want the hint add it explicitly.
+function basePacket() {
+  return {
+    packet_version: '1.0',
+    job: 'suggest_next_move',
+    room_stage: 'unknown',
+    origin: 'navigation_api',
+    privacy_mode: 'local_summary_only',
+    active_context: {
+      jtbd: null,
+      operator: 'OPERATOR_X',
+      focus_node: { id: 'n1', type: 'claim', summary: 'sample focus node' },
+    },
+    local_graph_summary: {
+      nearest_claims: [],
+      nearest_assumptions: [],
+      contradictions: [],
+      unsupported_claims: [],
+      recent_changes: [],
+      banked_opportunities: { count: 0, items: [] },
+    },
+    constraints: { privacy: 'no_raw_artifact_text', max_tokens: 1200 },
+  };
+}
+
+// A fully populated FrameworkChainHint (per Plan 04 CONTEXT.md Scope IN B item 5).
+function fullHint() {
+  return {
+    edges: [
+      {
+        from: 'JTBD',
+        to: 'Mullins 7 Domains',
+        confidence: 0.82,
+        transform_description: 'JTBD anchors customer pull; Mullins stress-tests market attractiveness',
+        hop_distance: 1,
+      },
+      {
+        from: 'Mullins 7 Domains',
+        to: 'Porter Five Forces',
+        confidence: 0.71,
+        transform_description: 'Market attractiveness flows into industry structure',
+        hop_distance: 2,
+      },
+    ],
+    slice_scope: 2,
+    slice_rationale: 'ill-defined state with active JTBD; 2-hop slice',
+    brain_snapshot_id: 'sha256:b4a1f2c3',
+    fetched_at: '2026-05-13T17:00:00Z',
+  };
+}
+
+// =============================================================================
+// Test 1 -- hint-absent packet validates (Phase 110 existing path stays GREEN)
+// =============================================================================
+test('packet-schema-validation: hint-absent packet validates', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const valid = v(basePacket());
+  ok(valid, 'expected valid; got errors: ' + JSON.stringify(v.errors));
+});
+
+// =============================================================================
+// Test 2 -- hint-present packet validates (Plan 03 enriched path)
+// =============================================================================
+test('packet-schema-validation: hint-present packet validates', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  const valid = v(p);
+  ok(valid, 'expected valid; got errors: ' + JSON.stringify(v.errors));
+});
+
+// =============================================================================
+// Test 3 -- existing required[] preserved (Canon Part 8 leak-prevention teeth)
+// =============================================================================
+test('packet-schema-validation: missing nearest_claims is rejected', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  delete p.local_graph_summary.nearest_claims;
+  const valid = v(p);
+  ok(!valid, 'expected rejection');
+  const msg = JSON.stringify(v.errors || []);
+  ok(/nearest_claims|required/i.test(msg),
+    'expected error mentioning nearest_claims or required; got: ' + msg);
+});
+
+// =============================================================================
+// Test 4 -- additionalProperties:false on LocalGraphSummary
+// =============================================================================
+test('packet-schema-validation: extra field in local_graph_summary is rejected', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.forbidden_field = 'should not be allowed';
+  const valid = v(p);
+  ok(!valid, 'expected rejection of unknown field in local_graph_summary');
+});
+
+// =============================================================================
+// Test 5 -- additionalProperties:false on FrameworkChainHint
+// =============================================================================
+test('packet-schema-validation: extra field in framework_chain_hint is rejected', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  p.local_graph_summary.framework_chain_hint.forbidden_field = 'should not be allowed';
+  const valid = v(p);
+  ok(!valid, 'expected rejection of unknown field in framework_chain_hint');
+});
+
+// =============================================================================
+// Test 6 -- slice_scope enum enforced (only 1, 2, 3 valid; 4 rejected)
+// =============================================================================
+test('packet-schema-validation: slice_scope=4 is rejected', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  p.local_graph_summary.framework_chain_hint.slice_scope = 4;
+  const valid = v(p);
+  ok(!valid, 'expected rejection of slice_scope=4');
+});
+
+// =============================================================================
+// Test 7 -- slice_scope enum accepts 1, 2, 3
+// =============================================================================
+test('packet-schema-validation: slice_scope=1, 2, 3 all accepted', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  for (const scope of [1, 2, 3]) {
+    const p = basePacket();
+    p.local_graph_summary.framework_chain_hint = fullHint();
+    p.local_graph_summary.framework_chain_hint.slice_scope = scope;
+    const valid = v(p);
+    ok(valid, 'expected slice_scope=' + scope + ' to validate; errors: ' + JSON.stringify(v.errors));
+  }
+});
+
+// =============================================================================
+// Test 8 -- edges array maxItems 50 enforced (51 entries rejected)
+// =============================================================================
+test('packet-schema-validation: edges maxItems 50 enforced (51 rejected)', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  const edges = [];
+  for (let i = 0; i < 51; i++) {
+    edges.push({
+      from: 'F' + i,
+      to: 'F' + (i + 1),
+      confidence: 0.5,
+      transform_description: null,
+      hop_distance: 1,
+    });
+  }
+  p.local_graph_summary.framework_chain_hint.edges = edges;
+  const valid = v(p);
+  ok(!valid, 'expected rejection of 51 edges (maxItems=50)');
+});
+
+// =============================================================================
+// Test 9 -- 12 jobs closed-vocab UNTOUCHED (D-02 invariant)
+// =============================================================================
+test('packet-schema-validation: 12 jobs closed-vocab D-02 untouched', () => {
+  const defs = SCHEMA.$defs || {};
+  for (const job of SHIPPED_JOBS) {
+    ok(defs[job], 'expected $def for shipped job ' + job + ' to exist');
+    ok(defs[job].in, 'expected $def "' + job + '" to have an "in" sub-schema');
+    ok(defs[job].out, 'expected $def "' + job + '" to have an "out" sub-schema');
+    const jobConst = defs[job].in
+      && defs[job].in.properties
+      && defs[job].in.properties.job
+      && defs[job].in.properties.job.const;
+    equal(jobConst, job,
+      'expected $def "' + job + '" in.properties.job.const to equal ' + job);
+  }
+  // Count the jobs by detecting which $defs have an "in" sub-schema (the
+  // per-job marker). Must be exactly 12 -- no additions allowed.
+  const jobCount = Object.keys(defs).filter((k) => defs[k] && defs[k].in).length;
+  equal(jobCount, 12,
+    'expected exactly 12 job $defs (D-02 closed vocabulary); got ' + jobCount);
+});
+
+// =============================================================================
+// Test 10 -- each edge requires from + to + hop_distance
+// =============================================================================
+test('packet-schema-validation: edge missing "to" is rejected', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  // Edge with `to` field omitted entirely (not null -- absent).
+  p.local_graph_summary.framework_chain_hint.edges = [
+    {
+      from: 'JTBD',
+      confidence: 0.7,
+      transform_description: 'missing to field',
+      hop_distance: 1,
+    },
+  ];
+  const valid = v(p);
+  ok(!valid, 'expected rejection of edge missing required "to" property');
+});
+
+// =============================================================================
+// Test 11 -- null tolerance in edges (Plan 02 graceful handling)
+// =============================================================================
+test('packet-schema-validation: edge with confidence=null accepted', () => {
+  const v = validatorFor('suggest_next_move', 'in');
+  const p = basePacket();
+  p.local_graph_summary.framework_chain_hint = fullHint();
+  p.local_graph_summary.framework_chain_hint.edges = [
+    {
+      from: 'JTBD',
+      to: 'Mullins 7 Domains',
+      confidence: null,
+      transform_description: null,
+      hop_distance: 1,
+    },
+  ];
+  const valid = v(p);
+  ok(valid, 'expected null confidence to be accepted; errors: ' + JSON.stringify(v.errors));
+});
+
+// =============================================================================
+// Self-assertion -- preserves the existing 6 LocalGraphSummary.required[]
+// entries and framework_chain_hint is NOT one of them. This is the structural
+// invariant from CONTEXT.md Scope IN B item 6 + the must_haves contract.
+// =============================================================================
+test('packet-schema-validation: LocalGraphSummary.required[] has 6 entries and excludes framework_chain_hint', () => {
+  const req = SCHEMA.$defs.LocalGraphSummary.required;
+  ok(Array.isArray(req), 'expected required[] array');
+  equal(req.length, 6,
+    'expected exactly 6 required entries on LocalGraphSummary; got ' + req.length);
+  ok(!req.includes('framework_chain_hint'),
+    'framework_chain_hint MUST be OPTIONAL -- not in required[]');
+  // The original 6 (in CONTEXT.md order):
+  for (const f of [
+    'nearest_claims',
+    'nearest_assumptions',
+    'contradictions',
+    'unsupported_claims',
+    'recent_changes',
+    'banked_opportunities',
+  ]) {
+    ok(req.includes(f),
+      'expected ' + f + ' to remain in LocalGraphSummary.required[]');
+  }
+});

package/lib/memory/per-command-jtbd-derivation.test.cjs

@@ -0,0 +1,130 @@
+'use strict';
+
+/*
+ * Phase 104.1 Plan 01 -- per-command-jtbd-derivation test. Asserts that the
+ * Phase 104.1 build script extension (scripts/build-command-registry.cjs)
+ * correctly derives `jtbd_label` and `jtbd_summary` from
+ * `lib/hmi/jtbd-taxonomy.json` via the per-command `serves_jtbd[0]`.
+ *
+ * Per Canon Part 7 (Reuse Before Build): the taxonomy is the single source
+ * of truth for JTBD content. Per-command frontmatter NEVER authors jtbd_label
+ * or jtbd_summary -- both are derived at registry-build time.
+ *
+ * Expected state: GREEN immediately after Plan 01 Task 1 lands (the registry
+ * already carries the derived fields; nothing about derivation depends on the
+ * teaching content sweep in Plan 02).
+ *
+ * Registered in:
+ *   - tests/run-all-104.1.sh (Phase 104.1 scoped aggregator)
+ *   - lib/memory/run-feynman-tests.cjs TEST_FILES[]
+ *
+ * Canon Part 8 boundary: this test reads ONLY the local plugin registry +
+ * the local taxonomy. Zero network surface, zero Brain calls.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const fs = require('fs');
+
+const registryPath = path.join(__dirname, '..', '..', 'data', 'command-registry.json');
+const taxonomyPath = path.join(__dirname, '..', '..', 'lib', 'hmi', 'jtbd-taxonomy.json');
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+const taxonomy = JSON.parse(fs.readFileSync(taxonomyPath, 'utf8'));
+const taxonomyById = Object.fromEntries(
+  (Array.isArray(taxonomy.entries) ? taxonomy.entries : []).map((e) => [e.id, e])
+);
+
+test('commands with serves_jtbd have non-null jtbd_label in registry', () => {
+  const offenders = registry.commands.filter(
+    (c) =>
+      Array.isArray(c.serves_jtbd) && c.serves_jtbd.length > 0 && !c.jtbd_label
+  );
+  assert.equal(
+    offenders.length,
+    0,
+    offenders.length +
+      ' commands with serves_jtbd missing jtbd_label: ' +
+      offenders.slice(0, 3).map((c) => c.command).join(', ')
+  );
+});
+
+test('commands with serves_jtbd have non-null jtbd_summary in registry (excluding orphan taxonomy references)', () => {
+  // A command's serves_jtbd[0] may reference a JTBD id that is not in the
+  // current taxonomy (an orphan). In that case jtbd_summary is null and that
+  // is correct (the build script cannot derive a summary it does not have).
+  // Real offenders are commands whose serves_jtbd[0] IS in the taxonomy yet
+  // still emit a null jtbd_summary -- that is a derivation bug.
+  const offenders = registry.commands.filter(
+    (c) =>
+      Array.isArray(c.serves_jtbd) &&
+      c.serves_jtbd.length > 0 &&
+      !c.jtbd_summary
+  );
+  const orphans = offenders.filter((c) => !taxonomyById[c.serves_jtbd[0]]);
+  const realOffenders = offenders.filter((c) => taxonomyById[c.serves_jtbd[0]]);
+  assert.equal(
+    realOffenders.length,
+    0,
+    realOffenders.length +
+      ' commands with valid serves_jtbd missing jtbd_summary (' +
+      orphans.length +
+      ' orphan references found separately): ' +
+      realOffenders.slice(0, 3).map((c) => c.command).join(', ')
+  );
+});
+
+test('jtbd_label matches capitalize+space-replace of serves_jtbd[0]', () => {
+  // Spot-check: for a command with serves_jtbd ['find-bottleneck'],
+  // jtbd_label should be 'Find Bottleneck'.
+  const sample = registry.commands.find(
+    (c) => Array.isArray(c.serves_jtbd) && c.serves_jtbd[0] === 'find-bottleneck'
+  );
+  if (sample) {
+    assert.equal(
+      sample.jtbd_label,
+      'Find Bottleneck',
+      "jtbd_label for find-bottleneck should be 'Find Bottleneck', got '" +
+        sample.jtbd_label +
+        "'"
+    );
+  }
+  // Generic check: every jtbd_label should match the derivation rule.
+  for (const c of registry.commands) {
+    if (!Array.isArray(c.serves_jtbd) || c.serves_jtbd.length === 0) continue;
+    const id = c.serves_jtbd[0];
+    const expected = id
+      .split('-')
+      .map((w) => (w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+      .join(' ');
+    assert.equal(
+      c.jtbd_label,
+      expected,
+      'jtbd_label mismatch for ' +
+        c.command +
+        ' (serves_jtbd[0]=' +
+        id +
+        "): expected '" +
+        expected +
+        "', got '" +
+        c.jtbd_label +
+        "'"
+    );
+  }
+});
+
+test('jtbd_summary matches taxonomy entry.one_line verbatim', () => {
+  for (const c of registry.commands) {
+    if (!Array.isArray(c.serves_jtbd) || c.serves_jtbd.length === 0) continue;
+    const id = c.serves_jtbd[0];
+    const entry = taxonomyById[id];
+    if (!entry) continue; // orphan reference -- separate concern.
+    assert.equal(
+      c.jtbd_summary,
+      entry.one_line,
+      'jtbd_summary mismatch for ' +
+        c.command +
+        ': expected verbatim taxonomy one_line'
+    );
+  }
+});

package/lib/memory/per-command-teaching.test.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+/*
+ * Phase 104.1 Plan 01 -- per-command-teaching presence + length + no-em-dash
+ * test. Mirrors the Phase 104 per-command-serves_jtbd test pattern: read
+ * data/command-registry.json, assert content invariants on every command.
+ *
+ * Initial state (Plan 01 RED): no command frontmatter has `teaching:` yet.
+ *   - Test 1 (presence) FAILS by design -- Plan 02 fills 86 teaching strings.
+ *   - Tests 2-4 (length / no-em-dash / sentence-count) PASS vacuously
+ *     because they filter on `c.teaching` (null short-circuits to empty).
+ *
+ * GREEN state (after Plan 02 lands content): all 4 tests pass.
+ *
+ * Registered in:
+ *   - tests/run-all-104.1.sh (Phase 104.1 scoped aggregator)
+ *   - lib/memory/run-feynman-tests.cjs TEST_FILES[]
+ *
+ * Constraints enforced (from .planning/phases/104.1-per-command-teaching-content/104.1-CONTEXT.md D2):
+ *   - non-empty teaching field on every command
+ *   - 50-300 characters
+ *   - no em-dashes (U+2014); double-hyphens `--` and hyphens `-` are fine
+ *   - 1-2 sentences (terminal `.` / `!` / `?` count)
+ *
+ * Canon Part 8 boundary: this test reads ONLY the local plugin registry
+ * (data/command-registry.json). Zero network surface, zero Brain calls.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const fs = require('fs');
+
+const registryPath = path.join(__dirname, '..', '..', 'data', 'command-registry.json');
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+
+test('every command has a non-empty teaching field', () => {
+  const missing = registry.commands.filter(
+    (c) => !c.teaching || c.teaching.length === 0
+  );
+  if (missing.length > 0) {
+    // RED until Plan 02 fills content. Print which commands are missing
+    // teaching field for diagnostic visibility (the WARNING tripwire in
+    // scripts/build-command-registry.cjs --check uses the same shape).
+    console.log(
+      'Missing teaching field on ' +
+        missing.length +
+        ' commands: ' +
+        missing.map((c) => c.command).join(', ')
+    );
+  }
+  assert.equal(
+    missing.length,
+    0,
+    missing.length +
+      ' of ' +
+      registry.commands.length +
+      ' commands missing teaching field'
+  );
+});
+
+test('every teaching string is 50-300 characters', () => {
+  const offenders = registry.commands.filter(
+    (c) => c.teaching && (c.teaching.length < 50 || c.teaching.length > 300)
+  );
+  assert.equal(
+    offenders.length,
+    0,
+    offenders.length +
+      ' teaching strings outside 50-300 char range: ' +
+      offenders
+        .slice(0, 3)
+        .map((c) => c.command + '(' + c.teaching.length + ')')
+        .join(', ')
+  );
+});
+
+test('no teaching string contains em-dashes (project no-em-dash rule)', () => {
+  // U+2014 EM DASH only. Allowed: U+002D HYPHEN-MINUS (single or doubled).
+  const emDashRegex = /—/;
+  const offenders = registry.commands.filter(
+    (c) => c.teaching && emDashRegex.test(c.teaching)
+  );
+  assert.equal(
+    offenders.length,
+    0,
+    offenders.length +
+      ' teaching strings contain em-dashes: ' +
+      offenders.slice(0, 3).map((c) => c.command).join(', ')
+  );
+});
+
+test('every teaching string is 1-2 sentences', () => {
+  // Heuristic: count terminal punctuation (. ! ?) followed by whitespace or
+  // end-of-string. Common abbreviations may double-count -- worth refining if
+  // false positives surface during Plan 02 content review.
+  const sentenceCountRegex = /[.!?](?:\s|$)/g;
+  const offenders = registry.commands.filter((c) => {
+    if (!c.teaching) return false;
+    const count = (c.teaching.match(sentenceCountRegex) || []).length;
+    return count > 2 || count < 1;
+  });
+  assert.equal(
+    offenders.length,
+    0,
+    offenders.length +
+      ' teaching strings not 1-2 sentences: ' +
+      offenders.slice(0, 3).map((c) => c.command).join(', ')
+  );
+});