@bongos/core 1.19.811 → 1.19.812

package/modules/hall-ui/public/settings-specialities.js

@@ -0,0 +1,241 @@
+// modules/hall-ui/public/settings-specialities.js — the "Your specialities" panel
+// on /builders/settings (task 1003855; ADR 0296).
+//
+// WHAT A SPECIALITY IS, for anyone reading this file first: a craft says HOW you
+// work (engineer / ideator / artist / ui); a speciality says what you work ON and
+// how you, as a subject-matter expert, want to be engaged inside that craft. The
+// contract you write here is injected into every session where you hold a claim
+// in that craft.
+//
+// Its own file rather than more of settings.js, on the settings-interaction.js /
+// settings-sessions.js precedent and for the same stated reason: settings.js sits
+// against the 1500-line size ratchet. Self-contained — it shares nothing with the
+// rest of the page but `window.OTB` and the generated client, both loaded before it.
+//
+// TRAINING IS TWO-FOLD, and only half of it is visible here. Documents you add are
+// the half you drive; the other half accumulates on its own from learnings captured
+// while you work in the speciality. The counts row says which is which, so "it
+// knows 4 things" is never mistaken for "I typed 4 things".
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const { escapeHtml, $ } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+
+  const state = { rows: [], openId: null, busy: false };
+
+  const el = (id) => document.getElementById(id);
+  const statusLine = (msg) => { const s = el('specialities-status'); if (s) s.textContent = msg || ''; };
+
+  async function call(method, path, body) {
+    const res = await fetch(`${API}${path}`, {
+      method,
+      credentials: 'same-origin',
+      headers: body ? { 'Content-Type': 'application/json', Accept: 'application/json' } : { Accept: 'application/json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); return null; }
+    let data = null;
+    try { data = await res.json(); } catch { /* an empty body is legal on some paths */ }
+    if (!res.ok) {
+      // Surface the field-level reason when the server sent one — a bare
+      // "failed" on a form with five fields is useless.
+      const detail = data && data.details && Array.isArray(data.details.errors)
+        ? data.details.errors.map((e) => `${e.field}: ${e.code}`).join(', ')
+        : (data && data.message) || `HTTP ${res.status}`;
+      throw new Error(detail);
+    }
+    return data;
+  }
+
+  const VISIBILITY_COPY = {
+    private: 'Only you',
+    project: 'Anyone in the owning project',
+    public: 'Anyone on this instance',
+  };
+
+
+  // THE INSTRUCTION THE ADOPTER IS AGREEING TO. A speciality someone else wrote
+  // puts their prose into YOUR sessions, which is the only place in this product
+  // where that happens — so it is shown in full before "Use this", never folded
+  // away behind a summary. Shown for your own too, because seeing what actually
+  // reaches a session is the point either way.
+  function contractHtml(s) {
+    if (!s.contract_md) return '';
+    const theirs = !s.mine;
+    return `
+      <details class="speciality-contract"${theirs ? ' open' : ''}>
+        <summary>${theirs ? 'What this adds to your sessions — written by someone else' : 'What this adds to your sessions'}</summary>
+        <pre class="speciality-contract__body">${escapeHtml(s.contract_md)}</pre>
+        ${theirs ? '<p class="prow__hint">You did not write this. Read it before using the speciality — it reaches every session where you hold work in that craft, and it is passed to Claude as this author\'s stated preferences, not as instructions it must obey.</p>' : ''}
+      </details>`;
+  }
+
+  function cardHtml(s) {
+    const trained = Number(s.documentCount || 0);
+    const learned = Number(s.learningCount || 0);
+    const open = String(state.openId) === String(s.id);
+    return `
+      <li class="prow speciality-card" data-id="${escapeHtml(String(s.id))}">
+        <div class="prow__main">
+          <div class="prow__label">
+            <strong>${escapeHtml(s.name)}</strong>
+            <span class="speciality-craft">${escapeHtml(s.discipline)}</span>
+            ${s.active ? '<span class="speciality-badge speciality-badge--on">active</span>' : ''}
+          </div>
+          <p class="prow__hint">${escapeHtml(s.summary || 'No summary yet.')}</p>
+          ${contractHtml(s)}
+          <p class="prow__hint speciality-counts">
+            Trained on <strong>${trained}</strong> document${trained === 1 ? '' : 's'} you added
+            · learned <strong>${learned}</strong> thing${learned === 1 ? '' : 's'} from your sessions
+            · shared with: ${escapeHtml(VISIBILITY_COPY[s.visibility] || s.visibility || 'only you')}
+          </p>
+        </div>
+        <div class="prow__actions">
+          ${s.mine ? `<button type="button" class="btn btn--quiet" data-act="train" data-id="${escapeHtml(String(s.id))}">${open ? 'Close' : 'Train'}</button>` : ''}
+          ${s.active
+            ? `<button type="button" class="btn btn--quiet" data-act="abandon" data-id="${escapeHtml(String(s.id))}">Stop using</button>`
+            : `<button type="button" class="btn" data-act="adopt" data-id="${escapeHtml(String(s.id))}" ${s.adoptable ? '' : 'disabled'}>Use this</button>`}
+        </div>
+        ${open ? trainHtml(s) : ''}
+      </li>`;
+  }
+
+  function trainHtml(s) {
+    return `
+      <form class="speciality-train" data-id="${escapeHtml(String(s.id))}">
+        <p class="prow__hint">
+          Add something you wrote — notes, a standard, a worked example. It is indexed
+          for recall, not pasted into every session, so length costs you nothing.
+        </p>
+        <label class="speciality-field">
+          <span>Title</span>
+          <input type="text" name="title" maxlength="200" required placeholder="How we price a swap" />
+        </label>
+        <label class="speciality-field">
+          <span>The document</span>
+          <textarea name="body_md" rows="6" required placeholder="Paste or write it here."></textarea>
+        </label>
+        <div class="speciality-actions">
+          <button type="submit" class="btn">Add to what it knows</button>
+        </div>
+      </form>`;
+  }
+
+  function render() {
+    const host = el('specialities-rows');
+    if (!host) return;
+    if (!state.rows.length) {
+      host.innerHTML = `<li class="prow"><div class="prow__main">
+        <p class="prow__hint">No specialities yet. Create one below — it takes a name and a craft, and you can train it afterwards.</p>
+      </div></li>`;
+      return;
+    }
+    host.innerHTML = state.rows.map(cardHtml).join('');
+  }
+
+  async function load() {
+    try {
+      const [cat, mine] = await Promise.all([call('GET', '/specialities'), call('GET', '/me/specialities')]);
+      if (!cat) return;
+      const activeIds = new Set(((mine && mine.adoptions) || []).filter((a) => a.active).map((a) => String(a.id)));
+      state.rows = ((cat && cat.specialities) || []).map((s) => ({ ...s, active: activeIds.has(String(s.id)) }));
+      render();
+      statusLine('');
+    } catch (err) {
+      statusLine(`Could not load specialities — ${err.message}`);
+    }
+  }
+
+  async function act(action, id) {
+    if (state.busy) return;
+    state.busy = true;
+    try {
+      if (action === 'adopt') { await call('POST', `/specialities/${id}/adopt`); toast('Using this speciality.'); }
+      if (action === 'abandon') { await call('POST', `/specialities/${id}/abandon`); toast('Stopped using it.'); }
+      await load();
+    } catch (err) {
+      statusLine(err.message);
+    } finally {
+      state.busy = false;
+    }
+  }
+
+  function wire() {
+    const host = el('specialities-rows');
+    if (host) {
+      host.addEventListener('click', (e) => {
+        const btn = e.target.closest('button[data-act]');
+        if (!btn) return;
+        const { act: action, id } = btn.dataset;
+        if (action === 'train') { state.openId = String(state.openId) === String(id) ? null : id; render(); return; }
+        act(action, id);
+      });
+
+      host.addEventListener('submit', async (e) => {
+        const form = e.target.closest('form.speciality-train');
+        if (!form) return;
+        e.preventDefault();
+        const title = form.elements.title.value.trim();
+        const body = form.elements.body_md.value.trim();
+        // Validate before calling: an empty field should say so inline rather
+        // than round-trip to a 400.
+        if (!title || !body) { statusLine('A document needs both a title and some content.'); return; }
+        try {
+          const out = await call('POST', `/specialities/${form.dataset.id}/documents`, { title, body_md: body });
+          toast(out && out.skipped ? 'It already knew that one.' : 'Added.');
+          state.openId = null;
+          await load();
+        } catch (err) { statusLine(err.message); }
+      });
+    }
+
+    const create = el('speciality-create');
+    if (create) {
+      create.addEventListener('submit', async (e) => {
+        e.preventDefault();
+        const name = create.elements.name.value.trim();
+        const discipline = create.elements.discipline.value;
+        if (!name) { statusLine('Give it a name.'); return; }
+        if (!discipline) { statusLine('Pick which craft it sits under.'); return; }
+        try {
+          await call('POST', '/specialities', {
+            name,
+            discipline,
+            summary: create.elements.summary.value.trim(),
+            contract_md: create.elements.contract_md.value.trim(),
+            visibility: create.elements.visibility.value,
+            sellable: create.elements.sellable.checked,
+          });
+          create.reset();
+          toast('Speciality created.');
+          await load();
+        } catch (err) { statusLine(err.message); }
+      });
+
+      // The server refuses private+sellable (there is nobody it could be sold
+      // to). Mirror that here so the checkbox cannot be left in a state the save
+      // will reject.
+      const vis = create.elements.visibility;
+      const sell = create.elements.sellable;
+      const sync = () => {
+        const isPrivate = vis.value === 'private';
+        sell.disabled = isPrivate;
+        if (isPrivate) sell.checked = false;
+      };
+      vis.addEventListener('change', sync);
+      sync();
+    }
+  }
+
+  function boot() {
+    if (!el('specialities-rows')) return; // panel not on this page
+    wire();
+    load();
+  }
+
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);
+  else boot();
+})();

package/modules/hall-ui/public/settings.css

@@ -161,3 +161,59 @@ select.voices__select { min-width: 140px; }
 /* the box panel is the shell's (.setup__box, box-panel.js); inside a settings
    panel it sits on the glass rather than a second card */
 .settings-groups .setup__box { margin: var(--sp-sm) 0 0; background: var(--glass); border-color: var(--glass-edge); border-radius: var(--radius-sm); }
+
+/* Specialities panel (task 1003855, ADR 0296). A speciality is a named bundle of
+   knowledge and terms under a craft; this styles the list, the train form and the
+   create form. Tokens only — no literal colours, so light/dark follow the page. */
+.speciality-craft {
+  font-size: 0.78rem;
+  text-transform: lowercase;
+  opacity: 0.72;
+  margin-left: 0.4rem;
+}
+.speciality-badge {
+  font-size: 0.7rem;
+  padding: 0.05rem 0.4rem;
+  border-radius: 0.5rem;
+  margin-left: 0.4rem;
+  border: 1px solid currentColor;
+}
+.speciality-counts { opacity: 0.82; }
+.speciality-card { flex-wrap: wrap; }
+.speciality-train,
+.speciality-create {
+  flex-basis: 100%;
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--rule, rgba(128, 128, 128, 0.25));
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+}
+.speciality-create__h { margin: 0; font-size: 0.95rem; }
+.speciality-field { display: flex; flex-direction: column; gap: 0.25rem; }
+.speciality-field > span { font-size: 0.85rem; }
+.speciality-field small { display: block; opacity: 0.7; font-weight: normal; }
+.speciality-field input[type='text'],
+.speciality-field select,
+.speciality-field textarea {
+  width: 100%;
+  box-sizing: border-box;
+}
+/* The checkbox row reads as one sentence, so it runs inline rather than stacked. */
+.speciality-field--check { flex-direction: row; align-items: flex-start; gap: 0.5rem; }
+.speciality-field--check input { margin-top: 0.2rem; }
+.speciality-actions { display: flex; gap: 0.5rem; }
+/* The adopted contract, shown in full before "Use this" — another builder's prose
+   reaching your sessions is the one thing here that must never be folded away. */
+.speciality-contract { flex-basis: 100%; margin-top: 0.5rem; font-size: 0.85rem; }
+.speciality-contract > summary { cursor: pointer; opacity: 0.85; }
+.speciality-contract__body {
+  white-space: pre-wrap;
+  margin: 0.4rem 0 0;
+  padding: 0.5rem 0.65rem;
+  border-left: 2px solid var(--rule, rgba(128, 128, 128, 0.35));
+  border-radius: 0;
+  font-family: inherit;
+  opacity: 0.92;
+}

package/modules/hall-ui/public/settings.html

@@ -269,6 +269,70 @@
               <p class="settings-status" id="interaction-status" role="status" aria-live="polite"></p>
             </section>
 
+            <!-- SPECIALITIES — a named bundle of knowledge + terms UNDER a craft
+                 (task 1003855, ADR 0296). GET/POST /api/bongos/specialities,
+                 POST /specialities/:id/{adopt,abandon,documents}. No rank gate:
+                 a speciality is how an expert's knowledge enters the platform,
+                 and gating that by rank would mean only trusted builders could
+                 be experts. -->
+            <section class="scroll" id="specialities-scroll" aria-labelledby="specialities-h" data-group="preferences" hidden>
+              <h2 id="specialities-h" class="scroll__h">Your specialities</h2>
+              <p class="scroll__lede">
+                A craft says how you work. A speciality says what you work on — and how you,
+                as someone who knows the subject, want to be engaged inside it. Whichever one
+                you are using reaches every session where you hold a claim in that craft.
+                Train it by adding things you have written; it also picks things up on its own
+                as you work.
+              </p>
+              <ul class="prows" id="specialities-rows"></ul>
+
+              <form id="speciality-create" class="speciality-create">
+                <h3 class="speciality-create__h">Create one</h3>
+                <label class="speciality-field">
+                  <span>Name</span>
+                  <input type="text" name="name" maxlength="80" required placeholder="Economics" />
+                </label>
+                <label class="speciality-field">
+                  <span>Craft it sits under</span>
+                  <select name="discipline" required>
+                    <option value="">Pick one…</option>
+                    <option value="engineer">Engineer</option>
+                    <option value="ideator">Ideator</option>
+                    <option value="artist">Artist</option>
+                    <option value="ui">UI design</option>
+                  </select>
+                </label>
+                <label class="speciality-field">
+                  <span>Summary <small>(optional)</small></span>
+                  <input type="text" name="summary" maxlength="500" placeholder="Markets, incentives, and how to price them." />
+                </label>
+                <label class="speciality-field">
+                  <span>How Claude should engage you in it <small>(optional)</small></span>
+                  <textarea name="contract_md" rows="4" maxlength="4000" placeholder="Argue from mechanism, not vibes. Always name the assumption a number rests on."></textarea>
+                </label>
+                <label class="speciality-field">
+                  <span>Who can use it</span>
+                  <select name="visibility">
+                    <option value="private">Only me</option>
+                    <option value="project">Anyone in the owning project</option>
+                    <option value="public">Anyone on this instance</option>
+                  </select>
+                </label>
+                <label class="speciality-field speciality-field--check">
+                  <input type="checkbox" name="sellable" />
+                  <span>
+                    May be offered for sale later
+                    <small>Records your decision only — there is no marketplace yet, and nothing is listed anywhere.</small>
+                  </span>
+                </label>
+                <div class="speciality-actions">
+                  <button type="submit" class="btn">Create speciality</button>
+                </div>
+              </form>
+
+              <p class="settings-status" id="specialities-status" role="status" aria-live="polite"></p>
+            </section>
+
             <!-- WANDERING — how readily the agent opens off-task threads (task 1268).
                  GET/PATCH /api/bongos/me/wandering. Rank sets the default + ceiling; the
                  server clamps, so options above the rank cap render disabled. -->
@@ -398,6 +462,7 @@
      the same precedent and for the same reason — settings.js is against the
      1500-line ratchet, and this panel shares nothing with the rest of the page. -->
 <script src="/builders/settings-interaction.js?v=2026-09-15-interaction"></script>
+<script src="/builders/settings-specialities.js?v=2026-09-17-specialities"></script>
 <!-- task 1002518: the card-richness ladder. Own file on the same precedent —
      the panel grew from one switch to a rung picker with a derived default, and
      settings.js is against the 1500-line ratchet. -->

package/modules/lifecycle/db-claim-reads.js

@@ -21,7 +21,11 @@ async function getActiveClaimsForBuilder(builderId) {
     `SELECT c.id AS claim_id, c.task_id, c.worktree_name, c.claimed_at,
             c.head_sha, c.reserved_migration_number,
             c.release_requested_by, c.release_requested_at, c.release_requested_note,
-            t.title, t.touches, t.priority, t.credits_reward, t.version_id, t.module_key
+            t.title, t.touches, t.priority, t.credits_reward, t.version_id, t.module_key,
+            -- task 1003855: the craft of the claimed work. A speciality contract is
+            -- craft-scoped, so the Conductor needs to know which craft is in play
+            -- before it can pick the right one to inject.
+            t.discipline
        FROM claims c JOIN tasks t ON t.id = c.task_id
       WHERE c.builder_id = $1 AND c.released_at IS NULL
       ORDER BY c.claimed_at`,

package/modules/memory/learnings.js

@@ -13,7 +13,7 @@
 
 // Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): pool via the doorway.
 const crypto = require('crypto');
-const { pool } = require('../../src/module-api');
+const { pool, resolveOptional } = require('../../src/module-api');
 // ADR 0095 C4: <private>…</private>-fenced content is stripped at ingest so it
 // never lands in the learnings store (nor the recall index that reads it).
 const { stripPrivate } = require('./search-chunker');
@@ -111,6 +111,20 @@ async function createLearning({
     }
   }
 
+  // task 1003855: once the row lands, offer it to the builder's active speciality
+  // for that task's craft (training half (b)). Through the PORT, so this module
+  // never requires the specialities module and a disabled one simply means no
+  // link. Best-effort by construction: a capture must never fail over it.
+  const offerToSpeciality = async (row) => {
+    if (!row || !row.id) return;
+    try {
+      const sp = typeof resolveOptional === 'function' ? resolveOptional('specialities') : null;
+      if (sp && typeof sp.recordLearningForTask === 'function') {
+        await sp.recordLearningForTask({ learningId: row.id, builderId: row.captured_by, taskId: row.task_id });
+      }
+    } catch { /* never fail a capture over speciality bookkeeping */ }
+  };
+
   const { rows } = await pool.query(
     `INSERT INTO learnings (title, body_md, tags, related_files, captured_by,
                             source, source_ref, task_id)
@@ -131,7 +145,12 @@ async function createLearning({
       taskId,
     ]
   );
-  return rows[0] ?? null;
+  const created = rows[0] ?? null;
+  // Awaited, not fire-and-forget: an unawaited promise here would let the process
+  // exit mid-write in a CLI capture, and the helper already swallows its own
+  // failures, so awaiting costs one round trip and never fails the capture.
+  await offerToSpeciality(created);
+  return created;
 }
 
 // -------------------------------------------------------------------------

package/modules/provisioning/starter-bundles.js

@@ -59,6 +59,7 @@ const ALWAYS_ON_CORE = Object.freeze([
   'public-landing',
   'security',
   'sessions',
+  'specialities',
   'status-ui',
   'ui-design',
 ]);

package/modules/specialities/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._